explico 0.4.0 → 0.6.0

package/src/reference/mdx-attributes.mjs

@@ -0,0 +1,38 @@
+/**
+ * Replace computed string attributes on an MDX JSX node without disturbing
+ * author-owned props. Remark adapters use this when the build, rather than the
+ * author, owns values such as a visible number or DOM anchor.
+ *
+ * @param {object} node
+ * @param {Record<string, string>} values
+ */
+export function injectMdxStringAttributes(node, values) {
+  const names = new Set(Object.keys(values));
+  node.attributes = (node.attributes ?? []).filter(
+    (attribute) =>
+      !(
+        attribute?.type === 'mdxJsxAttribute' &&
+        typeof attribute.name === 'string' &&
+        names.has(attribute.name)
+      ),
+  );
+  for (const [name, value] of Object.entries(values)) {
+    node.attributes.push({ type: 'mdxJsxAttribute', name, value });
+  }
+}
+
+/** Return every ordinary MDX JSX attribute with `name`. */
+export function mdxAttributesNamed(node, name) {
+  return (node?.attributes ?? []).filter(
+    (attribute) =>
+      attribute?.type === 'mdxJsxAttribute' && attribute.name === name,
+  );
+}
+
+/** Remove an internal adapter-owned attribute from an MDX JSX node. */
+export function removeMdxAttribute(node, name) {
+  node.attributes = (node.attributes ?? []).filter(
+    (attribute) =>
+      !(attribute?.type === 'mdxJsxAttribute' && attribute.name === name),
+  );
+}

package/src/reference/mixed-content.ts

@@ -0,0 +1,69 @@
+/**
+ * Split a plain string that mixes prose and `$…$` / `$$…$$` math into an
+ * ordered list of text and math segments, resolving each math span's glyphs
+ * against a page scope on the way — the shared step behind rendering an
+ * assessment `prompt` / `explanation` through the same KaTeX pipeline as
+ * lesson body math (`AssessmentSet.astro` calls `renderNotationMath` on each
+ * `math` segment's `latex`; nothing here touches KaTeX itself).
+ *
+ * Unlike `gate-math.ts`'s `mathSpans` (which only needs the math, for
+ * diagnostics), this keeps the surrounding text too, in order, since the
+ * caller has to reproduce the original sentence around the rendered math.
+ *
+ * Resolution failure is swallowed here, not thrown: a bad span falls back to
+ * its own raw source as a `math` segment KaTeX will very likely also reject,
+ * degrading the one span instead of crashing manifest compilation. The actual
+ * enforcement — failing the build — is `gate-math.ts`'s job (context
+ * `'assessment'`) and `gate-prose-notation.ts`'s (context `'prose'`); this
+ * module's contract is "never throw", so a manifest build never depends on
+ * content being clean to finish running.
+ */
+import { resolveMathGlyphs } from './math-glyphs.mjs';
+import type { ScopeEntry } from './gate-math';
+
+export type ContentSegment =
+  | { readonly type: 'text'; readonly value: string }
+  | { readonly type: 'math'; readonly latex: string };
+
+// Byte-identical to `gate-math.ts`'s `DISPLAY_MATH` / `INLINE_MATH` — both
+// scan the same author-facing `$…$` syntax and must agree on what counts as
+// a span. Assessment prompt/explanation strings have no code fences or MDX
+// to strip first, unlike a lesson body, so there is no shared `stripCode`
+// step to reuse here.
+const MATH_SPAN =
+  /\$\$([\s\S]+?)\$\$|(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
+
+/**
+ * Split `text` into ordered segments, resolving each math span's glyphs
+ * against `scope`. Never throws.
+ */
+export function splitMixedContent(
+  text: string,
+  scope: readonly ScopeEntry[],
+): ContentSegment[] {
+  const segments: ContentSegment[] = [];
+  let cursor = 0;
+  const pattern = new RegExp(MATH_SPAN);
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(text))) {
+    if (match.index > cursor) {
+      segments.push({ type: 'text', value: text.slice(cursor, match.index) });
+    }
+    const raw = match[1] ?? match[2] ?? '';
+    let latex = raw;
+    try {
+      latex = resolveMathGlyphs(raw, [...scope]).latex;
+    } catch {
+      latex = raw;
+    }
+    segments.push({ type: 'math', latex });
+    cursor = match.index + match[0].length;
+  }
+
+  if (cursor < text.length) {
+    segments.push({ type: 'text', value: text.slice(cursor) });
+  }
+
+  return segments;
+}

package/src/reference/page-notation.ts

