pm-dedup-core 2.1.0

package/src/reportColors.ts

@@ -0,0 +1,78 @@
+// Backported to node 22.13: allowed in eslint.config.js.
+import { styleText } from "node:util";
+
+// One hue for package identifiers, the scope a shade deeper than the name it
+// prefixes. `styleText` only knows the 16 named colours, hence the raw codes.
+const palette = {
+  scope: { hex: "#d75f00", ansi256: 166 },
+  packageName: { hex: "#d7875f", ansi256: 173 },
+} as const;
+
+export type PaletteStyle = keyof typeof palette;
+
+export type ReportStyle =
+  | PaletteStyle
+  | "bold"
+  | "cyan"
+  | "dim"
+  | "green"
+  | "red"
+  | "yellow";
+
+export type Colorize = (
+  styles: ReportStyle | ReportStyle[],
+  text: string,
+) => string;
+
+/**
+ * `styleText`'s own stream detection always looks at `process.stdout`, and bun
+ * has emitted escape codes regardless of it in the past. The bins run under
+ * both runtimes and also report on stderr, so the decision is taken here and
+ * `styleText` is called with `validateStream: false`.
+ */
+export const shouldColorize = (
+  stream: { isTTY?: boolean } = process.stdout,
+): boolean => {
+  const { FORCE_COLOR, NO_COLOR, TERM } = process.env;
+  if (FORCE_COLOR !== undefined && FORCE_COLOR !== "" && FORCE_COLOR !== "0") {
+    return true;
+  }
+  if (NO_COLOR !== undefined && NO_COLOR !== "") return false;
+  if (TERM === "dumb") return false;
+  return stream.isTTY === true;
+};
+
+const plain: Colorize = (_styles, text) => text;
+
+const isPaletteStyle = (style: ReportStyle): style is PaletteStyle =>
+  style in palette;
+
+// 24-bit when the terminal advertises it, the 256-colour approximation
+// otherwise.
+const paletteCode = (style: PaletteStyle): string => {
+  const { hex, ansi256 } = palette[style];
+  const { COLORTERM } = process.env;
+  if (COLORTERM !== "truecolor" && COLORTERM !== "24bit") {
+    return `38;5;${ansi256}`;
+  }
+  const channels = [1, 3, 5].map((start) =>
+    Number.parseInt(hex.slice(start, start + 2), 16),
+  );
+  return `38;2;${channels.join(";")}`;
+};
+
+// The palette colour wraps whatever `styleText` produced: its own reset (`22m`
+// for bold) leaves the colour standing, where the reverse order would not.
+const styled: Colorize = (styles, text) => {
+  const requested = Array.isArray(styles) ? styles : [styles];
+  const named = requested.filter((style) => !isPaletteStyle(style));
+  const inner =
+    named.length > 0 ? styleText(named, text, { validateStream: false }) : text;
+  const paletteStyle = requested.find(isPaletteStyle);
+  return paletteStyle === undefined
+    ? inner
+    : `\u001B[${paletteCode(paletteStyle)}m${inner}\u001B[39m`;
+};
+
+export const createColorize = (enabled: boolean): Colorize =>
+  enabled ? styled : plain;

package/src/reportText.ts

