pm-dedup-core 2.1.0

package/src/packageDependenciesUtils.ts

@@ -0,0 +1,156 @@
+import semver from "semver";
+
+/**
+ * Combination of an optional scope and name.
+ *
+ * eg `@npm/types`
+ */
+export interface PackageDescriptorName {
+  scope?: string;
+  name: string;
+}
+
+interface DescriptorUtils<Descriptor> {
+  parse: (value: string) => Descriptor;
+  stringify: (descriptor: Descriptor) => string;
+}
+
+export const PackageDescriptorNameUtils: DescriptorUtils<PackageDescriptorName> =
+  {
+    parse: (value) => {
+      if (value.startsWith("@")) {
+        const [scope, name] = value.slice(1).split("/", 2) as [string, string];
+        if (`@${scope}/${name}` !== value) {
+          throw new Error(
+            `Invalid package name with scope: ${value} (expecting ${scope}/${name})`,
+          );
+        }
+        return { scope, name };
+      }
+      return { name: value };
+    },
+    stringify: (descriptor) => {
+      return descriptor.scope === undefined
+        ? descriptor.name
+        : `@${descriptor.scope}/${descriptor.name}`;
+    },
+  };
+
+export interface PackageDependencyDescriptor<Protocol extends string = string> {
+  key: string;
+  npmName: string;
+  nameDescriptor: PackageDescriptorName;
+  /** `undefined` when the value is declared bare (`^1.0.0`), which means npm */
+  protocol: Protocol | undefined;
+  /** the npm name comes from the value (`npm:other@^1`), not from the key */
+  isAlias: boolean;
+  /** protocol removed: `^1.0.0` for `npm:^1.0.0`, `*` for `workspace:*` */
+  selector: string;
+}
+
+/**
+ * `git+ssh` and `https` keep their whole prefix rather than collapsing to `git`
+ * or being dropped: the round trip through `stringify` has to reproduce the
+ * declaration byte for byte, and nothing downstream branches on which flavour
+ * of git url it is.
+ */
+const protocolPattern = /^([a-z][a-z0-9+.-]*):/u;
+
+interface ExtractedProtocol {
+  protocol: string | undefined;
+  rest: string;
+}
+
+const extractProtocol = (dependencyValue: string): ExtractedProtocol => {
+  const match = protocolPattern.exec(dependencyValue);
+  if (!match) return { protocol: undefined, rest: dependencyValue };
+  return { protocol: match[1]!, rest: dependencyValue.slice(match[0].length) };
+};
+
+interface AliasParts {
+  npmName: string;
+  selector: string;
+}
+
+/**
+ * An `npm:` value is either a range (`npm:^1.0.0`, yarn's spelling) or an alias
+ * naming another package (`npm:semver@^6.0.0`, `npm:@types/bun`). Semver tells
+ * them apart: an alias target is never a valid range. A nameless alias keeps an
+ * empty selector, which `semver` already reads as `*`.
+ */
+const parseAlias = (rest: string): AliasParts | undefined => {
+  if (semver.validRange(rest) !== null) return undefined;
+
+  const separatorIndex = rest.startsWith("@")
+    ? rest.indexOf("@", 1)
+    : rest.indexOf("@");
+
+  return separatorIndex === -1
+    ? { npmName: rest, selector: "" }
+    : {
+        npmName: rest.slice(0, separatorIndex),
+        selector: rest.slice(separatorIndex + 1),
+      };
+};
+
+export const PackageDependencyDescriptorUtils = {
+  make: <Protocol extends string>(
+    descriptor: PackageDependencyDescriptor<Protocol>,
+    selector: string,
+  ): PackageDependencyDescriptor<Protocol> => ({ ...descriptor, selector }),
+
+  /**
+   * The `Protocol` union declares what a given lockfile can contain; `parse`
+   * does not enforce it. An unknown protocol has to parse, because
+   * `manifestKeyOf` reads every sibling declaration in a dependency block to
+   * find the one it edits — throwing on a neighbour would abort an unrelated
+   * rewrite. It still lands in `protocol` rather than being folded into the
+   * selector, so `isNpmProtocol` keeps it out of the npm comparisons.
+   */
+  parse: <Protocol extends string = string>(
+    dependencyKey: string,
+    dependencyValue: string,
+  ): PackageDependencyDescriptor<Protocol> => {
+    const { protocol, rest } = extractProtocol(dependencyValue);
+    const alias = protocol === "npm" ? parseAlias(rest) : undefined;
+    const npmName = alias?.npmName ?? dependencyKey;
+
+    return {
+      key: dependencyKey,
+      npmName,
+      nameDescriptor: PackageDescriptorNameUtils.parse(npmName),
+      protocol: protocol as Protocol | undefined,
+      isAlias: alias !== undefined,
+      selector: alias?.selector ?? rest,
+    };
+  },
+
+  stringify: ({
+    key,
+    npmName,
+    protocol,
+    isAlias,
+    selector,
+  }: PackageDependencyDescriptor): [key: string, value: string] => {
+    const target = (() => {
+      if (!isAlias) return selector;
+      return selector === "" ? npmName : `${npmName}@${selector}`;
+    })();
+
+    return [key, protocol === undefined ? target : `${protocol}:${target}`];
+  },
+};
+
+export const isNpmProtocol = (protocol: string | undefined): boolean =>
+  protocol === undefined || protocol === "npm";
+
+/**
+ * The guard to use before handing a selector to semver. A protocol check alone
+ * is not enough: shorthand declarations carry no prefix at all (`user/repo`,
+ * `./local`, `git@host:o/r.git`) and would otherwise read as npm ranges.
+ */
+export const isSemverComparable = (
+  descriptor: PackageDependencyDescriptor,
+): boolean =>
+  isNpmProtocol(descriptor.protocol) &&
+  semver.validRange(descriptor.selector) !== null;

