pm-dedup-core 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Christophe Hurpeau <christophe@hurpeau.com> (https://christophe.hurpeau.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+<h1 align="center">
+  pm-dedup-core
+</h1>
+
+<p align="center">
+  package manager utils
+</p>
+
+<p align="center">
+  <a href="https://npmjs.org/package/pm-dedup-core"><img src="https://img.shields.io/npm/v/pm-dedup-core.svg?style=flat-square" alt="npm version"></a>
+  <a href="https://npmjs.org/package/pm-dedup-core"><img src="https://img.shields.io/npm/dw/pm-dedup-core.svg?style=flat-square" alt="npm downloads"></a>
+  <a href="https://npmjs.org/package/pm-dedup-core"><img src="https://img.shields.io/node/v/pm-dedup-core.svg?style=flat-square" alt="node version"></a>
+  <a href="https://npmjs.org/package/pm-dedup-core"><img src="https://img.shields.io/npm/types/pm-dedup-core.svg?style=flat-square" alt="types"></a>
+</p>
+
+## Install
+
+```bash
+npm install --save pm-dedup-core
+```
+
+## Usage
+
+The package-manager-agnostic core behind
+[bun-dedup](../bun-dedup), [pnpm-dedup](../pnpm-dedup) and
+[yarn-berry-deduplicate](../yarn-berry-deduplicate): everything about finding
+duplicates, deciding what can be merged and rendering the result lives here.
+The per-manager packages only parse their lockfile into the shapes below and
+write the result back.
+
+It is published so those packages can depend on it, not as a general-purpose
+library: this is internal API and it changes with them. There is no default
+export — import the named ones.
+
+```js
+import {
+  buildLockstepClusters,
+  createPackageFilter,
+  findProjectRoot,
+  identifyResolutionFixes,
+} from "pm-dedup-core";
+
+const projectDir = findProjectRoot({ lockfileName: "bun.lock" }); // null when there is none
+const filter = createPackageFilter({
+  includeScopes: ["@babel"],
+  exclude: ["@babel/runtime"],
+});
+
+filter.selects("@babel/core"); // true
+filter.rejectionReason("lodash"); // why it is left alone, for the report
+```
+
+### What a package manager has to supply
+
+The core never touches the filesystem for you and never guesses a lockfile path.
+A caller reads its own lockfile and hands over:
+
+- a **resolutions** list — one entry per resolved copy of a package
+  (`ResolutionEntry`, whose `package` is `npm` or another protocol).
+- a **dependents map** — for each package name, who requires it and with which
+  range (`ResolutionDependentsMap`). This is where the managers differ most:
+  see the peer-dependency notes in each package's README.
+- for the cluster pass, a **lockstep graph** (`LockstepGraph`), the dependency
+  edges between resolved copies.
+
+### Areas
+
+| Area               | Exports                                                                                                                                             |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Project root       | `findProjectRoot`, `resolveProjectDir`                                                                                                              |
+| CLI grammar        | `parseBinArgs`, `packageFilterParseArgsOptions`, `packageFilterUsage`, `whyDuplicateParseArgsOptions`, `whyDuplicateUsage`, `toWhyDuplicateRequest` |
+| Package filtering  | `createPackageFilter`, `selectPackages`, `selectClusterFixes`, `describeSkippedClusterFix`, `selectExplainedPackages`                               |
+| Names and ranges   | `PackageDescriptorNameUtils`, `PackageDependencyDescriptorUtils`, `isNpmProtocol`, `isSemverComparable`, `createCandidateVersionComparator`         |
+| Fix identification | `identifyResolutionFixes`, `buildLockstepClusters`, `identifyLockstepClusterFixes`, `buildIdentifiedFixesMap`, `clusterLabel`                       |
+| Applying           | `planClusterApply`, `applyWorkspaceRangeEdit`, `nextSelector`, `partitionUnconditionalOverrides`, `captureFiles`, `restoreFiles`                    |
+| Measuring a run    | `buildVersionsSnapshot`, `diffVersionsSnapshots`, `countDuplicatedPackages`, `diffDuplicates`                                                       |
+| Rendering          | `renderDuplicatesReport`, `renderApplyPlan`, `renderDedupeSummary`, `createColorize`, `shouldColorize`, `stylePackageName`, `stylePackageReference` |
+
+Two of these carry most of the behaviour:
+
+- **`identifyResolutionFixes`** finds the merges reachable one package at a
+  time: a copy whose dependents' ranges all accept a version already in the
+  lockfile. This is what the lockfile pass applies.
+- **`identifyLockstepClusterFixes`** finds the rest. `buildLockstepClusters`
+  groups packages that are always published at the same version, and a
+  duplicate inside such a family only goes away when the whole family moves —
+  which needs a real resolution, hence the separate cluster pass.
+
+`resolveProjectDir` is the bin-facing half of `findProjectRoot`: it prints the
+reason and sets `process.exitCode` when there is no lockfile, and returns
+`null`, so callers guard with `if (projectDir === null) return;`. The notice
+naming the lockfile goes to stderr and only when the root is not the working
+directory, keeping a redirected report parseable.
+
+### Colors
+
+`shouldColorize(stream)` follows the terminal: `NO_COLOR` and a piped stream turn
+colors off, `FORCE_COLOR` turns them on. Every renderer takes the resulting
+`Colorize`, so a report piped to a file is plain text.
+
+### Runtime
+
+Node only (`>=22.18.0`), so the pnpm and yarn tools can depend on it: no
+`Bun.*`, no `bun` imports. Tests run under `bun test` like the rest of the
+monorepo.

package/dist/buildIdentifiedFixesMap.js

@@ -0,0 +1,6 @@
+import { identifyResolutionFixes, } from "./identifyResolutionFixes.js";
+export const buildIdentifiedFixesMap = (duplicatesResolutionsMap, dependents) => new Map(Object.entries(duplicatesResolutionsMap).map(([packageName, resolutions]) => [
+    packageName,
+    identifyResolutionFixes(resolutions, dependents),
+]));
+//# sourceMappingURL=buildIdentifiedFixesMap.js.map

package/dist/buildIdentifiedFixesMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildIdentifiedFixesMap.js","sourceRoot":"","sources":["../src/buildIdentifiedFixesMap.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,uBAAuB,GACxB,MAAM,8BAA8B,CAAC;AAItC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,wBAAwC,EACxC,UAAsC,EACR,EAAE,CAChC,IAAI,GAAG,CACL,MAAM,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC,GAAG,CAC1C,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC;IAC9B,WAAW;IACX,uBAAuB,CAAC,WAAW,EAAE,UAAU,CAAC;CACjD,CACF,CACF,CAAC"}

package/dist/buildLockstepClusters.js

@@ -0,0 +1,119 @@
+import semver from "semver";
+const createUnionFind = (names) => {
+    const parent = new Map(names.map((name) => [name, name]));
+    const find = (value) => {
+        let root = value;
+        while (parent.get(root) !== root) {
+            root = parent.get(root);
+        }
+        let cursor = value;
+        while (parent.get(cursor) !== root) {
+            const next = parent.get(cursor);
+            parent.set(cursor, root);
+            cursor = next;
+        }
+        return root;
+    };
+    const union = (a, b) => {
+        const rootA = find(a);
+        const rootB = find(b);
+        if (rootA !== rootB) {
+            parent.set(rootA, rootB);
+        }
+    };
+    return { find, union };
+};
+// npm versions installed for each name, normalized, for anchor lookups.
+const collectNpmVersions = (graph) => {
+    const versionsByName = new Map();
+    for (const [name, resolutions] of Object.entries(graph)) {
+        const versions = new Set();
+        for (const resolution of resolutions) {
+            if (!resolution.isNpm)
+                continue;
+            const parsed = semver.parse(resolution.version);
+            if (parsed)
+                versions.add(parsed.version);
+        }
+        versionsByName.set(name, versions);
+    }
+    return versionsByName;
+};
+// A dependency edge `A@version --(range)--> B` is "co-version" when the range
+// is anchored on the same version A itself carries, regardless of the caret /
+// tilde operator (`^8.61.0`, `8.61.0` and `~8.61.0` are all co-version with
+// `8.61.0`). This distinguishes a lockstep-published family member from an
+// ordinary external dependency such as `semver`/`debug`.
+//
+// The anchor also has to be a version of B the lock actually installs, or the
+// equality is a coincidence rather than a lockstep pin: `d@1.0.1` requesting
+// `type@^1.0.1` anchors on `1.0.1`, yet the only installed `type` versions are
+// `1.2.0` and `2.7.2`, so `d` and `type` do not move together. Lockfiles that
+// store resolved versions instead of ranges (pnpm) satisfy this by
+// construction; it brings the range-storing ones in line.
+const isCoVersion = (version, range, depVersions) => {
+    const min = (() => {
+        try {
+            return semver.minVersion(range);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (min === null)
+        return false;
+    return semver.eq(min, version) && depVersions.has(min.version);
+};
+// Detect families of packages published in lockstep (versions move together)
+// via union-find over the realized resolution graph. Names A and B are unioned
+// when a real dependency edge A->B exists AND across every installed resolution
+// where A requests B they carry the same version, that version being one the
+// lock installs for B. Returns connected components
+// of size > 1, members sorted, components ordered by their first member.
+export const buildLockstepClusters = (graph) => {
+    const names = Object.keys(graph);
+    const unionFind = createUnionFind(names);
+    const versionsByName = collectNpmVersions(graph);
+    for (const [name, resolutions] of Object.entries(graph)) {
+        const observationsByDep = new Map();
+        for (const resolution of resolutions) {
+            if (!resolution.isNpm)
+                continue;
+            for (const [depName, range] of Object.entries(resolution.dependencies)) {
+                if (depName === name)
+                    continue;
+                // edge must point to a package that actually exists in the lock
+                if (!graph[depName])
+                    continue;
+                let observations = observationsByDep.get(depName);
+                if (!observations) {
+                    observations = [];
+                    observationsByDep.set(depName, observations);
+                }
+                observations.push({ version: resolution.version, range });
+            }
+        }
+        for (const [depName, observations] of observationsByDep) {
+            const depVersions = versionsByName.get(depName) ?? new Set();
+            const allCoVersion = observations.every((observation) => isCoVersion(observation.version, observation.range, depVersions));
+            if (allCoVersion) {
+                unionFind.union(name, depName);
+            }
+        }
+    }
+    const componentsByRoot = new Map();
+    for (const name of names) {
+        const root = unionFind.find(name);
+        let members = componentsByRoot.get(root);
+        if (!members) {
+            members = [];
+            componentsByRoot.set(root, members);
+        }
+        members.push(name);
+    }
+    return [...componentsByRoot.values()]
+        .filter((members) => members.length > 1)
+        .map((members) => members.toSorted((a, b) => a.localeCompare(b)))
+        .toSorted((a, b) => a[0].localeCompare(b[0]));
+};
+//# sourceMappingURL=buildLockstepClusters.js.map

package/dist/buildLockstepClusters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildLockstepClusters.js","sourceRoot":"","sources":["../src/buildLockstepClusters.ts"],"names":[],"mappings":"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"}

package/dist/buildLockstepClusters.test.js

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "bun:test";
+import { buildLockstepClusters, } from "./buildLockstepClusters.js";
+const npm = (version, dependencies = {}) => ({
+    version,
+    isNpm: true,
+    dependencies,
+});
+describe("buildLockstepClusters", () => {
+    it("unions a co-versioned family across caret and exact pins", () => {
+        // a@1 and a@2 both request b/c at their own version; b requests c at its
+        // own version. `noise` is requested at an unrelated version by everyone.
+        const graph = {
+            a: [
+                npm("1.0.0", { b: "1.0.0", c: "^1.0.0", noise: "^3.0.0" }),
+                npm("2.0.0", { b: "2.0.0", c: "^2.0.0", noise: "^3.0.0" }),
+            ],
+            b: [npm("1.0.0", { c: "1.0.0" }), npm("2.0.0", { c: "2.0.0" })],
+            c: [npm("1.0.0"), npm("2.0.0")],
+            noise: [npm("3.1.0"), npm("3.2.0")],
+        };
+        const clusters = buildLockstepClusters(graph);
+        expect(clusters).toEqual([["a", "b", "c"]]);
+    });
+    it("does not union when a version observation breaks co-version", () => {
+        // a@2 requests b at b's matching version, but a@1 requests b at a stale
+        // version: not every observation co-versions, so no union.
+        const graph = {
+            a: [npm("1.0.0", { b: "2.0.0" }), npm("2.0.0", { b: "2.0.0" })],
+            b: [npm("1.0.0"), npm("2.0.0")],
+        };
+        expect(buildLockstepClusters(graph)).toEqual([]);
+    });
+    it("does not union when the anchor version is not installed", () => {
+        // Real case: `d@1.0.1` requests `type@^1.0.1`, so the range anchors on
+        // d's own version by coincidence — no `type@1.0.1` is installed, the
+        // request resolves to `type@1.2.0`, and the two do not move together.
+        const graph = {
+            d: [npm("1.0.1", { type: "^1.0.1" })],
+            esniff: [npm("2.0.1", { d: "^1.0.1", type: "^2.7.2" })],
+            type: [npm("1.2.0"), npm("2.7.2")],
+        };
+        expect(buildLockstepClusters(graph)).toEqual([]);
+    });
+    it("unions when the anchor version is installed alongside others", () => {
+        // Same shape, but the lock does carry `b@1.0.0`: the pin is real, and the
+        // duplicate `b@1.2.0` is what the cluster pass exists to collapse.
+        const graph = {
+            a: [npm("1.0.0", { b: "^1.0.0" })],
+            b: [npm("1.0.0"), npm("1.2.0")],
+        };
+        expect(buildLockstepClusters(graph)).toEqual([["a", "b"]]);
+    });
+    it("keeps unioning pnpm-style edges that store the resolved version", () => {
+        // pnpm records the resolved version, so the anchor is installed by
+        // construction and detection is unchanged.
+        const graph = {
+            a: [npm("7.28.0", { b: "7.28.0" })],
+            b: [npm("7.28.0")],
+        };
+        expect(buildLockstepClusters(graph)).toEqual([["a", "b"]]);
+    });
+    it("ignores edges to packages absent from the graph and non-npm resolutions", () => {
+        const graph = {
+            a: [npm("1.0.0", { missing: "1.0.0", b: "1.0.0" })],
+            b: [npm("1.0.0")],
+            w: [{ version: "", isNpm: false, dependencies: { a: "1.0.0" } }],
+        };
+        expect(buildLockstepClusters(graph)).toEqual([["a", "b"]]);
+    });
+});
+//# sourceMappingURL=buildLockstepClusters.test.js.map

package/dist/buildLockstepClusters.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildLockstepClusters.test.js","sourceRoot":"","sources":["../src/buildLockstepClusters.test.ts"],"names":[],"mappings":"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"}

package/dist/clusterLabel.js

@@ -0,0 +1,59 @@
+const leadingPrefixes = (member) => {
+    const scopeEnd = member.startsWith("@") ? member.indexOf("/") : -1;
+    const scope = scopeEnd === -1 ? null : member.slice(0, scopeEnd);
+    const rest = scope === null ? member : member.slice(scopeEnd + 1);
+    const segments = rest.split("-");
+    const withinRest = segments.map((_segment, index) => {
+        const joined = segments.slice(0, index + 1).join("-");
+        return scope === null ? joined : `${scope}/${joined}`;
+    });
+    return scope === null ? withinRest : [scope, ...withinRest];
+};
+const covers = (prefix, member) => member === prefix ||
+    member.startsWith(`${prefix}-`) ||
+    member.startsWith(`${prefix}/`);
+/**
+ * The prefix shared by the most members. Ties go to the longest prefix, so a
+ * family named after a scope wins over the bare package name it also matches.
+ */
+const bestGroup = (members) => {
+    const candidates = [...new Set(members.flatMap(leadingPrefixes))];
+    let best = null;
+    for (const prefix of candidates.toSorted((a, b) => a.localeCompare(b))) {
+        const covered = members.filter((member) => covers(prefix, member));
+        if (best === null ||
+            covered.length > best.covered.length ||
+            (covered.length === best.covered.length &&
+                prefix.length > best.prefix.length)) {
+            best = { prefix, covered };
+        }
+    }
+    return best;
+};
+const formatGroup = ({ prefix, covered }) => {
+    if (covered.length === 1 && covered[0] === prefix)
+        return prefix;
+    if (prefix.startsWith("@") && !prefix.includes("/"))
+        return `${prefix}/*`;
+    return covered.includes(prefix) ? `${prefix}*` : `${prefix}-*`;
+};
+/**
+ * A readable identity for a lockstep cluster, derived from the prefixes its
+ * members share: `@typescript-eslint/* (+1 more)`, `metro* + @react-native/*`.
+ * A second group is only worth naming when it covers more than one member;
+ * anything left over is counted, never guessed at.
+ */
+export const clusterLabel = (members) => {
+    const first = bestGroup(members);
+    if (first === null)
+        return "";
+    const groups = [first];
+    const remaining = members.filter((member) => !covers(first.prefix, member));
+    const second = remaining.length > 0 ? bestGroup(remaining) : null;
+    if (second !== null && second.covered.length > 1)
+        groups.push(second);
+    const uncovered = members.filter((member) => !groups.some((group) => covers(group.prefix, member))).length;
+    const label = groups.map(formatGroup).join(" + ");
+    return uncovered === 0 ? label : `${label} (+${uncovered} more)`;
+};
+//# sourceMappingURL=clusterLabel.js.map

package/dist/clusterLabel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusterLabel.js","sourceRoot":"","sources":["../src/clusterLabel.ts"],"names":[],"mappings":"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"}

package/dist/clusterLabel.test.js

@@ -0,0 +1,56 @@
+import { describe, it } from "bun:test";
+import { strictEqual } from "node:assert/strict";
+import { clusterLabel } from "./clusterLabel.js";
+const typescriptEslint = [
+    "@typescript-eslint/eslint-plugin",
+    "@typescript-eslint/parser",
+    "@typescript-eslint/project-service",
+    "@typescript-eslint/scope-manager",
+    "@typescript-eslint/tsconfig-utils",
+    "@typescript-eslint/type-utils",
+    "@typescript-eslint/types",
+    "@typescript-eslint/typescript-estree",
+    "@typescript-eslint/utils",
+    "@typescript-eslint/visitor-keys",
+    "typescript-eslint",
+];
+const metroFamily = [
+    "@react-native/asset-utils",
+    "@react-native/babel-plugin-codegen",
+    "@react-native/babel-preset",
+    "@react-native/codegen",
+    "metro",
+    "metro-cache",
+    "metro-config",
+    "metro-core",
+    "ob1",
+    "react-native",
+];
+describe("clusterLabel", () => {
+    it("names a family by its shared scope", () => {
+        strictEqual(clusterLabel(typescriptEslint), "@typescript-eslint/* (+1 more)");
+    });
+    it("names the two largest groups and counts the rest", () => {
+        strictEqual(clusterLabel(metroFamily), "@react-native/* + metro* (+2 more)");
+    });
+    it("uses a dash prefix when no member carries the prefix itself", () => {
+        strictEqual(clusterLabel([
+            "babel-plugin-syntax-hermes-parser",
+            "hermes-estree",
+            "hermes-parser",
+        ]), "hermes-* (+1 more)");
+    });
+    it("keeps the member name when it is the prefix", () => {
+        strictEqual(clusterLabel(["mini-metro", "mini-metro-config"]), "mini-metro*");
+    });
+    it("names a single member exactly", () => {
+        strictEqual(clusterLabel(["metro"]), "metro");
+    });
+    it("does not name a second group that covers one member", () => {
+        strictEqual(clusterLabel(["metro", "metro-config", "ob1"]), "metro* (+1 more)");
+    });
+    it("returns an empty label for no members", () => {
+        strictEqual(clusterLabel([]), "");
+    });
+});
+//# sourceMappingURL=clusterLabel.test.js.map

package/dist/clusterLabel.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusterLabel.test.js","sourceRoot":"","sources":["../src/clusterLabel.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,gBAAgB,GAAG;IACvB,kCAAkC;IAClC,2BAA2B;IAC3B,oCAAoC;IACpC,kCAAkC;IAClC,mCAAmC;IACnC,+BAA+B;IAC/B,0BAA0B;IAC1B,sCAAsC;IACtC,0BAA0B;IAC1B,iCAAiC;IACjC,mBAAmB;CACpB,CAAC;AAEF,MAAM,WAAW,GAAG;IAClB,2BAA2B;IAC3B,oCAAoC;IACpC,4BAA4B;IAC5B,uBAAuB;IACvB,OAAO;IACP,aAAa;IACb,cAAc;IACd,YAAY;IACZ,KAAK;IACL,cAAc;CACf,CAAC;AAEF,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,WAAW,CACT,YAAY,CAAC,gBAAgB,CAAC,EAC9B,gCAAgC,CACjC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,WAAW,CACT,YAAY,CAAC,WAAW,CAAC,EACzB,oCAAoC,CACrC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACrE,WAAW,CACT,YAAY,CAAC;YACX,mCAAmC;YACnC,eAAe;YACf,eAAe;SAChB,CAAC,EACF,oBAAoB,CACrB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,WAAW,CACT,YAAY,CAAC,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC,EACjD,aAAa,CACd,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,WAAW,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,WAAW,CACT,YAAY,CAAC,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC,EAC9C,kBAAkB,CACnB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,WAAW,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/compareCandidateVersions.js

@@ -0,0 +1,18 @@
+import semver from "semver";
+/**
+ * A version satisfying every dependent holds the maximal count, so it always
+ * sorts first: "the highest version that satisfies everyone" falls out of this
+ * ordering instead of needing a pass of its own.
+ */
+export const createCandidateVersionComparator = ({ satisfiedCountOf } = {}) => (versionA, versionB) => {
+    if (satisfiedCountOf) {
+        const satisfiesA = satisfiedCountOf(versionA);
+        const satisfiesB = satisfiedCountOf(versionB);
+        if (satisfiesB > satisfiesA)
+            return 1;
+        if (satisfiesB < satisfiesA)
+            return -1;
+    }
+    return semver.rcompare(versionA, versionB);
+};
+//# sourceMappingURL=compareCandidateVersions.js.map

package/dist/compareCandidateVersions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareCandidateVersions.js","sourceRoot":"","sources":["../src/compareCandidateVersions.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAO5B;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAC3C,CAAC,EAAE,gBAAgB,EAAE,GAAsC,EAAE,EAAE,EAAE,CACjE,CAAC,QAAgB,EAAE,QAAgB,EAAU,EAAE;IAC7C,IAAI,gBAAgB,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC9C,MAAM,UAAU,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,UAAU,GAAG,UAAU;YAAE,OAAO,CAAC,CAAC;QACtC,IAAI,UAAU,GAAG,UAAU;YAAE,OAAO,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAC7C,CAAC,CAAC"}

package/dist/compareCandidateVersions.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "bun:test";
+import { createCandidateVersionComparator } from "./compareCandidateVersions.js";
+const satisfiedCounts = new Map([
+    ["1.0.0", 1],
+    ["1.5.0", 3],
+    ["2.0.0", 3],
+    ["3.0.0", 2],
+]);
+const satisfiedCountOf = (version) => satisfiedCounts.get(version) ?? 0;
+describe("createCandidateVersionComparator", () => {
+    it("puts the version satisfying the most dependents first", () => {
+        const compare = createCandidateVersionComparator({ satisfiedCountOf });
+        expect(["1.0.0", "3.0.0", "1.5.0"].toSorted(compare)).toEqual([
+            "1.5.0",
+            "3.0.0",
+            "1.0.0",
+        ]);
+    });
+    it("breaks a tie on the highest version", () => {
+        const compare = createCandidateVersionComparator({ satisfiedCountOf });
+        expect(["1.5.0", "2.0.0"].toSorted(compare)).toEqual(["2.0.0", "1.5.0"]);
+    });
+    it("ranks on semver alone without a satisfied count", () => {
+        const compare = createCandidateVersionComparator();
+        expect(["1.0.0", "3.0.0", "1.5.0"].toSorted(compare)).toEqual([
+            "3.0.0",
+            "1.5.0",
+            "1.0.0",
+        ]);
+    });
+});
+//# sourceMappingURL=compareCandidateVersions.test.js.map

package/dist/compareCandidateVersions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareCandidateVersions.test.js","sourceRoot":"","sources":["../src/compareCandidateVersions.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAEjF,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,CAAC,OAAO,EAAE,CAAC,CAAC;IACZ,CAAC,OAAO,EAAE,CAAC,CAAC;IACZ,CAAC,OAAO,EAAE,CAAC,CAAC;IACZ,CAAC,OAAO,EAAE,CAAC,CAAC;CACb,CAAC,CAAC;AACH,MAAM,gBAAgB,GAAG,CAAC,OAAe,EAAU,EAAE,CACnD,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpC,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAChD,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,OAAO,GAAG,gCAAgC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAEvE,MAAM,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;YAC5D,OAAO;YACP,OAAO;YACP,OAAO;SACR,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,OAAO,GAAG,gCAAgC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAEvE,MAAM,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,OAAO,GAAG,gCAAgC,EAAE,CAAC;QAEnD,MAAM,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;YAC5D,OAAO;YACP,OAAO;YACP,OAAO;SACR,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/createPackageFilter.js

@@ -0,0 +1,81 @@
+import picomatch from "picomatch";
+import { clusterLabel } from "./clusterLabel.js";
+const scopePattern = (scope) => `${scope.startsWith("@") ? scope : `@${scope}`}/**`;
+const toPatterns = (names, scopes) => [
+    ...names,
+    ...scopes.map(scopePattern),
+];
+// picomatch throws on an empty pattern list, and "no pattern" has to mean "no
+// opinion" rather than "matches nothing".
+const compile = (patterns) => patterns.length === 0 ? () => false : picomatch(patterns);
+/**
+ * Selects the packages a dedupe run is allowed to touch. Deduplicating a large
+ * lockfile in one pass produces a diff no one reviews, so every tool exposes
+ * this as the way to work through it a family at a time.
+ *
+ * A package is selected when the include list is empty or one of its patterns
+ * matches, and no exclude pattern matches — exclusion always wins, so a scope
+ * can be selected with a few of its packages held back.
+ *
+ * Patterns are globs with path semantics (`*` stops at `/`), the same as the
+ * `why-duplicate` filters: `@babel/*` matches `@babel/core`, a bare `*` does
+ * not. npm names carry no glob metacharacter, so a plain name is still an
+ * exact match.
+ */
+export const createPackageFilter = ({ include = [], exclude = [], includeScopes = [], excludeScopes = [], } = {}) => {
+    const includePatterns = toPatterns(include, includeScopes);
+    const excludePatterns = toPatterns(exclude, excludeScopes);
+    const isIncluded = compile(includePatterns);
+    const isExcluded = compile(excludePatterns);
+    const rejectionReason = (packageName) => {
+        if (isExcluded(packageName))
+            return "excluded";
+        if (includePatterns.length > 0 && !isIncluded(packageName)) {
+            return "not selected";
+        }
+        return undefined;
+    };
+    return {
+        selectsEverything: includePatterns.length === 0 && excludePatterns.length === 0,
+        selects: (packageName) => rejectionReason(packageName) === undefined,
+        rejectionReason,
+    };
+};
+// A map keyed by package name is where the filter applies exactly: an unselected
+// package keeps every resolution it has, rather than being partly rewritten.
+export const selectPackages = (packages, filter) => filter.selectsEverything
+    ? packages
+    : Object.fromEntries(Object.entries(packages).filter(([packageName]) => filter.selects(packageName)));
+/**
+ * A cluster fix moves its whole family in lockstep, so it is kept only when
+ * every member is selected: applying it for part of a family would move the
+ * rest anyway, past the filter the user set. Select a family with a scope, or
+ * by naming all of its members.
+ */
+export const selectClusterFixes = (fixes, filter) => {
+    if (filter.selectsEverything)
+        return { selected: fixes, skipped: [] };
+    const selected = [];
+    const skipped = [];
+    for (const fix of fixes) {
+        const blockedBy = fix.members.filter((member) => !filter.selects(member));
+        if (blockedBy.length === 0) {
+            selected.push(fix);
+        }
+        else {
+            skipped.push({ fix, blockedBy });
+        }
+    }
+    return { selected, skipped };
+};
+// A family can block on a dozen members, and naming them all buries the point.
+const namedBlockers = 3;
+// Phrased for the `skipped` list of an apply plan, so both tools explain a
+// filtered-out family the same way.
+export const describeSkippedClusterFix = ({ fix, blockedBy, }) => {
+    const named = blockedBy.slice(0, namedBlockers).join(", ");
+    const rest = blockedBy.length - namedBlockers;
+    const blockers = rest > 0 ? `${named} (+${rest} more)` : named;
+    return `cluster ${clusterLabel(fix.members)}: ${blockers} not selected by the filter, and a family only converges as a whole`;
+};
+//# sourceMappingURL=createPackageFilter.js.map

package/dist/createPackageFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPackageFilter.js","sourceRoot":"","sources":["../src/createPackageFilter.ts"],"names":[],"mappings":"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"}