@@ -0,0 +1,58 @@
+/**
+ * The wording every report shares. Kept in one place so `why-duplicate` and the
+ * summary of a dedupe run cannot drift on how they count versions: both mean
+ * "this many remain", never "this many were merged".
+ */
+
+export const plural = (
+  count: number,
+  singular: string,
+  pluralForm: string,
+): string => `${count} ${count === 1 ? singular : pluralForm}`;
+
+/**
+ * How wide a left column may get before it starts pushing what follows off the
+ * right of the screen. A value longer than the budget keeps its own line width
+ * — the column is sized on the longest one that fits, so the outlier overflows
+ * alone instead of clamping the column below what every other row needs.
+ */
+export const maxColumnWidth = 44;
+
+// Beyond this a census stops being readable and the tail is counted instead.
+export const maxItemsListed = 5;
+
+export const columnWidth = (
+  values: string[],
+  budget: number = maxColumnWidth,
+): number =>
+  Math.max(
+    0,
+    ...values.map((value) => value.length).filter((length) => length <= budget),
+  );
+
+// padded on the plain value: the styled one carries escape codes
+export const padTo = (width: number, value: string): string =>
+  " ".repeat(Math.max(0, width - value.length));
+
+interface ListTextOptions {
+  items: string[];
+  render?: (item: string) => string;
+  limit?: number;
+  more: (rest: number) => string;
+}
+
+/**
+ * `a, b, c, +2 more` — the tail counted rather than dropped, so a truncated
+ * list never reads as a complete one.
+ */
+export const listText = ({
+  items,
+  render = (item) => item,
+  limit = maxItemsListed,
+  more,
+}: ListTextOptions): string => {
+  const listed = items.slice(0, limit);
+  const rest = items.length - listed.length;
+  const suffix = rest === 0 ? "" : more(rest);
+  return `${listed.map(render).join(", ")}${suffix}`;
+};

package/src/selectExplainedPackages.test.ts

@@ -0,0 +1,67 @@
+import { describe, it } from "bun:test";
+import { deepStrictEqual, ok, strictEqual } from "node:assert/strict";
+import { createPackageFilter } from "./createPackageFilter.ts";
+import type { PackageFilterOptions } from "./createPackageFilter.ts";
+import { selectExplainedPackages } from "./selectExplainedPackages.ts";
+
+const packagesMap: Record<string, string[]> = {
+  metro: ["metro@0.84.5", "metro@0.87.0"],
+  lodash: ["lodash@4.17.21"],
+  semver: ["semver@7.6.0"],
+};
+
+const select = (
+  filterOptions: PackageFilterOptions,
+  all = false,
+): ReturnType<typeof selectExplainedPackages<string[]>> =>
+  selectExplainedPackages({
+    packagesMap,
+    filter: createPackageFilter(filterOptions),
+    all,
+  });
+
+describe("selectExplainedPackages", () => {
+  it("keeps only the duplicated packages of the selection", () => {
+    const { packages, title, notice } = select({});
+    deepStrictEqual(Object.keys(packages), ["metro"]);
+    strictEqual(title, "duplicates");
+    strictEqual(notice, undefined);
+  });
+
+  it("keeps a named package that is not duplicated, to show its dependents", () => {
+    const { packages, title, notice } = select({ include: ["lodash"] });
+    deepStrictEqual(Object.keys(packages), ["lodash"]);
+    strictEqual(title, "matches");
+    strictEqual(notice, "lodash is not duplicated. Showing its dependents:");
+  });
+
+  it("names every match when several are selected and none is duplicated", () => {
+    const { packages, notice } = select({ include: ["lodash", "semver"] });
+    deepStrictEqual(Object.keys(packages), ["lodash", "semver"]);
+    ok(notice?.startsWith("None of the 2 matches is duplicated"));
+    ok(notice?.includes("lodash, semver"));
+  });
+
+  it("drops the single-version matches as soon as one selection is duplicated", () => {
+    const { packages, title, notice } = select({
+      include: ["lodash", "metro"],
+    });
+    deepStrictEqual(Object.keys(packages), ["metro"]);
+    strictEqual(title, "duplicates");
+    strictEqual(notice, undefined);
+  });
+
+  it("reports nothing for a package the lockfile does not hold", () => {
+    const { packages, title, notice } = select({ include: ["missing"] });
+    deepStrictEqual(Object.keys(packages), []);
+    strictEqual(title, "duplicates");
+    strictEqual(notice, undefined);
+  });
+
+  it("keeps every match under --all without a notice", () => {
+    const { packages, title, notice } = select({}, true);
+    deepStrictEqual(Object.keys(packages), ["metro", "lodash", "semver"]);
+    strictEqual(title, "matches");
+    strictEqual(notice, undefined);
+  });
+});

package/src/selectExplainedPackages.ts

