@zgeoff/chex 0.0.3 → 0.0.5

package/README.md

@@ -52,14 +52,14 @@ The docs checks read the repo's READMEs, its `docs/` tree and its skills:
 
 The repo checks read the branch, the pushed commits and the repo's config:
 
-| Check              | Fails on                                                                    | Arguments       |
-| ------------------ | --------------------------------------------------------------------------- | --------------- |
-| `commits`          | a pushed commit whose message fails `@zgeoff/commitlint-config`             | `--pushed-refs` |
-| `local-paths`      | a line a pushed commit adds that holds the home folder or the host name     | `--pushed-refs` |
-| `test-timeouts`    | a `bun test` timeout above its lane's limit, in a script or a `bunfig.toml` | none            |
-| `workflows`        | nothing: it warns on each fault of the shared workflow lint, and passes     | the paths       |
-| `dependency-gates` | a stale age-gate exclude, an override or an audit ignore that nothing needs | none            |
-| `uncommitted`      | a file the branch changes that holds a change the push does not send        | none            |
+| Check              | Fails on                                                                                                                       | Arguments       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | --------------- |
+| `commits`          | a pushed commit whose message fails `@zgeoff/commitlint-config`                                                                | `--pushed-refs` |
+| `local-paths`      | a line a pushed commit adds that holds the home folder or the host name                                                        | `--pushed-refs` |
+| `test-timeouts`    | a `bun test` timeout above its lane's limit, in a script or a `bunfig.toml`                                                    | none            |
+| `workflows`        | nothing: it warns on each fault of the shared workflow lint, and passes                                                        | the paths       |
+| `dependency-gates` | a stale age-gate exclude, an override or an audit ignore that nothing needs, or a first-party package with no age-gate exclude | none            |
+| `uncommitted`      | a file the branch changes that holds a change the push does not send                                                           | none            |
 
 With no path, `prose` and `links` read every README outside `.claude/` and `.agents/`, every file
 under `docs/`, each spike's `results.md`, and the Markdown under `.agents/skills/`,
@@ -79,8 +79,10 @@ skipped file back:
 - `prose`, `links`, `readmes` and `skill` skip each file that `.gitattributes` marks
   `linguist-vendored`.
 