@@ -0,0 +1,252 @@
+import type { Manifest, ManifestLessonNotation } from '../compiler/manifest';
+import {
+  formulaExplainKeys,
+  formulaGlyphScope,
+  type GlyphScopeEntry,
+} from './gloss';
+import { resolveReferenceId } from './references';
+import type { NotationDefinitionRecord } from './types';
+
+export interface PageNotationDependency {
+  readonly key: string;
+  readonly context: string;
+}
+
+interface StarlightLocals {
+  readonly starlightRoute?: {
+    readonly entry?: { readonly id?: unknown };
+  };
+}
+
+const dependenciesByLocals = new WeakMap<object, Map<string, Set<string>>>();
+
+/**
+ * Record notation keys emitted by a nested server component for this request.
+ * The request-local collector is deliberately keyed by `Astro.locals`: static
+ * builds render pages concurrently, so a process-global set would leak symbols
+ * between lessons and defeat page-local notation scope.
+ */
+export function registerPageNotationDependencies(
+  locals: object,
+  keys: Iterable<string>,
+  context: string,
+): void {
+  let byKey = dependenciesByLocals.get(locals);
+  if (!byKey) {
+    byKey = new Map();
+    dependenciesByLocals.set(locals, byKey);
+  }
+
+  for (const key of keys) {
+    let contexts = byKey.get(key);
+    if (!contexts) {
+      contexts = new Set();
+      byKey.set(key, contexts);
+    }
+    contexts.add(context);
+  }
+}
+
+export function pageNotationDependencies(
+  locals: object,
+): PageNotationDependency[] {
+  const byKey = dependenciesByLocals.get(locals);
+  if (!byKey) return [];
+  return [...byKey]
+    .flatMap(([key, contexts]) =>
+      [...contexts].map((context) => ({ key, context })),
+    )
+    .sort(
+      (left, right) =>
+        left.key.localeCompare(right.key) ||
+        left.context.localeCompare(right.context),
+    );
+}
+
+/** Starlight's route id as exposed to nested Astro components. */
+export function routeIdFromLocals(locals: object): string | undefined {
+  const id = (locals as StarlightLocals).starlightRoute?.entry?.id;
+  return typeof id === 'string' ? id : undefined;
+}
+
+/** Collect the notation keys that survived into a sanitized KaTeX tree. */
+export function notationKeysInMathNodes(
+  nodes: readonly {
+    readonly type: string;
+    readonly properties?: Readonly<Record<string, string>>;
+    readonly children?: readonly unknown[];
+  }[],
+): string[] {
+  const keys = new Set<string>();
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    const candidate = node as {
+      properties?: Readonly<Record<string, string>>;
+      children?: readonly unknown[];
+    };
+    const key = candidate.properties?.['data-notation-key'];
+    if (key) keys.add(key);
+    for (const child of candidate.children ?? []) visit(child);
+  };
+  for (const node of nodes) visit(node);
+  return [...keys].sort();
+}
+
+function manifestDefinition(
+  definition: NotationDefinitionRecord,
+  cardsByKey: ReadonlyMap<string, GlyphScopeEntry>,
+): ManifestLessonNotation {
+  return {
+    id: definition.id,
+    key: definition.key,
+    scope: definition.kind === 'shared' ? 'shared' : 'local',
+    notation: definition.notation,
+    label: definition.label,
+    summary: definition.summary,
+    editorialStatus: definition.status,
+    seeAlso: [...definition.seeAlso],
+    glosses: [...definition.glosses],
+    formulaScope: formulaGlyphScope({
+      key: definition.key,
+      notation: definition.notation,
+      glosses: definition.glosses,
+      cardsByKey,
+      ...(definition.formula === undefined
+        ? {}
+        : { formula: definition.formula }),
+    }),
+    ...(definition.units === undefined ? {} : { units: definition.units }),
+    ...(definition.formula === undefined
+      ? {}
+      : { formula: definition.formula }),
+  };
+}
+
+/**
+ * Extend one compiled lesson bundle with only the definitions requested by
+ * components rendered on that page (plus those definitions' normal closure).
+ */
+export function notationDefinitionsForRenderedPage(
+  manifest: Manifest,
+  lessonId: string,
+  dependencies: readonly PageNotationDependency[],
+): ManifestLessonNotation[] {
+  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
+  if (!lesson) return [];
+
+  const definitionsById = new Map(
+    manifest.notation.definitions.map((definition) => [definition.id, definition]),
+  );
+  const availableIds = new Set(definitionsById.keys());
+  const ids = new Set(lesson.notation.definitionIds);
+  const contextsByKey = new Map<string, Set<string>>();
+
+  for (const dependency of dependencies) {
+    let contexts = contextsByKey.get(dependency.key);
+    if (!contexts) {
+      contexts = new Set();
+      contextsByKey.set(dependency.key, contexts);
+    }
+    contexts.add(dependency.context);
+
+    const definitionId = resolveReferenceId(
+      dependency.key,
+      { kind: 'page', lessonId },
+      availableIds,
+    );
+    if (!definitionId) {
+      throw new Error(
+        `Notation payload error in lesson "${lessonId}": ${dependency.context} ` +
+          `emitted data-notation-key="${dependency.key}", but that key is not ` +
+          `defined in this lesson or the shared notation registry.`,
+      );
+    }
+    ids.add(definitionId);
+  }
+
+  const pending = [...ids];
+  while (pending.length > 0) {
+    const id = pending.pop();
+    if (!id) continue;
+    const definition = definitionsById.get(id);
+    for (const reference of definition?.resolvedReferences ?? []) {
+      if (ids.has(reference.definitionId)) continue;
+      ids.add(reference.definitionId);
+      pending.push(reference.definitionId);
+    }
+    // A card formula's explicit symbols are intentionally not curriculum
+    // reference edges, but they are UI dependencies: NotationFormula emits
+    // triggers for them, so their cards must travel with the parent card.
+    for (const key of formulaExplainKeys(definition?.formula ?? '')) {
+      if (!definition) continue;
+      const formulaDependencyId = resolveReferenceId(
+        key,
+        definition.scope,
+        availableIds,
+      );
+      // A gloss has no card record; NotationLayer emits its hidden source from
+      // the owning definition's `glosses` collection instead.
+      if (!formulaDependencyId || ids.has(formulaDependencyId)) continue;
+      ids.add(formulaDependencyId);
+      pending.push(formulaDependencyId);
+    }
+  }
+
+  // A local definition shadows the shared card with the same key. A shared
+  // dependency closure must never reintroduce that second meaning on the page.
+  const definitionIdByKey = new Map<string, string>();
+  for (const id of ids) {
+    const definition = definitionsById.get(id);
+    if (!definition) continue;
+    const previous = definitionIdByKey.get(definition.key);
+    if (previous && previous !== id) {
+      const context = [...(contextsByKey.get(definition.key) ?? [])].join(', ');
+      throw new Error(
+        `Notation payload error in lesson "${lessonId}": key "${definition.key}" ` +
+          `would have two meanings (${previous} and ${id})` +
+          (context ? ` after ${context} emitted it.` : '.'),
+      );
+    }
+    definitionIdByKey.set(definition.key, id);
+  }
+
+  const cardsByKey = new Map<string, GlyphScopeEntry>();
+  for (const definition of manifest.notation.definitions) {
+    if (definition.kind !== 'shared') continue;
+    cardsByKey.set(definition.key, {
+      key: definition.key,
+      notation: definition.notation,
+    });
+  }
+
+  const existingById = new Map(
+    lesson.notation.definitions.map((definition) => [definition.id, definition]),
+  );
+  return [...ids]
+    .sort()
+    .flatMap((id) => {
+      const existing = existingById.get(id);
+      if (existing) return [existing];
+      const definition = definitionsById.get(id);
+      return definition ? [manifestDefinition(definition, cardsByKey)] : [];
+    });
+}
+
+/**
+ * Structural backstop over final HTML: every trigger must have a source entry
+ * from which the popup enhancer can populate a card.
+ */
+export function missingNotationPayloadKeys(html: string): string[] {
+  const attributeValues = (name: string): Set<string> => {
+    const values = new Set<string>();
+    const pattern = new RegExp(`${name}=(?:"([^"]+)"|'([^']+)')`, 'g');
+    for (const match of html.matchAll(pattern)) {
+      const value = match[1] ?? match[2];
+      if (value) values.add(value);
+    }
+    return values;
+  };
+  const triggers = attributeValues('data-notation-key');
+  const entries = attributeValues('data-notation-entry');
+  return [...triggers].filter((key) => !entries.has(key)).sort();
+}