package/src/packageFilterArgs.test.ts

@@ -0,0 +1,116 @@
+import { describe, it } from "bun:test";
+import { deepStrictEqual } from "node:assert/strict";
+import { parseArgs } from "node:util";
+import {
+  toPackageFilterOptions,
+  toWhyDuplicateRequest,
+  whyDuplicateParseArgsOptions,
+} from "./packageFilterArgs.ts";
+
+const parseFlags = (args: string[]) =>
+  parseArgs({
+    args,
+    options: { ...whyDuplicateParseArgsOptions },
+    allowPositionals: true,
+  });
+
+const parse = (args: string[]) =>
+  toPackageFilterOptions(parseFlags(args).values);
+
+const request = (args: string[]) => {
+  const { values, positionals } = parseFlags(args);
+  return toWhyDuplicateRequest(values, positionals);
+};
+
+describe("toPackageFilterOptions", () => {
+  it("leaves every list undefined when no flag is passed", () => {
+    deepStrictEqual(parse([]), {
+      include: undefined,
+      includeScopes: undefined,
+      exclude: undefined,
+      excludeScopes: undefined,
+    });
+  });
+
+  it("reads the four flags", () => {
+    deepStrictEqual(
+      parse([
+        "--packages",
+        "lodash",
+        "--scopes",
+        "@babel",
+        "--exclude",
+        "react",
+        "--exclude-scopes",
+        "@types",
+      ]),
+      {
+        include: ["lodash"],
+        includeScopes: ["@babel"],
+        exclude: ["react"],
+        excludeScopes: ["@types"],
+      },
+    );
+  });
+
+  it("reads a repeated flag and a comma list the same way", () => {
+    const repeated = parse(["--packages", "lodash", "--packages", "react"]);
+    const commaSeparated = parse(["--packages", "lodash,react"]);
+
+    deepStrictEqual(repeated.include, ["lodash", "react"]);
+    deepStrictEqual(commaSeparated.include, ["lodash", "react"]);
+  });
+
+  it("drops the blanks a trailing comma or a stray space leaves behind", () => {
+    deepStrictEqual(parse(["--packages", " lodash , ,"]).include, ["lodash"]);
+    deepStrictEqual(parse(["--packages", ","]).include, undefined);
+  });
+});
+
+describe("toWhyDuplicateRequest", () => {
+  it("takes a positional as an included name", () => {
+    deepStrictEqual(request(["lodash"]), {
+      filter: {
+        include: ["lodash"],
+        includeScopes: undefined,
+        exclude: undefined,
+        excludeScopes: undefined,
+      },
+      explains: true,
+      all: false,
+      // naming a package is asking why, which the one-line form does not answer
+      details: true,
+    });
+  });
+
+  it("merges the positionals with the names the flag carries", () => {
+    deepStrictEqual(request(["--packages", "lodash", "react"]).filter.include, [
+      "lodash",
+      "react",
+    ]);
+  });
+
+  it("explains a scope with nothing named", () => {
+    const { filter, explains } = request(["--scopes", "@babel"]);
+
+    deepStrictEqual(filter.include, undefined);
+    deepStrictEqual(filter.includeScopes, ["@babel"]);
+    deepStrictEqual(explains, true);
+  });
+
+  it("lists the whole lockfile when only exclusions are given", () => {
+    deepStrictEqual(request(["--exclude", "lodash"]).explains, false);
+    deepStrictEqual(request([]).explains, false);
+  });
+
+  it("leaves a listing on one line per package until --details is asked for", () => {
+    deepStrictEqual(request([]).details, false);
+    deepStrictEqual(request(["--details"]).details, true);
+    deepStrictEqual(request(["-d"]).details, true);
+  });
+
+  it("reads --all", () => {
+    deepStrictEqual(request(["lodash"]).all, false);
+    deepStrictEqual(request(["lodash", "--all"]).all, true);
+  });
+});

