explico 0.4.0 → 0.6.0

package/dist/reference/remark-memo.mjs

@@ -0,0 +1,339 @@
+/**
+ * Remark adapter for substantial, referenceable memo disclosures.
+ *
+ * Authors place a memo as a normal flow block and cite it from earlier prose:
+ *
+ *   The complete calculation is recorded in [[memo-derivation]].
+ *
+ *   <Memo id="derivation" title="Derivation" description="The algebra.">
+ *   Several paragraphs, equations, tables, or figures.
+ *
+ *   </Memo>
+ *
+ * MDX normally rejects this before remark transforms run: an inline JSX node
+ * cannot contain block Markdown. The attacher therefore wraps remark-parse's
+ * parser and tags each memo before parsing. Legacy inline placements are still
+ * split into a temporary marker plus a flow `<Memo>`; standalone blocks do not
+ * emit a marker at their authored location. The transformer resolves every
+ * `[[memo-id]]` to a numbered link and injects the memo's per-page number and
+ * anchor into the real component. Temporary attributes never reach output.
+ */
+
+import { stripFencedCode } from './equations.mjs';
+import { KEYED_FLOAT_KEY_PATTERN } from './keyed-jsx-floats.mjs';
+import {
+  injectMdxStringAttributes,
+  mdxAttributesNamed,
+  removeMdxAttribute,
+} from './mdx-attributes.mjs';
+
+const BLOCK_ATTRIBUTE = 'data-explico-memo-block';
+const MARKER_URL_PREFIX = '#explico-internal-memo-marker-';
+const MEMO_REFERENCE_PATTERN =
+  /\[\[\s*memo-([a-z0-9]+(?:-[a-z0-9]+)*)\s*\]\]/g;
+
+/** A same-page memo reference payload, e.g. `memo-full-derivation`. */
+export function parseMemoRef(raw) {
+  const match = /^memo-([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(String(raw).trim());
+  return match ? { key: match[1] } : undefined;
+}
+
+// An MDX attribute may be a quoted string, a brace expression (including one
+// level of nested braces), or ordinary unquoted source. Required memo props are
+// validated as literal strings after parsing; this breadth is for preserving
+// unrelated props such as `rememberState={condition}` intact.
+const ATTRIBUTE_SOURCE = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'])*`;
+const MEMO_PAIR = new RegExp(
+  String.raw`<Memo\b(${ATTRIBUTE_SOURCE})>([\s\S]*?)<\/Memo\s*>`,
+  'g',
+);
+
+function maskBlock(block) {
+  return block.replace(/[^\n]/g, ' ');
+}
+
+/** Protect examples/comments whose literal `<Memo>` text is not authoring. */
+function searchableMemoSource(source) {
+  return stripFencedCode(source)
+    .replace(/<!--[\s\S]*?-->/g, maskBlock)
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, maskBlock);
+}
+
+function isStandaloneBlock(source, start, end) {
+  const lineStart = source.lastIndexOf('\n', start - 1) + 1;
+  const followingNewline = source.indexOf('\n', end);
+  const lineEnd = followingNewline === -1 ? source.length : followingNewline;
+  return (
+    source.slice(lineStart, start).trim().length === 0 &&
+    source.slice(end, lineEnd).trim().length === 0
+  );
+}
+
+/**
+ * Turn otherwise-unparseable inline/block memo syntax into ordinary MDX while
+ * retaining author attributes and body source verbatim.
+ */
+export function preprocessMemos(source) {
+  const input = String(source);
+  const searchable = searchableMemoSource(input);
+  const matches = [...searchable.matchAll(MEMO_PAIR)];
+  if (matches.length === 0) return input;
+
+  let cursor = 0;
+  let output = '';
+  for (let index = 0; index < matches.length; index++) {
+    const match = matches[index];
+    const start = match.index ?? 0;
+    if (start < cursor) continue;
+
+    const whole = match[0];
+    const maskedAttributes = match[1] ?? '';
+    const openLength = '<Memo'.length + maskedAttributes.length + 1;
+    const closeOffset = whole.lastIndexOf('</Memo');
+    const bodyStart = start + openLength;
+    const closeStart = start + closeOffset;
+    const attributes = input.slice(start + '<Memo'.length, bodyStart - 1);
+    const body = input.slice(bodyStart, closeStart);
+    const searchableBody = searchable.slice(bodyStart, closeStart);
+    if (/<Memo\b/.test(searchableBody)) {
+      throw new Error('A <Memo> cannot be nested inside another <Memo>.');
+    }
+
+    const closingTag = input.slice(closeStart, start + whole.length);
+    const end = start + whole.length;
+    output += input.slice(cursor, start);
+    if (isStandaloneBlock(input, start, end)) {
+      output += `<Memo ${BLOCK_ATTRIBUTE}="${index}"${attributes}>\n\n`;
+      output += body;
+      output += `\n\n${closingTag}`;
+    } else {
+      output += `[memo](${MARKER_URL_PREFIX}${index})\n\n`;
+      output += `<Memo ${BLOCK_ATTRIBUTE}="${index}"${attributes}>\n\n`;
+      output += body;
+      output += `\n\n${closingTag}\n\n`;
+    }
+    cursor = end;
+  }
+  output += input.slice(cursor);
+  return output;
+}
+
+function fail(file, message, node) {
+  if (typeof file?.fail === 'function') file.fail(message, node);
+  const location = file?.path ? `${file.path}: ` : '';
+  throw new Error(`${location}${message}`);
+}
+
+function literalAttribute(node, name, file, { optional = false } = {}) {
+  const matches = mdxAttributesNamed(node, name);
+  if (matches.length > 1) {
+    fail(file, `<Memo> has more than one \`${name}\` prop.`, node);
+  }
+  if (matches.length === 0) {
+    if (optional) return undefined;
+    fail(file, `<Memo> requires a non-empty literal \`${name}\` prop.`, node);
+  }
+  const value = matches[0]?.value;
+  if (typeof value !== 'string' || !value.trim()) {
+    const qualifier = optional ? 'when provided' : '';
+    fail(
+      file,
+      `<Memo> \`${name}\` must be a non-empty literal string${qualifier ? ` ${qualifier}` : ''}; expressions are not supported for build-time memo markers.`,
+      matches[0] ?? node,
+    );
+  }
+  return value;
+}
+
+function markerNode(memo) {
+  const link = {
+    type: 'link',
+    url: `#${memo.anchorId}`,
+    children: [
+      {
+        type: 'text',
+        value: memo.label ?? `[${memo.number}]`,
+      },
+    ],
+    data: {
+      hProperties: {
+        className: ['memo-marker'],
+        'data-memo-key': memo.id,
+        'data-memo-number': memo.number,
+        'aria-controls': memo.anchorId,
+        'aria-expanded': 'false',
+        'aria-label': memo.label
+          ? `${memo.label}: ${memo.title}`
+          : `Memo ${memo.number}: ${memo.title}`,
+        title: memo.title,
+      },
+    },
+  };
+  if (memo.label) return link;
+  return {
+    type: 'emphasis',
+    children: [link],
+    data: {
+      hName: 'sup',
+      hProperties: { className: ['memo-marker-wrap'] },
+    },
+  };
+}
+
+function visit(node, callback, parent) {
+  if (!node || typeof node !== 'object') return;
+  callback(node, parent);
+  if (!Array.isArray(node.children)) return;
+  for (const child of node.children) visit(child, callback, node);
+}
+
+function rewriteMemoReferences(node, memos, file) {
+  if (!node || typeof node !== 'object' || !Array.isArray(node.children)) return;
+  if (node.type === 'link' || node.type === 'linkReference') return;
+
+  for (let index = 0; index < node.children.length; index++) {
+    const child = node.children[index];
+    if (child?.type !== 'text' || typeof child.value !== 'string') {
+      rewriteMemoReferences(child, memos, file);
+      continue;
+    }
+
+    const replacements = [];
+    let cursor = 0;
+    let match;
+    MEMO_REFERENCE_PATTERN.lastIndex = 0;
+    while ((match = MEMO_REFERENCE_PATTERN.exec(child.value))) {
+      if (match.index > cursor) {
+        replacements.push({ type: 'text', value: child.value.slice(cursor, match.index) });
+      }
+      const memo = memos.get(match[1]);
+      if (!memo) {
+        fail(
+          file,
+          `Unknown memo reference [[memo-${match[1]}]]: no <Memo> on this page carries id="${match[1]}".`,
+          child,
+        );
+      }
+      replacements.push(markerNode({ ...memo, label: undefined }));
+      cursor = match.index + match[0].length;
+    }
+    if (replacements.length === 0) continue;
+    if (cursor < child.value.length) {
+      replacements.push({ type: 'text', value: child.value.slice(cursor) });
+    }
+    node.children.splice(index, 1, ...replacements);
+    index += replacements.length - 1;
+  }
+}
+
+/**
+ * Number memo blocks from one on every page and resolve same-page
+ * `[[memo-id]]` references. Numbering is intentionally page-local.
+ *
+ * @this {any}
+ */
+export default function remarkMemo() {
+  const processor = this;
+  const parse = processor.parser;
+  if (typeof parse !== 'function') {
+    throw new Error(
+      'remarkMemo must be registered after the Markdown parser (and after remark-mdx when configured explicitly).',
+    );
+  }
+  Reflect.set(processor, 'parser', (document, file) =>
+    parse(preprocessMemos(document), file),
+  );
+
+  return function transform(tree, file) {
+    const blocks = new Map();
+    const markerLocations = new Map();
+    const unprocessed = [];
+
+    visit(tree, (node, parent) => {
+      if (
+        node.type === 'link' &&
+        typeof node.url === 'string' &&
+        node.url.startsWith(MARKER_URL_PREFIX)
+      ) {
+        const token = node.url.slice(MARKER_URL_PREFIX.length);
+        if (markerLocations.has(token)) {
+          fail(file, 'Internal memo marker collision.', node);
+        }
+        markerLocations.set(token, { node, parent });
+      }
+      if (node.name !== 'Memo') return;
+      const internal = mdxAttributesNamed(node, BLOCK_ATTRIBUTE);
+      if (internal.length === 0) {
+        unprocessed.push(node);
+        return;
+      }
+      const token = literalAttribute(node, BLOCK_ATTRIBUTE, file);
+      if (blocks.has(token)) fail(file, 'Internal memo block collision.', node);
+      blocks.set(token, node);
+    });
+
+    if (unprocessed.length > 0) {
+      fail(
+        file,
+        '<Memo> must use a paired opening and closing tag so remarkMemo can place its inline marker and block body.',
+        unprocessed[0],
+      );
+    }
+    for (const token of markerLocations.keys()) {
+      if (!blocks.has(token)) fail(file, 'Internal memo marker/block pairing failed.', tree);
+    }
+
+    const seenIds = new Set();
+    const memos = new Map();
+    let number = 0;
+    for (const [token, node] of blocks) {
+      const marker = markerLocations.get(token);
+      if (marker && (!marker.parent || !Array.isArray(marker.parent.children))) {
+        fail(file, 'Internal memo marker has no paragraph parent.', marker.node);
+      }
+      if (node.type !== 'mdxJsxFlowElement') {
+        fail(file, '<Memo> did not become a block-level MDX element.', node);
+      }
+
+      const id = literalAttribute(node, 'id', file);
+      const title = literalAttribute(node, 'title', file);
+      literalAttribute(node, 'description', file);
+      const label = literalAttribute(node, 'label', file, { optional: true });
+      if (!KEYED_FLOAT_KEY_PATTERN.test(id)) {
+        fail(
+          file,
+          `Invalid <Memo id="${id}">; use lowercase letters/numbers separated by single hyphens.`,
+          node,
+        );
+      }
+      if (seenIds.has(id)) {
+        fail(file, `Duplicate <Memo id="${id}"> on this page.`, node);
+      }
+      seenIds.add(id);
+
+      number += 1;
+      const anchorId = `memo-${id}`;
+      removeMdxAttribute(node, BLOCK_ATTRIBUTE);
+      injectMdxStringAttributes(node, {
+        number: String(number),
+        anchorId,
+      });
+
+      const memo = {
+        id,
+        title,
+        label,
+        number: String(number),
+        anchorId,
+      };
+      memos.set(id, memo);
+
+      if (marker) {
+        const markerIndex = marker.parent.children.indexOf(marker.node);
+        marker.parent.children[markerIndex] = markerNode(memo);
+      }
+    }
+
+    rewriteMemoReferences(tree, memos, file);
+  };
+}

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

@@ -3,53 +3,88 @@
  *
  * Every number on a page comes from two places that MUST agree: the page's own
  * counters (`numbering`) and the manifest tables a cross-page `[[slug#eq-key]]`
- * is resolved against (`equations` / `tables` / `figures`). Deriving all four
- * from the same manifest in one step is what stops a course config from
+ * is resolved against (`equations` / `tables` / `figures` / `diagrams` /
+ * `checks`).
+ * Deriving every input from the same manifest in one step stops a course config from
  * supplying one without the other — the omission that produced page-local
  * `(2.2)` and cross-page `(4.5)` for the same equation.
  *
- * `numbering` maps a lesson slug to `{ part, equations, tables, figures }`:
- * the part's ordinal (the number before the dot) and, per kind of float, how
- * many of them the earlier lessons of that part already used.
+ * `numbering` maps a lesson slug to
+ * `{ part, equations, tables, figures, diagrams, checks }`: the part's ordinal
+ * (the number before the dot) and, per numbered kind, how many earlier lessons
+ * of that part already used.
  */
 export function numberingFromManifest(manifest: any): {
     equations?: undefined;
     tables?: undefined;
     figures?: undefined;
+    diagrams?: undefined;
+    checks?: undefined;
     numbering?: undefined;
 } | {
     equations: any;
     tables: any;
     figures: any;
+    diagrams: any;
+    checks: any;
     numbering: {
         [k: string]: any;
     };
 };
+/**
+ * The options object `remarkNotation` needs for one manifest, in one call.
+ *
+ * A consumer used to hand-assemble `definitions`, `equations`, `tables`,
+ * `figures`, and `chapters` separately — easy to do partially, which is how a
+ * page ends up numbered under the legacy `##`-section scheme while the
+ * manifest (and every cross-page reference to that page) uses the part
+ * scheme. This does not return that literal four-map-plus-chapters shape:
+ * `chapters` is the superseded per-lesson form (see `pageNumbering` below),
+ * and passing `manifest` through already makes `numberingFromManifest()`
+ * derive `numbering` plus every `equations`/`tables`/`figures`/`diagrams`/
+ * `checks` map from the same source in one step — strictly more correct than
+ * reconstructing `chapters` by hand.
+ *
+ * `overrides` is spread last, so a caller can add `strict`, `unknown`,
+ * `resolve`, `base`, or override anything above:
+ *
+ *   [remarkNotation, createRemarkNotationOptions(manifest, { strict: true })]
+ *
+ * @param {object} manifest - a compiled Explico manifest (`compileManifest()`).
+ * @param {object} [overrides] - additional/overriding `remarkNotation` options.
+ */
+export function createRemarkNotationOptions(manifest: object, overrides?: object): {
+    definitions: any;
+    manifest: object;
+};
 /**
  * @param {{
  *   definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>),
  *   resolve?: (key: string, context: object) => object | undefined,
  *   unknown?: 'error' | 'warn' | 'ignore',
+ *   strict?: boolean,
  *   base?: string,
  *   manifest?: object,
  *   equations?: Record<string, Record<string, string>>,
  *   tables?: Record<string, Record<string, string>>,
  *   figures?: Record<string, Record<string, string>>,
- *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number }>,
+ *   diagrams?: Record<string, Record<string, string>>,
+ *   checks?: Record<string, Record<string, string>>,
+ *   numbering?: Record<string, { part: number, equations: number, tables: number, figures: number, diagrams: number, checks: number }>,
  *   chapters?: Record<string, number>,
  * }} [options]
  *
- * `manifest` is the preferred wiring: pass the compiled manifest and the four
+ * `manifest` is the preferred wiring: pass the compiled manifest and all
  * numbering inputs below are read off it together, so they cannot drift apart.
  * They stay available individually for hand-built trees, and an explicitly
  * supplied one still wins over the manifest.
  *
  * `numbering` maps a lesson slug to its **part** (the number before the dot)
  * and, per kind of float, how many the earlier lessons of that part already
- * used. Every display equation / `<Table>` / `<Figure>` on the page is then
+ * used. Every display equation / `<Table>` / `<Figure>` / `<Diagram>` on the page is then
  * numbered `‹part›.‹offset + n›`, with `##` and `###` headings ignored; with no
  * entry the legacy `##`-section scheme applies. It must agree with
- * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`
+ * `manifest.lessons[]`, which is what feeds `equations`/`tables`/`figures`/`diagrams`
  * above — supplying the tables without `numbering` numbers the same equation
  * twice, and `assertManifestNumberParity` turns that into a build error rather
  * than a page whose references disagree with their targets.
@@ -57,21 +92,34 @@ export function numberingFromManifest(manifest: any): {
  * `chapters` is the superseded per-lesson form (slug → the lesson's course
  * ordinal, no running offset). Still read when `numbering` has no entry, so a
  * config written against the old option keeps building.
+ *
+ * `strict` (default `false`) additionally fails the build when a catalogued
+ * lesson contains an equation/`<Table>`/`<Figure>` — keyed or not — but has no
+ * `numbering` placement or no cross-page number table entry, instead of
+ * silently rendering it under the legacy `##`-section scheme. Off by default
+ * for backward compatibility; `createRemarkNotationOptions(manifest, { strict:
+ * true })` is the recommended way to turn it on for a course whose manifest
+ * covers every catalogued lesson.
  */
 export default function remarkNotation(options?: {
     definitions?: Map<string, object> | readonly object[] | Record<string, object> | (() => Map<string, object> | readonly object[] | Record<string, object>);
     resolve?: (key: string, context: object) => object | undefined;
     unknown?: "error" | "warn" | "ignore";
+    strict?: boolean;
     base?: string;
     manifest?: object;
     equations?: Record<string, Record<string, string>>;
     tables?: Record<string, Record<string, string>>;
     figures?: Record<string, Record<string, string>>;
+    diagrams?: Record<string, Record<string, string>>;
+    checks?: Record<string, Record<string, string>>;
     numbering?: Record<string, {
         part: number;
         equations: number;
         tables: number;
         figures: number;
+        diagrams: number;
+        checks: number;
     }>;
     chapters?: Record<string, number>;
 }): (tree: any, file: any) => void;