@@ -0,0 +1,79 @@
+import type { PackageFilter } from "./createPackageFilter.ts";
+import type { DuplicatesReportTitle } from "./renderDuplicatesReport.ts";
+import { listText, plural } from "./reportText.ts";
+
+export interface SelectExplainedPackagesOptions<
+  Resolutions extends readonly unknown[],
+> {
+  // every package the lockfile holds, keyed by name
+  packagesMap: Record<string, Resolutions>;
+  filter: PackageFilter;
+  // keeps packages the lockfile resolves only once, which a listing drops
+  all: boolean;
+}
+
+export interface ExplainedPackagesSelection<
+  Resolutions extends readonly unknown[],
+> {
+  packages: Record<string, Resolutions>;
+  title: DuplicatesReportTitle;
+  // headline replacing "No duplicates found", for the selection kept for its
+  // dependents alone
+  notice: string | undefined;
+}
+
+const singleVersionNotice = (names: string[]): string => {
+  const shown = listText({
+    items: names,
+    more: (rest) => `, +${rest} more`,
+  });
+  return names.length === 1
+    ? `${shown} is not duplicated. Showing its dependents:`
+    : `None of the ${plural(names.length, "match", "matches")} is duplicated (${shown}). Showing their dependents:`;
+};
+
+/**
+ * The packages a `why-duplicate` run reports on. Naming a package is asking why
+ * it is duplicated, and the honest answer to "it is not" is its dependents, not
+ * an empty report: a selection holding no duplicate is kept whole, and the
+ * notice says why it is being shown.
+ *
+ * `--all` asks for that unconditionally, so it never needs the fallback.
+ */
+export const selectExplainedPackages = <
+  Resolutions extends readonly unknown[],
+>({
+  packagesMap,
+  filter,
+  all,
+}: SelectExplainedPackagesOptions<Resolutions>): ExplainedPackagesSelection<Resolutions> => {
+  const selected = Object.entries(packagesMap).filter(([packageName]) =>
+    filter.selects(packageName),
+  );
+
+  if (all) {
+    return {
+      packages: Object.fromEntries(selected),
+      title: "matches",
+      notice: undefined,
+    };
+  }
+
+  const duplicated = selected.filter(
+    ([, resolutions]) => resolutions.length > 1,
+  );
+
+  if (duplicated.length > 0 || selected.length === 0) {
+    return {
+      packages: Object.fromEntries(duplicated),
+      title: "duplicates",
+      notice: undefined,
+    };
+  }
+
+  return {
+    packages: Object.fromEntries(selected),
+    title: "matches",
+    notice: singleVersionNotice(selected.map(([packageName]) => packageName)),
+  };
+};

