@zgeoff/chex 0.0.3 → 0.0.4

package/README.md

@@ -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.4",
   "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/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;
+}