@_linked/cli 1.43.1 → 1.44.0

package/lib/esm/localize/prune.js

@@ -16,35 +16,47 @@
  * 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.
+ * `node_modules` that is a CANDIDATE in that checkout (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:
+ * The candidates start from `providedPackages` (provided.ts) -- the one rule
+ * the run-time check and Vite's dedupe use too -- and are taken PER CHECKOUT:
  *
  * - 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;
+ * - one of **this checkout's own runtime dependencies** (`dependencies`,
+ *   `peerDependencies`, `optionalDependencies`) that the rule provides -- the
+ *   app has it at a version satisfying every localized checkout's range;
  * - `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.
+ * Nothing else is touched -- this checkout's devDependency stays even when
+ * another checkout depends on the same package at runtime, 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
+ * reported, 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;
+ * - a copy whose ranges the app's version does not satisfy;
+ * - a copy whose own dependencies would resolve to something else from the
+ *   app's copy than they do from the checkout (`contextChange` below): the
+ *   checkout keeps its own copies of whatever failed the guard, and removing
+ *   the copy would mix the two -- measured as a checkout's `tsc` seeing two
+ *   React type sets;
  * - 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.
+ *   package would simply be missing;
+ * - anything in a checkout recorded with `prune: false` (localized with
+ *   `--no-prune`).
+ *
+ * Kept copies are reported once per checkout, as a summary; `--list` gives
+ * each one's reason. A removal can make another copy removable, so a prune
+ * repeats until a pass removes nothing.
  *
  * 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`,
