pm-dedup-core 2.1.0

package/src/planClusterApply.test.ts

@@ -0,0 +1,163 @@
+import { describe, it } from "bun:test";
+import { deepStrictEqual } from "node:assert/strict";
+import type { ClusterFix } from "./identifyLockstepClusterFixes.ts";
+import { planClusterApply } from "./planClusterApply.ts";
+
+const fix = (overrides: Partial<ClusterFix>): ClusterFix => ({
+  members: [],
+  duplicatedMembers: [],
+  memberVersions: {},
+  target: null,
+  direction: "none",
+  convergentMembers: [],
+  driverMembers: [],
+  excludedMembers: [],
+  anchor: null,
+  reuseFixes: [],
+  floatingMembers: [],
+  workspaceChanges: [],
+  reResolutionSet: [],
+  externalConstraints: [],
+  needsRoundTrip: false,
+  applicable: false,
+  ...overrides,
+});
+
+describe("planClusterApply", () => {
+  it("edits the importer the workspace change points at", () => {
+    const plan = planClusterApply([
+      fix({
+        applicable: true,
+        target: "0.87.0",
+        workspaceChanges: [
+          {
+            requester: "package.json in devDependencies",
+            requesterName: undefined,
+            packageName: "metro",
+            range: "0.84.5",
+            to: "0.87.0",
+            workspace: { path: ".", depType: "devDependencies" },
+          },
+        ],
+      }),
+    ]);
+
+    deepStrictEqual(plan.manifestEdits, [
+      {
+        importerPath: ".",
+        depType: "devDependencies",
+        packageName: "metro",
+        range: "0.84.5",
+        to: "0.87.0",
+      },
+    ]);
+    deepStrictEqual(plan.unresolvableChanges, []);
+  });
+
+  it("reports a workspace change it cannot locate on disk", () => {
+    const plan = planClusterApply([
+      fix({
+        applicable: true,
+        target: "0.87.0",
+        workspaceChanges: [
+          {
+            requester: "package.json in devDependencies",
+            requesterName: undefined,
+            packageName: "metro",
+            range: "0.84.5",
+            to: "0.87.0",
+          },
+        ],
+      }),
+    ]);
+
+    deepStrictEqual(plan.manifestEdits, []);
+    deepStrictEqual(plan.unresolvableChanges, [
+      "metro in package.json in devDependencies",
+    ]);
+  });
+
+  it("overrides the convergent members and the ones to re-resolve", () => {
+    const plan = planClusterApply([
+      fix({
+        applicable: true,
+        target: "8.59.1",
+        convergentMembers: ["@typescript-eslint/types"],
+        reResolutionSet: ["@typescript-eslint/parser"],
+        // spared by construction: a convergence override skips the edges whose
+        // declared range rejects the target
+        excludedMembers: [
+          { packageName: "@typescript-eslint/utils", blockedBy: [] },
+        ],
+      }),
+    ]);
+
+    deepStrictEqual(plan.overrides, [
+      {
+        packageName: "@typescript-eslint/parser",
+        version: "8.59.1",
+        reason: "converge",
+      },
+      {
+        packageName: "@typescript-eslint/types",
+        version: "8.59.1",
+        reason: "converge",
+      },
+    ]);
+  });
+
+  it("lets the anchored reuse win over a computed target", () => {
+    const plan = planClusterApply([
+      fix({
+        applicable: true,
+        target: "0.87.0",
+        convergentMembers: ["mini-metro-config"],
+        anchor: "0.84.5",
+        reuseFixes: [
+          {
+            requester: "mini-plugin@1.0.0",
+            requesterName: "mini-plugin",
+            packageName: "mini-metro-config",
+            range: "*",
+            from: "0.87.0",
+            to: "0.84.5",
+          },
+        ],
+      }),
+    ]);
+
+    deepStrictEqual(plan.overrides, [
+      {
+        packageName: "mini-metro-config",
+        version: "0.84.5",
+        reason: "reuse",
+      },
+    ]);
+    deepStrictEqual(plan.conflicts, [
+      { packageName: "mini-metro-config", kept: "0.84.5", dropped: "0.87.0" },
+    ]);
+  });
+
+  it("ignores a cluster with no applicable fix but keeps its reuse fixes", () => {
+    const plan = planClusterApply([
+      fix({
+        applicable: false,
+        convergentMembers: ["ignored"],
+        reuseFixes: [
+          {
+            requester: "plugin@1",
+            requesterName: "plugin",
+            packageName: "leaf",
+            range: "*",
+            from: "2.0.0",
+            to: "1.0.0",
+          },
+        ],
+      }),
+    ]);
+
+    deepStrictEqual(plan.overrides, [
+      { packageName: "leaf", version: "1.0.0", reason: "reuse" },
+    ]);
+  });
+});

