[pull] latest from npm:latest#219
Merged
Merged
Conversation
…irs (#9586) Implements the accepted RFC [npm/rfcs#903](npm/rfcs#903): a root-owned `.npm-extension.mjs` / `.npm-extension.cjs` file exporting `transformManifest(pkg, context)` that imperatively repairs third-party dependency manifests **before** Arborist finalizes the ideal tree. It is the imperative counterpart to [`packageExtensions` (#9496)](#9496) and operates in the same pre-resolution phase, running **before** `packageExtensions`. ```js // .npm-extension.mjs export function transformManifest(pkg, context) { if (pkg.name === "foo" && pkg.version.startsWith("1.")) { pkg.dependencies = { ...pkg.dependencies, bar: "^2.0.0" }; context.log("added bar to foo@1"); } return pkg; } ``` ## Why `packageExtensions` is declarative JSON: it cannot carry comments or issue links, repeats itself across many packages, is add-only, and lives in `package.json` (so public packages cannot publish while it is present). `.npm-extension` covers the gap for advanced projects that need conditional repairs, deletion, range rewrites, repeated rules expressed as code, stale-repair guards, and a policy location outside the published manifest. ## What it does - **Discovery** — one root `.npm-extension.mjs` or `.npm-extension.cjs` (both present is an error). The `extension-file` config overrides discovery with a project-local path that must resolve inside the project root and use `.mjs`/`.cjs`. - **`transformManifest(pkg, context)`** — receives a deeply isolated copy of the normalized manifest; `context` exposes `log`, `root`, and `extensionPoint`. Must return a manifest synchronously; `null`/primitive/array/promise returns and throws fail the install with a `.npm-extension`-named error. - **Allowlist** — only `dependencies`, `optionalDependencies`, `peerDependencies`, and `peerDependenciesMeta` may change (add, replace, or delete). Any other changed field (`scripts`, `bin`, …) is rejected. pacote's cached manifest is never mutated. - **Caching** — runs at most once per resolved package identity (integrity, else resolved source + name@version); the entry file is hash-keyed so a changed file is reloaded rather than served stale from the module cache. - **Lockfile** — the root entry records `npmExtensionHash` (a format-tagged digest of the file bytes); affected entries record minimal `npmExtensionApplied` provenance. Extension state reuses the existing `lockfileVersion: 4` threshold. - **Re-resolution** — changing or removing the file re-resolves the affected packages on the next `npm install`, reverting transforms that no longer apply. - **`npm ci`** — never imports or executes the file; it validates the recorded hash and reifies the locked graph (which already carries the extension-influenced edges). - **Configs** — `ignore-extension` disables import/execution; `ignore-scripts` implies it; `extension-file` is honored only from project config or the command line, never from user/global/builtin sources. - **Workspaces** — a `.npm-extension` file in a non-root workspace is ignored with a warning; only the workspace root's file is honored. - **Visibility** — `npm explain` annotates extension-changed edges and `npm ls` (human + `--json`) surfaces the provenance. - **Publish** — companion change in `npm-packlist` force-excludes root `.npm-extension.{mjs,cjs}` from package tarballs. ## Companion change Requires [npm/npm-packlist#294](npm/npm-packlist#294) to exclude root `.npm-extension.{mjs,cjs}` from tarballs. `pacote`/CLI will pick this up via a version bump once that publishes. ## Notes / out of scope for this PR One item is deferred for a genuine structural reason the RFC itself flags: - **Local `file:`/`link:`/directory sources.** `transformManifest` applies to fetched manifests (registry, git, remote tarball, `file:` tarballs) and is re-derived on the installed tree across all install strategies including `install-strategy=linked`. It is **not yet** applied to local sources that create `Link` nodes directly and bypass the fetch phase — the RFC flags this as net-new wiring ("npm must add an analogous pre-edge-read transform path for the `Link` target"). Follow-up. ## References Implements npm/rfcs#903 Builds on #9496 Companion: npm/npm-packlist#294
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See Commits and Changes for more details.
Created by
pull[bot] (v2.0.0-alpha.4)
Can you help keep this open source service alive? 💖 Please sponsor : )