pm-dedup-core 2.1.0

package/dist/workspaceManifest.test.js

@@ -0,0 +1,159 @@
+import { describe, it } from "bun:test";
+import { strictEqual } from "node:assert/strict";
+import { applyWorkspaceRangeEdit, nextSelector } from "./workspaceManifest.js";
+const manifest = [
+    "{",
+    '  "name": "root",',
+    '  "dependencies": {',
+    '    "metro": "0.84.5"',
+    "  },",
+    '  "devDependencies": {',
+    '    "metro": "^0.84.5",',
+    '    "lodash.merge": "~4.6.0",',
+    '    "aliased": "npm:metro@^0.84.5"',
+    "  }",
+    "}",
+    "",
+].join("\n");
+// a block whose other declarations carry protocols the parser has no list for:
+// they have to parse so the target rewrite is not aborted by a neighbour
+const manifestWithProtocols = [
+    "{",
+    '  "name": "root",',
+    '  "dependencies": {',
+    '    "local": "workspace:^1.0.0",',
+    '    "vendored": "someproto:whatever",',
+    '    "forked": "git+ssh://git@host/r.git#v1",',
+    '    "metro": "^0.84.5"',
+    "  }",
+    "}",
+    "",
+].join("\n");
+describe("nextSelector", () => {
+    it("keeps a caret or tilde on the target line", () => {
+        strictEqual(nextSelector("^0.84.5", "0.87.0"), "^0.87.0");
+        strictEqual(nextSelector("~4.6.0", "4.7.1"), "~4.7.1");
+    });
+    it("pins exactly when the range has no target-line equivalent", () => {
+        strictEqual(nextSelector("0.84.5", "0.87.0"), "0.87.0");
+        strictEqual(nextSelector("*", "0.87.0"), "0.87.0");
+        strictEqual(nextSelector("0.83 - 0.86", "0.87.0"), "0.87.0");
+        strictEqual(nextSelector("^0.83 - 0.86", "0.87.0"), "0.87.0");
+    });
+});
+describe("applyWorkspaceRangeEdit", () => {
+    it("edits only the declaration in the requested depType", () => {
+        strictEqual(applyWorkspaceRangeEdit(manifest, {
+            packageName: "metro",
+            depType: "devDependencies",
+            range: "^0.84.5",
+            to: "0.87.0",
+        }), manifest.replace('"metro": "^0.84.5"', '"metro": "^0.87.0"'));
+    });
+    it("edits the exact pin in dependencies without touching devDependencies", () => {
+        strictEqual(applyWorkspaceRangeEdit(manifest, {
+            packageName: "metro",
+            depType: "dependencies",
+            range: "0.84.5",
+            to: "0.87.0",
+        }), manifest.replace('"metro": "0.84.5"', '"metro": "0.87.0"'));
+    });
+    it("keeps the npm: alias prefix", () => {
+        strictEqual(applyWorkspaceRangeEdit(manifest, {
+            packageName: "metro",
+            depType: "devDependencies",
+            range: "^0.84.5",
+            to: "0.87.0",
+        })?.includes('"aliased": "npm:metro@^0.84.5"'), true);
+        strictEqual(applyWorkspaceRangeEdit(manifest, {
+            packageName: "metro",
+            depType: "devDependencies",
+            range: "^0.84.5",
+            to: "0.87.0",
+        })?.includes('"metro": "^0.87.0"'), true);
+    });
+    it("matches a dotted name literally", () => {
+        strictEqual(applyWorkspaceRangeEdit(manifest, {
+            packageName: "lodash.merge",
+            depType: "devDependencies",
+            range: "~4.6.0",
+            to: "4.7.1",
+        }), manifest.replace('"lodash.merge": "~4.6.0"', '"lodash.merge": "~4.7.1"'));
+    });
+    it("rewrites past siblings declared with protocols it does not know", () => {
+        strictEqual(applyWorkspaceRangeEdit(manifestWithProtocols, {
+            packageName: "metro",
+            depType: "dependencies",
+            range: "^0.84.5",
+            to: "0.87.0",
+        }), manifestWithProtocols.replace('"metro": "^0.84.5"', '"metro": "^0.87.0"'));
+    });
+    // the range reaches here already stripped of its protocol, and `stringify`
+    // puts it back: rewriting `workspace:^1.0.0` to a bare `2.0.0` would change
+    // which package the declaration points at
+    it("keeps a workspace protocol on the rewritten declaration", () => {
+        strictEqual(applyWorkspaceRangeEdit(manifestWithProtocols, {
+            packageName: "local",
+            depType: "dependencies",
+            range: "^1.0.0",
+            to: "2.0.0",
+        }), manifestWithProtocols.replace('"local": "workspace:^1.0.0"', '"local": "workspace:^2.0.0"'));
+    });
+    it("edits an aliased declaration through its own key", () => {
+        strictEqual(applyWorkspaceRangeEdit([
+            "{",
+            '  "dependencies": {',
+            '    "aliased": "npm:metro@^0.84.5"',
+            "  }",
+            "}",
+            "",
+        ].join("\n"), {
+            packageName: "metro",
+            depType: "dependencies",
+            range: "^0.84.5",
+            to: "0.87.0",
+        })?.includes('"aliased": "npm:metro@^0.87.0"'), true);
+    });
+    // The manifest key `typescript` is an alias for another package entirely,
+    // while the real `typescript` is reached through `@typescript/native`. Keying
+    // the rewrite on the package name would edit the wrong line in both
+    // directions.
+    it("edits the key an alias reaches the package through, not its namesake", () => {
+        const swapped = [
+            "{",
+            '  "devDependencies": {',
+            '    "@typescript/native": "npm:typescript@^7.0.0",',
+            '    "typescript": "npm:@typescript/typescript6@6.0.2"',
+            "  }",
+            "}",
+            "",
+        ].join("\n");
+        strictEqual(applyWorkspaceRangeEdit(swapped, {
+            packageName: "typescript",
+            depType: "devDependencies",
+            range: "^7.0.0",
+            to: "7.1.0",
+        }), swapped.replace('"npm:typescript@^7.0.0"', '"npm:typescript@^7.1.0"'));
+        strictEqual(applyWorkspaceRangeEdit(swapped, {
+            packageName: "@typescript/typescript6",
+            depType: "devDependencies",
+            range: "6.0.2",
+            to: "6.1.0",
+        }), swapped.replace('"npm:@typescript/typescript6@6.0.2"', '"npm:@typescript/typescript6@6.1.0"'));
+    });
+    it("reports a declaration that moved on since the lockfile was read", () => {
+        strictEqual(applyWorkspaceRangeEdit(manifest, {
+            packageName: "metro",
+            depType: "devDependencies",
+            range: "^0.80.0",
+            to: "0.87.0",
+        }), undefined);
+        strictEqual(applyWorkspaceRangeEdit(manifest, {
+            packageName: "metro",
+            depType: "optionalDependencies",
+            range: "^0.84.5",
+            to: "0.87.0",
+        }), undefined);
+    });
+});
+//# sourceMappingURL=workspaceManifest.test.js.map

