explico 0.1.0

package/dist/reference/gate-math.d.ts

@@ -0,0 +1,41 @@
+import { NotationRegistryInput } from './types.js';
+
+interface MathGateDiagnostic {
+    readonly context: 'body' | 'formula' | 'assessment';
+    /**
+     * Body / component-slot math blocks the build (the render path needs every
+     * glyph resolved for the KaTeX trust callback). `formula` and `assessment`
+     * math enter as warnings (Tier 3) and are promoted once existing content is
+     * brought into line — they surface pre-existing ambiguities that are a
+     * separate reviewed content pass (D6/D13/D14), not a D3 codemod.
+     */
+    readonly severity: 'error' | 'warning';
+    readonly file: string;
+    readonly line?: number;
+    readonly token?: string;
+    readonly message: string;
+}
+interface AssessmentItemLike {
+    readonly id?: string;
+    readonly prompt?: string;
+    readonly explanation?: string;
+}
+interface AssessmentLike {
+    readonly id: string;
+    readonly items?: readonly AssessmentItemLike[];
+}
+interface LessonAssessmentLink {
+    readonly lessonId: string;
+    readonly assessmentIds: readonly string[];
+}
+/**
+ * Resolve every rendered-math context against the page glyph table. Returns one
+ * diagnostic per unresolved token; an empty array means the gate passed.
+ */
+declare function gateContentMath(input: {
+    readonly notationInput: NotationRegistryInput;
+    readonly assessments: readonly AssessmentLike[];
+    readonly lessonAssessments: readonly LessonAssessmentLink[];
+}): MathGateDiagnostic[];
+
+export { type MathGateDiagnostic, gateContentMath };

package/dist/reference/gate-math.js

