explico 0.1.1 → 0.3.0

package/dist/reference/consistency.js

@@ -1,3 +1,5 @@
+import { effectiveOperatorAllowlist } from "./base-operators.mjs";
+import { collectOperators } from "./math-glyphs.mjs";
 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) {
@@ -200,13 +202,147 @@ 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);
+      }
+    }
+  }
+}
+function checkOperatorExplained(input, out) {
+  const allowlist = effectiveOperatorAllowlist(input.operators);
+  const byId = new Map(
+    input.registry.definitions.map((definition) => [definition.id, definition])
+  );
+  const bindingsByLesson = new Map(
+    input.registry.bundles.map((bundle) => [bundle.lessonId, bundle.bindings])
+  );
+  for (const lesson of input.notationInput.lessons) {
+    const explained = /* @__PURE__ */ new Set();
+    const noteEntryOperators = (latex) => {
+      for (const operator of collectOperators(latex)) {
+        explained.add(operator.name);
+      }
+    };
+    for (const definition of lesson.localDefinitions) {
+      noteEntryOperators(definition.notation);
+    }
+    for (const binding of bindingsByLesson.get(lesson.lessonId) ?? []) {
+      const definition = byId.get(binding.definitionId);
+      if (definition) noteEntryOperators(definition.notation);
+    }
+    const reported = /* @__PURE__ */ new Set();
+    for (const span of mathSpans(lesson.body)) {
+      for (const operator of collectOperators(span.latex)) {
+        if (allowlist.has(operator.name)) continue;
+        if (explained.has(operator.name)) continue;
+        if (reported.has(operator.name)) continue;
+        reported.add(operator.name);
+        if (input.lintIgnore.matches("operator-explained", operator.name)) {
+          continue;
+        }
+        const display = operator.source === "operatorname" ? `\\operatorname{${operator.name}}` : `\\${operator.name}`;
+        out.push({
+          code: "operator-explained",
+          severity: "warning",
+          lessonId: lesson.lessonId,
+          file: lesson.source.file,
+          glyph: operator.name,
+          message: `${lesson.lessonId}: operator ${JSON.stringify(display)} is neither on the course operator allowlist nor explained by a notation entry; give it a card or notation.local entry (latex ${JSON.stringify(display)}) introduced with [[key]], or add ${JSON.stringify(operator.name)} to operators.allow in course.config.ts`
+        });
+      }
+    }
+  }
+}
 const CHECKS = [
   checkGlyphUniqueness,
   checkNotationUnits,
   checkConventionSingleDefinition,
   checkNumeralsTagged,
   checkWeakLocal,
-  checkNotationSourceLocator
+  checkNotationSourceLocator,
+  checkGlossWantsPromoting,
+  checkCardWantsDemoting,
+  checkGlossNameShape,
+  checkOperatorExplained
 ];
 function runConsistencyChecks(input) {
   const diagnostics = [];
@@ -223,7 +359,11 @@ 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,
+    "operator-explained": 0
   };
   for (const diagnostic of diagnostics) counts[diagnostic.code] += 1;
   return counts;

package/dist/reference/diagram-layout.d.ts