package/src/packageFilterArgs.ts

@@ -0,0 +1,98 @@
+import type { PackageFilterOptions } from "./createPackageFilter.ts";
+
+// `node:util` parseArgs shape, spread into a bin's own options so the four
+// filter flags read the same whatever the package manager.
+export const packageFilterParseArgsOptions = {
+  packages: { type: "string", multiple: true },
+  scopes: { type: "string", multiple: true },
+  exclude: { type: "string", multiple: true },
+  "exclude-scopes": { type: "string", multiple: true },
+} as const;
+
+// the `--help` block for the flags above, so every tool documents them alike
+export const packageFilterUsage = `  --packages <names>           only these packages, as names or globs
+  --scopes <scopes>            only these scopes
+  --exclude <names>            never these packages
+  --exclude-scopes <scopes>    never these scopes
+
+Every filter flag takes a comma list, or is repeated.`;
+
+export interface PackageFilterArgValues {
+  packages?: string[];
+  scopes?: string[];
+  exclude?: string[];
+  "exclude-scopes"?: string[];
+}
+
+// A repeated flag is how parseArgs collects several values; a comma list is what
+// people type. Both mean the same thing here.
+const toNames = (values: string[] | undefined): string[] | undefined => {
+  if (!values) return undefined;
+  const names = values
+    .flatMap((value) => value.split(","))
+    .map((name) => name.trim())
+    .filter((name) => name !== "");
+  return names.length > 0 ? names : undefined;
+};
+
+export const toPackageFilterOptions = (
+  values: PackageFilterArgValues,
+): PackageFilterOptions => ({
+  include: toNames(values.packages),
+  includeScopes: toNames(values.scopes),
+  exclude: toNames(values.exclude),
+  excludeScopes: toNames(values["exclude-scopes"]),
+});
+
+// the two flags every `why-duplicate` bin takes on top of the filters
+export const whyDuplicateParseArgsOptions = {
+  all: { type: "boolean", short: "a" },
+  details: { type: "boolean", short: "d" },
+  ...packageFilterParseArgsOptions,
+} as const;
+
+export const whyDuplicateUsage = `  -a, --all                    keep packages that are not duplicated
+  -d, --details                every dependent of every version, not one line each
+
+${packageFilterUsage}`;
+
+export interface WhyDuplicateArgValues extends PackageFilterArgValues {
+  all?: boolean;
+  details?: boolean;
+}
+
+export interface WhyDuplicateRequest {
+  filter: PackageFilterOptions;
+  // false lists the whole lockfile instead of explaining a selection
+  explains: boolean;
+  all: boolean;
+  // the whole tree rather than one line per package
+  details: boolean;
+}
+
+/**
+ * The positional a `why-duplicate` bin takes is the short form of `--packages`.
+ * Naming something to explain is what separates the two reports: without it
+ * there is nothing to be `--all` about, and the whole lockfile is listed.
+ *
+ * Naming one is also asking why it is duplicated, which the one-line form does
+ * not answer — so an explained selection is detailed unless it is a listing.
+ */
+export const toWhyDuplicateRequest = (
+  values: WhyDuplicateArgValues,
+  positionals: string[],
+): WhyDuplicateRequest => {
+  const filter = toPackageFilterOptions(values);
+  const include = [...(filter.include ?? []), ...positionals];
+  const explains = include.length > 0 || filter.includeScopes !== undefined;
+
+  return {
+    filter: {
+      ...filter,
+      include: include.length > 0 ? include : undefined,
+    },
+    explains,
+    all: values.all ?? false,
+    details: values.details === true || explains,
+  };
+};