-`chex init` writes the `extends` line into `lefthook.yml` and adds a `check:docs` script of
-`chex prose length links skill` when the repo has none. A second run changes nothing.
+`chex init` writes the `extends` line and a
+[`chex-baseline` job](../../docs/architecture/pre-push-baseline.md#a-checkout-without-the-baseline)
+into `lefthook.yml`, and adds a `check:docs` script of `chex prose length links skill` when the repo
+has none. A second run changes nothing.
 
 ## The pre-push baseline
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/chex",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Run each shared docs and repo check as one subcommand, with the lefthook pre-push baseline that calls them",
   "keywords": [
     "checks",
@@ -34,7 +34,7 @@
     "ts-pattern": "5.9.2"
   },
   "devDependencies": {
-    "@types/bun": "1.4.3",
+    "@types/bun": "1.4.4",
     "tiny-invariant": "1.3.3",
     "tsrs": "0.18.0-ts7.1.0-dev.20260929",
     "typescript": "7.0.2"

package/src/build-init-plan.ts

@@ -3,6 +3,7 @@ import type { PackageOutcome } from './build-init-package.ts';
 import { buildInitPackage, docsScript } from './build-init-package.ts';
 import type { LefthookOutcome } from './build-lefthook-extends.ts';
 import { baselinePath, buildLefthookExtends } from './build-lefthook-extends.ts';
+import { buildLefthookGuard, guardName, guardedHooks } from './build-lefthook-guard.ts';
 
 export interface InitWrite {
   readonly file: 'lefthook.yml' | 'package.json';
@@ -81,15 +82,32 @@ function buildPlanFromSteps(steps: readonly InitStep[]): InitPlan {
   };
 }
 
-const keptStep: InitStep = { reasons: [], writes: [], notes: [] };
-
 function buildLefthookStep(lefthookText: string | undefined): InitStep {
   return match<LefthookOutcome, InitStep>(buildLefthookExtends(lefthookText))
-    .with({ kind: 'unchanged' }, () => keptStep)
+    .with({ kind: 'unchanged' }, (outcome) => buildGuardStep(outcome.text, []))
+    .with({ kind: 'changed' }, (outcome) =>
+      buildGuardStep(outcome.text, [`lefthook.yml extends ${baselinePath}`]),
+    )
+    .with({ kind: 'refused' }, (outcome) => ({ reasons: [outcome.reason], writes: [], notes: [] }))
+    .exhaustive();
+}
+
+const keptStep: InitStep = { reasons: [], writes: [], notes: [] };
+
+function buildGuardStep(text: string, notes: readonly string[]): InitStep {
+  return match<LefthookOutcome, InitStep>(buildLefthookGuard(text))
+    .with({ kind: 'unchanged' }, () =>
+      notes.length === 0
+        ? keptStep
+        : { reasons: [], writes: [{ file: 'lefthook.yml', text }], notes },
+    )
     .with({ kind: 'changed' }, (outcome) => ({
       reasons: [],
       writes: [{ file: 'lefthook.yml', text: outcome.text }],
-      notes: [`lefthook.yml extends ${baselinePath}`],
+      notes: [
+        ...notes,
+        `lefthook.yml runs ${guardName} first in ${guardedHooks.join(' and ')}, which fails when ${baselinePath} is missing`,
+      ],
     }))
     .with({ kind: 'refused' }, (outcome) => ({ reasons: [outcome.reason], writes: [], notes: [] }))
     .exhaustive();

package/src/build-lefthook-extends.ts

@@ -1,9 +1,9 @@
-import { isRecord } from '@zgeoff/std';
+import { parseLefthookConfig } from './parse-lefthook-config.ts';
 
 export const baselinePath = 'node_modules/@zgeoff/chex/lefthook.yml';
 
 export type LefthookOutcome =
-  | { readonly kind: 'unchanged' }
+  | { readonly kind: 'unchanged'; readonly text: string }
   | { readonly kind: 'changed'; readonly text: string }
   | { readonly kind: 'refused'; readonly reason: string };
 
@@ -18,7 +18,7 @@ export function buildLefthookExtends(text: string | undefined): LefthookOutcome
     return { kind: 'changed', text: `extends:\n  - ${baselinePath}\n` };
   }
 
-  const config = parseConfig(text);
+  const config = parseLefthookConfig(text);
 
   if (config === undefined) {
     return { kind: 'refused', reason: 'lefthook.yml is not a YAML mapping' };
@@ -31,7 +31,7 @@ export function buildLefthookExtends(text: string | undefined): LefthookOutcome
   }
 
   if (Array.isArray(extended) && extended.includes(baselinePath)) {
-    return { kind: 'unchanged' };
+    return { kind: 'unchanged', text };
   }
 
   const inline = inlineExtends.exec(text);
@@ -54,25 +54,9 @@ export function buildLefthookExtends(text: string | undefined): LefthookOutcome
   return checkEdit(config, `${text.slice(0, end)}\n  - ${baselinePath}${text.slice(end)}`);
 }
 
-function parseConfig(text: string): Record<string, unknown> | undefined {
-  let parsed: unknown;
-
-  try {
-    parsed = Bun.YAML.parse(text);
-  } catch {
-    return undefined;
-  }
-
-  if (parsed === null) {
-    return {};
-  }
-
-  return isRecord(parsed) ? parsed : undefined;
-}
-
 // A flow mapping or a second YAML document reads differently once a block key joins the text.
 function checkEdit(config: Record<string, unknown>, edited: string): LefthookOutcome {
-  const editedConfig = parseConfig(edited);
+  const editedConfig = parseLefthookConfig(edited);
 
   if (editedConfig !== undefined) {
     const { extends: editedExtends, ...editedRest } = editedConfig;

package/src/build-lefthook-guard.ts

@@ -0,0 +1,170 @@
+import { isRecord } from '@zgeoff/std';
+import type { LefthookOutcome } from './build-lefthook-extends.ts';
+import { baselinePath } from './build-lefthook-extends.ts';
+import { parseLefthookConfig } from './parse-lefthook-config.ts';
+
+export const guardedHooks = ['pre-commit', 'pre-push'] as const;
+
+// lefthook runs the repo's own jobs before an extended file's, and a piped hook stops at the first
+// failure, so the guard goes first.
+export function buildLefthookGuard(text: string): LefthookOutcome {
+  let edited = text;
+
+  for (const hook of guardedHooks) {
+    const edit = buildHookEdit(edited, hook);
+
+    if (edit.kind === 'refused') {
+      return edit;
+    }
+
+    edited = edit.text;
+  }
+
+  return edited === text ? { kind: 'unchanged', text } : { kind: 'changed', text: edited };
+}
+
+type GuardedHook = (typeof guardedHooks)[number];
+
+type HookEdit =
+  | { readonly kind: 'guarded'; readonly text: string }
+  | { readonly kind: 'refused'; readonly reason: string };
+
+export const guardName = 'chex-baseline';
+
+// lefthook drops an extends entry whose file is missing and prints nothing, so a checkout with no
+// node_modules runs none of the baseline's jobs unless a job in the repo's own config fails.
+const guardScript = [
+  `if [ ! -f ${baselinePath} ]; then`,
+  `  echo "${guardName}: ${baselinePath} is missing, so lefthook runs none of the chex baseline's jobs; run bun install, then try again"`,
+  '  exit 1',
+  'fi',
+  '# {files}',
+];
+
+// lefthook 2.2.2 skips a job whose run substitutes no file when no file matches: a commit that
+// stages none, or a push of another branch while the checked-out one has nothing to push. Every
+// repo that takes the baseline has package.json, and the shell comment hides it from the check.
+const guardFiles = 'echo package.json';
+const guardJob = { name: guardName, files: guardFiles, run: `${guardScript.join('\n')}\n` };
+
+function buildHookEdit(text: string, hook: GuardedHook): HookEdit {
+  const config = parseLefthookConfig(text);
+
+  if (config === undefined) {
+    return { kind: 'refused', reason: 'lefthook.yml is not a YAML mapping' };
+  }
+
+  const hookConfig = config[hook];
+
+  if (hookConfig === undefined) {
+    const separator = text.endsWith('\n') ? '' : '\n';
+
+    return checkHookEdit(
+      config,
+      hook,
+      { jobs: [guardJob] },
+      `${text}${separator}\n${hook}:\n  jobs:\n${formatGuardJob('    ')}`,
+    );
+  }
+
+  const listedJobs = isRecord(hookConfig) ? hookConfig['jobs'] : undefined;
+
+  if (!isRecord(hookConfig) || !Array.isArray(listedJobs)) {
+    return refuseHook(hook);
+  }
+
+  const jobs: readonly unknown[] = listedJobs;
+  const listed = jobs.find((job: unknown) => isRecord(job) && job['name'] === guardName);
+
+  if (listed !== undefined) {
+    return Bun.deepEquals(listed, guardJob, true)
+      ? { kind: 'guarded', text }
+      : {
+          kind: 'refused',
+          reason: `lefthook.yml has a ${guardName} job under ${hook} that differs from the one chex init writes; remove it, then run chex init again`,
+        };
+  }
+
+  const insert = findGuardInsert(text, hook);
+
+  if (insert === undefined) {
+    return refuseHook(hook);
+  }
+
+  return checkHookEdit(
+    config,
+    hook,
+    { ...hookConfig, jobs: [guardJob, ...jobs] },
+    `${text.slice(0, insert.offset)}${formatGuardJob(insert.indent)}${text.slice(insert.offset)}`,
+  );
+}
+
+// A job list that the text lays out in a form the line search misreads, such as a flow list or a
+// key in quotes, parses to something else once the guard lines go in.
+function checkHookEdit(
+  config: Record<string, unknown>,
+  hook: GuardedHook,
+  hookConfig: Record<string, unknown>,
+  edited: string,
+): HookEdit {
+  const editedConfig = parseLefthookConfig(edited);
+
+  if (
+    editedConfig !== undefined &&
+    Bun.deepEquals(editedConfig, { ...config, [hook]: hookConfig }, true)
+  ) {
+    return { kind: 'guarded', text: edited };
+  }
+
+  return refuseHook(hook);
+}
+
+function refuseHook(hook: GuardedHook): HookEdit {
+  return {
+    kind: 'refused',
+    reason: `lefthook.yml writes ${hook} in a form chex init does not edit; write its ${hook} jobs as a block list, then run chex init again`,
+  };
+}
+
+function formatGuardJob(indent: string): string {
+  const lines = [
+    `- name: ${guardName}`,
+    `  files: ${guardFiles}`,
+    '  run: |',
+    ...guardScript.map((line) => `    ${line}`),
+  ];
+
+  return lines.map((line) => `${indent}${line}\n`).join('');
+}
+
+interface GuardInsert {
+  readonly offset: number;
+  readonly indent: string;
+}
+
+function findGuardInsert(text: string, hook: GuardedHook): GuardInsert | undefined {
+  const hookLine = new RegExp(`^${hook}:[ \\t]*(?:#.*)?$`, 'mu').exec(text);
+
+  if (hookLine === null) {
+    return undefined;
+  }
+
+  const blockStart = hookLine.index + hookLine[0].length;
+  const blockEnd = /^[^\s#]/mu.exec(text.slice(blockStart + 1));
+  const blockStop = blockEnd === null ? text.length : blockStart + 1 + blockEnd.index;
+  const block = text.slice(blockStart, blockStop);
+  const jobsLine = /^[ \t]+jobs:[ \t]*(?:#.*)?$/mu.exec(block);
+
+  if (jobsLine === null) {
+    return undefined;
+  }
+
+  const afterJobs = jobsLine.index + jobsLine[0].length;
+  const item = /^(?<indent>[ \t]*)- /mu.exec(block.slice(afterJobs));
+
+  if (item === null) {
+    return undefined;
+  }
+
+  return { offset: blockStart + afterJobs + 1, indent: item.groups?.['indent'] ?? '' };
+}

package/src/dependency-gates/collect-missing-first-party-excludes.ts

@@ -0,0 +1,24 @@
+import { firstPartyScopes } from './first-party-scopes.ts';
+import type { AgeGate } from './parse-age-gate.ts';
+import type { DependencyGateFinding } from './types.ts';
+
+// An exclude with a version, such as `@zgeoff/std@1.0.0`, lets only that release through, so it
+// does not count.
+export function collectMissingFirstPartyExcludes(
+  ageGate: AgeGate,
+  registryNames: readonly string[],
+): DependencyGateFinding[] {
+  if (!ageGate.isOn) {
+    return [];
+  }
+
+  return registryNames
+    .filter((name) => firstPartyScopes.some((scope) => name.startsWith(scope)))
+    .filter((name) => !ageGate.excludes.includes(name))
+    .map((name) => ({
+      path: 'bunfig.toml',
+      entry: name,
+      problem:
+        'the first-party package has no age-gate exclude, so bun install refuses each release younger than the gate',
+    }));
+}

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

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { firstPartyScopes } from './first-party-scopes.ts';
-import { isRecord } from './is-record.ts';
+import { parseAgeGate } from './parse-age-gate.ts';
 import type { DependencyGateFinding } from './types.ts';
 
 export function collectStaleAgeGateExcludes(
@@ -9,8 +9,8 @@ export function collectStaleAgeGateExcludes(
 ): DependencyGateFinding[] {
   const removalDates = collectRemovalDates(bunfig);
 
-  return parseAgeGateExcludes(bunfig)
-    .filter((name) => !firstPartyScopes.some((scope) => name.startsWith(scope)))
+  return parseAgeGate(bunfig)
+    .excludes.filter((name) => !firstPartyScopes.some((scope) => name.startsWith(scope)))
     .flatMap((name) => {
       const removalDate = removalDates.get(name);
 
@@ -61,23 +61,3 @@ function collectRemovalDates(bunfig: string): Map<string, string> {
 
   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/first-party-scopes.ts

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

package/src/dependency-gates/parse-age-gate.ts

@@ -0,0 +1,26 @@
+import { isRecord } from './is-record.ts';
+
+export interface AgeGate {
+  readonly isOn: boolean;
+  readonly excludes: readonly string[];
+}
+
+export function parseAgeGate(bunfig: string): AgeGate {
+  const parsed: unknown = Bun.TOML.parse(bunfig);
+  const install = isRecord(parsed) ? parsed['install'] : undefined;
+  const minimumReleaseAge = isRecord(install) ? install['minimumReleaseAge'] : undefined;
+  const excludes = isRecord(install) ? install['minimumReleaseAgeExcludes'] : undefined;
+
+  if (excludes !== undefined && !isStringList(excludes)) {
+    throw new TypeError('bunfig.toml sets a minimumReleaseAgeExcludes that is not a list of names');
+  }
+
+  return {
+    isOn: minimumReleaseAge !== undefined && minimumReleaseAge !== 0 && minimumReleaseAge !== '0',
+    excludes: excludes ?? [],
+  };
+}
+
+function isStringList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item: unknown) => typeof item === 'string');
+}

package/src/dependency-gates/parse-lockfile-registry-names.ts

@@ -0,0 +1,27 @@
+import { isRecord } from './is-record.ts';
+
+// An entry's id is `<name>@<version>`. A workspace, link, file or git entry carries a protocol in
+// its version, such as `workspace:packages/std`, and bun never puts it through the age gate.
+export function parseLockfileRegistryNames(lockfile: string): string[] {
+  const parsed: unknown = Bun.JSONC.parse(lockfile);
+  const packages = isRecord(parsed) ? parsed['packages'] : undefined;
+
+  if (!isRecord(packages)) {
+    throw new TypeError('bun.lock has no packages object');
+  }
+
+  const names = Object.values(packages).flatMap((entry) => {
+    const id: unknown = Array.isArray(entry) ? entry[0] : undefined;
+
+    if (typeof id !== 'string') {
+      throw new TypeError('bun.lock has a package entry that does not start with its id');
+    }
+
+    const versionStart = id.indexOf('@', 1);
+    const version = id.slice(versionStart + 1);
+
+    return versionStart > 0 && !version.includes(':') ? [id.slice(0, versionStart)] : [];
+  });
+
+  return [...new Set(names)].toSorted();
+}

package/src/dependency-gates/read-dependency-gate-findings.ts

@@ -1,11 +1,14 @@
 import type { RunProgram } from '../run-program.ts';
+import { collectMissingFirstPartyExcludes } from './collect-missing-first-party-excludes.ts';
 import { collectStaleAgeGateExcludes } from './collect-stale-age-gate-excludes.ts';
 import { collectUnneededAuditIgnores } from './collect-unneeded-audit-ignores.ts';
 import { collectUnneededOverrides } from './collect-unneeded-overrides.ts';
+import { parseAgeGate } from './parse-age-gate.ts';
 import { parseAuditAdvisories } from './parse-audit-advisories.ts';
 import { parseAuditIgnoreIDs } from './parse-audit-ignore-ids.ts';
 import { parseFixablePackages } from './parse-fixable-packages.ts';
 import { parseLockfileDependents } from './parse-lockfile-dependents.ts';
+import { parseLockfileRegistryNames } from './parse-lockfile-registry-names.ts';
 import type { RootManifest } from './parse-root-manifest.ts';
 import { parseRootManifest } from './parse-root-manifest.ts';
 import type { DependencyGateFinding } from './types.ts';
@@ -36,24 +39,30 @@ export function readDependencyGateFindings(
 
   const manifest = parseRootManifest(manifestText);
   const ignoreIDs = parseAuditIgnoreIDs(manifest.auditScript);
+  const bunfig = sources.readRepoFile('bunfig.toml') ?? '';
+  const lockfile = sources.readRepoFile('bun.lock');
 
   return [
-    ...collectStaleAgeGateExcludes(sources.readRepoFile('bunfig.toml') ?? '', sources.today),
-    ...readOverrideFindings(sources, manifest),
+    ...collectStaleAgeGateExcludes(bunfig, sources.today),
+    ...(lockfile === null
+      ? []
+      : collectMissingFirstPartyExcludes(
+          parseAgeGate(bunfig),
+          parseLockfileRegistryNames(lockfile),
+        )),
+    ...collectOverrideFindings(manifest, lockfile),
     ...(ignoreIDs.length === 0 ? [] : readIgnoreFindings(sources, ignoreIDs)),
   ];
 }
 
-function readOverrideFindings(
-  sources: Readonly<DependencyGateSources>,
+function collectOverrideFindings(
   manifest: RootManifest,
+  lockfile: string | null,
 ): DependencyGateFinding[] {
   if (Object.keys(manifest.overrides).length === 0) {
     return [];
   }
 
-  const lockfile = sources.readRepoFile('bun.lock');
-
   if (lockfile === null) {
     throw new Error('package.json sets overrides, and the repo has no bun.lock');
   }

package/src/parse-lefthook-config.ts

@@ -0,0 +1,17 @@
+import { isRecord } from '@zgeoff/std';
+
+export function parseLefthookConfig(text: string): Record<string, unknown> | undefined {
+  let parsed: unknown;
+
+  try {
+    parsed = Bun.YAML.parse(text);
+  } catch {
+    return undefined;
+  }
+
+  if (parsed === null) {
+    return {};
+  }
+
+  return isRecord(parsed) ? parsed : undefined;
+}