@@ -0,0 +1,63 @@
+interface DiagramNodeInput {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+}
+interface DiagramEdgeInput {
+    readonly from: string;
+    readonly to: string;
+}
+interface DiagramLayoutOptions {
+    /** Top-to-bottom (default) or left-to-right. */
+    readonly direction?: 'TB' | 'LR';
+    readonly nodeSeparation?: number;
+    readonly rankSeparation?: number;
+    /** Uniform padding added around the computed bounding box. */
+    readonly padding?: number;
+}
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+interface LaidOutNode {
+    readonly id: string;
+    /** Top-left corner, not the center dagre itself works in. */
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface LaidOutEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly points: readonly Point[];
+}
+interface DiagramLayout {
+    readonly nodes: readonly LaidOutNode[];
+    readonly edges: readonly LaidOutEdge[];
+    /** The SVG canvas size a caller should use as the `viewBox`. */
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Lay out a small directed graph. Node ids must be unique; an edge naming an
+ * undeclared node fails loudly rather than silently dropping it (dagre itself
+ * would otherwise create a phantom zero-size node).
+ */
+declare function layoutDiagram(nodes: readonly DiagramNodeInput[], edges: readonly DiagramEdgeInput[], options?: DiagramLayoutOptions): DiagramLayout;
+interface BoxSizeEstimate {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Estimate a diagram node's box from its label text (or raw, pre-resolution
+ * LaTeX for a formula node). Deliberately generous: it is meant to avoid
+ * clipping, not to match a real render pixel-for-pixel. Pass an explicit
+ * `width`/`height` on the node to override for a label this estimate gets
+ * badly wrong.
+ */
+declare function estimateBoxSize(content: string, kind: 'text' | 'formula', options?: {
+    readonly maxWidth?: number;
+}): BoxSizeEstimate;
+
+export { type BoxSizeEstimate, type DiagramEdgeInput, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodeInput, type LaidOutEdge, type LaidOutNode, type Point, estimateBoxSize, layoutDiagram };

package/dist/reference/diagram-layout.js

@@ -0,0 +1,122 @@
+import dagre from "@dagrejs/dagre";
+function layoutDiagram(nodes, edges, options = {}) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const node of nodes) {
+    if (ids.has(node.id)) {
+      throw new Error(`Diagram declares node "${node.id}" more than once.`);
+    }
+    if (!(node.width > 0) || !(node.height > 0)) {
+      throw new Error(
+        `Diagram node "${node.id}" must have a positive width and height.`
+      );
+    }
+    ids.add(node.id);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from)) {
+      throw new Error(`Diagram edge references unknown node "${edge.from}".`);
+    }
+    if (!ids.has(edge.to)) {
+      throw new Error(`Diagram edge references unknown node "${edge.to}".`);
+    }
+  }
+  const graph = new dagre.graphlib.Graph();
+  graph.setGraph({
+    rankdir: options.direction ?? "TB",
+    nodesep: options.nodeSeparation ?? 24,
+    ranksep: options.rankSeparation ?? 48,
+    marginx: 0,
+    marginy: 0
+  });
+  graph.setDefaultEdgeLabel(() => ({}));
+  for (const node of nodes) {
+    graph.setNode(node.id, { width: node.width, height: node.height });
+  }
+  for (const edge of edges) {
+    graph.setEdge(edge.from, edge.to);
+  }
+  dagre.layout(graph);
+  const centeredNodes = nodes.map((node) => {
+    const label = graph.node(node.id);
+    const cx = label.x ?? 0;
+    const cy = label.y ?? 0;
+    return {
+      id: node.id,
+      x: cx - node.width / 2,
+      y: cy - node.height / 2,
+      width: node.width,
+      height: node.height
+    };
+  });
+  const rawEdges = edges.map((edge) => {
+    const label = graph.edge(edge.from, edge.to) ?? {};
+    return {
+      from: edge.from,
+      to: edge.to,
+      points: (label.points ?? []).map((point) => ({
+        x: point.x,
+        y: point.y
+      }))
+    };
+  });
+  const padding = options.padding ?? 12;
+  const xs = [
+    ...centeredNodes.flatMap((node) => [node.x, node.x + node.width]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.x))
+  ];
+  const ys = [
+    ...centeredNodes.flatMap((node) => [node.y, node.y + node.height]),
+    ...rawEdges.flatMap((edge) => edge.points.map((point) => point.y))
+  ];
+  const minX = xs.length > 0 ? Math.min(...xs) : 0;
+  const minY = ys.length > 0 ? Math.min(...ys) : 0;
+  const maxX = xs.length > 0 ? Math.max(...xs) : 0;
+  const maxY = ys.length > 0 ? Math.max(...ys) : 0;
+  const shiftX = padding - minX;
+  const shiftY = padding - minY;
+  return {
+    nodes: centeredNodes.map((node) => ({
+      ...node,
+      x: node.x + shiftX,
+      y: node.y + shiftY
+    })),
+    edges: rawEdges.map((edge) => ({
+      ...edge,
+      points: edge.points.map((point) => ({
+        x: point.x + shiftX,
+        y: point.y + shiftY
+      }))
+    })),
+    width: maxX - minX + padding * 2,
+    height: maxY - minY + padding * 2
+  };
+}
+const DEFAULT_MAX_WIDTH = 220;
+const MIN_WIDTH = 90;
+const PADDING_X = 20;
+const PADDING_Y = 16;
+const LINE_HEIGHT = 22;
+const CHAR_WIDTH = {
+  text: 7.2,
+  formula: 11
+};
+function formulaVisibleLength(latex) {
+  const collapsed = latex.replace(/\\[a-zA-Z]+/g, "x").replace(/[{}$]/g, "").trim();
+  return Math.max(1, collapsed.length);
+}
+function estimateBoxSize(content, kind, options = {}) {
+  const maxWidth = options.maxWidth ?? DEFAULT_MAX_WIDTH;
+  const visibleLength = kind === "formula" ? formulaVisibleLength(content) : content.trim().length || 1;
+  const charWidth = CHAR_WIDTH[kind];
+  const naturalWidth = visibleLength * charWidth + PADDING_X * 2;
+  const width = Math.min(maxWidth, Math.max(MIN_WIDTH, naturalWidth));
+  const usableWidth = width - PADDING_X * 2;
+  const charsPerLine = Math.max(1, Math.floor(usableWidth / charWidth));
+  const lines = Math.max(1, Math.ceil(visibleLength / charsPerLine));
+  const height = lines * LINE_HEIGHT + PADDING_Y * 2;
+  return { width: Math.round(width), height: Math.round(height) };
+}
+export {
+  estimateBoxSize,
+  layoutDiagram
+};

