explico 0.1.0 → 0.2.0

package/dist/compiler/cli.d.ts

@@ -7,6 +7,7 @@ import '../reference/types.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
 import '../reference/gate-math.js';
+import '../reference/gloss.js';
 import './lesson-derivation.js';
 
 /**

package/dist/compiler/cli.js

@@ -12,7 +12,7 @@ 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";
+import { isLessonSlug, lessonIdFromSlug } from "./lesson-derivation.js";
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const DOCS_ROOT = join(CONTENT_ROOT, "docs");

package/dist/compiler/collections.js

@@ -1,16 +1,17 @@
 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 { isSubstantiveMeaning } from "../reference/prose.js";
 import { parseEquationRef } from "../reference/equations.mjs";
-import { resolveLabel } from "../reference/label";
+import { resolveLabel } from "../reference/label.js";
+import { resolveGlosses } from "../reference/gloss.js";
 import {
   deriveRequires,
   deriveSources,
   isLessonSlug,
   lessonIdFromSlug,
   parseCheckList
-} from "./lesson-derivation";
+} from "./lesson-derivation.js";
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 function filesBelow(directory, extensions) {
@@ -206,6 +207,30 @@ async function loadCurriculumCatalog() {
     tracks: jsonEntries(join(CONTENT_ROOT, "tracks"))
   };
 }
+function glossEntries(raw, ownerKey, at) {
+  if (raw === void 0) return [];
+  if (!Array.isArray(raw)) throw new Error(`${at} must be an array`);
+  const authored = raw.map((value, index) => {
+    const data = record(value, `${at}[${index}]`);
+    const units = optionalString(data.units, `${at}[${index}].units`);
+    return {
+      latex: string(data.latex, `${at}[${index}].latex`),
+      name: string(data.name, `${at}[${index}].name`),
+      ...units === void 0 ? {} : { units }
+    };
+  });
+  const glosses = resolveGlosses(ownerKey, authored);
+  const seen = /* @__PURE__ */ new Set();
+  for (const gloss of glosses) {
+    if (seen.has(gloss.key)) {
+      throw new Error(
+        `${at} declares two glosses named ${JSON.stringify(gloss.label)}`
+      );
+    }
+    seen.add(gloss.key);
+  }
+  return glosses;
+}
 function localDefinition(raw, file, index) {
   const at = `${file} notation.local[${index}]`;
   const data = record(raw, at);
@@ -224,6 +249,7 @@ function localDefinition(raw, file, index) {
     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"),
+    glosses: glossEntries(data.glosses, key, `${at}.glosses`),
     source: { file },
     ...formula === void 0 ? {} : { formula },
     ...units === void 0 ? {} : { units }
@@ -255,6 +281,7 @@ function sharedNotationEntries() {
       aiAssisted: boolean(data.aiAssisted, `${file} aiAssisted`),
       body,
       references: extractNotationReferences(body, file, void 0),
+      glosses: glossEntries(data.glosses, key, `${file} glosses`),
       source: { file },
       ...formula === void 0 ? {} : { formula },
       ...units === void 0 ? {} : { units }

package/dist/compiler/manifest.d.ts

@@ -2,7 +2,8 @@ import { CurriculumIssue } from '../curriculum/validation.js';
 import { ConsistencyDiagnostic } from '../reference/consistency.js';
 import { EquationLabelRecord, EquationDiagnostic } from '../reference/equations-validate.js';
 import { MathGateDiagnostic } from '../reference/gate-math.js';
-import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus } from '../reference/types.js';
+import { GlyphScopeEntry } from '../reference/gloss.js';
+import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus, NotationGlossEntry } from '../reference/types.js';
 import { CourseConfig } from './course-config.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
@@ -81,6 +82,14 @@ interface ManifestLessonNotation {
     readonly seeAlso: readonly string[];
     readonly units?: string;
     readonly formula?: string;
+    /** Symbols the formula names that have no card of their own (D15). */
+    readonly glosses: readonly NotationGlossEntry[];
+    /**
+     * Entry-scoped glyph table for `formula` — the entry, its glosses, and any
+     * card the formula names. Precomputed here because the whole card set lives
+     * in the compiler, not in the page component.
+     */
+    readonly formulaScope: readonly GlyphScopeEntry[];
 }
 interface ManifestLesson {
     readonly id: string;

package/dist/compiler/manifest.js

@@ -10,32 +10,33 @@ import { dirname, join, relative } from "node:path";
 import { parseFrontmatter } from "@astrojs/markdown-remark";
 import {
   validateCurriculum
-} from "../curriculum/validation";
+} from "../curriculum/validation.js";
 import {
   runConsistencyChecks
-} from "../reference/consistency";
-import { validateNotationAlignment } from "../reference/curriculum-alignment";
+} from "../reference/consistency.js";
+import { validateNotationAlignment } from "../reference/curriculum-alignment.js";
 import {
   validateEquations
-} from "../reference/equations-validate";
+} from "../reference/equations-validate.js";
 import {
   gateContentMath
-} from "../reference/gate-math";
-import { loadLintIgnore } from "../reference/lint-ignore";
-import { buildNotationRegistry } from "../reference/registry";
-import { resolveReferenceId } from "../reference/references";
+} from "../reference/gate-math.js";
+import { loadLintIgnore } from "../reference/lint-ignore.js";
+import { buildNotationRegistry } from "../reference/registry.js";
+import { formulaGlyphScope } from "../reference/gloss.js";
+import { resolveReferenceId } from "../reference/references.js";
 import {
   loadCurriculumCatalog,
   loadNotationDefinitions,
   loadNotationRegistryInput,
   loadNotationSpecs,
   loadSourceRecords
-} from "./collections";
+} from "./collections.js";
 import {
   buildSidebar,
   deriveSources,
   isLessonSlug
-} from "./lesson-derivation";
+} from "./lesson-derivation.js";
 const MANIFEST_SCHEMA_VERSION = 3;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
