diff --git a/.pnp.cjs b/.pnp.cjs index a507d776792d..95ebb9c39fd9 100755 --- a/.pnp.cjs +++ b/.pnp.cjs @@ -6,9 +6,7 @@ function $$SETUP_STATE(hydrateRuntimeState, basePath) { return hydrateRuntimeState(JSON.parse('{\ "__info": [\ "This file is automatically generated. Do not touch it, or risk",\ - "your modifications being lost. We also recommend you not to read",\ - "it either without using the @yarnpkg/pnp package, as the data layout",\ - "is entirely unspecified and WILL change from a version to another."\ + "your modifications being lost."\ ],\ "dependencyTreeRoots": [\ {\ @@ -10551,6 +10549,7 @@ function $$SETUP_STATE(hydrateRuntimeState, basePath) { ["monaco-editor", "npm:0.24.0"],\ ["monaco-editor-webpack-plugin", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:3.1.0"],\ ["pify", "npm:4.0.1"],\ + ["prism-react-renderer", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:1.3.5"],\ ["prismjs", "npm:1.23.0"],\ ["prop-types", "npm:15.7.2"],\ ["qs", "npm:6.10.1"],\ @@ -10561,6 +10560,7 @@ function $$SETUP_STATE(hydrateRuntimeState, basePath) { ["react-helmet", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:6.1.0"],\ ["react-icons", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:3.11.0"],\ ["react-instantsearch-dom", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:6.6.0"],\ + ["react-json-doc", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:2.3.4"],\ ["react-monaco-editor", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:0.36.0"],\ ["react-responsive-carousel", "npm:3.2.22"],\ ["react-scroll-into-view-if-needed", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:2.1.7"],\ @@ -33281,6 +33281,28 @@ function $$SETUP_STATE(hydrateRuntimeState, basePath) { "linkType": "HARD"\ }]\ ]],\ + ["prism-react-renderer", [\ + ["npm:1.3.5", {\ + "packageLocation": "./.yarn/cache/prism-react-renderer-npm-1.3.5-5891d32b72-c18806dcbc.zip/node_modules/prism-react-renderer/",\ + "packageDependencies": [\ + ["prism-react-renderer", "npm:1.3.5"]\ + ],\ + "linkType": "SOFT"\ + }],\ + ["virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:1.3.5", {\ + "packageLocation": "./.yarn/__virtual__/prism-react-renderer-virtual-ccb828411b/0/cache/prism-react-renderer-npm-1.3.5-5891d32b72-c18806dcbc.zip/node_modules/prism-react-renderer/",\ + "packageDependencies": [\ + ["prism-react-renderer", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:1.3.5"],\ + ["@types/react", "npm:16.9.2"],\ + ["react", "npm:16.13.1"]\ + ],\ + "packagePeers": [\ + "@types/react",\ + "react"\ + ],\ + "linkType": "HARD"\ + }]\ + ]],\ ["prismjs", [\ ["npm:1.23.0", {\ "packageLocation": "./.yarn/cache/prismjs-npm-1.23.0-3781560845-8c3cf69150.zip/node_modules/prismjs/",\ @@ -34308,6 +34330,28 @@ function $$SETUP_STATE(hydrateRuntimeState, basePath) { "linkType": "HARD"\ }]\ ]],\ + ["react-json-doc", [\ + ["npm:2.3.4", {\ + "packageLocation": "./.yarn/cache/react-json-doc-npm-2.3.4-6d21e4aa73-8d0e330d4c.zip/node_modules/react-json-doc/",\ + "packageDependencies": [\ + ["react-json-doc", "npm:2.3.4"]\ + ],\ + "linkType": "SOFT"\ + }],\ + ["virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:2.3.4", {\ + "packageLocation": "./.yarn/__virtual__/react-json-doc-virtual-2235cb2e35/0/cache/react-json-doc-npm-2.3.4-6d21e4aa73-8d0e330d4c.zip/node_modules/react-json-doc/",\ + "packageDependencies": [\ + ["react-json-doc", "virtual:118b26a6cee620b5aa3e7e8d8b8e34cd9e486f75b92701001168da9be550fadd8c9d9b12643c642e2d528c2624fd8fe7e128eec9d715340efac44400432a0e0c#npm:2.3.4"],\ + ["@types/react", "npm:16.9.2"],\ + ["react", "npm:16.13.1"]\ + ],\ + "packagePeers": [\ + "@types/react",\ + "react"\ + ],\ + "linkType": "HARD"\ + }]\ + ]],\ ["react-lifecycles-compat", [\ ["npm:3.0.4", {\ "packageLocation": "./.yarn/cache/react-lifecycles-compat-npm-3.0.4-d5e285a39e-a904b0fc0a.zip/node_modules/react-lifecycles-compat/",\ diff --git a/.yarn/cache/prism-react-renderer-npm-1.3.5-5891d32b72-c18806dcbc.zip b/.yarn/cache/prism-react-renderer-npm-1.3.5-5891d32b72-c18806dcbc.zip new file mode 100644 index 000000000000..af31b690a241 Binary files /dev/null and b/.yarn/cache/prism-react-renderer-npm-1.3.5-5891d32b72-c18806dcbc.zip differ diff --git a/.yarn/cache/react-json-doc-npm-2.3.4-6d21e4aa73-8d0e330d4c.zip b/.yarn/cache/react-json-doc-npm-2.3.4-6d21e4aa73-8d0e330d4c.zip new file mode 100644 index 000000000000..dd3440bd74fd Binary files /dev/null and b/.yarn/cache/react-json-doc-npm-2.3.4-6d21e4aa73-8d0e330d4c.zip differ diff --git a/.yarn/versions/48b3857e.yml b/.yarn/versions/48b3857e.yml new file mode 100644 index 000000000000..d6c94c7ecc03 --- /dev/null +++ b/.yarn/versions/48b3857e.yml @@ -0,0 +1,28 @@ +releases: + "@yarnpkg/cli": patch + "@yarnpkg/pnp": patch + +declined: + - "@yarnpkg/esbuild-plugin-pnp" + - "@yarnpkg/plugin-compat" + - "@yarnpkg/plugin-constraints" + - "@yarnpkg/plugin-dlx" + - "@yarnpkg/plugin-essentials" + - "@yarnpkg/plugin-init" + - "@yarnpkg/plugin-interactive-tools" + - "@yarnpkg/plugin-nm" + - "@yarnpkg/plugin-npm-cli" + - "@yarnpkg/plugin-pack" + - "@yarnpkg/plugin-patch" + - "@yarnpkg/plugin-pnp" + - "@yarnpkg/plugin-pnpm" + - "@yarnpkg/plugin-stage" + - "@yarnpkg/plugin-typescript" + - "@yarnpkg/plugin-version" + - "@yarnpkg/plugin-workspace-tools" + - "@yarnpkg/builder" + - "@yarnpkg/core" + - "@yarnpkg/doctor" + - "@yarnpkg/nm" + - "@yarnpkg/pnpify" + - "@yarnpkg/sdks" diff --git a/packages/gatsby/content/advanced/pnp-data.md b/packages/gatsby/content/advanced/pnp-data.md new file mode 100644 index 000000000000..dba6537afe12 --- /dev/null +++ b/packages/gatsby/content/advanced/pnp-data.md @@ -0,0 +1,298 @@ +--- +category: advanced +path: /advanced/pnp-spec +title: "PnP Specification" +description: In-depth documentation of the PnP spec. +--- + +```toc +# This code block gets replaced with the Table of Contents +``` + +## About this document + +To make interoperability easier for third-party projects, this document describes the specification we follow when installing files on disk under the [Plug'n'Play install strategy](/features/pnp). It also means: + +- any change we make to this document will follow semver rules +- we'll do our best to preserve backward compatibility +- new features will be intended to gracefully degrade + +## High-level idea + +Plug'n'Play works by keeping in memory a table of all packages part of the dependency tree, in such a way that we can easily answer two different questions: + +- Given a path, what package does it belong to? +- Given a package, where are the dependencies it can access? + +Resolving a package import thus becomes a matter of interlacing those two operations: + +- First, locate which package is requesting the resolution +- Then retrieve its dependencies, check if the requested package is amongst them +- If it is, then retrieve the dependency information, and return its location + +Extra features can then be designed, but are optional. For example, Yarn leverages the information it knows about the project to throw semantic errors when a dependency cannot be resolved: since we know the state of the whole dependency tree, we also know why a package may be missing. + +## Basic concepts + +All packages are uniquely referenced by **locators**. A locator is a combination of a **package ident**, which includes its scope if relevant, and a **package reference**, which can be seen as a unique ID used to distinguish different instances (or versions) of a same package. The package references should be treated as an opaque value: it doesn't matter from a resolution algorithm perspective that they start with `workspace:`, `virtual:`, `npm:`, or any other protocol. + +## Fallback + +For improved compatibility with legacy codebases, Plug'n'Play supports a feature we call "fallback". The fallback triggers when a package makes a resolution request to a dependency it doesn't list in its dependencies. In normal circumstances the resolver would throw, but when the fallback is enabled the resolver should first try to find the dependency packages amongst the dependencies of a set of special packages. If it finds it, it then returns it transparently. + +In a sense, the fallback can be seen as a limited and safer form of hoisting. While hoisting allows unconstrainted access through multiple levels of dependencies, the fallback requires to explicitly define a fallback package - usually the top-level one. + +## Package locations + +While the Plug'n'Play specification doesn't by itself require runtimes to support anything else than the regular filesystem when accessing package files, producers may rely on more complex data storage mechanisms. For instance, Yarn itself requires the two following extensions which we strongly recommend to support: + +### Zip access + +Files named `*.zip` must be treated as folders for the purpose of file access. For instance, `/foo/bar.zip/package.json` requires to access the `package.json` file located within the `/foo/bar.zip` zip archive. + +If writing a JS tool, the [`@yarnpkg/fslib`](https://yarnpkg.com/package/@yarnpkg/fslib) package may be of assistance, providing a zip-aware filesystem layer called `ZipOpenFS`. + +### Virtual folders + +In order to properly represent packages listing peer dependencies, Yarn relies on a concept called [Virtual Packages](/advanced/lexicon#virtual-package). Their most notable property is that they all have different paths (so that Node.js instantiates them as many times as needed), while still being baked by the same concrete folder on disk. + +This is done by adding path support for the following scheme: + +``` +/path/to/some/folder/__virtual__///subpath/to/file.dat +``` + +When this pattern is found, the `__virtual__//` part must be removed, the `hash` ignored, and the `dirname` operation applied `n` times to the `/path/to/some/folder` part. Some examples: + +``` +/path/to/some/folder/__virtual__/a0b1c2d3/0/subpath/to/file.dat +/path/to/some/folder/subpath/to/file.dat + +/path/to/some/folder/__virtual__/e4f5a0b1/0/subpath/to/file.dat +/path/to/some/folder/subpath/to/file.dat (different hash, same result) + +/path/to/some/folder/__virtual__/a0b1c2d3/1/subpath/to/file.dat +/path/to/some/subpath/to/file.dat + +/path/to/some/folder/__virtual__/a0b1c2d3/3/subpath/to/file.dat +/path/subpath/to/file.dat +``` + +If writing a JS tool, the [`@yarnpkg/fslib`](https://yarnpkg.com/package/@yarnpkg/fslib) package may be of assistance, providing a virtual-aware filesystem layer called `VirtualFS`. + +## Manifest reference + +When [`pnpEnableInlining`](/configuration/yarnrc#pnpEnableInlining) is explicitly set to `false`, Yarn will generate an additional `.pnp.data.json` file containing the following fields. + +This document only covers the data file itself - you should define your own in-memory data structures, populated at runtime with the information from the manifest. For example, Yarn turns the `packageRegistryData` table into two separate memory tables: one that maps a path to a package, and another that maps a package to a path. + +> **Note:** You may notice that various places use arrays of tuples in place of maps. This is mostly intended to make it easier to hydrate ES6 maps, but also sometimes to have non-string keys (for instance `packageRegistryData` will have a `null` key in one particular case). + +import pnpSchema from '@yarnpkg/gatsby/static/configuration/pnp.json'; +import theme from 'prism-react-renderer/themes/vsDark'; +import {JsonDoc} from 'react-json-doc'; + + + +## Resolution algorithm + +> **Note:** for simplicity, this algorithm doesn't mention all the Node.js features that allow mapping a module to another, such as [`imports`](https://nodejs.org/api/packages.html#imports), [`exports`](https://nodejs.org/api/packages.html#exports), or other vendor-specific features. + +### NM_RESOLVE(`specifier`, `parentURL`) + +1. This function is specified in the [Node.js documentation](https://nodejs.org/api/esm.html#resolver-algorithm-specification) + +### PNP_RESOLVE(`specifier`, `parentURL`) + +1. Let `resolved` be **undefined** + +2. If `specifier` is a Node.js builtin, then + + 1. Set `resolved` to `specifier` itself and return it + +3. Otherwise, if `specifier` starts with "/", "./", or "../", then + + 1. Set `resolved` to **NM_RESOLVE**(`specifier`, `parentURL`) and return it + +4. Otherwise, + + 1. Note: `specifier` is now a bare identifier + + 2. Let `unqualified` be **RESOLVE_TO_UNQUALIFIED**(`specifier`, `parentURL`) + + 3. Set `resolved` to **NM_RESOLVE**(`unqualified`, `parentURL`) + +### RESOLVE_TO_UNQUALIFIED(`specifier`, `parentURL`) + +1. Let `resolved` be **undefined** + +2. Let `ident` and `modulePath` be the result of **PARSE_BARE_IDENTIFIER**(`specifier`) + +3. Let `manifest` be **FIND_PNP_MANIFEST**(`parentURL`) + +4. If `manifest` is null, then + + 1. Set `resolved` to **NM_RESOLVE**(`specifier`, `parentURL`) and return it + +5. Let `parentLocator` be **FIND_LOCATOR**(`manifest`, `parentURL`) + +6. If `parentLocator` is null, then + + 1. Set `resolved` to **NM_RESOLVE**(`specifier`, `parentURL`) and return it + +7. Let `parentPkg` be **GET_PACKAGE**(`manifest`, `parentLocator`) + +8. Let `referenceOrAlias` be the entry from `parentPkg.packageDependencies` referenced by `ident` + +9. If `referenceOrAlias` is **undefined**, then + + 1. If `manifest.enableTopLevelFallback` is **true**, then + + 1. If `parentLocator` **isn't** in `manifest.fallbackExclusionList`, then + + 1. Set `referenceOrAlias` to **RESOLVE_VIA_FALLBACK**(`manifest`, `ident`) + +10. If `referenceOrAlias` is still **undefined**, then + + 1. Throw a resolution error + +11. If `referenceOrAlias` is **null**, then + + 1. Note: It means that `parentPkg` has an unfulfilled peer dependency on `ident` + + 2. Throw a resolution error + +12. Otherwise, if `referenceOrAlias` is an array, then + + 1. Let `alias` be `referenceOrAlias` + + 2. Let `dependencyPkg` be **GET_PACKAGE**(`manifest`, `alias`) + + 3. Return `dependencyPkg.packageLocation` concatenated with `modulePath` + +13. Otherwise, + + 1. Let `reference` be `referenceOrAlias` + + 2. Let `dependencyPkg` be **GET_PACKAGE**(`manifest`, {`ident`, `reference`}) + + 3. Return `dependencyPkg.packageLocation` concatenated with `modulePath` + +### GET_PACKAGE(`manifest`, `locator`) + +1. Let `referenceMap` be the entry from `parentPkg.packageRegistryData` referenced by `locator.ident` + +2. Let `pkg` be the entry from `referenceMap` referenced by `locator.reference` + +3. Return `pkg` + + 1. Note: `pkg` cannot be **undefined** here; all packages referenced in any of the Plug'n'Play data tables **MUST** have a corresponding entry inside `packageRegistryData`. + +### FIND_LOCATOR(`manifest`, `moduleUrl`) + +Note: The algorithm described here is quite inefficient. You should make sure to prepare data structure more suited for this task when you read the manifest. + +1. Let `bestLength` be **0** + +2. Let `bestLocator` be **null** + +3. Let `relativeUrl` be the relative path between `manifest` and `moduleUrl` + + 1. Note: Make sure it always starts with a `./` or `../` + +4. If `relativeUrl` matches `manifest.ignorePatternData`, then + + 1. Return **null** + +5. For each `referenceMap` value in `manifest.packageRegistryData` + + 1. For each `registryPkg` value in `referenceMap` + + 1. If `registryPkg.discardFromLookup` **isn't true**, then + + 1. If `registryPkg.packageLocation.length` is greater than `bestLength`, then + + 1. If `relativeUrl` starts with `registryPkg.packageLocation`, then + + 1. Set `bestLength` to `registryPkg.packageLocation.length` + + 2. Set `bestLocator` to the current `registryPkg` locator + +6. Return `bestLocator` + +### RESOLVE_VIA_FALLBACK(`manifest`, `specifier`) + +1. Let `topLevelPkg` be **GET_PACKAGE**(`manifest`, {**null**, **null**}) + +2. Let `referenceOrAlias` be the entry from `topLevelPkg.packageDependencies` referenced by `ident` + +3. If `referenceOrAlias` is defined, then + + 1. Return it immediately + +4. Otherwise, + + 1. Let `referenceOrAlias` be the entry from `manifest.fallbackPool` referenced by `ident` + + 2. Return it immediatly, whether it's defined or not + +### FIND_PNP_MANIFEST(`url`) + +Finding the right PnP manifest to use for a resolution isn't always trivial. There are two main options: + +- Assume that there is a single PnP manifest covering the whole project. This is the most common case, as even when referencing third-party projects (for example via the [`portal:` protocol](/features/protocols#whats-the-difference-between-link-and-portal)) their dependency trees are stored in the same manifest as the main project. + + To do that, call **FIND_CLOSEST_PNP_MANIFEST**(`require.main.filename`) once at the start of the process, cache its result, and return it for each call to **FIND_PNP_MANIFEST** (if you're running in Node.js, you can even use `require.resolve('pnpapi')` which will do this work for you). + +- Try to operate within a multi-project world. **This is rarely required**. We support it inside the Node.js PnP loader, but only because of "project generator" tools like `create-react-app` which are run via `yarn create react-app` and require two different projects (the generator one `and` the generated one) to cooperate within the same Node.js process. + + Supporting this use case is difficult, as it requires a bookkeeping mechanism to track the manifests used to access modules, reusing them as much as possible and only looking for a new one when the chain breaks. + +### FIND_CLOSEST_PNP_MANIFEST(`url`) + +1. Let `manifest` be **null** + +2. Let `directoryPath` be the directory for `url` + +3. Let `pnpPath` be `directoryPath` concatenated with `/.pnp.cjs` + +4. If `pnpPath` exists on the filesystem, then + + 1. Let `pnpDataPath` be `directoryPath` concatenated with `/.pnp.data.json` + + 2. Set `manifest` to `JSON.parse(readFile(pnpDataPath))` and return it + +5. Otherwise, if `directoryPath` is `/`, then + + 1. Return **null** + +6. Otherwise, + + 1. Return **FIND_PNP_MANIFEST**(`directoryPath`) + +### PARSE_BARE_IDENTIFIER(`specifier`) + +1. If `specifier` starts with "@", then + + 1. If `specifier` doesn't contain a "/" separator, then + + 1. Throw an error + + 2. Otherwise, + + 1. Set `ident` to the substring of `specifier` until the second "/" separator or the end of string, whatever happens first + +2. Otherwise, + + 1. Set `ident` to the substring of `specifier` until the first "/" separator or the end of string, whatever happens first + +3. Set `modulePath` to the substring of `specifier` starting from `ident.length` + +4. Return {`ident`, `modulePath`} diff --git a/packages/gatsby/package.json b/packages/gatsby/package.json index 79a5a0874fc6..aec01dad0ede 100644 --- a/packages/gatsby/package.json +++ b/packages/gatsby/package.json @@ -61,6 +61,7 @@ "monaco-editor": "^0.24.0", "monaco-editor-webpack-plugin": "^3.1.0", "pify": "^4.0.1", + "prism-react-renderer": "^1.3.5", "prismjs": "^1.23.0", "prop-types": "^15.7.2", "qs": "^6.7.0", @@ -71,6 +72,7 @@ "react-helmet": "^6.1.0", "react-icons": "^3.10.0", "react-instantsearch-dom": "^6.6.0", + "react-json-doc": "^2.1.0", "react-monaco-editor": "^0.36.0", "react-responsive-carousel": "^3.2.22", "react-scroll-into-view-if-needed": "^2.1.7", diff --git a/packages/gatsby/src/components/markdown.js b/packages/gatsby/src/components/markdown.js index 27f9f0841f41..241567fdb1b4 100644 --- a/packages/gatsby/src/components/markdown.js +++ b/packages/gatsby/src/components/markdown.js @@ -36,8 +36,7 @@ const EditLink = styled.a` const Content = styled.div` blockquote { - margin-left: 0; - margin-right: 0; + margin: 1.5em 0; border-left: 5px solid #859daf; @@ -57,6 +56,10 @@ const Content = styled.div` margin: 0; } + blockquote > p + p { + margin-top: 1.5em; + } + a:not(.anchor) { border-bottom: 1px solid; diff --git a/packages/gatsby/static/configuration/pnp.json b/packages/gatsby/static/configuration/pnp.json new file mode 100644 index 000000000000..cfb878b1ecf4 --- /dev/null +++ b/packages/gatsby/static/configuration/pnp.json @@ -0,0 +1,181 @@ +{ + "title": "JSON Schema for Node.js Plug'n'Play data files", + "$schema": "https://json-schema.org/draft/2019-09/schema#", + "description": "The Plug'n'Play data files contains the set of packages used within a project, and their dependencies.", + "__info": [ + "The following document describes the content of the .pnp.data.json files Yarn generates", + "when the `pnpEnableInlining` setting is set to `false`." + ], + "type": "object", + "properties": { + "__info": { + "description": "An array of arbitrary strings; only used as a header field to give some context to Yarn users.", + "type": "array", + "items": { + "type": "string" + }, + "exampleItems": [ + "This file is automatically generated. Do not touch it, or risk", + "your modifications being lost." + ] + }, + "dependencyTreeRoots": { + "description": "A list of package locators that are roots of the dependency tree. There will typically be one entry for each workspace in the project (always at least one, as the top-level package is a workspace by itself).", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "pattern": "^(?:@([^/]+?)/)?([^/]+?)$", + "examples": ["@app/name"] + }, + "reference": { + "type": "string", + "examples": ["workspace:."] + } + } + }, + "exampleItems": [ + {"name": "@app/monorepo", "reference": "workspace:."}, + {"name": "@app/website", "reference": "workspace:website"} + ] + }, + "ignorePatternData": { + "description": "A nullable regexp. If set, all project-relative importer paths should be matched against it. If the match succeeds, the resolution should follow the classic Node.js resolution algorithm rather than the Plug'n'Play one. Note that unlike other paths in the manifest, the one checked against this regexp won't begin by `./`.", + "type": "string", + "examples": ["^examples(/|$)"] + }, + "enableTopLevelFallback": { + "description": "If true, should a dependency resolution fail for an importer that isn't explicitly listed in `fallbackExclusionList`, the runtime must first check whether the resolution would succeed for any of the packages in `fallbackPool`; if it would, transparently return this resolution. Note that all dependencies from the top-level package are implicitly part of the fallback pool, even if not listed here.", + "type": "boolean", + "examples": [true] + }, + "fallbackPool": { + "description": "A map of locators that all packages are allowed to access, regardless whether they list them in their dependencies or not.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "pattern": "^(?:@([^/]+?)/)?([^/]+?)$", + "examples": ["@app/name"] + }, + "reference": { + "type": "string", + "examples": ["workspace:."] + } + } + }, + "exampleItems": [ + {"name": "@app/monorepo", "reference": "workspace:."} + ] + }, + "fallbackExclusionList": { + "description": "A map of packages that must never use the fallback logic, even when enabled. Keys are the package idents, values are sets of references. Combining the ident with each individual reference yields the set of affected locators.", + "type": "array", + "items": { + "type": "array", + "prefixItems": [{ + "type": "string" + }, { + "type": "array", + "foldStyle": false, + "items": { + "type": "string" + } + }] + }, + "exampleItems": [ + ["@app/server", ["workspace:sources/server"]] + ] + }, + "packageRegistryData": { + "description": "This is the main part of the PnP data file. This table contains the list of all packages, first keyed by package ident then by package reference. One entry will have `null` in both fields and represents the absolute top-level package.", + "type": "array", + "foldStyle": true, + "items": { + "type": "array", + "foldStyle": false, + "prefixItems": [{ + "type": "string" + }, { + "type": "array", + "foldStyle": true, + "items": { + "type": "array", + "foldStyle": false, + "prefixItems": [{ + "type": "string" + }, { + "type": "object", + "properties": { + "packageLocation": { + "description": "The location of the package on disk, relative to the Plug'n'Play manifest. This path must begin by either `./` or `../`, and must end with a trailing `/`.", + "type": "string" + }, + "packageDependencies": { + "description": "The set of dependencies that the package is allowed to access. Each entry is a tuple where the first key is a package name, and the value a package reference. Note that this reference may be null! This only happens when a peer dependency is missing.", + "type": "array", + "foldStyle": true, + "items": { + "type": "array", + "foldStyle": false, + "prefixItems": [{ + "type": "string" + }, { + "type": "string" + }] + } + }, + "linkType": { + "description": "Can be either SOFT, or HARD. Hard package links are the most common, and mean that the target location is fully owned by the package manager. Soft links, on the other hand, typically point to arbitrary user-defined locations on disk.\nThe link type shouldn't matter much for most implementors - it's only needed because of some subtleties involved in turning a Plug'n'Play tree into a node_modules one.", + "type": "string", + "enum": ["SOFT", "HARD"] + }, + "discardFromLookup": { + "description": "If true, this optional field indicates that the package must not be considered when the Plug'n'Play runtime tries to figure out the package that contains a given path. This is for instance what we use when using the `link:` protocol, as they often point to subfolders of a package, not to other packages.", + "type": "boolean" + }, + "packagePeers": { + "description": "A list of packages that are peer dependencies. Just like `linkType`, this field isn't used by the Plug'n'Play runtime itself, but only by tools that may want to leverage the data file to create a node_modules folder.", + "type": "array", + "items": { + "type": "string" + } + } + } + }] + } + }] + }, + "exampleItems": [ + [null, [ + [null, { + "packageLocation": "./", + "packageDependencies": [ + ["react", "npm:18.0.0"] + ], + "packagePeers": [], + "linkType": "SOFT", + "discardFromLookup": false + }] + ]], + ["react", [ + ["npm:18.0.0", { + "packageLocation": "./.yarn/cache/react-npm-18.0.0-a0b1c2d3.zip", + "packageDependencies": [ + ["react-dom", null] + ], + "packagePeers": [ + "react-dom" + ], + "linkType": "HARD", + "discardFromLookup": false + }] + ]] + ] + } + } +} diff --git a/packages/yarnpkg-cli/sources/tools/getPluginConfiguration.ts b/packages/yarnpkg-cli/sources/tools/getPluginConfiguration.ts index ea588d853a39..95bba319091b 100644 --- a/packages/yarnpkg-cli/sources/tools/getPluginConfiguration.ts +++ b/packages/yarnpkg-cli/sources/tools/getPluginConfiguration.ts @@ -1,4 +1,3 @@ -// @ts-expect-error import packageJson from '@yarnpkg/cli/package.json'; import {PluginConfiguration} from '@yarnpkg/core'; diff --git a/packages/yarnpkg-pnp/sources/generateSerializedState.ts b/packages/yarnpkg-pnp/sources/generateSerializedState.ts index 44c23c310138..081cadb4a9ed 100644 --- a/packages/yarnpkg-pnp/sources/generateSerializedState.ts +++ b/packages/yarnpkg-pnp/sources/generateSerializedState.ts @@ -101,9 +101,7 @@ export function generateSerializedState(settings: PnpSettings): SerializedState // @eslint-ignore-next-line @typescript-eslint/naming-convention __info: [ `This file is automatically generated. Do not touch it, or risk`, - `your modifications being lost. We also recommend you not to read`, - `it either without using the @yarnpkg/pnp package, as the data layout`, - `is entirely unspecified and WILL change from a version to another.`, + `your modifications being lost.`, ], dependencyTreeRoots: settings.dependencyTreeRoots, diff --git a/packages/yarnpkg-pnp/sources/hydratePnpApi.ts b/packages/yarnpkg-pnp/sources/hydratePnpApi.ts index 102acc114d5b..73517cc1d784 100644 --- a/packages/yarnpkg-pnp/sources/hydratePnpApi.ts +++ b/packages/yarnpkg-pnp/sources/hydratePnpApi.ts @@ -1,14 +1,10 @@ import {FakeFS, PortablePath} from '@yarnpkg/fslib'; -import {readFile} from 'fs'; import {dirname} from 'path'; -import {promisify} from 'util'; import {hydrateRuntimeState} from './loader/hydrateRuntimeState'; import {makeApi} from './loader/makeApi'; import {SerializedState} from './types'; -const readFileP = promisify(readFile); - // Note that using those functions is typically NOT needed! The PnP API is // designed to be consumed directly from within Node - meaning that depending // on your situation you probably should use one of those two alternatives @@ -28,8 +24,8 @@ const readFileP = promisify(readFile); // real use case is to access the PnP API without running the risk of executing // third-party Javascript code. -export async function hydratePnpFile(location: string, {fakeFs, pnpapiResolution}: {fakeFs: FakeFS, pnpapiResolution: string}) { - const source = await readFileP(location, `utf8`); +export async function hydratePnpFile(location: PortablePath, {fakeFs, pnpapiResolution}: {fakeFs: FakeFS, pnpapiResolution: string}) { + const source = await fakeFs.readFilePromise(location, `utf8`); return hydratePnpSource(source, { basePath: dirname(location), diff --git a/packages/yarnpkg-pnp/tests/pnpStandardRunner.test.ts b/packages/yarnpkg-pnp/tests/pnpStandardRunner.test.ts new file mode 100644 index 000000000000..fa7bffff98b0 --- /dev/null +++ b/packages/yarnpkg-pnp/tests/pnpStandardRunner.test.ts @@ -0,0 +1,46 @@ +import {Filename, npath, PortablePath, ppath, ZipFS} from '@yarnpkg/fslib'; +import {getLibzipSync} from '@yarnpkg/libzip'; + +import {hydratePnpFile} from '../sources'; + +import expectations from './testExpectations.json'; + +const projectRoot = `/path/to/project` as PortablePath; + +process.env.PNP_DEBUG_LEVEL = `0`; + +for (const {manifest, tests} of expectations) { + const fakeFs = new ZipFS(null, { + libzip: getLibzipSync(), + }); + + fakeFs.mkdirSync(projectRoot, {recursive: true}); + + const pnpApiFile = ppath.join(projectRoot, `.pnp.cjs` as Filename); + fakeFs.writeFileSync(pnpApiFile, `/* something */`); + + const pnpDataFile = ppath.join(projectRoot, `.pnp.data.json` as Filename); + fakeFs.writeJsonSync(pnpDataFile, manifest); + + for (const test of tests) { + it(test.it, async () => { + const pnpApi = await hydratePnpFile(pnpDataFile, {fakeFs, pnpapiResolution: pnpApiFile}); + + const imported = test.imported; + const importer = npath.fromPortablePath(test.importer); + + if (test.expected === `error!`) { + expect(() => { + pnpApi.resolveToUnqualified(imported, importer); + }).toThrow(); + } else { + const resolution = pnpApi.resolveToUnqualified(imported, importer); + const expectation = test.expected !== null + ? npath.fromPortablePath(test.expected as PortablePath) + : null; + + expect(resolution).toEqual(expectation); + } + }); + } +} diff --git a/packages/yarnpkg-pnp/tests/testExpectations.json b/packages/yarnpkg-pnp/tests/testExpectations.json new file mode 100644 index 000000000000..7a44b4339f16 --- /dev/null +++ b/packages/yarnpkg-pnp/tests/testExpectations.json @@ -0,0 +1,311 @@ +[{ + "manifest": { + "__info": [], + "dependencyTreeRoots": [{ + "name": "root", + "reference": "workspace:." + }], + "ignorePatternData": null, + "enableTopLevelFallback": false, + "fallbackPool": [], + "fallbackExclusionList": [], + "packageRegistryData": [ + [null, [ + [null, { + "packageLocation": "./", + "packageDependencies": [], + "linkType": "SOFT" + }] + ]], + ["root", [ + ["workspace:.", { + "packageLocation": "./", + "packageDependencies": [["test", "npm:1.0.0"]], + "linkType": "SOFT" + }] + ]], + ["workspace-alias-dependency", [ + ["workspace:workspace-alias-dependency", { + "packageLocation": "./workspace-alias-dependency/", + "packageDependencies": [["alias", ["test", "npm:1.0.0"]]], + "linkType": "SOFT" + }] + ]], + ["workspace-self-dependency", [ + ["workspace:workspace-self-dependency", { + "packageLocation": "./workspace-self-dependency/", + "packageDependencies": [["workspace-self-dependency", "workspace:workspace-self-dependency"]], + "linkType": "SOFT" + }] + ]], + ["workspace-unfulfilled-peer-dependency", [ + ["workspace:workspace-unfulfilled-peer-dependency", { + "packageLocation": "./workspace-unfulfilled-peer-dependency/", + "packageDependencies": [["test", null]], + "linkType": "SOFT" + }] + ]], + ["longer", [ + ["workspace:longer", { + "packageLocation": "./longer/", + "packageDependencies": [["test", "npm:2.0.0"]], + "linkType": "SOFT" + }] + ]], + ["long", [ + ["workspace:long", { + "packageLocation": "./long/", + "packageDependencies": [["test", "npm:1.0.0"]], + "linkType": "SOFT" + }] + ]], + ["longerer", [ + ["workspace:longerer", { + "packageLocation": "./longerer/", + "packageDependencies": [["test", "npm:3.0.0"]], + "linkType": "SOFT" + }] + ]], + ["test", [ + ["npm:1.0.0", { + "packageLocation": "./test-1.0.0/", + "packageDependencies": [], + "linkType": "HARD" + }], + ["npm:2.0.0", { + "packageLocation": "./test-2.0.0/", + "packageDependencies": [], + "linkType": "HARD" + }], + ["npm:3.0.0", { + "packageLocation": "./test-3.0.0/", + "packageDependencies": [], + "linkType": "HARD" + }] + ]] + ] + }, + "tests": [{ + "it": "should allow a package to import one of its dependencies", + "imported": "test", + "importer": "/path/to/project/", + "expected": "/path/to/project/test-1.0.0/" + }, { + "it": "should allow a package to import itself, if specified in its own dependencies", + "imported": "workspace-self-dependency", + "importer": "/path/to/project/workspace-self-dependency/", + "expected": "/path/to/project/workspace-self-dependency/" + }, { + "it": "should allow a package to import an aliased dependency", + "imported": "alias", + "importer": "/path/to/project/workspace-alias-dependency/", + "expected": "/path/to/project/test-1.0.0/" + }, { + "it": "shouldn't allow a package to import something that isn't one of its dependencies", + "imported": "missing-dependency", + "importer": "/path/to/project/", + "expected": "error!" + }, { + "it": "shouldn't accidentally discard the trailing slash from the package locations", + "imported": "test", + "importer": "/path/to/project/long/", + "expected": "/path/to/project/test-1.0.0/" + }, { + "it": "should throw an exception when trying to access an unfulfilled peer dependency", + "imported": "test", + "importer": "/path/to/project/workspace-unfulfilled-peer-dependency/", + "expected": "error!" + }] +}, { + "manifest": { + "__info": [], + "dependencyTreeRoots": [{ + "name": "root", + "reference": "workspace:." + }], + "ignorePatternData": null, + "enableTopLevelFallback": true, + "fallbackPool": [ + ["test-2", "npm:1.0.0"], + ["alias", ["test-1", "npm:1.0.0"]] + ], + "fallbackExclusionList": [[ + "workspace-no-fallbacks", + ["workspace:workspace-no-fallbacks"] + ]], + "packageRegistryData": [ + [null, [ + [null, { + "packageLocation": "./", + "packageDependencies": [["test-1", "npm:1.0.0"]], + "linkType": "SOFT" + }] + ]], + ["root", [ + ["workspace:.", { + "packageLocation": "./", + "packageDependencies": [["test-1", "npm:1.0.0"]], + "linkType": "SOFT" + }] + ]], + ["workspace-no-fallbacks", [ + ["workspace:workspace-no-fallbacks", { + "packageLocation": "./workspace-no-fallbacks/", + "packageDependencies": [], + "linkType": "SOFT" + }] + ]], + ["workspace-with-fallbacks", [ + ["workspace:workspace-with-fallbacks", { + "packageLocation": "./workspace-with-fallbacks/", + "packageDependencies": [], + "linkType": "SOFT" + }] + ]], + ["workspace-unfulfilled-peer-dependency", [ + ["workspace:workspace-unfulfilled-peer-dependency", { + "packageLocation": "./workspace-unfulfilled-peer-dependency/", + "packageDependencies": [ + ["test-1", null], + ["test-2", null] + ], + "linkType": "SOFT" + }] + ]], + ["test-1", [ + ["npm:1.0.0", { + "packageLocation": "./test-1/", + "packageDependencies": [], + "linkType": "HARD" + }] + ]], + ["test-2", [ + ["npm:1.0.0", { + "packageLocation": "./test-2/", + "packageDependencies": [], + "linkType": "HARD" + }] + ]] + ] + }, + "tests": [{ + "it": "should allow resolution coming from the fallback pool if enableTopLevelFallback is set to true", + "imported": "test-1", + "importer": "/path/to/project/", + "expected": "/path/to/project/test-1/" + }, { + "it": "should allow the fallback pool to contain aliases", + "imported": "alias", + "importer": "/path/to/project/", + "expected": "/path/to/project/test-1/" + }, { + "it": "shouldn't use the fallback pool when the importer package is listed in fallbackExclusionList", + "imported": "test-1", + "importer": "/path/to/project/workspace-no-fallbacks/", + "expected": "error!" + }, { + "it": "should implicitly use the top-level package dependencies as part of the fallback pool", + "imported": "test-2", + "importer": "/path/to/project/workspace-with-fallbacks/", + "expected": "/path/to/project/test-2/" + }, { + "it": "should throw an error if a resolution isn't in in the package dependencies, nor inside the fallback pool", + "imported": "test-3", + "importer": "/path/to/project/workspace-with-fallbacks/", + "expected": "error!" + }, { + "it": "should use the top-level fallback if a dependency is missing because of an unfulfilled peer dependency", + "imported": "test-1", + "importer": "/path/to/project/workspace-unfulfilled-peer-dependency/", + "expected": "/path/to/project/test-1/" + }, { + "it": "should use the fallback pool if a dependency is missing because of an unfulfilled peer dependency", + "imported": "test-2", + "importer": "/path/to/project/workspace-unfulfilled-peer-dependency/", + "expected": "/path/to/project/test-2/" + }] +}, { + "manifest": { + "__info": [], + "dependencyTreeRoots": [{ + "name": "root", + "reference": "workspace:." + }], + "ignorePatternData": null, + "enableTopLevelFallback": false, + "fallbackPool": [ + ["test", "npm:1.0.0"] + ], + "fallbackExclusionList": [], + "packageRegistryData": [ + [null, [ + [null, { + "packageLocation": "./", + "packageDependencies": [], + "linkType": "SOFT" + }] + ]], + ["root", [ + ["workspace:.", { + "packageLocation": "./", + "packageDependencies": [], + "linkType": "SOFT" + }] + ]], + ["test", [ + ["npm:1.0.0", { + "packageLocation": "./test-1/", + "packageDependencies": [], + "linkType": "HARD" + }] + ]] + ] + }, + "tests": [{ + "it": "should ignore the fallback pool if enableTopLevelFallback is set to false", + "imported": "test", + "importer": "/path/to/project/", + "expected": "error!" + }] +}, { + "manifest": { + "__info": [], + "dependencyTreeRoots": [{ + "name": "root", + "reference": "workspace:." + }], + "ignorePatternData": "^not-a-workspace(/|$)", + "enableTopLevelFallback": false, + "fallbackPool": [], + "fallbackExclusionList": [], + "packageRegistryData": [ + [null, [ + [null, { + "packageLocation": "./", + "packageDependencies": [], + "linkType": "SOFT" + }] + ]], + ["root", [ + ["workspace:.", { + "packageLocation": "./", + "packageDependencies": [["test", "npm:1.0.0"]], + "linkType": "SOFT" + }] + ]], + ["test", [ + ["npm:1.0.0", { + "packageLocation": "./test/", + "packageDependencies": [], + "linkType": "HARD" + }] + ]] + ] + }, + "tests": [{ + "it": "shouldn't go through PnP when trying to resolve dependencies from packages covered by ignorePatternData", + "imported": "test", + "importer": "/path/to/project/not-a-workspace/", + "expected": "error!" + }] +}] diff --git a/tsconfig.json b/tsconfig.json index a5f44081329e..a1d91a52a46a 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -8,6 +8,7 @@ "lib": ["ES2019"], "module": "commonjs", "noImplicitReturns": true, + "resolveJsonModule": true, "strict": true, "alwaysStrict": false, "target": "ES2019", diff --git a/yarn.lock b/yarn.lock index 3b60549ad4d8..2f02da8c9a5e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5723,6 +5723,7 @@ __metadata: monaco-editor: ^0.24.0 monaco-editor-webpack-plugin: ^3.1.0 pify: ^4.0.1 + prism-react-renderer: ^1.3.5 prismjs: ^1.23.0 prop-types: ^15.7.2 qs: ^6.7.0 @@ -5733,6 +5734,7 @@ __metadata: react-helmet: ^6.1.0 react-icons: ^3.10.0 react-instantsearch-dom: ^6.6.0 + react-json-doc: ^2.1.0 react-monaco-editor: ^0.36.0 react-responsive-carousel: ^3.2.22 react-scroll-into-view-if-needed: ^2.1.7 @@ -21316,6 +21318,15 @@ pem@dexus/pem: languageName: node linkType: hard +"prism-react-renderer@npm:^1.3.5": + version: 1.3.5 + resolution: "prism-react-renderer@npm:1.3.5" + peerDependencies: + react: ">=0.14.9" + checksum: c18806dcbc4c0b4fd6fd15bd06b4f7c0a6da98d93af235c3e970854994eb9b59e23315abb6cfc29e69da26d36709a47e25da85ab27fed81b6812f0a52caf6dfa + languageName: node + linkType: hard + "prismjs@npm:^1.23.0": version: 1.23.0 resolution: "prismjs@npm:1.23.0" @@ -22037,6 +22048,15 @@ pem@dexus/pem: languageName: node linkType: hard +"react-json-doc@npm:^2.1.0": + version: 2.3.4 + resolution: "react-json-doc@npm:2.3.4" + peerDependencies: + react: "*" + checksum: 8d0e330d4c017ff11c16b222f7d66d6b0bd2eace6b7911a62637985a3213c463d9ef23b60169438102ab2fd540f4957a9b50c602d02d8166aa9baa5da9bb70ba + languageName: node + linkType: hard + "react-lifecycles-compat@npm:^3.0.4": version: 3.0.4 resolution: "react-lifecycles-compat@npm:3.0.4"