package/src/unconditionalOverrides.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "bun:test";
+import type {
+  ClusterExternalConstraint,
+  ClusterFix,
+  PlannedOverride,
+} from "./index.ts";
+import { partitionUnconditionalOverrides } from "./unconditionalOverrides.ts";
+
+const constraint = (range: string): ClusterExternalConstraint => ({
+  requester: "requester",
+  requesterName: "requester",
+  packageName: "lib",
+  range,
+});
+
+const workspaceConstraint = (range: string): ClusterExternalConstraint => ({
+  ...constraint(range),
+  requester: "package.json in dependencies",
+  requesterName: undefined,
+});
+
+// only `externalConstraints` is read; the rest is an empty cluster
+const fixWith = (constraints: ClusterExternalConstraint[]): ClusterFix => ({
+  members: ["lib"],
+  duplicatedMembers: ["lib"],
+  memberVersions: {},
+  target: null,
+  direction: "none",
+  convergentMembers: [],
+  driverMembers: [],
+  excludedMembers: [],
+  anchor: null,
+  reuseFixes: [],
+  floatingMembers: [],
+  workspaceChanges: [],
+  reResolutionSet: [],
+  externalConstraints: constraints,
+  needsRoundTrip: false,
+  applicable: false,
+});
+
+const override: PlannedOverride = {
+  packageName: "lib",
+  version: "2.0.0",
+  reason: "converge",
+};
+
+describe("partitionUnconditionalOverrides", () => {
+  it("rejects an override a third-party range does not accept", () => {
+    const { safe, rejected } = partitionUnconditionalOverrides(
+      [fixWith([constraint("^1.0.0")])],
+      [override],
+    );
+
+    expect(safe).toEqual([]);
+    expect(rejected).toEqual([
+      { override, rejectedBy: [constraint("^1.0.0")] },
+    ]);
+  });
+
+  it("keeps an override every range accepts", () => {
+    const { safe, rejected } = partitionUnconditionalOverrides(
+      [fixWith([constraint("^2.0.0")])],
+      [override],
+    );
+
+    expect(safe).toEqual([override]);
+    expect(rejected).toEqual([]);
+  });
+
+  // `semver.satisfies` answers `false` for a range it cannot read rather than
+  // throwing, so a selector naming something other than a version — which says
+  // nothing about the version at all — would otherwise reject every override.
+  it("keeps an override against a selector semver cannot read", () => {
+    const { safe, rejected } = partitionUnconditionalOverrides(
+      [
+        fixWith([
+          constraint("workspace:*"),
+          constraint("git+ssh://git@host/r.git#v1"),
+          constraint("catalog:default"),
+        ]),
+      ],
+      [override],
+    );
+
+    expect(safe).toEqual([override]);
+    expect(rejected).toEqual([]);
+  });
+
+  // A workspace range belongs to the user, who is the one asking for the dedupe.
+  it("ignores a workspace constraint", () => {
+    const { safe } = partitionUnconditionalOverrides(
+      [fixWith([workspaceConstraint("^1.0.0")])],
+      [override],
+    );
+
+    expect(safe).toEqual([override]);
+  });
+});

package/src/unconditionalOverrides.ts

@@ -0,0 +1,60 @@
+import semver from "semver";
+import type {
+  ClusterExternalConstraint,
+  ClusterFix,
+} from "./identifyLockstepClusterFixes.ts";
+import type { PlannedOverride } from "./planClusterApply.ts";
+
+export interface RejectedOverride {
+  override: PlannedOverride;
+  rejectedBy: ClusterExternalConstraint[];
+}
+
+export interface PartitionedOverrides {
+  safe: PlannedOverride[];
+  rejected: RejectedOverride[];
+}
+
+// A selector semver cannot read (`workspace:`, a git url) says nothing about the
+// version, so it is no reason to drop the override. `semver.satisfies` answers
+// `false` rather than throwing on one, hence the explicit check.
+const accepts = (version: string, range: string): boolean =>
+  semver.validRange(range) === null ||
+  semver.satisfies(version, range, { includePrerelease: true });
+
+/**
+ * Split the planned overrides for a package manager whose overrides apply to
+ * every requester of the package, whatever range it declares (bun's
+ * `overrides`, pnpm's plain ones). Such an override cannot spare the dependents
+ * a conditional one would — pnpm's convergence overrides only repoint the edges
+ * that accept the version — so one a third-party range rejects would force that
+ * dependent onto a version it never allowed.
+ *
+ * The `converge` overrides are safe by construction: the detector only converges
+ * a member no third-party range holds elsewhere. A `reuse` override is derived
+ * from a single requester's range, and another requester can still reject it.
+ */
+export const partitionUnconditionalOverrides = (
+  fixes: ClusterFix[],
+  overrides: PlannedOverride[],
+): PartitionedOverrides => {
+  const constraints = fixes.flatMap((fix) => fix.externalConstraints);
+  const safe: PlannedOverride[] = [];
+  const rejected: RejectedOverride[] = [];
+
+  for (const override of overrides) {
+    const rejectedBy = constraints.filter(
+      (constraint) =>
+        constraint.packageName === override.packageName &&
+        constraint.requesterName !== undefined &&
+        !accepts(override.version, constraint.range),
+    );
+    if (rejectedBy.length === 0) {
+      safe.push(override);
+    } else {
+      rejected.push({ override, rejectedBy });
+    }
+  }
+
+  return { safe, rejected };
+};

package/src/versionsSnapshot.test.ts