package/src/packageStyles.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, it } from "bun:test";
+import { ok, strictEqual } from "node:assert/strict";
+import { stylePackageName, stylePackageReference } from "./packageStyles.ts";
+import { createColorize } from "./reportColors.ts";
+
+const environment = { ...process.env };
+
+afterEach(() => {
+  process.env = { ...environment };
+});
+
+const colorize = createColorize(true);
+// eslint-disable-next-line no-control-regex
+const escapePattern = /\u001B\[[\d;]+m/gu;
+const plainText = (text: string): string => text.replaceAll(escapePattern, "");
+
+describe("stylePackageName", () => {
+  it("returns the name untouched when colour is off", () => {
+    strictEqual(
+      stylePackageName(createColorize(false), "@babel/core"),
+      "@babel/core",
+    );
+  });
+
+  it("styles the scope apart from the rest of the name", () => {
+    const styled = stylePackageName(colorize, "@babel/core");
+    strictEqual(plainText(styled), "@babel/core");
+    // the two are not in the same run of escape codes
+    ok(!styled.includes("@babel/core"));
+  });
+
+  it("renders the scope and the name in two shades of one hue", () => {
+    delete process.env.COLORTERM;
+    const styled = stylePackageName(colorize, "@babel/core");
+    ok(styled.startsWith("\u001B[38;5;166m@babel/"));
+    ok(styled.includes("\u001B[38;5;173mcore"));
+  });
+
+  it("switches to 24-bit colour when the terminal advertises it", () => {
+    process.env.COLORTERM = "truecolor";
+    ok(
+      stylePackageName(colorize, "metro").startsWith("\u001B[38;2;215;135;95m"),
+    );
+  });
+
+  it("styles an unscoped name in one run", () => {
+    strictEqual(plainText(stylePackageName(colorize, "metro")), "metro");
+  });
+});
+
+describe("stylePackageReference", () => {
+  it("splits the name from the version", () => {
+    const styled = stylePackageReference(colorize, "metro@0.84.5");
+    strictEqual(plainText(styled), "metro@0.84.5");
+    ok(!styled.includes("metro@"));
+  });
+
+  it("splits past the scope", () => {
+    const styled = stylePackageReference(colorize, "@babel/core@7.28.0");
+    strictEqual(plainText(styled), "@babel/core@7.28.0");
+    ok(!styled.includes("core@"));
+  });
+
+  it("keeps a peer suffix with the version", () => {
+    const styled = stylePackageReference(colorize, "metro@0.84.5(react@19)");
+    strictEqual(plainText(styled), "metro@0.84.5(react@19)");
+    ok(!styled.includes("metro@"));
+  });
+
+  it("leaves a reference carrying no version untouched", () => {
+    strictEqual(
+      stylePackageReference(colorize, "package.json in devDependencies"),
+      "package.json in devDependencies",
+    );
+    strictEqual(stylePackageReference(colorize, "@babel/core"), "@babel/core");
+  });
+});

package/src/packageStyles.ts

@@ -0,0 +1,42 @@
+import type { Colorize, ReportStyle } from "./reportColors.ts";
+
+/**
+ * A package name in two tones: the scope one shade deeper than the name it
+ * prefixes, so the half that identifies stays the readable one without the
+ * other fading out.
+ */
+export const stylePackageName = (
+  color: Colorize,
+  name: string,
+  styles: ReportStyle[] = ["packageName"],
+): string => {
+  // 0 when unscoped, since indexOf returns -1
+  const scopeEnd = name.startsWith("@") ? name.indexOf("/") + 1 : 0;
+  if (scopeEnd === 0) return color(styles, name);
+  const scopeStyles = styles.map((style) =>
+    style === "packageName" ? "scope" : style,
+  );
+  return `${color(scopeStyles, name.slice(0, scopeEnd))}${color(styles, name.slice(scopeEnd))}`;
+};
+
+// The version part of `name@version`, past the scope's own `@`. Yarn's
+// `lodash@npm:4.17.21` and pnpm's `metro@0.84.5(react@19)` both split here.
+const versionStart = (reference: string): number => {
+  const nameStart = reference.startsWith("@") ? reference.indexOf("/") + 1 : 0;
+  if (nameStart === 0 && reference.startsWith("@")) return -1;
+  return reference.indexOf("@", nameStart);
+};
+
+/**
+ * A `name@version` reference. Anything without a version is returned untouched:
+ * the reports also list requesters that are not packages at all, such as
+ * `package.json in devDependencies`.
+ */
+export const stylePackageReference = (
+  color: Colorize,
+  reference: string,
+): string => {
+  const at = versionStart(reference);
+  if (at <= 0) return reference;
+  return `${stylePackageName(color, reference.slice(0, at))}${color("yellow", reference.slice(at))}`;
+};

package/src/parseBinArgs.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, describe, it } from "bun:test";
+import { deepStrictEqual, strictEqual } from "node:assert/strict";
+import { parseBinArgs } from "./parseBinArgs.ts";
+
+const usage = "Usage: tool [options]";
+
+const originalLog = console.log;
+const originalError = console.error;
+
+afterEach(() => {
+  console.log = originalLog;
+  console.error = originalError;
+});
+
+// `process.exitCode` is the test runner's own, so the error path has to hand it
+// back untouched.
+const withCapturedOutput = <T>(run: () => T): { result: T; output: string } => {
+  const lines: string[] = [];
+  const record = (message = ""): void => {
+    lines.push(message);
+  };
+  console.log = record;
+  console.error = record;
+
+  const exitCodeBefore = process.exitCode;
+  try {
+    return { result: run(), output: lines.join("\n") };
+  } finally {
+    if (process.exitCode !== exitCodeBefore) {
+      // bun ignores `process.exitCode = undefined` (node resets it), so the
+      // whole run would end on 1 with every test passing.
+      process.exitCode = exitCodeBefore ?? 0;
+    }
+  }
+};
+
+describe("parseBinArgs", () => {
+  const parse = (args: string[]) =>
+    parseBinArgs(usage, {
+      args,
+      options: { check: { type: "boolean" } },
+      allowPositionals: true,
+    });
+
+  it("parses the arguments it knows", () => {
+    const parsed = parse(["--check", "lodash"]);
+
+    // `parseArgs` returns a null-prototype `values`, and `deepStrictEqual`
+    // compares prototypes.
+    deepStrictEqual(parsed?.values, { __proto__: null, check: true });
+    deepStrictEqual(parsed?.positionals, ["lodash"]);
+  });
+
+  it("prints the usage and stops on --help", () => {
+    const { result, output } = withCapturedOutput(() => parse(["--help"]));
+
+    strictEqual(result, null);
+    strictEqual(output, usage);
+    strictEqual(process.exitCode, undefined);
+  });
+
+  it("names an unknown flag and fails instead of ignoring it", () => {
+    const { result, output } = withCapturedOutput(() => {
+      const parsed = parse(["--chekc"]);
+      strictEqual(process.exitCode, 1);
+      return parsed;
+    });
+
+    strictEqual(result, null);
+    strictEqual(output.includes("--chekc"), true);
+    strictEqual(output.includes(usage), true);
+  });
+});

package/src/parseBinArgs.ts

@@ -0,0 +1,33 @@
+import { parseArgs } from "node:util";
+
+type ParseArgsConfig = NonNullable<Parameters<typeof parseArgs>[0]>;
+
+/**
+ * `parseArgs` with the two things a bin still has to do itself: answer
+ * `--help`, and turn an unknown flag into a readable line instead of a stack
+ * trace. Rejecting the unknown flag matters more than it reads: a mistyped
+ * `--dry-run` silently ignored is a run that applies its changes.
+ *
+ * Returns null when the bin has nothing left to do — the usage was asked for,
+ * or the arguments were rejected and the exit code already says so.
+ */
+export const parseBinArgs = <T extends ParseArgsConfig>(
+  usage: string,
+  config: T,
+): ReturnType<typeof parseArgs<T>> | null => {
+  const args = config.args ?? process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(usage);
+    return null;
+  }
+
+  try {
+    return parseArgs(config);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error();
+    console.error(usage);
+    process.exitCode = 1;
+    return null;
+  }
+};