@@ -65,7 +77,7 @@ 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). */
+/** The rule (`providedPackages`, provided.ts) over `entries`, plus every entry (sibling). */
 export function candidatesFor(entries, deps) {
     const rule = providedPackages(deps.appRoot, Object.keys(entries));
     return {
@@ -97,6 +109,10 @@ export function satisfies(version, range) {
 export function shouldPrune(opts = {}) {
     return opts.prune !== false;
 }
+/** Is pruning on for this recorded checkout? `--no-prune` at localize/adopt records `prune: false`. */
+export function prunesEntry(entry) {
+    return entry.prune !== false;
+}
 const REQUIRE_FIELDS = [
     'dependencies',
     'peerDependencies',
@@ -108,45 +124,103 @@ const DECLARE_FIELDS = [
     'peerDependencies',
     'optionalDependencies',
 ];
+/** Candidates in every checkout, declared or not: a second React breaks hooks whoever loads it. */
+const ALWAYS_CANDIDATES = new Set(['react', 'react-dom']);
+/** prune repeats until a pass removes nothing, at most this many passes. */
+export const MAX_PRUNE_PASSES = 5;
+export function newPruneCache() {
+    return { indexes: new Map(), builds: 0 };
+}
 /**
- * @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)
+ * Decide, for every recorded checkout and every candidate copy in its
+ * `node_modules`, whether pruning removes it -- without removing anything.
+ * `pruneProvided` applies it; the run-time check (`checkOneCopy`) and
+ * `--list` call it on its own, which is why it has to be cheap: a copy whose
+ * checkout's own range rules it out is decided from that `package.json`
+ * alone, and every other range comes from one requirement index per
+ * `node_modules`, built at most once per call.
+ *
+ * Candidates are PER OWNER: a copy is a candidate in checkout O when the rule
+ * provides it AND it is a localized sibling, `react`/`react-dom`, or one of
+ * O's own runtime dependencies (`dependencies`, `peerDependencies`,
+ * `optionalDependencies`). O's devDependencies are O's tooling, whatever
+ * another checkout declares at runtime.
  */
-export function pruneProvided(entries, opts, deps, scope = {}) {
+export function planPrune(entries, deps, scope = {}, cache = newPruneCache(), candidates = candidatesFor(entries, deps)) {
     var _a;
-    const removed = [];
-    const kept = [];
+    const plan = { remove: [], keep: [], outside: [] };
     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;
+        if (!prunesEntry(entry))
+            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.`);
+            plan.outside.push({ name, path: entry.path });
             continue;
         }
-        const ctx = {
-            name,
-            entry,
-            pkgDir,
-            pkg: (_a = readJson(path.join(pkgDir, 'package.json'))) !== null && _a !== void 0 ? _a : {},
-            entries,
-            candidates,
-            only,
-            deps,
-        };
+        const pkg = (_a = readJson(path.join(pkgDir, 'package.json'))) !== null && _a !== void 0 ? _a : {};
+        const runtime = new Set(REQUIRE_FIELDS.flatMap((f) => { var _a; return Object.keys((_a = pkg[f]) !== null && _a !== void 0 ? _a : {}); }));
+        // The names that can be a decision here, looked up directly rather than
+        // by listing node_modules (thousands of entries per checkout): this
+        // checkout's candidates, and what the rule skipped that it declares.
+        const names = new Set();
+        for (const n of candidates.names) {
+            if (entries[n] || ALWAYS_CANDIDATES.has(n) || runtime.has(n))
+                names.add(n);
+        }
+        for (const n of candidates.skipped.keys()) {
+            if (declared(pkg, DECLARE_FIELDS, n) !== undefined)
+                names.add(n);
+        }
+        names.delete(name);
+        const ctx = { name, entry, pkg, names, entries, candidates, only, deps };
         for (const nm of nodeModulesRoots(pkgDir, entry)) {
-            const result = pruneOne(nm, ctx);
-            removed.push(...result.removed);
-            kept.push(...result.kept);
+            for (const d of decideIn(nm, ctx, cache)) {
+                (d.action === 'remove' ? plan.remove : plan.keep).push(d);
+            }
+        }
+    }
+    return plan;
+}
+/**
+ * @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)
+ *
+ * A removal can make another copy removable -- the copy that went was the one
+ * asking a range the app misses, or the one a sibling copy's dependency
+ * resolved to -- so it plans and removes again until a pass removes nothing
+ * (at most `MAX_PRUNE_PASSES`): one call converges. A checkout recorded with
+ * `prune: false` is never touched.
+ */
+export function pruneProvided(entries, opts, deps, scope = {}, cache = newPruneCache()) {
+    const removed = [];
+    let kept = [];
+    const candidates = candidatesFor(entries, deps);
+    for (let pass = 0; pass < MAX_PRUNE_PASSES; pass++) {
+        const passScope = pass === 0 ? scope : { owners: scope.owners };
+        const plan = planPrune(entries, deps, passScope, cache, candidates);
+        if (pass === 0) {
+            for (const o of plan.outside) {
+                deps.log(`[localize] ${o.name}: ${o.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.`);
+            }
+        }
+        for (const d of plan.remove) {
+            fs.rmSync(d.dir, { recursive: true, force: true });
+            removeEmptyScope(d.nm, d.dep);
+            removeBinLinksInto(d.nm, d.dir);
+            removed.push(d);
         }
+        kept = plan.keep;
+        if (!plan.remove.length)
+            break;
     }
     report(removed, kept, deps);
     return { removed, kept };
@@ -156,9 +230,10 @@ export function pruneProvided(entries, opts, deps, scope = {}) {
  * 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.
+ * postinstall. `pkg` is the checkout's `package.json`: only what would be a
+ * candidate in THAT checkout counts.
  */
-export function isProvidedByApp(dep, range, entries, candidates, deps) {
+export function isProvidedByApp(dep, range, entries, candidates, deps, pkg) {
     const app = appCopy(dep, deps);
     if (!app)
         return false;
@@ -166,20 +241,21 @@ export function isProvidedByApp(dep, range, entries, candidates, deps) {
         return true;
     if (!candidates.names.has(dep))
         return false;
+    if (pkg &&
+        !ALWAYS_CANDIDATES.has(dep) &&
+        declared(pkg, REQUIRE_FIELDS, dep) === undefined)
+        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;
+function decideIn(nm, ctx, cache) {
+    const out = [];
+    const { name: owner, entry, pkg, names, entries, candidates, only, deps } = ctx;
+    for (const dep of [...names].sort()) {
         if (only && !only.has(dep))
             continue;
         const skip = candidates.skipped.get(dep);
-        if (!candidates.names.has(dep) && !skip)
-            continue;
+        const inRule = candidates.names.has(dep);
+        const sibling = Boolean(entries[dep]);
         const dir = path.join(nm, dep);
         const nested = readJson(path.join(dir, 'package.json'));
         if (!nested)
@@ -189,57 +265,211 @@ function pruneOne(nm, ctx) {
             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)) {
+        const base = {
+            ownerName: owner,
+            owner: entry.path,
+            dep,
+            dir,
+            where: path.relative(deps.appRoot, dir),
+            nm,
+            version: nested.version,
+            app: app.version,
+            sibling,
+        };
+        if (!inRule) {
             // 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,
-            });
+            out.push(Object.assign(Object.assign({}, base), { action: 'keep', reason: 'range', unmet: skip.asks }));
             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,
-                });
+        const own = declared(pkg, DECLARE_FIELDS, dep);
+        const ownAsk = own === undefined ? [] : [{ from: owner, range: own }];
+        if (sibling) {
+            // Always removed: the live checkout is the point of localizing it. A
+            // range it misses is drift, said out loud and never acted on.
+            const ranges = [...ownAsk, ...requirementIndex(nm, cache).asks(dep)];
+            out.push(Object.assign(Object.assign({}, base), { action: 'remove', unmet: ranges.filter((r) => satisfies(app.version, r.range) === false) }));
+            continue;
+        }
+        // The checkout's own range first: when it rules the copy out, no index is needed.
+        if (own !== undefined && satisfies(app.version, own) !== true) {
+            out.push(Object.assign(Object.assign({}, base), { action: 'keep', reason: 'range', unmet: ownAsk }));
+            continue;
+        }
+        const unmet = requirementIndex(nm, cache)
+            .asks(dep)
+            .filter((r) => satisfies(app.version, r.range) !== true);
+        if (unmet.length) {
+            out.push(Object.assign(Object.assign({}, base), { action: 'keep', reason: 'range', unmet }));
+            continue;
+        }
+        const context = contextChange(dir, app.real, nested);
+        if (context) {
+            out.push(Object.assign(Object.assign({}, base), { action: 'keep', reason: 'context', unmet: [], context }));
+            continue;
+        }
+        out.push(Object.assign(Object.assign({}, base), { action: 'remove', unmet: [] }));
+    }
+    return out;
+}
+/**
+ * Would removing the copy at `copyDir` change what ITS OWN dependencies
+ * resolve to? Removing it hands its importers the app's copy, which resolves
+ * its dependencies from the app root -- while the checkout keeps its own copy
+ * of everything that failed the guard. Measured: a checkout kept its
+ * `react`/`@types/react` 18 (its range), lost `prism-react-renderer` (in
+ * range), and the app's copy of that resolved `react` -- and with it the
+ * types -- to the app's 19: the checkout's own `tsc` saw both React type sets
+ * and failed. So the copy stays when any of its `dependencies`,
+ * `peerDependencies` or `optionalDependencies` (and the `@types/` package
+ * TypeScript would take for it) resolves, from the copy's place in the
+ * checkout, to a different package than from the app's copy: a different real
+ * path that is not the same `name@version`, or nothing at all from the app's.
+ * The same version at another path is the same code, so it does not count; a
+ * dependency the checkout cannot resolve either is no change.
+ */
+function contextChange(copyDir, appReal, pkg) {
+    var _a;
+    const names = new Set();
+    for (const f of REQUIRE_FIELDS) {
+        for (const d of Object.keys((_a = pkg[f]) !== null && _a !== void 0 ? _a : {})) {
+            names.add(d);
+            names.add(typesPackageFor(d));
+        }
+    }
+    for (const d of names) {
+        const here = resolveFrom(copyDir, d);
+        if (!here)
+            continue;
+        const there = resolveFrom(appReal, d);
+        if (!there)
+            return { dep: d, here: here.version, app: null };
+        if (here.real !== there.real && here.version !== there.version)
+            return { dep: d, here: here.version, app: there.version };
+    }
+    return undefined;
+}
+/** `react` → `@types/react`; `@scope/name` → `@types/scope__name`; an `@types/` name is itself. */
+function typesPackageFor(name) {
+    if (name.startsWith('@types/'))
+        return name;
+    return `@types/${name.startsWith('@') ? name.slice(1).replace('/', '__') : name}`;
+}
+/** Node's upward search for `name` from the directory `from`: the first `node_modules/<name>`. */
+function resolveFrom(from, name) {
+    for (let dir = from;;) {
+        if (path.basename(dir) !== 'node_modules') {
+            const candidate = path.join(dir, 'node_modules', name);
+            const pkg = readJson(path.join(candidate, 'package.json'));
+            if (pkg)
+                return { real: realOrSelf(candidate), version: String(pkg.version) };
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** The package's directory, and the `node_modules` directories between `nm` and it (its own included). */
+function locate(nm, i) {
+    if (!i.located) {
+        const segs = i.rel.split('/');
+        const dir = path.join(nm, ...segs);
+        const between = [path.join(dir, 'node_modules')];
+        for (let k = 0; k < segs.length; k++) {
+            if (segs[k] === 'node_modules')
+                between.push(path.join(nm, ...segs.slice(0, k + 1)));
+        }
+        i.located = { dir, between };
+    }
+    return i.located;
+}
+function requirementIndex(nm, cache) {
+    var _a;
+    let index = cache.indexes.get(nm);
+    if (!index) {
+        cache.builds++;
+        const byDep = (_a = fromHiddenLockfile(nm)) !== null && _a !== void 0 ? _a : fromWalk(nm);
+        index = {
+            asks(dep) {
+                var _a;
+                const out = [];
+                for (const { installed, range } of (_a = byDep.get(dep)) !== null && _a !== void 0 ? _a : []) {
+                    if (installed.name === dep)
+                        continue;
+                    const { dir, between } = locate(nm, installed);
+                    if (!fs.existsSync(path.join(dir, 'package.json')))
+                        continue;
+                    if (between.some((d) => fs.existsSync(path.join(d, dep))))
+                        continue;
+                    out.push({ from: `${installed.name}@${installed.version}`, range });
+                }
+                return out;
+            },
+        };
+        cache.indexes.set(nm, index);
+    }
+    return index;
+}
+/** Record what the package at `rel` (below `nm`) requires. */
+function addRequirer(byDep, rel, pkg) {
+    var _a;
+    const at = rel.lastIndexOf('/node_modules/');
+    const installed = {
+        name: at === -1 ? rel : rel.slice(at + '/node_modules/'.length),
+        version: pkg.version,
+        rel,
+    };
+    const seen = new Set();
+    for (const f of REQUIRE_FIELDS) {
+        for (const [dep, range] of Object.entries((_a = pkg[f]) !== null && _a !== void 0 ? _a : {})) {
+            if (typeof range !== 'string' || seen.has(dep))
                 continue;
-            }
+            seen.add(dep);
+            let list = byDep.get(dep);
+            if (!list)
+                byDep.set(dep, (list = []));
+            list.push({ installed, range });
         }
-        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 };
+}
+const NODE_MODULES_PREFIX = 'node_modules/';
+function fromHiddenLockfile(nm) {
+    const lock = readJson(path.join(nm, '.package-lock.json'));
+    if (!(lock === null || lock === void 0 ? void 0 : lock.packages) || typeof lock.packages !== 'object')
+        return null;
+    const byDep = new Map();
+    for (const [key, meta] of Object.entries(lock.packages)) {
+        if (!key.startsWith(NODE_MODULES_PREFIX) || !meta || meta.link)
+            continue;
+        addRequirer(byDep, key.slice(NODE_MODULES_PREFIX.length), meta);
+    }
+    return byDep;
+}
+function fromWalk(nm) {
+    const byDep = new Map();
+    const walk = (dir, prefix) => {
+        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 rel = prefix + name;
+            const pkg = readJson(path.join(pkgDir, 'package.json'));
+            if (pkg)
+                addRequirer(byDep, rel, pkg);
+            const inner = path.join(pkgDir, 'node_modules');
+            if (fs.existsSync(inner))
+                walk(inner, `${rel}/node_modules/`);
+        }
+    };
+    walk(nm, '');
+    return byDep;
 }
 function report(removed, kept, deps) {
-    var _a;
+    var _a, _b;
     const byOwner = new Map();
     for (const r of removed)
         byOwner.set(r.owner, [...((_a = byOwner.get(r.owner)) !== null && _a !== void 0 ? _a : []), r]);
@@ -249,48 +479,47 @@ function report(removed, kept, deps) {
                 .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) {
+            for (const d of r.unmet) {
                 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}.`);
+    const keptBy = new Map();
+    for (const k of kept)
+        keptBy.set(k.owner, [...((_b = keptBy.get(k.owner)) !== null && _b !== void 0 ? _b : []), k]);
+    for (const [owner, list] of keptBy) {
+        const one = list.length === 1;
+        deps.warn(`[localize] ${owner}: kept ${list.length} own ${one ? 'copy' : 'copies'} the app's cannot ` +
+            `replace: ${summarizeKept(list)} — so the app loads ${one ? 'it' : 'them'} twice. ` +
+            `\`linked localize --list\` says why.`);
     }
 }
-/**
- * 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;
+const SUMMARY_LIMIT = 8;
+/** `react@18.3.1 (app 19.2.0), prism-react-renderer@2.4.1 (its react would change), … and 4 more` */
+export function summarizeKept(list) {
+    const shown = list.slice(0, SUMMARY_LIMIT).map(keptShort);
+    const more = list.length - shown.length;
+    return shown.join(', ') + (more > 0 ? `, … and ${more} more` : '');
+}
+function keptShort(k) {
+    return k.reason === 'context'
+        ? `${k.dep}@${k.version} (its ${k.context.dep} would change)`
+        : `${k.dep}@${k.version} (app ${k.app})`;
+}
+/** The full reason a copy stays, for `--list`. */
+export function explainKept(k) {
+    if (k.reason === 'context') {
+        const c = k.context;
+        return (`${k.where}@${k.version}: from the checkout its ${c.dep} is ${c.here}, from the app's copy ` +
+            `${c.app === null ? 'nothing' : c.app} — removing it would change what it loads`);
+    }
+    return (`${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)'
+            : ''));
 }
 function declared(pkg, fields, dep) {
     var _a;