@@ -0,0 +1,151 @@
+import { resolveMathGlyphs, GlyphResolutionError } from "./math-glyphs.mjs";
+import { stripEquationLabels } from "./equations.mjs";
+const SEVERITY = {
+  body: "error",
+  formula: "warning",
+  assessment: "warning"
+};
+const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
+const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
+const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g;
+const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
+function stripCode(text) {
+  return text.replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, " ")).replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, " "));
+}
+function lineOf(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+function mathSpans(body) {
+  const searchable = stripCode(body);
+  const spans = [];
+  for (const pattern of [DISPLAY_MATH, INLINE_MATH]) {
+    pattern.lastIndex = 0;
+    let match;
+    while (match = pattern.exec(searchable)) {
+      spans.push({
+        // D7: `\label{eq:…}` is an identity marker, not math KaTeX parses.
+        latex: stripEquationLabels(match[1] ?? ""),
+        line: lineOf(body, match.index)
+      });
+    }
+  }
+  return spans;
+}
+function pageScope(lesson, sharedByKey) {
+  const local = lesson.localDefinitions.map((definition) => ({
+    key: definition.key,
+    notation: definition.notation
+  }));
+  const localKeys = new Set(local.map((entry) => entry.key));
+  const referenced = /* @__PURE__ */ new Set();
+  for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
+    for (const match of lesson.body.matchAll(pattern)) referenced.add(match[1]);
+  }
+  const scope = [...local];
+  for (const key of referenced) {
+    if (localKeys.has(key)) continue;
+    const shared = sharedByKey.get(key);
+    if (shared) scope.push({ key: shared.key, notation: shared.notation });
+  }
+  return scope;
+}
+function resolveInto(latex, scope, context, file, line, fix, out) {
+  let result;
+  try {
+    result = resolveMathGlyphs(latex, [...scope]);
+  } catch (error) {
+    out.push({
+      context,
+      severity: SEVERITY[context],
+      file,
+      line,
+      message: error instanceof GlyphResolutionError ? error.message : `Could not compile math ${JSON.stringify(latex)}: ${error instanceof Error ? error.message : String(error)}`
+    });
+    return;
+  }
+  for (const { token } of result.unresolved) {
+    out.push({
+      context,
+      severity: SEVERITY[context],
+      file,
+      line,
+      token,
+      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math. ${fix}`
+    });
+  }
+}
+const BODY_FIX = "Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.";
+const FORMULA_FIX = "Every right-hand-side variable of a notation.local formula must resolve to the entry key, another page symbol, or the base library.";
+const ASSESSMENT_FIX = "Introduce the symbol in the owning lesson's prose with [[key]], or wrap it in \\explain{key}{latex}.";
+function gateContentMath(input) {
+  const { notationInput, assessments, lessonAssessments } = input;
+  const sharedByKey = new Map(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      definition
+    ])
+  );
+  const lessonById = new Map(
+    notationInput.lessons.map((lesson) => [lesson.lessonId, lesson])
+  );
+  const assessmentById = new Map(
+    assessments.map((assessment) => [assessment.id, assessment])
+  );
+  const diagnostics = [];
+  for (const lesson of notationInput.lessons) {
+    const scope = pageScope(lesson, sharedByKey);
+    const file = lesson.source.file;
+    for (const span of mathSpans(lesson.body)) {
+      resolveInto(
+        span.latex,
+        scope,
+        "body",
+        file,
+        span.line,
+        BODY_FIX,
+        diagnostics
+      );
+    }
+    for (const definition of lesson.localDefinitions) {
+      if (!definition.formula) continue;
+      resolveInto(
+        definition.formula,
+        scope,
+        "formula",
+        file,
+        void 0,
+        FORMULA_FIX,
+        diagnostics
+      );
+    }
+  }
+  for (const link of lessonAssessments) {
+    const lesson = lessonById.get(link.lessonId);
+    if (!lesson) continue;
+    const scope = pageScope(lesson, sharedByKey);
+    for (const assessmentId of link.assessmentIds) {
+      const assessment = assessmentById.get(assessmentId);
+      if (!assessment?.items) continue;
+      for (const item of assessment.items) {
+        for (const field of [item.prompt, item.explanation]) {
+          if (typeof field !== "string") continue;
+          for (const span of mathSpans(field)) {
+            resolveInto(
+              span.latex,
+              scope,
+              "assessment",
+              `${assessmentId} (${item.id ?? "?"})`,
+              void 0,
+              ASSESSMENT_FIX,
+              diagnostics
+            );
+          }
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
+export {
+  gateContentMath
+};

package/dist/reference/katex-options.mjs

@@ -0,0 +1,91 @@
+import { NOTATION_KEY_PATTERN } from './remark-notation.mjs';
+
+export const EXPLAIN_MACRO = String.raw`\htmlData{notation-key=#1}{#2}`;
+
+// Interactive labs render developer-authored math templates that carry two
+// kinds of inert marker: `\explain` for a notation key (as above) and `\slot`
+// for a numeric hole the island rewrites at runtime. Both compile to a single
+// `data-*` attribute and nothing else.
+export const SLOT_MACRO = String.raw`\htmlData{lab-slot=#1}{#2}`;
+const LAB_SLOT_PATTERN = /^[a-z][a-z0-9]*$/;
+
+/**
+ * KaTeX trust callback that permits exactly one inert marker attribute:
+ * `data-notation-key` (a registry key) or `data-lab-slot` (a lab value hole).
+ * Links, styles, classes, IDs, protocols, and every other data attribute stay
+ * untrusted. Key existence is checked by the remark adapter, the lab-math
+ * renderer, and the workspace validator before KaTeX runs.
+ */
+export function trustNotationMarker(context) {
+  if (context?.command !== '\\htmlData') return false;
+  if (!context.attributes || typeof context.attributes !== 'object') {
+    return false;
+  }
+
+  const entries = Object.entries(context.attributes);
+  if (entries.length !== 1) return false;
+  const [name, value] = entries[0];
+  if (typeof value !== 'string') return false;
+
+  if (name === 'data-notation-key') return NOTATION_KEY_PATTERN.test(value);
+  if (name === 'data-lab-slot') return LAB_SLOT_PATTERN.test(value);
+  return false;
+}
+
+function strictNotation(errorCode) {
+  // The trusted macros intentionally use KaTeX's HTML extension. Keep normal
+  // strict-mode warnings for all other non-LaTeX constructs.
+  return errorCode === 'htmlExtension' ? 'ignore' : 'warn';
+}
+
+export const notationKatexOptions = Object.freeze({
+  output: 'htmlAndMathml',
+  throwOnError: true,
+  strict: strictNotation,
+  trust: trustNotationMarker,
+  macros: Object.freeze({
+    '\\explain': EXPLAIN_MACRO,
+    '\\slot': SLOT_MACRO,
+  }),
+});
+
+/**
+ * Add non-security KaTeX settings while keeping the notation macros and trust
+ * boundary non-overridable.
+ */
+export function createNotationKatexOptions(overrides = {}) {
+  if ('output' in overrides) {
+    throw new TypeError(
+      'The notation KaTeX output mode cannot be overridden; HTML and MathML are required.',
+    );
+  }
+  if ('throwOnError' in overrides) {
+    throw new TypeError(
+      'The notation KaTeX error mode cannot be overridden; rendering errors must fail the build.',
+    );
+  }
+  if ('trust' in overrides) {
+    throw new TypeError(
+      'The notation KaTeX trust callback cannot be overridden.',
+    );
+  }
+  if (overrides.macros?.['\\explain'] !== undefined) {
+    throw new TypeError('The \\explain KaTeX macro cannot be overridden.');
+  }
+  if (overrides.macros?.['\\slot'] !== undefined) {
+    throw new TypeError('The \\slot KaTeX macro cannot be overridden.');
+  }
+
+  return {
+    ...notationKatexOptions,
+    ...overrides,
+    output: notationKatexOptions.output,
+    throwOnError: notationKatexOptions.throwOnError,
+    trust: trustNotationMarker,
+    macros: {
+      ...(overrides.macros ?? {}),
+      '\\explain': EXPLAIN_MACRO,
+      '\\slot': SLOT_MACRO,
+    },
+  };
+}

package/dist/reference/lab-math-scope.d.ts

@@ -0,0 +1,21 @@
+import { LabMathScopeDefinition } from './render-lab-math.js';
+
+interface LessonNotationFrontmatter {
+    readonly local?: ReadonlyArray<{
+        readonly key: string;
+        readonly latex: string;
+    }>;
+}
+/**
+ * The notation a lab's math template may reference: exactly the same page glyph
+ * scope the remark adapter gives lesson `$$` math — this page's
+ * `notation.local` plus the shared entries it names in the body with `[[key]]`
+ * (or `\explain{key}{…}`). No transitive closure, so island math cannot
+ * quietly reach beyond what the lesson introduces.
+ *
+ * Shared definitions are read from the one compiler manifest (Phase D5); this
+ * module never re-reads the content tree.
+ */
+declare function labMathScope(notation: LessonNotationFrontmatter | undefined, body?: string): Promise<LabMathScopeDefinition[]>;
+
+export { labMathScope };

package/dist/reference/lab-math-scope.js

@@ -0,0 +1,28 @@
+import { loadManifest } from "../compiler/manifest";
+const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
+const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;
+async function labMathScope(notation, body = "") {
+  const local = notation?.local ?? [];
+  const scope = local.map((definition) => ({
+    key: definition.key,
+    notation: definition.latex
+  }));
+  const referenced = /* @__PURE__ */ new Set();
+  for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
+    for (const match of body.matchAll(pattern)) referenced.add(match[1]);
+  }
+  const localKeys = new Set(local.map((definition) => definition.key));
+  const manifest = await loadManifest();
+  const sharedByKey = new Map(
+    manifest.notation.definitions.filter((definition) => definition.kind === "shared").map((definition) => [definition.key, definition])
+  );
+  for (const key of referenced) {
+    if (localKeys.has(key)) continue;
+    const shared = sharedByKey.get(key);
+    if (shared) scope.push({ key: shared.key, notation: shared.notation });
+  }
+  return scope;
+}
+export {
+  labMathScope
+};

package/dist/reference/label.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Display label for a notation entry (Phase C1b, replacing the authored
+ * `title`). Default = the key humanized: split on `-`/`.`, upper-case known
+ * acronyms, capitalize the first word. An entry may still set an explicit
+ * `label` where the humanized key would read wrong.
+ */
+declare function humanizeKey(key: string): string;
+/** The label an entry resolves to: an explicit `label`, else the humanized key. */
+declare function resolveLabel(key: string, label?: string): string;
+
+export { humanizeKey, resolveLabel };

package/dist/reference/label.js

@@ -0,0 +1,38 @@
+const ACRONYMS = /* @__PURE__ */ new Map([
+  ["cds", "CDS"],
+  ["cdx", "CDX"],
+  ["isda", "ISDA"],
+  ["pv", "PV"],
+  ["npv", "NPV"],
+  ["lgd", "LGD"],
+  ["ytm", "YTM"],
+  ["rop", "RoP"]
+]);
+const COMPOUNDS = /* @__PURE__ */ new Set([
+  "risk-neutral",
+  "real-world",
+  "price-yield",
+  "market-standard",
+  "risk-free"
+]);
+function humanizeKey(key) {
+  const words = key.split(/[-.]/).filter(Boolean);
+  const cased = words.map((word, index) => {
+    const acronym = ACRONYMS.get(word);
+    if (acronym) return acronym;
+    return index === 0 ? word.charAt(0).toUpperCase() + word.slice(1) : word;
+  });
+  let out = cased[0] ?? "";
+  for (let i = 1; i < cased.length; i += 1) {
+    const joiner = COMPOUNDS.has(`${words[i - 1]}-${words[i]}`) ? "-" : " ";
+    out += joiner + cased[i];
+  }
+  return out;
+}
+function resolveLabel(key, label) {
+  return label && label.trim().length > 0 ? label : humanizeKey(key);
+}
+export {
+  humanizeKey,
+  resolveLabel
+};

package/dist/reference/lint-ignore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The one reviewed suppression registry for consistency checks (Step D6).
+ *
+ * A corpus-level finding (a glyph that resolves to more than one meaning, a
+ * unit outside the controlled vocabulary, …) is a violation unless it is
+ * acknowledged here, in `lint-ignore.yml` at the repository root, with a
+ * reason. Silent suppression is disallowed: there is no per-file pragma and no
+ * inline comment that turns a check off.
+ *
+ * File grammar — one acknowledgement per line:
+ *
+ *     <check-code>[:<detail>] — <reason>
+ *
+ * `<detail>` is optional and narrows the acknowledgement (a glyph for
+ * `glyph-unique-in-corpus`, a notation key otherwise); with no detail the line
+ * acknowledges every finding of that code. The separator is an em dash (`—`),
+ * or `--` / ` - ` in ASCII. Blank lines and `#` comments are ignored.
+ */
+interface LintIgnoreEntry {
+    readonly code: string;
+    readonly detail?: string;
+    readonly reason: string;
+}
+interface LintIgnore {
+    readonly entries: readonly LintIgnoreEntry[];
+    /** True when a `<code>` (optionally `<code>:<detail>`) finding is acknowledged. */
+    matches(code: string, detail?: string): boolean;
+}
+declare function parseLintIgnore(text: string): LintIgnoreEntry[];
+declare function loadLintIgnore(): LintIgnore;
+
+export { type LintIgnore, type LintIgnoreEntry, loadLintIgnore, parseLintIgnore };

package/dist/reference/lint-ignore.js

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const IGNORE_PATH = join(process.cwd(), "lint-ignore.yml");
+const LINE = /^-\s*([a-z0-9-]+)(?::([^\s—-][^—-]*?))?\s*(?:—|--|\s-\s)\s*(.+?)\s*$/;
+function parseLintIgnore(text) {
+  const entries = [];
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.replace(/#.*$/, "").trim();
+    if (line === "" || line === "ignore:" || line === "[]") continue;
+    const match = LINE.exec(line);
+    if (!match) {
+      throw new Error(
+        `lint-ignore.yml: expected "- <code>[:<detail>] \u2014 <reason>", got ${JSON.stringify(rawLine)}`
+      );
+    }
+    const [, code, detail, reason] = match;
+    entries.push({
+      code,
+      ...detail && detail.trim() ? { detail: detail.trim() } : {},
+      reason: reason.trim()
+    });
+  }
+  return entries;
+}
+function loadLintIgnore() {
+  const entries = existsSync(IGNORE_PATH) ? parseLintIgnore(readFileSync(IGNORE_PATH, "utf8")) : [];
+  return {
+    entries,
+    matches(code, detail) {
+      return entries.some(
+        (entry) => entry.code === code && (entry.detail === void 0 || entry.detail === detail)
+      );
+    }
+  };
+}
+export {
+  loadLintIgnore,
+  parseLintIgnore
+};