pm-dedup-core 2.1.0

package/src/identifyResolutionFixes.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "bun:test";
+import type {
+  NpmResolutionPackage,
+  ResolutionDependent,
+  ResolutionEntry,
+} from "./identifyResolutionFixes.ts";
+import { identifyResolutionFixes } from "./identifyResolutionFixes.ts";
+
+const npm = (
+  name: string,
+  version: string,
+): ResolutionEntry<NpmResolutionPackage> => ({
+  resolution: `${name}@${version}`,
+  package: { type: "npm", name, version },
+});
+
+const workspace = (name: string): ResolutionEntry => ({
+  resolution: `${name}@workspace`,
+  package: { type: "workspace", name },
+});
+
+const dependentsOf = (
+  name: string,
+  ranges: string[],
+): Map<string, ResolutionDependent[]> =>
+  new Map([[name, ranges.map((version) => ({ version }))]]);
+
+describe("identifyResolutionFixes", () => {
+  it("ignores a dependent whose declaration semver cannot read", () => {
+    // read as a range, `workspace:*` satisfies neither candidate and the merge
+    // the real dependent allows would be suppressed
+    const dependents = new Map<string, ResolutionDependent[]>([
+      [
+        "lib",
+        [{ version: "^1.0.0" }, { version: "workspace:*", nonSemver: true }],
+      ],
+    ]);
+
+    expect(
+      identifyResolutionFixes(
+        [npm("lib", "1.0.0"), npm("lib", "1.2.0")],
+        dependents,
+      ),
+    ).toEqual([
+      { mergeableResolutions: ["lib@1.0.0", "lib@1.2.0"], to: "lib@1.2.0" },
+    ]);
+  });
+
+  it("vouches for no merge when every dependent is unreadable", () => {
+    const dependents = new Map<string, ResolutionDependent[]>([
+      ["lib", [{ version: "workspace:*", nonSemver: true }]],
+    ]);
+
+    expect(
+      identifyResolutionFixes(
+        [npm("lib", "1.0.0"), npm("lib", "1.2.0")],
+        dependents,
+      ),
+    ).toEqual([]);
+  });
+
+  it("returns nothing for fewer than two resolutions", () => {
+    expect(identifyResolutionFixes([], new Map())).toEqual([]);
+    expect(identifyResolutionFixes([npm("lib", "1.0.0")], new Map())).toEqual(
+      [],
+    );
+  });
+
+  it("merges every resolution onto the highest version satisfying all dependents", () => {
+    const fixes = identifyResolutionFixes(
+      [npm("lib", "1.0.0"), npm("lib", "1.2.0")],
+      dependentsOf("lib", ["^1.0.0", "^1.2.0"]),
+    );
+
+    expect(fixes).toEqual([
+      { mergeableResolutions: ["lib@1.0.0", "lib@1.2.0"], to: "lib@1.2.0" },
+    ]);
+  });
+
+  it("partitions greedily when no version satisfies every dependent", () => {
+    const fixes = identifyResolutionFixes(
+      [npm("lib", "1.0.0"), npm("lib", "1.2.0"), npm("lib", "2.0.0")],
+      dependentsOf("lib", ["^1.0.0", "^1.2.0", "^2.0.0"]),
+    );
+
+    expect(fixes).toEqual([
+      { mergeableResolutions: ["lib@1.0.0", "lib@1.2.0"], to: "lib@1.2.0" },
+    ]);
+  });
+
+  it("refuses a merge that would drop a dependent the merged resolution served", () => {
+    // `>=1.0.0` accepts 2.0.0, but merging 1.2.0 into it would strand `^1.0.0`
+    const fixes = identifyResolutionFixes(
+      [npm("lib", "1.0.0"), npm("lib", "1.2.0"), npm("lib", "2.0.0")],
+      dependentsOf("lib", [">=1.0.0", "^1.0.0", "2.0.0"]),
+    );
+
+    expect(fixes).toEqual([
+      { mergeableResolutions: ["lib@1.0.0", "lib@1.2.0"], to: "lib@1.2.0" },
+    ]);
+  });
+
+  it("ignores resolutions that are not npm packages", () => {
+    const fixes = identifyResolutionFixes(
+      [npm("lib", "1.0.0"), workspace("lib"), npm("lib", "1.2.0")],
+      dependentsOf("lib", ["^1.0.0", "^1.2.0"]),
+    );
+
+    expect(fixes).toEqual([
+      { mergeableResolutions: ["lib@1.0.0", "lib@1.2.0"], to: "lib@1.2.0" },
+    ]);
+  });
+
+  // Reachable as soon as every requester declares the package through something
+  // semver cannot read: those declarations are left out of the map, and no range
+  // is left to vouch for a merge. Reading the empty set as "one candidate covers
+  // every dependent" would merge the whole package on no evidence at all.
+  it("proposes nothing for a package with no collected dependents", () => {
+    expect(
+      identifyResolutionFixes(
+        [npm("lib", "1.0.0"), npm("lib", "1.2.0")],
+        new Map(),
+      ),
+    ).toEqual([]);
+
+    expect(
+      identifyResolutionFixes(
+        [npm("lib", "1.0.0"), npm("lib", "1.2.0")],
+        new Map([["lib", []]]),
+      ),
+    ).toEqual([]);
+  });
+});

