explico 0.1.0

package/dist/compiler/collections.js

@@ -0,0 +1,383 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import { parseFrontmatter } from "@astrojs/markdown-remark";
+import { isSubstantiveMeaning } from "../reference/prose";
+import { parseEquationRef } from "../reference/equations.mjs";
+import { resolveLabel } from "../reference/label";
+import {
+  deriveRequires,
+  deriveSources,
+  isLessonSlug,
+  lessonIdFromSlug,
+  parseCheckList
+} from "./lesson-derivation";
+const REPOSITORY_ROOT = process.cwd();
+const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
+function filesBelow(directory, extensions) {
+  const entries = readdirSync(directory, { withFileTypes: true });
+  return entries.flatMap((entry) => {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) return filesBelow(path, extensions);
+    return entry.isFile() && extensions.some((extension) => entry.name.endsWith(extension)) ? [path] : [];
+  }).sort();
+}
+function parseDocument(path) {
+  const parsed = parseFrontmatter(readFileSync(path, "utf8"));
+  return {
+    file: relative(REPOSITORY_ROOT, path),
+    data: parsed.frontmatter ?? {},
+    body: parsed.content.replace(/^\n/, "")
+  };
+}
+function record(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  return value;
+}
+function string(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+function optionalString(value, label) {
+  return value === void 0 ? void 0 : string(value, label);
+}
+function meaningText(value, label) {
+  const text = string(value, label);
+  if (!isSubstantiveMeaning(text)) {
+    throw new TypeError(
+      `${label} must be substantive prose (at least four words, not a placeholder)`
+    );
+  }
+  return text;
+}
+function strings(value, label) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new TypeError(`${label} must be an array of strings`);
+  }
+  return [...value];
+}
+function sourceIds(value, label) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${label} must be an array`);
+  }
+  return value.map((item, index) => {
+    if (typeof item === "string") return item;
+    if (item !== null && typeof item === "object" && "id" in item) {
+      return string(item.id, `${label}[${index}].id`);
+    }
+    throw new TypeError(`${label}[${index}] must be an id or { id, locator }`);
+  });
+}
+function boolean(value, label) {
+  if (typeof value !== "boolean") {
+    throw new TypeError(`${label} must be a boolean`);
+  }
+  return value;
+}
+function status(value, label) {
+  if (value !== "draft" && value !== "in-review" && value !== "reviewed") {
+    throw new TypeError(`${label} must be draft, in-review, or reviewed`);
+  }
+  return value;
+}
+function alignment(value, label) {
+  const data = record(value, label);
+  if (data.kind === "general") {
+    return {
+      kind: "general",
+      rationale: string(data.rationale, `${label}.rationale`)
+    };
+  }
+  if (data.kind === "competency") {
+    return {
+      kind: "competency",
+      introducedByCompetency: string(
+        data.introducedByCompetency,
+        `${label}.introducedByCompetency`
+      ),
+      introducedInLesson: string(
+        data.introducedInLesson,
+        `${label}.introducedInLesson`
+      )
+    };
+  }
+  throw new TypeError(`${label}.kind must be competency or general`);
+}
+function sourceSpan(file, text, index) {
+  if (text === void 0 || index === void 0) return { file };
+  const before = text.slice(0, index);
+  const lines = before.split("\n");
+  return {
+    file,
+    line: lines.length,
+    column: (lines.at(-1)?.length ?? 0) + 1
+  };
+}
+function maskMarkdownLiterals(text) {
+  const mask = (value) => value.replace(/[^\n]/g, " ");
+  return text.replace(
+    /(^|\n)[ \t]{0,3}(`{3,}|~{3,})[^\n]*\n[\s\S]*?(?:\n[ \t]{0,3}\2[^\n]*(?=\n|$)|$)/g,
+    mask
+  ).replace(/^(?: {4}|\t).*$/gm, mask).replace(/(`+)(?!`)([^\n]*?)\1/g, mask);
+}
+function extractNotationReferences(text, file, kind) {
+  const references = [];
+  const searchable = maskMarkdownLiterals(text);
+  const patterns = [
+    [/\[\[\s*([^\][]+?)\s*\]\]/g, kind ?? "prose"],
+    [/\\explain\{([^{}]+)\}/g, kind ?? "math"]
+  ];
+  for (const [pattern, referenceKind] of patterns) {
+    for (const match of searchable.matchAll(pattern)) {
+      const key = (match[1] ?? "").trim();
+      if (parseEquationRef(key)) continue;
+      references.push({
+        key,
+        kind: referenceKind,
+        source: sourceSpan(file, text, match.index)
+      });
+    }
+  }
+  return references.sort(
+    (left, right) => (left.source.line ?? 0) - (right.source.line ?? 0) || (left.source.column ?? 0) - (right.source.column ?? 0) || left.key.localeCompare(right.key)
+  );
+}
+function jsonEntries(directory) {
+  return filesBelow(directory, [".json"]).map((path) => {
+    const entry = JSON.parse(readFileSync(path, "utf8"));
+    const filenameId = basename(path, ".json");
+    if (entry.id !== filenameId) {
+      throw new Error(
+        `${relative(REPOSITORY_ROOT, path)} declares id ${entry.id}; expected filename ${filenameId}.json`
+      );
+    }
+    return entry;
+  });
+}
+function docSlug(path) {
+  return relative(join(CONTENT_ROOT, "docs"), path).replace(/\\/g, "/");
+}
+function lessonCheckIds(lessonPath) {
+  const checksPath = lessonPath.replace(/\.mdx?$/, ".checks.yml");
+  return existsSync(checksPath) ? parseCheckList(readFileSync(checksPath, "utf8")) : [];
+}
+function lessonEntries(prerequisitesById) {
+  const lessons = [];
+  for (const path of filesBelow(join(CONTENT_ROOT, "docs"), [".md", ".mdx"])) {
+    const slug = docSlug(path);
+    if (!isLessonSlug(slug)) continue;
+    const { data, body } = parseDocument(path);
+    const teaches = data.teaches ?? [];
+    lessons.push({
+      id: lessonIdFromSlug(slug),
+      status: data.editorialStatus ?? "draft",
+      requires: deriveRequires(teaches, prerequisitesById),
+      teaches,
+      assessments: lessonCheckIds(path),
+      sources: deriveSources(body),
+      assumptions: data.assumptions ?? [],
+      body
+    });
+  }
+  return lessons;
+}
+async function loadCurriculumCatalog() {
+  const competencies = jsonEntries(
+    join(CONTENT_ROOT, "competencies")
+  );
+  const prerequisitesById = new Map(
+    competencies.map((competency) => [
+      competency.id,
+      competency.prerequisites ?? []
+    ])
+  );
+  return {
+    competencies,
+    lessons: lessonEntries(prerequisitesById),
+    assessments: jsonEntries(
+      join(CONTENT_ROOT, "assessments")
+    ),
+    sources: jsonEntries(join(CONTENT_ROOT, "sources")),
+    tracks: jsonEntries(join(CONTENT_ROOT, "tracks"))
+  };
+}
+function localDefinition(raw, file, index) {
+  const at = `${file} notation.local[${index}]`;
+  const data = record(raw, at);
+  const key = string(data.key, `${at}.key`);
+  const latex = string(data.latex, `${at}.latex`);
+  const meaning = meaningText(data.meaning, `${at}.meaning`);
+  const formula = optionalString(data.formula, `${at}.formula`);
+  const units = optionalString(data.units, `${at}.units`);
+  const definitionText = [meaning, formula].filter((value) => value !== void 0).join("\n");
+  return {
+    key,
+    notation: latex,
+    label: resolveLabel(key, optionalString(data.label, `${at}.label`)),
+    summary: meaning,
+    sources: sourceIds(data.sources, `${at}.sources`),
+    seeAlso: strings(data.seeAlso, `${at}.seeAlso`),
+    alignment: data.alignment === void 0 ? { kind: "general", rationale: "Lesson-local symbol." } : alignment(data.alignment, `${at}.alignment`),
+    references: extractNotationReferences(definitionText, file, "definition"),
+    source: { file },
+    ...formula === void 0 ? {} : { formula },
+    ...units === void 0 ? {} : { units }
+  };
+}
+function sharedNotationEntries() {
+  const directory = join(CONTENT_ROOT, "notation");
+  return filesBelow(directory, [".md"]).map((path) => {
+    const { file, data, body } = parseDocument(path);
+    const key = string(data.key, `${file} key`);
+    const filenameKey = basename(path, ".md");
+    if (key !== filenameKey) {
+      throw new Error(`${file} declares key ${key}; expected ${filenameKey}`);
+    }
+    const units = optionalString(data.units, `${file} units`);
+    const formula = optionalString(data.formula, `${file} formula`);
+    const meaning = meaningText(data.meaning, `${file} meaning`);
+    return {
+      key,
+      notation: string(data.latex, `${file} latex`),
+      label: resolveLabel(key, optionalString(data.label, `${file} label`)),
+      summary: meaning,
+      aliases: strings(data.aliases, `${file} aliases`),
+      domain: string(data.domain, `${file} domain`),
+      sources: sourceIds(data.sources, `${file} sources`),
+      seeAlso: strings(data.seeAlso, `${file} seeAlso`),
+      alignment: alignment(data.alignment, `${file} alignment`),
+      status: status(data.editorialStatus, `${file} editorialStatus`),
+      aiAssisted: boolean(data.aiAssisted, `${file} aiAssisted`),
+      body,
+      references: extractNotationReferences(body, file, void 0),
+      source: { file },
+      ...formula === void 0 ? {} : { formula },
+      ...units === void 0 ? {} : { units }
+    };
+  });
+}
+function notationLessonEntries() {
+  const lessons = [];
+  for (const path of filesBelow(join(CONTENT_ROOT, "docs"), [".md", ".mdx"])) {
+    const slug = docSlug(path);
+    if (!isLessonSlug(slug)) continue;
+    const { file, data, body } = parseDocument(path);
+    const notation = record(data.notation ?? {}, `${file} notation`);
+    const local = Array.isArray(notation.local) ? notation.local : [];
+    lessons.push({
+      lessonId: lessonIdFromSlug(slug),
+      status: status(data.editorialStatus, `${file} editorialStatus`),
+      localDefinitions: local.map(
+        (entry, index) => localDefinition(entry, file, index)
+      ),
+      references: extractNotationReferences(body, file, void 0),
+      body,
+      source: { file }
+    });
+  }
+  return lessons;
+}
+async function loadNotationRegistryInput() {
+  return {
+    sharedDefinitions: sharedNotationEntries(),
+    lessons: notationLessonEntries()
+  };
+}
+function loadNotationDefinitions() {
+  return filesBelow(join(CONTENT_ROOT, "notation"), [".md"]).map(
+    (path) => parseDocument(path).data
+  );
+}
+function loadSourceRecords() {
+  return jsonEntries(
+    join(CONTENT_ROOT, "sources")
+  );
+}
+function loadLessonChecks(lessonId) {
+  const slug = lessonId.replace(/\./g, "/");
+  for (const extension of [".mdx", ".md"]) {
+    const lessonPath = join(CONTENT_ROOT, "docs", `${slug}${extension}`);
+    if (existsSync(lessonPath)) return lessonCheckIds(lessonPath);
+  }
+  return [];
+}
+function specSources(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((entry) => {
+    if (typeof entry === "string") return { id: entry, hasLocator: false };
+    const record2 = entry ?? {};
+    return {
+      id: typeof record2.id === "string" ? record2.id : "",
+      hasLocator: typeof record2.locator === "string" && record2.locator.trim().length > 0
+    };
+  });
+}
+function loadNotationSpecs() {
+  const specs = [];
+  for (const path of filesBelow(join(CONTENT_ROOT, "notation"), [".md"])) {
+    const { file, data } = parseDocument(path);
+    const key = typeof data.key === "string" ? data.key : basename(path, ".md");
+    specs.push({
+      id: `shared:${key}`,
+      key,
+      scope: "shared",
+      file,
+      latex: typeof data.latex === "string" ? data.latex : "",
+      ...typeof data.units === "string" ? { units: data.units } : {},
+      dimensionless: data.dimensionless === true,
+      ...typeof data.formula === "string" ? { formula: data.formula } : {},
+      sources: specSources(data.sources)
+    });
+  }
+  for (const path of filesBelow(join(CONTENT_ROOT, "docs"), [".md", ".mdx"])) {
+    const slug = docSlug(path);
+    if (!isLessonSlug(slug)) continue;
+    const { file, data } = parseDocument(path);
+    const lessonId = lessonIdFromSlug(slug);
+    const local = data.notation?.local;
+    if (!Array.isArray(local)) continue;
+    for (const raw of local) {
+      const entry = raw ?? {};
+      const key = typeof entry.key === "string" ? entry.key : "";
+      specs.push({
+        id: `page:${lessonId}:${key}`,
+        key,
+        scope: "local",
+        lessonId,
+        file,
+        latex: typeof entry.latex === "string" ? entry.latex : "",
+        ...typeof entry.units === "string" ? { units: entry.units } : {},
+        dimensionless: entry.dimensionless === true,
+        ...typeof entry.formula === "string" ? { formula: entry.formula } : {},
+        sources: specSources(entry.sources)
+      });
+    }
+  }
+  return specs.sort((left, right) => left.id.localeCompare(right.id));
+}
+function notationSourceLocatorGaps() {
+  let bare = 0;
+  let total = 0;
+  for (const spec of loadNotationSpecs()) {
+    for (const source of spec.sources) {
+      total += 1;
+      if (!source.hasLocator) bare += 1;
+    }
+  }
+  return { bare, total };
+}
+export {
+  extractNotationReferences,
+  loadCurriculumCatalog,
+  loadLessonChecks,
+  loadNotationDefinitions,
+  loadNotationRegistryInput,
+  loadNotationSpecs,
+  loadSourceRecords,
+  notationSourceLocatorGaps
+};