package/src/planClusterApply.ts

@@ -0,0 +1,105 @@
+import type { ClusterFix } from "./identifyLockstepClusterFixes.ts";
+import type { WorkspaceRangeEdit } from "./workspaceManifest.ts";
+
+export interface PlannedManifestEdit extends WorkspaceRangeEdit {
+  importerPath: string;
+}
+
+export interface PlannedOverride {
+  packageName: string;
+  version: string;
+  // why it is proposed, for the log and for the diagnostic on a failed verify
+  reason: "converge" | "reuse";
+}
+
+export interface ClusterApplyPlan {
+  manifestEdits: PlannedManifestEdit[];
+  overrides: PlannedOverride[];
+  // a package two clusters want at different versions: the first one wins and
+  // the loser is reported rather than silently dropped
+  conflicts: { packageName: string; kept: string; dropped: string }[];
+  // workspace changes carrying no importer reference, which cannot be applied
+  unresolvableChanges: string[];
+}
+
+/**
+ * Turn the detector's records into the two edits every package manager
+ * understands:
+ *
+ * - a `workspaceChanges` entry is a range the user declares, so it is edited in
+ *   place in the importer's `package.json`;
+ * - everything else is a transitive edge, which only an override can repoint.
+ *
+ * The overrides are per package name and carry no scoping: a package manager
+ * whose overrides apply unconditionally (bun) has to drop the ones a third-party
+ * range would reject, where one with conditional overrides (pnpm's convergence
+ * overrides) can write them all and let the resolver spare the members
+ * `excludedMembers` lists.
+ *
+ * `reuseFixes` come first: they converge on `anchor`, the version the user
+ * pinned, and a pin outranks a version the detector merely computed.
+ */
+export const planClusterApply = (fixes: ClusterFix[]): ClusterApplyPlan => {
+  const manifestEdits: PlannedManifestEdit[] = [];
+  const unresolvableChanges: string[] = [];
+  const conflicts: ClusterApplyPlan["conflicts"] = [];
+  const overrides = new Map<string, PlannedOverride>();
+
+  const addOverride = (
+    packageName: string,
+    version: string,
+    reason: PlannedOverride["reason"],
+  ): void => {
+    const existing = overrides.get(packageName);
+    if (existing) {
+      if (existing.version !== version) {
+        conflicts.push({
+          packageName,
+          kept: existing.version,
+          dropped: version,
+        });
+      }
+      return;
+    }
+    overrides.set(packageName, { packageName, version, reason });
+  };
+
+  for (const fix of fixes) {
+    for (const reuse of fix.reuseFixes) {
+      addOverride(reuse.packageName, reuse.to, "reuse");
+    }
+  }
+
+  for (const fix of fixes) {
+    if (!fix.applicable || fix.target === null) continue;
+
+    for (const change of fix.workspaceChanges) {
+      if (!change.workspace) {
+        unresolvableChanges.push(
+          `${change.packageName} in ${change.requester}`,
+        );
+        continue;
+      }
+      manifestEdits.push({
+        importerPath: change.workspace.path,
+        depType: change.workspace.depType,
+        packageName: change.packageName,
+        range: change.range,
+        to: change.to,
+      });
+    }
+
+    for (const member of [...fix.convergentMembers, ...fix.reResolutionSet]) {
+      addOverride(member, fix.target, "converge");
+    }
+  }
+
+  return {
+    manifestEdits,
+    overrides: [...overrides.values()].toSorted((a, b) =>
+      a.packageName.localeCompare(b.packageName),
+    ),
+    conflicts,
+    unresolvableChanges,
+  };
+};