package/src/reference/raw-floats-validate.ts

@@ -0,0 +1,103 @@
+/** Diagnostics for raw/unwrapped floats — see `raw-floats.mjs`. */
+
+import { scanRawFloats } from './raw-floats.mjs';
+
+export type RawFloatDiagnosticCode =
+  | 'raw-table-markdown'
+  | 'raw-table-html'
+  | 'diagram-unkeyed'
+  | 'diagram-nested';
+
+export interface RawFloatDiagnostic {
+  readonly code: RawFloatDiagnosticCode;
+  readonly severity: 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly lessonId?: string;
+}
+
+export interface RawFloatLessonInput {
+  readonly lessonId: string;
+  readonly slug: string;
+  readonly file: string;
+  readonly body: string;
+}
+
+function plural(count: number, noun: string): string {
+  return count === 1 ? noun : `${noun}s`;
+}
+
+export function validateRawFloats(
+  lessons: readonly RawFloatLessonInput[],
+): readonly RawFloatDiagnostic[] {
+  const diagnostics: RawFloatDiagnostic[] = [];
+
+  const push = (
+    lesson: RawFloatLessonInput,
+    code: RawFloatDiagnosticCode,
+    count: number,
+    message: (count: number) => string,
+  ) => {
+    if (count === 0) return;
+    diagnostics.push({
+      code,
+      severity: 'warning',
+      message: message(count),
+      file: lesson.file,
+      lessonId: lesson.lessonId,
+    });
+  };
+
+  for (const lesson of [...lessons].sort((a, b) =>
+    a.lessonId.localeCompare(b.lessonId),
+  )) {
+    const found = scanRawFloats(lesson.body);
+
+    push(
+      lesson,
+      'raw-table-markdown',
+      found.markdownTableCount,
+      (count) =>
+        `${lesson.lessonId} has ${count} raw Markdown ${plural(count, 'table')} ` +
+        `not wrapped in <Table>; ${count === 1 ? 'it has' : 'they have'} no ` +
+        `stable number and cannot be referenced with [[tab-…]]. Wrap it in ` +
+        `<Table id="…">…</Table> to give it one.`,
+    );
+    push(
+      lesson,
+      'raw-table-html',
+      found.htmlTableCount,
+      (count) =>
+        `${lesson.lessonId} has ${count} raw HTML <table> ${plural(count, 'element')} ` +
+        `not wrapped in <Table>; ${count === 1 ? 'it has' : 'they have'} no ` +
+        `stable number and cannot be referenced with [[tab-…]]. Wrap it in ` +
+        `<Table id="…">…</Table> to give it one.`,
+    );
+    push(
+      lesson,
+      'diagram-unkeyed',
+      found.unkeyedDiagramCount,
+      (count) =>
+        `${lesson.lessonId} has ${count} <Diagram> ${plural(count, 'component')} ` +
+        `with no id; ${count === 1 ? 'it' : 'they'} cannot be referenced with ` +
+        `[[dia-…]]. Add an id to give it a stable reference.`,
+    );
+    push(
+      lesson,
+      'diagram-nested',
+      found.nestedDiagramCount,
+      (count) =>
+        `${lesson.lessonId} has ${count} <Diagram> ${plural(count, 'component')} ` +
+        `nested inside another component; ${count === 1 ? 'it is' : 'they are'} ` +
+        `invisible to diagram numbering. Move it to the top level (or inside ` +
+        `<Memo>/<ShortNote>), or wrap it in <Figure> to give it identity.`,
+    );
+  }
+
+  diagnostics.sort(
+    (a, b) =>
+      a.code.localeCompare(b.code) ||
+      (a.lessonId ?? '').localeCompare(b.lessonId ?? ''),
+  );
+  return diagnostics;
+}

