explico 0.1.0

package/src/reference/consistency.ts

@@ -0,0 +1,375 @@
+/**
+ * Corpus consistency checks (Step D6) — the Tier 1–2 checks from the cleanup
+ * plan's "Enforced checks" section that no earlier step covers.
+ *
+ * Every check here enters as a **Tier-3 warning**: `pnpm validate:content`
+ * surfaces the counts, `manifest.diagnostics.consistency` records the detail,
+ * and `resolution/consistency-report.json` is the committed, diff-checkable
+ * snapshot. Nothing here changes content — each finding is an open item for a
+ * separate human-quantitative-reviewed pass. A finding is silenced only by a
+ * reviewed line in `lint-ignore.yml` (see `./lint-ignore`).
+ *
+ *   (a) glyph-unique-in-corpus       one rendered glyph → one meaning corpus-wide
+ *   (b) notation-units / units-vocab  every entry has units or `dimensionless`,
+ *                                     unit strings drawn from a controlled vocab
+ *   (c) convention-single-definition  a sign / cash-flow-perspective convention a
+ *                                     lesson uses resolves to one declaration
+ *   (e) numerals-tagged              numerals in `$…$` / result tables are tagged
+ *                                     to a `src/domain/` call or a source locator
+ *   (f) weak-local                   a `notation.local` symbol used only in its
+ *                                     own defining equation and prose
+ *   (g) notation-source-locator      every notation `sources` entry has a locator
+ *
+ * Check (d) — the committed per-lesson resolution report — lives in
+ * `src/content/resolution-report.ts`.
+ */
+
+import type { CourseConventions } from '../compiler/course-config';
+import type { CurriculumCatalog } from '../curriculum/validation';
+import type { NotationSpec } from '../compiler/collections';
+import type { LintIgnore } from './lint-ignore';
+import { offVocabularyTokens } from './units-vocab';
+import type {
+  NotationDefinitionRecord,
+  NotationRegistry,
+  NotationRegistryInput,
+} from './types';
+
+export type ConsistencyCode =
+  | 'glyph-unique-in-corpus'
+  | 'notation-units'
+  | 'units-vocab'
+  | 'convention-single-definition'
+  | 'numerals-tagged'
+  | 'weak-local'
+  | 'notation-source-locator';
+
+export interface ConsistencyDiagnostic {
+  readonly code: ConsistencyCode;
+  /** Tier 3 — every finding here is a warning until content is brought clean. */
+  readonly severity: 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+  readonly glyph?: string;
+  /** For the aggregate numeral check. */
+  readonly count?: number;
+}
+
+export interface ConsistencyInput {
+  readonly registry: NotationRegistry;
+  readonly notationInput: NotationRegistryInput;
+  readonly specs: readonly NotationSpec[];
+  readonly catalog: CurriculumCatalog;
+  readonly lintIgnore: LintIgnore;
+  /** Convention keys this course anchors on (from `content/course.config.ts`). */
+  readonly conventions: CourseConventions;
+}
+
+const CONVENTION_RE =
+  /\bsign convention\b|\bcash-flow perspective\b|\bholder(?:'s)?(?:\s+\w+){0,2}\s+perspective\b|\bfrom (?:a|one|the|its)(?:\s+\w+){0,3}\s+perspective\b|\breverses? every sign\b|\bpositive (?:means|amounts?)\b/i;
+
+// --- shared text helpers ------------------------------------------------
+
+function stripCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, ' '))
+    .replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, ' '));
+}
+
+interface MathSpan {
+  readonly latex: string;
+}
+
+function mathSpans(body: string): MathSpan[] {
+  const searchable = stripCode(body);
+  const spans: MathSpan[] = [];
+  for (const match of searchable.matchAll(/\$\$([\s\S]+?)\$\$/g)) {
+    spans.push({ latex: match[1] ?? '' });
+  }
+  for (const match of searchable
+    .replace(/\$\$([\s\S]+?)\$\$/g, (block) => block.replace(/[^\n]/g, ' '))
+    .matchAll(/(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g)) {
+    spans.push({ latex: match[1] ?? '' });
+  }
+  return spans;
+}
+
+function tableRows(body: string): string[] {
+  const rows: string[] = [];
+  for (const line of stripCode(body).split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|') || !trimmed.slice(1).includes('|')) continue;
+    if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) continue;
+    rows.push(line);
+  }
+  return rows;
+}
+
+const NUMERAL_RE = /(?<![\w.])-?\d+(?:\.\d+)?/g;
+
+function numeralCount(text: string): number {
+  return (text.replace(/\\[a-zA-Z]+/g, ' ').match(NUMERAL_RE) ?? []).length;
+}
+
+/** A math span / table row is "tagged" when it carries a citation or a domain marker. */
+function isTagged(text: string): boolean {
+  return /\[@[a-z0-9]/i.test(text) || /<!--\s*domain:/i.test(text);
+}
+
+// --- glyph regex for weak-local --------------------------------------
+
+function glyphMatcher(latex: string): RegExp | undefined {
+  const trimmed = latex.trim();
+  if (trimmed === '') return undefined;
+  if (/^[A-Za-z]$/.test(trimmed)) {
+    return new RegExp(`(?<![A-Za-z\\\\])${trimmed}(?![A-Za-z])`);
+  }
+  const escaped = trimmed.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(
+    /[A-Za-z]$/.test(trimmed) ? `${escaped}(?![A-Za-z])` : escaped,
+  );
+}
+
+// --- checks ----------------------------------------------------------
+
+function checkGlyphUniqueness(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const byId = new Map<string, NotationDefinitionRecord>(
+    input.registry.definitions.map((definition) => [definition.id, definition]),
+  );
+  // glyph -> key -> lessons that bind it
+  const glyphs = new Map<string, Map<string, Set<string>>>();
+  const record = (glyph: string, key: string, lessonId: string): void => {
+    const trimmed = glyph.trim();
+    if (trimmed === '') return;
+    const keys = glyphs.get(trimmed) ?? new Map<string, Set<string>>();
+    const lessons = keys.get(key) ?? new Set<string>();
+    lessons.add(lessonId);
+    keys.set(key, lessons);
+    glyphs.set(trimmed, keys);
+  };
+
+  for (const definition of input.registry.definitions) {
+    if (definition.kind === 'local') {
+      record(definition.notation, definition.key, definition.lessonId);
+    }
+  }
+  for (const bundle of input.registry.bundles) {
+    for (const binding of bundle.bindings) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) record(definition.notation, binding.key, bundle.lessonId);
+    }
+  }
+
+  for (const [glyph, keys] of [...glyphs].sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    if (keys.size < 2) continue;
+    if (input.lintIgnore.matches('glyph-unique-in-corpus', glyph)) continue;
+    const detail = [...keys]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, lessons]) => `${key} (${[...lessons].sort().join(', ')})`)
+      .join('; ');
+    out.push({
+      code: 'glyph-unique-in-corpus',
+      severity: 'warning',
+      glyph,
+      message: `glyph ${JSON.stringify(glyph)} resolves to ${keys.size} meanings across the corpus: ${detail}`,
+    });
+  }
+}
+
+function checkNotationUnits(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  for (const spec of input.specs) {
+    if (spec.units === undefined && !spec.dimensionless) {
+      if (input.lintIgnore.matches('notation-units', spec.key)) continue;
+      out.push({
+        code: 'notation-units',
+        severity: 'warning',
+        key: spec.key,
+        file: spec.file,
+        ...(spec.lessonId ? { lessonId: spec.lessonId } : {}),
+        message: `notation ${spec.key} (${spec.scope}) declares neither units nor dimensionless`,
+      });
+      continue;
+    }
+    if (spec.units === undefined) continue;
+    const offVocab = offVocabularyTokens(spec.units);
+    if (offVocab.length === 0) continue;
+    if (input.lintIgnore.matches('units-vocab', spec.key)) continue;
+    out.push({
+      code: 'units-vocab',
+      severity: 'warning',
+      key: spec.key,
+      file: spec.file,
+      ...(spec.lessonId ? { lessonId: spec.lessonId } : {}),
+      message: `notation ${spec.key} units ${JSON.stringify(spec.units)} use non-vocabulary token(s): ${offVocab.join(', ')}`,
+    });
+  }
+}
+
+function checkConventionSingleDefinition(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const lessonById = new Map(
+    input.catalog.lessons.map((lesson) => [lesson.id, lesson]),
+  );
+  for (const lesson of input.notationInput.lessons) {
+    const body = lesson.body;
+    if (!CONVENTION_RE.test(body)) continue;
+    const meta = lessonById.get(lesson.lessonId);
+    const { signConventionKey, cashFlowPerspectiveCompetency } =
+      input.conventions;
+    const anchoredByCompetency = [
+      ...(meta?.teaches ?? []),
+      ...(meta?.requires ?? []),
+    ].includes(cashFlowPerspectiveCompetency);
+    const anchoredByTerm = new RegExp(
+      `\\[\\[\\s*${signConventionKey}\\s*\\]\\]`,
+    ).test(body);
+    if (anchoredByCompetency || anchoredByTerm) continue;
+    if (
+      input.lintIgnore.matches('convention-single-definition', lesson.lessonId)
+    ) {
+      continue;
+    }
+    out.push({
+      code: 'convention-single-definition',
+      severity: 'warning',
+      lessonId: lesson.lessonId,
+      file: lesson.source.file,
+      message: `${lesson.lessonId} states a sign / cash-flow-perspective convention in prose but does not resolve it to a single declaration ([[${signConventionKey}]] or ${cashFlowPerspectiveCompetency})`,
+    });
+  }
+}
+
+function checkNumeralsTagged(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  for (const lesson of input.notationInput.lessons) {
+    if (input.lintIgnore.matches('numerals-tagged', lesson.lessonId)) continue;
+    let math = 0;
+    for (const span of mathSpans(lesson.body)) {
+      if (isTagged(span.latex)) continue;
+      math += numeralCount(span.latex);
+    }
+    let table = 0;
+    for (const row of tableRows(lesson.body)) {
+      if (isTagged(row)) continue;
+      table += numeralCount(row.replace(/\$[^$\n]*\$/g, ' '));
+    }
+    const count = math + table;
+    if (count === 0) continue;
+    out.push({
+      code: 'numerals-tagged',
+      severity: 'warning',
+      lessonId: lesson.lessonId,
+      file: lesson.source.file,
+      count,
+      message: `${lesson.lessonId}: ${count} numeral(s) in $…$ / result tables (${math} in math, ${table} in tables) are not tagged to a src/domain/ call or a source locator`,
+    });
+  }
+}
+
+function checkWeakLocal(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  for (const lesson of input.notationInput.lessons) {
+    const spans = mathSpans(lesson.body).map((span) => span.latex);
+    for (const definition of lesson.localDefinitions) {
+      if (input.lintIgnore.matches('weak-local', definition.key)) continue;
+      const matcher = glyphMatcher(definition.notation);
+      if (!matcher) continue;
+      const uses = spans.filter((latex) => matcher.test(latex)).length;
+      if (uses > 1) continue;
+      out.push({
+        code: 'weak-local',
+        severity: 'warning',
+        lessonId: lesson.lessonId,
+        file: lesson.source.file,
+        key: definition.key,
+        count: uses,
+        message: `${lesson.lessonId}: local symbol ${definition.key} (${definition.notation}) appears in ${uses} body equation(s); referenced only in its defining equation and prose — inline candidate`,
+      });
+    }
+  }
+}
+
+function checkNotationSourceLocator(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  for (const spec of input.specs) {
+    for (const [index, source] of spec.sources.entries()) {
+      if (source.hasLocator) continue;
+      if (input.lintIgnore.matches('notation-source-locator', spec.key)) break;
+      out.push({
+        code: 'notation-source-locator',
+        severity: 'warning',
+        key: spec.key,
+        file: spec.file,
+        ...(spec.lessonId ? { lessonId: spec.lessonId } : {}),
+        message: `notation ${spec.key} sources[${index}] (${source.id || 'bare id'}) has no non-empty locator`,
+      });
+    }
+  }
+}
+
+const CHECKS: ((
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+) => void)[] = [
+  checkGlyphUniqueness,
+  checkNotationUnits,
+  checkConventionSingleDefinition,
+  checkNumeralsTagged,
+  checkWeakLocal,
+  checkNotationSourceLocator,
+];
+
+/**
+ * Run every consistency check. The result is sorted deterministically (code,
+ * then lesson / key / glyph, then message) so it is byte-stable in the manifest
+ * and the committed report.
+ */
+export function runConsistencyChecks(
+  input: ConsistencyInput,
+): ConsistencyDiagnostic[] {
+  const diagnostics: ConsistencyDiagnostic[] = [];
+  for (const check of CHECKS) check(input, diagnostics);
+  return diagnostics.sort(
+    (left, right) =>
+      left.code.localeCompare(right.code) ||
+      (left.lessonId ?? '').localeCompare(right.lessonId ?? '') ||
+      (left.key ?? '').localeCompare(right.key ?? '') ||
+      (left.glyph ?? '').localeCompare(right.glyph ?? '') ||
+      left.message.localeCompare(right.message),
+  );
+}
+
+/** `{ code: count }` for the CLI summary and the report header. */
+export function consistencyCounts(
+  diagnostics: readonly ConsistencyDiagnostic[],
+): Record<ConsistencyCode, number> {
+  const counts = {
+    'glyph-unique-in-corpus': 0,
+    'notation-units': 0,
+    'units-vocab': 0,
+    'convention-single-definition': 0,
+    'numerals-tagged': 0,
+    'weak-local': 0,
+    'notation-source-locator': 0,
+  } satisfies Record<ConsistencyCode, number>;
+  for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
+  return counts;
+}

