@_linked/cli 1.41.0 → 1.42.0

package/lib/esm/localize/prune.js

@@ -0,0 +1,390 @@
+/**
+ * Pruning -- stop a checkout's own `node_modules` holding a second copy of
+ * something the app already provides. On by default after every install in a
+ * checkout and on every `--relink`; `--no-prune` (`{prune: false}`) skips it.
+ *
+ * `shouldPrune(opts)` is the one place that default lives.
+ *
+ * Why it is needed. `npm install` inside a checkout (localize.ts, step 3)
+ * installs what the CHECKOUT's lockfile says: its own copy of every
+ * dependency, often older than the app's. Node resolves a module from the
+ * importer's REAL path and takes the first `node_modules` it meets going up,
+ * so a localized `A` that imports `B` gets `A/node_modules/B` -- a registry
+ * copy -- and never the localized `B`; and a framework package that holds a
+ * registry of classes (or React) loads once per copy. Measured with three
+ * localized `@_linked/*` packages: plain Node and `tsx` loaded three copies of
+ * the same core.
+ *
+ * What it does. For every localized checkout, each package at the top of its
+ * `node_modules` that is a CANDIDATE (below) is removed when the app provides
+ * it -- `<appRoot>/node_modules/<name>` exists -- at a version that satisfies
+ * every range that resolves to that copy: the checkout's own declaration and
+ * that of every installed package that would load it. Node's upward search
+ * then finds the app's copy instead. Nothing else in the checkout moves.
+ *
+ * The candidates are `providedPackages` (provided.ts) -- the one rule the
+ * run-time check and Vite's dedupe use too -- over the entries being pruned:
+ *
+ * - a **localized sibling** -- always counts as provided, whatever the range,
+ *   because the live checkout is the point of localizing it. A range it does
+ *   not satisfy is said out loud, never acted on;
+ * - a **runtime dependency** (`dependencies`, `peerDependencies`,
+ *   `optionalDependencies`) of any localized checkout that the app has at a
+ *   version satisfying every localized checkout's range for it;
+ * - `react` and `react-dom`.
+ *
+ * Nothing else is touched -- a devDependency the app happens to have too
+ * stays, so the checkout's tooling does not come to depend on the app's. A
+ * runtime dependency the rule leaves out because a localized range misses the
+ * app's version is kept and said out loud, like any other copy kept below.
+ *
+ * Never removed, candidate or not:
+ *
+ * - a copy whose ranges the app's version does not satisfy -- kept, with a
+ *   warning naming the package, the range and the app's version;
+ * - anything in a checkout that is not under the app root, because then the
+ *   upward search never reaches the app's `node_modules` and the removed
+ *   package would simply be missing.
+ *
+ * A package with a `bin` is NOT exempt. Measured in a checkout under an app
+ * root with its own `@_linked/cli` removed: `npx linked build`,
+ * `npm exec linked -- --help`, a script running `npm exec linked` and a script
+ * running a bare `linked` all resolved `linked` to the app root's copy,
+ * because npm puts every ancestor's `node_modules/.bin` on the PATH. The
+ * removed package's links in the checkout's `node_modules/.bin` are removed
+ * with it, so nothing dangles.
+ *
+ * It never runs npm and never touches the checkout's `package.json` or
+ * `package-lock.json`. `npm install` in the checkout puts the copies back;
+ * `ensure` (ensure.ts) is the install-then-prune step every in-checkout
+ * install goes through, and the run-time check (`checkOneCopy`) takes them out
+ * again before `linked start` and friends.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isInside, isSymlink, readJson } from './fsops.js';
+import semver from 'semver';
+import { providedPackages } from './provided.js';
+/** The candidates for `entries`, by `providedPackages` (provided.ts). */
+export function candidatesFor(entries, deps) {
+    const rule = providedPackages(deps.appRoot, Object.keys(entries));
+    return {
+        names: new Set([...rule.names, ...Object.keys(entries)]),
+        skipped: new Map(rule.skipped.map((s) => [s.name, s])),
+    };
+}
+/**
+ * Does the app's installed `version` satisfy `range`? `null` means "cannot
+ * tell" -- a dist-tag, `file:`, `npm:`, `workspace:`, a git URL, or a version
+ * that is not one -- and every caller then keeps the copy. The failure mode is
+ * therefore always the safe one: a copy kept that could have gone, never a
+ * copy removed that was needed.
+ *
+ * npm's own `semver` decides, so prereleases follow npm's rule: `1.3.0-beta.1`
+ * satisfies a range only when one of its comparators names a prerelease on
+ * the same `major.minor.patch`.
+ */
+export function satisfies(version, range) {
+    if (typeof version !== 'string' || typeof range !== 'string')
+        return null;
+    if (semver.valid(version) === null)
+        return null;
+    if (semver.validRange(range) === null)
+        return null;
+    return semver.satisfies(version, range);
+}
+/** Pruning is on unless a caller says `{prune: false}`. */
+export function shouldPrune(opts = {}) {
+    return opts.prune !== false;
+}
+const REQUIRE_FIELDS = [
+    'dependencies',
+    'peerDependencies',
+    'optionalDependencies',
+];
+const DECLARE_FIELDS = [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+];
+/**
+ * @param entries  the localized packages: every one counts as a sibling
+ * @param opts  unused beyond `prune`, which callers check with `shouldPrune`
+ * @param deps  `{appRoot, log, warn}`
+ * @param scope  prune only some checkouts / names (the run-time check)
+ */
+export function pruneProvided(entries, opts, deps, scope = {}) {
+    var _a;
+    const removed = [];
+    const kept = [];
+    const appRoot = realOrSelf(deps.appRoot);
+    const candidates = candidatesFor(entries, deps);
+    const only = scope.deps ? new Set(scope.deps) : null;
+    for (const [name, entry] of Object.entries(entries)) {
+        if (scope.owners && !scope.owners.includes(name))
+            continue;
+        const pkgDir = path.join(deps.appRoot, entry.path);
+        if (!fs.existsSync(path.join(pkgDir, 'package.json')))
+            continue;
+        if (!isInside(realOrSelf(pkgDir), appRoot)) {
+            deps.log(`[localize] ${name}: ${entry.path} is outside the app root, so Node cannot reach the app's ` +
+                `node_modules from it — its own dependencies are left as they are.`);
+            continue;
+        }
+        const ctx = {
+            name,
+            entry,
+            pkgDir,
+            pkg: (_a = readJson(path.join(pkgDir, 'package.json'))) !== null && _a !== void 0 ? _a : {},
+            entries,
+            candidates,
+            only,
+            deps,
+        };
+        for (const nm of nodeModulesRoots(pkgDir, entry)) {
+            const result = pruneOne(nm, ctx);
+            removed.push(...result.removed);
+            kept.push(...result.kept);
+        }
+    }
+    report(removed, kept, deps);
+    return { removed, kept };
+}
+/**
+ * Is `dep` -- declared by a checkout at `range` -- something the app provides,
+ * so that its absence from the checkout's own `node_modules` is not a
+ * dependency gone missing? `--relink` asks this before reinstalling a
+ * checkout, so a copy pruned on purpose does not trigger a reinstall on every
+ * postinstall.
+ */
+export function isProvidedByApp(dep, range, entries, candidates, deps) {
+    const app = appCopy(dep, deps);
+    if (!app)
+        return false;
+    if (entries[dep])
+        return true;
+    if (!candidates.names.has(dep))
+        return false;
+    return range === undefined || satisfies(app.version, range) === true;
+}
+function pruneOne(nm, ctx) {
+    const removed = [];
+    const kept = [];
+    const { name: owner, entry, pkg, entries, candidates, only, deps } = ctx;
+    for (const dep of topLevelPackages(nm)) {
+        if (dep === owner)
+            continue;
+        if (only && !only.has(dep))
+            continue;
+        const skip = candidates.skipped.get(dep);
+        if (!candidates.names.has(dep) && !skip)
+            continue;
+        const dir = path.join(nm, dep);
+        const nested = readJson(path.join(dir, 'package.json'));
+        if (!nested)
+            continue;
+        const app = appCopy(dep, deps);
+        if (!app)
+            continue; // the app does not provide it, so this copy is the only one
+        if (realOrSelf(dir) === app.real)
+            continue; // already the app's copy
+        const where = path.relative(deps.appRoot, dir);
+        if (!candidates.names.has(dep)) {
+            // The rule leaves it out: a localized checkout asks a range the app
+            // misses. Said for a checkout that declares it; a copy it only has
+            // transitively is none of its business.
+            if (declared(pkg, DECLARE_FIELDS, dep) === undefined)
+                continue;
+            kept.push({
+                where,
+                dep,
+                version: nested.version,
+                app: app.version,
+                unmet: skip.asks,
+                owner: entry.path,
+            });
+            continue;
+        }
+        const sibling = Boolean(entries[dep]);
+        const ranges = rangesResolvingTo(nm, dep, pkg, owner);
+        if (!sibling) {
+            const unmet = ranges.filter((r) => satisfies(app.version, r.range) !== true);
+            if (unmet.length) {
+                kept.push({
+                    where,
+                    dep,
+                    version: nested.version,
+                    app: app.version,
+                    unmet,
+                    owner: entry.path,
+                });
+                continue;
+            }
+        }
+        fs.rmSync(dir, { recursive: true, force: true });
+        removeEmptyScope(nm, dep);
+        removeBinLinksInto(nm, dir);
+        removed.push({
+            owner: entry.path,
+            dep,
+            version: nested.version,
+            app: app.version,
+            sibling,
+            drift: sibling
+                ? ranges.filter((r) => satisfies(app.version, r.range) === false)
+                : [],
+        });
+    }
+    return { removed, kept };
+}
+function report(removed, kept, deps) {
+    var _a;
+    const byOwner = new Map();
+    for (const r of removed)
+        byOwner.set(r.owner, [...((_a = byOwner.get(r.owner)) !== null && _a !== void 0 ? _a : []), r]);
+    for (const [owner, list] of byOwner) {
+        deps.log(`[localize] ${owner}: removed its own copies of what the app provides — ` +
+            list
+                .map((r) => `${r.dep}@${r.version} (app: ${r.sibling ? `localized, ${r.app}` : r.app})`)
+                .join(', '));
+        for (const r of list) {
+            for (const d of r.drift) {
+                deps.warn(`[localize] ${owner}: ${d.from} asks ${r.dep}@${d.range}; the localized checkout is ${r.app}. ` +
+                    `It is used anyway — that is what localizing it means — but the range is now fiction.`);
+            }
+        }
+    }
+    for (const k of kept) {
+        deps.warn(`[localize] kept ${k.where}@${k.version}: ` +
+            k.unmet.map((u) => `${u.from} asks ${k.dep}@${u.range}`).join(', ') +
+            `, and the app has ${k.dep}@${k.app}${k.unmet.some((u) => satisfies(k.app, u.range) === null)
+                ? ' (or the range is one localize cannot read)'
+                : ''}. ` +
+            `${k.owner} loads its own copy, so the app loads two. Align the ranges, or update the app's ${k.dep}.`);
+    }
+}
+/**
+ * Every range that resolves to `<nm>/<dep>`: the checkout's own declaration,
+ * plus each installed package under `nm` that requires `dep` and has no copy
+ * of its own between itself and `nm`.
+ */
+function rangesResolvingTo(nm, dep, checkoutPkg, owner) {
+    const out = [];
+    const own = declared(checkoutPkg, DECLARE_FIELDS, dep);
+    if (own !== undefined)
+        out.push({ from: owner, range: own });
+    const walk = (dir, chain) => {
+        for (const name of topLevelPackages(dir)) {
+            const pkgDir = path.join(dir, name);
+            if (isSymlink(pkgDir))
+                continue; // resolves from its real path, which is not here
+            const pkg = readJson(path.join(pkgDir, 'package.json'));
+            const range = pkg && name !== dep ? declared(pkg, REQUIRE_FIELDS, dep) : undefined;
+            const inner = path.join(pkgDir, 'node_modules');
+            const shadowed = [...chain, inner].some((d) => fs.existsSync(path.join(d, dep)));
+            if (range !== undefined && !shadowed)
+                out.push({ from: `${name}@${pkg.version}`, range });
+            if (fs.existsSync(inner))
+                walk(inner, [...chain, inner]);
+        }
+    };
+    walk(nm, []);
+    return out;
+}
+function declared(pkg, fields, dep) {
+    var _a;
+    for (const f of fields)
+        if (((_a = pkg[f]) === null || _a === void 0 ? void 0 : _a[dep]) !== undefined)
+            return pkg[f][dep];
+    return undefined;
+}
+/** The app's own copy of `dep`: `<appRoot>/node_modules/<dep>`, followed through a link. */
+function appCopy(dep, deps) {
+    const dir = path.join(deps.appRoot, 'node_modules', dep);
+    const pkg = readJson(path.join(dir, 'package.json'));
+    if (!(pkg === null || pkg === void 0 ? void 0 : pkg.version))
+        return null;
+    return { version: pkg.version, real: realOrSelf(dir) };
+}
+/** The package dir's `node_modules`, and the clone root's when the package is a monorepo subdir. */
+export function nodeModulesRoots(pkgDir, entry) {
+    const roots = [path.join(pkgDir, 'node_modules')];
+    if (entry.subdir) {
+        const rel = path.normalize(entry.subdir);
+        if (pkgDir.endsWith(path.sep + rel))
+            roots.push(path.join(pkgDir.slice(0, -(rel.length + 1)), 'node_modules'));
+    }
+    return roots.filter((d) => fs.existsSync(d));
+}
+/** Package names directly under a `node_modules`, scoped ones as `@scope/name`. */
+function topLevelPackages(nm) {
+    const out = [];
+    let items;
+    try {
+        items = fs.readdirSync(nm, { withFileTypes: true });
+    }
+    catch (_a) {
+        return out;
+    }
+    for (const item of items) {
+        if (item.name.startsWith('.'))
+            continue;
+        if (item.name.startsWith('@')) {
+            let inner = [];
+            try {
+                inner = fs.readdirSync(path.join(nm, item.name));
+            }
+            catch (_b) {
+                /* not a directory */
+            }
+            for (const sub of inner)
+                if (!sub.startsWith('.'))
+                    out.push(`${item.name}/${sub}`);
+        }
+        else {
+            out.push(item.name);
+        }
+    }
+    return out;
+}
+/** Links in `<nm>/.bin` that pointed into a package just removed: dangling now. */
+function removeBinLinksInto(nm, removedDir) {
+    const bin = path.join(nm, '.bin');
+    let names;
+    try {
+        names = fs.readdirSync(bin);
+    }
+    catch (_a) {
+        return;
+    }
+    for (const name of names) {
+        const link = path.join(bin, name);
+        if (!isSymlink(link))
+            continue;
+        const target = path.resolve(bin, fs.readlinkSync(link));
+        if (isInside(target, removedDir))
+            fs.unlinkSync(link);
+    }
+}
+function removeEmptyScope(nm, dep) {
+    if (!dep.startsWith('@'))
+        return;
+    const scope = path.join(nm, dep.split('/')[0]);
+    try {
+        if (!fs.readdirSync(scope).length)
+            fs.rmdirSync(scope);
+    }
+    catch (_a) {
+        /* already gone */
+    }
+}
+export function realOrSelf(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch (_a) {
+        return p;
+    }
+}
+//# sourceMappingURL=prune.js.map

