diff --git a/packages/zpm-config/schema.json b/packages/zpm-config/schema.json index 64992a3f..e669437e 100644 --- a/packages/zpm-config/schema.json +++ b/packages/zpm-config/schema.json @@ -98,7 +98,7 @@ }, "enableImmutableInstalls": { "type": "boolean", - "description": "Whether to report errors when a package would be added or removed from the cache", + "description": "Whether to report errors when an install would modify the lockfile or files matched by immutablePatterns", "default": false }, "immutablePatterns": { @@ -339,7 +339,7 @@ }, "npmAuthIdent": { "type": ["string", "null"], - "description": "The username to use for authentication when querying the npm registry" + "description": "The username and password (username:password), or their Base64 encoding, to use for npm authentication" }, "npmAuthToken": { "type": ["zpm_utils::Secret", "null"], @@ -371,7 +371,7 @@ }, "npmAuthIdent": { "type": ["string", "null"], - "description": "The username to use for authentication when querying the npm registry" + "description": "The username and password (username:password), or their Base64 encoding, to use for npm authentication" }, "npmAuthToken": { "type": ["zpm_utils::Secret", "null"], @@ -411,7 +411,7 @@ }, "npmAuthIdent": { "type": ["string", "null"], - "description": "The username to use for authentication when querying the npm registry" + "description": "The username and password (username:password), or their Base64 encoding, to use for npm authentication" }, "npmAuthToken": { "type": ["zpm_utils::Secret", "null"], @@ -457,7 +457,7 @@ }, "npmAuthIdent": { "type": ["string", "null"], - "description": "The username to use for npm authentication for matching packages" + "description": "The username and password (username:password), or their Base64 encoding, to use for npm authentication" }, "npmAuthToken": { "type": ["zpm_utils::Secret", "null"], @@ -491,7 +491,7 @@ }, "npmAuthIdent": { "type": ["string", "null"], - "description": "The username to use for npm authentication for matching sources" + "description": "The username and password (username:password), or their Base64 encoding, to use for npm authentication" }, "npmAuthToken": { "type": ["zpm_utils::Secret", "null"], diff --git a/website/config/manifest.json b/website/config/manifest.json index f56f5983..c96d2066 100644 --- a/website/config/manifest.json +++ b/website/config/manifest.json @@ -1,11 +1,11 @@ { "title": "JSON Schema for Yarn Manifest files", "$schema": "https://json-schema.org/draft/2019-09/schema#", - "description": "Manifest files (also called `package.json` because of their name) contain everything needed to describe the settings unique to one particular package. Project will contain multiple such manifests if they use the workspace feature, as each workspace is described through its own manifest.", + "description": "Manifest files (also called `package.json` because of their name) contain everything needed to describe the settings unique to one particular package. Project will contain multiple such manifests if they use the workspace feature, as each workspace is described through its own manifest. Fields whose types include `null` accept it as an unset value. Dependency maps, script maps, workspace lists, and `publishConfig` must retain their documented collection or object types. Nested `exports` targets may be `null` to block an export; nested `imports` targets must be strings or objects.", "__info": [ "This file contains the JSON Schema for Yarn Manifest files and is:", - "1) Hosted on the Yarn Website at http://yarnpkg.com/configuration/manifest.json", - "2) Used to generate the documentation page at http://yarnpkg.com/configuration/manifest", + "1) Hosted on the Yarn Website at https://v6.yarnpkg.com/configuration/manifest.json", + "2) Used to generate the documentation page at https://v6.yarnpkg.com/configuration/manifest", "Note: Properties prefixed with a single underscore (e.g. _examples, _hidden)", "are unique to our documentation generation interpreter. All others will be picked up", @@ -21,21 +21,21 @@ "name": { "title": "Name of the package.", "description": "Used to identify it across the application, especially amongst multiple workspaces. The first part of the name (here `@scope/`) is optional and is used as a namespace).", - "type": "string", + "type": ["string", "null"], "pattern": "^(?:@([^/]+?)/)?([^/]+?)$", "examples": ["@scope/name"] }, "version": { "title": "Version of the package.", "description": "Usually doesn't have any impact on your project, except when it is a workspace - then its version must match the specified ranges for the workspace to be selected as resolution candidate.", - "type": "string", + "type": ["string", "null"], "pattern": "^(?:(.+))$", "examples": ["1.2.3"] }, "stableVersion": { "title": "Stable version used as the base for deferred version bumps.", "description": "When present, Yarn will use this value instead of `version` as the current stable release when applying deferred version changes. This is useful for prerelease workflows where `version` may already include a prerelease suffix.", - "type": "string", + "type": ["string", "null"], "pattern": "^(?:(.+))$", "_examples": [ { @@ -51,7 +51,7 @@ "packageManager": { "title": "Define the package manager that should be used when working on this project.", "description": "This field is used by [Corepack](https://nodejs.org/api/corepack.html) and similar tools to detect the Yarn version in use in a project - in a sense, it has the same purpose as your lockfile, but only for Yarn itself.\n\nYarn will automatically set this value when running `yarn set version`.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["yarn@4.0.0"], "_examples": [ @@ -68,7 +68,7 @@ "packageManagerMigration": { "title": "Define the package manager that should be used while migration mode is enabled.", "description": "This field is used by Yarn Switch when migration mode is active. It lets a project temporarily opt into a different Yarn binary without replacing the regular `packageManager` field.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "_examples": [ { @@ -84,8 +84,8 @@ "type": { "title": "Define how should be interpreted `.js` files.", "description": "A Node.js v13.x [option](https://nodejs.org/api/esm.html#esm_package_json_type_field). Possible values are `commonjs` (the default) and `module`. Yarn 3+ will generate a `.pnp.cjs` file when using PnP regardless of this option.", - "type": "string", - "enum": ["commonjs", "module"], + "type": ["string", "null"], + "enum": ["commonjs", "module", null], "default": "commonjs" }, "extends": { @@ -109,7 +109,7 @@ "private": { "title": "Define whether the package is meant to be published.", "description": "If true, the package is considered private and Yarn will refuse to publish it regardless of the circumstances.", - "type": "boolean", + "type": ["boolean", "null"], "default": false, "examples": [true] }, @@ -178,7 +178,7 @@ "main": { "title": "Path of the file that should be resolved when requiring the package via a bare identifier.", "description": "This field can be modified at publish-time through the use of the `publishConfig.main` field.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./sources/index.js"] }, @@ -214,13 +214,17 @@ "imports": { "title": "Private package import aliases.", "description": "Defines `#`-prefixed import specifiers that can be used from within this package.", - "type": ["string", "object"], + "type": ["string", "object", "null"], "patternProperties": { "^#.+$": { "$ref": "#/properties/imports" }, "^(.+)$": { - "$ref": "#/properties/imports" + "$ref": "#/properties/imports", + "type": [ + "string", + "object" + ] } }, "_examples": [ @@ -244,14 +248,14 @@ "module": { "title": "Path of the file that should be resolved when requiring the package via a bare identifier in an ES6-compatible bundler environment.", "description": "This field should be considered deprecated, with `exports` being its official replacement.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./sources/index.mjs"] }, "browser": { "title": "Browser-specific entry point or path replacements.", "description": "Bundlers may use this field to replace Node-oriented files with browser-compatible alternatives, or to ignore files by mapping them to `false`.", - "type": ["string", "object"], + "type": ["string", "object", "null"], "patternProperties": { "^(.+)$": { "type": ["string", "boolean"], @@ -283,7 +287,7 @@ "bin": { "title": "Set of files to expose via `yarn run bin-name` and the shell environment.", "description": "If set to a string, the binary value will be the package name (not including its scope part).", - "type": ["string", "object"], + "type": ["string", "object", "null"], "format": "uri-reference", "patternProperties": { "^(.+)$": { @@ -511,13 +515,13 @@ "built": { "title": "Define whether to run the postinstall script or not.", "description": "If false, the package will never be built (deny-list). This behavior is reversed when the `enableScripts` yarnrc setting is toggled off - when that happens, only packages with `built` explicitly set to `true` will be built (allow-list); as for those with `built` explicitly set to `false`, they will simply see their build script warnings downgraded into simple notices.", - "type": "boolean", + "type": ["boolean", "null"], "examples": [false] }, "unplugged": { "title": "Define whether the package must be unplugged or not.", "description": "If true, the specified package will be automatically unplugged at install time. This should only be needed for packages that contain scripts in other languages than Javascript (for example `nan` contains C++ headers).", - "type": "boolean", + "type": ["boolean", "null"], "examples": [true] } }, @@ -640,13 +644,13 @@ "preferUnplugged": { "title": "Define whether the package must be unplugged or not.", "description": "While Yarn attempts to reference and load packages directly from their zip archives, it may not always be possible. A heuristic tries to detect cases where zip-loading would be problematic and unpack the files on disk instead but, being just a heuristic, it may report incorrect results.\n\nThe `preferUnplugged` field lets you define yourself, as a package author, whether your package works or not when stored as an archive. If set, it will override the default heuristic.", - "type": "boolean", + "type": ["boolean", "null"], "examples": [false] }, "files": { "title": "Array of file glob patterns that will be included within the published tarball.", "description": "File patterns follow a similar syntax to `.gitignore`, but reversed: including a file, directory, or glob pattern (`*`, `**/*`, and such) will make it so that file is included in the tarball when it’s packed. Omitting the field will make it default to `[\"*\"]`, which means it will include all files.\n\nIf this field is missing, Yarn will use the project's `.gitignore` to generate the pack list, or the `.npmignore` file instead if available.\n\nSome special files and directories are also [included](https://github.com/yarnpkg/berry/blob/ab2e84588b1eacb2ec60a751f12b168415224a19/packages/plugin-pack/sources/packUtils.ts#L11) or [excluded](https://github.com/yarnpkg/berry/blob/ab2e84588b1eacb2ec60a751f12b168415224a19/packages/plugin-pack/sources/packUtils.ts#L27) regardless of whether they exist in the `files` array.", - "type": "array", + "type": ["array", "null"], "items": { "type": "string", "format": "uri-reference" @@ -670,13 +674,13 @@ "access": { "title": "Define the access to use when publishing the package.", "description": "Valid values are `public` and `restricted`, but `restricted` usually requires to register for a paid plan (this is up to the registry you use).", - "type": "string", - "enum": ["public", "restricted"], + "type": ["string", "null"], + "enum": ["public", "restricted", null], "examples": ["public"] }, "bin": { "title": "Replacement of the package's `bin` field, used in the published tarball over the main one.", - "type": ["string", "object"], + "type": ["string", "object", "null"], "format": "uri-reference", "patternProperties": { "^(.+)$": { @@ -688,7 +692,7 @@ }, "browser": { "title": "Replacement of the package's `browser` field, used in the published tarball over the main one.", - "type": ["string", "object"], + "type": ["string", "object", "null"], "format": "uri-reference", "patternProperties": { "^(.+)$": { @@ -700,7 +704,7 @@ }, "executableFiles": { "title": "Set of files that must be marked as executable (+x) in the published tarball.", - "type": "array", + "type": ["array", "null"], "items": { "type": "string", "format": "uri-reference" @@ -722,52 +726,53 @@ }, "imports": { "title": "Replacement of the package's `imports` field, used in the published tarball over the main one.", - "type": ["string", "object"], + "type": ["string", "object", "null"], "patternProperties": { "^(.+)$": { - "$ref": "#/properties/imports" + "$ref": "#/properties/imports", + "type": ["string", "object"] } }, "examples": [{"#internal": "./build/internal.js"}] }, "main": { "title": "Replacement of the package's `main` field, used in the published tarball over the main one.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./build/index.js"] }, "module": { "title": "Replacement of the package's `module` field, used in the published tarball over the main one.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./build/index.mjs"] }, "provenance": { "title": "Define whether to produce a provenance statement for the package when publishing. Overrides all other provenance settings.", - "type": "boolean", + "type": ["boolean", "null"], "examples": [true] }, "registry": { "description": "If present, will replace whatever registry is defined in the configuration when the package is about to be pushed to a remote location.", - "type": "string", + "type": ["string", "null"], "format": "uri", "examples": ["https://npm.pkg.github.com"] }, "type": { "title": "Replacement of the package's `type` field, used in the published tarball over the main one.", - "type": "string", - "enum": ["commonjs", "module"], + "type": ["string", "null"], + "enum": ["commonjs", "module", null], "examples": ["module"] }, "types": { "title": "Replacement of the package's `types` field, used in the published tarball over the main one.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./build/index.d.ts"] }, "typings": { "title": "Replacement of the package's `typings` field, used in the published tarball over the main one.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./build/index.d.ts"] } @@ -798,21 +803,20 @@ }, "installConfig": { "title": "Extra settings affecting how the package is installed.", - "type": "object", + "description": "Omitted or null overrides inherit `nmHoistingLimits` and `nmSelfReferences` from the yarnrc configuration.", + "type": ["object", "null"], "properties": { "hoistingLimits": { "title": "Defines the highest point where packages can be hoisted.", "description": "See `nmHoistingLimits` for more information.", - "type": "string", - "enum": ["workspaces", "dependencies", "none"], - "default": "none", + "type": ["string", "null"], + "enum": ["workspaces", "dependencies", "none", null], "examples": ["none"] }, "selfReferences": { "title": "Defines whether workspaces are allowed to require themselves.", "description": "See `nmSelfReferences` for more information.", - "type": "boolean", - "default": true, + "type": ["boolean", "null"], "examples": [true] } }, diff --git a/website/config/yarnrc.json b/website/config/yarnrc.json index 769998c1..5a02b490 100644 --- a/website/config/yarnrc.json +++ b/website/config/yarnrc.json @@ -1,12 +1,12 @@ { "title": "JSON Schema for Yarnrc files", "$schema": "https://json-schema.org/draft/2019-09/schema#", - "description": "Yarnrc files (named this way because they must be called `.yarnrc.yml`) are the one place where you'll be able to configure Yarn's internal settings. While Yarn will automatically find them in the parent directories, they should usually be kept at the root of your project (often your repository). **Starting from the v2, they must be written in valid Yaml and have the right extension** (simply calling your file `.yarnrc` won't do).\n\nEnvironment variables can be accessed from setting definitions by using the `${NAME}` syntax when defining the values. By default Yarn will require the variables to be present, but this can be turned off by using either `${NAME-fallback}` (which will return `fallback` if `NAME` isn't set) or `${NAME:-fallback}` (which will return `fallback` if `NAME` isn't set, or is an empty string).\n\nFinally, note that most settings can also be defined through environment variables (at least for the simpler ones; arrays and objects aren't supported yet). To do this, just prefix the names and write them in snake case: `YARN_CACHE_FOLDER` will set the cache folder (such values will overwrite any that might have been defined in the RC files - use them sparingly).", + "description": "Yarnrc files (named this way because they must be called `.yarnrc.yml`) are the one place where you'll be able to configure Yarn's internal settings. While Yarn will automatically find them in the parent directories, they should usually be kept at the root of your project (often your repository). **Starting from the v2, they must be written in valid Yaml and have the right extension** (simply calling your file `.yarnrc` won't do).\n\nEnvironment variables can be accessed from setting definitions by using the `${NAME}` syntax when defining the values. By default Yarn will require the variables to be present, but this can be turned off by using either `${NAME-fallback}` (which will return `fallback` if `NAME` isn't set) or `${NAME:-fallback}` (which will return `fallback` if `NAME` isn't set, or is an empty string).\n\nNullable settings accept explicit `null` values. Omission lets configuration sources and defaults apply; `null` is an explicit value, with setting-specific behavior.\n\nFinally, note that most settings can also be defined through environment variables (at least for the simpler ones; arrays and objects aren't supported yet). To do this, just prefix the names and write them in snake case: `YARN_CACHE_FOLDER` will set the cache folder (such values will overwrite any that might have been defined in the RC files - use them sparingly).", "__info": [ "This file contains the JSON Schema for Yarnrc files and is:", - "1) Hosted on the Yarn Website at http://yarnpkg.com/configuration/yarnrc.json", + "1) Hosted on the Yarn Website at https://v6.yarnpkg.com/configuration/yarnrc.json", "2) Registered on the SchemaStore catalog so that editors can offer autocompletion and validation.", - "3) Used to generate the documentation page at http://yarnpkg.com/configuration/yarnrc", + "3) Used to generate the documentation page at https://v6.yarnpkg.com/configuration/yarnrc", "Note: Properties prefixed with a single underscore (e.g. _exampleItems, _exampleKeys, _hidden)", "are unique to our documentation generation interpreter. All others will be picked up", @@ -14,7 +14,7 @@ "Rules:", "1) Don't set a default if it's null, dynamic, or an object.", - "2) Use `examples` for scalars, `_exampleItems` for arrays, and `_exampleKeys` for objects.", + "2) Use `examples` for scalars and `_examples` with descriptions and values for richer examples.", "3) Always add a _package property to each configuration setting." ], "type": "object", @@ -22,10 +22,9 @@ "cacheFolder": { "_package": "@yarnpkg/core", "title": "Path where the downloaded packages are stored on your system.", - "description": "They'll be normalized, compressed, and saved under the form of zip archives with standardized names. The cache is deemed to be relatively safe to be shared by multiple projects, even when multiple Yarn instances run at the same time on different projects. For setting a global cache folder, you should use `enableGlobalCache` instead.", + "description": "They'll be normalized, compressed, and saved under the form of zip archives with standardized names. The cache is deemed to be relatively safe to be shared by multiple projects, even when multiple Yarn instances run at the same time on different projects. For setting a global cache folder, you should use `enableGlobalCache` instead. Defaults to `.yarn/cache` in the project when the global cache is disabled.", "type": "string", - "format": "uri-reference", - "default": "crate::compute_cache_folder(context)" + "format": "uri-reference" }, "changesetBaseRefs": { "_package": "@yarnpkg/plugin-git", @@ -51,15 +50,16 @@ "_package": "@yarnpkg/plugin-git", "title": "Amount of `git clone` operations that Yarn will run at the same time.", "description": "We by default limit it to 2 concurrent clone operations.", - "type": "number", - "default": 2 + "type": "integer", + "default": 2, + "minimum": 0 }, "compressionLevel": { "_package": "@yarnpkg/core", - "type": ["number", "string"], + "type": ["integer", "string", "null"], "title": "Compression level employed for zip archives", - "description": "Possible values go from `0` (\"no compression, faster\") to `9` (\"heavy compression, slower\").", - "enum": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + "description": "Values from `0` (no compression) to `9` (heavy compression) are accepted as integers or strings. Set to `null` to let Yarn choose the compression algorithm.", + "enum": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", null] }, "defaultSemverRangePrefix": { "_package": "@yarnpkg/plugin-essentials", @@ -95,8 +95,7 @@ "_package": "@yarnpkg/core", "title": "Define whether Yarn should attempt to check for malicious changes.", "description": "If true, Yarn will query the remote registries to validate that the lockfile content matches the remote information. These checks make installs slower, so you should only run them on branches managed by users outside your circle of trust.\n\nYarn will automatically enable the hardened mode on GitHub pull requests from public repository. Should you want to disable it, explicitly set it to `false` in your yarnrc file.", - "type": "boolean", - "default": "crate::is_public_pr_ci(context)" + "type": "boolean" }, "enableImmutableCache": { "_package": "@yarnpkg/core", @@ -108,7 +107,7 @@ "enableImmutableInstalls": { "_package": "@yarnpkg/plugin-essentials", "title": "Define whether to allow adding/removing entries from the lockfile or not.", - "description": "If true (the default on CI), Yarn will refuse to change the lockfile in any way, whether it would add new entries or remove them. Other files can be added to the checklist via the `immutablePatterns` setting.", + "description": "If true, Yarn refuses to change the lockfile and aborts the install instead. Other files can be protected via `immutablePatterns`. Defaults to false, or true when hardened mode is automatically enabled for public GitHub Actions pull requests.", "type": "boolean", "default": false }, @@ -129,9 +128,8 @@ "enableProgressBars": { "_package": "@yarnpkg/core", "title": "Define whether animated progress bars should be shown or not.", - "description": "If true (the default outside of CI environments), Yarn will show progress bars for long-running events.", + "description": "If true, Yarn shows progress bars for long-running events. Enabled by default when the output is a terminal.", "type": "boolean", - "default": "zpm_utils::is_terminal()", "examples": [true] }, "enableScripts": { @@ -165,56 +163,57 @@ "globalFolder": { "_package": "@yarnpkg/core", "title": "Path where all files global to the system will be stored.", - "description": "Various files we be stored there: global cache, metadata cache, ...", + "description": "Stores the global package cache and metadata cache. Defaults to `.yarn/zpm` inside your home directory.", "type": "string", "format": "uri-reference", - "default": "Path::home_dir().unwrap().unwrap().with_join_str(\".yarn/zpm\")", - "examples": ["${HOME}/.yarn/berry"] + "examples": ["${HOME}/.yarn/zpm"] }, "httpProxy": { "_package": "@yarnpkg/core", "title": "Proxy to use when making an HTTP request.", - "type": "string", + "type": ["string", "null"], "format": "uri", "examples": ["http://proxy:4040"] }, "httpRetry": { "_package": "@yarnpkg/core", - "title": "Amount of time to wait in seconds before retrying a failed HTTP request.", - "type": "number", - "default": 3 + "title": "Number of times to retry a failed HTTP request.", + "type": "integer", + "default": 3, + "minimum": 0 }, "httpTimeout": { "_package": "@yarnpkg/core", "title": "Amount of time to wait in milliseconds before cancelling pending HTTP requests.", - "type": "number", - "default": 60000 + "type": "integer", + "default": 60000, + "minimum": 0 }, "httpsCaFilePath": { "_package": "@yarnpkg/core", "title": "Path to a file containing one or multiple Certificate Authority signing certificates.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./exampleCA.pem"] }, "httpsCertFilePath": { "_package": "@yarnpkg/core", "title": "Path to a file containing a certificate chain in PEM format.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./exampleCert.pem"] }, "httpsKeyFilePath": { "_package": "@yarnpkg/core", "title": "Path to a file containing a private key in PEM format.", - "type": "string", + "type": ["string", "null"], "format": "uri-reference", "examples": ["./exampleKey.pem"] }, "httpsProxy": { "_package": "@yarnpkg/core", "title": "Define a proxy to use when making an HTTPS request.", - "type": "string", + "type": ["string", "null"], "format": "uri", "examples": ["http://proxy:4040"] }, @@ -266,6 +265,14 @@ } ] }, + "lazyInstallMode": { + "_package": "@yarnpkg/core", + "title": "Scope of lazy installs.", + "description": "Use `focused` to install only the active workspace and its dependencies, or `all` to install the entire project.", + "type": "string", + "enum": ["focused", "all"], + "default": "all" + }, "logFilters": { "title": "Alter the log levels for emitted messages.", "description": "This can be used to hide specific messages, or instead make them more prominent. Rules defined there accept filtering messages by exact text or glob pattern.", @@ -274,12 +281,12 @@ "type": "object", "properties": { "text": { - "type": "string", + "type": ["string", "null"], "title": "Match messages whose content is strictly equal to the given text.", "examples": ["lorem-ipsum@npm:1.2.3 lists build scripts, but its build has been explicitly disabled through configuration"] }, "pattern": { - "type": "string", + "type": ["string", "null"], "title": "Match messages whose content match the given glob pattern.", "description": "Patterns can be overridden on a case-by-case basis by using the `text` filter, which has precedence over `pattern`.", "examples": ["lorem-ipsum@* lists build scripts, but its build has been explicitly disabled through configuration"] @@ -326,8 +333,9 @@ "_package": "@yarnpkg/core", "title": "Amount of HTTP requests that are allowed to run at the same time.", "description": "We default to 100 concurrent requests, but it may be required to limit it even more when working behind proxies that can't handle large amounts of traffic.", - "type": "number", - "default": 100 + "type": "integer", + "default": 100, + "minimum": 0 }, "networkSettings": { "_package": "@yarnpkg/core", @@ -338,20 +346,20 @@ "type": "object", "properties": { "enableNetwork": { - "$ref": "#/properties/enableNetwork", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/enableNetwork"}, {"type": "null"}] }, "httpsCaFilePath": { - "$ref": "#/properties/httpsCaFilePath", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/httpsCaFilePath" }, "httpsCertFilePath": { - "$ref": "#/properties/httpsCertFilePath", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/httpsCertFilePath" }, "httpsKeyFilePath": { - "$ref": "#/properties/httpsKeyFilePath", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/httpsKeyFilePath" } } } @@ -403,10 +411,6 @@ "_package": "@yarnpkg/plugin-pnp", "title": "Define how Node packages should be installed.", "description": "Yarn supports three ways to install your project's dependencies, based on the `nodeLinker` setting. Possible values are:\n\n- If `pnp`, a single Node.js loader file will be generated.\n- If `pnpm`, a `node-modules` will be created using symlinks and hardlinks to a global content-addressable store.\n- If `node-modules`, a regular `node_modules` folder just like in Yarn Classic or npm will be created.", - "anyOf": [ - { "type": "string" }, - { "enum": ["pnp", "pnpm", "node-modules"] } - ], "type": "string", "default": "pnp", "_examples": [ @@ -418,7 +422,8 @@ "description": "Use a traditional node_modules install.", "value": "node-modules" } - ] + ], + "enum": ["pnp", "pnpm", "node-modules"] }, "nodeExperimentalPackageMap": { "_package": "@yarnpkg/plugin-pnp", @@ -473,30 +478,30 @@ "_package": "@yarnpkg/plugin-npm", "title": "Define the registry to use when auditing dependencies.", "description": "If not explicitly set, the value of `npmRegistryServer` will be used.", - "type": "string", + "type": ["string", "null"], "format": "uri", "examples": ["https://registry.npmjs.org"] }, "npmAuthIdent": { "_package": "@yarnpkg/plugin-npm", - "title": "Define the authentication credentials to use by default when accessing your registries.", + "title": "Username and password (`username:password`), or their Base64 encoding, to use for npm authentication.", "description": "Replacement of the former `_auth` setting. Because it requires storing unencrypted values in your configuration, `npmAuthToken` should be preferred when possible.", - "type": "string", + "type": ["string", "null"], "examples": ["username:password"] }, "npmAuthToken": { "_package": "@yarnpkg/plugin-npm", "title": "Define the authentication token to use by default when accessing your registries.", "description": "Replacement of the former `_authToken` settings. If you're using `npmScopes` to define multiple registries, the `npmRegistries` dictionary allows you to override these credentials on a per-registry basis.", - "type": "string", + "type": ["string", "null"], "examples": ["ffffffff-ffff-ffff-ffff-ffffffffffff"] }, "npmPublishAccess": { "_package": "@yarnpkg/plugin-npm-cli", - "type": "string", + "type": ["string", "null"], "title": "Define the default access to use when publishing packages to the npm registry.", "description": "Valid values are `public` and `restricted`, but `restricted` usually requires to register for a paid plan (this is up to the registry you use). Can be overridden on a per-package basis using the [`publishConfig.access`](manifest#publishConfig.access) field.", - "enum": ["public", "restricted"] + "enum": ["public", "restricted", null] }, "npmPublishProvenance": { "_package": "@yarnpkg/plugin-npm-cli", @@ -512,7 +517,7 @@ "items": { "type": "string" }, - "examples": ["known_insecure_package"], + "examples": [["known_insecure_package"]], "_examples": [ { "description": "Exclude one package from audit reports.", @@ -531,7 +536,7 @@ "items": { "type": "string" }, - "examples": ["1234567"], + "examples": [["1234567"]], "_examples": [ { "description": "Ignore a single advisory ID.", @@ -547,7 +552,7 @@ "_package": "@yarnpkg/plugin-npm", "title": "Define the registry to use when pushing packages.", "description": "If not explicitly set, the value of `npmRegistryServer` will be used. Overridden by `publishConfig.registry`.", - "type": "string", + "type": ["string", "null"], "format": "uri", "examples": ["https://npm.pkg.github.com"] }, @@ -561,16 +566,16 @@ "type": "object", "properties": { "npmAlwaysAuth": { - "$ref": "#/properties/npmAlwaysAuth", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/npmAlwaysAuth"}, {"type": "null"}] }, "npmAuthIdent": { - "$ref": "#/properties/npmAuthIdent", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmAuthIdent" }, "npmAuthToken": { - "$ref": "#/properties/npmAuthToken", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmAuthToken" } } } @@ -629,25 +634,25 @@ "type": "object", "properties": { "npmPublishRegistry": { - "$ref": "#/properties/npmPublishRegistry", "examples": ["https://registry.yarnpkg.com"], - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmPublishRegistry" }, "npmRegistryServer": { - "$ref": "#/properties/npmRegistryServer", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/npmRegistryServer"}, {"type": "null"}] }, "npmAlwaysAuth": { - "$ref": "#/properties/npmAlwaysAuth", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/npmAlwaysAuth"}, {"type": "null"}] }, "npmAuthIdent": { - "$ref": "#/properties/npmAuthIdent", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmAuthIdent" }, "npmAuthToken": { - "$ref": "#/properties/npmAuthToken", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmAuthToken" } } } @@ -684,43 +689,65 @@ "type": "object", "properties": { "ecosystemFilter": { - "type": "string", - "enum": ["npm", "pypi"], + "type": ["string", "null"], + "enum": ["npm", "pypi", null], "_hidden": true }, "packageFilter": { - "type": "string", + "type": ["string", "null"], "_hidden": true }, "npmRegistryServer": { - "$ref": "#/properties/npmRegistryServer", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/npmRegistryServer"}, {"type": "null"}] }, "npmPublishRegistry": { - "$ref": "#/properties/npmPublishRegistry", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmPublishRegistry" }, "pypiRegistryServer": { - "$ref": "#/properties/pypiRegistryServer", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/pypiRegistryServer"}, {"type": "null"}] }, "npmMinimalAgeGate": { - "$ref": "#/properties/npmMinimalAgeGate", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/npmMinimalAgeGate"}, {"type": "null"}] }, "npmAlwaysAuth": { - "$ref": "#/properties/npmAlwaysAuth", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/npmAlwaysAuth"}, {"type": "null"}] }, "npmAuthIdent": { - "$ref": "#/properties/npmAuthIdent", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmAuthIdent" }, "npmAuthToken": { - "$ref": "#/properties/npmAuthToken", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmAuthToken" } - } + }, + "anyOf": [ + { + "required": ["ecosystemFilter"], + "properties": { + "ecosystemFilter": { + "not": { + "type": "null" + } + } + } + }, + { + "required": ["packageFilter"], + "properties": { + "packageFilter": { + "not": { + "type": "null" + } + } + } + } + ] }, "_examples": [ { @@ -756,32 +783,54 @@ "type": "object", "properties": { "ecosystemFilter": { - "type": "string", - "enum": ["npm", "pypi"], + "type": ["string", "null"], + "enum": ["npm", "pypi", null], "_hidden": true }, "registryFilter": { - "type": "string", + "type": ["string", "null"], "format": "uri", "_hidden": true }, "npmMinimalAgeGate": { - "$ref": "#/properties/npmMinimalAgeGate", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/npmMinimalAgeGate"}, {"type": "null"}] }, "npmAlwaysAuth": { - "$ref": "#/properties/npmAlwaysAuth", - "_hidden": true + "_hidden": true, + "anyOf": [{"$ref": "#/properties/npmAlwaysAuth"}, {"type": "null"}] }, "npmAuthIdent": { - "$ref": "#/properties/npmAuthIdent", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmAuthIdent" }, "npmAuthToken": { - "$ref": "#/properties/npmAuthToken", - "_hidden": true + "_hidden": true, + "$ref": "#/properties/npmAuthToken" } - } + }, + "anyOf": [ + { + "required": ["ecosystemFilter"], + "properties": { + "ecosystemFilter": { + "not": { + "type": "null" + } + } + } + }, + { + "required": ["registryFilter"], + "properties": { + "registryFilter": { + "not": { + "type": "null" + } + } + } + } + ] }, "_examples": [ { @@ -846,7 +895,7 @@ "properties": { "optional": { "_hidden": true, - "type": "boolean", + "type": ["boolean", "null"], "examples": [true] } } @@ -977,34 +1026,34 @@ "supportedArchitectures": { "_package": "@yarnpkg/core", "title": "Systems for which Yarn should install packages.", - "type": "object", + "type": ["object", "array", "null"], "properties": { "os": { "title": "List of operating systems to cover.", - "type": "array", + "type": ["string", "array", "null"], "items": { "type": "string" }, - "default": [], + "default": "current", "_exampleItems": ["current", "darwin", "linux", "win32"] }, "cpu": { "title": "List of CPU architectures to cover.", "description": "See https://nodejs.org/docs/latest/api/process.html#processarch for the architectures supported by Node.js", - "type": "array", + "type": ["string", "array", "null"], "items": { "type": "string" }, - "default": [], + "default": "current", "_exampleItems": ["current", "x64", "ia32", "arm64"] }, "libc": { "title": "The list of standard C libraries to cover.", - "type": "array", + "type": ["string", "array", "null"], "items": { "type": "string" }, - "default": [], + "default": "current", "_exampleItems": ["current", "glibc", "musl"] } }, @@ -1024,13 +1073,33 @@ "cpu": ["x64", "arm64"], "libc": ["glibc", "musl"] } + }, + { + "description": "Match macOS arm64 and Linux x64 independently, with any C library.", + "value": [ + { + "os": "darwin", + "cpu": "arm64", + "libc": null + }, + { + "os": "linux", + "cpu": "x64", + "libc": null + } + ] } - ] + ], + "description": "Accepts a single entry or a list of entries. Fields within each entry form a cross product; list entries are matched independently. An omitted setting, `null`, or an empty list uses the current system. Each field accepts a string, an array of strings, or `null` to cover all values; an empty field array covers none. Omitted fields default to `current`.", + "items": { + "$ref": "#/properties/supportedArchitectures", + "type": "object" + } }, "tsEnableAutoTypes": { "_package": "@yarnpkg/plugin-typescript", "title": "Define whether to automatically install @types dependencies.", - "description": "If true, Yarn will automatically add `@types` dependencies when running `yarn add` with packages that don't provide their own typings (as reported by the Algolia npm database). This behavior is enabled by default if you have a tsconfig.json file at the root of your project, or in your current workspace.", + "description": "Alias for `enableAutoTypes`. Prefer the canonical setting name for new configurations.", "type": "boolean", "examples": [true] }, @@ -1058,7 +1127,7 @@ "_package": "@yarnpkg/core", "title": "Maximum number of output lines kept in memory per daemon task.", "description": "Long-running daemon tasks keep a bounded output buffer so recent logs remain available without unbounded memory growth.", - "type": "number", + "type": "integer", "default": 1000, "_examples": [ { @@ -1069,13 +1138,14 @@ "description": "Keep a larger in-memory history while debugging task output.", "value": 5000 } - ] + ], + "minimum": 0 }, "daemonMaxClosedTasks": { "_package": "@yarnpkg/core", "title": "Maximum number of completed daemon tasks kept in memory.", "description": "Once this limit is reached, older completed or failed daemon tasks may be discarded from the daemon's in-memory history.", - "type": "number", + "type": "integer", "default": 100, "_examples": [ { @@ -1086,7 +1156,8 @@ "description": "Keep more completed tasks available for inspection.", "value": 250 } - ] + ], + "minimum": 0 }, "daemonDefaultWarmupPeriod": { "_package": "@yarnpkg/core", @@ -1108,9 +1179,8 @@ "enableAutoTypes": { "_package": "@yarnpkg/plugin-typescript", "title": "Define whether Yarn should automatically add @types packages.", - "description": "When enabled, Yarn may add matching `@types/*` packages when adding dependencies that don't ship their own TypeScript declarations. This setting is also available through the `tsEnableAutoTypes` alias.", + "description": "When enabled, Yarn may add matching `@types/*` packages when adding dependencies that don't ship their own TypeScript declarations. Enabled by default when a `tsconfig.json` exists at the project root or in the active workspace. This setting is also available through the `tsEnableAutoTypes` alias.", "type": "boolean", - "default": "crate::check_tsconfig(context)", "_examples": [ { "description": "Enable automatic type acquisition explicitly.", @@ -1287,7 +1357,7 @@ "_package": "@yarnpkg/core", "title": "Timeout before a network request is considered slow.", "description": "The value is expressed in milliseconds and controls when Yarn reports a network request as slow.", - "type": "number", + "type": "integer", "default": 5000, "_examples": [ { @@ -1298,7 +1368,8 @@ "description": "Use a more patient threshold on slow networks.", "value": 30000 } - ] + ], + "minimum": 0 }, "unstableIslands": { "_package": "@yarnpkg/core", @@ -1485,8 +1556,7 @@ "title": "Array of hostname glob patterns for which using the HTTP protocol is allowed.", "type": "array", "items": { - "type": "string", - "pattern": "[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b([-a-zA-Z0-9()@:%_\\+.~#?&//=]*)" + "type": "string" }, "_exampleItems": ["*.example.org", "example.org"], "_examples": [ diff --git a/website/plugins/test-schema.mjs b/website/plugins/test-schema.mjs new file mode 100644 index 00000000..64eb5aba --- /dev/null +++ b/website/plugins/test-schema.mjs @@ -0,0 +1,37 @@ +import assert from 'node:assert/strict'; +import {test} from 'node:test'; + +import {schemaToMarkdown} from '../src/utils/schema.ts'; + +test('renders nullable enums and scalar examples', () => { + const markdown = schemaToMarkdown({properties: { + access: {type: [`string`, `null`], enum: [`public`, `restricted`, null], examples: [`public`, null]}, + }}); + + assert.ok(markdown.includes(':type["public" | "restricted" | null]')); + assert.ok(markdown.includes('access: "public"')); + assert.ok(markdown.includes('access: null')); +}); + +test('renders scalar, array, and null architecture forms', () => { + const markdown = schemaToMarkdown({properties: { + cpu: {type: [`string`, `array`, `null`], items: {type: `string`}}, + targets: {type: `array`, items: {type: [`string`, `null`]}}, + }}); + + assert.ok(markdown.includes(':type[string | string\\[\\] | null]')); + assert.ok(markdown.includes(':type[(string | null)\\[\\]]')); +}); + +test('preserves rich example descriptions and values', () => { + const markdown = schemaToMarkdown({properties: { + cpu: { + type: [`array`, `null`], items: {type: `string`}, examples: [null], + _examples: [{description: `Cover both architectures.`, value: [`x64`, `arm64`]}], + }, + }}); + + assert.ok(markdown.includes('# Cover both architectures.')); + assert.ok(markdown.includes('cpu:\n - "x64"\n - "arm64"')); + assert.ok(!markdown.includes('cpu: null')); +}); diff --git a/website/src/pages/configuration/manifest.astro b/website/src/pages/configuration/manifest.astro index 913554f6..75711793 100644 --- a/website/src/pages/configuration/manifest.astro +++ b/website/src/pages/configuration/manifest.astro @@ -21,5 +21,7 @@ const fields = schemaFieldNames(schema); +

JSON schema for editor validation and autocompletion.

+
diff --git a/website/src/pages/configuration/manifest.json.ts b/website/src/pages/configuration/manifest.json.ts new file mode 100644 index 00000000..5b9aeeaa --- /dev/null +++ b/website/src/pages/configuration/manifest.json.ts @@ -0,0 +1,7 @@ +import type {APIRoute} from 'astro'; + +import schema from '../../../config/manifest.json'; + +export const GET: APIRoute = () => new Response(JSON.stringify(schema, null, 2), { + headers: {'Content-Type': `application/json; charset=utf-8`}, +}); diff --git a/website/src/pages/configuration/yarnrc.astro b/website/src/pages/configuration/yarnrc.astro index bd9bc13d..92b09060 100644 --- a/website/src/pages/configuration/yarnrc.astro +++ b/website/src/pages/configuration/yarnrc.astro @@ -21,5 +21,7 @@ const fields = schemaFieldNames(schema); +

JSON schema for editor validation and autocompletion.

+
diff --git a/website/src/pages/configuration/yarnrc.json.ts b/website/src/pages/configuration/yarnrc.json.ts new file mode 100644 index 00000000..5fc534ad --- /dev/null +++ b/website/src/pages/configuration/yarnrc.json.ts @@ -0,0 +1,7 @@ +import type {APIRoute} from 'astro'; + +import schema from '../../../config/yarnrc.json'; + +export const GET: APIRoute = () => new Response(JSON.stringify(schema, null, 2), { + headers: {'Content-Type': `application/json; charset=utf-8`}, +}); diff --git a/website/src/utils/schema.ts b/website/src/utils/schema.ts index 17e4ec81..3b7bbbf0 100644 --- a/website/src/utils/schema.ts +++ b/website/src/utils/schema.ts @@ -3,14 +3,16 @@ function escapeDirective(s: string): string { } function formatType(prop: Record): string { - if (Array.isArray(prop.type)) - return prop.type.join(` | `); - if (prop.enum) return prop.enum.map((v: any) => typeof v === `string` ? `"${v}"` : String(v)).join(` | `); - if (prop.type === `array`) - return `${prop.items?.type || `any`}[]`; + if (Array.isArray(prop.type)) + return prop.type.map((type: string) => formatType({...prop, type})).join(` | `); + + if (prop.type === `array`) { + const itemType = prop.items ? formatType(prop.items) : `any`; + return `${itemType.includes(` | `) ? `(${itemType})` : itemType}[]`; + } return prop.type || `any`; } @@ -108,11 +110,13 @@ function propertyToMarkdown(name: string, prop: Record): string { lines.push(``, prop.description); - if (Array.isArray(prop._examples) && prop._examples.length > 0) { + const examples = prop._examples ?? prop.examples?.map((value: any) => ({value})); + + if (Array.isArray(examples) && examples.length > 0) { lines.push( ``, `\`\`\`yaml`, - prop._examples.map((example: any) => exampleToYaml(name, example)).join(`\n\n`), + examples.map((example: any) => exampleToYaml(name, example)).join(`\n\n`), `\`\`\``, ); }