package/src/reference/curriculum-alignment.ts

@@ -0,0 +1,228 @@
+import type { CurriculumCatalog } from '../curriculum/validation';
+import { compareDiagnostics } from './references';
+import type {
+  NotationDefinitionRecord,
+  NotationDiagnostic,
+  NotationRegistry,
+} from './types';
+
+interface EditorialCompetency {
+  readonly id: string;
+  readonly editorialStatus?: 'draft' | 'in-review' | 'reviewed';
+}
+
+export function validateNotationAlignment(
+  registry: NotationRegistry,
+  catalog: CurriculumCatalog,
+): readonly NotationDiagnostic[] {
+  const diagnostics: NotationDiagnostic[] = [];
+  const competencies = new Map(
+    (catalog.competencies as readonly EditorialCompetency[]).map((entry) => [
+      entry.id,
+      entry,
+    ]),
+  );
+  const lessons = new Map(catalog.lessons.map((entry) => [entry.id, entry]));
+  const sources = new Map(catalog.sources.map((entry) => [entry.id, entry]));
+  const trackPositions = buildTrackPositions(catalog, diagnostics);
+
+  for (const definition of registry.definitions) {
+    validateSources(definition, sources, diagnostics);
+
+    const alignment = definition.alignment;
+    if (alignment.kind === 'general') continue;
+
+    const competency = competencies.get(alignment.introducedByCompetency);
+    const lesson = lessons.get(alignment.introducedInLesson);
+    if (!competency) {
+      diagnostics.push(
+        error(
+          'alignment-unknown-competency',
+          `${definition.id} is aligned to unknown competency ${alignment.introducedByCompetency}`,
+          definition,
+        ),
+      );
+    }
+    if (!lesson) {
+      diagnostics.push(
+        error(
+          'alignment-unknown-lesson',
+          `${definition.id} is introduced in unknown lesson ${alignment.introducedInLesson}`,
+          definition,
+        ),
+      );
+      continue;
+    }
+    if (!lesson.teaches.includes(alignment.introducedByCompetency)) {
+      diagnostics.push(
+        error(
+          'alignment-introduction',
+          `${definition.id} names ${alignment.introducedInLesson} as its introduction, but that lesson does not teach ${alignment.introducedByCompetency}`,
+          definition,
+        ),
+      );
+    }
+    if (
+      definition.kind === 'local' &&
+      alignment.introducedInLesson !== definition.lessonId
+    ) {
+      diagnostics.push(
+        error(
+          'alignment-introduction',
+          `${definition.id} is page-local to ${definition.lessonId} but declares its introduction in ${alignment.introducedInLesson}`,
+          definition,
+        ),
+      );
+    }
+
+    validateIntroductionOrder(
+      definition,
+      alignment.introducedInLesson,
+      registry,
+      trackPositions,
+      diagnostics,
+    );
+
+    if (
+      definition.status === 'reviewed' &&
+      (lesson.status !== 'reviewed' ||
+        competency?.editorialStatus !== 'reviewed')
+    ) {
+      diagnostics.push(
+        error(
+          'alignment-review-state',
+          `${definition.id} is reviewed while its owning lesson or competency is not reviewed`,
+          definition,
+        ),
+      );
+    }
+  }
+
+  return diagnostics.sort(compareDiagnostics);
+}
+
+export function assertValidNotationAlignment(
+  registry: NotationRegistry,
+  catalog: CurriculumCatalog,
+): void {
+  const errors = validateNotationAlignment(registry, catalog).filter(
+    (diagnostic) => diagnostic.severity === 'error',
+  );
+  if (errors.length === 0) return;
+  throw new Error(
+    `Invalid notation alignment:\n${errors
+      .map((diagnostic) => `- [${diagnostic.code}] ${diagnostic.message}`)
+      .join('\n')}`,
+  );
+}
+
+function buildTrackPositions(
+  catalog: CurriculumCatalog,
+  diagnostics: NotationDiagnostic[],
+): Map<string, Map<string, number>> {
+  const positions = new Map<string, Map<string, number>>();
+  for (const track of catalog.tracks) {
+    const trackMap = new Map<string, number>();
+    track.lessons.forEach((lessonId, index) => trackMap.set(lessonId, index));
+    positions.set(track.id, trackMap);
+  }
+  if (positions.size === 0 && catalog.lessons.length > 0) {
+    diagnostics.push({
+      code: 'alignment-unavailable',
+      severity: 'error',
+      message: 'notation introduction order cannot be checked without a track',
+    });
+  }
+  return positions;
+}
+
+function validateIntroductionOrder(
+  definition: NotationDefinitionRecord,
+  introductionLessonId: string,
+  registry: NotationRegistry,
+  trackPositions: ReadonlyMap<string, ReadonlyMap<string, number>>,
+  diagnostics: NotationDiagnostic[],
+): void {
+  const usedIn = registry.backlinks
+    .filter((backlink) => backlink.definitionId === definition.id)
+    .map((backlink) => backlink.lessonId);
+
+  for (const [trackId, positions] of trackPositions) {
+    const introductionPosition = positions.get(introductionLessonId);
+    for (const lessonId of usedIn) {
+      const usePosition = positions.get(lessonId);
+      if (usePosition === undefined) continue;
+      if (introductionPosition === undefined) {
+        diagnostics.push(
+          error(
+            'alignment-unavailable',
+            `${definition.id} is used by ${lessonId} in track ${trackId}, but its declared introduction ${introductionLessonId} is absent from that track`,
+            definition,
+            lessonId,
+          ),
+        );
+      } else if (usePosition < introductionPosition) {
+        diagnostics.push(
+          error(
+            'alignment-introduction',
+            `${definition.id} is used by ${lessonId} before its declared introduction ${introductionLessonId} in track ${trackId}`,
+            definition,
+            lessonId,
+          ),
+        );
+      }
+    }
+  }
+}
+
+function validateSources(
+  definition: NotationDefinitionRecord,
+  sources: ReadonlyMap<
+    string,
+    { readonly editorialStatus: 'draft' | 'in-review' | 'reviewed' }
+  >,
+  diagnostics: NotationDiagnostic[],
+): void {
+  for (const sourceId of definition.sources) {
+    const source = sources.get(sourceId);
+    if (!source) {
+      diagnostics.push(
+        error(
+          'alignment-unavailable',
+          `${definition.id} cites unknown source ${sourceId}`,
+          definition,
+        ),
+      );
+    } else if (
+      definition.status === 'reviewed' &&
+      source.editorialStatus !== 'reviewed'
+    ) {
+      diagnostics.push(
+        error(
+          'alignment-review-state',
+          `${definition.id} is reviewed while source ${sourceId} is ${source.editorialStatus}`,
+          definition,
+        ),
+      );
+    }
+  }
+}
+
+function error(
+  code: NotationDiagnostic['code'],
+  message: string,
+  definition: NotationDefinitionRecord,
+  lessonId?: string,
+): NotationDiagnostic {
+  return {
+    code,
+    severity: 'error',
+    message,
+    key: definition.key,
+    definitionId: definition.id,
+    lessonId:
+      lessonId ??
+      (definition.kind === 'local' ? definition.lessonId : undefined),
+    source: definition.source,
+  };
+}