package/src/renderApplyPlan.test.ts

@@ -0,0 +1,136 @@
+import { describe, it } from "bun:test";
+import { ok, strictEqual } from "node:assert/strict";
+import { renderApplyPlan } from "./renderApplyPlan.ts";
+import type { ApplyPlanOptions } from "./renderApplyPlan.ts";
+
+const escapeStart = "\u001B[";
+
+const render = (
+  overrides: Partial<ApplyPlanOptions> = {},
+): { output: string; changeCount: number } => {
+  let output = "";
+  const { changeCount } = renderApplyPlan({
+    fileChanges: [
+      {
+        path: "package.json",
+        changes: ['"metro": "0.84.5" -> "0.87.0" (devDependencies)'],
+      },
+    ],
+    dedupeCommand: "pnpm-dedupe",
+    color: false,
+    log: (message = "") => {
+      output += `${message}\n`;
+    },
+    ...overrides,
+  });
+  return { output, changeCount };
+};
+
+const lastLine = (output: string): string =>
+  output.trimEnd().split("\n").at(-1)!;
+
+describe("renderApplyPlan", () => {
+  it("renders the changes per file and counts them", () => {
+    const { output, changeCount } = render();
+    strictEqual(changeCount, 1);
+    ok(output.startsWith("Would apply:\n"));
+    ok(output.includes("package.json:"));
+    ok(output.includes('  - "metro": "0.84.5" -> "0.87.0" (devDependencies)'));
+    strictEqual(
+      lastLine(output),
+      "1 change in 1 file. Run `pnpm-dedupe` to apply.",
+    );
+  });
+
+  it("pluralizes changes and files", () => {
+    const { output, changeCount } = render({
+      fileChanges: [
+        { path: "package.json", changes: ["a", "b"] },
+        { path: "packages/app/package.json", changes: ["c"] },
+      ],
+    });
+    strictEqual(changeCount, 3);
+    strictEqual(
+      lastLine(output),
+      "3 changes in 2 files. Run `pnpm-dedupe` to apply.",
+    );
+  });
+
+  it("marks a file that is only touched for the run", () => {
+    const { output } = render({
+      fileChanges: [
+        {
+          path: "pnpm-workspace.yaml",
+          transient: "removed once the result is verified",
+          changes: ['"metro@": "0.87.0" (converge)'],
+        },
+      ],
+    });
+    ok(
+      output.includes(
+        "pnpm-workspace.yaml (transient, removed once the result is verified):",
+      ),
+    );
+  });
+
+  it("skips a file with no change of its own", () => {
+    const { output, changeCount } = render({
+      fileChanges: [
+        { path: "package.json", changes: ["a"] },
+        { path: "pnpm-workspace.yaml", changes: [] },
+      ],
+    });
+    strictEqual(changeCount, 1);
+    ok(!output.includes("pnpm-workspace.yaml"));
+    ok(lastLine(output).startsWith("1 change in 1 file."));
+  });
+
+  it("reports what the plan gave up on", () => {
+    const { output } = render({
+      skipped: ["metro-config: keeping 0.87.0, ignoring 0.84.5"],
+    });
+    ok(output.includes("Skipped:"));
+    ok(output.includes("  - metro-config: keeping 0.87.0, ignoring 0.84.5"));
+  });
+
+  it("reports what the package manager would still change", () => {
+    const { output } = render({
+      packageManagerResiduals: "`pnpm dedupe` would also change the lockfile.",
+    });
+    ok(output.includes("`pnpm dedupe` would also change the lockfile."));
+  });
+
+  it("says nothing to do when there is no change and no residual", () => {
+    const { output, changeCount } = render({ fileChanges: [] });
+    strictEqual(changeCount, 0);
+    strictEqual(output, "Nothing to dedupe.\n");
+  });
+
+  it("still points at the command when only the package manager would act", () => {
+    const { output, changeCount } = render({
+      fileChanges: [],
+      packageManagerResiduals: "`pnpm dedupe` would also change the lockfile.",
+    });
+    strictEqual(changeCount, 0);
+    ok(!output.includes("Would apply:"));
+    strictEqual(lastLine(output), "Run `pnpm-dedupe` to apply.");
+  });
+
+  it("reports what was skipped even with nothing to apply", () => {
+    const { output } = render({
+      fileChanges: [],
+      skipped: ["metro in packages/app: no workspace file recorded for it"],
+    });
+    ok(
+      output.includes(
+        "  - metro in packages/app: no workspace file recorded for it",
+      ),
+    );
+    ok(output.includes("Nothing to dedupe."));
+  });
+
+  it("emits no escape codes with color off, and some with it on", () => {
+    ok(!render().output.includes(escapeStart));
+    ok(render({ color: true }).output.includes(escapeStart));
+  });
+});

