explico 0.1.0

package/dist/compiler/cli.js

@@ -0,0 +1,552 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  createMarkdownProcessor,
+  parseFrontmatter
+} from "@astrojs/markdown-remark";
+import rehypeKatex from "rehype-katex";
+import remarkMath from "remark-math";
+import { createNotationKatexOptions } from "../reference/katex-options.mjs";
+import rehypeFailKatexErrors from "../reference/rehype-fail-katex-errors.mjs";
+import remarkCitation from "../reference/remark-citation.mjs";
+import remarkNotation from "../reference/remark-notation.mjs";
+import { isLessonSlug, lessonIdFromSlug } from "./lesson-derivation";
+const REPOSITORY_ROOT = process.cwd();
+const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
+const DOCS_ROOT = join(CONTENT_ROOT, "docs");
+const DOMAIN_ROOT = join(CONTENT_ROOT, "domain");
+class ContentCliError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ContentCliError";
+    this.code = code;
+  }
+}
+function mentions(message, lessonId, file) {
+  return message.includes(lessonId) || message.includes(file) || message.includes(file.replace(/^content\/docs\//, ""));
+}
+function lessonDiagnostics(manifest, lesson) {
+  const out = [];
+  const { file, id } = lesson;
+  const assessments = new Set(lesson.assessments);
+  const withFile = (value) => value === void 0 ? {} : { file: value };
+  for (const issue of manifest.diagnostics.curriculum) {
+    if (!mentions(issue.message, id, file)) continue;
+    out.push({
+      code: `curriculum:${issue.kind}`,
+      severity: issue.severity === "warning" ? "warning" : "error",
+      message: issue.message
+    });
+  }
+  for (const diagnostic of [
+    ...manifest.diagnostics.notation.map((d) => ["notation", d]),
+    ...manifest.diagnostics.alignment.map((d) => ["alignment", d])
+  ]) {
+    const [group, entry] = diagnostic;
+    const entryFile = entry.source?.file;
+    if (entry.lessonId !== id && entryFile !== file && !mentions(entry.message, id, file)) {
+      continue;
+    }
+    out.push({
+      code: `${group}:${entry.code}`,
+      severity: entry.severity === "warning" ? "warning" : "error",
+      message: entry.message,
+      ...withFile(entryFile)
+    });
+  }
+  for (const diagnostic of manifest.diagnostics.math) {
+    const forLesson = diagnostic.file === file || diagnostic.context === "assessment" && [...assessments].some(
+      (assessmentId) => diagnostic.file.startsWith(`${assessmentId} `)
+    );
+    if (!forLesson) continue;
+    out.push({
+      code: `math:${diagnostic.context}`,
+      severity: diagnostic.severity,
+      message: diagnostic.message,
+      file: diagnostic.file,
+      ...diagnostic.line === void 0 ? {} : { line: diagnostic.line }
+    });
+  }
+  for (const diagnostic of manifest.diagnostics.equations) {
+    if (diagnostic.lessonId !== id && diagnostic.file !== file && !mentions(diagnostic.message, id, file)) {
+      continue;
+    }
+    out.push({
+      code: `equations:${diagnostic.code}`,
+      severity: diagnostic.severity === "warning" ? "warning" : "error",
+      message: diagnostic.message,
+      ...withFile(diagnostic.file)
+    });
+  }
+  for (const diagnostic of manifest.diagnostics.consistency) {
+    if (diagnostic.file !== file && diagnostic.lessonId !== id) continue;
+    out.push({
+      code: `consistency:${diagnostic.code}`,
+      severity: "warning",
+      message: diagnostic.message,
+      ...withFile(diagnostic.file)
+    });
+  }
+  return out.sort(
+    (a, b) => a.code.localeCompare(b.code) || a.message.localeCompare(b.message)
+  );
+}
+let processorPromise;
+function processorFor(manifest) {
+  processorPromise ??= createMarkdownProcessor({
+    syntaxHighlight: false,
+    smartypants: false,
+    remarkPlugins: [
+      remarkMath,
+      [
+        remarkNotation,
+        {
+          definitions: manifest.notation.raw,
+          equations: manifest.equations.numbersBySlug
+        }
+      ],
+      [remarkCitation, { sources: manifest.sources }]
+    ],
+    rehypePlugins: [
+      [rehypeKatex, createNotationKatexOptions()],
+      rehypeFailKatexErrors
+    ]
+  });
+  return processorPromise;
+}
+function stripEsm(body) {
+  return body.replace(/^(?:import|export)\s[^\n]*\n?/gm, "");
+}
+function renderErrorCode(message) {
+  if (/Unresolved notation/i.test(message)) return "render:notation";
+  if (/KaTeX|ParseError|katex-error/i.test(message)) return "render:katex";
+  if (/Unknown notation key|Malformed notation|Invalid notation key/i.test(
+    message
+  )) {
+    return "render:notation";
+  }
+  if (/equation reference|display equation|equation label eq:/i.test(message)) {
+    return "render:equation";
+  }
+  if (/Unknown (?:source|citation)|Malformed citation/i.test(message)) {
+    return "render:citation";
+  }
+  return "render:mdx";
+}
+async function renderLesson(manifest, input) {
+  const processor = await processorFor(manifest);
+  const lessonId = lessonIdFromSlug(
+    relative(DOCS_ROOT, input.path).replace(/\\/g, "/")
+  );
+  try {
+    await processor.render(stripEsm(input.body), {
+      frontmatter: { ...input.frontmatter, lessonId },
+      fileURL: pathToFileURL(input.path)
+    });
+    return { rendered: true, diagnostics: [] };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      rendered: false,
+      diagnostics: [
+        { code: renderErrorCode(message), severity: "error", message }
+      ]
+    };
+  }
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function readIfExists(path) {
+  return existsSync(path) ? readFileSync(path, "utf8") : "";
+}
+function walkFiles(directory) {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) return walkFiles(path);
+    return entry.isFile() ? [path] : [];
+  });
+}
+function docSetTokens() {
+  return ["README.md", "AGENTS.md", join("docs", "architecture.md")].map(
+    (relPath) => estimateTokens(readIfExists(join(REPOSITORY_ROOT, relPath)))
+  ).reduce((sum, value) => sum + value, 0);
+}
+function corpusTokens() {
+  return walkFiles(CONTENT_ROOT).map((path) => estimateTokens(readFileSync(path, "utf8"))).reduce((sum, value) => sum + value, 0);
+}
+function tokenCounts(contextPayload) {
+  const context = estimateTokens(JSON.stringify(contextPayload));
+  const docSet = docSetTokens();
+  const corpus = corpusTokens();
+  const baseline = docSet + corpus;
+  return {
+    context,
+    docSet,
+    corpus,
+    ratio: baseline === 0 ? 0 : Math.round(context / baseline * 1e4) / 1e4
+  };
+}
+function normalizeLessonId(raw) {
+  const trimmed = raw.trim().replace(/\.mdx?$/, "");
+  if (trimmed.includes("/")) return trimmed.replace(/\//g, ".");
+  return trimmed;
+}
+function findLesson(manifest, rawId) {
+  const id = normalizeLessonId(rawId);
+  const lesson = manifest.lessons.find((entry) => entry.id === id);
+  if (!lesson) {
+    throw new ContentCliError(
+      "unknown-lesson",
+      `No lesson ${JSON.stringify(id)}. Known ids: ${manifest.lessons.map((entry) => entry.id).join(", ")}`
+    );
+  }
+  return lesson;
+}
+function lessonAbsolutePath(lesson) {
+  return join(REPOSITORY_ROOT, lesson.file);
+}
+function lessonRaw(lesson) {
+  const parsed = parseFrontmatter(
+    readFileSync(lessonAbsolutePath(lesson), "utf8")
+  );
+  return {
+    frontmatter: parsed.frontmatter ?? {},
+    body: parsed.content.replace(/^\n/, "")
+  };
+}
+const DOMAIN_DIRS_BY_SECTION = {
+  foundations: [".", "rates", "valuation"],
+  bonds: ["bonds", "rates"],
+  rates: ["rates"],
+  derivatives: ["derivatives", "valuation"],
+  "bond-options": ["bonds", "derivatives", "valuation"],
+  credit: ["credit"],
+  cds: ["cds", "credit"]
+};
+const EXPORT_FN = /export\s+(?:async\s+)?function\s+([A-Za-z0-9_]+)\s*(\([\s\S]*?\))\s*(?::\s*([^\n{]+?))?\s*\{/g;
+const EXPORT_ARROW = /export\s+const\s+([A-Za-z0-9_]+)\s*(?::\s*[^=\n]+)?=\s*(?:async\s*)?(\([\s\S]*?\))\s*(?::\s*([^=\n]+?))?\s*=>/g;
+function signaturesInFile(path) {
+  const source = readFileSync(path, "utf8");
+  const out = [];
+  for (const pattern of [EXPORT_FN, EXPORT_ARROW]) {
+    pattern.lastIndex = 0;
+    let match;
+    while (match = pattern.exec(source)) {
+      const params = (match[2] ?? "").replace(/\s+/g, " ").trim();
+      const ret = (match[3] ?? "").replace(/\s+/g, " ").trim();
+      out.push(`${match[1]}${params}${ret ? `: ${ret}` : ""}`);
+    }
+  }
+  return out.sort();
+}
+function domainSignaturesForSection(section) {
+  const dirs = DOMAIN_DIRS_BY_SECTION[section] ?? [section];
+  const files = /* @__PURE__ */ new Set();
+  for (const dir of dirs) {
+    const base = dir === "." ? DOMAIN_ROOT : join(DOMAIN_ROOT, dir);
+    if (dir === ".") {
+      for (const entry of existsSync(base) ? readdirSync(base) : []) {
+        if (entry.endsWith(".ts")) files.add(join(base, entry));
+      }
+    } else {
+      for (const path of walkFiles(base)) {
+        if (path.endsWith(".ts")) files.add(path);
+      }
+    }
+  }
+  return [...files].sort().map((path) => ({
+    file: relative(REPOSITORY_ROOT, path).replace(/\\/g, "/"),
+    signatures: signaturesInFile(path)
+  })).filter((entry) => entry.signatures.length > 0);
+}
+function contentStatus(manifest) {
+  const draftLessons = manifest.lessons.filter((lesson) => lesson.status === "draft").map((lesson) => lesson.id).sort();
+  const draftNotation = manifest.notation.definitions.filter((definition) => definition.status === "draft").map((definition) => definition.id).sort();
+  const orphans = manifest.notation.diagnostics.filter((diagnostic) => diagnostic.code === "unused-definition").map((diagnostic) => ({
+    code: `notation:${diagnostic.code}`,
+    severity: diagnostic.severity === "warning" ? "warning" : "error",
+    message: diagnostic.message,
+    ...diagnostic.source?.file === void 0 ? {} : { file: diagnostic.source.file }
+  })).sort((a, b) => a.message.localeCompare(b.message));
+  const allDiagnostics = [
+    ...manifest.diagnostics.curriculum.map((d) => d.severity ?? "error"),
+    ...manifest.diagnostics.notation.map((d) => d.severity),
+    ...manifest.diagnostics.alignment.map((d) => d.severity),
+    ...manifest.diagnostics.math.map((d) => d.severity),
+    ...manifest.diagnostics.equations.map((d) => d.severity),
+    ...manifest.diagnostics.consistency.map(() => "warning")
+  ];
+  const keyedEquations = manifest.lessons.reduce(
+    (count, lesson) => count + lesson.equations.length,
+    0
+  );
+  const assessments = new Set(
+    manifest.lessons.flatMap((lesson) => lesson.assessments)
+  ).size;
+  return {
+    counts: {
+      lessons: manifest.lessons.length,
+      competencies: manifest.competencies.length,
+      assessments,
+      sources: manifest.sources.length,
+      tracks: manifest.tracks.length,
+      notationDefinitions: manifest.notation.definitions.length,
+      keyedEquations
+    },
+    draftDebt: { lessons: draftLessons, notation: draftNotation },
+    orphans,
+    diagnostics: {
+      errors: allDiagnostics.filter((severity) => severity === "error").length,
+      warnings: allDiagnostics.filter((severity) => severity === "warning").length
+    }
+  };
+}
+function contentContext(manifest, rawId) {
+  const lesson = findLesson(manifest, rawId);
+  const { frontmatter, body } = lessonRaw(lesson);
+  const outcomeById = new Map(
+    manifest.competencies.map((competency) => [
+      String(competency.id),
+      String(competency.outcome ?? "")
+    ])
+  );
+  const outcomesFor = (ids) => ids.filter((id) => outcomeById.has(id)).map((id) => ({ id, outcome: outcomeById.get(id) ?? "" }));
+  const sourceById = new Map(
+    manifest.sources.map((source) => [String(source.id), source])
+  );
+  const citedLocatorsById = /* @__PURE__ */ new Map();
+  for (const citation of lesson.citations) {
+    const list = citedLocatorsById.get(citation.id) ?? [];
+    if (citation.locator) list.push(citation.locator);
+    citedLocatorsById.set(citation.id, list);
+  }
+  const contextWithoutTokens = {
+    lesson: {
+      id: lesson.id,
+      slug: lesson.slug,
+      file: lesson.file,
+      title: lesson.title,
+      description: lesson.description,
+      status: lesson.status,
+      teaches: lesson.teaches,
+      requires: lesson.requires,
+      assumptions: lesson.assumptions,
+      notationLocal: frontmatter.notation?.local ?? [],
+      body
+    },
+    taughtOutcomes: outcomesFor(lesson.teaches),
+    prerequisiteOutcomes: outcomesFor(lesson.requires),
+    notation: lesson.notation.definitions.map((definition) => ({
+      key: definition.key,
+      latex: definition.notation,
+      meaning: definition.summary,
+      scope: definition.scope,
+      ...definition.units === void 0 ? {} : { units: definition.units },
+      ...definition.formula === void 0 ? {} : { formula: definition.formula }
+    })),
+    equations: lesson.equations.map((equation) => ({ ...equation })),
+    sources: lesson.sources.map((id) => {
+      const record = sourceById.get(id);
+      return {
+        id,
+        title: String(record?.title ?? id),
+        type: String(record?.type ?? "unknown"),
+        ...typeof record?.locator === "string" ? { recordLocator: record.locator } : {},
+        citedLocators: citedLocatorsById.get(id) ?? []
+      };
+    }),
+    domainSignatures: domainSignaturesForSection(
+      lesson.slug.split("/")[0] ?? ""
+    ),
+    diagnostics: lessonDiagnostics(manifest, lesson)
+  };
+  return {
+    ...contextWithoutTokens,
+    tokens: tokenCounts(contextWithoutTokens)
+  };
+}
+async function checkOneLesson(manifest, lesson) {
+  const manifestDiagnostics = lessonDiagnostics(manifest, lesson);
+  const { frontmatter, body } = lessonRaw(lesson);
+  const render = await renderLesson(manifest, {
+    body,
+    frontmatter,
+    path: lessonAbsolutePath(lesson)
+  });
+  const diagnostics = [...manifestDiagnostics, ...render.diagnostics].sort(
+    (a, b) => a.code.localeCompare(b.code) || a.message.localeCompare(b.message)
+  );
+  return {
+    lesson: lesson.id,
+    file: lesson.file,
+    ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
+    rendered: render.rendered,
+    diagnostics
+  };
+}
+function changedLessonIds() {
+  let output;
+  try {
+    const tracked = execFileSync(
+      "git",
+      ["diff", "--name-only", "HEAD", "--", "content/docs"],
+      { cwd: REPOSITORY_ROOT, encoding: "utf8" }
+    );
+    const untracked = execFileSync(
+      "git",
+      ["ls-files", "--others", "--exclude-standard", "--", "content/docs"],
+      { cwd: REPOSITORY_ROOT, encoding: "utf8" }
+    );
+    output = `${tracked}
+${untracked}`;
+  } catch {
+    throw new ContentCliError(
+      "no-git",
+      "Could not read git status for --changed. Run inside a git working tree."
+    );
+  }
+  const ids = /* @__PURE__ */ new Set();
+  for (const line of output.split("\n")) {
+    const path = line.trim();
+    if (!path) continue;
+    const slug = path.replace(/^content\/docs\//, "").replace(/\.checks\.yml$/, ".mdx").replace(/\.mdx?$/, "");
+    if (!isLessonSlug(slug)) continue;
+    ids.add(slug.replace(/\//g, "."));
+  }
+  return [...ids].sort();
+}
+async function contentCheck(manifest, options) {
+  let targets;
+  if (options.changed) {
+    const ids = changedLessonIds();
+    targets = manifest.lessons.filter((lesson) => ids.includes(lesson.id));
+  } else {
+    if (!options.lesson) {
+      throw new ContentCliError(
+        "usage",
+        "content check needs a <lesson> id or --changed."
+      );
+    }
+    targets = [findLesson(manifest, options.lesson)];
+  }
+  const lessons = await Promise.all(
+    targets.map((lesson) => checkOneLesson(manifest, lesson))
+  );
+  return { ok: lessons.every((entry) => entry.ok), lessons };
+}
+const ID_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+function scaffoldLesson(rawId) {
+  const slug = rawId.trim().replace(/\.mdx?$/, "").replace(/\./g, "/");
+  if (!slug.includes("/")) {
+    throw new ContentCliError(
+      "invalid-id",
+      `A lesson id is <section>/<slug> (or <section>.<slug>), got ${JSON.stringify(rawId)}.`
+    );
+  }
+  if (!isLessonSlug(slug) || slug.split("/").some((part) => !ID_PATTERN.test(part))) {
+    throw new ContentCliError(
+      "invalid-id",
+      `Lesson slug ${JSON.stringify(slug)} is not a valid <section>/<slug>.`
+    );
+  }
+  const relPath = `content/docs/${slug}.mdx`;
+  const checksPath = `content/docs/${slug}.checks.yml`;
+  if (existsSync(join(REPOSITORY_ROOT, relPath))) {
+    throw new ContentCliError(
+      "exists",
+      `${relPath} already exists; not overwriting.`
+    );
+  }
+  const title = (slug.split("/").at(-1) ?? slug).split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  const contents = `---
+title: ${title}
+description: One sentence on what the reader can do after this lesson.
+editorialStatus: draft
+teaches: []
+assumptions: []
+---
+
+import CompactExample from '../../../components/examples/CompactExample.astro';
+import AssessmentSet from '../../../components/assessments/AssessmentSet.astro';
+
+## What you will be able to do
+
+After this lesson, you should be able to:
+
+- <!-- one observable outcome per teaches entry -->
+
+## Intuition
+
+<!-- draft prose; every symbol introduced with [[key]] before its first math use -->
+
+## Model
+
+<!-- the reproducible worked example; every numeral tagged to a content/domain/ call or [@source; locator] -->
+`;
+  return {
+    path: relPath,
+    contents,
+    companions: [
+      {
+        path: checksPath,
+        contents: `# Assessment sets for this lesson. Ids resolve against content/assessments/.
+[]
+`
+      }
+    ]
+  };
+}
+function scaffoldTerm(rawKey) {
+  const key = rawKey.trim();
+  if (!ID_PATTERN.test(key)) {
+    throw new ContentCliError(
+      "invalid-id",
+      `A notation key is lower-case, dot/hyphen separated, got ${JSON.stringify(rawKey)}.`
+    );
+  }
+  const relPath = `content/notation/${key}.md`;
+  if (existsSync(join(REPOSITORY_ROOT, relPath))) {
+    throw new ContentCliError(
+      "exists",
+      `${relPath} already exists; not overwriting.`
+    );
+  }
+  const contents = `---
+key: ${key}
+latex: 'x'
+meaning: Describe the quantity this symbol denotes.
+domain: general
+units: stated currency
+sources: []
+seeAlso: []
+alignment:
+  kind: general
+  rationale: Draft scaffold \u2014 set a real alignment before review.
+editorialStatus: draft
+aiAssisted: true
+---
+
+Draft definition for [[${key}]]. Replace this body and the placeholder
+frontmatter before moving the entry past \`draft\`.
+`;
+  return { path: relPath, contents, companions: [] };
+}
+export {
+  ContentCliError,
+  changedLessonIds,
+  contentCheck,
+  contentContext,
+  contentStatus,
+  estimateTokens,
+  findLesson,
+  lessonDiagnostics,
+  normalizeLessonId,
+  renderLesson,
+  scaffoldLesson,
+  scaffoldTerm
+};

package/dist/compiler/collections.d.ts

@@ -0,0 +1,70 @@
+import { CurriculumCatalog } from '../curriculum/validation.js';
+import { NotationReferenceInput, NotationRegistryInput } from '../reference/types.js';
+
+/**
+ * The single path from content files to typed data.
+ *
+ * Every consumer — the `validate:content` CLI, the Astro build (`astro.config.mjs`),
+ * the Starlight footer, the lab math scope, and the tests — reads content through
+ * this module. It walks `src/content/` once and parses frontmatter with Astro's
+ * own `parseFrontmatter` (the same parser the content collections use), so there
+ * is no second Markdown/YAML reader and `gray-matter` is no longer a dependency.
+ *
+ * Replaces `scripts/curriculum-files.ts`, `scripts/notation-files.ts`, and the
+ * inline `readdirSync`/`gray-matter` notation + source loads in `astro.config.mjs`.
+ */
+
+/**
+ * Notation references (`[[key]]` in prose, `\explain{key}` in math) in a body,
+ * ignoring code fences and inline code, sorted by position.
+ */
+declare function extractNotationReferences(text: string, file: string, kind: NotationReferenceInput['kind'] | undefined): NotationReferenceInput[];
+declare function loadCurriculumCatalog(): Promise<CurriculumCatalog>;
+declare function loadNotationRegistryInput(): Promise<NotationRegistryInput>;
+/**
+ * Notation frontmatter objects for `remark-notation`'s `definitions` option.
+ * Returned synchronously because the remark transform reads the loader inline.
+ */
+declare function loadNotationDefinitions(): Record<string, unknown>[];
+/** Parsed `src/content/sources/*.json` records for `remark-citation`. */
+declare function loadSourceRecords(): Record<string, unknown>[];
+/**
+ * Assessment ids for one lesson, from its colocated `<name>.checks.yml`. The
+ * lesson layout uses this to auto-place `<AssessmentSet>`; nothing is authored
+ * in the MDX body.
+ */
+declare function loadLessonChecks(lessonId: string): string[];
+/**
+ * Flat view of every notation entry (shared + page-local) for the consistency
+ * checks (Step D6): the fields those checks read that the registry input drops
+ * or normalizes — the raw `dimensionless` marker and the per-source locator
+ * shape. One walk of the same files the loader already parses.
+ */
+interface NotationSpec {
+    /** `shared:<key>` or `page:<lessonId>:<key>` — matches the registry id. */
+    readonly id: string;
+    readonly key: string;
+    readonly scope: 'shared' | 'local';
+    readonly lessonId?: string;
+    readonly file: string;
+    readonly latex: string;
+    readonly units?: string;
+    readonly dimensionless: boolean;
+    readonly formula?: string;
+    readonly sources: readonly {
+        readonly id: string;
+        readonly hasLocator: boolean;
+    }[];
+}
+declare function loadNotationSpecs(): NotationSpec[];
+/**
+ * Notation `sources` entries still written as a bare id rather than
+ * `{ id, locator }` (Phase C1b shape). Formalized as the `notation-source-locator`
+ * consistency check in Step D6; kept here for the CLI summary line.
+ */
+declare function notationSourceLocatorGaps(): {
+    bare: number;
+    total: number;
+};
+
+export { type NotationSpec, extractNotationReferences, loadCurriculumCatalog, loadLessonChecks, loadNotationDefinitions, loadNotationRegistryInput, loadNotationSpecs, loadSourceRecords, notationSourceLocatorGaps };