@@ -0,0 +1,146 @@
+import { describe, it } from "bun:test";
+import { deepStrictEqual, strictEqual } from "node:assert/strict";
+import {
+  buildVersionsSnapshot,
+  countDuplicatedPackages,
+  diffVersionsSnapshots,
+} from "./versionsSnapshot.ts";
+import type { SnapshotPackage, VersionsSnapshot } from "./versionsSnapshot.ts";
+
+const npm = (name: string, version: string): SnapshotPackage => ({
+  type: "npm",
+  name,
+  version,
+  resolution: `${name}@${version}`,
+});
+
+const snapshot = (entries: Record<string, string[]>): VersionsSnapshot =>
+  new Map(Object.entries(entries));
+
+describe("buildVersionsSnapshot", () => {
+  it("groups versions per package, sorted by semver", () => {
+    deepStrictEqual(
+      [
+        ...buildVersionsSnapshot([
+          npm("semver", "7.10.0"),
+          npm("semver", "7.9.0"),
+          npm("lodash", "4.17.21"),
+        ]),
+      ],
+      [
+        ["semver", ["7.9.0", "7.10.0"]],
+        ["lodash", ["4.17.21"]],
+      ],
+    );
+  });
+
+  it("counts one version per resolution, whatever it is installed at", () => {
+    deepStrictEqual(
+      buildVersionsSnapshot([npm("semver", "7.9.0"), npm("semver", "7.9.0")]),
+      snapshot({ semver: ["7.9.0"] }),
+    );
+  });
+
+  it("identifies a non-npm package by its resolution", () => {
+    deepStrictEqual(
+      buildVersionsSnapshot([
+        { type: "git", name: "psc", resolution: "psc@git:abcdef" },
+      ]),
+      snapshot({ psc: ["psc@git:abcdef"] }),
+    );
+  });
+});
+
+describe("diffVersionsSnapshots", () => {
+  it("keeps both sides whole, so the collapse reads as one", () => {
+    deepStrictEqual(
+      diffVersionsSnapshots(
+        snapshot({ "range-parser": ["1.2.1", "1.3.0"] }),
+        snapshot({ "range-parser": ["1.2.1"] }),
+      ),
+      [
+        {
+          packageName: "range-parser",
+          before: ["1.2.1", "1.3.0"],
+          after: ["1.2.1"],
+        },
+      ],
+    );
+  });
+
+  it("reports a package only partly collapsed with what is left", () => {
+    deepStrictEqual(
+      diffVersionsSnapshots(
+        snapshot({ semver: ["7.5.4", "7.6.0", "7.7.1"] }),
+        snapshot({ semver: ["7.6.0", "7.7.1"] }),
+      ),
+      [
+        {
+          packageName: "semver",
+          before: ["7.5.4", "7.6.0", "7.7.1"],
+          after: ["7.6.0", "7.7.1"],
+        },
+      ],
+    );
+  });
+
+  it("says nothing of a package whose versions did not move", () => {
+    deepStrictEqual(
+      diffVersionsSnapshots(
+        snapshot({ semver: ["7.7.1"] }),
+        snapshot({ semver: ["7.7.1"], lodash: ["4.17.21"] }),
+      ),
+      [],
+    );
+  });
+
+  // the cluster pass that made the edit reports it; no copy went away, so it is
+  // not a dedupe
+  it("says nothing of a version that moved without a copy going away", () => {
+    deepStrictEqual(
+      diffVersionsSnapshots(
+        snapshot({ metro: ["0.84.5"] }),
+        snapshot({ metro: ["0.87.0"] }),
+      ),
+      [],
+    );
+  });
+
+  // the rewritten copy drops the private subtrees of the versions it replaced,
+  // and the next install resolves them again: gone from the lockfile is not
+  // deduplicated
+  it("says nothing of a package that left the lockfile entirely", () => {
+    deepStrictEqual(
+      diffVersionsSnapshots(
+        snapshot({ "metro-config": ["0.84.5"] }),
+        snapshot({}),
+      ),
+      [],
+    );
+  });
+
+  it("sorts the entries by package name", () => {
+    deepStrictEqual(
+      diffVersionsSnapshots(
+        snapshot({ semver: ["1.0.0", "2.0.0"], lodash: ["3.0.0", "4.0.0"] }),
+        snapshot({ semver: ["2.0.0"], lodash: ["4.0.0"] }),
+      ).map((entry) => entry.packageName),
+      ["lodash", "semver"],
+    );
+  });
+});
+
+describe("countDuplicatedPackages", () => {
+  it("counts the packages resolved more than once", () => {
+    strictEqual(
+      countDuplicatedPackages(
+        snapshot({
+          semver: ["7.5.4", "7.7.1"],
+          lodash: ["4.17.21"],
+          react: ["18.0.0", "19.0.0"],
+        }),
+      ),
+      2,
+    );
+  });
+});

