explico 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# explico
+
+A build-time engine for **prerequisite-aware, notation-rigorous course
+content**. It turns a folder of MDX lessons and JSON collections into a
+validated static course whose every rendered symbol is explained and whose
+curriculum graph is checked.
+
+What it gives a course:
+
+- **One validated content model** — Zod schemas for lessons, competencies,
+  assessments, tracks, sources, and notation; a single loader from files to
+  typed data.
+- **A semantic notation system** — `[[key]]` binds a glyph to a define-once
+  meaning; a **completeness gate** fails the build if any identifier in any
+  rendered-math context (lesson body, `notation.formula`, `checks.yml`,
+  assessment prompts, component slots) does not resolve to a key. One meaning
+  per glyph per page, enforced corpus-wide.
+- **Inline citations** — `[@source-id; locator]` → numbered marker + generated
+  reference list, resolved against a schema-checked source collection.
+- **Equation identity** — `\label{eq:key}` gives a display equation a stable
+  key, an appearance-order number, an anchor, and cross-lesson `[[eq-key]]`
+  references.
+- **A KaTeX trust boundary** — build-time HTML + MathML; the trust callback
+  accepts exactly one validated `data-notation-key`. No runtime math, no CDN.
+- **A deterministic JSON manifest** — the MCP/LMS contract: lessons, notation,
+  competencies, sources, cross-refs, diagnostics, content hashes. Two compiles
+  of one content tree are byte-identical.
+- **Shared Astro/Starlight UI** — a hover-panel primitive shared by the
+  notation and citation layers, a glossary, a curriculum map, compact examples,
+  layout overrides.
+- **LMS / analytics / identity seams** — framework-free interfaces shipped as
+  no-ops; a host supplies real implementations without touching a component.
+- **A `content` CLI** — `status`, `context <lesson>`, `check <lesson>` (compiles
+  MDX → remark → KaTeX and fails loudly), `new lesson|term`.
+
+The prerequisite graph itself is authored by the lecturer or an AI; the engine
+validates it (DAG, ordering, coverage, orphans) rather than inferring it.
+
+## Install
+
+```bash
+pnpm add -D explico
+```
+
+Peer dependencies (the course provides them, pinned): `astro`,
+`@astrojs/starlight`, `@astrojs/react`, `@astrojs/markdown-remark`, `react`,
+`react-dom`, `katex`, `rehype-katex`, `remark-math`.
+
+## Use
+
+A course provides `content/` (the six collections + `content/domain/` +
+`content/course.config.ts`) and wires the engine in three places:
+
+```ts
+// src/content.config.ts — Astro's content entry
+export { collections } from 'explico/content-config';
+```
+
+```js
+// astro.config.mjs
+import { loadManifest } from 'explico/compiler/manifest.js';
+import remarkNotation from 'explico/reference/remark-notation.mjs';
+import remarkCitation from 'explico/reference/remark-citation.mjs';
+import { createNotationKatexOptions } from 'explico/reference/katex-options.mjs';
+import rehypeFailKatexErrors from 'explico/reference/rehype-fail-katex-errors.mjs';
+import { courseConfig } from './content/course.config.ts';
+
+const manifest = await loadManifest(courseConfig);
+// … starlight({ customCss: ['explico/styles/global.css'],
+//               components: { Footer: 'explico/components/starlight/LessonFooter.astro', … } })
+// … markdown.remarkPlugins / rehypePlugins from the manifest
+```
+
+```jsonc
+// package.json — the read-side CLI
+"scripts": { "validate:content": "tsx scripts/compile-manifest.ts" }
+```
+
+The reference course is
+[**credit-and-derivatives**](https://github.com/danieltuzes/credit-and-derivatives):
+discounting → bonds → credit/CDS → derivatives and options.
+
+## Layout
+
+| Path                                              | What                                                                                                                                        |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/compiler/`                                   | the one manifest compiler + the `content` CLI                                                                                               |
+| `src/reference/`                                  | notation registry, page-glyph resolver, remark/rehype adapters, the completeness gate, equation identity, consistency checks, KaTeX options |
+| `src/curriculum/`                                 | the curriculum-graph semantic validator                                                                                                     |
+| `src/components/`                                 | shared Astro/React UI (notation layer, citations, glossary, hover panel, examples, layout)                                                  |
+| `src/progress/`, `src/session/`, `src/analytics/` | the LMS / identity / analytics seams (no-op impls)                                                                                          |
+| `src/content-config.ts`                           | the Zod collection schemas (Astro re-exports them)                                                                                          |
+| `src/styles/`                                     | `global.css` (notation panel, keyed-equation flash, KaTeX)                                                                                  |
+
+## Build
+
+```bash
+pnpm build   # tsup → dist/ (ESM + .d.ts) for the .ts core; .astro / .tsx / .css
+             # and content-config.ts ship from src/; .mjs adapters are copied.
+```
+
+Published `exports` resolve to `dist/` for the typed core and to `src/` for the
+Astro components and styles (see `publishConfig` in `package.json`).
+
+## Status
+
+`0.1.x` — extracted from the `equations` project. API not yet stable; the
+license is undecided (`UNLICENSED` until chosen).

package/dist/analytics/AnalyticsEmitter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The analytics seam (Phase H1).
+ *
+ * `noopAnalyticsEmitter` is the only sink the static site ships — `emit` does
+ * nothing. Stateful components call it alongside the {@link ProgressRepository}
+ * so a future host can route interaction events somewhere real without touching
+ * a component. Framework-free: no React, Astro, content, or browser API, and no
+ * network call.
+ */
+interface AnalyticsEvent {
+    readonly name: string;
+    /** Epoch milliseconds, supplied by the caller so this stays side-effect-free. */
+    readonly at: number;
+    readonly props?: Readonly<Record<string, string | number | boolean | null>>;
+}
+interface AnalyticsEmitter {
+    emit(event: AnalyticsEvent): void;
+}
+/** The only sink in the static build. */
+declare const noopAnalyticsEmitter: AnalyticsEmitter;
+
+export { type AnalyticsEmitter, type AnalyticsEvent, noopAnalyticsEmitter };

package/dist/analytics/AnalyticsEmitter.js

@@ -0,0 +1,5 @@
+const noopAnalyticsEmitter = { emit: () => {
+} };
+export {
+  noopAnalyticsEmitter
+};

package/dist/compiler/cli.d.ts

@@ -0,0 +1,189 @@
+import { Manifest, ManifestLesson } from './manifest.js';
+import '../curriculum/validation.js';
+import '../reference/consistency.js';
+import './course-config.js';
+import './collections.js';
+import '../reference/types.js';
+import '../reference/lint-ignore.js';
+import '../reference/equations-validate.js';
+import '../reference/gate-math.js';
+import './lesson-derivation.js';
+
+/**
+ * The `content` CLI core (Phase G1).
+ *
+ * `scripts/content.ts` is a thin argv wrapper; every command's logic lives here
+ * as a pure-ish function that takes a compiled {@link Manifest} and returns a
+ * plain data object. The router is **read-only** — only `content new` touches
+ * the filesystem, and even then `scaffoldLesson` / `scaffoldTerm` only return
+ * the path + contents for the wrapper to write, and never overwrite.
+ *
+ * Design points the G1 gate pins:
+ *   - Every diagnostic carries a **stable code** (`<source>:<kind>`), never a
+ *     bare string, so an AI caller can branch on it.
+ *   - `--json` output is data only: no stack traces. The wrapper converts any
+ *     thrown {@link ContentCliError} (and any unexpected error) into
+ *     `{ code, message }`.
+ *   - `content context <lesson>` emits that lesson plus only what a drafter
+ *     needs — direct-prerequisite outcomes, the resolved notation bundle, cited
+ *     source metadata + locators, the section's domain signatures, and the
+ *     lesson's current diagnostics — and reports token counts against the doc
+ *     set + corpus so the size win is visible.
+ *   - `content check` compiles the lesson MDX → remark → KaTeX → HTML and fails
+ *     on any renderability error (unparseable MDX, KaTeX error, unresolved
+ *     notation, unknown `[[key]]`, unknown citation), on top of the manifest's
+ *     schema / ref / math / equation diagnostics for that lesson.
+ */
+
+type ContentCliCode = 'unknown-command' | 'usage' | 'unknown-lesson' | 'unknown-kind' | 'invalid-id' | 'exists' | 'not-a-lesson' | 'no-git';
+/** A user-facing failure with a stable code and no stack in `--json` output. */
+declare class ContentCliError extends Error {
+    readonly code: ContentCliCode;
+    constructor(code: ContentCliCode, message: string);
+}
+/** One normalized diagnostic. `code` is `<source>:<kind>` and always stable. */
+interface CliDiagnostic {
+    readonly code: string;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file?: string;
+    readonly line?: number;
+}
+/**
+ * Every manifest diagnostic that names this lesson (by id or file), normalized
+ * to {@link CliDiagnostic}. Corpus-wide checks (curriculum) are included only
+ * when their message mentions the lesson; per-file checks (notation, math,
+ * equations, consistency) are filtered by `file`.
+ */
+declare function lessonDiagnostics(manifest: Manifest, lesson: ManifestLesson): CliDiagnostic[];
+interface RenderResult {
+    readonly rendered: boolean;
+    readonly diagnostics: readonly CliDiagnostic[];
+}
+/**
+ * Compile one lesson body through the real remark → KaTeX → HTML pipeline and
+ * report the first failure as a coded diagnostic. Exported so a fixture body
+ * can be checked directly, without a manifest entry.
+ */
+declare function renderLesson(manifest: Manifest, input: {
+    body: string;
+    frontmatter: Record<string, unknown>;
+    path: string;
+}): Promise<RenderResult>;
+/** Rough token estimate — ~4 chars/token, the usual GPT-family heuristic. */
+declare function estimateTokens(text: string): number;
+interface TokenCounts {
+    /** Tokens in the serialized `content context` payload. */
+    readonly context: number;
+    /** `README.md` + `AGENTS.md` + `docs/architecture.md`. */
+    readonly docSet: number;
+    /** Every file under `content/`. */
+    readonly corpus: number;
+    /** `context / (docSet + corpus)`, rounded to 4 dp. */
+    readonly ratio: number;
+}
+/** Normalize `foundations/discount-factors` or the dotted id to the dotted id. */
+declare function normalizeLessonId(raw: string): string;
+declare function findLesson(manifest: Manifest, rawId: string): ManifestLesson;
+interface DomainFileSignatures {
+    readonly file: string;
+    readonly signatures: readonly string[];
+}
+interface StatusReport {
+    readonly counts: {
+        readonly lessons: number;
+        readonly competencies: number;
+        readonly assessments: number;
+        readonly sources: number;
+        readonly tracks: number;
+        readonly notationDefinitions: number;
+        readonly keyedEquations: number;
+    };
+    readonly draftDebt: {
+        readonly lessons: readonly string[];
+        readonly notation: readonly string[];
+    };
+    readonly orphans: readonly CliDiagnostic[];
+    readonly diagnostics: {
+        readonly errors: number;
+        readonly warnings: number;
+    };
+}
+declare function contentStatus(manifest: Manifest): StatusReport;
+interface ContextReport {
+    readonly lesson: {
+        readonly id: string;
+        readonly slug: string;
+        readonly file: string;
+        readonly title: string;
+        readonly description: string;
+        readonly status: string;
+        readonly teaches: readonly string[];
+        readonly requires: readonly string[];
+        readonly assumptions: readonly string[];
+        readonly notationLocal: unknown;
+        readonly body: string;
+    };
+    readonly taughtOutcomes: readonly {
+        id: string;
+        outcome: string;
+    }[];
+    readonly prerequisiteOutcomes: readonly {
+        id: string;
+        outcome: string;
+    }[];
+    readonly notation: readonly {
+        key: string;
+        latex: string;
+        meaning: string;
+        scope: string;
+        units?: string;
+        formula?: string;
+    }[];
+    readonly equations: readonly {
+        key: string;
+        number: string;
+    }[];
+    readonly sources: readonly {
+        id: string;
+        title: string;
+        type: string;
+        recordLocator?: string;
+        citedLocators: readonly string[];
+    }[];
+    readonly domainSignatures: readonly DomainFileSignatures[];
+    readonly diagnostics: readonly CliDiagnostic[];
+    readonly tokens: TokenCounts;
+}
+declare function contentContext(manifest: Manifest, rawId: string): ContextReport;
+interface CheckLessonResult {
+    readonly lesson: string;
+    readonly file: string;
+    readonly ok: boolean;
+    readonly rendered: boolean;
+    readonly diagnostics: readonly CliDiagnostic[];
+}
+interface CheckReport {
+    readonly ok: boolean;
+    readonly lessons: readonly CheckLessonResult[];
+}
+/** `.mdx` / `.checks.yml` paths that differ from `HEAD`, tracked or not. */
+declare function changedLessonIds(): string[];
+declare function contentCheck(manifest: Manifest, options: {
+    lesson?: string;
+    changed?: boolean;
+}): Promise<CheckReport>;
+interface Scaffold {
+    /** Repo-relative path the wrapper writes. */
+    readonly path: string;
+    readonly contents: string;
+    /** Companion files (e.g. a lesson's `checks.yml`), also non-overwriting. */
+    readonly companions: readonly {
+        path: string;
+        contents: string;
+    }[];
+}
+declare function scaffoldLesson(rawId: string): Scaffold;
+declare function scaffoldTerm(rawKey: string): Scaffold;
+
+export { type CheckLessonResult, type CheckReport, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DomainFileSignatures, type RenderResult, type Scaffold, type StatusReport, type TokenCounts, changedLessonIds, contentCheck, contentContext, contentStatus, estimateTokens, findLesson, lessonDiagnostics, normalizeLessonId, renderLesson, scaffoldLesson, scaffoldTerm };