package/src/identifyResolutionFixes.ts

@@ -0,0 +1,183 @@
+import semver from "semver";
+import { createCandidateVersionComparator } from "./compareCandidateVersions.ts";
+
+export interface ResolutionPackage {
+  type: string;
+  name: string;
+}
+
+export interface NpmResolutionPackage extends ResolutionPackage {
+  type: "npm";
+  version: string;
+}
+
+export interface ResolutionEntry<
+  P extends ResolutionPackage = ResolutionPackage,
+> {
+  resolution: string;
+  package: P;
+}
+
+export interface ResolutionDependent {
+  // the range this dependent declares
+  version: string;
+  // the declaration is not a semver range — a git url, a tarball, `file:`,
+  // `workspace:`, `patch:`. It is kept in the map so the report can name the
+  // requester of a resolution nothing else explains, but no candidate version
+  // can be tested against it, so it takes no part in a merge decision.
+  nonSemver?: boolean;
+}
+
+export type ResolutionDependentsMap<
+  D extends ResolutionDependent = ResolutionDependent,
+> = Map<string, D[]>;
+
+export interface ResolutionFix {
+  mergeableResolutions: string[];
+  to: string;
+}
+
+const isNpmResolution = (
+  resolution: ResolutionEntry,
+): resolution is ResolutionEntry<NpmResolutionPackage> =>
+  resolution.package.type === "npm";
+
+/**
+ * Dedupe opportunities reachable one package at a time. A family of co-versioned
+ * packages whose duplicate survives only because a few members resolve high is
+ * invisible here and is handled by `identifyLockstepClusterFixes`.
+ */
+export const identifyResolutionFixes = <D extends ResolutionDependent>(
+  resolutions: ResolutionEntry[],
+  dependents: ResolutionDependentsMap<D>,
+): ResolutionFix[] => {
+  if (resolutions.length <= 1) {
+    return [];
+  }
+
+  const onlyNpmResolutions = resolutions.filter(isNpmResolution);
+
+  const fixes: ResolutionFix[] = [];
+
+  const packageNames = new Set(
+    resolutions.map((resolution) => resolution.package.name),
+  );
+
+  for (const packageName of packageNames) {
+    const npmVersions = onlyNpmResolutions
+      .filter((resolution) => resolution.package.name === packageName)
+      .map((resolution) => ({
+        resolution,
+        version: resolution.package.version,
+        satisfies: new Set<D>(),
+      }));
+
+    // Every requester can declare the package through something semver cannot
+    // read — a git url, `file:`, `workspace:` — and such a declaration is
+    // dropped here rather than treated as a range nothing satisfies, which
+    // would suppress the merges the real dependents allow. Once they are gone
+    // nothing may vouch for a merge at all, and the "one candidate covers every
+    // dependent" test below would read the empty set as full coverage.
+    const packageDependents = dependents
+      .get(packageName)
+      ?.filter((dependent) => !dependent.nonSemver);
+    if (!packageDependents || packageDependents.length === 0) continue;
+
+    packageDependents.forEach((dependent) => {
+      for (const { version, satisfies } of npmVersions) {
+        if (
+          semver.satisfies(version, dependent.version, {
+            includePrerelease: true,
+          })
+        ) {
+          satisfies.add(dependent);
+        }
+      }
+    });
+
+    const byVersionAscending = (
+      resolutionA: string,
+      resolutionB: string,
+    ): number => {
+      const versionA = npmVersions.find(
+        (candidate) => candidate.resolution.resolution === resolutionA,
+      )?.version;
+      const versionB = npmVersions.find(
+        (candidate) => candidate.resolution.resolution === resolutionB,
+      )?.version;
+      return versionA && versionB ? semver.compare(versionA, versionB) : 0;
+    };
+
+    const satisfiedCountByVersion = new Map(
+      npmVersions.map(({ version, satisfies }) => [version, satisfies.size]),
+    );
+    const compareCandidates = createCandidateVersionComparator({
+      satisfiedCountOf: (version) => satisfiedCountByVersion.get(version) ?? 0,
+    });
+
+    // the best-ranked candidate satisfies everyone whenever any candidate does
+    const [bestCandidate] = npmVersions.toSorted((candidateA, candidateB) =>
+      compareCandidates(candidateA.version, candidateB.version),
+    );
+
+    if (bestCandidate?.satisfies.size === packageDependents.length) {
+      const mergeableResolutions = npmVersions
+        .map((candidate) => candidate.resolution.resolution)
+        .toSorted(byVersionAscending);
+
+      if (mergeableResolutions.length > 1) {
+        fixes.push({
+          mergeableResolutions,
+          to: bestCandidate.resolution.resolution,
+        });
+      }
+
+      continue;
+    }
+
+    // no single candidate satisfies all dependents — do greedy assignment from highest -> lowest
+    npmVersions.sort((candidateA, candidateB) =>
+      semver.rcompare(candidateA.version, candidateB.version),
+    );
+    const unassigned = new Set<D>(packageDependents);
+
+    for (const candidate of npmVersions) {
+      const newlyAssigned = new Set<D>(
+        [...candidate.satisfies].filter((dependent) =>
+          unassigned.has(dependent),
+        ),
+      );
+      if (newlyAssigned.size === 0) continue;
+
+      const mergeable = npmVersions.filter((other) => {
+        if (other === candidate) return false;
+        const intersects = [...other.satisfies].some((dependent) =>
+          newlyAssigned.has(dependent),
+        );
+        if (!intersects) return false;
+        // merging is safe only when the candidate satisfies every dependent the
+        // resolution being merged away was serving
+        return [...other.satisfies].every((dependent) =>
+          candidate.satisfies.has(dependent),
+        );
+      });
+
+      const mergeableResolutions = [
+        candidate.resolution.resolution,
+        ...mergeable.map((other) => other.resolution.resolution),
+      ].toSorted(byVersionAscending);
+
+      if (mergeableResolutions.length > 1) {
+        fixes.push({
+          mergeableResolutions,
+          to: candidate.resolution.resolution,
+        });
+      }
+
+      for (const dependent of newlyAssigned) unassigned.delete(dependent);
+      if (unassigned.size === 0) break;
+    }
+  }
+
+  return fixes;
+};

