explico 0.13.1 → 0.15.0

package/dist/compiler/cli-main.js

@@ -0,0 +1,433 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  ContentCliError,
+  applyEditPlan,
+  changedLessonIds,
+  contentBindings,
+  contentCheck,
+  contentContext,
+  contentDiagnostics,
+  contentEquation,
+  contentMigrate,
+  contentRule,
+  contentRules,
+  contentStatus,
+  contentSymbol,
+  contentWarnings,
+  filterDiagnostics,
+  findLesson,
+  formatBindingsReport,
+  formatCliDiagnostic,
+  formatDiagnosticsSummary,
+  formatEquationReport,
+  formatMigrateReport,
+  formatRuleReport,
+  formatSymbolReport,
+  ownerTag,
+  parseRulesFilter,
+  planFixMany,
+  planInitAgent,
+  planMove,
+  planRename,
+  renderEditPlan,
+  scaffoldDeck,
+  scaffoldLesson,
+  scaffoldTerm,
+  summarizeDiagnostics
+} from "./cli.js";
+import { formatVerbHelp, loadCliReference, verbHelp } from "./cli-reference.js";
+import { CONTENT_USAGE } from "./cli-verbs.js";
+import { planContentRelease } from "./content-release.js";
+import { formatVerifyReport, formatVerifyStep, runVerify } from "./cli-verify.js";
+import { compileManifest } from "./manifest.js";
+const VALUED_FLAGS = ["element", "enforcement", "edition", "code", "lesson", "from", "to"];
+function parseContentArgs(argv) {
+  const positionals = [];
+  const values = {};
+  let json = false;
+  let changed = false;
+  let all = false;
+  let write = false;
+  let e2e = false;
+  let force = false;
+  const valued = new RegExp(`^--(${VALUED_FLAGS.join("|")})(?:=(.*))?$`);
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const match = valued.exec(arg);
+    if (arg === "--json") json = true;
+    else if (arg === "--changed") changed = true;
+    else if (arg === "--all") all = true;
+    else if (arg === "--write") write = true;
+    else if (arg === "--e2e") e2e = true;
+    else if (arg === "--force") force = true;
+    else if (match) values[match[1]] = match[2] ?? argv[i += 1] ?? "";
+    else positionals.push(arg);
+  }
+  return {
+    command: positionals[0] ?? "",
+    positionals: positionals.slice(1),
+    json,
+    changed,
+    all,
+    write,
+    e2e,
+    force,
+    ...values
+  };
+}
+function diagnosticsWhere(diagnostics, file) {
+  const own = diagnostics.filter((diagnostic) => diagnostic.file === file).length;
+  return own === diagnostics.length ? "" : ` (${own} in ${file}, ${diagnostics.length - own} in the shared cards it shows)`;
+}
+const PROCESS_IO = {
+  out: (text) => process.stdout.write(text),
+  err: (text) => process.stderr.write(text)
+};
+class Usage extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+}
+function usage(code, message) {
+  throw new Usage(code, message);
+}
+function writeScaffold(scaffold) {
+  const written = [];
+  for (const file of [{ path: scaffold.path, contents: scaffold.contents }, ...scaffold.companions]) {
+    const absolute = join(process.cwd(), file.path);
+    mkdirSync(dirname(absolute), { recursive: true });
+    writeFileSync(absolute, file.contents, { flag: "wx" });
+    written.push(file.path);
+  }
+  return written;
+}
+async function runContentCli(courseConfig, argv = process.argv.slice(2), io = PROCESS_IO, compiled) {
+  const args = parseContentArgs(argv);
+  const json = (value) => io.out(`${JSON.stringify(value, null, 2)}
+`);
+  try {
+    return await dispatch(courseConfig, args, io, json, compiled);
+  } catch (error) {
+    const code = error instanceof Usage || error instanceof ContentCliError ? error.code : "internal";
+    const message = error instanceof Error ? error.message : String(error);
+    if (args.json) json({ ok: false, error: { code, message } });
+    else io.err(`Error [${code}]: ${message}
+`);
+    return 1;
+  }
+}
+async function dispatch(courseConfig, args, io, json, compiled) {
+  const out = io.out;
+  if (args.command === "" || args.command === "--help" || args.command === "help" && args.positionals.length === 0 && !args.json) {
+    out(`${CONTENT_USAGE}
+`);
+    return 0;
+  }
+  if (args.command === "help") {
+    if (args.positionals.length > 1) usage("usage", `content help takes one verb; got ${args.positionals.join(" ")}.`);
+    const reference = loadCliReference();
+    const [word] = args.positionals;
+    if (word === void 0) {
+      json(reference);
+      return 0;
+    }
+    const help = verbHelp(reference, word);
+    if (args.json) json(help);
+    else out(formatVerbHelp(reference, help));
+    return 0;
+  }
+  if (args.command === "verify") {
+    if (args.positionals.length > 0) usage("usage", `content verify takes no argument; got ${args.positionals.join(" ")}.`);
+    if (!args.json) out(`verify (${args.e2e ? "with" : "without"} e2e; whole output under node_modules/.cache/explico/verify/)
+`);
+    const report = runVerify({
+      e2e: args.e2e,
+      force: args.force,
+      ...args.json ? {} : { onStep: (event) => event.phase === "end" && out(formatVerifyStep(event.step)) }
+    });
+    if (args.json) json(report);
+    else out(report.cached ? formatVerifyReport(report) : `
+${formatVerifyReport(report)}`);
+    return report.ok ? 0 : 1;
+  }
+  if (args.command === "new") {
+    const [kind, id] = args.positionals;
+    if (kind !== "lesson" && kind !== "deck" && kind !== "term") {
+      usage("unknown-kind", 'content new expects "lesson", "deck" or "term".');
+    }
+    if (!id) usage("usage", `content new ${kind} needs an id.`);
+    if (args.positionals.length > 2) {
+      usage("usage", `content new ${kind} takes one id; got also ${args.positionals.slice(2).join(" ")}.`);
+    }
+    const scaffold = kind === "lesson" ? scaffoldLesson(id) : kind === "deck" ? scaffoldDeck(id) : scaffoldTerm(id);
+    const written = writeScaffold(scaffold);
+    if (args.json) json({ ok: true, created: written });
+    else out(`Created:
+${written.map((p) => `  ${p}`).join("\n")}
+`);
+    return 0;
+  }
+  if (["status", "rules", "warnings"].includes(args.command) && args.positionals.length > 0) {
+    usage("usage", `content ${args.command} takes no <lesson>; got ${args.positionals.join(" ")}.`);
+  }
+  if (args.command === "init-agent" || args.command === "release") {
+    let plan;
+    if (args.command === "init-agent") {
+      if (args.positionals.length > 0) usage("usage", `content init-agent takes no argument; got ${args.positionals.join(" ")}.`);
+      plan = planInitAgent();
+    } else {
+      if (args.positionals.length > 1) usage("usage", `content release takes one of major, minor, patch; got ${args.positionals.join(" ")}.`);
+      plan = planContentRelease(args.positionals[0]);
+    }
+    if (args.json) json({ ...plan, written: args.write });
+    else out(renderEditPlan(plan));
+    if (plan.edits.length === 0) return 0;
+    const next = plan.next.length > 0 ? plan.next.join(" \xB7 ") : "";
+    if (args.write) {
+      const touched = applyEditPlan(plan);
+      if (!args.json) out(`
+written: ${touched.join(", ")}${next === "" ? "" : `
+next: ${next}`}
+`);
+    } else if (!args.json) out(`
+dry run: nothing written. Add --write to apply${next === "" ? "" : `; then ${next}`}.
+`);
+    return 0;
+  }
+  if (args.command === "migrate") {
+    if (args.positionals.length > 0) {
+      usage("usage", `content migrate takes no positional argument; got ${args.positionals.join(" ")}. Use --from and --to.`);
+    }
+    const report = contentMigrate({
+      ...args.from === void 0 ? {} : { from: args.from },
+      ...args.to === void 0 ? {} : { to: args.to }
+    });
+    if (args.json) json(report);
+    else out(formatMigrateReport(report));
+    return 0;
+  }
+  const known = [
+    "status",
+    "move",
+    "rename",
+    "fix",
+    "rule",
+    "rules",
+    "warnings",
+    "diagnostics",
+    "context",
+    "equation",
+    "bindings",
+    "symbol",
+    "check"
+  ];
+  if (!known.includes(args.command)) {
+    usage("unknown-command", `Unknown command "${args.command}".
+${CONTENT_USAGE}`);
+  }
+  const manifest = compiled ?? await compileManifest(courseConfig);
+  switch (args.command) {
+    case "status": {
+      const report = contentStatus(manifest);
+      if (args.json) {
+        json(report);
+        return 0;
+      }
+      const c = report.counts;
+      const unreleased = report.pageVersions.unreleased;
+      const UNRELEASED_SHOWN = 6;
+      const unreleasedList = unreleased.length <= UNRELEASED_SHOWN ? unreleased.join(", ") : `${unreleased.slice(0, UNRELEASED_SHOWN).join(", ")}, \u2026 ${unreleased.length - UNRELEASED_SHOWN} more in --json`;
+      out(
+        `Knowledge version ${report.knowledgeVersion}
+Page versions: ${report.pageVersions.tracked} page(s) tracked, ${unreleased.length} with changes not yet released${unreleased.length > 0 ? ` (${unreleasedList})` : ""}
+Lessons ${c.lessons} \xB7 competencies ${c.competencies} \xB7 assessments ${c.assessments} \xB7 sources ${c.sources} \xB7 tracks ${c.tracks} \xB7 notation ${c.notationDefinitions} \xB7 keyed equations ${c.keyedEquations} \xB7 tables ${c.keyedTables} \xB7 figures ${c.keyedFigures} \xB7 diagrams ${c.keyedDiagrams} \xB7 example sets ${c.keyedExamples}
+Diagnostics: ${report.diagnostics.errors} error(s), ${report.diagnostics.warnings} warning(s), ${report.diagnostics.infos} info
+Orphans: ${report.orphans.length}
+Agent surfaces (estimated tokens): ${report.agentSurfaces.map((s) => `${s.name} ${(s.tokens / 1e3).toFixed(1)}k`).join(" \xB7 ")}
+Agent guide: ${report.agentGuide.agentsFile === null ? "no AGENTS.md \u2014 `pnpm content init-agent --write` installs the baseline" : report.agentGuide.linksGuide ? `${report.agentGuide.agentsFile} points at the engine's guide` : `${report.agentGuide.agentsFile} does not point at node_modules/explico/docs/authoring/agents.md \u2014 add that line`}; procedures ${report.agentGuide.skillsInstalled ? "installed" : "not installed (`pnpm content init-agent --write`)"}
+`
+      );
+      return 0;
+    }
+    case "move":
+    case "rename":
+    case "fix": {
+      let plan;
+      if (args.command === "move") {
+        const [target, ...extra] = args.positionals;
+        const [lesson, key] = (target ?? "").split(":");
+        if (!lesson || !key || extra.length > 0) usage("usage", "content move needs <lesson>:<key> and optionally --to <key>.");
+        plan = planMove(manifest, lesson, key, args.to === void 0 ? {} : { to: args.to });
+      } else if (args.command === "rename") {
+        const [oldKey, newKey, ...extra] = args.positionals;
+        if (!oldKey || !newKey || extra.length > 0) usage("usage", "content rename needs <old> <new>.");
+        plan = planRename(manifest, oldKey, newKey);
+      } else {
+        if (args.all === args.positionals.length > 0) usage("usage", "content fix needs <lesson> ids, or --all for every lesson.");
+        plan = planFixMany(manifest, args.all ? manifest.lessons.map((lesson) => lesson.id) : args.positionals);
+      }
+      if (args.json) json({ ...plan, written: args.write });
+      else out(renderEditPlan(plan));
+      if (plan.edits.length === 0) return 0;
+      if (args.write) {
+        const touched = applyEditPlan(plan);
+        if (!args.json) out(`
+written: ${touched.join(", ")}
+next: ${plan.next.join(" \xB7 ")}
+`);
+      } else if (!args.json) {
+        out(`
+dry run: nothing written. Add --write to apply; then ${plan.next.join(" \xB7 ")}.
+`);
+      }
+      return 0;
+    }
+    case "rule": {
+      const [id, ...extra] = args.positionals;
+      if (!id) usage("usage", "content rule needs a rule ID: N4, V8, X1, or an invariant such as keyed-floats.");
+      if (extra.length > 0) usage("usage", `content rule takes one ID; got also ${extra.join(" ")}.`);
+      const report = contentRule(manifest, id);
+      if (args.json) json(report);
+      else out(formatRuleReport(report));
+      return report.status === "unknown" ? 1 : 0;
+    }
+    case "rules": {
+      const filter = parseRulesFilter({
+        ...args.element === void 0 ? {} : { element: args.element },
+        ...args.enforcement === void 0 ? {} : { enforcement: args.enforcement },
+        ...args.edition === void 0 ? {} : { edition: args.edition }
+      });
+      const report = contentRules(manifest, filter);
+      if (args.json) json({ filter: report.filter, count: report.count, rules: report.rules });
+      else out(report.markdown);
+      return 0;
+    }
+    case "warnings": {
+      const report = contentWarnings(manifest);
+      if (args.json) json(report);
+      else {
+        for (const warning of report.warnings) out(`${formatCliDiagnostic(warning)}
+`);
+        out(`${report.count} warning(s)
+`);
+      }
+      return 0;
+    }
+    case "diagnostics": {
+      const [requested = "info", ...extra] = args.positionals;
+      if (extra.length > 0 || requested !== "info" && requested !== "warning" && requested !== "error") {
+        usage("usage", "content diagnostics expects one of: info, warning, error.");
+      }
+      let report = contentDiagnostics(manifest, requested);
+      let narrowed = false;
+      if (args.code !== void 0) {
+        report = filterDiagnostics(report, { code: args.code });
+        narrowed = true;
+      }
+      if (args.lesson !== void 0) {
+        report = filterDiagnostics(report, { files: [findLesson(manifest, args.lesson).file] });
+        narrowed = true;
+      }
+      if (args.changed) {
+        const ids = new Set(changedLessonIds());
+        const files = manifest.lessons.filter((l) => ids.has(l.id)).map((l) => l.file);
+        report = filterDiagnostics(report, { files });
+        narrowed = true;
+      }
+      if (args.json) json(report);
+      else if (args.all || narrowed) {
+        for (const diagnostic of report.diagnostics) out(`${formatCliDiagnostic(diagnostic)}
+`);
+        out(`${report.count} diagnostic(s) at ${report.minimumSeverity} or higher
+`);
+      } else out(formatDiagnosticsSummary(summarizeDiagnostics(report)));
+      return 0;
+    }
+    case "context": {
+      const [lesson, ...extra] = args.positionals;
+      if (!lesson) usage("usage", "content context needs a <lesson> id.");
+      if (extra.length > 0) usage("usage", `content context takes one <lesson> id; got also ${extra.join(" ")}.`);
+      const report = contentContext(manifest, lesson);
+      if (args.json) {
+        json(report);
+        return 0;
+      }
+      const t = report.tokens;
+      out(
+        `${report.lesson.id} \u2014 ${report.lesson.title}
+teaches: ${report.lesson.teaches.join(", ") || "(none)"}
+requires: ${report.lesson.requires.join(", ") || "(none)"}
+notation: ${report.notation.map((n) => n.key).join(", ") || "(none)"}
+sources: ${report.sources.map((s) => s.id).join(", ") || "(none)"}
+diagnostics: ${report.diagnostics.length}${diagnosticsWhere(report.diagnostics, report.lesson.file)}
+tokens: context ${t.context} vs doc set ${t.docSet} + corpus ${t.corpus} (${(t.ratio * 100).toFixed(2)}% of the baseline)
+`
+      );
+      return 0;
+    }
+    case "equation": {
+      const [latex, ...extra] = args.positionals;
+      if (!latex) usage("usage", "content equation needs one quoted LaTeX string: content equation 'v_0 \\sin(\\theta)' --lesson <id>.");
+      if (extra.length > 0) usage("usage", `content equation takes one string; got also ${extra.join(" ")}. Quote the whole expression.`);
+      const report = contentEquation(manifest, latex, args.lesson === void 0 ? {} : { lesson: args.lesson });
+      if (args.json) json(report);
+      else out(formatEquationReport(report));
+      return report.ok ? 0 : 1;
+    }
+    case "bindings": {
+      const [lesson, ...extra] = args.positionals;
+      if (!lesson) usage("usage", "content bindings needs a <lesson> id.");
+      if (extra.length > 0) usage("usage", `content bindings takes one <lesson> id; got also ${extra.join(" ")}.`);
+      const report = contentBindings(manifest, lesson);
+      if (args.json) json(report);
+      else out(formatBindingsReport(report));
+      return 0;
+    }
+    case "symbol": {
+      const [query, ...extra] = args.positionals;
+      if (!query) usage("usage", "content symbol needs a <latex | key>; quote a backslash: '\\theta'.");
+      if (extra.length > 0) {
+        usage("usage", `content symbol takes one <latex | key>; got also ${extra.join(" ")}. Quote a symbol with spaces: 'v(t)'.`);
+      }
+      const report = contentSymbol(manifest, query);
+      if (args.json) json(report);
+      else out(formatSymbolReport(report));
+      return 0;
+    }
+    case "check": {
+      const report = await contentCheck(manifest, { lessons: args.positionals, changed: args.changed });
+      if (args.json) json(report);
+      else {
+        for (const entry of report.lessons) {
+          out(`${entry.ok ? "ok  " : "FAIL"} ${entry.lesson}${entry.rendered ? "" : " (render failed)"}
+`);
+          const infos = /* @__PURE__ */ new Map();
+          for (const diagnostic of entry.diagnostics) {
+            if (diagnostic.severity === "info") infos.set(diagnostic.code, (infos.get(diagnostic.code) ?? 0) + 1);
+            else out(`     [${diagnostic.severity}] ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}
+`);
+          }
+          if (infos.size > 0) {
+            const total = [...infos.values()].reduce((sum, n) => sum + n, 0);
+            const byCode = [...infos].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([code, n]) => `${code} ${n}`).join(", ");
+            out(`     + ${total} info (${byCode}); content diagnostics --lesson ${entry.lesson} lists them
+`);
+          }
+        }
+        if (report.lessons.length === 0) out("No changed lessons.\n");
+      }
+      return report.ok ? 0 : 1;
+    }
+    default:
+      return usage("unknown-command", `Unknown command "${args.command}".
+${CONTENT_USAGE}`);
+  }
+}
+export {
+  CONTENT_USAGE,
+  parseContentArgs,
+  runContentCli
+};

package/dist/compiler/cli-reference.d.ts

@@ -0,0 +1,50 @@
+import { ContentVerb } from './cli-verbs.js';
+
+/** A JSON Schema (draft 2020-12), the subset the generator writes. */
+type JsonSchema = Readonly<Record<string, unknown>>;
+/** `docs/authoring/cli-reference.json`, whole: what `content help --json` prints. */
+interface CliReference {
+    /** Where it came from, and that it is generated. */
+    readonly generatedBy: string;
+    readonly verbs: readonly ContentVerb[];
+    /** The type every verb's `--json` prints when the run fails: a stable code and a message, never a stack. */
+    readonly error: string;
+    /** A JSON Schema of every type a verb's `--json` prints, and of every named type inside one, by name. */
+    readonly $defs: Readonly<Record<string, JsonSchema>>;
+}
+/** One verb's row, its usage line, and a self-contained JSON Schema of its `--json`. */
+interface VerbHelp extends ContentVerb {
+    readonly usage: string;
+    readonly schema: JsonSchema;
+}
+/** What `content help <verb> --json` prints: every verb the word names (`new` names three). */
+interface VerbHelpJson {
+    readonly verbs: readonly VerbHelp[];
+}
+/** `content help --json` prints the whole reference; `content help <verb> --json` that verb's rows. */
+type HelpJson = CliReference | VerbHelpJson;
+declare const CLI_REFERENCE_FILE = "cli-reference.json";
+/** The reference beside the engine (`node_modules/explico/docs/authoring/`, or this repository's). */
+declare function loadCliReference(): CliReference;
+/** The verbs a word names: `symbol` one, `new` the three `new …` verbs. */
+declare function verbsNamed(word: string): readonly ContentVerb[];
+/** A self-contained schema of one named type: a `$ref` and the `$defs` it reaches. */
+declare function schemaOf(reference: CliReference, name: string): JsonSchema;
+declare function verbHelp(reference: CliReference, word: string): VerbHelpJson;
+/** One line per property, `name?: type  — description`, nested objects indented under their property. */
+declare function shapeLines(schema: JsonSchema, indent?: string): string[];
+/** A named type as a block: its name and description, then its shape. */
+declare function defLines(name: string, schema: JsonSchema): string[];
+/** `content help <verb>` as text: the usage, what it is for, its flags, and the shape of its `--json`. */
+declare function formatVerbHelp(reference: CliReference, help: VerbHelpJson): string;
+/** `docs/authoring/cli.md`, generated: one section per verb, then every `--json` type. */
+declare function cliReferenceMarkdown(reference: CliReference): string;
+/**
+ * Where `value` departs from `schema`, one message per place (`$.hits[0].tier:
+ * expected one of …`); empty when it conforms. The subset the generator
+ * writes: `$ref`, `type`, `const`, `enum`, `anyOf`, `properties`, `required`,
+ * `additionalProperties`, `items`.
+ */
+declare function jsonShapeErrors(schema: JsonSchema, value: unknown, defs?: CliReference["$defs"], path?: string): string[];
+
+export { CLI_REFERENCE_FILE, type CliReference, type HelpJson, type JsonSchema, type VerbHelp, type VerbHelpJson, cliReferenceMarkdown, defLines, formatVerbHelp, jsonShapeErrors, loadCliReference, schemaOf, shapeLines, verbHelp, verbsNamed };