@@ -97,7 +98,7 @@ function lessonNotationResolution(lesson, definitionsById, availableDefinitionId
     };
   });
 }
-function lessonNotationBundle(bundle, definitionsById, resolution) {
+function lessonNotationBundle(bundle, definitionsById, resolution, cardsByKey) {
   const definitions = [];
   for (const definitionId of bundle?.definitionIds ?? []) {
     const definition = definitionsById.get(definitionId);
@@ -111,6 +112,14 @@ function lessonNotationBundle(bundle, definitionsById, resolution) {
       summary: definition.summary,
       editorialStatus: definition.status,
       seeAlso: [...definition.seeAlso],
+      glosses: [...definition.glosses],
+      formulaScope: formulaGlyphScope({
+        key: definition.key,
+        notation: definition.notation,
+        glosses: definition.glosses,
+        cardsByKey,
+        ...definition.formula === void 0 ? {} : { formula: definition.formula }
+      }),
       ...definition.units === void 0 ? {} : { units: definition.units },
       ...definition.formula === void 0 ? {} : { formula: definition.formula }
     });
@@ -152,6 +161,12 @@ async function compileManifest(courseConfig) {
     loadNotationRegistryInput()
   ]);
   const registry = buildNotationRegistry(notationInput);
+  const cardsByKey = new Map(
+    notationInput.sharedDefinitions.map((definition) => [
+      definition.key,
+      { key: definition.key, notation: definition.notation }
+    ])
+  );
   const definitionsById = new Map(
     registry.definitions.map((definition) => [definition.id, definition])
   );
@@ -237,7 +252,8 @@ async function compileManifest(courseConfig) {
           notationLesson,
           definitionsById,
           availableDefinitionIds
-        )
+        ),
+        cardsByKey
       )
     });
   }

package/dist/compiler/resolution-report.d.ts

@@ -7,6 +7,7 @@ import '../reference/types.js';
 import '../reference/lint-ignore.js';
 import '../reference/equations-validate.js';
 import '../reference/gate-math.js';
