explico 0.13.1 → 0.15.0

package/src/reference/consistency.ts

@@ -9,7 +9,10 @@
  * snapshot. Nothing here changes content. 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
+ *   (a) glyph-unique-in-corpus       one rendered glyph → one shared meaning; a
+ *                                    local card or a gloss may reuse a letter
+ *   (a') definition-repeated         one local key declared in two lessons
+ *   (a'') meaning-repeated           one symbol and name defined at two sites, any tier
  *   (b) notation-units / units-vocab  every entry has units or `dimensionless`,
  *                                     unit strings drawn from a controlled vocab
  *   (f) weak-local                  a `notation.local` symbol used only in its
@@ -35,6 +38,7 @@
  * `src/content/resolution-report.ts`.
  */
 
+import type { LocalNotationDefinitionInput } from './types';
 import type {
   CourseAccents,
   CourseOperators,
@@ -70,7 +74,8 @@ export type ConsistencyCode =
   | 'units-vocab'
   | 'weak-local'
   | 'notation-source-locator'
-  | 'gloss-wants-promoting'
+  | 'definition-repeated'
+  | 'meaning-repeated'
   | 'card-wants-demoting'
   | 'gloss-name-shape'
   | 'operator-explained'
@@ -142,7 +147,7 @@ function mathSpans(body: string): MathSpan[] {
 
 // --- glyph regex for weak-local --------------------------------------
 
-function glyphMatcher(latex: string): RegExp | undefined {
+export function glyphMatcher(latex: string): RegExp | undefined {
   const trimmed = latex.trim();
   if (trimmed === '') return undefined;
   if (/^[A-Za-z]$/.test(trimmed)) {
@@ -175,15 +180,19 @@ function checkGlyphUniqueness(
     glyphs.set(trimmed, keys);
   };
 
+  // Shared cards only: a vocabulary glyph has one meaning across the course.
+  // A `notation.local` entry or a gloss that reuses a letter is the declared
+  // exception — the tier exists for that — so it is never recorded here;
+  // `definition-repeated` and `meaning-repeated` watch those for copies.
   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);
     }
   }
 
@@ -194,13 +203,16 @@ function checkGlyphUniqueness(
     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(', ')})`)
+      .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 — keep one card, or make the page-bound one a notation.local entry`,
     });
   }
 }
@@ -286,50 +298,134 @@ function checkNotationSourceLocator(
 }
 
 /**
- * The two-tier vocabulary needs both directions kept honest (D15).
+ * The tier model needs both directions kept honest (D15). A meaning is
+ * declared once: a shared card unless the letter already means something
+ * else in the course, and only then `notation.local` or a gloss. The sign
+ * that a meaning is not page-bound is that it got defined a second time —
+ * so the lints watch for copies, never for how often a symbol is used.
  *
- * A gloss is cheap on purpose, and cheapness invites copying: the same symbol
- * and name glossed on three cards is a shared meaning that should be a card,
- * reviewed once, with sources and a curriculum home. `GLOSS_PROMOTION_LIMIT`
- * is where "a letter this formula needs" stops being a plausible reading.
+ * `definition-repeated`: one local key declared in two or more lessons. Either
+ * it is one meaning, so it belongs in `content/notation/<key>.md` (every
+ * `[[key]]` keeps working), or it is two, so one needs another key. A deck
+ * inherits its chapters' entries rather than redeclaring them, so decks never
+ * count. When a shared card already owns the glyph, the entry is a reused
+ * letter (N4) and promoting it would put two shared cards on one glyph, so
+ * the message says that instead of "move one copy".
  */
-const GLOSS_PROMOTION_LIMIT = 3;
+function checkDefinitionRepeated(
+  input: ConsistencyInput,
+  out: ConsistencyDiagnostic[],
+): void {
+  const byKey = new Map<string, { lessonId: string; file: string; definition: LocalNotationDefinitionInput }[]>();
+  // A deck resolves in its chapters' scopes (`scopeLessonIds`) and is no
+  // declaration site of its own, whatever its frontmatter repeats.
+  const chapters = input.notationInput.lessons.filter((lesson) => lesson.scopeLessonIds === undefined);
+  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 = new Map<string, string>();
+  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'] as const).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 !== undefined && owner !== key
+        ? ` — 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} — <why>"), or, if they are two meanings, give one another key`
+        : ` — 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 checkGlossWantsPromoting(
+/**
+ * `meaning-repeated`: one symbol with one name defined at two or more sites,
+ * in any tier — a local card and a gloss, two glosses, a local card beside a
+ * shared card that already says it. A second definition of the same meaning
+ * is the signal that it is vocabulary; a shared card serves every site, and
+ * where one exists already the page should bind it instead.
+ */
+function checkMeaningRepeated(
   input: ConsistencyInput,
   out: ConsistencyDiagnostic[],
 ): void {
-  const owners = new Map<string, { label: string; keys: Set<string> }>();
-  const record = (
-    ownerKey: string,
-    gloss: { notation: string; label: string },
-  ) => {
-    const id = `${gloss.notation}\u0000${gloss.label.toLowerCase()}`;
-    const current = owners.get(id) ?? { label: gloss.label, keys: new Set() };
-    current.keys.add(ownerKey);
-    owners.set(id, current);
+  interface Site {
+    readonly tier: 'shared' | 'local' | 'gloss';
+    readonly key: string;
+    readonly where: string;
+  }
+  const normalize = (label: string) => label.toLowerCase().replace(/\s+/g, ' ').trim();
+  const groups = new Map<string, { notation: string; label: string; sites: Site[] }>();
+  const record = (notation: string, label: string, site: Site) => {
+    const id = `${notation.trim()}\u0000${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 !== undefined) continue; // a deck declares nothing of its own
     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('\u0000')[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;
+    // One local key copied across lessons is `definition-repeated`'s finding.
+    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
+          ? ` — ${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`
+          : ' — one shared card would serve every site; promote it and reference it'),
     });
   }
 }
@@ -726,7 +822,8 @@ const CHECKS: ((
   checkNotationUnits,
   checkWeakLocal,
   checkNotationSourceLocator,
-  checkGlossWantsPromoting,
+  checkDefinitionRepeated,
+  checkMeaningRepeated,
   checkCardWantsDemoting,
   checkGlossNameShape,
   checkOperatorExplained,
@@ -765,7 +862,8 @@ export function consistencyCounts(
     '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,