explico 0.3.0 → 0.5.0

package/src/reference/gate-prose-notation.ts

@@ -0,0 +1,224 @@
+/**
+ * The plain-text-notation gate (rule N9), run from the CLI alongside the
+ * completeness gate (`gate-math.ts`). Where that gate asks "does every glyph
+ * *inside* `$…$` resolve", this one asks the complementary question: "is
+ * anything that reads as math sitting *outside* `$…$` in the first place" —
+ * a unit abbreviation, a division of two variable-like symbols, an escaped
+ * absolute-value bar, a hand-typed sub/superscript. Both gates share one
+ * `MathGateDiagnostic` shape and one output array (`manifest.diagnostics.math`)
+ * so the CLI needs no separate wiring.
+ *
+ * Two entry points, one set of checks (`findingsIn`): `gateProseNotation`
+ * scans `lesson.body` with fenced/inline code and every `$…$` / `$$…$$` span
+ * already blanked out (same `stripCode` + math-span erasure `gate-math.ts`
+ * uses), so it only ever sees prose and table cells. `gateProseNotationInAssessments`
+ * scans an assessment item's `prompt` / `explanation` the same way — a plain
+ * JSON string field, not Markdown, but one that renders through the same
+ * KaTeX pipeline as a lesson body since `AssessmentRunner` picked it up
+ * (`mixed-content.ts`), so the same rule applies.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import type { NotationLessonInput } from './types';
+
+interface AssessmentItemLike {
+  readonly id?: string;
+  readonly prompt?: string;
+  readonly explanation?: string;
+}
+interface AssessmentLike {
+  readonly id: string;
+  readonly items?: readonly AssessmentItemLike[];
+}
+
+const CODE_FENCE = /```[\s\S]*?```/g;
+const INLINE_CODE = /(^|[^`])`[^`\n]*`/g;
+const DISPLAY_MATH = /\$\$([\s\S]+?)\$\$/g;
+const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
+// MDX `import … from '…/…'` lines: the path's `/` is a module separator, not
+// a division of two symbols.
+const IMPORT_LINE = /^[ \t]*import\b[^\n]*$/gm;
+// `[[key]]` / `[[slug/lesson#anchor]]` reference syntax: never prose math,
+// and a cross-page slug legitimately contains a `/`.
+const KEY_REFERENCE = /\[\[[^\]\n]*\]\]/g;
+// A JSX tag, opening through its matching `>` — may span several lines when
+// each prop is on its own line. Component prop strings (`caption="…"`,
+// `title="…"`) are plain display text with no math rendering at all (Figure
+// and Table hand their `caption` straight to the DOM as a string), so N9
+// does not apply inside one — enforcing "use $…$" somewhere it can't render
+// would just break the caption instead of fixing it.
+const JSX_TAG = /<\/?[A-Za-z][^<>]*>/g;
+
+/**
+ * Blank code, math, reference, and JSX-tag spans so offsets don't shift.
+ * Exported so `gate-abbreviations.ts` (N14) scans exactly the same "is this
+ * really prose" surface as N9, instead of drifting with a second copy of
+ * these regexes.
+ */
+export function proseOnly(body: string): string {
+  const blank = (match: string) => match.replace(/[^\n]/g, ' ');
+  return body
+    .replace(CODE_FENCE, blank)
+    .replace(INLINE_CODE, (match, lead: string) => lead + blank(match.slice(lead.length)))
+    .replace(DISPLAY_MATH, blank)
+    .replace(INLINE_MATH, blank)
+    .replace(IMPORT_LINE, blank)
+    .replace(KEY_REFERENCE, blank)
+    .replace(JSX_TAG, blank);
+}
+
+/** Exported for the same reason as {@link proseOnly}. */
+export function lineOf(text: string, index: number): number {
+  return text.slice(0, index).split('\n').length;
+}
+
+// Symbolic/abbreviated unit tokens that must be typeset in `$…$`, longest
+// first so the alternation can't match a prefix of a longer unit.
+const UNIT = String.raw`m/s²|m/s|km/h|rad/s|m²/s²|J/kg|m²|s⁻¹|kg|N|J|W|Hz|deg|°|rad|m|s`;
+
+const NUMERAL_UNIT = new RegExp(
+  String.raw`(?<![\w.])-?\d+(?:\.\d+)?\s?(?:${UNIT})(?![A-Za-z])`,
+  'g',
+);
+const BARE_UNIT_PARENS = new RegExp(String.raw`\((?:${UNIT})\)`, 'g');
+
+// Idiomatic English slash constructs that are prose, not a division of two
+// symbols — reviewed and extended in the same PR that adds a new one, not by
+// a per-page suppression (there is no lint-ignore.yml entry for this gate;
+// see N9's "everything, no exceptions" scope).
+const SLASH_IDIOMS = new Set([
+  'and/or',
+  'his/her',
+  'him/her',
+  'he/she',
+  'she/he',
+  'on/off',
+  'yes/no',
+  'pass/fail',
+  'input/output',
+  'output/input',
+  'read/write',
+  'either/or',
+  'client/server',
+  'pre/post',
+  'a/b',
+]);
+const SLASH_TOKENS = /\b([A-Za-z]{1,6})\/([A-Za-z]{1,6})\b/g;
+
+// A `_` or `^` sitting directly between two alphanumerics reads as a
+// hand-typed sub/superscript that was never wrapped in `$…$`.
+const FAKE_SCRIPT = /[A-Za-z0-9][_^][A-Za-z0-9{]/g;
+
+interface Finding {
+  readonly index: number;
+  readonly token: string;
+  readonly message: string;
+}
+
+function findAll(text: string, pattern: RegExp, toFinding: (m: RegExpExecArray) => Finding): Finding[] {
+  const out: Finding[] = [];
+  const re = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(text))) {
+    out.push(toFinding(match));
+    if (match[0].length === 0) re.lastIndex++;
+  }
+  return out;
+}
+
+const FIX = 'Wrap it in $…$ (or $$…$$) instead — see docs/authoring/notation.md#n9.';
+
+/** Every N9 finding in one already-prose-only string, in source order. */
+function findingsIn(text: string): Finding[] {
+  return [
+    ...findAll(text, /\\\|/g, (m) => ({
+      index: m.index,
+      token: m[0],
+      message: `Escaped pipe ${JSON.stringify(m[0])} outside math. Use \\lvert…\\rvert for an absolute value or norm inside $…$, not an escaped table pipe. ${FIX}`,
+    })),
+    ...findAll(text, NUMERAL_UNIT, (m) => ({
+      index: m.index,
+      token: m[0].trim(),
+      message: `Numeral with a plain-text unit ${JSON.stringify(m[0].trim())} outside math. ${FIX}`,
+    })),
+    ...findAll(text, BARE_UNIT_PARENS, (m) => ({
+      index: m.index,
+      token: m[0],
+      message: `Plain-text unit ${JSON.stringify(m[0])} outside math. ${FIX}`,
+    })),
+    ...findAll(text, FAKE_SCRIPT, (m) => ({
+      index: m.index,
+      token: m[0],
+      message: `${JSON.stringify(m[0])} looks like a hand-typed sub/superscript outside math. ${FIX}`,
+    })),
+    ...findAll(text, SLASH_TOKENS, (m) => {
+      if (SLASH_IDIOMS.has(m[0].toLowerCase())) return null as unknown as Finding;
+      return {
+        index: m.index,
+        token: m[0],
+        message: `${JSON.stringify(m[0])} outside math reads as a division of two symbols/units, not English prose. If it really is prose, add the idiom to SLASH_IDIOMS in gate-prose-notation.ts (reviewed like any other rule change). ${FIX}`,
+      };
+    }).filter(Boolean),
+  ];
+}
+
+/**
+ * Scan every lesson body for plain-text math notation outside `$…$`. Returns
+ * one `MathGateDiagnostic` (context `'prose'`, always an error — N9 has no
+ * escape hatch) per finding.
+ */
+export function gateProseNotation(
+  lessons: readonly NotationLessonInput[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const lesson of lessons) {
+    const text = proseOnly(lesson.body);
+    for (const finding of findingsIn(text)) {
+      diagnostics.push({
+        context: 'prose',
+        severity: 'error',
+        file: lesson.source.file,
+        line: lineOf(lesson.body, finding.index),
+        token: finding.token,
+        message: finding.message,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+/**
+ * Scan every assessment `prompt` / `explanation` for the same plain-text
+ * notation N9 forbids in a lesson body — `AssessmentRunner` renders both
+ * through the same KaTeX pipeline now (`mixed-content.ts`), so text sitting
+ * outside `$…$` there is just as invisible to the reader's hover cards as it
+ * would be in a lesson. No line number: an assessment item is one JSON string
+ * field, not a multi-line source file, so `file` names the item instead —
+ * same `"<assessmentId> (<itemId>)"` shape `gate-math.ts` already uses for
+ * this context.
+ */
+export function gateProseNotationInAssessments(
+  assessments: readonly AssessmentLike[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+
+  for (const assessment of assessments) {
+    for (const item of assessment.items ?? []) {
+      for (const field of [item.prompt, item.explanation]) {
+        if (typeof field !== 'string') continue;
+        for (const finding of findingsIn(proseOnly(field))) {
+          diagnostics.push({
+            context: 'prose',
+            severity: 'error',
+            file: `${assessment.id} (${item.id ?? '?'})`,
+            token: finding.token,
+            message: finding.message,
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}

package/src/reference/keyed-float-validate.ts

@@ -6,13 +6,13 @@
  * - `<prefix>-invalid-key` (error): an `id` must match the key grammar.
  * - `<prefix>-duplicate-key` (error): an `id` is unique per lesson.
  * - `<prefix>-ref-resolves` (error): every `[[<prefix>-key]]` /
- *   `[[slug#<prefix>-key]]` points at a `<Table>`/`<Figure>` with that `id`.
+ *   `[[slug#<prefix>-key]]` points at the matching keyed float with that `id`.
  * - `<prefix>-key-unused` (warning): a keyed float never referenced.
  *
- * `tables-validate.ts` and `figures-validate.ts` are thin wrappers over this
- * so callers import `validateTables` / `validateFigures` with their own
- * narrow diagnostic-code types, while `equations-validate.ts` stays
- * untouched — equations predate this and keep their own dedicated path.
+ * `tables-validate.ts`, `figures-validate.ts`, and `diagrams-validate.ts` are
+ * thin wrappers over this so callers import a kind-specific validator with
+ * narrow diagnostic-code types, while `equations-validate.ts` stays untouched
+ * — equations predate this and keep their own dedicated path.
  */
 
 import {
@@ -69,10 +69,13 @@ export interface KeyedFloatLessonInput {
   readonly file: string;
   readonly body: string;
   /**
-   * The lesson's 1-based ordinal in the course. When set, floats are numbered
-   * `‹chapter›.‹n›`; when omitted, the legacy `##`-section scheme.
+   * `{ prefix, offset }` — the part's 1-based ordinal among the sidebar groups,
+   * and how many floats of this kind earlier lessons of that part already used.
+   * When set, floats are numbered `‹part›.‹offset + n›`; when omitted, the
+   * legacy `##`-section scheme. Each kind counts on its own, so the caller
+   * passes a different `offset` for `<Table>` than for `<Figure>`.
    */
-  readonly chapter?: number;
+  readonly numbering?: { readonly prefix: number; readonly offset: number };
 }
 
 const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
@@ -117,7 +120,7 @@ export function validateKeyedFloats(
     const table: Record<string, string> = {};
     for (const raw of scanKeyedJsxFloats(lesson.body, {
       tagName,
-      chapter: lesson.chapter,
+      numbering: lesson.numbering,
     }) as {
       key: string | null;
       number: string;

package/src/reference/keyed-jsx-floats.mjs

@@ -1,20 +1,20 @@
 /**
- * Keyed-float identity for a JSX-wrapped table or figure, shared between
- * `<Table>` and `<Figure>` (Step F-tables-figures).
+ * Keyed-float identity for a JSX-wrapped table, figure, or diagram, shared
+ * between `<Table>`, `<Figure>`, and `<Diagram>`.
  *
  * This mirrors `equations.mjs`, but the key comes from a plain `id` prop on
  * the wrapper component rather than a `\label{eq:key}` embedded in shared
- * LaTeX source — a `<Table>`/`<Figure>` is purpose-built, so there is no
+ * LaTeX source — a `<Table>`/`<Figure>`/`<Diagram>` is purpose-built, so there is no
  * ambiguity an embedded marker would need to resolve. An author writes the
  * bare key (`id="kinematics-summary"`); the rendered DOM id and the `[[…]]`
  * reference prefix are computed the same way `\label{eq:key}` becomes
- * `#eq-key` — `keyedFloatAnchorId` prepends `tab-`/`fig-`.
+ * `#eq-key` — `keyedFloatAnchorId` prepends `tab-`/`fig-`/`dia-`.
  *
- * Only top-level occurrences count, exactly like `collectDisplayEquations`:
- * a `<Table>` nested inside a `<CompactExample>` (or any other component) is
- * illustrative, not part of the lesson's official sequence, so both the
- * mdast walker and the raw-text scanner only look at the document's direct
- * top-level blocks.
+ * Only top-level occurrences count, exactly like `collectDisplayEquations`,
+ * except that `<Memo>` is transparent: a float in a memo remains a side-note
+ * in the lesson's reading order. A keyed float nested inside a
+ * `<CompactExample>` (or any other component) is illustrative, not part of the
+ * official sequence.
  *
  * `scanKeyedJsxFloats` (raw Markdown, for the manifest builder) and
  * `collectKeyedJsxFloats` (mdast, for `remark-notation.mjs`) MUST agree —
@@ -22,7 +22,11 @@
  * `equations.test.ts` holds equations to.
  */
 
-import { stripFencedCode, stripJsxComponents } from './equations.mjs';
+import {
+  resolveNumbering,
+  stripFencedCode,
+  stripJsxComponents,
+} from './equations.mjs';
 
 /** Same shape as `EQ_KEY_PATTERN` — the notation-key grammar without dots. */
 export const KEYED_FLOAT_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -33,15 +37,22 @@ function floatNumber(section, index) {
 }
 
 /**
- * The visible number for one float. With `chapter` (the lesson's course
- * ordinal) the scheme is `‹chapter›.‹indexInLesson›` and `##` headings are
- * ignored; without it, the legacy `##`-section scheme. Mirrors
- * `displayEquationNumber` in `equations.mjs`.
+ * The visible number for one float. With a `prefix` (the part's ordinal) the
+ * scheme is `‹part›.‹offset + indexInLesson›` and `##` headings are ignored;
+ * without it, the legacy `##`-section scheme. Mirrors `displayEquationNumber`
+ * in `equations.mjs`. Each kind of float counts on its own — a `<Table>` never
+ * advances the `<Figure>` or `<Diagram>` sequence — so `offset` is per kind too.
  */
-function keyedFloatNumber({ chapter, section, indexInSection, indexInLesson }) {
-  return chapter == null
+function keyedFloatNumber({
+  prefix,
+  offset = 0,
+  section,
+  indexInSection,
+  indexInLesson,
+}) {
+  return prefix == null
     ? floatNumber(section, indexInSection)
-    : `${chapter}.${indexInLesson}`;
+    : `${prefix}.${offset + indexInLesson}`;
 }
 
 /** The anchor id for a float, e.g. `{prefix:'tab', key:'foo'}` → `tab-foo`. */
@@ -71,14 +82,19 @@ function readIdAttribute(attributesSource) {
 /**
  * The raw-text equivalent of `collectKeyedJsxFloats`, mirroring
  * `scanEquationLabels`: every top-level `<TagName …>` in appearance order.
- * With `chapter` (the lesson's course ordinal) the number is `‹chapter›.‹n›`,
- * `n` sequential over the whole lesson; without it, `##` headings advance a
- * section counter. Other JSX components' bodies are blanked first so a
- * `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like text
- * inside an unrelated component) is never counted.
+ * With `numbering` (`{ prefix, offset }` — the part's ordinal and the count of
+ * this kind of float in earlier lessons of that part) the number is
+ * `‹part›.‹offset + n›`, `n` sequential over the whole lesson; without it, `##`
+ * headings advance a section counter. Other JSX components' bodies are blanked
+ * first so a `<Table>` nested inside e.g. `<CompactExample>` (and any `##`-like
+ * text inside an unrelated component) is never counted.
  */
-export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
-  const text = stripJsxComponents(stripFencedCode(markdown), tagName);
+export function scanKeyedJsxFloats(markdown, { tagName, numbering }) {
+  const { prefix, offset } = resolveNumbering(numbering);
+  const text = stripJsxComponents(stripFencedCode(markdown), tagName, [
+    'Memo',
+    'ShortNote',
+  ]);
   const tokens = [];
   const heading = /^[ \t]{0,3}##[ \t]+\S/gm;
   const opening = new RegExp(`<${tagName}\\b([^>]*)>`, 'g');
@@ -106,7 +122,8 @@ export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
     labels.push({
       key: token.key,
       number: keyedFloatNumber({
-        chapter,
+        prefix,
+        offset,
         section,
         indexInSection,
         indexInLesson,
@@ -119,26 +136,30 @@ export function scanKeyedJsxFloats(markdown, { tagName, chapter }) {
 }
 
 /**
- * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's *top-level*
- * children in document order, advancing the section counter on every
- * depth-2 heading and emitting a record for every `mdxJsxFlowElement` named
- * `tagName` — keyed or not, exactly like `collectDisplayEquations`. `chapter`
- * is threaded the same way as in `scanKeyedJsxFloats`.
+ * How many floats of this kind a lesson body holds — the input to the next
+ * lesson's `offset` within the same part.
  */
-export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
+export function countKeyedJsxFloats(markdown, { tagName }) {
+  return scanKeyedJsxFloats(markdown, { tagName }).length;
+}
+
+/**
+ * The mdast equivalent of `scanKeyedJsxFloats`: walk the tree's top-level
+ * children (and through `<Memo>` bodies) in document order, advancing the
+ * section counter on every top-level depth-2 heading and emitting a record for
+ * every `mdxJsxFlowElement` named `tagName` — keyed or not, exactly like
+ * `collectDisplayEquations`. `numbering` is threaded the same way as in
+ * `scanKeyedJsxFloats`.
+ */
+export function collectKeyedJsxFloats(tree, { tagName, numbering }) {
+  const { prefix, offset } = resolveNumbering(numbering);
   const floats = [];
   let section = 0;
   let indexInSection = 0;
   let indexInLesson = 0;
 
-  const children = Array.isArray(tree?.children) ? tree.children : [];
-  for (const node of children) {
-    if (!node || typeof node !== 'object') continue;
-    if (node.type === 'heading' && node.depth === 2) {
-      section += 1;
-      indexInSection = 0;
-      continue;
-    }
+  const collectFromDetail = (node) => {
+    if (!node || typeof node !== 'object') return;
     if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
       indexInSection += 1;
       indexInLesson += 1;
@@ -151,7 +172,8 @@ export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
       floats.push({
         key: key ?? null,
         number: keyedFloatNumber({
-          chapter,
+          prefix,
+          offset,
           section,
           indexInSection,
           indexInLesson,
@@ -160,8 +182,35 @@ export function collectKeyedJsxFloats(tree, { tagName, chapter }) {
         indexInSection,
         node,
       });
+      return;
+    }
+    if (
+      node.type === 'mdxJsxFlowElement' &&
+      node.name !== 'Memo' &&
+      node.name !== 'ShortNote'
+    ) {
+      return;
+    }
+    if (!Array.isArray(node.children)) return;
+    for (const child of node.children) collectFromDetail(child);
+  };
+
+  const children = Array.isArray(tree?.children) ? tree.children : [];
+  for (const node of children) {
+    if (!node || typeof node !== 'object') continue;
+    if (node.type === 'heading' && node.depth === 2) {
+      section += 1;
+      indexInSection = 0;
+      continue;
+    }
+    if (node.type === 'mdxJsxFlowElement' && node.name === tagName) {
+      collectFromDetail(node);
+    } else if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Memo' || node.name === 'ShortNote')
+    ) {
+      collectFromDetail(node);
     }
   }
   return floats;
 }
-

package/src/reference/knowledge-checks-validate.ts

@@ -0,0 +1,130 @@
+/** Build-time identity and reference validation for knowledge checks. */
+
+import {
+  collectKnowledgeChecks,
+  KNOWLEDGE_CHECK_KEY_PATTERN,
+  parseKnowledgeCheckRef,
+} from './knowledge-checks.mjs';
+
+export interface KnowledgeCheckLessonInput {
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly body: string;
+  readonly assessmentIds: readonly string[];
+  readonly numbering?: { readonly prefix: number; readonly offset: number };
+}
+
+export interface KnowledgeCheckLabelRecord {
+  readonly key: string;
+  readonly number: string;
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly indexInLesson: number;
+}
+
+export interface KnowledgeCheckDiagnostic {
+  readonly code:
+    | 'check-invalid-key'
+    | 'check-duplicate-key'
+    | 'check-ref-resolves';
+  readonly severity: 'error';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+  readonly key?: string;
+}
+
+export interface KnowledgeCheckValidation {
+  readonly labels: readonly KnowledgeCheckLabelRecord[];
+  readonly numbersBySlug: Record<string, Record<string, string>>;
+  readonly diagnostics: readonly KnowledgeCheckDiagnostic[];
+}
+
+const BRACKET_REF = /\[\[\s*([^\][]+?)\s*\]\]/g;
+
+function stripCode(text: string): string {
+  return text
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/~~~[\s\S]*?~~~/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ');
+}
+
+export function validateKnowledgeChecks(
+  lessons: readonly KnowledgeCheckLessonInput[],
+): KnowledgeCheckValidation {
+  const labels: KnowledgeCheckLabelRecord[] = [];
+  const diagnostics: KnowledgeCheckDiagnostic[] = [];
+  const numbersBySlug: Record<string, Record<string, string>> = {};
+
+  for (const lesson of [...lessons].sort((a, b) =>
+    a.lessonId.localeCompare(b.lessonId),
+  )) {
+    const seen = new Set<string>();
+    const table: Record<string, string> = {};
+    for (const check of collectKnowledgeChecks(
+      lesson.assessmentIds,
+      lesson.numbering,
+    )) {
+      if (!KNOWLEDGE_CHECK_KEY_PATTERN.test(check.key)) {
+        diagnostics.push({
+          code: 'check-invalid-key',
+          severity: 'error',
+          message: `${lesson.lessonId} has a knowledge-check id "${check.key}" that is not a valid content key.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: check.key,
+        });
+        continue;
+      }
+      if (seen.has(check.key)) {
+        diagnostics.push({
+          code: 'check-duplicate-key',
+          severity: 'error',
+          message: `${lesson.lessonId} lists knowledge check "${check.key}" twice; an assessment id is unique per lesson.`,
+          file: lesson.file,
+          lessonId: lesson.lessonId,
+          key: check.key,
+        });
+        continue;
+      }
+      seen.add(check.key);
+      table[check.key] = check.number;
+      labels.push({
+        ...check,
+        lessonId: lesson.lessonId,
+        slug: lesson.slug,
+      });
+    }
+    numbersBySlug[lesson.slug] = table;
+  }
+
+  for (const lesson of lessons) {
+    for (const match of stripCode(lesson.body).matchAll(BRACKET_REF)) {
+      const ref = parseKnowledgeCheckRef((match[1] ?? '').trim());
+      if (!ref) continue;
+      const targetSlug = ref.lesson ?? lesson.slug;
+      if (numbersBySlug[targetSlug]?.[ref.key] !== undefined) continue;
+      diagnostics.push({
+        code: 'check-ref-resolves',
+        severity: 'error',
+        message: ref.lesson
+          ? `${lesson.lessonId} references [[${ref.lesson}#check-${ref.key}]] but that lesson has no knowledge check "${ref.key}"`
+          : `${lesson.lessonId} references [[check-${ref.key}]] but its .checks.yml does not list "${ref.key}"`,
+        file: lesson.file,
+        lessonId: lesson.lessonId,
+        key: ref.key,
+      });
+    }
+  }
+
+  diagnostics.sort(
+    (a, b) =>
+      a.code.localeCompare(b.code) ||
+      (a.lessonId ?? '').localeCompare(b.lessonId ?? '') ||
+      (a.key ?? '').localeCompare(b.key ?? '') ||
+      a.message.localeCompare(b.message),
+  );
+
+  return { labels, numbersBySlug, diagnostics };
+}

package/src/reference/knowledge-checks.mjs

@@ -0,0 +1,45 @@
+/**
+ * Stable identity and numbering helpers for lesson knowledge checks.
+ *
+ * A course owns check titles and questions in `content/assessments/*.json`,
+ * then places their ids in a lesson's colocated `.checks.yml`. That ordered
+ * list is the check sequence: numbers run independently across each part,
+ * exactly like the equation/table/figure/diagram streams.
+ */
+
+/** Assessment ids use the content key grammar, including optional dots. */
+export const KNOWLEDGE_CHECK_KEY_PATTERN =
+  /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+/** `[[check-id]]`, or `[[lesson/slug#check-id]]` across pages. */
+export function parseKnowledgeCheckRef(raw) {
+  const match =
+    /^(?:([a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*)#)?check-([a-z0-9]+(?:[.-][a-z0-9]+)*)$/.exec(
+      String(raw).trim(),
+    );
+  if (!match) return undefined;
+  return match[1] ? { lesson: match[1], key: match[2] } : { key: match[2] };
+}
+
+/** The stable DOM fragment for a knowledge check. */
+export function knowledgeCheckAnchorId(key) {
+  return `check-${key}`;
+}
+
+/**
+ * Number an ordered assessment-id list. With manifest placement, the number
+ * is `part.offset + index`; without it, the list remains usefully page-local.
+ */
+export function collectKnowledgeChecks(assessmentIds, numbering) {
+  const prefix = Number.isInteger(numbering?.prefix) && numbering.prefix > 0
+    ? numbering.prefix
+    : undefined;
+  const offset = Number.isInteger(numbering?.offset) && numbering.offset >= 0
+    ? numbering.offset
+    : 0;
+  return assessmentIds.map((key, index) => ({
+    key,
+    number: prefix == null ? String(index + 1) : `${prefix}.${offset + index + 1}`,
+    indexInLesson: index + 1,
+  }));
+}