+import '../reference/gloss.js';
 import './lesson-derivation.js';
 
 /**

package/dist/compiler/resolution-report.js

@@ -9,8 +9,8 @@ import {
 import { join } from "node:path";
 import {
   consistencyCounts
-} from "../reference/consistency";
-import { MANIFEST_SCHEMA_VERSION } from "./manifest";
+} from "../reference/consistency.js";
+import { MANIFEST_SCHEMA_VERSION } from "./manifest.js";
 const REPOSITORY_ROOT = process.cwd();
 const RESOLUTION_DIR = join(REPOSITORY_ROOT, "build", "resolution");
 const RESOLUTION_PREFIX = "build/resolution/";

package/dist/reference/base-library.d.mts

@@ -0,0 +1,17 @@
+/** True when `token` is a base-library atom and needs no semantic key. */
+export function isBaseLibraryAtom(token: any): boolean;
+/**
+ * The base notation library: a small, fixed set of universal identifier atoms
+ * that the page-level glyph map never asks an author to declare.
+ *
+ * Rationale (cleanup plan, "Decide once"): keep a base library so the
+ * completeness gate does not choke on mathematical constants and the
+ * differential operator. It is deliberately tiny and greppable — anything a
+ * lesson uses with a domain meaning (rates, indices, prices) still resolves to
+ * a semantic key or fails at `file:line:token`.
+ *
+ * Function names (`\ln`, `\exp`, `\log`, `\sin`, `\max`, `\sum`, `\prod`, …)
+ * are not listed here: KaTeX parses them as operator nodes, not identifier
+ * atoms, so the tokenizer never treats them as bindable symbols.
+ */
+export const BASE_LIBRARY: Readonly<Set<string>>;

package/dist/reference/citation-format.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Short author label: one surname, "A & B" for two, "A et al." for more.
+ * Falls back to the publishing organization for official guidance.
+ *
+ * @param {Record<string, unknown>} record
+ * @returns {string}
+ */
+export function formatAuthors(record: Record<string, unknown>): string;
+/**
+ * The "(4th ed., 2022)" tail, omitting whichever parts are absent.
+ *
+ * @param {Record<string, unknown>} record
+ * @returns {string}
+ */
+export function formatEditionYear(record: Record<string, unknown>): string;
+/**
+ * One reference-list line: "Authors, Title (edition, year). Locator."
+ * `locator` is the text an author passed after the `;` in `[@id; locator]` and is
+ * optional. The source record's own catalog `locator` is not used here.
+ *
+ * @param {Record<string, unknown>} record
+ * @param {string | undefined} locator
+ * @returns {string}
+ */
+export function formatReferenceText(record: Record<string, unknown>, locator: string | undefined): string;
+/**
+ * Recover the source label (authors + title, no locator) from a rendered
+ * reference-list line — the inverse of the ". <locator>." tail
+ * `formatReferenceText` appends. Lets the citation hover panel read its
+ * heading off the page's own "References" list instead of a second serialized
+ * copy of the source database. Falls back to the whole line if the tail is
+ * not where it is expected.
+ *
+ * @param {string} referenceText  text of the `#cite-n` list item
+ * @param {string | undefined} locator  the marker's `data-citation-locator`
+ * @returns {string}
+ */
+export function referenceLabelFromText(referenceText: string, locator: string | undefined): string;
+/**
+ * The compact "Tuckman & Serrat, Fixed Income Securities (4th ed., 2022)"
+ * shown as the panel heading, without the locator.
+ *
+ * @param {Record<string, unknown>} record
+ * @returns {string}
+ */
+export function formatSourceLabel(record: Record<string, unknown>): string;
+/**
+ * Pure helpers for turning a source record plus a per-citation locator into
+ * the strings shown in the inline panel and the end-of-page reference list.
+ *
+ * Imported by both the remark adapter (build-time list rendering) and the
+ * `CitationLayer` island (hover panel), so it must not touch the DOM, the
+ * file system, or Astro APIs.
+ */
+export const SOURCE_ID_PATTERN: RegExp;

package/dist/reference/consistency.d.ts

@@ -30,7 +30,7 @@ import { NotationRegistry, NotationRegistryInput } from './types.js';
  * `src/content/resolution-report.ts`.
  */
 
