pm-dedup-core 2.1.0

package/src/compareCandidateVersions.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "bun:test";
+import { createCandidateVersionComparator } from "./compareCandidateVersions.ts";
+
+const satisfiedCounts = new Map([
+  ["1.0.0", 1],
+  ["1.5.0", 3],
+  ["2.0.0", 3],
+  ["3.0.0", 2],
+]);
+const satisfiedCountOf = (version: string): number =>
+  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",
+    ]);
+  });
+});

package/src/compareCandidateVersions.ts

@@ -0,0 +1,23 @@
+import semver from "semver";
+
+export interface CandidateVersionComparatorOptions {
+  // omit to rank on semver alone
+  satisfiedCountOf?: (version: string) => number;
+}
+
+/**
+ * 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 }: CandidateVersionComparatorOptions = {}) =>
+  (versionA: string, versionB: string): number => {
+    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);
+  };

package/src/createPackageFilter.test.ts

@@ -0,0 +1,156 @@
+import { describe, it } from "bun:test";
+import { deepStrictEqual, strictEqual } from "node:assert/strict";
+import {
+  createPackageFilter,
+  describeSkippedClusterFix,
+  selectClusterFixes,
+} from "./createPackageFilter.ts";
+import type { ClusterFix } from "./identifyLockstepClusterFixes.ts";
+
+const clusterFix = (members: string[]): ClusterFix => ({
+  members,
+  duplicatedMembers: members,
+  memberVersions: {},
+  target: null,
+  direction: "none",
+  convergentMembers: [],
+  driverMembers: [],
+  excludedMembers: [],
+  anchor: null,
+  reuseFixes: [],
+  floatingMembers: [],
+  workspaceChanges: [],
+  reResolutionSet: [],
+  externalConstraints: [],
+  needsRoundTrip: false,
+  applicable: true,
+});
+
+describe("createPackageFilter", () => {
+  it("selects everything when nothing is asked for", () => {
+    const filter = createPackageFilter();
+
+    strictEqual(filter.selectsEverything, true);
+    strictEqual(filter.selects("lodash"), true);
+    strictEqual(filter.selects("@babel/core"), true);
+    strictEqual(filter.rejectionReason("lodash"), undefined);
+  });
+
+  it("keeps only the included names", () => {
+    const filter = createPackageFilter({ include: ["lodash", "@babel/core"] });
+
+    strictEqual(filter.selectsEverything, false);
+    strictEqual(filter.selects("lodash"), true);
+    strictEqual(filter.selects("@babel/core"), true);
+    strictEqual(filter.selects("react"), false);
+    strictEqual(filter.rejectionReason("react"), "not selected");
+  });
+
+  it("drops the excluded names and keeps the rest", () => {
+    const filter = createPackageFilter({ exclude: ["lodash"] });
+
+    strictEqual(filter.selects("react"), true);
+    strictEqual(filter.selects("lodash"), false);
+    strictEqual(filter.rejectionReason("lodash"), "excluded");
+  });
+
+  it("lets an exclusion hold back part of an included scope", () => {
+    const filter = createPackageFilter({
+      includeScopes: ["@babel"],
+      exclude: ["@babel/runtime"],
+    });
+
+    strictEqual(filter.selects("@babel/core"), true);
+    strictEqual(filter.selects("@babel/runtime"), false);
+    strictEqual(filter.rejectionReason("@babel/runtime"), "excluded");
+  });
+
+  it("reads a scope with or without its leading @", () => {
+    const withAt = createPackageFilter({ includeScopes: ["@babel"] });
+    const withoutAt = createPackageFilter({ includeScopes: ["babel"] });
+
+    for (const filter of [withAt, withoutAt]) {
+      strictEqual(filter.selects("@babel/core"), true);
+      strictEqual(filter.selects("@babel/plugin-transform-runtime"), true);
+      strictEqual(filter.selects("babel-jest"), false);
+      strictEqual(filter.selects("@babel-other/core"), false);
+    }
+  });
+
+  it("excludes a whole scope", () => {
+    const filter = createPackageFilter({ excludeScopes: ["@types"] });
+
+    strictEqual(filter.selects("@types/node"), false);
+    strictEqual(filter.selects("typescript"), true);
+  });
+
+  it("matches a name holding glob-adjacent characters literally", () => {
+    const filter = createPackageFilter({
+      include: ["lodash.merge", "@scope/a-b_c"],
+    });
+
+    strictEqual(filter.selects("lodash.merge"), true);
+    strictEqual(filter.selects("@scope/a-b_c"), true);
+    strictEqual(filter.selects("lodashXmerge"), false);
+  });
+
+  it("stops a single star at the scope separator", () => {
+    const filter = createPackageFilter({ include: ["@babel/*"] });
+
+    strictEqual(filter.selects("@babel/core"), true);
+    strictEqual(filter.selects("babel"), false);
+
+    const everyUnscoped = createPackageFilter({ include: ["*"] });
+    strictEqual(everyUnscoped.selects("lodash"), true);
+    strictEqual(everyUnscoped.selects("@babel/core"), false);
+  });
+});
+
+describe("selectClusterFixes", () => {
+  it("passes every fix through when the filter selects everything", () => {
+    const fixes = [clusterFix(["@babel/core", "@babel/types"])];
+
+    deepStrictEqual(selectClusterFixes(fixes, createPackageFilter()), {
+      selected: fixes,
+      skipped: [],
+    });
+  });
+
+  it("keeps a fix whose whole family is selected", () => {
+    const fix = clusterFix(["@babel/core", "@babel/types"]);
+
+    const { selected, skipped } = selectClusterFixes(
+      [fix],
+      createPackageFilter({ includeScopes: ["@babel"] }),
+    );
+
+    deepStrictEqual(selected, [fix]);
+    deepStrictEqual(skipped, []);
+  });
+
+  it("skips a partly selected family and names what blocked it", () => {
+    const fix = clusterFix(["@babel/core", "@babel/types"]);
+
+    const { selected, skipped } = selectClusterFixes(
+      [fix],
+      createPackageFilter({ include: ["@babel/types"] }),
+    );
+
+    deepStrictEqual(selected, []);
+    deepStrictEqual(skipped, [{ fix, blockedBy: ["@babel/core"] }]);
+  });
+});
+
+describe("describeSkippedClusterFix", () => {
+  it("names the family and counts the blockers past the first few", () => {
+    const members = ["a", "b", "c", "d", "e"];
+
+    strictEqual(
+      describeSkippedClusterFix({
+        fix: clusterFix(members),
+        blockedBy: members,
+      }),
+      "cluster a (+4 more): a, b, c (+2 more) not selected by the filter, and a family only converges as a whole",
+    );
+  });
+});

package/src/createPackageFilter.ts

@@ -0,0 +1,142 @@
+import picomatch from "picomatch";
+import { clusterLabel } from "./clusterLabel.ts";
+import type { ClusterFix } from "./identifyLockstepClusterFixes.ts";
+
+export interface PackageFilterOptions {
+  // glob patterns matched against the full npm name, `@scope/name` included
+  include?: string[];
+  exclude?: string[];
+  // bare scope names, with or without the leading `@`
+  includeScopes?: string[];
+  excludeScopes?: string[];
+}
+
+export interface PackageFilter {
+  // nothing was asked for, so every package is selected and callers holding a
+  // whole lockfile can skip the pass entirely
+  selectsEverything: boolean;
+  selects: (packageName: string) => boolean;
+  // why a package is left alone, for reports; undefined when it is selected
+  rejectionReason: (packageName: string) => string | undefined;
+}
+
+const scopePattern = (scope: string): string =>
+  `${scope.startsWith("@") ? scope : `@${scope}`}/**`;
+
+const toPatterns = (names: string[], scopes: string[]): string[] => [
+  ...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: string[]): ((name: string) => boolean) =>
+  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 = [],
+}: PackageFilterOptions = {}): PackageFilter => {
+  const includePatterns = toPatterns(include, includeScopes);
+  const excludePatterns = toPatterns(exclude, excludeScopes);
+  const isIncluded = compile(includePatterns);
+  const isExcluded = compile(excludePatterns);
+
+  const rejectionReason = (packageName: string): string | undefined => {
+    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 = <T>(
+  packages: Record<string, T>,
+  filter: PackageFilter,
+): Record<string, T> =>
+  filter.selectsEverything
+    ? packages
+    : Object.fromEntries(
+        Object.entries(packages).filter(([packageName]) =>
+          filter.selects(packageName),
+        ),
+      );
+
+export interface SkippedClusterFix {
+  fix: ClusterFix;
+  // the members that are not selected, so a fix doing nothing is never silent
+  blockedBy: string[];
+}
+
+export interface SelectedClusterFixes {
+  selected: ClusterFix[];
+  skipped: SkippedClusterFix[];
+}
+
+/**
+ * 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: ClusterFix[],
+  filter: PackageFilter,
+): SelectedClusterFixes => {
+  if (filter.selectsEverything) return { selected: fixes, skipped: [] };
+
+  const selected: ClusterFix[] = [];
+  const skipped: SkippedClusterFix[] = [];
+
+  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,
+}: SkippedClusterFix): string => {
+  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`;
+};

package/src/duplicateSnapshot.ts

@@ -0,0 +1,24 @@
+// Every resolution that is one copy too many, as `name@version` ids. Sets, not
+// counts: a change that removes one duplicate and introduces another is not an
+// improvement, and a count would hide it.
+export type DuplicateSnapshot = Set<string>;
+
+export interface DuplicateDiff {
+  removed: string[];
+  added: string[];
+  improved: boolean;
+}
+
+export const diffDuplicates = (
+  before: DuplicateSnapshot,
+  after: DuplicateSnapshot,
+): DuplicateDiff => {
+  const removed = [...before].filter((resolution) => !after.has(resolution));
+  const added = [...after].filter((resolution) => !before.has(resolution));
+
+  return {
+    removed: removed.toSorted((a, b) => a.localeCompare(b)),
+    added: added.toSorted((a, b) => a.localeCompare(b)),
+    improved: added.length === 0 && removed.length > 0,
+  };
+};

package/src/fileSnapshot.ts

@@ -0,0 +1,28 @@
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+
+export interface FileSnapshot {
+  path: string;
+  // undefined when the file did not exist: restoring deletes it again
+  content: string | undefined;
+}
+
+const readIfExists = (path: string): string | undefined => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+};
+
+export const captureFiles = (paths: string[]): FileSnapshot[] =>
+  paths.map((path) => ({ path, content: readIfExists(path) }));
+
+export const restoreFiles = (snapshots: FileSnapshot[]): void => {
+  for (const { path, content } of snapshots) {
+    if (content === undefined) {
+      rmSync(path, { force: true });
+    } else {
+      writeFileSync(path, content);
+    }
+  }
+};

package/src/findProjectRoot.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, it } from "bun:test";
+import { strictEqual } from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { findProjectRoot } from "./findProjectRoot.ts";
+
+const lockfileName = "pm-tools.lock";
+
+const dirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+const tempRoot = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), `find-project-root-${process.pid}-`));
+  dirs.push(dir);
+  return dir;
+};
+
+const makeDir = (root: string, relativePath: string): string => {
+  const dir = join(root, relativePath);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+const makeLockfile = (dir: string): void => {
+  writeFileSync(join(dir, lockfileName), "");
+};
+
+describe("findProjectRoot", () => {
+  it("finds the lockfile in cwd", () => {
+    const root = tempRoot();
+    makeLockfile(root);
+
+    strictEqual(findProjectRoot({ lockfileName, cwd: root }), root);
+  });
+
+  it("walks up to an ancestor holding the lockfile", () => {
+    const root = tempRoot();
+    makeLockfile(root);
+    const nested = makeDir(root, join("packages", "app", "src"));
+
+    strictEqual(findProjectRoot({ lockfileName, cwd: nested }), root);
+  });
+
+  it("stops at the nearest one when two ancestors hold a lockfile", () => {
+    const root = tempRoot();
+    makeLockfile(root);
+    const nestedProject = makeDir(root, "examples/embedded");
+    makeLockfile(nestedProject);
+    const nested = makeDir(nestedProject, "src");
+
+    strictEqual(findProjectRoot({ lockfileName, cwd: nested }), nestedProject);
+  });
+
+  it("returns null when no ancestor up to the filesystem root has one", () => {
+    const root = tempRoot();
+    const nested = makeDir(root, "packages/app");
+
+    strictEqual(findProjectRoot({ lockfileName, cwd: nested }), null);
+  });
+});

package/src/findProjectRoot.ts

@@ -0,0 +1,61 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createColorize, shouldColorize } from "./reportColors.ts";
+
+export interface ProjectRootOptions {
+  lockfileName: string;
+  cwd?: string;
+}
+
+/**
+ * The nearest directory holding the lockfile, starting at `cwd` and walking up
+ * to the filesystem root; null when there is none.
+ *
+ * Nearest wins, which is the rule every package manager applies: a nested
+ * project carrying its own lockfile keeps resolving to itself rather than to the
+ * workspace above it.
+ */
+export const findProjectRoot = ({
+  lockfileName,
+  cwd = process.cwd(),
+}: ProjectRootOptions): string | null => {
+  let dir = cwd;
+  for (;;) {
+    if (existsSync(join(dir, lockfileName))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+};
+
+/**
+ * `findProjectRoot` for a bin: the project root the run operates on, whatever
+ * subdirectory it was invoked from.
+ *
+ * Returns null when there is no project to work on — as `parseBinArgs` does, the
+ * reason is printed and the exit code already says so, leaving the caller
+ * nothing to do but return.
+ *
+ * The notice goes to stderr, and only when the root is not `cwd` — a run from
+ * the root prints exactly what it always did, and a redirected report stays
+ * parseable.
+ */
+export const resolveProjectDir = ({
+  lockfileName,
+  cwd = process.cwd(),
+}: ProjectRootOptions): string | null => {
+  const projectDir = findProjectRoot({ lockfileName, cwd });
+
+  if (projectDir === null) {
+    console.error(`No ${lockfileName} found in ${cwd} or any parent directory`);
+    process.exitCode = 1;
+    return null;
+  }
+
+  if (projectDir !== cwd) {
+    const colorize = createColorize(shouldColorize(process.stderr));
+    console.error(colorize("dim", `using ${join(projectDir, lockfileName)}`));
+  }
+
+  return projectDir;
+};