@zgeoff/chex 0.0.0 → 0.0.2

package/src/collect-command-names.ts

@@ -0,0 +1,297 @@
+import type { ShellWord } from './parse-shell-words.ts';
+import { parseShellWords } from './parse-shell-words.ts';
+
+// Each command contributes the word the shell runs, after any NAME=value assignments, plus the
+// script that bash, sh or bun runs. A command outside the forms read here returns undefined, so the
+// caller skips the step rather than guess what it runs.
+export function collectCommandNames(words: readonly ShellWord[]): string[] | undefined {
+  const names = splitCommands(words).map((command) => collectRunTargets(command));
+
+  return names.every((targets) => targets !== undefined) ? names.flat() : undefined;
+}
+
+function splitCommands(words: readonly ShellWord[]): ShellWord[][] {
+  const commands: ShellWord[][] = [[]];
+
+  for (const word of words) {
+    if (word.isOperator) {
+      commands.push([]);
+    } else {
+      commands.at(-1)?.push(word);
+    }
+  }
+
+  return commands;
+}
+
+// A command substitution runs a command that the parser does not split out, a heredoc body holds
+// lines that are data, and a name held in a variable is known only when the step runs.
+const unreadablePattern = /\$\((?!\()|`|(?<!<)<<(?!<)/u;
+
+function collectRunTargets(command: readonly ShellWord[]): string[] | undefined {
+  const start = command.findIndex((word) => !word.isAssignment);
+  const words = start === -1 ? [] : command.slice(start).map((word) => word.text);
+  const [name, ...rest] = words;
+
+  if (name === undefined) {
+    return [];
+  }
+
+  if (words.some((word) => unreadablePattern.test(word)) || name.includes('$')) {
+    return undefined;
+  }
+
+  if (name === 'bash' || name === 'sh') {
+    return collectShellTargets(name, rest);
+  }
+
+  return name === 'bun' ? collectBunTargets(rest) : [name];
+}
+
+const shellLongOptions = new Set(['--login', '--noediting', '--noprofile', '--norc', '--posix']);
+
+// With -s a shell reads its commands from standard input, so its first operand is an argument, and
+// with -c that operand is a command string. -o and +o take an option name.
+function collectShellTargets(name: string, args: readonly string[]): string[] | undefined {
+  let flags = '';
+  let index = 0;
+
+  while (index < args.length) {
+    const argument = args[index] ?? '';
+
+    if (argument === '--') {
+      index += 1;
+      break;
+    }
+
+    if (argument === '-o' || argument === '+o') {
+      index += 2;
+    } else if (/^[-+][A-Za-z]+$/u.test(argument)) {
+      flags += argument.slice(1);
+      index += 1;
+    } else if (argument.startsWith('-')) {
+      if (!shellLongOptions.has(argument)) {
+        return undefined;
+      }
+
+      index += 1;
+    } else {
+      break;
+    }
+  }
+
+  return collectShellOperandTargets(name, flags, args[index]);
+}
+
+function collectShellOperandTargets(
+  name: string,
+  flags: string,
+  operand: string | undefined,
+): string[] | undefined {
+  if (flags.includes('s')) {
+    return [name];
+  }
+
+  if (!flags.includes('c')) {
+    return operand === undefined ? [name] : [name, operand];
+  }
+
+  const words = operand === undefined ? undefined : parseShellWords(operand);
+  const names = words === undefined ? undefined : collectCommandNames(words);
+
+  return names === undefined ? undefined : [name, ...names];
+}
+
+// The subcommands `bun --help` lists, with their short aliases. Bun runs any other first operand as
+// a file or a package script.
+const bunCommands = new Set([
+  'a',
+  'add',
+  'audit',
+  'build',
+  'c',
+  'check',
+  'create',
+  'dedupe',
+  'exec',
+  'i',
+  'info',
+  'init',
+  'install',
+  'link',
+  'lint',
+  'outdated',
+  'patch',
+  'pm',
+  'prune',
+  'publish',
+  'remove',
+  'repl',
+  'rm',
+  'test',
+  'unlink',
+  'update',
+  'upgrade',
+  'why',
+  'x',
+]);
+
+function collectBunTargets(args: readonly string[]): string[] | undefined {
+  const firstIndex = findBunOperand(args, 0);
+  const first = firstIndex === undefined ? undefined : args[firstIndex];
+
+  if (firstIndex === undefined) {
+    return undefined;
+  }
+
+  if (first !== 'run') {
+    return first === undefined || bunCommands.has(first) ? ['bun'] : ['bun', first];
+  }
+
+  const scriptIndex = findBunOperand(args, firstIndex + 1);
+  const script = scriptIndex === undefined ? undefined : args[scriptIndex];
+
+  if (scriptIndex === undefined) {
+    return undefined;
+  }
+
+  return script === undefined ? ['bun'] : ['bun', script];
+}
+
+// The options `bun run --help` lists that take a value, as `--cwd dir` or `--cwd=dir`.
+const bunValueOptions = new Set([
+  '-F',
+  '--filter',
+  '-r',
+  '--preload',
+  '--require',
+  '--import',
+  '-d',
+  '--define',
+  '-l',
+  '--loader',
+  '-c',
+  '--config',
+  '--conditions',
+  '--console-depth',
+  '--cpu-prof-dir',
+  '--cpu-prof-interval',
+  '--cpu-prof-name',
+  '--cron-period',
+  '--cron-title',
+  '--cwd',
+  '--disable-warning',
+  '--dns-result-order',
+  '--drop',
+  '--elide-lines',
+  '--env-file',
+  '--extension-order',
+  '--feature',
+  '--fetch-preconnect',
+  '--heap-prof-dir',
+  '--heap-prof-interval',
+  '--heap-prof-name',
+  '--install',
+  '--jsx-factory',
+  '--jsx-fragment',
+  '--jsx-import-source',
+  '--jsx-runtime',
+  '--main-fields',
+  '--max-http-header-size',
+  '--port',
+  '--redirect-warnings',
+  '--shell',
+  '--title',
+  '--tsconfig-override',
+  '--unhandled-rejections',
+  '--user-agent',
+  '--watch-kill-signal',
+]);
+
+// The options `bun run --help` lists that take no value. The inspect options take one only after
+// an `=`.
+const bunFlagOptions = new Set([
+  '-b',
+  '--bun',
+  '-h',
+  '--help',
+  '--check',
+  '--cpu-prof',
+  '--cpu-prof-md',
+  '--experimental-http2-fetch',
+  '--experimental-http3-fetch',
+  '--experimental-stream-iter',
+  '--expose-gc',
+  '--heap-prof',
+  '--heap-prof-md',
+  '--hot',
+  '--if-present',
+  '--ignore-dce-annotations',
+  '--insecure-http-parser',
+  '--inspect',
+  '--inspect-brk',
+  '--inspect-wait',
+  '--interactive',
+  '--jsx-side-effects',
+  '--no-addons',
+  '--no-clear-screen',
+  '--no-deprecation',
+  '--no-env-file',
+  '--no-exit-on-error',
+  '--no-ffi-cc',
+  '--no-install',
+  '--no-macros',
+  '--no-orphans',
+  '--no-warnings',
+  '--parallel',
+  '--pending-deprecation',
+  '--prefer-latest',
+  '--prefer-offline',
+  '--preserve-symlinks',
+  '--preserve-symlinks-main',
+  '--redis-preconnect',
+  '--sequential',
+  '--silent',
+  '--smol',
+  '--sql-preconnect',
+  '--throw-deprecation',
+  '--tls-max-v1.2',
+  '--tls-max-v1.3',
+  '--tls-min-v1.0',
+  '--tls-min-v1.1',
+  '--tls-min-v1.2',
+  '--tls-min-v1.3',
+  '--trace-deprecation',
+  '--trace-warnings',
+  '--use-bundled-ca',
+  '--use-openssl-ca',
+  '--use-system-ca',
+  '--watch',
+  '--workspaces',
+  '--zero-fill-buffers',
+]);
+
+// The index of the first operand at or after start, past each option and the value it takes; the
+// length of args when no operand follows, and undefined at an option outside the two tables.
+function findBunOperand(args: readonly string[], start: number): number | undefined {
+  let index = start;
+
+  while (index < args.length) {
+    const argument = args[index] ?? '';
+    const option = argument.split('=')[0] ?? '';
+
+    if (!argument.startsWith('-')) {
+      return index;
+    }
+
+    if (bunValueOptions.has(option)) {
+      index += argument.includes('=') ? 1 : 2;
+    } else if (bunFlagOptions.has(option)) {
+      index += 1;
+    } else {
+      return undefined;
+    }
+  }
+
+  return index;
+}

package/src/collect-expression-references.ts

@@ -0,0 +1,17 @@
+// A string literal in an expression may hold `}}`, so the end of an expression is found past them.
+const expressionPattern = /\$\{\{(?<body>(?:'(?:[^']|'')*'|[^'])*?)\}\}/gsu;
+const indexPattern = /\[\s*'(?<name>[A-Za-z_][\w-]*)'\s*\]/gu;
+const stringPattern = /'(?:[^']|'')*'/gu;
+const referencePattern = /[A-Za-z_][\w-]*(?:\.[A-Za-z_][\w-]*)+/gu;
+
+// Only a context reference inside an expression changes between runs: the same words outside one,
+// or in one of its string literals, are text. `github['sha']` reads the same value as `github.sha`.
+export function collectExpressionReferences(text: string): string[] {
+  return [...text.matchAll(expressionPattern)].flatMap((expression) => {
+    const body = (expression.groups?.['body'] ?? '')
+      .replaceAll(indexPattern, '.$<name>')
+      .replaceAll(stringPattern, "''");
+
+    return [...body.matchAll(referencePattern)].map((reference) => reference[0]);
+  });
+}

package/src/dependency-gates/collect-stale-age-gate-excludes.ts

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict';
+import { firstPartyScopes } from './first-party-scopes.ts';
+import { isRecord } from './is-record.ts';
+import type { DependencyGateFinding } from './types.ts';
+
+export function collectStaleAgeGateExcludes(
+  bunfig: string,
+  today: string,
+): DependencyGateFinding[] {
+  const removalDates = collectRemovalDates(bunfig);
+
+  return parseAgeGateExcludes(bunfig)
+    .filter((name) => !firstPartyScopes.some((scope) => name.startsWith(scope)))
+    .flatMap((name) => {
+      const removalDate = removalDates.get(name);
+
+      if (removalDate === undefined) {
+        return [
+          {
+            path: 'bunfig.toml',
+            entry: name,
+            problem: 'the age-gate exclude has no dated removal comment',
+          },
+        ];
+      }
+
+      if (removalDate < today) {
+        return [
+          {
+            path: 'bunfig.toml',
+            entry: name,
+            problem: `the age-gate exclude was due for removal on ${removalDate}`,
+          },
+        ];
+      }
+
+      return [];
+    });
+}
+
+// The shared audit-fix workflow writes this comment for each exclude it adds, and removes the
+// exclude once the date passes.
+const removalCommentPattern =
+  /^# (?<name>\S+) \S+ \(published [^)]*\) ages past the gate ~(?<date>\d{4}-\d{2}-\d{2}) — remove then/gmu;
+
+function collectRemovalDates(bunfig: string): Map<string, string> {
+  const removalDates = new Map<string, string>();
+
+  for (const match of bunfig.matchAll(removalCommentPattern)) {
+    const name = match.groups?.['name'];
+    const date = match.groups?.['date'];
+
+    assert.ok(name !== undefined && date !== undefined, 'the removal comment pattern names both');
+
+    const latest = removalDates.get(name);
+
+    if (latest === undefined || date > latest) {
+      removalDates.set(name, date);
+    }
+  }
+
+  return removalDates;
+}
+
+function parseAgeGateExcludes(bunfig: string): string[] {
+  const parsed: unknown = Bun.TOML.parse(bunfig);
+  const install = isRecord(parsed) ? parsed['install'] : undefined;
+  const excludes = isRecord(install) ? install['minimumReleaseAgeExcludes'] : undefined;
+
+  if (excludes === undefined) {
+    return [];
+  }
+
+  if (!isStringList(excludes)) {
+    throw new TypeError('bunfig.toml sets a minimumReleaseAgeExcludes that is not a list of names');
+  }
+
+  return excludes;
+}
+
+function isStringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item: unknown) => typeof item === 'string');
+}

package/src/dependency-gates/collect-unneeded-audit-ignores.ts

@@ -0,0 +1,41 @@
+import type { AuditAdvisory, DependencyGateFinding } from './types.ts';
+
+interface UnneededAuditIgnoresInput {
+  readonly ignoreIDs: readonly string[];
+  readonly advisories: readonly AuditAdvisory[];
+  readonly fixablePackages: readonly string[];
+}
+
+export function collectUnneededAuditIgnores(
+  input: UnneededAuditIgnoresInput,
+): DependencyGateFinding[] {
+  return input.ignoreIDs.flatMap((ignoreID) => {
+    const matches = input.advisories.filter((advisory) => advisory.advisoryIDs.includes(ignoreID));
+
+    if (matches.length === 0) {
+      return [
+        {
+          path: 'package.json',
+          entry: ignoreID,
+          problem: 'no locked package has the ignored advisory',
+        },
+      ];
+    }
+
+    const fixable = matches.find((advisory) =>
+      input.fixablePackages.includes(advisory.packageName),
+    );
+
+    if (fixable !== undefined) {
+      return [
+        {
+          path: 'package.json',
+          entry: ignoreID,
+          problem: `bun audit fix can move ${fixable.packageName} to a patched release in range`,
+        },
+      ];
+    }
+
+    return [];
+  });
+}

package/src/dependency-gates/collect-unneeded-overrides.ts

@@ -0,0 +1,70 @@
+import type { DependencyGateFinding, LockfileDependent } from './types.ts';
+
+interface UnneededOverridesInput {
+  readonly overrides: Readonly<Record<string, string>>;
+  readonly catalog: Readonly<Record<string, string>>;
+  readonly catalogs: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  readonly dependents: readonly LockfileDependent[];
+}
+
+export function collectUnneededOverrides(input: UnneededOverridesInput): DependencyGateFinding[] {
+  return Object.entries(input.overrides).flatMap(([name, pin]) => {
+    const ranges = input.dependents
+      .filter((dependent) => dependent.name === name)
+      .map((dependent) => resolveCatalogRange(input, name, dependent.range));
+
+    if (ranges.length === 0) {
+      return [
+        {
+          path: 'package.json',
+          entry: name,
+          problem: 'no package in bun.lock depends on the overridden package',
+        },
+      ];
+    }
+
+    const isPinOutsideARange = ranges.some(
+      (range) => !isSemverRange(range) || !Bun.semver.satisfies(pin, range),
+    );
+
+    const isPinTheCatalogVersion = input.catalog[name] === pin;
+
+    if (isPinOutsideARange || isPinTheCatalogVersion) {
+      return [];
+    }
+
+    return [
+      {
+        path: 'package.json',
+        entry: name,
+        problem: `every range in bun.lock already admits ${pin}, so the override changes nothing`,
+      },
+    ];
+  });
+}
+
+// bun.lock keeps a workspace's `catalog:` reference as it is written in its package.json.
+function resolveCatalogRange(input: UnneededOverridesInput, name: string, range: string): string {
+  if (!range.startsWith('catalog:')) {
+    return range;
+  }
+
+  const catalogName = range.slice('catalog:'.length);
+  const catalog = catalogName === '' ? input.catalog : input.catalogs[catalogName];
+
+  return catalog?.[name] ?? range;
+}
+
+const comparatorPattern =
+  /^(?:[<>]=?|=|\^|~)?v?(?:\d+|[*Xx])(?:\.(?:\d+|[*Xx])){0,2}(?:-[\w.-]+)?(?:\+[\w.-]+)?$/u;
+
+// Bun.semver.satisfies reads a range it cannot parse, such as a dist-tag, a `workspace:` or `npm:`
+// protocol or a git URL, as any version, so only a range of plain comparators can admit the pin.
+function isSemverRange(range: string): boolean {
+  return range.split('||').every((part) =>
+    part
+      .trim()
+      .split(/\s+/u)
+      .every((token) => token === '' || token === '-' || comparatorPattern.test(token)),
+  );
+}

package/src/dependency-gates/first-party-scopes.ts

@@ -0,0 +1 @@
+export const firstPartyScopes = ['@zgeoff/', '@impz/'] as const;

package/src/dependency-gates/is-record.ts

@@ -0,0 +1,4 @@
+// repo-sync delivers this folder without the @zgeoff/std package, so the folder keeps its own guard.
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/dependency-gates/parse-audit-advisories.ts

@@ -0,0 +1,33 @@
+import { isRecord } from './is-record.ts';
+import type { AuditAdvisory } from './types.ts';
+
+export function parseAuditAdvisories(output: string): AuditAdvisory[] {
+  const report: unknown = JSON.parse(output);
+
+  if (!isRecord(report)) {
+    throw new TypeError('bun audit --json printed no object');
+  }
+
+  return Object.entries(report).flatMap(([packageName, advisories]) => {
+    if (!Array.isArray(advisories)) {
+      throw new TypeError(`bun audit --json lists no advisories for ${packageName}`);
+    }
+
+    return advisories.map((advisory: unknown) => {
+      if (
+        !isRecord(advisory) ||
+        typeof advisory['id'] !== 'number' ||
+        typeof advisory['url'] !== 'string'
+      ) {
+        throw new TypeError(
+          `bun audit --json has an advisory with no id or url for ${packageName}`,
+        );
+      }
+
+      return {
+        advisoryIDs: [String(advisory['id']), ...advisory['url'].split('/').slice(-1)],
+        packageName,
+      };
+    });
+  });
+}

package/src/dependency-gates/parse-audit-ignore-ids.ts

@@ -0,0 +1,15 @@
+import { parseShellWords } from '../parse-shell-words.ts';
+
+export function parseAuditIgnoreIDs(auditScript: string): string[] {
+  const words = parseShellWords(auditScript).map((word) => word.text);
+
+  return words.flatMap((word, index) => {
+    if (word.startsWith('--ignore=')) {
+      return [word.slice('--ignore='.length)];
+    }
+
+    const next = words[index + 1];
+
+    return word === '--ignore' && next !== undefined ? [next] : [];
+  });
+}

package/src/dependency-gates/parse-fixable-packages.ts

@@ -0,0 +1,29 @@
+import { isRecord } from './is-record.ts';
+
+export function parseFixablePackages(output: string): string[] {
+  const plan: unknown = JSON.parse(output);
+
+  if (!isRecord(plan)) {
+    throw new TypeError('bun audit fix --json printed no object');
+  }
+
+  const stuck = new Set([...collectNames(plan, 'blocked'), ...collectNames(plan, 'unfixable')]);
+
+  return [...new Set(collectNames(plan, 'fixes'))].filter((name) => !stuck.has(name));
+}
+
+function collectNames(plan: Record<string, unknown>, key: string): string[] {
+  const list = plan[key];
+
+  if (!Array.isArray(list)) {
+    throw new TypeError(`bun audit fix --json has no ${key} list`);
+  }
+
+  return list.map((entry: unknown) => {
+    if (!isRecord(entry) || typeof entry['name'] !== 'string') {
+      throw new TypeError(`bun audit fix --json has an entry with no name in its ${key} list`);
+    }
+
+    return entry['name'];
+  });
+}

package/src/dependency-gates/parse-lockfile-dependents.ts

@@ -0,0 +1,77 @@
+import { isRecord } from './is-record.ts';
+import type { LockfileDependent } from './types.ts';
+
+// A root override reaches a workspace's own dependencies too, so the workspaces' ranges count
+// beside the ranges of the registry packages.
+export function parseLockfileDependents(lockfile: string): LockfileDependent[] {
+  const parsed: unknown = Bun.JSONC.parse(lockfile);
+  const workspaces = isRecord(parsed) ? parsed['workspaces'] : undefined;
+  const packages = isRecord(parsed) ? parsed['packages'] : undefined;
+
+  if (!isRecord(workspaces)) {
+    throw new TypeError('bun.lock has no workspaces object');
+  }
+
+  if (!isRecord(packages)) {
+    throw new TypeError('bun.lock has no packages object');
+  }
+
+  return [
+    ...Object.entries(workspaces).flatMap(([path, workspace]) =>
+      collectWorkspaceDependents(path, workspace),
+    ),
+    ...Object.values(packages).flatMap((entry) => collectPackageDependents(entry)),
+  ];
+}
+
+const workspaceFields = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const;
+
+function collectWorkspaceDependents(path: string, workspace: unknown): LockfileDependent[] {
+  const dependent = path === '' ? 'the root workspace' : path;
+
+  return collectDeclaredRanges(dependent, workspace, workspaceFields);
+}
+
+function collectDeclaredRanges(
+  dependent: string,
+  metadata: unknown,
+  fields: readonly string[],
+): LockfileDependent[] {
+  if (!isRecord(metadata)) {
+    return [];
+  }
+
+  return fields.flatMap((field) => {
+    const ranges = metadata[field];
+
+    if (!isRecord(ranges)) {
+      return [];
+    }
+
+    return Object.entries(ranges).flatMap(([name, range]) =>
+      typeof range === 'string' ? [{ dependent, name, range }] : [],
+    );
+  });
+}
+
+const packageFields = ['dependencies', 'optionalDependencies', 'peerDependencies'] as const;
+
+// A registry entry is [id, registry, metadata, integrity]; a workspace or link entry is shorter.
+function collectPackageDependents(entry: unknown): LockfileDependent[] {
+  const [dependent, , metadata] = isList(entry) ? entry : [];
+
+  if (typeof dependent !== 'string') {
+    throw new TypeError('bun.lock has a package entry that does not start with its id');
+  }
+
+  return collectDeclaredRanges(dependent, metadata, packageFields);
+}
+
+function isList(value: unknown): value is readonly unknown[] {
+  return Array.isArray(value);
+}