package/dist/workspaceManifest.test.js.map

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

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "pm-dedup-core",
+  "version": "2.1.0",
+  "description": "package manager utils",
+  "keywords": [],
+  "homepage": "https://github.com/christophehurpeau/pm-tools",
+  "bugs": {
+    "url": "https://github.com/christophehurpeau/pm-tools/issues"
+  },
+  "license": "MIT",
+  "author": "Christophe Hurpeau <christophe@hurpeau.com> (https://christophe.hurpeau.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/christophehurpeau/pm-tools.git",
+    "directory": "packages/pm-dedup-core"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/definitions/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/definitions/index.d.ts",
+      "node": {
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "bun run lint:oxlint && bun run lint:eslint",
+    "lint:eslint": "bun run --cwd '../..' eslint --quiet 'packages/pm-dedup-core'",
+    "lint:oxlint": "bun run --cwd '../..' oxlint --quiet 'packages/pm-dedup-core'",
+    "test": "bun run --cwd '../..' test -- 'packages/pm-dedup-core'",
+    "tsc": "tsc"
+  },
+  "dependencies": {
+    "picomatch": "4.0.7",
+    "semver": "7.8.5",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.2",
+    "@types/picomatch": "4.0.3",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "typescript": "npm:@typescript/typescript6@6.0.2"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "pob": {
+    "bundler": "tsc",
+    "entries": [
+      "index"
+    ],
+    "envs": [
+      {
+        "target": "node",
+        "version": "22"
+      }
+    ]
+  }
+}