package/src/index.ts

@@ -0,0 +1,123 @@
+export {
+  PackageDescriptorNameUtils,
+  PackageDependencyDescriptorUtils,
+  isNpmProtocol,
+  isSemverComparable,
+} from "./packageDependenciesUtils.ts";
+export type {
+  PackageDescriptorName,
+  PackageDependencyDescriptor,
+} from "./packageDependenciesUtils.ts";
+export { buildLockstepClusters } from "./buildLockstepClusters.ts";
+export type {
+  LockstepGraph,
+  LockstepResolution,
+} from "./buildLockstepClusters.ts";
+export { identifyLockstepClusterFixes } from "./identifyLockstepClusterFixes.ts";
+export type {
+  ClusterDependent,
+  ClusterDependentsMap,
+  ClusterExcludedMember,
+  ClusterExternalConstraint,
+  ClusterFix,
+  ClusterMember,
+  ClusterMemberVersions,
+  ClusterMembersMap,
+  ClusterReuseFix,
+  ClusterWorkspaceChange,
+  ClusterWorkspaceRef,
+} from "./identifyLockstepClusterFixes.ts";
+export { identifyResolutionFixes } from "./identifyResolutionFixes.ts";
+export type {
+  NpmResolutionPackage,
+  ResolutionDependent,
+  ResolutionDependentsMap,
+  ResolutionEntry,
+  ResolutionFix,
+  ResolutionPackage,
+} from "./identifyResolutionFixes.ts";
+export { buildIdentifiedFixesMap } from "./buildIdentifiedFixesMap.ts";
+export type { ResolutionsMap } from "./buildIdentifiedFixesMap.ts";
+export {
+  createPackageFilter,
+  describeSkippedClusterFix,
+  selectClusterFixes,
+  selectPackages,
+} from "./createPackageFilter.ts";
+export type {
+  PackageFilter,
+  PackageFilterOptions,
+  SelectedClusterFixes,
+  SkippedClusterFix,
+} from "./createPackageFilter.ts";
+export {
+  packageFilterParseArgsOptions,
+  packageFilterUsage,
+  toPackageFilterOptions,
+  toWhyDuplicateRequest,
+  whyDuplicateParseArgsOptions,
+  whyDuplicateUsage,
+} from "./packageFilterArgs.ts";
+export type {
+  PackageFilterArgValues,
+  WhyDuplicateArgValues,
+  WhyDuplicateRequest,
+} from "./packageFilterArgs.ts";
+export { parseBinArgs } from "./parseBinArgs.ts";
+export { findProjectRoot, resolveProjectDir } from "./findProjectRoot.ts";
+export type { ProjectRootOptions } from "./findProjectRoot.ts";
+export { createCandidateVersionComparator } from "./compareCandidateVersions.ts";
+export type { CandidateVersionComparatorOptions } from "./compareCandidateVersions.ts";
+export { clusterLabel } from "./clusterLabel.ts";
+export { createColorize, shouldColorize } from "./reportColors.ts";
+export type { Colorize, PaletteStyle, ReportStyle } from "./reportColors.ts";
+export { stylePackageName, stylePackageReference } from "./packageStyles.ts";
+export { renderDuplicatesReport } from "./renderDuplicatesReport.ts";
+export type {
+  DuplicateDedupeView,
+  DuplicateDependentView,
+  DuplicatePackageView,
+  DuplicateResolutionView,
+  DuplicatesReportOptions,
+  DuplicatesReportTitle,
+} from "./renderDuplicatesReport.ts";
+export { selectExplainedPackages } from "./selectExplainedPackages.ts";
+export type {
+  ExplainedPackagesSelection,
+  SelectExplainedPackagesOptions,
+} from "./selectExplainedPackages.ts";
+export { renderApplyPlan } from "./renderApplyPlan.ts";
+export type {
+  ApplyPlanFileChange,
+  ApplyPlanOptions,
+  ApplyPlanSummary,
+} from "./renderApplyPlan.ts";
+export { renderDedupeSummary } from "./renderDedupeSummary.ts";
+export type { DedupeSummaryOptions } from "./renderDedupeSummary.ts";
+export {
+  buildVersionsSnapshot,
+  countDuplicatedPackages,
+  diffVersionsSnapshots,
+} from "./versionsSnapshot.ts";
+export type {
+  DedupedPackage,
+  SnapshotPackage,
+  VersionsSnapshot,
+} from "./versionsSnapshot.ts";
+export { captureFiles, restoreFiles } from "./fileSnapshot.ts";
+export type { FileSnapshot } from "./fileSnapshot.ts";
+export { applyWorkspaceRangeEdit, nextSelector } from "./workspaceManifest.ts";
+export type { WorkspaceRangeEdit } from "./workspaceManifest.ts";
+export { planClusterApply } from "./planClusterApply.ts";
+export type {
+  ClusterApplyPlan,
+  PlannedManifestEdit,
+  PlannedOverride,
+} from "./planClusterApply.ts";
+export { diffDuplicates } from "./duplicateSnapshot.ts";
+export type { DuplicateDiff, DuplicateSnapshot } from "./duplicateSnapshot.ts";
+export { partitionUnconditionalOverrides } from "./unconditionalOverrides.ts";
+export type {
+  PartitionedOverrides,
+  RejectedOverride,
+} from "./unconditionalOverrides.ts";