explico 0.13.0 → 0.14.0

package/dist/reference/gate-indices.js

@@ -4,7 +4,8 @@ import {
   equationLinkFor,
   mathSpans,
   pageScope,
-  suspendedOperators
+  suspendedOperators,
+  scopeLocals
 } from "./gate-math.js";
 import { formulaGlyphScope } from "./gloss.js";
 import { indexOfEntry } from "./math-glyphs.mjs";
@@ -38,7 +39,7 @@ function message(lessonId, code, details, place = "body") {
     case "index-swallowed":
       return `${lessonId}: \\explain{${details.key}}{${details.token}} wraps an indexed symbol in ${details.key}, whose latex (${details.notation}) has no index, so its card cannot explain ${JSON.stringify(details.index)}. Drop the wrap and give the subscript an index entry (latex: "{}_${details.index}"), or wrap it in an entry for the indexed symbol (rule N23).`;
     case "index-range":
-      return `${lessonId}: the running index ${details.letter} (first in ${JSON.stringify(details.token)}) has no stated set. Give ${details.where} a range (range: "1, \\\\dots, n"), state it after a \\quad on the first display line that uses it (\\quad ${details.letter} = 1, \\dots, n), or mark the card fixedIndex: true if ${details.letter} is a label there, not a running index (rule N23).`;
+      return `${lessonId}: the running index ${details.letter} (first in ${JSON.stringify(details.token)}) has no stated set. Give ${details.where} a range (range: "1, \\\\dots, n"), state it after a \\quad on the first display line that uses it (\\quad ${details.letter} = 1, \\dots, n), or mark the card fixedIndex: true if ${details.letter} is a label there, not a running index; a family indexed by ${details.letter} then explains none of its instances (rule N23).`;
     case "derived-key-taken":
       return `${lessonId}: ${JSON.stringify(details.token)} composes the derived card ${details.key}, but an authored entry has that key. Rename the entry: a key of the form <symbol>.sub.<index> is the build's (rule N23).`;
   }