package/src/versionsSnapshot.ts

@@ -0,0 +1,93 @@
+import semver from "semver";
+
+/**
+ * Every version a package resolves to in a lockfile, by package name.
+ *
+ * The duplicate snapshot only carries the resolutions of packages that have
+ * several, so it cannot name the version a merge landed on: once a package is
+ * deduplicated it leaves the snapshot altogether. Saying what a run deduped
+ * needs the whole picture, before and after.
+ */
+export type VersionsSnapshot = Map<string, string[]>;
+
+/**
+ * The shape every package manager's parsed package already has. `version` is
+ * only there for npm resolutions — a `git:` or `file:` copy is identified by its
+ * resolution instead, which is unique per install just the same.
+ */
+export interface SnapshotPackage {
+  type: string;
+  name: string;
+  resolution: string;
+  version?: string;
+}
+
+const versionLabel = (pkg: SnapshotPackage): string =>
+  pkg.type === "npm" && pkg.version !== undefined && pkg.version !== ""
+    ? pkg.version
+    : pkg.resolution;
+
+const compareVersions = (a: string, b: string): number =>
+  semver.valid(a) !== null && semver.valid(b) !== null
+    ? semver.compare(a, b)
+    : a.localeCompare(b);
+
+export const buildVersionsSnapshot = (
+  packages: Iterable<SnapshotPackage>,
+): VersionsSnapshot => {
+  const snapshot: VersionsSnapshot = new Map();
+
+  for (const pkg of packages) {
+    const version = versionLabel(pkg);
+    const versions = snapshot.get(pkg.name);
+    if (versions === undefined) {
+      snapshot.set(pkg.name, [version]);
+    } else if (!versions.includes(version)) {
+      versions.push(version);
+    }
+  }
+
+  for (const versions of snapshot.values()) versions.sort(compareVersions);
+
+  return snapshot;
+};
+
+export interface DedupedPackage {
+  packageName: string;
+  // every version it resolved to before the run
+  before: string[];
+  // every version it resolves to now, fewer than before
+  after: string[];
+}
+
+/**
+ * What the two snapshots say a run collapsed, one entry per package: both sides
+ * whole, so a family converging on an older release reads as the two copies
+ * becoming one rather than as a downgrade.
+ *
+ * Only a package resolved fewer times than before is reported. A version that
+ * moved without a copy going away is a re-resolution, not a dedupe — the pass
+ * that made the edit already said so — and a package that left the lockfile
+ * entirely is neither: the in-memory rewrite drops the private subtrees of the
+ * versions it replaced, entries the next install resolves again.
+ */
+export const diffVersionsSnapshots = (
+  before: VersionsSnapshot,
+  after: VersionsSnapshot,
+): DedupedPackage[] => {
+  const deduped: DedupedPackage[] = [];
+
+  for (const [packageName, versions] of before) {
+    const remaining = after.get(packageName);
+    if (remaining === undefined || remaining.length === 0) continue;
+    if (remaining.length >= versions.length) continue;
+
+    deduped.push({ packageName, before: versions, after: remaining });
+  }
+
+  return deduped.toSorted((a, b) => a.packageName.localeCompare(b.packageName));
+};
+
+// Packages the lockfile still resolves more than once.
+export const countDuplicatedPackages = (snapshot: VersionsSnapshot): number =>
+  [...snapshot.values()].filter((versions) => versions.length > 1).length;