package/src/buildIdentifiedFixesMap.ts

@@ -0,0 +1,22 @@
+import {
+  type ResolutionDependent,
+  type ResolutionDependentsMap,
+  type ResolutionEntry,
+  type ResolutionFix,
+  identifyResolutionFixes,
+} from "./identifyResolutionFixes.ts";
+
+export type ResolutionsMap = Record<string, ResolutionEntry[]>;
+
+export const buildIdentifiedFixesMap = <D extends ResolutionDependent>(
+  duplicatesResolutionsMap: ResolutionsMap,
+  dependents: ResolutionDependentsMap<D>,
+): Map<string, ResolutionFix[]> =>
+  new Map<string, ResolutionFix[]>(
+    Object.entries(duplicatesResolutionsMap).map(
+      ([packageName, resolutions]) => [
+        packageName,
+        identifyResolutionFixes(resolutions, dependents),
+      ],
+    ),
+  );

package/src/buildLockstepClusters.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "bun:test";
+import {
+  type LockstepGraph,
+  buildLockstepClusters,
+} from "./buildLockstepClusters.ts";
+
+const npm = (
+  version: string,
+  dependencies: Record<string, string> = {},
+): { version: string; isNpm: true; dependencies: Record<string, string> } => ({
+  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: LockstepGraph = {
+      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: LockstepGraph = {
+      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: LockstepGraph = {
+      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: LockstepGraph = {
+      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: LockstepGraph = {
+      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: LockstepGraph = {
+      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"]]);
+  });
+});

package/src/buildLockstepClusters.ts

@@ -0,0 +1,155 @@
+import semver from "semver";
+
+// One installed resolution of a package, reduced to what cluster detection
+// needs. `dependencies` maps a dependency name to either a requested range
+// (bun stores `^8.61.0`) or a resolved version (pnpm snapshots store `8.61.0`);
+// both are handled by anchoring on the minimum version.
+export interface LockstepResolution {
+  version: string;
+  isNpm: boolean;
+  dependencies: Record<string, string>;
+}
+
+// name -> installed resolutions. Package-manager packages adapt their own
+// lockfile model into this neutral shape.
+export type LockstepGraph = Record<string, LockstepResolution[]>;
+
+interface UnionFind {
+  find: (value: string) => string;
+  union: (a: string, b: string) => void;
+}
+
+const createUnionFind = (names: string[]): UnionFind => {
+  const parent = new Map<string, string>(names.map((name) => [name, name]));
+
+  const find = (value: string): string => {
+    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: string, b: string): void => {
+    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: LockstepGraph): Map<string, Set<string>> => {
+  const versionsByName = new Map<string, Set<string>>();
+
+  for (const [name, resolutions] of Object.entries(graph)) {
+    const versions = new Set<string>();
+    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: string,
+  range: string,
+  depVersions: Set<string>,
+): boolean => {
+  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: LockstepGraph): string[][] => {
+  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<
+      string,
+      { version: string; range: string }[]
+    >();
+
+    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<string>();
+      const allCoVersion = observations.every((observation) =>
+        isCoVersion(observation.version, observation.range, depVersions),
+      );
+      if (allCoVersion) {
+        unionFind.union(name, depName);
+      }
+    }
+  }
+
+  const componentsByRoot = new Map<string, string[]>();
+  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]!));
+};

package/src/clusterLabel.test.ts

@@ -0,0 +1,79 @@
+import { describe, it } from "bun:test";
+import { strictEqual } from "node:assert/strict";
+import { clusterLabel } from "./clusterLabel.ts";
+
+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([]), "");
+  });
+});

package/src/clusterLabel.ts

@@ -0,0 +1,75 @@
+const leadingPrefixes = (member: string): string[] => {
+  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: string, member: string): boolean =>
+  member === prefix ||
+  member.startsWith(`${prefix}-`) ||
+  member.startsWith(`${prefix}/`);
+
+interface PrefixGroup {
+  prefix: string;
+  covered: string[];
+}
+
+/**
+ * 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: string[]): PrefixGroup | null => {
+  const candidates = [...new Set(members.flatMap(leadingPrefixes))];
+
+  let best: PrefixGroup | null = 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 }: PrefixGroup): string => {
+  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: string[]): string => {
+  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)`;
+};