explico 0.13.1 → 0.15.0

package/dist/reference/consistency.js

@@ -54,14 +54,14 @@ function checkGlyphUniqueness(input, out) {
     glyphs.set(trimmed, keys);
   };
   for (const definition of input.registry.definitions) {
-    if (definition.kind === "local") {
-      record(definition.notation, definition.key, definition.lessonId);
+    if (definition.kind === "shared") {
+      record(definition.notation, definition.key, "");
     }
   }
   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);
+      if (definition?.kind === "shared") record(definition.notation, binding.key, bundle.lessonId);
     }
   }
   for (const [glyph, keys] of [...glyphs].sort(
@@ -69,12 +69,15 @@ function checkGlyphUniqueness(input, out) {
   )) {
     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("; ");
+    const detail = [...keys].sort(([a], [b]) => a.localeCompare(b)).map(([key, lessons]) => {
+      const bound = [...lessons].filter((lesson) => lesson !== "").sort();
+      return `${key} (${bound.length > 0 ? bound.join(", ") : "no lesson binds it"})`;
+    }).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}`
+      message: `glyph ${JSON.stringify(glyph)} is ${keys.size} shared cards: ${detail}; course vocabulary gives a glyph one meaning \u2014 keep one card, or make the page-bound one a notation.local entry`
     });
   }
 }
@@ -144,34 +147,84 @@ 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);
+function checkDefinitionRepeated(input, out) {
+  const byKey = /* @__PURE__ */ new Map();
+  const chapters = input.notationInput.lessons.filter((lesson) => lesson.scopeLessonIds === void 0);
+  for (const lesson of [...chapters].sort((a, b) => a.lessonId.localeCompare(b.lessonId))) {
+    for (const definition of lesson.localDefinitions) {
+      const list = byKey.get(definition.key) ?? [];
+      if (!list.some((entry) => entry.lessonId === lesson.lessonId)) {
+        list.push({ lessonId: lesson.lessonId, file: lesson.source.file, definition });
+      }
+      byKey.set(definition.key, list);
+    }
+  }
+  const sharedByGlyph = /* @__PURE__ */ new Map();
+  for (const definition of input.notationInput.sharedDefinitions) {
+    if (!sharedByGlyph.has(definition.notation.trim())) sharedByGlyph.set(definition.notation.trim(), definition.key);
+  }
+  for (const [key, copies] of [...byKey].sort(([a], [b]) => a.localeCompare(b))) {
+    if (copies.length < 2) continue;
+    if (input.lintIgnore.matches("definition-repeated", key)) continue;
+    const first = copies[0];
+    const differing = ["notation", "label", "summary", "units", "sources"].filter(
+      (field) => copies.some((copy) => JSON.stringify(copy.definition[field] ?? null) !== JSON.stringify(first.definition[field] ?? null))
+    );
+    const lessons = copies.map((copy) => copy.lessonId).sort();
+    const owner = sharedByGlyph.get(first.definition.notation.trim());
+    const advice = owner !== void 0 && owner !== key ? ` \u2014 its glyph is already shared card ${owner}'s, so it is a reused letter (rule N4) and promoting it would put two shared cards on one glyph (glyph-unique-in-corpus): keep the copies local and acknowledge them in lint-ignore.yml ("definition-repeated:${key} \u2014 <why>"), or, if they are two meanings, give one another key` : ` \u2014 move one copy to content/notation/${key}.md and delete the others: every [[${key}]] and \\explain{${key}} keeps working; if they are two meanings, give one another key`;
+    out.push({
+      code: "definition-repeated",
+      severity: "warning",
+      key,
+      lessonId: first.lessonId,
+      file: first.file,
+      count: copies.length,
+      message: `local entry ${key} (${first.definition.notation}) is declared in ${copies.length} lessons (${lessons.join(", ")}); ` + (differing.length === 0 ? "the copies agree" : `the copies differ in ${differing.join(", ")}`) + advice
+    });
+  }
+}
+function checkMeaningRepeated(input, out) {
+  const normalize = (label) => label.toLowerCase().replace(/\s+/g, " ").trim();
+  const groups = /* @__PURE__ */ new Map();
+  const record = (notation, label, site) => {
+    const id = `${notation.trim()}\0${normalize(label)}`;
+    const group = groups.get(id) ?? { notation: notation.trim(), label, sites: [] };
+    if (!group.sites.some((known) => known.tier === site.tier && known.key === site.key && known.where === site.where)) {
+      group.sites.push(site);
+    }
+    groups.set(id, group);
   };
   for (const definition of input.notationInput.sharedDefinitions) {
-    for (const gloss of definition.glosses) record(definition.key, gloss);
+    record(definition.notation, definition.label, { tier: "shared", key: definition.key, where: `card ${definition.key}` });
+    for (const gloss of definition.glosses) {
+      record(gloss.notation, gloss.label, { tier: "gloss", key: gloss.key, where: `gloss on ${definition.key}` });
+    }
   }
   for (const lesson of input.notationInput.lessons) {
+    if (lesson.scopeLessonIds !== void 0) continue;
     for (const definition of lesson.localDefinitions) {
-      for (const gloss of definition.glosses) record(definition.key, gloss);
+      record(definition.notation, definition.label, {
+        tier: "local",
+        key: definition.key,
+        where: `local ${definition.key} on ${lesson.lessonId}`
+      });
+      for (const gloss of definition.glosses) {
+        record(gloss.notation, gloss.label, { tier: "gloss", key: gloss.key, where: `gloss on ${definition.key} (${lesson.lessonId})` });
+      }
     }
   }
-  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;
+  for (const [, group] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
+    if (group.sites.length < 2) continue;
+    if (group.sites.every((site) => site.tier === "local" && site.key === group.sites[0].key)) continue;
+    if (input.lintIgnore.matches("meaning-repeated", group.notation)) continue;
+    const shared = group.sites.find((site) => site.tier === "shared");
     out.push({
-      code: "gloss-wants-promoting",
+      code: "meaning-repeated",
       severity: "info",
-      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`
+      glyph: group.notation,
+      count: group.sites.length,
+      message: `${group.notation} as ${JSON.stringify(group.label)} is defined ${group.sites.length} times: ${group.sites.map((site) => site.where).join("; ")}` + (shared ? ` \u2014 ${shared.key} is the shared card; bind it with [[${shared.key}]] (or \\explain{${shared.key}}{${group.notation}} in a formula) instead of declaring it again` : " \u2014 one shared card would serve every site; promote it and reference it")
     });
   }
 }
@@ -435,7 +488,8 @@ const CHECKS = [
   checkNotationUnits,
   checkWeakLocal,
   checkNotationSourceLocator,
-  checkGlossWantsPromoting,
+  checkDefinitionRepeated,
+  checkMeaningRepeated,
   checkCardWantsDemoting,
   checkGlossNameShape,
   checkOperatorExplained,
@@ -457,7 +511,8 @@ function consistencyCounts(diagnostics) {
     "units-vocab": 0,
     "weak-local": 0,
     "notation-source-locator": 0,
-    "gloss-wants-promoting": 0,
+    "definition-repeated": 0,
+    "meaning-repeated": 0,
     "card-wants-demoting": 0,
     "gloss-name-shape": 0,
     "operator-explained": 0,
@@ -473,5 +528,6 @@ function consistencyCounts(diagnostics) {
 }
 export {
   consistencyCounts,
+  glyphMatcher,
   runConsistencyChecks
 };

package/dist/reference/deck-remark.d.mts

@@ -0,0 +1,123 @@
+/**
+ * The deck a docs file is, or `undefined`. A lesson's: `{ scope: 'lesson',
+ * lessonSlug, lessonId, path, chapterPath }`, the chapter being the lesson's
+ * `.mdx` (or `.md`) beside it. A part's (`<part>/index.deck.mdx`): `{ scope:
+ * 'part', partDir, pageId, path }`, its page id `<part>.slides`.
+ */
+export function deckOfFile(file: any): {
+    scope: string;
+    path: string;
+    partDir: string;
+    pageId: string;
+} | {
+    chapterPath?: string | undefined;
+    scope: string;
+    path: string;
+    lessonSlug: string;
+    lessonId: string;
+    partDir?: undefined;
+    pageId?: undefined;
+} | undefined;
+/**
+ * The chapter file of a lesson of a part's deck's part (`motion/range` →
+ * `…/motion/range.mdx`, or `.md`), beside the deck, if there is one.
+ */
+export function partChapterPath(deck: any, lessonSlug: any): string | undefined;
+/**
+ * The chapter files whose scope a deck's symbols bind in, in order: a
+ * lesson's deck its chapter (none for a slides-first lesson); a part's deck
+ * every chapter of its part, in reading order (`manifest.parts[].lessons`).
+ */
+export function deckScopeChapters(deck: any, manifest: any): any;
+/** A chapter file's frontmatter and body, read once per change of the file. */
+export function readChapter(chapterPath: any): any;
+/**
+ * The manifest's deck for a deck file (`deckOfFile`) — a lesson's or a
+ * part's — or, given a lesson id, for that lesson, if there is one.
+ */
+export function manifestDeckOf(manifest: any, owner: any): any;
+/**
+ * Replace each `<Recall ref="eq-…" />` (or `fig-`, `tab-`, `dia-`) with the
+ * chapter's own float, parsed from the chapter with this page's parser.
+ * A recalled equation's math node and a recalled float's element carry
+ * `data.explicoRecall = { prefix, key, number, href }`; the imports a
+ * recalled float's components need are added to the deck's own.
+ */
+/**
+ * What MDX's compile does to a tree before any course plugin sees it: a
+ * paragraph holding only JSX (and white space) becomes that JSX, as flow.
+ * An inline SVG's `<text x="…">0</text>` line parses as such a paragraph;
+ * kept, it would put a `<p>` inside the `<svg>`. `processor.parse` stops
+ * short of that step, so a chapter read for a recall takes it here
+ * (`remark-mark-and-unravel` in `@mdx-js/mdx`).
+ */
+export function unravelJsxParagraphs(tree: any): any;
+export function expandRecalls(tree: any, { processor, deck, deckEntry, manifest, base, fail }: {
+    processor: any;
+    deck: any;
+    deckEntry: any;
+    manifest: any;
+    base: any;
+    fail: any;
+}): void;
+/**
+ * The deck page's equations and floats, in its reading order, and what each
+ * shows: a recalled one the chapter's number, a labelled equation of the
+ * deck its own (1), (2) in label order (`manifest.decks[].equations`), and
+ * the deck's own floats no number.
+ */
+export function collectDeckFloats(tree: any, deckEntry: any): {
+    equations: Map<any, any>;
+    floats: Map<any, any>;
+};
+/**
+ * Give the deck's `##` and `###` headings the anchors and frame numbers the
+ * manifest decided, in order; a different count fails the build (a stale
+ * manifest), as a chapter's headings do.
+ */
+export function stampDeckHeadings(tree: any, deckEntry: any, fail: any): void;
+/**
+ * On a part's deck, give each `<AssessmentSet>` the lesson whose checks it
+ * asks (`lesson`, the component's prop): the chapter its frame's section
+ * covers (`frames[].chapter`). A frame in no such section asks none, which
+ * the manifest reports as `deck-check-no-chapter`.
+ */
+export function markDeckChecks(tree: any, deckEntry: any, fail: any): void;
+/**
+ * The generated title frame: the deck's title, its course, its authors and
+ * the version its content is at (rules D10 and C5), in the words of a
+ * chapter's PDF (`versionPhrase` in compiler/page-versions.ts).
+ */
+export function titleFrameNode(manifest: any, deckEntry: any): {
+    type: string;
+    data: {
+        hName: any;
+        hProperties: any;
+    };
+    children: any[];
+};
+/**
+ * The competencies a deck's outcomes frame lists: its lesson's, or on a
+ * part's deck every covered chapter's, in reading order, each once.
+ */
+export function deckTeaches(manifest: any, deckEntry: any): any;
+/** The generated outcomes frame: what the lesson's competencies say a student can now do. */
+export function outcomesFrameNode(manifest: any, deckEntry: any, lesson: any): {
+    type: string;
+    data: {
+        hName: any;
+        hProperties: any;
+    };
+    children: any[];
+} | undefined;
+/**
+ * After notation ran: give each `###` frame its legend line — the symbols it
+ * shows for the first time in the deck (`first-use`), or all it shows
+ * (`every-frame`) — as math the page's KaTeX pass renders, each symbol bound
+ * to its card. `resolved` is the page's resolved notation (`key → entry`).
+ */
+export function insertLegends(tree: any, { resolved, mode }: {
+    resolved: any;
+    mode: any;
+}): void;
+export const DECK_CAPTION_PATTERN: RegExp;