@zgeoff/chex 0.0.12 → 0.0.14

package/README.md

@@ -83,7 +83,7 @@ skipped file back:
 `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.
+has none, and changes nothing on a second run. `chex ci-plan` plans a run of `bun-checks`.
 
 ## The pre-push baseline
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/chex",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Run each shared docs and repo check as one subcommand, with the lefthook pre-push baseline that calls them",
   "keywords": [
     "checks",

package/src/ci-plan/parse-docs-checks.ts

@@ -0,0 +1,37 @@
+import { match } from 'ts-pattern';
+import { docsCheckNames } from '../check-names.ts';
+import type { ChexRequest } from '../parse-chex-args.ts';
+import { parseChexArgs } from '../parse-chex-args.ts';
+
+export type DocsChecks =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'named'; readonly checks: readonly string[] }
+  | { readonly kind: 'refused'; readonly message: string };
+
+// CI runs each docs check that the repo's check:docs script names as its own step, so the script
+// holds chex and the names alone, as chex init writes it.
+export function parseDocsChecks(script: string | undefined): DocsChecks {
+  if (script === undefined) {
+    return { kind: 'none' };
+  }
+
+  const [program, ...words] = script.trim().split(/\s+/u);
+
+  const refusal: DocsChecks = {
+    kind: 'refused',
+    message: `package.json runs "${script}" as check:docs; write it as chex and the docs checks it takes, from ${docsCheckNames.join(', ')}, such as "chex prose length links", so CI runs each check as its own step.`,
+  };
+
+  return match<ChexRequest, DocsChecks>(parseChexArgs(words))
+    .with({ kind: 'checks' }, (request) =>
+      program === 'chex' &&
+      request.args.length === 0 &&
+      request.names.every((name) => docsCheckNames.some((docsName) => docsName === name))
+        ? { kind: 'named', checks: request.names }
+        : refusal,
+    )
+    .with({ kind: 'init' }, () => refusal)
+    .with({ kind: 'ci-plan' }, () => refusal)
+    .with({ kind: 'refused' }, () => refusal)
+    .exhaustive();
+}

package/src/ci-plan/plan-check-scripts.ts

@@ -0,0 +1,76 @@
+export type CheckPart = 'all' | 'static' | 'test' | 'lane';
+
+export interface CheckPlanRequest {
+  readonly scripts: string;
+
+  readonly defined: readonly string[];
+
+  readonly part: CheckPart;
+
+  readonly lane: string;
+}
+
+export type CheckPlan =
+  | {
+      readonly kind: 'planned';
+      readonly scripts: readonly string[];
+      readonly static: readonly string[];
+      readonly test: readonly string[];
+      readonly lanes: readonly string[];
+    }
+  | { readonly kind: 'missing'; readonly missing: readonly string[] };
+
+export function planCheckScripts(request: CheckPlanRequest): CheckPlan {
+  const defined = new Set(request.defined);
+
+  const listed = request.scripts.split(/\s+/u).filter((name) => name !== '');
+  const list = listed.length === 0 ? buildStandardList(defined) : listed;
+  const missing = list.filter((name) => !defined.has(name));
+
+  if (missing.length > 0) {
+    return { kind: 'missing', missing };
+  }
+
+  const lanes = list.filter((name) => isLaneScript(name)).map((name) => name.slice('test:'.length));
+  const tests = list.filter((name) => isTestScript(name) && !isLaneScript(name));
+  const staticChecks = list.filter((name) => !isTestScript(name));
+
+  const parts: Record<CheckPart, readonly string[]> = {
+    all: [...staticChecks, ...tests, ...lanes.map((lane) => `test:${lane}`)],
+    static: staticChecks,
+    test: tests,
+    lane: [`test:${request.lane}`],
+  };
+
+  return {
+    kind: 'planned',
+    scripts: parts[request.part],
+    static: staticChecks,
+    test: tests,
+    lanes,
+  };
+}
+
+const laneNames = ['e2e', 'browser', 'docker', 'host', 'agent-sdk', 'crash'];
+
+function buildStandardList(defined: ReadonlySet<string>): string[] {
+  const optional = (name: string) => (defined.has(name) ? [name] : []);
+
+  return [
+    'audit',
+    'deadcode',
+    'format:check',
+    'lint',
+    'typecheck',
+    'test',
+    ...laneNames.flatMap((lane) => optional(`test:${lane}`)),
+  ];
+}
+
+function isLaneScript(name: string): boolean {
+  return laneNames.some((lane) => name === `test:${lane}`);
+}
+
+function isTestScript(name: string): boolean {
+  return name === 'test' || name.startsWith('test:');
+}

package/src/ci-plan/write-check-plan.ts

@@ -0,0 +1,123 @@
+import { appendFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { match } from 'ts-pattern';
+import type { StepOutputFile } from '../write-step-outputs.ts';
+import { writeStepOutputs } from '../write-step-outputs.ts';
+import { parseDocsChecks } from './parse-docs-checks.ts';
+import type { CheckPart, CheckPlan } from './plan-check-scripts.ts';
+import { planCheckScripts } from './plan-check-scripts.ts';
+
+export interface CheckPlanStep {
+  readonly cwd: string;
+
+  readonly outputPath: string;
+
+  readonly part: string;
+
+  readonly scripts: string;
+
+  readonly lane: string;
+
+  readonly readText: (path: string) => Promise<string>;
+
+  readonly outputFile: StepOutputFile;
+}
+
+const parts: readonly CheckPart[] = ['all', 'static', 'test', 'lane'];
+
+// Returns the errors that fail the step; with none, the plan is in the step outputs.
+export async function writeCheckPlan(step: Readonly<CheckPlanStep>): Promise<string[]> {
+  const part = parts.find((candidate) => candidate === step.part);
+
+  if (part === undefined || step.outputPath === '') {
+    return [`the plan step needs PART (one of ${parts.join(', ')}) and GITHUB_OUTPUT.`];
+  }
+
+  const packageText = await step.readText(join(step.cwd, 'package.json'));
+
+  const packageJSON: unknown = JSON.parse(packageText);
+  const scripts = findScripts(packageJSON);
+  const docsScript = scripts['check:docs'];
+  const docsText = typeof docsScript === 'string' ? docsScript : undefined;
+
+  const plan = planCheckScripts({
+    scripts: step.scripts,
+    defined: Object.keys(scripts),
+    part,
+    lane: step.lane,
+  });
+
+  // A repo with no check:docs gets an empty docs output, which runs the docs step that reads the
+  // docs scripts repo-sync delivers.
+  return match(parseDocsChecks(docsText))
+    .with({ kind: 'refused' }, (docs) => Promise.resolve([docs.message]))
+    .with({ kind: 'none' }, () => writePlanOutcome(plan, '', step))
+    .with({ kind: 'named' }, (docs) => writePlanOutcome(plan, ` ${docs.checks.join(' ')} `, step))
+    .exhaustive();
+}
+
+function findScripts(value: unknown): Readonly<Record<string, unknown>> {
+  if (typeof value !== 'object' || value === null || !('scripts' in value)) {
+    return {};
+  }
+
+  const scripts = value.scripts;
+
+  return typeof scripts === 'object' && scripts !== null ? { ...scripts } : {};
+}
+
+type CheckPlanOf<Kind extends CheckPlan['kind']> = Extract<CheckPlan, { readonly kind: Kind }>;
+
+type PlanOutcomeWriter<Kind extends CheckPlan['kind']> = (
+  plan: CheckPlanOf<Kind>,
+  docs: string,
+  step: Readonly<CheckPlanStep>,
+) => Promise<string[]>;
+
+// A table typed over every plan kind, so a new kind fails the type check until it has an outcome.
+const planOutcomeWriters: { readonly [Kind in CheckPlan['kind']]: PlanOutcomeWriter<Kind> } = {
+  missing: (plan) =>
+    Promise.resolve([
+      `package.json defines no script named: ${plan.missing.join(' ')}. Pass the scripts input, or set the BUN_CHECK_SCRIPTS repo variable, to change the list.`,
+    ]),
+  planned: async (plan, docs, step) => {
+    // Spaces around each list let a later step match one whole name.
+    await writeStepOutputs(step.outputFile, step.outputPath, {
+      scripts: ` ${plan.scripts.join(' ')} `,
+      static: ` ${plan.static.join(' ')} `,
+      test: ` ${plan.test.join(' ')} `,
+      lanes: JSON.stringify(plan.lanes),
+      docs,
+    });
+
+    return [];
+  },
+};
+
+function writePlanOutcome<Kind extends CheckPlan['kind']>(
+  plan: CheckPlanOf<Kind>,
+  docs: string,
+  step: Readonly<CheckPlanStep>,
+): Promise<string[]> {
+  const writeOutcome: PlanOutcomeWriter<Kind> = planOutcomeWriters[plan.kind];
+
+  return writeOutcome(plan, docs, step);
+}
+
+export async function runCIPlanCommand(): Promise<number> {
+  const errors = await writeCheckPlan({
+    cwd: process.cwd(),
+    outputPath: process.env['GITHUB_OUTPUT'] ?? '',
+    part: process.env['PART'] ?? '',
+    scripts: process.env['SCRIPTS'] ?? '',
+    lane: process.env['LANE'] ?? '',
+    readText: (path) => readFile(path, 'utf8'),
+    outputFile: { appendText: (path, text) => appendFile(path, text) },
+  });
+
+  for (const error of errors) {
+    process.stdout.write(`::error::${error}\n`);
+  }
+
+  return errors.length === 0 ? 0 : 1;
+}

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { rename, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readOptionalText } from '@zgeoff/std';
+import { runCIPlanCommand } from './ci-plan/write-check-plan.ts';
 import { runDependencyGatesCommand } from './dependency-gates/run-dependency-gates-check.ts';
 import { makeCheckRunner } from './make-check-runner.ts';
 import { runChex } from './run-chex.ts';
@@ -42,6 +43,7 @@ process.exitCode = await runChex(process.argv.slice(2), {
         process.stderr.write(text);
       },
     }),
+  runCIPlan: runCIPlanCommand,
   writeOutput: (text) => {
     process.stdout.write(text);
   },

package/src/docs/check-skill.sh

@@ -8,7 +8,7 @@
 # .gitattributes.
 # Fails on: a missing name or description, a name that differs from the folder or breaks the name
 # format, a description over 1,024 characters, a plain description that holds a colon YAML reads as a
-# key, a link with a line anchor outside code, and a SKILL.md body over 1,700 words.
+# key, frontmatter that Bun.YAML.parse refuses, a link with a line anchor outside code, and a SKILL.md body over 1,700 words.
 # Warns on: a SKILL.md body over 1,500 words, a SKILL.md over 500
 # lines, a reference that SKILL.md does not list under ## References, a reference over 100 lines
 # with two or more headings and no contents list near its top, a code-formatted span outside a table that names an existing repo file, and a bullet in
@@ -284,10 +284,12 @@ sub list_references {
 sub check_frontmatter {
   my ($dir, $skill, @lines) = @_;
   my ($name, $description, $in_description, $closed, $raw_description, $folded, $style, $colon);
+  my @block;
 
   if (@lines && $lines[0] eq "---") {
     for my $line (@lines[1 .. $#lines]) {
       if ($line eq "---") { $closed = 1; last }
+      push @block, $line;
       if ($line =~ /^name:\s*(.*?)\s*$/) {
         $name = unquote($1);
         $in_description = 0;
@@ -334,6 +336,32 @@ sub check_frontmatter {
 
   fail($skill, "description holds a colon and a space, which YAML reads as a key in a plain scalar; reword it, or quote it or write it as a block scalar (>-)")
     if $colon;
+
+  # The colon error already names the cause of the parse error that the colon brings.
+  my $yaml_error = $colon ? undef : read_yaml_error(join("\n", @block) . "\n");
+  fail($skill, "frontmatter is not valid YAML ($yaml_error), so a strict loader refuses the skill; escape each quote inside a quoted value, or write the value as a block scalar (>-)")
+    if defined $yaml_error;
+}
+
+# Returns the error that Bun.YAML.parse throws on the text, or undef when the text parses. The line
+# reads above take a stray quote inside a quoted value as text, where a strict loader refuses it.
+sub read_yaml_error {
+  my ($text) = @_;
+  my $parse = q{try { Bun.YAML.parse(process.argv.at(-1)) } catch (error) { console.log(error.message); process.exit(1) }};
+  my $parser;
+  # The check prints its own message when bun is missing, in place of the warning perl adds.
+  no warnings "exec";
+  unless (open $parser, "-|", "bun", "-e", $parse, to_bytes($text)) {
+    print STDERR "check-skill: cannot run bun to parse the frontmatter: $!\n";
+    exit 2;
+  }
+  my $output = do { local $/; <$parser> } // "";
+  close $parser;
+  return undef if $? == 0;
+  utf8::decode($output);
+  $output =~ s/\s+\z//;
+  $output =~ s/\s*\n\s*/ /g;
+  return $output eq "" ? "bun exited with status " . ($? >> 8) : $output;
 }
 
 # Returns block, quoted or plain for the text after a key, or undef when the text is empty or only a

package/src/parse-chex-args.ts

@@ -4,6 +4,7 @@ import { checkNames, isCheckName } from './check-names.ts';
 
 export type ChexRequest =
   | { readonly kind: 'init' }
+  | { readonly kind: 'ci-plan' }
   | {
       readonly kind: 'checks';
       readonly names: readonly CheckName[];
@@ -20,7 +21,7 @@ const checksWithArgs: ReadonlySet<CheckName> = new Set([
   'workflows',
 ]);
 
-export const chexUsage = `usage: chex <check>... | chex <check> [args...] | chex init
+export const chexUsage = `usage: chex <check>... | chex <check> [args...] | chex init | chex ci-plan
 checks: ${checkNames.join(', ')}`;
 
 export function parseChexArgs(argv: readonly string[]): ChexRequest {
@@ -36,6 +37,12 @@ export function parseChexArgs(argv: readonly string[]): ChexRequest {
       : { kind: 'refused', message: 'init takes no arguments' };
   }
 
+  if (first === 'ci-plan') {
+    return rest.length === 0
+      ? { kind: 'ci-plan' }
+      : { kind: 'refused', message: 'ci-plan takes no arguments' };
+  }
+
   // Each check parses its own options, so the tokens only mark where the check names end.
   const tokens = parseArgs({
     args: [...argv],

package/src/run-chex.ts

@@ -5,6 +5,7 @@ import { chexUsage, parseChexArgs } from './parse-chex-args.ts';
 export interface ChexDeps {
   readonly runCheck: (name: CheckName, args: readonly string[]) => Promise<number>;
   readonly runInit: () => Promise<number>;
+  readonly runCIPlan: () => Promise<number>;
   readonly writeOutput: (text: string) => void;
   readonly writeError: (text: string) => void;
 }
@@ -19,6 +20,7 @@ export function runChex(argv: readonly string[], deps: ChexDeps): Promise<number
       return Promise.resolve(2);
     })
     .with({ kind: 'init' }, () => deps.runInit())
+    .with({ kind: 'ci-plan' }, () => deps.runCIPlan())
     .with({ kind: 'checks' }, (request) => runChecks(request.names, request.args, deps))
     .exhaustive();
 }

package/src/write-step-outputs.ts

@@ -0,0 +1,21 @@
+export interface StepOutputFile {
+  readonly appendText: (path: string, text: string) => Promise<void>;
+}
+
+// GitHub Actions reads each `name=value` line of the file that GITHUB_OUTPUT names as one step
+// output, so a value that holds a newline would end its output early.
+export async function writeStepOutputs(
+  outputFile: StepOutputFile,
+  outputPath: string,
+  outputs: Readonly<Record<string, string>>,
+): Promise<void> {
+  const lines = Object.entries(outputs).map(([name, value]) => {
+    if (value.includes('\n')) {
+      throw new Error(`the step output ${name} holds a newline`);
+    }
+
+    return `${name}=${value}\n`;
+  });
+
+  await outputFile.appendText(outputPath, lines.join(''));
+}