@rushstack/rig-package - npm Package Compare versions

Comparing version 0.3.8 to 0.3.9

package.json

 {
   "name": "@rushstack/rig-package",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "A system for sharing tool configurations between projects without duplicating config files.",
@@ -18,3 +18,3 @@ "main": "lib/index.js",
   "devDependencies": {
-    "@rushstack/eslint-config": "2.5.2",
+    "@rushstack/eslint-config": "2.5.3",
     "@rushstack/heft-node-rig": "1.7.1",
@@ -33,3 +33,3 @@ "@rushstack/heft": "0.44.2",
   },
-  "readme": "# @rushstack/rig-package\n\nThe **config/rig.json** file is a system that Node.js build tools can adopt, in order to eliminate\nduplication of config files when many projects share a common configuration. This is particularly valuable\nin a setup where hundreds of projects may be built using a small set of reusable recipes.\n\n## Motivation\n\nFor a concrete example, consider the [API Extractor](https://api-extractor.com/) tool which reads its\nconfiguration from **\\<projectFolder\\>/config/api-extractor.json**. Suppose that we have three separate projects\nthat all share the exact same configuration:\n\n```\nproject1/package.json\nproject1/config/api-extractor.json\nproject1/config/other-tool2.json\nproject1/config/other-tool3.json\nproject1/src/index.ts\n\nproject2/package.json\nproject2/config/api-extractor.json\nproject2/config/other-tool2.json\nproject2/config/other-tool3.json\nproject2/src/index.ts\n\nproject3/package.json\nproject3/config/api-extractor.json\nproject3/config/other-tool2.json\nproject3/config/other-tool3.json\nproject3/src/index.ts\n```\n\nIt seems wasteful to copy and paste the **api-extractor.json** file with all those settings. If we later need\nto tune the configuration, we'd have to find and update each file. For a large organization, there could be\nhundreds of such projects.\n\nThe `\"extends\"` setting provides a basic way to centralize the configuration in a \"rig package\". For this example,\nwe'll call our NPM package **example-rig**:\n\n```\nexample-rig/package.json\nexample-rig/profile/node-library/config/api-extractor.json\nexample-rig/profile/web-library/config/api-extractor.json\n\nproject1/package.json\nproject1/config/api-extractor.json\nproject1/config/other-tool2.json\nproject1/config/other-tool3.json\nproject1/src/index.ts\n\nproject2/package.json\nproject2/config/api-extractor.json\nproject2/config/other-tool2.json\nproject2/config/other-tool3.json\nproject2/src/index.ts\n\nproject3/package.json\nproject3/config/api-extractor.json\nproject3/config/other-tool2.json\nproject3/config/other-tool3.json\nproject3/src/index.ts\n```\n\nTo make things interesting, above we've introduced two \"profiles\":\n\n- `node-library` is for libraries that target the Node.js runtime\n- `web-library` is for libraries that target a web browser\n\n> **NOTE:** The `node-library` and `web-library` names are hypothetical examples. The names and purposes of\n> rig profiles are user-defined. If you only need one profile, then call it `default`.\n\nIf **project1** and **project2** are Node.js libraries, then their **api-extractor.json** now reduces to this:\n\n**project1/config/api-extractor.json**\n\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json\",\n  \"extends\": \"example-rig/profile/node-library/config/api-extractor.json\"\n}\n```\n\nWhereas if **project3** is a web browser library, then it might look like this:\n\n**project3/config/api-extractor.json**\n\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json\",\n  \"extends\": \"example-rig/profile/web-library/config/api-extractor.json\"\n}\n```\n\nUsing `\"extends\"` definitely made the config file shorter! But imagine that we have a large monorepo with 100 projects.\nAnd each project has 5 config files like **api-extactor.json**. We still have to copy+paste 100 x 5 = 500 config files\nacross all our project folders.\n\nCan we do better?\n\n## rig.json eliminates files entirely\n\nThe idea is to replace `config/api-extractor.json` and `config/other-tool2.json` (and any other such files)\nwith a single file `config/rig.json` that delegates everything to the rig package:\n\n**project3/config/rig.json**\n\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json\",\n\n  /**\n   * (Required) The name of the rig package to inherit from.\n   * It should be an NPM package name with the \"-rig\" suffix.\n   */\n  \"rigPackageName\": \"example-rig\",\n\n  /**\n   * (Optional) Selects a config profile from the rig package.  The name must consist of\n   * lowercase alphanumeric words separated by hyphens, for example \"sample-profile\".\n   * If omitted, then the \"default\" profile will be used.\"\n   */\n  \"rigProfile\": \"web-library\"\n}\n```\n\nUsing **rig.json** eliminates the `\"extends\"` stub files entirely. A tool that implements the **rig.json** system\nwould probe for its config file (`<targetFile>.json`) using the following procedure:\n\n1. First check for `config/<targetFile>.json` in the project folder; if found, use that file. OTHERWISE...\n2. Check for `config/rig.json`; if found, then this project is using a rig package. Read the `<rigPackageName>`\n   and `<rigProfile>` settings from that file.\n3. Use Node.js module resolution to find the `<rigPackageName>` package folder (let's call that `<rigPackageFolder>`)\n4. Check for `<rigPackageFolder>/profile/<rigProfile>/<targetFile>.json`; if found, use that file. OTHERWISE...\n5. If the `<targetFile>.json` cannot be found in either of these places, the behavior is left to the tool.\n   For example, it could report an error, or proceed using defaults.\n\nIn cases where we need a project-specific customization, the `\"extends\"` field is still supported. For example,\n**project1** can still add a local override like this:\n\n**project1/config/api-extractor.json**\n\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json\",\n  \"extends\": \"example-rig/profile/node-library/config/api-extractor.json\",\n\n  // Local override:\n  \"mainEntryPointFilePath\": \"<projectFolder>/lib/custom.d.ts\",\n}\n```\n\nThe result is a much shorter inventory of files:\n\n```\nexample-rig/package.json\n\nexample-rig/profile/node-library/config/api-extractor.json\nexample-rig/profile/node-library/config/other-tool2.json\nexample-rig/profile/node-library/config/other-tool3.json\n\nexample-rig/profile/web-library/config/api-extractor.json\nexample-rig/profile/web-library/config/other-tool2.json\nexample-rig/profile/web-library/config/other-tool3.json\n\nproject1/package.json\nproject1/config/rig.json\nproject1/config/api-extractor.json  <-- local override shown above\nproject1/src/index.ts\n\nproject2/package.json\nproject2/config/rig.json\nproject2/src/index.ts\n\nproject3/package.json\nproject3/config/rig.json\nproject3/src/index.ts\n```\n\n## The `@rushstack/rig-package` API\n\nThe `@rushstack/rig-package` library provides an API for loading the **rig.json** file and performing lookups.\nIt is a lightweight NPM package, intended to be easy for tool projects to accept as a dependency. The package\nalso includes the JSON schema file **rig.schema.json**.\n\nExample usage of the API:\n\n```ts\nimport { RigConfig } from '@rushstack/rig-package';\n\n// Probe for the rig.json file and load it if found\nconst rigConfig: RigConfig = RigConfig.loadForProjectFolder({\n  // Specify a  project folder (i.e. where its package.json file is located)\n  projectFolderPath: testProjectFolder\n});\n\nif (rigConfig.rigFound) {\n  // We found a config/rig.json file\n  //\n  // Prints \"/path/to/project3/config/rig.json\"\n  console.log('Found rig.json: ' + rigConfig.filePath);\n\n  // Prints \"example-rig\"\n  console.log('The rig package is: ' + rigConfig.rigPackageName);\n\n  // Resolve the rig package\n  //\n  // Prints \"/path/to/project3/node_modules/example-rig/profile/web-library\"\n  console.log('Profile folder: ' + rigConfig.getResolvedProfileFolder());\n\n  // Look up a config file.  These file paths will be tested:\n  //\n  //   /path/to/project3/folder/file.json\n  //   /path/to/project3/node_modules/example-rig/profile/web-library/folder/file.json\n  //\n  // The result will be the first path that exists, or undefined if the config file was not found.\n  console.log('Resolved config file: ' + rigConfig.tryResolveConfigFilePath('folder/file.json'));\n}\n```\n\nNote that there are also async variants of the functions that access the filesystem.\n\n## Links\n\n- [CHANGELOG.md](\n  https://github.com/microsoft/rushstack/blob/master/libraries/rig-package/CHANGELOG.md) - Find\n  out what's new in the latest version\n- [API Reference](https://rushstack.io/pages/api/rig-package/)\n\n`@rushstack/rig-package` is part of the [Rush Stack](https://rushstack.io/) family of projects.\n"
+  "readme": "# @rushstack/rig-package\n\nThe **config/rig.json** file is a system that Node.js build tools can adopt, in order to eliminate\nduplication of config files when many projects share a common configuration. This is particularly valuable\nin a setup where hundreds of projects may be built using a small set of reusable recipes.\n\n## Motivation\n\nFor a concrete example, consider the [API Extractor](https://api-extractor.com/) tool which reads its\nconfiguration from **\\<projectFolder\\>/config/api-extractor.json**. Suppose that we have three separate projects\nthat all share the exact same configuration:\n\n```\nproject1/package.json\nproject1/config/api-extractor.json\nproject1/config/other-tool2.json\nproject1/config/other-tool3.json\nproject1/src/index.ts\n\nproject2/package.json\nproject2/config/api-extractor.json\nproject2/config/other-tool2.json\nproject2/config/other-tool3.json\nproject2/src/index.ts\n\nproject3/package.json\nproject3/config/api-extractor.json\nproject3/config/other-tool2.json\nproject3/config/other-tool3.json\nproject3/src/index.ts\n```\n\nIt seems wasteful to copy and paste the **api-extractor.json** file with all those settings. If we later need\nto tune the configuration, we'd have to find and update each file. For a large organization, there could be\nhundreds of such projects.\n\nThe `\"extends\"` setting provides a basic way to centralize the configuration in a \"rig package\". For this example,\nwe'll call our NPM package **example-rig**:\n\n```\nexample-rig/package.json\nexample-rig/profile/node-library/config/api-extractor.json\nexample-rig/profile/web-library/config/api-extractor.json\n\nproject1/package.json\nproject1/config/api-extractor.json\nproject1/config/other-tool2.json\nproject1/config/other-tool3.json\nproject1/src/index.ts\n\nproject2/package.json\nproject2/config/api-extractor.json\nproject2/config/other-tool2.json\nproject2/config/other-tool3.json\nproject2/src/index.ts\n\nproject3/package.json\nproject3/config/api-extractor.json\nproject3/config/other-tool2.json\nproject3/config/other-tool3.json\nproject3/src/index.ts\n```\n\nTo make things interesting, above we've introduced two \"profiles\":\n\n- `node-library` is for libraries that target the Node.js runtime\n- `web-library` is for libraries that target a web browser\n\n> **NOTE:** The `node-library` and `web-library` names are hypothetical examples. The names and purposes of\n> rig profiles are user-defined. If you only need one profile, then call it `default`.\n\nIf **project1** and **project2** are Node.js libraries, then their **api-extractor.json** now reduces to this:\n\n**project1/config/api-extractor.json**\n\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json\",\n  \"extends\": \"example-rig/profile/node-library/config/api-extractor.json\"\n}\n```\n\nWhereas if **project3** is a web browser library, then it might look like this:\n\n**project3/config/api-extractor.json**\n\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json\",\n  \"extends\": \"example-rig/profile/web-library/config/api-extractor.json\"\n}\n```\n\nUsing `\"extends\"` definitely made the config file shorter! But imagine that we have a large monorepo with 100 projects.\nAnd each project has 5 config files like **api-extactor.json**. We still have to copy+paste 100 x 5 = 500 config files\nacross all our project folders.\n\nCan we do better?\n\n## rig.json eliminates files entirely\n\nThe idea is to replace `config/api-extractor.json` and `config/other-tool2.json` (and any other such files)\nwith a single file `config/rig.json` that delegates everything to the rig package:\n\n**project3/config/rig.json**\n\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json\",\n\n  /**\n   * (Required) The name of the rig package to inherit from.\n   * It should be an NPM package name with the \"-rig\" suffix.\n   */\n  \"rigPackageName\": \"example-rig\",\n\n  /**\n   * (Optional) Selects a config profile from the rig package.  The name must consist of\n   * lowercase alphanumeric words separated by hyphens, for example \"sample-profile\".\n   * If omitted, then the \"default\" profile will be used.\"\n   */\n  \"rigProfile\": \"web-library\"\n}\n```\n\nUsing **rig.json** eliminates the `\"extends\"` stub files entirely. A tool that implements the **rig.json** system\nwould probe for its config file (`<targetFile>.json`) using the following procedure:\n\n1. First check for `config/<targetFile>.json` in the project folder; if found, use that file. OTHERWISE...\n2. Check for `config/rig.json`; if found, then this project is using a rig package. Read the `<rigPackageName>`\n   and `<rigProfile>` settings from that file.\n3. Use Node.js module resolution to find the `<rigPackageName>` package folder (let's call that `<rigPackageFolder>`)\n4. Check for `<rigPackageFolder>/profile/<rigProfile>/<targetFile>.json`; if found, use that file. OTHERWISE...\n5. If the `<targetFile>.json` cannot be found in either of these places, the behavior is left to the tool.\n   For example, it could report an error, or proceed using defaults.\n\nIn cases where we need a project-specific customization, the `\"extends\"` field is still supported. For example,\n**project1** can still add a local override like this:\n\n**project1/config/api-extractor.json**\n\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json\",\n  \"extends\": \"example-rig/profile/node-library/config/api-extractor.json\",\n\n  // Local override:\n  \"mainEntryPointFilePath\": \"<projectFolder>/lib/custom.d.ts\",\n}\n```\n\nThe result is a much shorter inventory of files:\n\n```\nexample-rig/package.json\n\nexample-rig/profile/node-library/config/api-extractor.json\nexample-rig/profile/node-library/config/other-tool2.json\nexample-rig/profile/node-library/config/other-tool3.json\n\nexample-rig/profile/web-library/config/api-extractor.json\nexample-rig/profile/web-library/config/other-tool2.json\nexample-rig/profile/web-library/config/other-tool3.json\n\nproject1/package.json\nproject1/config/rig.json\nproject1/config/api-extractor.json  <-- local override shown above\nproject1/src/index.ts\n\nproject2/package.json\nproject2/config/rig.json\nproject2/src/index.ts\n\nproject3/package.json\nproject3/config/rig.json\nproject3/src/index.ts\n```\n\n## The `@rushstack/rig-package` API\n\nThe `@rushstack/rig-package` library provides an API for loading the **rig.json** file and performing lookups.\nIt is a lightweight NPM package, intended to be easy for tool projects to accept as a dependency. The package\nalso includes the JSON schema file **rig.schema.json**.\n\nExample usage of the API:\n\n```ts\nimport { RigConfig } from '@rushstack/rig-package';\n\n// Probe for the rig.json file and load it if found\nconst rigConfig: RigConfig = RigConfig.loadForProjectFolder({\n  // Specify a  project folder (i.e. where its package.json file is located)\n  projectFolderPath: testProjectFolder\n});\n\nif (rigConfig.rigFound) {\n  // We found a config/rig.json file\n  //\n  // Prints \"/path/to/project3/config/rig.json\"\n  console.log('Found rig.json: ' + rigConfig.filePath);\n\n  // Prints \"example-rig\"\n  console.log('The rig package is: ' + rigConfig.rigPackageName);\n\n  // Resolve the rig package\n  //\n  // Prints \"/path/to/project3/node_modules/example-rig/profile/web-library\"\n  console.log('Profile folder: ' + rigConfig.getResolvedProfileFolder());\n\n  // Look up a config file.  These file paths will be tested:\n  //\n  //   /path/to/project3/folder/file.json\n  //   /path/to/project3/node_modules/example-rig/profile/web-library/folder/file.json\n  //\n  // The result will be the first path that exists, or undefined if the config file was not found.\n  console.log('Resolved config file: ' + rigConfig.tryResolveConfigFilePath('folder/file.json'));\n}\n```\n\nNote that there are also async variants of the functions that access the filesystem.\n\n## Links\n\n- [CHANGELOG.md](\n  https://github.com/microsoft/rushstack/blob/main/libraries/rig-package/CHANGELOG.md) - Find\n  out what's new in the latest version\n- [API Reference](https://rushstack.io/pages/api/rig-package/)\n\n`@rushstack/rig-package` is part of the [Rush Stack](https://rushstack.io/) family of projects.\n"
 }

README.md

@@ -225,3 +225,3 @@ # @rushstack/rig-package
 - [CHANGELOG.md](
-  https://github.com/microsoft/rushstack/blob/master/libraries/rig-package/CHANGELOG.md) - Find
+  https://github.com/microsoft/rushstack/blob/main/libraries/rig-package/CHANGELOG.md) - Find
   out what's new in the latest version
@@ -228,0 +228,0 @@ - [API Reference](https://rushstack.io/pages/api/rig-package/)

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Worsened metrics

Total package byte prevSize

82091

No dependency changes