explico 0.14.0 → 0.15.0

package/src/compiler/cli-verbs.ts

@@ -0,0 +1,270 @@
+/**
+ * Every `content` verb, as data: its arguments, what it is for, what it
+ * prints, what it writes, when it exits non-zero, and the exported type its
+ * `--json` prints. The one source for the usage text (`CONTENT_USAGE`),
+ * `content help <verb>`, `docs/authoring/cli.md` and
+ * `docs/authoring/cli-reference.json` — the last two generated by
+ * `scripts/agent/gen-cli.mjs`, which also turns each `json` type name into a
+ * JSON Schema from the TypeScript declaration (`--check` in verify and CI).
+ *
+ * A new verb is a row here, a `case` in `cli-main.ts`, and a regenerated
+ * reference; the `--json` contract test in the playground runs every
+ * read-only row against the course and validates its output.
+ */
+
+/** One flag a verb takes. */
+export interface ContentVerbFlag {
+  /** As typed: `--lesson <id>`, `--write`. */
+  readonly flag: string;
+  readonly description: string;
+}
+
+/** One verb's row. */
+export interface ContentVerb {
+  /** The command word(s): `symbol`, `new lesson`. */
+  readonly verb: string;
+  /** What follows the verb on the usage line, `--json` left out (every verb takes it). */
+  readonly args: string;
+  /** What you want to know or do when you reach for it. */
+  readonly when: string;
+  /** What it prints as text. */
+  readonly prints: string;
+  /** The flags, each once; a positional argument is described in `prints` or `when`. */
+  readonly flags: readonly ContentVerbFlag[];
+  /** What it changes on disk. */
+  readonly writes: string;
+  /** When it exits 1, beyond a usage error. */
+  readonly exit?: string;
+  /** The type its `--json` prints, by its exported name in `explico/compiler/cli`, `cli-main` or `cli-verify`. */
+  readonly json: string;
+}
+
+const WRITE: ContentVerbFlag = { flag: '--write', description: 'apply the edits; without it the diff is printed and nothing changes' };
+const READ_ONLY = 'nothing';
+
+export const CONTENT_VERBS: readonly ContentVerb[] = [
+  {
+    verb: 'status',
+    args: '',
+    when: 'how the course stands',
+    prints:
+      "counts, diagnostic totals, the knowledge and page versions, the agent surfaces' sizes, whether the course's AGENTS.md points at the engine's guide and the procedures are installed",
+    flags: [],
+    writes: READ_ONLY,
+    json: 'StatusReport',
+  },
+  {
+    verb: 'diagnostics',
+    args: '[info|warning|error] [--all | --code <c> | --lesson <id> | --changed]',
+    when: 'what is wrong, where',
+    prints:
+      'counts by code (with each code\'s rule) and by file, at the given severity or higher (info by default); a filter or --all lists the lines instead. --json always prints the lines',
+    flags: [
+      { flag: '--all', description: 'list every diagnostic instead of the counts' },
+      { flag: '--code <c>', description: 'only that diagnostic code' },
+      { flag: '--lesson <id>', description: "only that lesson's file" },
+      { flag: '--changed', description: 'only lessons whose .mdx or .checks.yml differs from git HEAD, tracked or not' },
+    ],
+    writes: READ_ONLY,
+    json: 'DiagnosticsReport',
+  },
+  {
+    verb: 'warnings',
+    args: '',
+    when: 'the warnings alone',
+    prints: 'every warning, one line each with its rule, then the count',
+    flags: [],
+    writes: READ_ONLY,
+    json: 'WarningsReport',
+  },
+  {
+    verb: 'context',
+    args: '<lesson>',
+    when: 'what a lesson draws on',
+    prints:
+      'its outcomes, notation, sources, diagnostics and token counts; --json adds the body, the floats it can reference, its sections and domain signatures',
+    flags: [],
+    writes: READ_ONLY,
+    json: 'ContextReport',
+  },
+  {
+    verb: 'equation',
+    args: '"<latex>" [--lesson <id>]',
+    when: 'will this expression build',
+    prints: "each glyph's card, unresolved glyphs with where they are defined",
+    flags: [{ flag: '--lesson <id>', description: "resolve against that lesson's local notation as well as the shared cards" }],
+    writes: READ_ONLY,
+    exit: 'when the build would refuse the expression',
+    json: 'EquationReport',
+  },
+  {
+    verb: 'bindings',
+    args: '<lesson>',
+    when: "what a lesson's math binds",
+    prints: 'every math span: its bindings, unresolved glyphs, redundant \\explain wraps',
+    flags: [],
+    writes: READ_ONLY,
+    json: 'BindingsReport',
+  },
+  {
+    verb: 'symbol',
+    args: '<latex | key>',
+    when: 'is this symbol defined already',
+    prints: 'the shared card, each local entry with its lesson, each gloss with its card, near misses',
+    flags: [],
+    writes: READ_ONLY,
+    json: 'SymbolReport',
+  },
+  {
+    verb: 'check',
+    args: '<lesson | deck>… [--changed]',
+    when: 'does it render',
+    prints: 'ok or FAIL per lesson: schema, references, MDX → KaTeX; each error and warning with its rule, the info counted by code',
+    flags: [{ flag: '--changed', description: 'the lessons whose .mdx or .checks.yml differs from git HEAD, tracked or not' }],
+    writes: READ_ONLY,
+    exit: 'when a lesson has an error',
+    json: 'CheckReport',
+  },
+  {
+    verb: 'rule',
+    args: '<ID>',
+    when: 'one rule, whole',
+    prints: "the entry as this course has it (enforcement, codes, settings in effect) and the rule page's section, example included",
+    flags: [],
+    writes: READ_ONLY,
+    exit: 'for an ID the catalog and the course rules do not know',
+    json: 'RuleReport',
+  },
+  {
+    verb: 'migrate',
+    args: '[--from <version>] [--to <version>]',
+    when: 'what an upgrade needs',
+    prints: "the migration guide's sections between the version package.json pins at git HEAD and the one installed, oldest first",
+    flags: [
+      { flag: '--from <version>', description: 'start here instead of the version pinned at HEAD' },
+      { flag: '--to <version>', description: 'stop here instead of the installed version' },
+    ],
+    writes: READ_ONLY,
+    exit: 'when a section between the two versions is missing',
+    json: 'MigrateReport',
+  },
+  {
+    verb: 'rules',
+    args: '[--element <e>[,<e>]] [--enforcement script|partial|guide|locked] [--edition chapter|deck]',
+    when: 'which rules apply',
+    prints: 'the rules this course has on, by element, with enforcement, codes, settings in effect and a one-line summary',
+    flags: [
+      { flag: '--element <e>[,<e>]', description: 'only rules about these elements (prose, table, notation, …)' },
+      { flag: '--enforcement <kind>', description: 'only script, partial, guide or locked rules' },
+      { flag: '--edition <edition>', description: "chapter (the default) or deck: the rules for that edition's pages" },
+    ],
+    writes: READ_ONLY,
+    json: 'RulesJson',
+  },
+  {
+    verb: 'move',
+    args: '<lesson>:<key> [--to <key>] [--write]',
+    when: 'a local entry becomes shared',
+    prints: 'the new card and every copy and reference that changes, as a diff',
+    flags: [{ flag: '--to <key>', description: 'the shared card\'s key, when it differs from the local one' }, WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'rename',
+    args: '<old> <new> [--write]',
+    when: 'rename a shared card',
+    prints: 'the card file and every reference, as a diff',
+    flags: [WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'fix',
+    args: '<lesson>… | --all [--write]',
+    when: 'the mechanical repairs',
+    prints: 'redundant \\explain wraps unwrapped, as a diff',
+    flags: [{ flag: '--all', description: 'every lesson; the ones with nothing to fix are counted' }, WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'new lesson',
+    args: '<id>',
+    when: 'a chapter to start from',
+    prints: 'the files it created: the .mdx and its .checks.yml',
+    flags: [],
+    writes: 'new files; never overwrites',
+    json: 'NewJson',
+  },
+  {
+    verb: 'new deck',
+    args: '<lesson | part>',
+    when: 'slides to start from',
+    prints: "the deck it drafted from the chapter (or the part's chapters)",
+    flags: [],
+    writes: 'new files; never overwrites',
+    json: 'NewJson',
+  },
+  {
+    verb: 'new term',
+    args: '<key>',
+    when: 'a shared notation card to start from',
+    prints: 'the card file it created',
+    flags: [],
+    writes: 'new files; never overwrites',
+    json: 'NewJson',
+  },
+  {
+    verb: 'init-agent',
+    args: '[--write]',
+    when: 'install the agent procedures',
+    prints:
+      "the skills and the rules-reviewer agent it would copy into .claude/, and a baseline AGENTS.md when the course has none; rerun after an upgrade",
+    flags: [WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'release',
+    args: '[major|minor|patch] [--write]',
+    when: 'cut a content release (rule C3)',
+    prints:
+      "## [Unreleased] in content/CHANGELOG.md becoming a dated ## [x.y.z] heading and about.version becoming x.y.z, as a diff; the bump defaults to what the section's headings imply (Breaking or Removed → major, Added → minor, else patch)",
+    flags: [WRITE],
+    writes: 'only with --write',
+    json: 'EditPlanJson',
+  },
+  {
+    verb: 'verify',
+    args: '[--e2e] [--force]',
+    when: 'is it ready to hand back',
+    prints:
+      "one line per step — validate:content, check --changed, astro check, the course's tests, astro build, and with --e2e the browser tests — and the tail of each failed step's log; a rerun on an unchanged tree answers from the last pass",
+    flags: [
+      { flag: '--e2e', description: "also run the browser tests (the course's test:e2e script, or playwright test when it has a config)" },
+      { flag: '--force', description: 'run even when nothing changed since the last pass' },
+    ],
+    writes: 'what validate:content and astro build write; logs and the pass record under node_modules/.cache/explico/verify/',
+    exit: 'when a step fails',
+    json: 'VerifyReport',
+  },
+  {
+    verb: 'help',
+    args: '[<verb>]',
+    when: "a verb's flags and its --json shape",
+    prints: "the usage; with a verb, its flags, what it writes, its exit code and the shape of its --json",
+    flags: [],
+    writes: READ_ONLY,
+    exit: 'for an unknown verb',
+    json: 'HelpJson',
+  },
+];
+
+/** One usage line: `pnpm content symbol <latex | key> [--json]`. */
+export function usageLine(verb: ContentVerb): string {
+  return `pnpm content ${verb.verb}${verb.args === '' ? '' : ` ${verb.args}`} [--json]`;
+}
+
+/** The usage text `content help` prints; `scripts/agent/gen-map.mjs` lists the verbs from the generated reference. */
+export const CONTENT_USAGE = `Usage:\n${CONTENT_VERBS.map((verb) => `  ${usageLine(verb)}`).join('\n')}`;

package/src/compiler/cli-verify.ts

@@ -0,0 +1,241 @@
+/**
+ * `content verify` — the one gate before a course's work is handed back:
+ * `validate:content` → `content check --changed` → `astro check` → the
+ * course's tests → `astro build`, and with `--e2e` its browser tests. Each
+ * step runs as its own process (the course's own scripts, so whatever they
+ * do is what runs), its whole output goes to a log under
+ * `node_modules/.cache/explico/verify/`, and the run prints one line per step
+ * and the tail of each failed step's log.
+ *
+ * A pass records the tree it left (git HEAD, every change against it, every
+ * untracked file's content; ignored files are no input) and whether it ran
+ * the browser tests. A rerun on the same tree that asks for no more answers
+ * from the record without running anything, so "run it again to be sure"
+ * costs nothing. This repository's `scripts/agent/verify` is the same gate
+ * for the engine and the playground.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export type VerifyStepName = 'validate:content' | 'check --changed' | 'astro check' | 'tests' | 'astro build' | 'e2e';
+
+export interface VerifyStep {
+  readonly name: VerifyStepName;
+  readonly status: 'pass' | 'fail' | 'skipped';
+  /** The command it ran, as it would be typed; absent for a skipped step. */
+  readonly command?: string;
+  /** Why it was skipped, or why it could not start. */
+  readonly reason?: string;
+  readonly seconds?: number;
+  /** Course-relative path of its whole output. */
+  readonly log?: string;
+  /** The last lines of the output of a failed step. */
+  readonly tail?: readonly string[];
+}
+
+export interface VerifyReport {
+  readonly ok: boolean;
+  /** True when the tree is unchanged since a pass that covered as much: nothing ran, `steps` are that pass's. */
+  readonly cached: boolean;
+  /** When the recorded pass ran, for a cached answer (ISO 8601). */
+  readonly since?: string;
+  /** The hash of the tree the run left, or `null` outside a git repository (then nothing is recorded). */
+  readonly tree: string | null;
+  /** Whether the browser tests were part of the run. */
+  readonly e2e: boolean;
+  readonly steps: readonly VerifyStep[];
+}
+
+export interface VerifyOptions {
+  readonly e2e?: boolean;
+  readonly force?: boolean;
+  /** The course root; the working directory by default. */
+  readonly cwd?: string;
+  /** Called as each step starts and ends, for a progress line. */
+  readonly onStep?: (event: { readonly phase: 'start'; readonly name: VerifyStepName } | { readonly phase: 'end'; readonly step: VerifyStep }) => void;
+}
+
+export const VERIFY_DIR = join('node_modules', '.cache', 'explico', 'verify');
+const RECORD = 'last-pass.json';
+const TAIL_LINES = 20;
+
+interface PassRecord {
+  readonly tree: string;
+  readonly e2e: boolean;
+  readonly when: string;
+  readonly steps: readonly VerifyStep[];
+}
+
+/** The working tree as the gate sees it, in one hash; `null` outside git. */
+export function verifyTreeHash(cwd: string): string | null {
+  try {
+    const git = (args: string[]) =>
+      execFileSync('git', args, { cwd, maxBuffer: 1 << 30, stdio: ['ignore', 'pipe', 'ignore'] });
+    const hash = createHash('sha1');
+    hash.update(git(['rev-parse', 'HEAD']));
+    hash.update(git(['diff', 'HEAD', '--binary']));
+    const untracked = git(['ls-files', '--others', '--exclude-standard', '-z']).toString('utf8').split('\0').filter(Boolean).sort();
+    for (const file of untracked) {
+      hash.update(`\0${file}\0`);
+      if (existsSync(join(cwd, file))) hash.update(readFileSync(join(cwd, file)));
+    }
+    return hash.digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/** How to run a package script with the manager that started this process (`npm_execpath`), pnpm otherwise. */
+function scriptCommand(script: string, args: readonly string[]): { file: string; argv: string[]; display: string } {
+  const execpath = process.env.npm_execpath ?? '';
+  const manager = /pnpm/.test(execpath) ? 'pnpm' : /yarn/.test(execpath) ? 'yarn' : /npm/.test(execpath) ? 'npm' : 'pnpm';
+  // npm hands a script its arguments only after `--`; pnpm and yarn pass them as they are.
+  const tail = manager === 'npm' && args.length > 0 ? ['run', script, '--', ...args] : ['run', script, ...args];
+  const display = `${manager} ${tail.join(' ')}`;
+  if (execpath === '' || !execpath.includes(manager)) return { file: manager, argv: tail, display };
+  return /\.[cm]?js$/.test(execpath)
+    ? { file: process.execPath, argv: [execpath, ...tail], display }
+    : { file: execpath, argv: tail, display };
+}
+
+function binCommand(cwd: string, bin: string, args: readonly string[]): { file: string; argv: string[]; display: string } {
+  return { file: join(cwd, 'node_modules', '.bin', process.platform === 'win32' ? `${bin}.cmd` : bin), argv: [...args], display: [bin, ...args].join(' ') };
+}
+
+function slug(name: VerifyStepName): string {
+  return name.replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function tailOf(file: string): string[] {
+  const lines = readFileSync(file, 'utf8').split('\n').map((line) => line.trimEnd()).filter((line) => line !== '');
+  return lines.slice(-TAIL_LINES);
+}
+
+/** Run every step, record a pass, and say what happened; never throws for a failing step. */
+export function runVerify(options: VerifyOptions = {}): VerifyReport {
+  const cwd = options.cwd ?? process.cwd();
+  const e2e = options.e2e ?? false;
+  const dir = join(cwd, VERIFY_DIR);
+  const recordFile = join(dir, RECORD);
+
+  if (!options.force && existsSync(recordFile)) {
+    try {
+      const record = JSON.parse(readFileSync(recordFile, 'utf8')) as PassRecord;
+      const tree = verifyTreeHash(cwd);
+      if (tree !== null && record.tree === tree && (record.e2e || !e2e)) {
+        return { ok: true, cached: true, since: record.when, tree, e2e: record.e2e, steps: record.steps };
+      }
+    } catch {
+      // an unreadable record is no record
+    }
+  }
+
+  mkdirSync(dir, { recursive: true });
+  const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')) as { scripts?: Record<string, string> };
+  const scripts = pkg.scripts ?? {};
+  const has = (path: string) => existsSync(join(cwd, path));
+  const playwrightConfig = ['playwright.config.ts', 'playwright.config.mts', 'playwright.config.js', 'playwright.config.mjs'].some(has);
+
+  type Plan = { name: VerifyStepName; command?: ReturnType<typeof scriptCommand>; reason?: string; fail?: boolean };
+  const plans: Plan[] = [
+    scripts['validate:content'] === undefined
+      ? { name: 'validate:content', reason: 'package.json has no validate:content script', fail: true }
+      : { name: 'validate:content', command: scriptCommand('validate:content', []) },
+    scripts.content === undefined
+      ? { name: 'check --changed', reason: 'package.json has no content script', fail: true }
+      : { name: 'check --changed', command: scriptCommand('content', ['check', '--changed']) },
+    // Without @astrojs/check, `astro check` stops to ask whether to install it.
+    has(join('node_modules', '@astrojs', 'check', 'package.json'))
+      ? { name: 'astro check', command: binCommand(cwd, 'astro', ['check']) }
+      : { name: 'astro check', reason: '@astrojs/check is not installed (pnpm add -D @astrojs/check typescript)' },
+    scripts.test === undefined
+      ? { name: 'tests', reason: 'package.json has no test script' }
+      : { name: 'tests', command: scriptCommand('test', []) },
+    { name: 'astro build', command: binCommand(cwd, 'astro', ['build']) },
+  ];
+  if (e2e) {
+    plans.push(
+      scripts['test:e2e'] !== undefined
+        ? { name: 'e2e', command: scriptCommand('test:e2e', []) }
+        : playwrightConfig
+          ? { name: 'e2e', command: binCommand(cwd, 'playwright', ['test']) }
+          : { name: 'e2e', reason: 'no test:e2e script and no playwright.config' },
+    );
+  }
+
+  const steps: VerifyStep[] = [];
+  for (const plan of plans) {
+    options.onStep?.({ phase: 'start', name: plan.name });
+    let step: VerifyStep;
+    if (plan.command === undefined) {
+      step = { name: plan.name, status: plan.fail ? 'fail' : 'skipped', reason: plan.reason! };
+    } else {
+      const log = join(dir, `${slug(plan.name)}.log`);
+      const fd = openSync(log, 'w');
+      const started = Date.now();
+      let result;
+      try {
+        result = spawnSync(plan.command.file, plan.command.argv, {
+          cwd,
+          stdio: ['ignore', fd, fd],
+          shell: process.platform === 'win32',
+          env: process.env,
+        });
+      } finally {
+        closeSync(fd);
+      }
+      const seconds = Math.round((Date.now() - started) / 100) / 10;
+      const passed = result.error === undefined && result.status === 0;
+      step = {
+        name: plan.name,
+        status: passed ? 'pass' : 'fail',
+        command: plan.command.display,
+        seconds,
+        log: relative(cwd, log),
+        ...(result.error === undefined ? {} : { reason: result.error.message }),
+        ...(passed ? {} : { tail: tailOf(log) }),
+      };
+    }
+    steps.push(step);
+    options.onStep?.({ phase: 'end', step });
+  }
+
+  const ok = steps.every((step) => step.status !== 'fail');
+  // The tree the steps left: validate:content may rewrite tracked files (content/versions.json).
+  const tree = verifyTreeHash(cwd);
+  if (ok && tree !== null) {
+    const record: PassRecord = { tree, e2e, when: new Date().toISOString(), steps };
+    writeFileSync(recordFile, `${JSON.stringify(record, null, 2)}\n`);
+  }
+  return { ok, cached: false, tree, e2e, steps };
+}
+
+/** The digest after a run: failed steps' tails, then one verdict line. */
+export function formatVerifyReport(report: VerifyReport): string {
+  if (report.cached) {
+    return `verify: PASS, unchanged since ${report.since} (${report.e2e ? 'with' : 'without'} e2e); --force reruns\n`;
+  }
+  const out: string[] = [];
+  for (const step of report.steps) {
+    if (step.status !== 'fail') continue;
+    out.push('', `${step.name} failed${step.reason === undefined ? '' : `: ${step.reason}`}${step.log === undefined ? '' : ` — last lines of ${step.log}:`}`);
+    for (const line of step.tail ?? []) out.push(`  ${line}`);
+  }
+  const failed = report.steps.filter((step) => step.status === 'fail').map((step) => step.name);
+  out.push(
+    '',
+    failed.length === 0
+      ? `verify: PASS${report.tree === null ? ' (not a git repository: nothing recorded)' : ''}`
+      : `verify: FAIL — ${failed.join(', ')}; whole output under ${VERIFY_DIR}/`,
+  );
+  return `${out.join('\n').replace(/^\n/, '')}\n`;
+}
+
+/** One progress line per step: `  astro build        ok   41.2s`. */
+export function formatVerifyStep(step: VerifyStep): string {
+  const verdict = step.status === 'pass' ? 'ok' : step.status === 'fail' ? 'FAIL' : 'skipped';
+  const detail = step.seconds !== undefined ? `${step.seconds.toFixed(1)}s` : (step.reason ?? '');
+  return `  ${step.name.padEnd(18)} ${verdict.padEnd(7)} ${detail}\n`;
+}