package/dist/reference/equations-validate.d.ts

@@ -44,6 +44,11 @@ interface EquationLessonInput {
     readonly slug: string;
     readonly file: string;
     readonly body: string;
+    /**
+     * The lesson's 1-based ordinal in the course. When set, equations are
+     * numbered `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+     */
+    readonly chapter?: number;
 }
 declare function validateEquations(lessons: readonly EquationLessonInput[]): EquationValidation;
 

package/dist/reference/equations-validate.js

@@ -25,7 +25,7 @@ function validateEquations(lessons) {
   )) {
     const seen = /* @__PURE__ */ new Set();
     const table = {};
-    for (const raw of scanEquationLabels(lesson.body)) {
+    for (const raw of scanEquationLabels(lesson.body, lesson.chapter)) {
       if (seen.has(raw.key)) {
         diagnostics.push({
           code: "eq-duplicate-key",

package/dist/reference/equations.d.mts

@@ -8,42 +8,100 @@ export function parseEquationRef(raw: any): {
 } | undefined;
 /** Remove every `\label{eq:…}` (and the whitespace it leaves) from a math source. */
 export function stripEquationLabels(latex: any): string;
+/**
+ * The visible number for one display equation. With `chapter` (the lesson's
+ * course ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings
+ * are ignored; without it, the legacy `##`-section scheme.
+ */
+export function displayEquationNumber({ chapter, section, indexInSection, indexInLesson, }: {
+    chapter: any;
+    section: any;
+    indexInSection: any;
+    indexInLesson: 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;
+export function stripFencedCode(markdown: any): string;
+/**
+ * Blank the body of every block-level MDX component (`<Capitalised …> … </…>`)
+ * so a `$$…$$` used to illustrate a worked example inside `<CompactExample>`
+ * (or an `<Aside>`, etc.) is not counted as a lesson-body equation. The
+ * outermost match wins, so nested components are blanked in one pass;
+ * newlines are kept so line/section structure is unchanged.
+ *
+ * `keep`, when given, leaves a component of that name untouched instead of
+ * blanking it — `keyed-jsx-floats.mjs` uses this to blank every *other*
+ * component while still finding `<Table>`/`<Figure>` tags at the top level.
+ */
+export function stripJsxComponents(markdown: any, keep: 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.
+ * its assigned number. `$$…$$` blocks only. With `chapter` (the lesson's
+ * course ordinal) the number is `‹chapter›.‹n›`, `n` sequential over every
+ * display block in the lesson; without it, `##` headings advance a section
+ * counter and the number is `‹section›.‹indexInSection›`. Either way every
+ * display block advances the 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 | undefined;
+export function scanEquationLabels(markdown: any, chapter: any): {
+    key: string;
     number: string;
     section: number;
     indexInSection: number;
 }[];
 /**
- * The mdast equivalent of `scanEquationLabels`: walk the tree in document
- * order, advancing the section counter on every depth-2 heading and emitting a
- * label for every `math` node whose source carries `\label{eq:…}`.
+ * 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`. `chapter` is threaded the
+ * same way as in `scanEquationLabels`.
  */
-export function collectEquationLabels(tree: any): any[];
+export function collectDisplayEquations(tree: any, chapter: 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, chapter: any): {
+    key: string | null;
+    number: string;
+    section: number;
+    indexInSection: number;
+    node: any;
+}[];
 /**
- * Equation identity (Step D7) — shared, framework-free helpers.
+ * Equation identity (Step D7, extended F3) — shared, framework-free helpers.
  *
- * An author marks a display equation by putting a trailing `\label{eq:<key>}`
- * inside its `$$…$$` block (inside math, so the `:` is safe and the form
- * matches amsmath). The compiler assigns the *visible* number from appearance
- * order, scoped to the enclosing `##` section (`(2.4)` = fourth keyed equation
- * under the second section). The number is never authored; unkeyed display
- * equations render clean and stay un-referenceable. Prose refers to an
- * equation with the reserved `eq-` prefix (a bare `:` in `[[…]]` prose would
- * be eaten by `remark-directive`):
+ * Every display equation (`$$…$$`) in a lesson is numbered and given an `id`
+ * from appearance order. When the caller supplies a `chapter` (the lesson's
+ * ordinal position in the course), the number is `‹chapter›.‹n›` — `n` counts
+ * every display equation in the lesson and `##` headings do not affect it
+ * (`(2.4)` = fourth display equation of the second lesson). With no `chapter`
+ * the number falls back to the `##`-section scheme `‹section›.‹indexInSection›`
+ * (used by hand-built test trees and non-lesson pages). 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.
+ * 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;