explico 0.13.1 → 0.15.0

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