explico 0.13.1 → 0.14.0

package/dist/compiler/cli-main.js

@@ -0,0 +1,392 @@
+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,
+  planFix,
+  planInitAgent,
+  planMove,
+  planRename,
+  renderEditPlan,
+  scaffoldDeck,
+  scaffoldLesson,
+  scaffoldTerm,
+  summarizeDiagnostics
+} from "./cli.js";
+import { compileManifest } from "./manifest.js";
+const CONTENT_USAGE = `Usage:
+  pnpm content status
+  pnpm content diagnostics [info|warning|error] [--all | --code <c> | --lesson <id> | --changed] [--json]
+  pnpm content warnings [--json]
+  pnpm content context <lesson> [--json]
+  pnpm content equation "<latex>" [--lesson <id>] [--json]
+  pnpm content bindings <lesson> [--json]
+  pnpm content symbol <latex | key> [--json]
+  pnpm content check <lesson | deck>\u2026 [--changed] [--json]
+  pnpm content rule <ID> [--json]
+  pnpm content migrate [--from <version>] [--to <version>] [--json]
+  pnpm content rules [--element <e>[,<e>]] [--enforcement script|partial|guide|locked] [--edition chapter|deck] [--json]
+  pnpm content move <lesson>:<key> [--to <key>] [--write]
+  pnpm content rename <old> <new> [--write]
+  pnpm content fix <lesson> [--write]
+  pnpm content new lesson <id>
+  pnpm content new deck <lesson | part>
+  pnpm content new term <key>
+  pnpm content init-agent [--write]`;
+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;
+  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 (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,
+    ...values
+  };
+}
+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) {
+  const args = parseContentArgs(argv);
+  const json = (value) => io.out(`${JSON.stringify(value, null, 2)}
+`);
+  try {
+    return await dispatch(courseConfig, args, io, json);
+  } 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) {
+  const out = io.out;
+  if (args.command === "" || args.command === "help" || args.command === "--help") {
+    out(`${CONTENT_USAGE}
+`);
+    return 0;
+  }
+  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") {
+    if (args.positionals.length > 0) usage("usage", `content init-agent takes no argument; got ${args.positionals.join(" ")}.`);
+    const plan = planInitAgent();
+    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(", ")}
+`);
+    } else if (!args.json) out("\ndry run: nothing written. Add --write to install.\n");
+    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 = 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;
+      out(
+        `Knowledge version ${report.knowledgeVersion}
+Page versions: ${report.pageVersions.tracked} page(s) tracked, ${unreleased.length} with changes not yet released${unreleased.length > 0 ? ` (${unreleased.join(", ")})` : ""}
+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 {
+        const [lesson, ...extra] = args.positionals;
+        if (!lesson || extra.length > 0) usage("usage", "content fix needs one <lesson> id.");
+        plan = planFix(manifest, lesson);
+      }
+      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}
+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)"}
+`);
+          for (const diagnostic of entry.diagnostics) {
+            out(`     [${diagnostic.severity}] ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}
+`);
+          }
+        }
+        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
+};