package/src/renderApplyPlan.ts

@@ -0,0 +1,95 @@
+import { createColorize, shouldColorize } from "./reportColors.ts";
+import { plural } from "./reportText.ts";
+
+export interface ApplyPlanFileChange {
+  // repo-relative
+  path: string;
+  // why the file is only touched for the duration of the run, when it is
+  transient?: string;
+  // one line per change, worded by the caller: only it knows the manifest
+  // shape the change lands in
+  changes: string[];
+}
+
+export interface ApplyPlanOptions {
+  fileChanges: ApplyPlanFileChange[];
+  // what the plan gave up on, and why
+  skipped?: string[];
+  // what the package manager's own dedupe would still do on top
+  packageManagerResiduals?: string;
+  dedupeCommand: string;
+  color?: boolean;
+  log?: (message?: string) => void;
+}
+
+export interface ApplyPlanSummary {
+  changeCount: number;
+}
+
+/**
+ * The plan a dedupe run would apply, shared by `--check` and `--dry-run`. The
+ * returned `changeCount` is what `--check` gates its exit code on.
+ */
+export const renderApplyPlan = ({
+  fileChanges,
+  skipped = [],
+  packageManagerResiduals,
+  dedupeCommand,
+  color: colorEnabled = shouldColorize(),
+  log = console.log,
+}: ApplyPlanOptions): ApplyPlanSummary => {
+  const color = createColorize(colorEnabled);
+  const changeCount = fileChanges.reduce(
+    (total, file) => total + file.changes.length,
+    0,
+  );
+
+  if (changeCount === 0 && packageManagerResiduals === undefined) {
+    for (const entry of skipped) {
+      log(`  - ${color("red", entry)}`);
+    }
+    log("Nothing to dedupe.");
+    return { changeCount };
+  }
+
+  if (changeCount > 0) {
+    log(color("dim", "Would apply:"));
+
+    for (const file of fileChanges) {
+      if (file.changes.length === 0) continue;
+      const suffix =
+        file.transient === undefined
+          ? ""
+          : color("dim", ` (transient, ${file.transient})`);
+      log();
+      log(`${color("bold", file.path)}${suffix}:`);
+      for (const change of file.changes) {
+        log(`  - ${change}`);
+      }
+    }
+  }
+
+  if (skipped.length > 0) {
+    log();
+    log(color("dim", "Skipped:"));
+    for (const entry of skipped) {
+      log(`  - ${color("red", entry)}`);
+    }
+  }
+
+  if (packageManagerResiduals !== undefined) {
+    log();
+    log(packageManagerResiduals);
+  }
+
+  const touchedFiles = fileChanges.filter((file) => file.changes.length > 0);
+  const counts =
+    changeCount === 0
+      ? ""
+      : `${plural(changeCount, "change", "changes")} in ${plural(touchedFiles.length, "file", "files")}. `;
+
+  log();
+  log(`${counts}Run ${color("cyan", `\`${dedupeCommand}\``)} to apply.`);
+
+  return { changeCount };
+};

package/src/renderDedupeSummary.test.ts

@@ -0,0 +1,121 @@
+import { describe, it } from "bun:test";
+import { ok, strictEqual } from "node:assert/strict";
+import { renderDedupeSummary } from "./renderDedupeSummary.ts";
+import type { DedupeSummaryOptions } from "./renderDedupeSummary.ts";
+
+const render = (overrides: Partial<DedupeSummaryOptions> = {}): string => {
+  let output = "";
+  renderDedupeSummary({
+    deduped: [
+      { packageName: "semver", before: ["7.5.4", "7.7.1"], after: ["7.7.1"] },
+    ],
+    remainingDuplicates: 0,
+    whyCommand: "bun-why-duplicate",
+    color: false,
+    log: (message = "") => {
+      output += `${message}\n`;
+    },
+    ...overrides,
+  });
+  return output;
+};
+
+const lines = (output: string): string[] => output.trimEnd().split("\n");
+
+describe("renderDedupeSummary", () => {
+  it("counts and names both sides, one package per line", () => {
+    strictEqual(
+      render({
+        deduped: [
+          {
+            packageName: "@typescript-eslint/parser",
+            before: ["8.1.0", "8.2.0", "8.3.0"],
+            after: ["8.3.0"],
+          },
+          {
+            packageName: "range-parser",
+            before: ["1.2.1", "1.3.0"],
+            after: ["1.2.1"],
+          },
+        ],
+      }),
+      [
+        "Deduped 2 packages, 3 copies merged:",
+        "  @typescript-eslint/parser: 3 versions (8.1.0, 8.2.0, 8.3.0) -> 1 version (8.3.0)",
+        "  range-parser:              2 versions (1.2.1, 1.3.0) -> 1 version (1.2.1)",
+        "No duplicate left.",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  // the counts are what say a copy went away: a bare `1.3.0 -> 1.2.1` reads as
+  // a downgrade the tool chose
+  it("keeps the surviving version alongside its count", () => {
+    ok(
+      render().includes(
+        "  semver: 2 versions (7.5.4, 7.7.1) -> 1 version (7.7.1)\n",
+      ),
+    );
+  });
+
+  it("names what is left of a package only partly collapsed", () => {
+    ok(
+      render({
+        deduped: [
+          {
+            packageName: "react",
+            before: ["17.0.2", "18.2.0", "19.0.0"],
+            after: ["18.2.0", "19.0.0"],
+          },
+        ],
+        remainingDuplicates: 1,
+      }).includes(
+        "  react: 3 versions (17.0.2, 18.2.0, 19.0.0) -> 2 versions (18.2.0, 19.0.0)\n",
+      ),
+    );
+  });
+
+  it("summarises a package resolved more times than the line can hold", () => {
+    ok(
+      render({
+        deduped: [
+          {
+            packageName: "@types/node",
+            before: [
+              "18.0.0",
+              "20.0.0",
+              "20.1.0",
+              "22.0.0",
+              "22.1.0",
+              "24.0.0",
+            ],
+            after: ["24.0.0"],
+          },
+        ],
+      }).includes(
+        "6 versions (18.0.0, 20.0.0, 20.1.0, 22.0.0, 22.1.0, +1 more) -> 1 version (24.0.0)",
+      ),
+    );
+  });
+
+  it("points at the why command for what is left", () => {
+    strictEqual(
+      lines(render({ remainingDuplicates: 3 })).at(-1),
+      "3 duplicates left — run `bun-why-duplicate` to see them.",
+    );
+    strictEqual(
+      lines(render({ remainingDuplicates: 1 })).at(-1),
+      "1 duplicate left — run `bun-why-duplicate` to see it.",
+    );
+  });
+
+  // the caller has its own wording for a run that changed nothing
+  it("prints nothing when nothing was deduped", () => {
+    strictEqual(render({ deduped: [], remainingDuplicates: 4 }), "");
+  });
+
+  it("colours the versions when asked", () => {
+    ok(render({ color: true }).includes("["));
+  });
+});

package/src/renderDedupeSummary.ts

@@ -0,0 +1,78 @@
+import { stylePackageName } from "./packageStyles.ts";
+import { createColorize, shouldColorize } from "./reportColors.ts";
+import type { Colorize, ReportStyle } from "./reportColors.ts";
+import { columnWidth, listText, padTo, plural } from "./reportText.ts";
+import type { DedupedPackage } from "./versionsSnapshot.ts";
+
+export interface DedupeSummaryOptions {
+  deduped: DedupedPackage[];
+  // packages the lockfile still resolves more than once, counted as
+  // `why-duplicate` counts them so the two commands agree
+  remainingDuplicates: number;
+  whyCommand: string;
+  color?: boolean;
+  log?: (message?: string) => void;
+}
+
+// A package resolved more times than the shared cap is summarised: the line
+// says what it collapsed to, not the whole census.
+const versionList = (
+  color: Colorize,
+  versions: string[],
+  style: ReportStyle,
+): string =>
+  `${plural(versions.length, "version", "versions")} (${listText({
+    items: versions,
+    render: (version) => color(style, version),
+    more: (rest) => color("dim", `, +${rest} more`),
+  })})`;
+
+/**
+ * What a dedupe run actually collapsed, one line per package. Shared by every
+ * tool so the three of them report a run the same way; the caller still says
+ * what it wrote, which only it knows.
+ *
+ * Both sides are counted and named: `2 versions (1.2.1, 1.3.0) -> 1 version
+ * (1.2.1)` is the copy that went away, where a bare `1.3.0 -> 1.2.1` reads as a
+ * downgrade the tool decided on its own.
+ *
+ * Nothing is printed when nothing was deduped: the caller has its own wording
+ * for that, and an empty table reads as a failure it may not be.
+ */
+export const renderDedupeSummary = ({
+  deduped,
+  remainingDuplicates,
+  whyCommand,
+  color: colorEnabled = shouldColorize(),
+  log = console.log,
+}: DedupeSummaryOptions): void => {
+  if (deduped.length === 0) return;
+
+  const color = createColorize(colorEnabled);
+  const mergedCount = deduped.reduce(
+    (total, entry) => total + (entry.before.length - entry.after.length),
+    0,
+  );
+
+  log(
+    `${color("bold", "Deduped")} ${plural(deduped.length, "package", "packages")}, ${plural(mergedCount, "copy", "copies")} merged:`,
+  );
+
+  // tighter than the shared budget: two version lists follow the name here
+  const width = columnWidth(
+    deduped.map((entry) => entry.packageName),
+    34,
+  );
+
+  for (const { packageName, before, after } of deduped) {
+    log(
+      `  ${stylePackageName(color, packageName)}:${padTo(width, packageName)} ${versionList(color, before, "yellow")} -> ${versionList(color, after, "green")}`,
+    );
+  }
+
+  log(
+    remainingDuplicates === 0
+      ? "No duplicate left."
+      : `${plural(remainingDuplicates, "duplicate", "duplicates")} left — run ${color("cyan", `\`${whyCommand}\``)} to see ${remainingDuplicates === 1 ? "it" : "them"}.`,
+  );
+};