@zgeoff/chex 0.0.2 → 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` 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.2",
+  "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-package.ts

@@ -2,7 +2,7 @@ import { isRecord } from '@zgeoff/std';
 
 // The baseline's jobs run chex, the related tests through rig, and each job under diet's memory cap.
 export const baselinePackages = ['@zgeoff/chex', '@zgeoff/rig', '@zgeoff/diet'] as const;
-export const docsScript = 'chex prose length links';
+export const docsScript = 'chex prose length links skill';
 
 export type PackageOutcome =
   | { readonly kind: 'missing'; readonly packages: readonly string[] }

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;
+}

package/src/read-checks-profile.ts

@@ -0,0 +1,57 @@
+import type { RunProgram } from './run-program.ts';
+
+export type ChecksProfile = 'public' | 'private';
+
+export interface ChecksProfileOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly runProgram: RunProgram;
+  readonly writeError: (text: string) => void;
+}
+
+// bun-checks picks the profile from the repo's visibility, so a run that CHECKS_PROFILE gives no
+// profile, such as a pre-push hook, asks GitHub for the same visibility.
+export function readChecksProfile(
+  options: Readonly<ChecksProfileOptions>,
+): ChecksProfile | undefined {
+  const given = parseChecksProfile(options.env['CHECKS_PROFILE']);
+
+  if (given !== undefined) {
+    return given;
+  }
+
+  const visibility = readRepoVisibility(options);
+
+  if (visibility instanceof Error) {
+    options.writeError(
+      `workflows: the repo's visibility is unknown, so every rule applies: ${visibility.message}\n`,
+    );
+
+    return undefined;
+  }
+
+  return visibility;
+}
+
+function parseChecksProfile(value: string | undefined): ChecksProfile | undefined {
+  return value === 'public' || value === 'private' ? value : undefined;
+}
+
+const visibilityCommand = ['gh', 'repo', 'view', '--json', 'isPrivate', '--jq', '.isPrivate'];
+
+function readRepoVisibility(options: Readonly<ChecksProfileOptions>): ChecksProfile | Error {
+  try {
+    const result = options.runProgram(visibilityCommand, { cwd: options.cwd, env: options.env });
+    const answer = result.stdout.trim();
+
+    if (result.exitCode === 0 && (answer === 'true' || answer === 'false')) {
+      return answer === 'true' ? 'private' : 'public';
+    }
+
+    return new Error(
+      `${visibilityCommand.join(' ')} exited ${result.exitCode}: ${result.stderr.trim() || answer}`,
+    );
+  } catch (error) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+}

package/src/run-workflows-check.ts

@@ -3,11 +3,11 @@ import { collectCommandNames } from './collect-command-names.ts';
 import { collectExpressionReferences } from './collect-expression-references.ts';
 import { findInstallCachePath } from './find-install-cache-path.ts';
 import { parseShellWords } from './parse-shell-words.ts';
+import type { ChecksProfile } from './read-checks-profile.ts';
+import { readChecksProfile } from './read-checks-profile.ts';
 import type { RunProgram } from './run-program.ts';
 import { runProgram } from './run-program.ts';
 
-export type ChecksProfile = 'public' | 'private';
-
 export interface WorkflowsCheckOptions {
   readonly cwd: string;
   readonly env: Readonly<Record<string, string | undefined>>;
@@ -15,7 +15,7 @@ export interface WorkflowsCheckOptions {
   // The workflow files to read, relative to the repo root; empty reads every one HEAD holds.
   readonly paths: readonly string[];
 
-  // The bun-checks profile of the run; undefined when the check cannot see it, such as in a hook.
+  // The bun-checks profile of the run; undefined when it is unknown, which applies every rule.
   readonly profile: ChecksProfile | undefined;
 
   readonly runProgram: RunProgram;
@@ -552,7 +552,14 @@ export function runWorkflowsCommand(args: readonly string[]): number {
       cwd: process.cwd(),
       env: process.env,
       paths,
-      profile: parseChecksProfile(process.env['CHECKS_PROFILE']),
+      profile: readChecksProfile({
+        cwd: process.cwd(),
+        env: process.env,
+        runProgram,
+        writeError: (text) => {
+          process.stderr.write(text);
+        },
+      }),
       runProgram,
     });
 
@@ -585,10 +592,6 @@ function parseCLIPaths(args: readonly string[]): string[] | Error {
   }
 }
 
-function parseChecksProfile(value: string | undefined): ChecksProfile | undefined {
-  return value === 'public' || value === 'private' ? value : undefined;
-}
-
 // GitHub reads a workflow command's properties up to `,` and `::`, and its message up to a
 // newline, so each escapes its own characters.
 function formatAnnotation(finding: WorkflowFinding): string {