package/lib/esm/localize/prune.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.js","sourceRoot":"","sources":["../../../src/localize/prune.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Pruning -- stop a checkout's own `node_modules` holding a second copy of\n * something the app already provides. On by default after every install in a\n * checkout and on every `--relink`; `--no-prune` (`{prune: false}`) skips it.\n *\n * `shouldPrune(opts)` is the one place that default lives.\n *\n * Why it is needed. `npm install` inside a checkout (localize.ts, step 3)\n * installs what the CHECKOUT's lockfile says: its own copy of every\n * dependency, often older than the app's. Node resolves a module from the\n * importer's REAL path and takes the first `node_modules` it meets going up,\n * so a localized `A` that imports `B` gets `A/node_modules/B` -- a registry\n * copy -- and never the localized `B`; and a framework package that holds a\n * registry of classes (or React) loads once per copy. Measured with three\n * localized `@_linked/*` packages: plain Node and `tsx` loaded three copies of\n * the same core.\n *\n * What it does. For every localized checkout, each package at the top of its\n * `node_modules` that is a CANDIDATE (below) is removed when the app provides\n * it -- `<appRoot>/node_modules/<name>` exists -- at a version that satisfies\n * every range that resolves to that copy: the checkout's own declaration and\n * that of every installed package that would load it. Node's upward search\n * then finds the app's copy instead. Nothing else in the checkout moves.\n *\n * The candidates are `providedPackages` (provided.ts) -- the one rule the\n * run-time check and Vite's dedupe use too -- over the entries being pruned:\n *\n * - a **localized sibling** -- always counts as provided, whatever the range,\n *   because the live checkout is the point of localizing it. A range it does\n *   not satisfy is said out loud, never acted on;\n * - a **runtime dependency** (`dependencies`, `peerDependencies`,\n *   `optionalDependencies`) of any localized checkout that the app has at a\n *   version satisfying every localized checkout's range for it;\n * - `react` and `react-dom`.\n *\n * Nothing else is touched -- a devDependency the app happens to have too\n * stays, so the checkout's tooling does not come to depend on the app's. A\n * runtime dependency the rule leaves out because a localized range misses the\n * app's version is kept and said out loud, like any other copy kept below.\n *\n * Never removed, candidate or not:\n *\n * - a copy whose ranges the app's version does not satisfy -- kept, with a\n *   warning naming the package, the range and the app's version;\n * - anything in a checkout that is not under the app root, because then the\n *   upward search never reaches the app's `node_modules` and the removed\n *   package would simply be missing.\n *\n * A package with a `bin` is NOT exempt. Measured in a checkout under an app\n * root with its own `@_linked/cli` removed: `npx linked build`,\n * `npm exec linked -- --help`, a script running `npm exec linked` and a script\n * running a bare `linked` all resolved `linked` to the app root's copy,\n * because npm puts every ancestor's `node_modules/.bin` on the PATH. The\n * removed package's links in the checkout's `node_modules/.bin` are removed\n * with it, so nothing dangles.\n *\n * It never runs npm and never touches the checkout's `package.json` or\n * `package-lock.json`. `npm install` in the checkout puts the copies back;\n * `ensure` (ensure.ts) is the install-then-prune step every in-checkout\n * install goes through, and the run-time check (`checkOneCopy`) takes them out\n * again before `linked start` and friends.\n */\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport {isInside, isSymlink, readJson} from './fsops.js';\nimport semver from 'semver';\nimport {providedPackages} from './provided.js';\nimport type {ProvidedSkip} from './provided.js';\n\nimport type {ManifestEntry} from './manifest.js';\nimport type {Deps} from './run.js';\n\n/** What pruning reads from a command's options. */\nexport interface PruneOptions {\n  /** On unless explicitly false. */\n  prune?: boolean;\n}\n\n/** Limit a prune to some checkouts and/or some dependency names. */\nexport interface PruneScope {\n  /** Only these localized packages' checkouts. */\n  owners?: string[];\n  /** Only these dependency names. */\n  deps?: string[];\n}\n\n/** What pruning may remove: the rule's names plus every localized sibling, and what the rule skipped. */\nexport interface Candidates {\n  names: Set<string>;\n  skipped: Map<string, ProvidedSkip>;\n}\n\n/** The candidates for `entries`, by `providedPackages` (provided.ts). */\nexport function candidatesFor(\n  entries: Record<string, ManifestEntry>,\n  deps: Pick<Deps, 'appRoot'>,\n): Candidates {\n  const rule = providedPackages(deps.appRoot, Object.keys(entries));\n  return {\n    names: new Set([...rule.names, ...Object.keys(entries)]),\n    skipped: new Map(rule.skipped.map((s) => [s.name, s])),\n  };\n}\n\n/**\n * Does the app's installed `version` satisfy `range`? `null` means \"cannot\n * tell\" -- a dist-tag, `file:`, `npm:`, `workspace:`, a git URL, or a version\n * that is not one -- and every caller then keeps the copy. The failure mode is\n * therefore always the safe one: a copy kept that could have gone, never a\n * copy removed that was needed.\n *\n * npm's own `semver` decides, so prereleases follow npm's rule: `1.3.0-beta.1`\n * satisfies a range only when one of its comparators names a prerelease on\n * the same `major.minor.patch`.\n */\nexport function satisfies(version: string, range: string): boolean | null {\n  if (typeof version !== 'string' || typeof range !== 'string') return null;\n  if (semver.valid(version) === null) return null;\n  if (semver.validRange(range) === null) return null;\n  return semver.satisfies(version, range);\n}\n\n/** Pruning is on unless a caller says `{prune: false}`. */\nexport function shouldPrune(opts: PruneOptions = {}): boolean {\n  return opts.prune !== false;\n}\n\nconst REQUIRE_FIELDS = [\n  'dependencies',\n  'peerDependencies',\n  'optionalDependencies',\n];\nconst DECLARE_FIELDS = [\n  'dependencies',\n  'devDependencies',\n  'peerDependencies',\n  'optionalDependencies',\n];\n\n/**\n * @param entries  the localized packages: every one counts as a sibling\n * @param opts  unused beyond `prune`, which callers check with `shouldPrune`\n * @param deps  `{appRoot, log, warn}`\n * @param scope  prune only some checkouts / names (the run-time check)\n */\nexport function pruneProvided(\n  entries: Record<string, ManifestEntry>,\n  opts: PruneOptions,\n  deps: Pick<Deps, 'appRoot' | 'log' | 'warn'>,\n  scope: PruneScope = {},\n): {removed: any[]; kept: any[]} {\n  const removed: any[] = [];\n  const kept: any[] = [];\n  const appRoot = realOrSelf(deps.appRoot);\n  const candidates = candidatesFor(entries, deps);\n  const only = scope.deps ? new Set(scope.deps) : null;\n\n  for (const [name, entry] of Object.entries(entries)) {\n    if (scope.owners && !scope.owners.includes(name)) continue;\n    const pkgDir = path.join(deps.appRoot, entry.path);\n    if (!fs.existsSync(path.join(pkgDir, 'package.json'))) continue;\n    if (!isInside(realOrSelf(pkgDir), appRoot)) {\n      deps.log(\n        `[localize] ${name}: ${entry.path} is outside the app root, so Node cannot reach the app's ` +\n          `node_modules from it — its own dependencies are left as they are.`,\n      );\n      continue;\n    }\n    const ctx = {\n      name,\n      entry,\n      pkgDir,\n      pkg: readJson(path.join(pkgDir, 'package.json')) ?? {},\n      entries,\n      candidates,\n      only,\n      deps,\n    };\n    for (const nm of nodeModulesRoots(pkgDir, entry)) {\n      const result = pruneOne(nm, ctx);\n      removed.push(...result.removed);\n      kept.push(...result.kept);\n    }\n  }\n\n  report(removed, kept, deps);\n  return {removed, kept};\n}\n\n/**\n * Is `dep` -- declared by a checkout at `range` -- something the app provides,\n * so that its absence from the checkout's own `node_modules` is not a\n * dependency gone missing? `--relink` asks this before reinstalling a\n * checkout, so a copy pruned on purpose does not trigger a reinstall on every\n * postinstall.\n */\nexport function isProvidedByApp(\n  dep: string,\n  range: string | undefined,\n  entries: Record<string, ManifestEntry>,\n  candidates: Candidates,\n  deps: Pick<Deps, 'appRoot'>,\n): boolean {\n  const app = appCopy(dep, deps);\n  if (!app) return false;\n  if (entries[dep]) return true;\n  if (!candidates.names.has(dep)) return false;\n  return range === undefined || satisfies(app.version, range) === true;\n}\n\nfunction pruneOne(nm, ctx) {\n  const removed = [];\n  const kept = [];\n  const {name: owner, entry, pkg, entries, candidates, only, deps} = ctx;\n\n  for (const dep of topLevelPackages(nm)) {\n    if (dep === owner) continue;\n    if (only && !only.has(dep)) continue;\n    const skip = candidates.skipped.get(dep);\n    if (!candidates.names.has(dep) && !skip) continue;\n    const dir = path.join(nm, dep);\n    const nested = readJson(path.join(dir, 'package.json'));\n    if (!nested) continue;\n    const app = appCopy(dep, deps);\n    if (!app) continue; // the app does not provide it, so this copy is the only one\n    if (realOrSelf(dir) === app.real) continue; // already the app's copy\n\n    const where = path.relative(deps.appRoot, dir);\n    if (!candidates.names.has(dep)) {\n      // The rule leaves it out: a localized checkout asks a range the app\n      // misses. Said for a checkout that declares it; a copy it only has\n      // transitively is none of its business.\n      if (declared(pkg, DECLARE_FIELDS, dep) === undefined) continue;\n      kept.push({\n        where,\n        dep,\n        version: nested.version,\n        app: app.version,\n        unmet: skip!.asks,\n        owner: entry.path,\n      });\n      continue;\n    }\n    const sibling = Boolean(entries[dep]);\n    const ranges = rangesResolvingTo(nm, dep, pkg, owner);\n\n    if (!sibling) {\n      const unmet = ranges.filter(\n        (r) => satisfies(app.version, r.range) !== true,\n      );\n      if (unmet.length) {\n        kept.push({\n          where,\n          dep,\n          version: nested.version,\n          app: app.version,\n          unmet,\n          owner: entry.path,\n        });\n        continue;\n      }\n    }\n\n    fs.rmSync(dir, {recursive: true, force: true});\n    removeEmptyScope(nm, dep);\n    removeBinLinksInto(nm, dir);\n    removed.push({\n      owner: entry.path,\n      dep,\n      version: nested.version,\n      app: app.version,\n      sibling,\n      drift: sibling\n        ? ranges.filter((r) => satisfies(app.version, r.range) === false)\n        : [],\n    });\n  }\n  return {removed, kept};\n}\n\nfunction report(removed, kept, deps) {\n  const byOwner = new Map();\n  for (const r of removed)\n    byOwner.set(r.owner, [...(byOwner.get(r.owner) ?? []), r]);\n  for (const [owner, list] of byOwner) {\n    deps.log(\n      `[localize] ${owner}: removed its own copies of what the app provides — ` +\n        list\n          .map(\n            (r) =>\n              `${r.dep}@${r.version} (app: ${r.sibling ? `localized, ${r.app}` : r.app})`,\n          )\n          .join(', '),\n    );\n    for (const r of list) {\n      for (const d of r.drift) {\n        deps.warn(\n          `[localize] ${owner}: ${d.from} asks ${r.dep}@${d.range}; the localized checkout is ${r.app}. ` +\n            `It is used anyway — that is what localizing it means — but the range is now fiction.`,\n        );\n      }\n    }\n  }\n  for (const k of kept) {\n    deps.warn(\n      `[localize] kept ${k.where}@${k.version}: ` +\n        k.unmet.map((u) => `${u.from} asks ${k.dep}@${u.range}`).join(', ') +\n        `, and the app has ${k.dep}@${k.app}${\n          k.unmet.some((u) => satisfies(k.app, u.range) === null)\n            ? ' (or the range is one localize cannot read)'\n            : ''\n        }. ` +\n        `${k.owner} loads its own copy, so the app loads two. Align the ranges, or update the app's ${k.dep}.`,\n    );\n  }\n}\n\n/**\n * Every range that resolves to `<nm>/<dep>`: the checkout's own declaration,\n * plus each installed package under `nm` that requires `dep` and has no copy\n * of its own between itself and `nm`.\n */\nfunction rangesResolvingTo(nm, dep, checkoutPkg, owner) {\n  const out = [];\n  const own = declared(checkoutPkg, DECLARE_FIELDS, dep);\n  if (own !== undefined) out.push({from: owner, range: own});\n\n  const walk = (dir, chain) => {\n    for (const name of topLevelPackages(dir)) {\n      const pkgDir = path.join(dir, name);\n      if (isSymlink(pkgDir)) continue; // resolves from its real path, which is not here\n      const pkg = readJson(path.join(pkgDir, 'package.json'));\n      const range =\n        pkg && name !== dep ? declared(pkg, REQUIRE_FIELDS, dep) : undefined;\n      const inner = path.join(pkgDir, 'node_modules');\n      const shadowed = [...chain, inner].some((d) =>\n        fs.existsSync(path.join(d, dep)),\n      );\n      if (range !== undefined && !shadowed)\n        out.push({from: `${name}@${pkg.version}`, range});\n      if (fs.existsSync(inner)) walk(inner, [...chain, inner]);\n    }\n  };\n  walk(nm, []);\n  return out;\n}\n\nfunction declared(pkg, fields, dep) {\n  for (const f of fields) if (pkg[f]?.[dep] !== undefined) return pkg[f][dep];\n  return undefined;\n}\n\n/** The app's own copy of `dep`: `<appRoot>/node_modules/<dep>`, followed through a link. */\nfunction appCopy(dep, deps) {\n  const dir = path.join(deps.appRoot, 'node_modules', dep);\n  const pkg = readJson(path.join(dir, 'package.json'));\n  if (!pkg?.version) return null;\n  return {version: pkg.version, real: realOrSelf(dir)};\n}\n\n/** The package dir's `node_modules`, and the clone root's when the package is a monorepo subdir. */\nexport function nodeModulesRoots(pkgDir, entry) {\n  const roots = [path.join(pkgDir, 'node_modules')];\n  if (entry.subdir) {\n    const rel = path.normalize(entry.subdir);\n    if (pkgDir.endsWith(path.sep + rel))\n      roots.push(path.join(pkgDir.slice(0, -(rel.length + 1)), 'node_modules'));\n  }\n  return roots.filter((d) => fs.existsSync(d));\n}\n\n/** Package names directly under a `node_modules`, scoped ones as `@scope/name`. */\nfunction topLevelPackages(nm) {\n  const out = [];\n  let items;\n  try {\n    items = fs.readdirSync(nm, {withFileTypes: true});\n  } catch {\n    return out;\n  }\n  for (const item of items) {\n    if (item.name.startsWith('.')) continue;\n    if (item.name.startsWith('@')) {\n      let inner = [];\n      try {\n        inner = fs.readdirSync(path.join(nm, item.name));\n      } catch {\n        /* not a directory */\n      }\n      for (const sub of inner)\n        if (!sub.startsWith('.')) out.push(`${item.name}/${sub}`);\n    } else {\n      out.push(item.name);\n    }\n  }\n  return out;\n}\n\n/** Links in `<nm>/.bin` that pointed into a package just removed: dangling now. */\nfunction removeBinLinksInto(nm, removedDir) {\n  const bin = path.join(nm, '.bin');\n  let names;\n  try {\n    names = fs.readdirSync(bin);\n  } catch {\n    return;\n  }\n  for (const name of names) {\n    const link = path.join(bin, name);\n    if (!isSymlink(link)) continue;\n    const target = path.resolve(bin, fs.readlinkSync(link));\n    if (isInside(target, removedDir)) fs.unlinkSync(link);\n  }\n}\n\nfunction removeEmptyScope(nm, dep) {\n  if (!dep.startsWith('@')) return;\n  const scope = path.join(nm, dep.split('/')[0]);\n  try {\n    if (!fs.readdirSync(scope).length) fs.rmdirSync(scope);\n  } catch {\n    /* already gone */\n  }\n}\n\nexport function realOrSelf(p: string): string {\n  try {\n    return fs.realpathSync(p);\n  } catch {\n    return p;\n  }\n}\n"]}

package/lib/esm/localize/relink.d.ts

@@ -0,0 +1,11 @@
+import type { PruneOptions } from './prune.js';
+import type { Deps } from './run.js';
+/**
+ * @param {object} deps
+ * @param {{prune?: boolean}} [opts]  unless `prune` is
+ *   false, every checkout's own copies of what the app provides are removed
+ *   after relinking (see prune.ts), and a dependency missing from a checkout
+ *   because it was pruned is not mistaken for one a root install took.
+ */
+export declare function relink(deps: Deps, opts?: PruneOptions): number;
+//# sourceMappingURL=relink.d.ts.map

package/lib/esm/localize/relink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relink.d.ts","sourceRoot":"","sources":["../../../src/localize/relink.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,UAAU,CAAC;AAEnC;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAE,YAAiB,GAAG,MAAM,CAiElE"}

package/lib/esm/localize/relink.js

@@ -0,0 +1,174 @@
+/**
+ * `--relink` -- the `postinstall` hook. Recreate every recorded symlink after
+ * an install removed it (`npm ci` deletes `node_modules` and exits 0).
+ *
+ * Three rules, each of which is the difference between a useful hook and one
+ * everybody disables:
+ *
+ * - **It always exits 0.** A postinstall that fails an install because of a
+ *   developer's private state is worse than the problem it solves.
+ * - **With no manifest it produces NO output at all.** That is the CI case and
+ *   the fresh-clone case. Any output there and people learn to ignore this
+ *   hook's output, which is the one thing it can never become.
+ * - **It never runs npm at the consumer root.** A postinstall that installs
+ *   the root, recurses. A test asserts it.
+ *
+ * It DOES run `npm install` inside a checkout whose dependencies are gone, and
+ * only then. Measured on npm 11: a root `npm install` treats a linked checkout
+ * that sits under the root as part of the root's tree, marks its dependencies
+ * `extraneous` and prunes them -- for a localized published dependency as
+ * much as for an undeclared one. Putting the link back without the
+ * dependencies leaves a checkout that cannot build. That install runs in the
+ * checkout, never at the root, so it cannot re-enter this hook; and it runs
+ * only when a declared dependency is missing, so an ordinary install stays
+ * silent and fast.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readManifest } from './manifest.js';
+import { isSymlink, readJson, writeLink } from './fsops.js';
+import { declaredRange } from './localize.js';
+import { candidatesFor, isProvidedByApp, pruneProvided, shouldPrune, } from './prune.js';
+import { ensure } from './ensure.js';
+/**
+ * @param {object} deps
+ * @param {{prune?: boolean}} [opts]  unless `prune` is
+ *   false, every checkout's own copies of what the app provides are removed
+ *   after relinking (see prune.ts), and a dependency missing from a checkout
+ *   because it was pruned is not mistaken for one a root install took.
+ */
+export function relink(deps, opts = {}) {
+    let manifest;
+    try {
+        manifest = readManifest(deps.appRoot, deps);
+    }
+    catch (e) {
+        // Even a refusal is only a warning here: never fail an install.
+        deps.warn(`[localize] ${e.message}`);
+        return 0;
+    }
+    if (!manifest.exists)
+        return 0;
+    const names = Object.keys(manifest.entries);
+    if (!names.length)
+        return 0;
+    let relinked = 0;
+    for (const name of names) {
+        const entry = manifest.entries[name];
+        const checkout = path.join(deps.appRoot, entry.path);
+        if (!fs.existsSync(checkout)) {
+            deps.warn(`[localize] ${name} is recorded as local but ${entry.path} is gone — using the registry ` +
+                `copy. ` +
+                (entry.repo
+                    ? `\`linked localize ${name}\` to re-clone.`
+                    : `It has no recorded repository, so restore the checkout by hand, then ` +
+                        `\`linked localize ${name} --adopt\`.`));
+            continue;
+        }
+        reinstallIfPruned(name, entry, manifest.entries, opts, deps);
+        if (isSymlink(path.join(deps.appRoot, 'node_modules', name))) {
+            // Already linked; rewriting it would be noise on every install.
+            const existing = fs.realpathSync(path.join(deps.appRoot, 'node_modules', name));
+            if (existing === fs.realpathSync(checkout))
+                continue;
+        }
+        writeLink(deps.appRoot, name, checkout);
+        relinked++;
+        deps.log(`[localize] relinked ${name} -> ${entry.path} (branch ${entry.branch})`);
+        warnRangeDrift(name, entry, checkout, deps);
+    }
+    if (relinked) {
+        deps.log(`[localize] ${relinked} local package${relinked === 1 ? '' : 's'} relinked. ` +
+            '`linked localize --list` for detail.');
+    }
+    if (shouldPrune(opts)) {
+        try {
+            pruneProvided(manifest.entries, opts, deps);
+        }
+        catch (e) {
+            // Never fail an install over it.
+            deps.warn(`[localize] pruning failed: ${e.message}`);
+        }
+    }
+    return 0;
+}
+/**
+ * Restore a checkout's own `node_modules` when a root install pruned it: any
+ * declared dependency (or devDependency -- the checkout's build needs those)
+ * missing from it. A failure warns; the hook still exits 0.
+ */
+function reinstallIfPruned(name, entry, entries, opts, deps) {
+    const checkout = path.join(deps.appRoot, entry.path);
+    // When pruning, a dependency the app provides is absent on purpose.
+    const candidates = shouldPrune(opts) ? candidatesFor(entries, deps) : null;
+    const provided = candidates
+        ? (dep, range) => isProvidedByApp(dep, range, entries, candidates, deps)
+        : () => false;
+    const missing = missingDependencies(checkout, cloneRootOf(entry, deps), provided);
+    if (!missing.length)
+        return;
+    deps.log(`[localize] ${name}: ${missing.length} of its dependencies are gone from ${entry.path}/node_modules ` +
+        `(a root install prunes a checkout under the root) — reinstalling it`);
+    try {
+        ensure(entry, deps, opts);
+    }
+    catch (e) {
+        deps.warn(`[localize] ${name}: ${e.message}\n` +
+            `Retry with \`linked localize --reinstall ${name}\`.`);
+    }
+}
+/**
+ * Declared dependency names found in neither the checkout's own `node_modules`
+ * nor, for a package inside a monorepo, the clone root's -- where a workspaces
+ * install hoists them. Checking only the package directory there would find
+ * every hoisted dependency "missing" and reinstall on every postinstall.
+ */
+function missingDependencies(checkout, cloneRoot, provided = () => false) {
+    const pkg = readJson(path.join(checkout, 'package.json'));
+    if (!pkg)
+        return [];
+    const declared = Object.assign(Object.assign({}, pkg.devDependencies), pkg.dependencies);
+    const roots = cloneRoot === checkout ? [checkout] : [checkout, cloneRoot];
+    return Object.keys(declared).filter((dep) => !roots.some((root) => fs.existsSync(path.join(root, 'node_modules', dep))) && !provided(dep, declared[dep], pkg));
+}
+/** The clone a `subdir` entry lives in: its path with the subdir taken off the end. */
+function cloneRootOf(entry, deps) {
+    const pkgDir = path.join(deps.appRoot, entry.path);
+    if (!entry.subdir)
+        return pkgDir;
+    const rel = path.normalize(entry.subdir);
+    return pkgDir.endsWith(path.sep + rel)
+        ? pkgDir.slice(0, -(rel.length + 1))
+        : pkgDir;
+}
+/**
+ * npm matches a link by NAME and never checks the range, so a checkout at
+ * 2.0.99 silently satisfies `^3.0.0` and `npm ls` does not flag it. This warns
+ * and never errors, and the range is never used to decide whether a checkout
+ * is usable -- only to say out loud that the declared range is now fiction.
+ */
+function warnRangeDrift(name, entry, checkout, deps) {
+    var _a;
+    const declared = declaredRange(name, deps);
+    const version = (_a = readJson(path.join(checkout, 'package.json'))) === null || _a === void 0 ? void 0 : _a.version;
+    if (!declared || !version)
+        return;
+    if (sameMajor(version, declared) &&
+        (!entry.range || entry.range === declared))
+        return;
+    deps.warn(`[localize] ${name}: checkout is ${version}, package.json asks ${declared}` +
+        (entry.range ? ` (recorded ${entry.range})` : '') +
+        ` — the symlink wins; npm does NOT check the range.`);
+}
+/**
+ * Deliberately crude: enough to spot obvious drift for a warning, never used
+ * to gate anything. Real semver (`satisfies` in prune.ts) here would invite
+ * someone to treat the answer as a constraint.
+ */
+function sameMajor(version, range) {
+    const m = /^[\^~]?(\d+)\./.exec(range);
+    if (!m)
+        return true;
+    return version.split('.')[0] === m[1];
+}
+//# sourceMappingURL=relink.js.map