From d9f85cb45978c18632d10b9e9aaf508d23734586 Mon Sep 17 00:00:00 2001 From: ump45nose Date: Mon, 5 Oct 2026 04:04:34 +0800 Subject: [PATCH 1/2] docs(arborist): describe yarn and pnpm lockfile support The arborist package description mentioned `yarn.lock` once, inside a usage code comment, and did not mention pnpm at all, so the level of support Arborist has for other package managers was unclear. Add a `SUPPORTED LOCKFILES` section to the arborist README summarizing the level of support, and a new `workspaces/arborist/docs/lockfiles.md` page with the details: `yarn.lock` is read and written but only as a metadata source, and `pnpm-lock.yaml` is not handled at all. Closes: https://github.com/npm/cli/issues/7765 --- workspaces/arborist/README.md | 12 +++++++ workspaces/arborist/docs/lockfiles.md | 48 +++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 workspaces/arborist/docs/lockfiles.md diff --git a/workspaces/arborist/README.md b/workspaces/arborist/README.md index 7263a83f6b31b..90170b295af5e 100644 --- a/workspaces/arborist/README.md +++ b/workspaces/arborist/README.md @@ -11,6 +11,18 @@ Inspect and manage `node_modules` trees. There's more documentation [in the docs folder](https://github.com/npm/cli/tree/latest/workspaces/arborist/docs). +## SUPPORTED LOCKFILES + +Arborist's primary lockfile is `package-lock.json`, which it reads and writes +as it builds and saves a tree. + +A `yarn.lock` file is also read and written, but only as a source of metadata +rather than a full description of the tree. See +[lockfiles.md](docs/lockfiles.md) for the level of support and its caveats. + +`pnpm-lock.yaml` is neither read nor written, and there is no other pnpm +integration. + ## USAGE ```js diff --git a/workspaces/arborist/docs/lockfiles.md b/workspaces/arborist/docs/lockfiles.md new file mode 100644 index 0000000000000..2e85a5df401b6 --- /dev/null +++ b/workspaces/arborist/docs/lockfiles.md @@ -0,0 +1,48 @@ +# lockfiles + +`package-lock.json` is the lockfile that Arborist reads and writes. It is +loaded by `Shrinkwrap.load()`, which reads it along with any `yarn.lock` in the +same directory, and it is written back by `Shrinkwrap.save()`. + +Two other package managers are involved to a lesser degree, described below. + +## yarn v1 + +A `yarn.lock` file is parsed into a `YarnLock` object, and is written back out +when a tree is saved. It is used as a source of metadata, not as a description +of the tree. + +Yarn entries supply `resolved`, `integrity`, and `version` metadata that a +`package-lock.json` would otherwise have to provide. That metadata is consumed +when building the ideal tree and when loading the actual tree. + +On save, if the yarn lock has any entries it is rewritten to `yarn.lock` in the +project root. A `yarn.lock` file is never created when one did not already +exist. + +### Caveats + +- Yarn entries are only consulted when no `package-lock.json` was loaded from + disk. Arborist always prefers the package-lock when one is present and + readable, so the yarn entries are effectively a fallback for projects that + have a `yarn.lock` but no `package-lock.json`. +- Only the yarn v1 lockfile format is handled. The parser writes and expects + the `# yarn lockfile v1` header, so Yarn Berry (v2+) lockfiles are not + supported. +- The parser only supports a single layer of nested objects. +- A `yarn.lock` file is not sufficient on its own. It does not define the + shape of the tree, so `loadVirtual()` still requires a `package-lock.json` + or a `package.json` to be present. +- Yarn data that fails to parse is ignored, and is likely to be overwritten on + the next save. + +## pnpm + +There is no pnpm support in Arborist. `pnpm-lock.yaml` is neither read nor +written, and Arborist does not create or consume pnpm's isolated +`node_modules` layout. + +The closest thing to pnpm handling is the `test/fixtures/pnpm` test fixture, +whose `package-lock.json` describes a `node_modules/.pnpm` virtual store. It +exists to exercise Arborist's link and `fsParent` resolution against a +pnpm-shaped layout, and is not a statement of pnpm lockfile support. From d44669221bd75babf31faf8fc9ac1dfd9cec0f0d Mon Sep 17 00:00:00 2001 From: ump45nose <52391318+ump45nose@users.noreply.github.com> Date: Fri, 23 Oct 2026 09:49:15 +0800 Subject: [PATCH 2/2] docs: use one sentence per line in added prose Apply the Markdown conventions from #10108 to this PR's new text only. Preserve wording, links, paragraph boundaries, and Markdown structure. Validation: rendered HTML equivalence (whitespace-normalized), text and scope assertions, and whitespace checks. Full npm/docs tests not run locally. AI-assisted formatting update. --- workspaces/arborist/README.md | 11 +++--- workspaces/arborist/docs/lockfiles.md | 50 ++++++++++----------------- 2 files changed, 23 insertions(+), 38 deletions(-) diff --git a/workspaces/arborist/README.md b/workspaces/arborist/README.md index 90170b295af5e..0bc4205a7edf7 100644 --- a/workspaces/arborist/README.md +++ b/workspaces/arborist/README.md @@ -13,15 +13,12 @@ folder](https://github.com/npm/cli/tree/latest/workspaces/arborist/docs). ## SUPPORTED LOCKFILES -Arborist's primary lockfile is `package-lock.json`, which it reads and writes -as it builds and saves a tree. +Arborist's primary lockfile is `package-lock.json`, which it reads and writes as it builds and saves a tree. -A `yarn.lock` file is also read and written, but only as a source of metadata -rather than a full description of the tree. See -[lockfiles.md](docs/lockfiles.md) for the level of support and its caveats. +A `yarn.lock` file is also read and written, but only as a source of metadata rather than a full description of the tree. +See [lockfiles.md](docs/lockfiles.md) for the level of support and its caveats. -`pnpm-lock.yaml` is neither read nor written, and there is no other pnpm -integration. +`pnpm-lock.yaml` is neither read nor written, and there is no other pnpm integration. ## USAGE diff --git a/workspaces/arborist/docs/lockfiles.md b/workspaces/arborist/docs/lockfiles.md index 2e85a5df401b6..150bf7b738e74 100644 --- a/workspaces/arborist/docs/lockfiles.md +++ b/workspaces/arborist/docs/lockfiles.md @@ -1,48 +1,36 @@ # lockfiles -`package-lock.json` is the lockfile that Arborist reads and writes. It is -loaded by `Shrinkwrap.load()`, which reads it along with any `yarn.lock` in the -same directory, and it is written back by `Shrinkwrap.save()`. +`package-lock.json` is the lockfile that Arborist reads and writes. +It is loaded by `Shrinkwrap.load()`, which reads it along with any `yarn.lock` in the same directory, and it is written back by `Shrinkwrap.save()`. Two other package managers are involved to a lesser degree, described below. ## yarn v1 -A `yarn.lock` file is parsed into a `YarnLock` object, and is written back out -when a tree is saved. It is used as a source of metadata, not as a description -of the tree. +A `yarn.lock` file is parsed into a `YarnLock` object, and is written back out when a tree is saved. +It is used as a source of metadata, not as a description of the tree. -Yarn entries supply `resolved`, `integrity`, and `version` metadata that a -`package-lock.json` would otherwise have to provide. That metadata is consumed -when building the ideal tree and when loading the actual tree. +Yarn entries supply `resolved`, `integrity`, and `version` metadata that a `package-lock.json` would otherwise have to provide. +That metadata is consumed when building the ideal tree and when loading the actual tree. -On save, if the yarn lock has any entries it is rewritten to `yarn.lock` in the -project root. A `yarn.lock` file is never created when one did not already -exist. +On save, if the yarn lock has any entries it is rewritten to `yarn.lock` in the project root. +A `yarn.lock` file is never created when one did not already exist. ### Caveats -- Yarn entries are only consulted when no `package-lock.json` was loaded from - disk. Arborist always prefers the package-lock when one is present and - readable, so the yarn entries are effectively a fallback for projects that - have a `yarn.lock` but no `package-lock.json`. -- Only the yarn v1 lockfile format is handled. The parser writes and expects - the `# yarn lockfile v1` header, so Yarn Berry (v2+) lockfiles are not - supported. +- Yarn entries are only consulted when no `package-lock.json` was loaded from disk. + Arborist always prefers the package-lock when one is present and readable, so the yarn entries are effectively a fallback for projects that have a `yarn.lock` but no `package-lock.json`. +- Only the yarn v1 lockfile format is handled. + The parser writes and expects the `# yarn lockfile v1` header, so Yarn Berry (v2+) lockfiles are not supported. - The parser only supports a single layer of nested objects. -- A `yarn.lock` file is not sufficient on its own. It does not define the - shape of the tree, so `loadVirtual()` still requires a `package-lock.json` - or a `package.json` to be present. -- Yarn data that fails to parse is ignored, and is likely to be overwritten on - the next save. +- A `yarn.lock` file is not sufficient on its own. + It does not define the shape of the tree, so `loadVirtual()` still requires a `package-lock.json` or a `package.json` to be present. +- Yarn data that fails to parse is ignored, and is likely to be overwritten on the next save. ## pnpm -There is no pnpm support in Arborist. `pnpm-lock.yaml` is neither read nor -written, and Arborist does not create or consume pnpm's isolated -`node_modules` layout. +There is no pnpm support in Arborist. +`pnpm-lock.yaml` is neither read nor written, and Arborist does not create or consume pnpm's isolated `node_modules` layout. -The closest thing to pnpm handling is the `test/fixtures/pnpm` test fixture, -whose `package-lock.json` describes a `node_modules/.pnpm` virtual store. It -exists to exercise Arborist's link and `fsParent` resolution against a -pnpm-shaped layout, and is not a statement of pnpm lockfile support. +The closest thing to pnpm handling is the `test/fixtures/pnpm` test fixture, whose `package-lock.json` describes a `node_modules/.pnpm` virtual store. +It exists to exercise Arborist's link and `fsParent` resolution against a pnpm-shaped layout, and is not a statement of pnpm lockfile support.