@@ -51,7 +52,7 @@ function gateIndices(lessons, entries, extras = {}) {
     const bodyOffset = (lesson.bodyLine ?? 1) - 1;
     const scope = pageScope(lesson, entries);
     const local = new Map(
-      lesson.localDefinitions.map((definition) => [definition.key, definition])
+      scopeLocals(lesson).map((definition) => [definition.key, definition])
     );
     const factsOf = (key) => key === null ? void 0 : local.get(key) ?? entries.get(key);
     const suspended = suspendedOperators(lesson);
@@ -185,7 +186,7 @@ function gateIndices(lessons, entries, extras = {}) {
     if (!lesson) continue;
     const scope = pageScope(lesson, entries);
     const local = new Map(
-      lesson.localDefinitions.map((definition) => [definition.key, definition])
+      scopeLocals(lesson).map((definition) => [definition.key, definition])
     );
     const factsOf = (key) => key === null ? void 0 : local.get(key) ?? entries.get(key);
     for (const assessmentId of link.assessmentIds) {

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

@@ -43,7 +43,7 @@ interface MathGateDiagnostic {
      * one the engine ships; its severity is the course's choice, so it is the one
      * context whose severity is not fixed here.
      */
-    readonly severity: 'error' | 'warning';
+    readonly severity: 'error' | 'warning' | 'info';
     /** Owned by exactly one rule or invariant in `src/rules/catalog.ts`. */
     readonly code: string;
     readonly file: string;
@@ -106,6 +106,33 @@ declare function scopeEntry(definition: {
  * assessment's math (`mixed-content.ts`), say — doesn't reconstruct it by
  * hand and risk drifting from what the completeness gate actually checks.
  */
+/**
+ * The `notation.local` entries in scope on a page: its own, and for a deck
+ * beside its chapter the chapter's, which are the lesson's
+ * (`NotationLessonInput.inheritedLocalDefinitions`).
+ */
+declare function scopeLocals(lesson: NotationLessonInput): readonly NotationLessonInput['localDefinitions'][number][];
+/** Every `\explain{key}{inner}` in a span, in source order, with its offset. */
+declare function explainCalls(latex: string): {
+    key: string;
+    inner: string;
+    index: number;
+}[];
+/**
+ * The `\explain` wraps in a span that bind nothing new (rule N4): the bare
+ * inner form already resolves to the same card, with no glyph left over and
+ * no decoration left unexplained (rule N22). Such a wrap costs an author
+ * tokens on every use and the resolver nothing; `\explain` is for a compound
+ * or a colliding glyph.
+ */
+declare function redundantExplainWraps(latex: string, scope: readonly ScopeEntry[], options?: {
+    readonly suspended?: readonly string[];
+    readonly derive?: boolean;
+}): {
+    key: string;
+    inner: string;
+    index: number;
+}[];
 declare function pageScope(lesson: NotationLessonInput, sharedByKey: ReadonlyMap<string, ScopeEntry>): ScopeEntry[];
 /**
  * The `\label{eq:…}` a math source carries, as a key plus the anchor the
@@ -136,4 +163,4 @@ declare function gateContentMath(input: {
     readonly lessonAssessments: readonly LessonAssessmentLink[];
 }): MathGateDiagnostic[];
 
-export { type AssessmentItemLike, type AssessmentLike, type EquationLink, type LessonAssessmentLink, type MathGateDiagnostic, type MathSpan, type ScopeEntry, currencyDollars, equationLinkFor, gateContentMath, mathSpans, pageScope, scopeEntry, suspendedOperators };
+export { type AssessmentItemLike, type AssessmentLike, type EquationLink, type LessonAssessmentLink, type MathGateDiagnostic, type MathSpan, type ScopeEntry, currencyDollars, equationLinkFor, explainCalls, gateContentMath, mathSpans, pageScope, redundantExplainWraps, scopeEntry, scopeLocals, suspendedOperators };

package/dist/reference/gate-math.js

@@ -1,4 +1,4 @@
-import { resolveMathGlyphs, GlyphResolutionError } from "./math-glyphs.mjs";
+import { resolveMathGlyphs, GlyphResolutionError, fixedLenderMessage, mathExcerpt } from "./math-glyphs.mjs";
 import {
   EQ_LABEL_PATTERN,
   equationAnchorId,
@@ -7,6 +7,7 @@ import {
 import { lintDelimiterSizes } from "./delimiter-size.js";
 import { formulaGlyphScope, unknownFormulaScopeKeys } from "./gloss.js";
 import { blankPropStrings } from "./gate-prop-text.js";
+import { REGISTRY_BODY_FIX, registryGlyphScope } from "./registry-scope.mjs";
 const SEVERITY = {
   body: "error",
   formula: "error",
@@ -55,10 +56,40 @@ function scopeEntry(definition) {
     ...definition.fixedIndex ? { fixedIndex: true } : {}
   };
 }
+function scopeLocals(lesson) {
+  const inherited = lesson.inheritedLocalDefinitions ?? [];
+  return inherited.length === 0 ? lesson.localDefinitions : [...lesson.localDefinitions, ...inherited];
+}
+const EXPLAIN_CALL = /\\explain\{([^{}]+)\}\{((?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*)\}/g;
+function explainCalls(latex) {
+  return [...latex.matchAll(EXPLAIN_CALL)].map((match) => ({
+    key: match[1],
+    inner: match[2],
+    index: match.index ?? 0
+  }));
+}
+function redundantExplainWraps(latex, scope, options = {}) {
+  const redundant = [];
+  for (const call of explainCalls(latex)) {
+    let bare;
+    try {
+      bare = resolveMathGlyphs(call.inner, [...scope], {
+        suspended: options.suspended ?? [],
+        derive: options.derive ?? false
+      });
+    } catch {
+      continue;
+    }
+    if (bare.unresolved.length === 0 && bare.bindings.length > 0 && bare.bindings.every((binding) => binding.key === call.key && binding.level !== "explicit") && bare.decorations.every((decoration) => decoration.wholeForm !== null || decoration.operator !== null)) {
+      redundant.push(call);
+    }
+  }
+  return redundant;
+}
 function pageScope(lesson, sharedByKey) {
-  const local = lesson.localDefinitions.map(scopeEntry);
+  const local = scopeLocals(lesson).map(scopeEntry);
   const localKeys = new Set(local.map((entry) => entry.key));
-  const referenced = /* @__PURE__ */ new Set();
+  const referenced = new Set(lesson.inheritedKeys ?? []);
   for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
     for (const match of lesson.body.matchAll(pattern)) referenced.add(match[1]);
   }
@@ -117,6 +148,21 @@ function resolveInto(latex, scope, context, file, line, column, fix, out, equati
     });
     return;
   }
+  if (context !== "formula") {
+    for (const wrap of redundantExplainWraps(stripEquationLabels(latex), scope, { suspended, derive })) {
+      out.push({
+        context,
+        code: "explain-redundant",
+        severity: "info",
+        file,
+        line,
+        ...column === void 0 ? {} : { column },
+        token: wrap.inner,
+        ...at,
+        message: `\\explain{${wrap.key}}{${wrap.inner}} wraps what ${wrap.inner} already resolves to on this page; write it bare \u2014 \\explain is for a compound or a colliding glyph (rule N4)`
+      });
+    }
+  }
   for (const item of result.unresolved) {
     const { token } = item;
     if ("suspended" in item && typeof item.suspended === "string") {
@@ -133,7 +179,12 @@ function resolveInto(latex, scope, context, file, line, column, fix, out, equati
       continue;
     }
     const fontHint = "font" in item && typeof item.font === "string" ? ` ${token} is a different symbol from the plain letter: give it its own entry (latex: ${token}) or wrap it in \\explain{key}{${token}}.` : "";
-    const lenderHint = "lenders" in item && Array.isArray(item.lenders) && item.lenders.length > 0 ? ` ${item.lenders.join(", ")} ${item.lenders.length === 1 ? "has" : "have"} ${token} with a subscript, and an indexed entry explains its own instances only, never a bare ${token} (rule N4). If ${token} is a different object, give it its own entry (latex: ${token}); if it is shorthand for that entry, wrap it in \\explain{${item.lenders[0]}}{${token}}.` : "";
+    const fixedLenders = "fixedLenders" in item && Array.isArray(item.fixedLenders) ? item.fixedLenders : [];
+    const instance = "instance" in item && typeof item.instance === "string" ? item.instance : token;
+    const fixedHint = fixedLenders.map((lender) => ` ${fixedLenderMessage(lender, instance)}`).join("");
+    const fixedKeys = new Set(fixedLenders.map((lender) => lender.key));
+    const lenders = "lenders" in item && Array.isArray(item.lenders) ? item.lenders.filter((key) => !fixedKeys.has(key)) : [];
+    const lenderHint = lenders.length > 0 ? ` ${lenders.join(", ")} ${lenders.length === 1 ? "has" : "have"} ${token} with a subscript, and an indexed entry explains its own instances only, never a bare ${token} (rule N4). If ${token} is a different object, give it its own entry (latex: ${token}); if it is shorthand for that entry, wrap it in \\explain{${lenders[0]}}{${token}}.` : "";
     out.push({
       context,
       code: "unresolved-glyph",
@@ -142,7 +193,7 @@ function resolveInto(latex, scope, context, file, line, column, fix, out, equati
       line,
       token,
       ...at,
-      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math.${fontHint}${lenderHint} ${fix}`
+      message: `Unresolved notation ${JSON.stringify(token)} in ${context} math, in ${mathExcerpt(latex)}.${fontHint}${fixedHint}${lenderHint} ${fix}`
     });
   }
 }
@@ -170,6 +221,21 @@ function currencyDollars(body) {
   });
   return spans;
 }
+function reportCurrencyDollars(body, file, bodyOffset, out) {
+  for (const span of currencyDollars(body)) {
+    const shown = span.latex.replace(/\s+$/, "");
+    out.push({
+      context: "body",
+      code: "currency-dollar",
+      severity: SEVERITY.body,
+      file,
+      line: span.line + bodyOffset,
+      column: span.column,
+      token: `$${span.latex}$`,
+      message: `"$${span.latex}$" reads as math: remark-math pairs any two dollars on a line, so the page shows "${shown}" without them. Write a currency dollar as \\$ (\\$5 to \\$6), or the amount in words.`
+    });
+  }
+}
 const BODY_FIX = "Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.";
 function dedupeScope(scope) {
   const seen = /* @__PURE__ */ new Set();
@@ -251,19 +317,7 @@ function gateContentMath(input) {
         true
       );
     }
-    for (const span of currencyDollars(lesson.body)) {
-      const shown = span.latex.replace(/\s+$/, "");
-      diagnostics.push({
-        context: "body",
-        code: "currency-dollar",
-        severity: SEVERITY.body,
-        file,
-        line: span.line + bodyOffset,
-        column: span.column,
-        token: `$${span.latex}$`,
-        message: `"$${span.latex}$" reads as math: remark-math pairs any two dollars on a line, so the page shows "${shown}" without them. Write a currency dollar as \\$ (\\$5 to \\$6), or the amount in words.`
-      });
-    }
+    reportCurrencyDollars(lesson.body, file, bodyOffset, diagnostics);
     for (const definition of lesson.localDefinitions) {
       if (!definition.formula) continue;
       resolveInto(
@@ -285,6 +339,30 @@ function gateContentMath(input) {
       reportUnknownScopeKeys(definition, cardKeys, file, diagnostics);
     }
   }
+  const registryScope = registryGlyphScope(
+    notationInput.sharedDefinitions
+  );
+  for (const definition of notationInput.sharedDefinitions) {
+    const file = definition.source.file;
+    const bodyOffset = (definition.bodyLine ?? 1) - 1;
+    for (const span of mathSpans(definition.body)) {
+      resolveInto(
+        span.latex,
+        registryScope,
+        "body",
+        file,
+        span.line + bodyOffset,
+        span.column,
+        REGISTRY_BODY_FIX,
+        diagnostics,
+        void 0,
+        // An entry's body suspends nothing and derives no cards.
+        [],
+        false
+      );
+    }
+    reportCurrencyDollars(definition.body, file, bodyOffset, diagnostics);
+  }
   for (const definition of notationInput.sharedDefinitions) {
     if (!definition.formula) continue;
     resolveInto(
@@ -349,9 +427,12 @@ function gateContentMath(input) {
 export {
   currencyDollars,
   equationLinkFor,
+  explainCalls,
   gateContentMath,
   mathSpans,
   pageScope,
+  redundantExplainWraps,
   scopeEntry,
+  scopeLocals,
   suspendedOperators
 };

package/dist/reference/gate-part-pages.d.ts

@@ -1,4 +1,4 @@
-import { i as NormalizedPartPages } from '../course-config-rRtME5UV.js';
+import { m as NormalizedPartPages } from '../course-config-BLtIdkei.js';
 import { MathGateDiagnostic } from './gate-math.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';

package/dist/reference/lab-katex-validate.d.ts

@@ -7,9 +7,12 @@
  * Starting at each lesson's own imports, this follows every relative import
  * — the course's visuals, wherever they live — and reports each file that
  * imports `katex` as `lab-katex-direct`, with the chain of imports that
- * reaches it. A package import (`explico/…`, `react`) is not followed:
- * explico's own KaTeX use is the seam. A type-only import and the KaTeX
- * stylesheet draw nothing and are not reported.
+ * reaches it. The answer is per lesson: a helper that three lessons reach is
+ * reported three times, each with that lesson's own chain, and a lesson that
+ * reaches none is clean — so `content check <lesson>` can say so. A package
+ * import (`explico/…`, `react`) is not followed: explico's own KaTeX use is
+ * the seam. A type-only import and the KaTeX stylesheet draw nothing and are
+ * not reported.
  *
  * `figure-symbols.ts` checks the same promise on the rendered page, which
  * also catches math a lab draws some other way.
@@ -20,7 +23,7 @@ interface LabKatexDiagnostic {
     readonly message: string;
     /** The file that imports `katex`, repository-relative. */
     readonly file: string;
-    /** The first lesson (by id) whose imports reach it. */
+    /** The lesson whose imports reach it; one diagnostic per lesson and file. */
     readonly lessonId: string;
 }
 interface LabKatexLessonInput {
@@ -35,8 +38,9 @@ interface LabKatexLessonInput {
  */
 declare function importSpecifiers(source: string): string[];
 /**
- * Each course file that a lesson's imports reach and that imports `katex`.
- * `root` is the repository root the lesson paths are relative to.
+ * Each course file that imports `katex`, once for every lesson whose imports
+ * reach it, by the shortest chain. `root` is the repository root the lesson
+ * paths are relative to.
  */
 declare function validateLabKatexImports(lessons: readonly LabKatexLessonInput[], root?: string): LabKatexDiagnostic[];
 

package/dist/reference/lab-katex-validate.js

@@ -44,18 +44,23 @@ function resolveRelative(fromFile, specifier) {
   return candidates.find(isFile);
 }
 function validateLabKatexImports(lessons, root = process.cwd()) {
+  const sources = /* @__PURE__ */ new Map();
   const read = (path) => {
-    try {
-      return readFileSync(path, "utf8");
-    } catch {
-      return void 0;
+    if (!sources.has(path)) {
+      try {
+        sources.set(path, readFileSync(path, "utf8"));
+      } catch {
+        sources.set(path, void 0);
+      }
     }
+    return sources.get(path);
   };
   const repoPath = (path) => relative(root, path).split(sep).join("/");
-  const diagnostics = /* @__PURE__ */ new Map();
-  const seen = /* @__PURE__ */ new Set();
+  const diagnostics = [];
   for (const lesson of [...lessons].sort((a, b) => a.lessonId.localeCompare(b.lessonId))) {
     const lessonPath = join(root, lesson.file);
+    const reported = /* @__PURE__ */ new Set();
+    const seen = /* @__PURE__ */ new Set();
     const queue = [
       { path: lessonPath, source: stripFencedCode(lesson.body), chain: [lesson.file] }
     ];
@@ -64,8 +69,9 @@ function validateLabKatexImports(lessons, root = process.cwd()) {
       for (const specifier of importSpecifiers(source)) {
         if (isKatexModule(specifier)) {
           const file = repoPath(path);
-          if (!diagnostics.has(file)) {
-            diagnostics.set(file, {
+          if (!reported.has(file)) {
+            reported.add(file);
+            diagnostics.push({
               code: "lab-katex-direct",
               severity: "error",
               file,
@@ -88,7 +94,9 @@ function validateLabKatexImports(lessons, root = process.cwd()) {
       }
     }
   }
-  return [...diagnostics.values()].sort((a, b) => a.file.localeCompare(b.file));
+  return diagnostics.sort(
+    (a, b) => a.file.localeCompare(b.file) || a.lessonId.localeCompare(b.lessonId)
+  );
 }
 export {
   importSpecifiers,

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

@@ -2,18 +2,44 @@ import { loadManifest } from "../compiler/manifest.js";
 import {
   bindScopeToPage,
   registerPageNotationDependencies,
-  routeIdFromLocals
+  routeIdFromLocals,
+  scopeLessonsOf
 } from "./page-notation.js";
 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 = "", component) {
-  const local = notation?.local ?? [];
+  const manifest = await loadManifest();
+  const routeId = component ? routeIdFromLocals(component.locals) : void 0;
+  const deck = routeId === void 0 ? void 0 : manifest.decks?.find(
+    (entry) => entry.slug === routeId && (entry.chapter !== void 0 || entry.part !== void 0)
+  );
+  const scopeLessons = deck ? scopeLessonsOf(manifest, deck.pageId) : [];
+  const lessonLocal = [];
+  for (const lessonId of scopeLessons) {
+    for (const definition of manifest.notation.definitions) {
+      if (definition.kind !== "local" || !definition.id.startsWith(`page:${lessonId}:`)) continue;
+      if (lessonLocal.some((known) => known.key === definition.key)) continue;
+      lessonLocal.push({
+        key: definition.key,
+        latex: definition.notation,
+        ...definition.fixedIndex ? { fixedIndex: true } : {}
+      });
+    }
+  }
+  const lessonKeys = scopeLessons.flatMap(
+    (lessonId) => (manifest.lessons.find((lesson) => lesson.id === lessonId)?.notation.bindings ?? []).map((binding) => binding.key)
+  );
+  const ownLocal = notation?.local ?? [];
+  const local = [
+    ...ownLocal,
+    ...lessonLocal.filter((definition) => !ownLocal.some((own) => own.key === definition.key))
+  ];
   const scope = local.map((definition) => ({
     key: definition.key,
     notation: definition.latex,
     ...definition.fixedIndex === true ? { fixedIndex: true } : {}
   }));
-  const referenced = /* @__PURE__ */ new Set();
+  const referenced = new Set(lessonKeys);
   const explicitlyExplained = /* @__PURE__ */ new Set();
   for (const pattern of [TERM_KEY, EXPLAIN_KEY]) {
     for (const match of body.matchAll(pattern)) {
@@ -22,7 +48,6 @@ async function labMathScope(notation, body = "", component) {
     }
   }
   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])
   );

package/dist/reference/math-glyphs.d.mts

@@ -97,6 +97,31 @@ export function indexDisplayLatex(latex: string): string;
  * @returns {boolean}
  */
 export function entryHasIndex(latex: string): boolean;
+/**
+ * The math span a finding sits in, as an author wrote it: `$…$`, whitespace
+ * collapsed, cut at 100 characters. A line number can drift (a loader that
+ * hands over a body, a generated file), but the span can be searched for, so a
+ * message that quotes it still leads to the spot.
+ *
+ * @param {string} latex
+ * @returns {string}
+ */
+export function mathExcerpt(latex: string): string;
+/**
+ * What to tell an author whose subscripted symbol a family would have
+ * explained, were its index not fixed (rule N23): the cause, and the repair
+ * that fits it. One sentence, for an unresolved item's `fixedLenders`.
+ *
+ * @param {{ key: string, via: string, card?: string, letter?: string }} lender
+ * @param {string} instance The subscripted symbol as written, `r_2`.
+ * @returns {string}
+ */
+export function fixedLenderMessage(lender: {
+    key: string;
+    via: string;
+    card?: string;
+    letter?: string;
+}, instance: string): string;
 /**
  * Resolve and annotate one KaTeX expression against a page's flat glyph table.
  * Source offsets in the result always refer to the original, unmodified LaTeX.