Merge pull request #642 from TobyAndToby/ts/docs-v4

Update the docs to include major version 4

Author: tobysmith568

website/docs/v3-to-v4.mdx

@@ -0,0 +1,12 @@
+---
+title: Migrate from V3 to V4
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+## Breaking Changes
+
+### Dropped Support for Node.js 18
+
+Generate-license-file now requires Node.js 20 or later.

website/sidebars.js

@@ -47,6 +47,7 @@ const sidebars = {
       label: "Migration Guides",
       collapsed: false,
       items: [
+        { type: "doc", id: "v3-to-v4", label: "V3 to V4" },
         { type: "doc", id: "v2-to-v3", label: "V2 to V3" },
         { type: "doc", id: "v1-to-v2", label: "V1 to V2" },
       ],

website/versioned_docs/version-1.3.0/library/index.mdx

@@ -12,9 +12,9 @@ a detailed spec on the method signatures and types, please read the [API spec](.
 
 ## Generate and write a license file to disk
 
-To programatically run the generate license file program you can use the `generateLicenseFile` method.
+To programmatically run the generate license file program you can use the `generateLicenseFile` method.
 Like the CLI, this method requires a path to a package.json, an output file path, and can be given
-an optional line ending paramter. It will produce the same result as running the command via the CLI.
+an optional line ending parameter. It will produce the same result as running the command via the CLI.
 
 <Tabs groupId="library-page">
   <TabItem value="ts" label="TypeScript">

website/versioned_docs/version-2.0.0/library/index.mdx

@@ -12,9 +12,9 @@ a detailed spec on the method signatures and types, please read the [API spec](.
 
 ## Generate and write a license file to disk
 
-To programatically run the generate license file program you can use the `generateLicenseFile` method.
+To programmatically run the generate license file program you can use the `generateLicenseFile` method.
 Like the CLI, this method requires a path to a package.json, an output file path, and can be given
-an optional line ending paramter. It will produce the same result as running the command via the CLI.
+an optional line ending parameter. It will produce the same result as running the command via the CLI.
 
 <Tabs groupId="library-page">
   <TabItem value="ts" label="TypeScript">

website/versioned_docs/version-3.0.0/cli/config-file.mdx

@@ -1,7 +1,6 @@
 ---
 title: Config File
 description: Overview and example usages of the generate license file CLI config file
-toc_max_heading_level: 4
 ---
 
 import Tabs from "@theme/Tabs";
@@ -82,11 +81,9 @@ module.exports = {
 
 :::
 
-### Advanced Options
+The more advanced features that a config file can contain allow you to edit the contents of the generated output file.
 
-The config file also allows for more complex configurations that are not available as CLI flags.
-
-#### Append
+### Append
 
 The append option allows you to append files to the end of the generated output file. This is useful if your project
 contains other types of licensed material other than node_modules dependencies that you want to include like fonts or images.
@@ -122,7 +119,7 @@ module.exports = {
 </TabItem>
 </Tabs>
 
-#### Replace
+### Replace
 
 The replace option allows you to replace the license content for a specific dependency. This is useful in situations like:
 
@@ -134,7 +131,7 @@ Packages can be specified using the format `package@version` or `package`, where
 
 :::info
 
-While it might be more convenient to use the package name without the version, it is recommended to use the version where possible to guarentee you always know exactly which package you are replacing the license for.
+While it might be more convenient to use the package name without the version, it is recommended to use the version where possible to guarantee you always know exactly which package you are replacing the license for.
 
 :::
 
@@ -208,19 +205,17 @@ module.exports = {
 </div>
 </details>
 
-#### Exclude
+### Exclude
 
-The exclude option allows you to exclude dependencies from the generated output file. This is useful for cases like when a dependency
+The exclude option allows you to exclude a dependency from the generated output file. This is useful if a dependency
 accidentally lists one of it's own dev-dependencies as a normal dependency and you want to exclude that dev-dependency.
 
-Values can be specified using the format `package@version` or `package`, where the latter will match all versions of a given package. You can also use regular expressions by wrapping the expression in forward slashes `/.../` and adding any relevant flags after the closing slash.
-
 <Tabs groupId="file-formats">
 <TabItem value="json" label="JSON" default>
 
 ```json
 {
-  "exclude": ["lodash", "lodash@1.2.0", "/lodash-.*/i"]
+  "exclude": ["[email protected].3"]
 }
 ```
 
@@ -230,9 +225,7 @@ Values can be specified using the format `package@version` or `package`, where t
 
 ```yaml
 exclude:
-  - lodash
-  - [email protected]
-  - /lodash-.*/i
+  - [email protected]
 ```
 
 </TabItem>
@@ -241,7 +234,7 @@ exclude:
 
 ```js
 module.exports = {
-  exclude: ["lodash", "lodash@1.2.0", "/lodash-.*/i"],
+  exclude: ["[email protected].3"],
 };
 ```
 

website/versioned_docs/version-3.0.0/library/index.mdx

@@ -12,9 +12,9 @@ a detailed spec on the method signatures and types, please read the [API spec](.
 
 ## Generate and write a license file to disk
 
-To programatically run the generate license file program you can use the `generateLicenseFile` method.
+To programmatically run the generate license file program you can use the `generateLicenseFile` method.
 Like the CLI, this method requires a path to a package.json, an output file path, and can be given
-an optional line ending paramter. It will produce the same result as running the command via the CLI.
+an optional line ending parameter. It will produce the same result as running the command via the CLI.
 
 <Tabs groupId="library-page">
   <TabItem value="ts" label="TypeScript">

website/versioned_docs/version-4.0.0/cli/config-file.mdx

@@ -0,0 +1,258 @@
+---
+title: Config File
+description: Overview and example usages of the generate license file CLI config file
+toc_max_heading_level: 4
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+The generate-license-file CLI can be configured using a config file so that you don't need to re-enter the same
+config options every time. The config file also allows you to specify additional more complex options that are not
+available as CLI flags.
+
+## File Formats
+
+Config files can be called either `.glf` or `.generatelicensefile` and can be customised using the following options:
+
+- File name can optionally end with `rc`
+- Can be in a `./.config` directory (no longer needs the `.` prefix on the file name)
+- Have the following file extensions: `.json`, `jsonc`, `.json5`, `.yaml`, `.yml`, `.js`, `.cjs`
+
+E.g. `.glf.json`, `.glfrc.yml`, `.generatelicensefile.jsonc`, `.config/glf.js`, and more.
+
+## Config Options
+
+The file can contain all of the options that are [available as CLI flags](./).
+
+<Tabs groupId="file-formats">
+<TabItem value="json" label="JSON" default>
+
+```json
+{
+  "inputs": ["./package.json"],
+  "output": "./THIRD-PARTY-LICENSES.txt",
+  "overwrite": true,
+  "eol": "lf",
+  "ci": true,
+  "no-spinner": true
+}
+```
+
+</TabItem>
+
+<TabItem value="yaml" label="YAML">
+
+```yaml
+inputs:
+  - ./package.json
+output: ./THIRD-PARTY-LICENSES.txt
+overwrite: true
+eol: lf
+ci: true
+no-spinner: true
+```
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```js
+module.exports = {
+  inputs: ["./package.json"],
+  output: "./THIRD-PARTY-LICENSES.txt",
+  overwrite: true,
+  eol: "lf",
+  ci: true,
+  noSpinner: true,
+};
+```
+
+</TabItem>
+</Tabs>
+
+:::tip
+JavaScript allows for more dynamic usages
+
+```js
+module.exports = {
+  ci: process.env.CI === "true",
+};
+```
+
+:::
+
+### Advanced Options
+
+The config file also allows for more complex configurations that are not available as CLI flags.
+
+#### Append
+
+The append option allows you to append files to the end of the generated output file. This is useful if your project
+contains other types of licensed material other than node_modules dependencies that you want to include like fonts or images.
+
+<Tabs groupId="file-formats">
+<TabItem value="json" label="JSON" default>
+
+```json
+{
+  "append": ["./extra-licenses.txt"]
+}
+```
+
+</TabItem>
+
+<TabItem value="yaml" label="YAML">
+
+```yaml
+append:
+  - ./extra-licenses.txt
+```
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```js
+module.exports = {
+  append: ["./extra-licenses.txt"],
+};
+```
+
+</TabItem>
+</Tabs>
+
+#### Replace
+
+The replace option allows you to replace the license content for a specific dependency. This is useful in situations like:
+
+- A dependency does not have its license file included in the published package
+- The license file is not in a standard format
+- The published package contains multiple license files and you want to pick a specific one
+
+Packages can be specified using the format `package@version` or `package`, where the latter will match all versions of a given package. If both are specified, then the configuration with a matching version will take precedence.
+
+:::info
+
+While it might be more convenient to use the package name without the version, it is recommended to use the version where possible to guarantee you always know exactly which package you are replacing the license for.
+
+:::
+
+The replacement value can be:
+
+- A relative or absolute file path to a location on disk
+- A URL to a remote file on the internet
+
+:::tip
+
+An advantage to using a file path over a URL is that the generated output will always be the same for any given commit.
+
+:::
+
+<Tabs groupId="file-formats">
+<TabItem value="json" label="JSON" default>
+
+```json
+{
+  "replace": {
+    "[email protected]": "./licenses/lodash.txt",
+    "[email protected]": "./node_modules/react/LICENSE",
+    "axios": "./node_modules/axios/LICENSE",
+    "express": "https://spdx.org/licenses/MIT.txt"
+  }
+}
+```
+
+</TabItem>
+
+<TabItem value="yaml" label="YAML">
+
+```yaml
+replace:
+  [email protected]: ./licenses/lodash.txt
+  [email protected]: ./node_modules/react/LICENSE
+  axios: ./node_modules/axios/LICENSE
+  express: https://spdx.org/licenses/MIT.txt
+```
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```js
+module.exports = {
+  replace: {
+    "[email protected]": "./licenses/lodash.txt",
+    "[email protected]": "./node_modules/react/LICENSE",
+    axios: "./node_modules/axios/LICENSE",
+    express: "https://spdx.org/licenses/MIT.txt",
+  },
+};
+```
+
+</TabItem>
+</Tabs>
+
+<details>
+<summary>When using pnpm, the way to reference a file in a node_module can look a little different</summary>
+<div>
+
+```json
+{
+  "replace": {
+    "[email protected]": "node_modules/.pnpm/[email protected]/node_modules/react/LICENSE"
+  }
+}
+```
+
+</div>
+</details>
+
+#### Exclude
+
+The exclude option allows you to exclude dependencies from the generated output file. This is useful for cases like when a dependency
+accidentally lists one of it's own dev-dependencies as a normal dependency and you want to exclude that dev-dependency.
+
+Values can be specified using the format `package@version` or `package`, where the latter will match all versions of a given package. You can also use regular expressions by wrapping the expression in forward slashes `/.../` and adding any relevant flags after the closing slash.
+
+<Tabs groupId="file-formats">
+<TabItem value="json" label="JSON" default>
+
+```json
+{
+  "exclude": ["lodash", "[email protected]", "/lodash-.*/i"]
+}
+```
+
+</TabItem>
+
+<TabItem value="yaml" label="YAML">
+
+```yaml
+exclude:
+  - lodash
+  - [email protected]
+  - /lodash-.*/i
+```
+
+</TabItem>
+
+<TabItem value="js" label="JavaScript">
+
+```js
+module.exports = {
+  exclude: ["lodash", "[email protected]", "/lodash-.*/i"],
+};
+```
+
+</TabItem>
+</Tabs>
+
+## File Location
+
+If you want to keep your config file in a different location to the current working directory (or a `./.config` directory)
+then you can specify the location of the config file using the `--config` CLI flag.
+
+```bash
+generate-license-file --config ./path/to/config.json
+```