package/src/reference/raw-floats.mjs

@@ -0,0 +1,129 @@
+/**
+ * Detection for content invisible to keyed-float validation:
+ *
+ * - a raw Markdown pipe table or raw HTML `<table>` that was never wrapped in
+ *   `<Table>`/`<Figure>`, so it can never get a stable number or be
+ *   referenced with `[[tab-…]]`;
+ * - an Explico `<Diagram>` with no `id` (can't be referenced with
+ *   `[[dia-…]]` even though it participates in diagram numbering);
+ * - an Explico `<Diagram>` nested inside some other, non-transparent
+ *   component (anything but `<Memo>`/`<ShortNote>`, or `<Table>`/`<Figure>`
+ *   which legitimately gives it identity) — invisible to
+ *   `keyed-jsx-floats.mjs`'s top-level-only scan entirely, so it never even
+ *   reaches diagram numbering.
+ *
+ * A raw table nested in `<Table>`/`<Figure>` is the intended, wrapped case
+ * and is not flagged; nesting inside anything else (`<CompactExample>`,
+ * `<Aside>`, `<Memo>`, …) still is, because a raw table has no numbering
+ * scheme of its own to opt into the way a `<Diagram>`'s top-level/`<Memo>`-
+ * transparent scan does.
+ *
+ * `scanRawFloats` (raw Markdown, for the manifest builder) and
+ * `collectRawFloats` (mdast, for `remark-notation.mjs`) MUST agree on counts
+ * — `tests/notation/raw-floats.test.ts` checks that, the same contract
+ * `keyed-jsx-floats.mjs` holds `scanKeyedJsxFloats`/`collectKeyedJsxFloats` to.
+ */
+
+import { stripFencedCode } from './equations.mjs';
+import { collectKeyedJsxFloats, scanKeyedJsxFloats } from './keyed-jsx-floats.mjs';
+
+/** Blank `<Table>…</Table>` and `<Figure>…</Figure>` bodies — legitimately wrapped, not raw. */
+function blankFloatWrappers(text) {
+  return text.replace(
+    /<(Table|Figure)\b(?:\s[^>]*)?>[\s\S]*?<\/\1\s*>/g,
+    (block) => block.replace(/[^\n]/g, ' '),
+  );
+}
+
+/** Line index of every GFM pipe-table header + delimiter-row pair. */
+function findMarkdownTableStarts(text) {
+  const lines = text.split('\n');
+  const delimiterRow =
+    /^[ \t]{0,3}\|?[ \t]*:?-+:?[ \t]*(\|[ \t]*:?-+:?[ \t]*)*\|?[ \t]*$/;
+  const hits = [];
+  for (let index = 0; index < lines.length - 1; index++) {
+    const header = lines[index];
+    const delimiter = lines[index + 1];
+    if (!header.includes('|')) continue;
+    if (!delimiter.includes('-') || !delimiterRow.test(delimiter)) continue;
+    hits.push(index);
+  }
+  return hits;
+}
+
+function findHtmlTableTags(text) {
+  return [...text.matchAll(/<table\b/gi)];
+}
+
+function findDiagramTags(text) {
+  return [...text.matchAll(/<Diagram\b/g)];
+}
+
+/**
+ * Counts of raw/unwrapped content in one lesson body. See the module doc for
+ * what each count means and why `<Diagram>` needs the extra visible/nested
+ * split that raw tables don't.
+ */
+export function scanRawFloats(markdown) {
+  const codeStripped = stripFencedCode(String(markdown));
+  const withoutWrappedFloats = blankFloatWrappers(codeStripped);
+
+  const markdownTableCount = findMarkdownTableStarts(withoutWrappedFloats).length;
+  const htmlTableCount = findHtmlTableTags(withoutWrappedFloats).length;
+
+  const diagramsOutsideWrappers = findDiagramTags(withoutWrappedFloats).length;
+  const visibleDiagrams = scanKeyedJsxFloats(markdown, { tagName: 'Diagram' });
+  const nestedDiagramCount = Math.max(
+    0,
+    diagramsOutsideWrappers - visibleDiagrams.length,
+  );
+  const unkeyedDiagramCount = visibleDiagrams.filter(
+    (diagram) => diagram.key == null,
+  ).length;
+
+  return {
+    markdownTableCount,
+    htmlTableCount,
+    nestedDiagramCount,
+    unkeyedDiagramCount,
+  };
+}
+
+/** The mdast equivalent of `scanRawFloats` — same counts, plus the nodes. */
+export function collectRawFloats(tree) {
+  const markdownTableNodes = [];
+  const htmlTableNodes = [];
+  const allDiagramNodes = [];
+
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (
+      node.type === 'mdxJsxFlowElement' &&
+      (node.name === 'Table' || node.name === 'Figure')
+    ) {
+      return; // legitimately wrapped — don't descend
+    }
+    if (node.type === 'table') markdownTableNodes.push(node);
+    if (node.type === 'html' && /<table\b/i.test(String(node.value ?? ''))) {
+      htmlTableNodes.push(node);
+    }
+    if (node.type === 'mdxJsxFlowElement' && node.name === 'Diagram') {
+      allDiagramNodes.push(node);
+    }
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) walk(child);
+    }
+  };
+  walk(tree);
+
+  const visibleDiagrams = collectKeyedJsxFloats(tree, { tagName: 'Diagram' });
+  const visibleNodes = new Set(visibleDiagrams.map((diagram) => diagram.node));
+  const nestedDiagramNodes = allDiagramNodes.filter(
+    (node) => !visibleNodes.has(node),
+  );
+  const unkeyedDiagramNodes = visibleDiagrams
+    .filter((diagram) => diagram.key == null)
+    .map((diagram) => diagram.node);
+
+  return { markdownTableNodes, htmlTableNodes, nestedDiagramNodes, unkeyedDiagramNodes };
+}