@rushstack/rig-package - npm Package Compare versions

Comparing version 0.3.7 to 0.3.8

dist/tsdoc-metadata.json

@@ -8,5 +8,5 @@ // This file is read by tools that parse documentation comments conforming to the TSDoc standard.
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.19.2"
+      "packageVersion": "7.19.4"
     }
   ]
 }

lib/schemas/rig.schema.json

@@ -0,0 +0,0 @@ {

package.json

 {
-	"name": "@rushstack/rig-package",
-	"version": "0.3.7",
-	"description": "A system for sharing tool configurations between projects without duplicating config files.",
-	"main": "lib/index.js",
-	"typings": "dist/rig-package.d.ts",
-	"license": "MIT",
-	"repository": {
-		"url": "https://github.com/microsoft/rushstack.git",
-		"type": "git",
-		"directory": "libraries/rig-package"
-	},
-	"dependencies": {
-		"resolve": "~1.17.0",
-		"strip-json-comments": "~3.1.1"
-	},
-	"devDependencies": {
-		"@rushstack/eslint-config": "2.5.1",
-		"@rushstack/heft-node-rig": "1.4.3",
-		"@rushstack/heft": "0.43.2",
-		"@types/heft-jest": "1.0.1",
-		"@types/node": "12.20.24",
-		"@types/resolve": "1.17.1",
-		"ajv": "~6.12.5",
-		"resolve": "~1.17.0"
-	},
-	"scripts": {
-		"build": "heft test --clean"
-	}
-}
+  "name": "@rushstack/rig-package",
+  "version": "0.3.8",
+  "description": "A system for sharing tool configurations between projects without duplicating config files.",
+  "main": "lib/index.js",
+  "typings": "dist/rig-package.d.ts",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/microsoft/rushstack.git",
+    "type": "git",
+    "directory": "libraries/rig-package"
+  },
+  "dependencies": {
+    "resolve": "~1.17.0",
+    "strip-json-comments": "~3.1.1"
+  },
+  "devDependencies": {
+    "@rushstack/eslint-config": "2.5.2",
+    "@rushstack/heft-node-rig": "1.7.1",
+    "@rushstack/heft": "0.44.2",
+    "@types/heft-jest": "1.0.1",
+    "@types/node": "12.20.24",
+    "@types/resolve": "1.17.1",
+    "ajv": "~6.12.5",
+    "resolve": "~1.17.0"
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "_phase:build": "heft build --clean",
+    "_phase:test": "heft test --no-build"
+  },
+  "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.md

@@ -0,0 +0,0 @@ # @rushstack/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

82095

decreased by-4.17%

Number of package files

18

decreased by-10%

Lines of code

823

decreased by-27.87%

No dependency changes