package/dist/compiler/course-config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The shape `content/course.config.ts` must satisfy (Phase F).
+ *
+ * The engine never imports the course's config file; the wiring layer
+ * (`astro.config.mjs`, `scripts/*`, `src/content.config.ts`) imports the plain
+ * data value and passes it here, typed against `CourseConfig`. A second course
+ * supplies its own value of this shape.
+ */
+interface CourseSection {
+    /** Lesson-slug prefix, e.g. `bonds` for `bonds/yield-to-maturity`. */
+    readonly dir: string;
+    /** Sidebar group heading. */
+    readonly label: string;
+}
+interface CourseConventions {
+    /** Notation key a lesson's stated sign convention must resolve to. */
+    readonly signConventionKey: string;
+    /** Competency id that also counts as declaring the cash-flow perspective. */
+    readonly cashFlowPerspectiveCompetency: string;
+}
+interface CourseConfig {
+    readonly title: string;
+    readonly description: string;
+    /** Sidebar section groups, in order. */
+    readonly sections: readonly CourseSection[];
+    /** Namespaces used by competency / notation `domain` fields. */
+    readonly domains: readonly string[];
+    readonly conventions: CourseConventions;
+}
+
+export type { CourseConfig, CourseConventions, CourseSection };

package/dist/compiler/lesson-derivation.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure derivations for facts that used to be authored in lesson frontmatter
+ * (Phase C2). Nothing here reads the filesystem; `collections.ts` supplies the
+ * inputs and every consumer (the CLI validator, the Astro build, the Starlight
+ * layout, the tests) goes through that one loader.
+ *
+ * Authored per lesson after C2: `title`, `description`, `teaches`, `assumptions`,
+ * `editorialStatus`, `notation.local`. Everything below is derived:
+ *
+ * - `lessonId`      — the doc slug, `/` → `.` (`foundations/discount-factors`).
+ * - `requires`      — direct competency-graph prerequisites of `teaches`, minus
+ *                     what the lesson teaches itself. `teaches` is kept
+ *                     topologically ordered, so the intra-lesson subtraction is
+ *                     safe for the `lesson-order` check.
+ * - `sources`       — the `[@…]` ids in the body (the validator already
+ *                     required frontmatter `sources` to equal this set exactly).
+ * - `assessments`   — the id list in the colocated `<lesson>.checks.yml`.
+ * - `sidebar` order — per section, lessons in the order the tracks introduce
+ *                     them (a stable merge of every track's `lessons`).
+ *
+ * `notation.uses` is retired (D3): the completeness gate compiles every
+ * lesson's math against the page glyph table — `notation.local` plus the
+ * shared keys the body names with `[[key]]` / `\explain` — so an import list
+ * is redundant.
+ */
+/** `foundations/discount-factors` → `foundations.discount-factors`. */
+declare function lessonIdFromSlug(slug: string): string;
+/**
+ * A docs entry is a lesson when it lives in a section directory. The three
+ * top-level pages (`index`, `curriculum-map`, `glossary`) are not lessons; a
+ * future `<section>/index` page would not be one either.
+ */
+declare function isLessonSlug(slug: string): boolean;
+/**
+ * Direct prerequisites of everything the lesson `teaches`, minus the taught
+ * competencies themselves, sorted. Editorial "you should also know" extras that
+ * a few lessons used to list by hand are intentionally not reconstructed — a
+ * real dependency belongs in the competency graph, not per lesson.
+ */
+declare function deriveRequires(teaches: readonly string[], prerequisitesById: ReadonlyMap<string, readonly string[]>): string[];
+/**
+ * Source ids cited with `[@id]` (optionally `[@id; locator]`) in a lesson body,
+ * with fenced and inline code stripped first so a syntax example does not
+ * count. Mirrors the reader in `curriculum/validation.ts`.
+ */
+declare function citedSourceIds(body: string): Set<string>;
+/** Cited source ids as a sorted array — the derived frontmatter `sources`. */
+declare function deriveSources(body: string): string[];
+/**
+ * Parse a colocated `<lesson>.checks.yml`. The file is a flat YAML list of
+ * assessment ids (`- discount-factor-check`); `[]` and an empty file mean no
+ * assessments. Deliberately tiny — a colocated check *spec* with inline items
+ * is a later step; C2 only relocates the id list.
+ */
+declare function parseCheckList(text: string): string[];
+interface TrackLike {
+    readonly id: string;
+    readonly lessons: readonly string[];
+}
+/**
+ * One global lesson order from every track: start with the tracks sorted by id,
+ * then splice each later track's new lessons in right after the last lesson from
+ * that track already placed. Lessons shared between tracks keep their first
+ * track's position; a lesson in no track is absent (callers append leftovers).
+ */
+declare function mergeTrackOrder(tracks: readonly TrackLike[]): string[];
+/** One sidebar section group. Data lives in `content/course.config.ts` (Phase F). */
+interface SidebarSection {
+    readonly dir: string;
+    readonly label: string;
+}
+type SidebarGroup = {
+    readonly label: string;
+    readonly items: readonly string[];
+} | {
+    readonly label: string;
+    readonly items: readonly {
+        readonly label: string;
+        readonly link: string;
+    }[];
+};
+/**
+ * The Starlight `sidebar` config: one group per section, lessons ordered by the
+ * merged track order (ties broken by slug), then the static Reference group.
+ * Replaces seven `autogenerate` blocks that read an authored `sidebar.order`.
+ */
+declare function buildSidebar(tracks: readonly TrackLike[], lessonSlugs: readonly string[], sections: readonly SidebarSection[]): SidebarGroup[];
+
+export { type SidebarGroup, type SidebarSection, buildSidebar, citedSourceIds, deriveRequires, deriveSources, isLessonSlug, lessonIdFromSlug, mergeTrackOrder, parseCheckList };

package/dist/compiler/lesson-derivation.js

@@ -0,0 +1,91 @@
+function lessonIdFromSlug(slug) {
+  return slug.replace(/\.(md|mdx)$/, "").replace(/\//g, ".");
+}
+function isLessonSlug(slug) {
+  const clean = slug.replace(/\.(md|mdx)$/, "");
+  return clean.includes("/") && !clean.endsWith("/index");
+}
+function deriveRequires(teaches, prerequisitesById) {
+  const taught = new Set(teaches);
+  const required = /* @__PURE__ */ new Set();
+  for (const competencyId of teaches) {
+    for (const prerequisiteId of prerequisitesById.get(competencyId) ?? []) {
+      if (!taught.has(prerequisiteId)) required.add(prerequisiteId);
+    }
+  }
+  return [...required].sort();
+}
+function citedSourceIds(body) {
+  const withoutCode = body.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]*`/g, "");
+  const ids = /* @__PURE__ */ new Set();
+  for (const match of withoutCode.matchAll(
+    /\[@([a-z0-9][a-z0-9.-]*)(?:;[^\]]*)?\]/g
+  )) {
+    ids.add((match[1] ?? "").trim());
+  }
+  return ids;
+}
+function deriveSources(body) {
+  return [...citedSourceIds(body)].sort();
+}
+function parseCheckList(text) {
+  const ids = [];
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.replace(/#.*$/, "").trim();
+    if (line === "" || line === "[]") continue;
+    const match = line.match(/^-\s+(['"]?)([A-Za-z0-9][A-Za-z0-9._-]*)\1$/);
+    if (!match) {
+      throw new Error(
+        `checks.yml: expected "- <assessment-id>" lines, got ${JSON.stringify(rawLine)}`
+      );
+    }
+    ids.push(match[2]);
+  }
+  return ids;
+}
+function mergeTrackOrder(tracks) {
+  const ordered = [];
+  for (const track of [...tracks].sort((a, b) => a.id.localeCompare(b.id))) {
+    let anchor = -1;
+    for (const lessonId of track.lessons) {
+      const at = ordered.indexOf(lessonId);
+      if (at !== -1) {
+        anchor = at;
+        continue;
+      }
+      ordered.splice(anchor + 1, 0, lessonId);
+      anchor += 1;
+    }
+  }
+  return ordered;
+}
+function buildSidebar(tracks, lessonSlugs, sections) {
+  const rank = new Map(
+    mergeTrackOrder(tracks).map((lessonId, index) => [lessonId, index])
+  );
+  const positionOf = (slug) => rank.get(lessonIdFromSlug(slug)) ?? Number.POSITIVE_INFINITY;
+  const groups = sections.map(({ dir, label }) => ({
+    label,
+    items: lessonSlugs.filter((slug) => slug.startsWith(`${dir}/`)).sort(
+      (left, right) => positionOf(left) - positionOf(right) || left.localeCompare(right)
+    )
+  }));
+  groups.push({
+    label: "Reference",
+    items: [
+      { label: "Curriculum map", link: "/curriculum-map/" },
+      { label: "Notation glossary", link: "/glossary/" }
+    ]
+  });
+  return groups;
+}
+export {
+  buildSidebar,
+  citedSourceIds,
+  deriveRequires,
+  deriveSources,
+  isLessonSlug,
+  lessonIdFromSlug,
+  mergeTrackOrder,
+  parseCheckList
+};