-type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator';
+type ConsistencyCode = 'glyph-unique-in-corpus' | 'notation-units' | 'units-vocab' | 'convention-single-definition' | 'numerals-tagged' | 'weak-local' | 'notation-source-locator' | 'gloss-wants-promoting' | 'card-wants-demoting' | 'gloss-name-shape';
 interface ConsistencyDiagnostic {
     readonly code: ConsistencyCode;
     /** Tier 3 — every finding here is a warning until content is brought clean. */

package/dist/reference/consistency.js

@@ -1,4 +1,4 @@
-import { offVocabularyTokens } from "./units-vocab";
+import { offVocabularyTokens } from "./units-vocab.js";
 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;
 function stripCode(text) {
   return text.replace(/```[\s\S]*?```/g, (block) => block.replace(/[^\n]/g, " ")).replace(/(^|[^`])`[^`\n]*`/g, (match) => match.replace(/[^\n]/g, " "));
@@ -200,13 +200,101 @@ function checkNotationSourceLocator(input, out) {
     }
   }
 }
+const GLOSS_PROMOTION_LIMIT = 3;
+function checkGlossWantsPromoting(input, out) {
+  const owners = /* @__PURE__ */ new Map();
+  const record = (ownerKey, gloss) => {
+    const id = `${gloss.notation}\0${gloss.label.toLowerCase()}`;
+    const current = owners.get(id) ?? { label: gloss.label, keys: /* @__PURE__ */ new Set() };
+    current.keys.add(ownerKey);
+    owners.set(id, current);
+  };
+  for (const definition of input.notationInput.sharedDefinitions) {
+    for (const gloss of definition.glosses) record(definition.key, gloss);
+  }
+  for (const lesson of input.notationInput.lessons) {
+    for (const definition of lesson.localDefinitions) {
+      for (const gloss of definition.glosses) record(definition.key, gloss);
+    }
+  }
+  for (const [id, { label, keys }] of [...owners].sort(
+    ([a], [b]) => a.localeCompare(b)
+  )) {
+    if (keys.size < GLOSS_PROMOTION_LIMIT) continue;
+    const glyph = id.split("\0")[0] ?? "";
+    if (input.lintIgnore.matches("gloss-wants-promoting", glyph)) continue;
+    out.push({
+      code: "gloss-wants-promoting",
+      severity: "warning",
+      glyph,
+      message: `gloss ${JSON.stringify(glyph)} (${label}) is declared on ${keys.size} entries (${[...keys].sort().join(", ")}); a meaning reused this widely wants promoting to a card`
+    });
+  }
+}
+const CARD_BODY_MINIMUM_WORDS = 25;
+function checkCardWantsDemoting(input, out) {
+  const used = new Set(
+    input.registry.backlinks.map((backlink) => backlink.key)
+  );
+  for (const definition of input.notationInput.sharedDefinitions) {
+    if (definition.formula !== void 0) continue;
+    if (definition.sources.length > 0) continue;
+    if (used.has(definition.key)) continue;
+    const words = stripCode(definition.body).split(/\s+/).filter((word) => word.length > 0).length;
+    if (words >= CARD_BODY_MINIMUM_WORDS) continue;
+    if (input.lintIgnore.matches("card-wants-demoting", definition.key)) {
+      continue;
+    }
+    out.push({
+      code: "card-wants-demoting",
+      severity: "warning",
+      key: definition.key,
+      file: definition.source.file,
+      count: words,
+      message: `notation card ${definition.key} has no formula, no sources, a ${words}-word body, and no lesson uses it; it carries no more than a name \u2014 a gloss on the entry that needs it may be the right home`
+    });
+  }
+}
+const GLOSS_NAME_WORD_LIMIT = 6;
+const GLOSS_NAME_PROSE = /[.;]|\b(?:which|whose|that is|such that)\b/i;
+function checkGlossNameShape(input, out) {
+  const check = (gloss, file, lessonId) => {
+    const words = gloss.label.trim().split(/\s+/).filter(Boolean);
+    const reason = words.length > GLOSS_NAME_WORD_LIMIT ? `${words.length} words` : GLOSS_NAME_PROSE.test(gloss.label) ? "sentence punctuation or a relative clause" : void 0;
+    if (reason === void 0) return;
+    if (input.lintIgnore.matches("gloss-name-shape", gloss.key)) return;
+    out.push({
+      code: "gloss-name-shape",
+      severity: "warning",
+      key: gloss.key,
+      file,
+      ...lessonId ? { lessonId } : {},
+      message: `gloss ${gloss.key} is named ${JSON.stringify(gloss.label)} (${reason}); a gloss name is a short noun phrase naming the symbol, not a description of it`
+    });
+  };
+  for (const definition of input.notationInput.sharedDefinitions) {
+    for (const gloss of definition.glosses) {
+      check(gloss, definition.source.file);
+    }
+  }
+  for (const lesson of input.notationInput.lessons) {
+    for (const definition of lesson.localDefinitions) {
+      for (const gloss of definition.glosses) {
+        check(gloss, definition.source.file, lesson.lessonId);
+      }
+    }
+  }
+}
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
   checkConventionSingleDefinition,
   checkNumeralsTagged,
   checkWeakLocal,
-  checkNotationSourceLocator
+  checkNotationSourceLocator,
+  checkGlossWantsPromoting,
+  checkCardWantsDemoting,
+  checkGlossNameShape
 ];
 function runConsistencyChecks(input) {
   const diagnostics = [];
@@ -223,7 +311,10 @@ function consistencyCounts(diagnostics) {
     "convention-single-definition": 0,
     "numerals-tagged": 0,
     "weak-local": 0,
-    "notation-source-locator": 0
+    "notation-source-locator": 0,
+    "gloss-wants-promoting": 0,
+    "card-wants-demoting": 0,
+    "gloss-name-shape": 0
   };
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/dist/reference/curriculum-alignment.js

@@ -1,4 +1,4 @@
-import { compareDiagnostics } from "./references";
+import { compareDiagnostics } from "./references.js";
 function validateNotationAlignment(registry, catalog) {
   const diagnostics = [];
   const competencies = new Map(

package/dist/reference/equations.d.mts

@@ -0,0 +1,84 @@
+/** `{ lesson?, key }` when `raw` is an equation reference, else `undefined`. */
+export function parseEquationRef(raw: any): {
+    lesson: string;
+    key: string;
+} | {
+    key: string;
+    lesson?: undefined;
+} | undefined;
+/** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
+export function stripEquationLabels(latex: any): string;
+/** The positional anchor id for an unkeyed equation, e.g. `2.4` → `eq-2-4`. */
+export function equationAnchorId({ key, number }: {
+    key: any;
+    number: any;
+}): string;
+/**
+ * Every keyed display equation in a Markdown body, in appearance order, with
+ * its assigned number. `$$…$$` blocks only; `##` headings between them advance
+ * the section counter. Every display block advances the in-section index, so a
+ * keyed equation's number reflects its position among *all* display equations,
+ * not only the keyed ones.
+ */
+export function scanEquationLabels(markdown: any): {
+    key: string;
+    number: string;
+    section: number;
+    indexInSection: number;
+}[];
+/**
+ * The mdast equivalent of `scanEquationLabels` for *every* display equation:
+ * walk the tree in document order, advancing the section counter on every
+ * depth-2 heading and emitting a record for every `math` node. `key` is the
+ * `\label{eq:…}` payload when present, else `null`.
+ */
+export function collectDisplayEquations(tree: any): {
+    key: string | null;
+    number: string;
+    section: number;
+    indexInSection: number;
+    node: any;
+}[];
+/**
+ * The keyed subset of `collectDisplayEquations` — the tree-walk counterpart of
+ * `scanEquationLabels`. Numbers reflect position among all display equations.
+ */
+export function collectEquationLabels(tree: any): {
+    key: string | null;
+    number: string;
+    section: number;
+    indexInSection: number;
+    node: any;
+}[];
+/**
+ * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
+ *
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an
+ * `id`, from appearance order scoped to the enclosing `##` section (`(2.4)` =
+ * fourth display equation under the second section). An author additionally
+ * marks an equation with a trailing `\label{eq:<key>}` inside its `$$…$$`
+ * block (inside math, so the `:` is safe and the form matches amsmath) when
+ * they want a *stable* anchor that survives edits and cross-page references:
+ *
+ *   [[eq-discount-factor-def]]           same page  → "(2.4)" linked to #eq-…
+ *   [[foundations/present-value#eq-pv]]  cross page → number from the manifest
+ *
+ * An unkeyed equation still gets a positional anchor (`#eq-2-4`) so it can be
+ * deep-linked, but only a keyed equation is referenceable by name.
+ *
+ * `scanEquationLabels` (raw Markdown) and `collectEquationLabels` (mdast tree)
+ * MUST agree — `tests/notation/equations.test.ts` checks that on the real
+ * corpus. Both are here so `manifest.ts` and `remark-notation.mjs` share one
+ * numbering algorithm. `collectDisplayEquations` is the superset the render
+ * path uses to number and anchor every display equation, keyed or not.
+ */
+/** `eq:` key grammar — the notation-key shape without the dotted namespaces. */
+export const EQ_KEY_PATTERN: RegExp;
+/** A `\label{eq:<key>}` anywhere in a math source. Global; `key` in group 1. */
+export const EQ_LABEL_PATTERN: RegExp;
+/**
+ * A `[[ … ]]` payload that targets an equation: `eq-<key>` on the current page,
+ * or `<lesson-slug>#eq-<key>` across pages. `lesson` (group 1) is a `/`-slug.
+ * The `eq-` prefix is reserved — a notation key may not start with it.
+ */
+export const EQ_REF_PATTERN: RegExp;