explico 0.11.1 → 0.13.0

package/dist/reference/gate-non-chapter-pages.js

@@ -0,0 +1,156 @@
+import { scannable } from "./gate-part-pages.js";
+import { lessonLine } from "./gate-prose-notation.js";
+const NUMBERED_BLOCKS = {
+  Table: { noun: "a table", ref: "tab" },
+  Figure: { noun: "a figure", ref: "fig" },
+  Diagram: { noun: "a diagram", ref: "dia" },
+  CompactExamples: { noun: "a worked-example set", ref: "ex" },
+  AssessmentSet: { noun: "a knowledge check", ref: "check" }
+};
+const NUMBERED_BLOCK_TAG = new RegExp(
+  `<(${Object.keys(NUMBERED_BLOCKS).join("|")})(?=[\\s/>])`,
+  "g"
+);
+const EQUATION_LABEL = /\\label\s*\{\s*eq:([^}]*)\}/g;
+const CLIENT_DIRECTIVE = /<([A-Z][\w.]*)\b[^<>]*?\sclient:[a-z]+/g;
+const IMPORT = /^\s*import\s+([\s\S]*?)\s+from\s+['"]([^'"]+)['"]/gm;
+const PLAIN_TEXT_MARKUP = /\$|\[\[/;
+function labComponentNames(text) {
+  const names = /* @__PURE__ */ new Set();
+  for (const match of text.matchAll(IMPORT)) {
+    const [, clause, source] = match;
+    if (!/(^|\/)labs\//.test(source)) continue;
+    const named = /\{([^}]*)\}/.exec(clause);
+    const defaultName = clause.replace(/\{[^}]*\}/, "").replace(/,/g, " ").trim();
+    if (/^[A-Za-z_$][\w$]*$/.test(defaultName)) names.add(defaultName);
+    for (const part of named?.[1].split(",") ?? []) {
+      const alias = part.trim().split(/\s+as\s+/).pop()?.trim();
+      if (alias) names.add(alias);
+    }
+  }
+  return names;
+}
+function floatFindings(text) {
+  const findings = [];
+  for (const match of text.matchAll(NUMBERED_BLOCK_TAG)) {
+    const tag = match[1];
+    const { noun, ref } = NUMBERED_BLOCKS[tag];
+    findings.push({
+      index: match.index ?? 0,
+      code: "non-chapter-float",
+      token: `<${tag}>`,
+      message: `<${tag}> on a page that is not a chapter (rule S10): only a chapter numbers ${noun}. Move it into the chapter it belongs to, and link it from here with [[<chapter>#${ref}-<key>]]: the link shows it in its card.`
+    });
+  }
+  const labs = labComponentNames(text);
+  const flagged = /* @__PURE__ */ new Set();
+  for (const name of labs) {
+    if (name in NUMBERED_BLOCKS) continue;
+    const usage = new RegExp(`<${name.replace(/\./g, "\\.")}(?=[\\s/>])`, "g");
+    for (const match of text.matchAll(usage)) {
+      const index = match.index ?? 0;
+      flagged.add(index);
+      findings.push({
+        index,
+        code: "non-chapter-float",
+        token: `<${name}>`,
+        message: `<${name}> is a lab, on a page that is not a chapter (rule S10): a plot belongs in a chapter\u2019s <Figure>. Move it there, and link it from here with [[<chapter>#fig-<key>]]: the link shows it in its card.`
+      });
+    }
+  }
+  for (const match of text.matchAll(CLIENT_DIRECTIVE)) {
+    const index = match.index ?? 0;
+    if (flagged.has(index) || match[1] in NUMBERED_BLOCKS) continue;
+    findings.push({
+      index,
+      code: "non-chapter-float",
+      token: `<${match[1]}>`,
+      message: `<${match[1]}> is an interactive island, on a page that is not a chapter (rule S10): an interactive figure belongs in a chapter\u2019s <Figure>. Move it there, and link it from here with [[<chapter>#fig-<key>]]: the link shows it in its card.`
+    });
+  }
+  for (const match of text.matchAll(EQUATION_LABEL)) {
+    const key = match[1].trim();
+    findings.push({
+      index: match.index ?? 0,
+      code: "non-chapter-float",
+      token: `\\label{eq:${key}}`,
+      message: `\\label{eq:${key}} on a page that is not a chapter (rule S10): only a chapter numbers an equation. Drop the label to show the equation unnumbered, or link the chapter\u2019s own with [[<chapter>#eq-<key>]].`
+    });
+  }
+  return findings;
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function frontmatterFindings(data) {
+  const findings = [];
+  const notation = record(data.notation);
+  for (const field of ["local", "suspend"]) {
+    if (notation?.[field] === void 0) continue;
+    findings.push({
+      index: 0,
+      inFrontmatter: true,
+      code: "non-chapter-local-notation",
+      token: `notation.${field}`,
+      message: `notation.${field} on a page that is not a chapter (rule S10): the page recalls symbols and defines none. Move the entry to the chapter that introduces the symbol, or to shared notation, and name it here with [[key]].`
+    });
+  }
+  const hero = record(data.hero);
+  for (const field of ["title", "tagline"]) {
+    const value = hero?.[field];
+    if (typeof value !== "string" || !PLAIN_TEXT_MARKUP.test(value)) continue;
+    findings.push({
+      index: 0,
+      inFrontmatter: true,
+      code: "non-chapter-plain-text",
+      token: `hero.${field}`,
+      message: `hero.${field} is plain text, so its $\u2026$ or [[\u2026]] prints literally (rule S10). Write the words here, and put the symbol in the page body, where it gets its card.`
+    });
+  }
+  return findings;
+}
+function chainFindings(text) {
+  const findings = [];
+  const overview = /<PartOverview\b[\s\S]*?\bchain=\{\s*\[([\s\S]*?)\]\s*\}/g;
+  for (const match of text.matchAll(overview)) {
+    const listStart = (match.index ?? 0) + match[0].indexOf(match[1]);
+    const step = /'((?:[^'\\]|\\.)*)'|"((?:[^"\\]|\\.)*)"|`((?:[^`\\]|\\.)*)`/g;
+    for (const item of match[1].matchAll(step)) {
+      const value = item[1] ?? item[2] ?? item[3] ?? "";
+      if (!PLAIN_TEXT_MARKUP.test(value)) continue;
+      findings.push({
+        index: listStart + (item.index ?? 0),
+        code: "non-chapter-plain-text",
+        token: "chain",
+        message: "A <PartOverview chain> step is plain text, so its $\u2026$ or [[\u2026]] prints literally (rule S10). Write the step in words; a symbol with its card goes in <PartScope>."
+      });
+    }
+  }
+  return findings;
+}
+function gateNonChapterPages(pages) {
+  const diagnostics = [];
+  for (const page of pages) {
+    const text = scannable(page.body);
+    const findings = [
+      ...frontmatterFindings(page.data),
+      ...floatFindings(text),
+      ...chainFindings(text)
+    ].sort((a, b) => a.index - b.index);
+    for (const finding of findings) {
+      diagnostics.push({
+        context: "structure",
+        severity: "error",
+        code: finding.code,
+        file: page.file,
+        line: finding.inFrontmatter ? 1 : lessonLine(page, finding.index),
+        token: finding.token,
+        message: finding.message
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  gateNonChapterPages
+};

package/dist/reference/gate-part-pages.d.ts

@@ -1,4 +1,4 @@
-import { N as NormalizedPartPages } from '../course-config-Dsnri9Tk.js';
+import { i as NormalizedPartPages } from '../course-config-rRtME5UV.js';
 import { MathGateDiagnostic } from './gate-math.js';
 import '../rules/catalog.js';
 import '../rules/course-rules.js';
@@ -34,6 +34,8 @@ interface PartPageInput {
     readonly body: string;
     readonly bodyLine: number;
 }
+/** Blank MDX comments (`{/* … *\/}`) and code, keeping every newline. */
+declare function scannable(body: string): string;
 /**
  * Words a reader reads in a paragraph of MDX prose. A math span, a `[[key]]`
  * reference, or a link each count by what they render as: one token for the
@@ -47,4 +49,4 @@ declare function proseWordCount(markdown: string): number;
  */
 declare function gatePartPages(pages: readonly PartPageInput[], limits: NormalizedPartPages): MathGateDiagnostic[];
 
-export { type PartPageInput, gatePartPages, proseWordCount };
+export { type PartPageInput, gatePartPages, proseWordCount, scannable };

package/dist/reference/gate-part-pages.js

@@ -114,5 +114,6 @@ function gatePartPages(pages, limits) {
 }
 export {
   gatePartPages,
-  proseWordCount
+  proseWordCount,
+  scannable
 };

package/dist/reference/gate-prop-text.d.ts

@@ -0,0 +1,28 @@
+import { CurriculumIssue } from '../curriculum/validation.js';
+import { ContentRecord } from './gate-retired-keys.js';
+
+/**
+ * The prop-text gate (invariant `prop-text`). A component's quoted prop —
+ * `caption="…"`, `short="…"`, `title="…"`, `label="…"` — reaches the page as
+ * plain text: KaTeX, the reference plugin and the citation plugin never run
+ * inside one. A `$…$`, `[[…]]` or `[@…]` there would print exactly as typed,
+ * dollars and brackets included, so it fails the build at its line with what
+ * to write instead. See docs/authoring/components.md#props-are-plain-text.
+ */
+
+/** One quoted prop of a JSX opening tag: `name="value"`. */
+interface PropString {
+    readonly tag: string;
+    readonly name: string;
+    readonly value: string;
+    /** Index of `value` in the text it was read from. */
+    readonly offset: number;
+}
+/** Every quoted prop of every JSX opening tag in `text`, outside code, comments and frontmatter. */
+declare function propStrings(text: string): PropString[];
+/** `text` with every quoted JSX prop value blanked: the scans for math and prose skip what never renders as either. */
+declare function blankPropStrings(text: string): string;
+/** One `markup-in-prop` issue per quoted prop of a page's JSX that holds math, a reference or a citation. */
+declare function findMarkupInProps(records: readonly ContentRecord[]): CurriculumIssue[];
+
+export { type PropString, blankPropStrings, findMarkupInProps, propStrings };

package/dist/reference/gate-prop-text.js

@@ -0,0 +1,106 @@
+const blank = (text) => text.replace(/[^\n]/g, " ");
+function blankNonJsx(text) {
+  return text.replace(/^---\r?\n[\s\S]*?\r?\n---(?=\r?\n|$)/, blank).replace(/\{\/\*[\s\S]*?\*\/\}/g, blank).replace(/```[\s\S]*?```/g, blank).replace(/(^|[^`])`[^`\n]*`/g, (match, lead) => lead + blank(match.slice(lead.length)));
+}
+function readTag(text, start) {
+  let quote;
+  let depth = 0;
+  let props = "";
+  for (let index = start; index < text.length; index += 1) {
+    const char = text[index];
+    const kept = depth === 0 || char === "\n" ? char : " ";
+    if (quote !== void 0) {
+      if (char === quote) quote = void 0;
+      props += kept;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`" && depth > 0) {
+      quote = char;
+    } else if (char === "{") {
+      depth += 1;
+    } else if (char === "}") {
+      depth = Math.max(0, depth - 1);
+      props += " ";
+      continue;
+    } else if (char === ">" && depth === 0) {
+      return { end: index + 1, props: props + char };
+    }
+    props += depth === 0 || char === "\n" ? char : " ";
+  }
+  return void 0;
+}
+function propStrings(text) {
+  const searchable = blankNonJsx(text);
+  const found = [];
+  const opening = /<([A-Za-z][\w.:-]*)/g;
+  let match;
+  while (match = opening.exec(searchable)) {
+    const tag = readTag(searchable, match.index);
+    if (tag === void 0) break;
+    for (const prop of tag.props.matchAll(/([A-Za-z_][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+      const value = prop[2] ?? prop[3] ?? "";
+      const valueAt = match.index + (prop.index ?? 0) + prop[0].length - value.length - 1;
+      found.push({ tag: match[1], name: prop[1], value: text.slice(valueAt, valueAt + value.length), offset: valueAt });
+    }
+    opening.lastIndex = tag.end;
+  }
+  return found;
+}
+function blankPropStrings(text) {
+  let out = text;
+  for (const { value, offset } of propStrings(text)) {
+    out = out.slice(0, offset) + blank(value) + out.slice(offset + value.length);
+  }
+  return out;
+}
+const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/;
+const REFERENCE = /\[\[[^\]\n]*\]\]/;
+const CITATION = /\[@[^\]\n]*\]/;
+function markupIn(value) {
+  const math = INLINE_MATH.exec(value);
+  if (math) {
+    return {
+      found: `math (\`${math[0]}\`)`,
+      advice: 'Write the symbol in Unicode or words ("v\u2080", "the launch speed"); the prose next to it typesets the symbol.'
+    };
+  }
+  const reference = REFERENCE.exec(value);
+  if (reference) {
+    return {
+      found: `a reference (\`${reference[0]}\`)`,
+      advice: "Name the target in words, and reference it from the prose next to the component."
+    };
+  }
+  const citation = CITATION.exec(value);
+  if (citation) {
+    return {
+      found: `a citation (\`${citation[0]}\`)`,
+      advice: "Cite the source in the prose next to the component."
+    };
+  }
+  return void 0;
+}
+function findMarkupInProps(records) {
+  const issues = [];
+  for (const { file, text } of records) {
+    const path = file.replace(/\\/g, "/");
+    if (!path.startsWith("content/docs/") || !path.endsWith(".mdx")) continue;
+    for (const prop of propStrings(text)) {
+      const markup = markupIn(prop.value);
+      if (markup === void 0) continue;
+      const line = text.slice(0, prop.offset).split("\n").length;
+      issues.push({
+        kind: "markup-in-prop",
+        message: `${file}:${line}: <${prop.tag}> \`${prop.name}\` holds ${markup.found}, but a prop is plain text: it would print as typed. ${markup.advice}`,
+        file,
+        line
+      });
+    }
+  }
+  return issues;
+}
+export {
+  blankPropStrings,
+  findMarkupInProps,
+  propStrings
+};

package/dist/reference/gate-prose-notation.d.ts

@@ -34,10 +34,12 @@ interface AssessmentLike {
 /**
  * `keepMath` leaves `$…$` / `$$…$$` in place (everything else still blanked,
  * offsets unchanged) — for a check that needs to see what a math span sits
- * next to, such as `$x = 3$ meters`.
+ * next to, such as `$x = 3$ meters`. `keepReferences` leaves `[[…]]` in
+ * place, for the check that a reference is well formed.
  */
 declare function proseOnly(body: string, options?: {
     readonly keepMath?: boolean;
+    readonly keepReferences?: boolean;
 }): string;
 /** Exported for the same reason as {@link proseOnly}. */
 declare function lineOf(text: string, index: number): number;

package/dist/reference/gate-prose-notation.js

@@ -6,12 +6,14 @@ const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
 const IMPORT_LINE = /^[ \t]*import\b[^\n]*$/gm;
 const KEY_REFERENCE = /\[\[[^\]\n]*\]\]/g;
 const JSX_TAG = /<\/?[A-Za-z][^<>]*>/g;
+const LINK_DESTINATION = /\]\((?:[^()\n]|\([^()\n]*\))*\)/g;
+const LINK_DEFINITION = /^[ \t]{0,3}\[[^\]\n]+\]:[ \t]*\S[^\n]*$/gm;
 const MDX_COMMENT = /\{\/\*[\s\S]*?\*\/\}/g;
 function proseOnly(body, options = {}) {
   const blank = (match) => match.replace(/[^\n]/g, " ");
   const code = body.replace(MDX_COMMENT, blank).replace(CODE_FENCE, blank).replace(INLINE_CODE, (match, lead) => lead + blank(match.slice(lead.length)));
   const math = options.keepMath ? code : code.replace(DISPLAY_MATH, blank).replace(INLINE_MATH, blank);
-  return math.replace(IMPORT_LINE, blank).replace(KEY_REFERENCE, blank).replace(JSX_TAG, blank);
+  return math.replace(IMPORT_LINE, blank).replace(KEY_REFERENCE, (match) => options.keepReferences ? match : blank(match)).replace(LINK_DESTINATION, (match) => `]${blank(match.slice(1))}`).replace(LINK_DEFINITION, blank).replace(JSX_TAG, blank);
 }
 function lineOf(text, index) {
   return text.slice(0, index).split("\n").length;
@@ -43,7 +45,7 @@ const SLASH_IDIOMS = /* @__PURE__ */ new Set([
   "a/b"
 ]);
 const SLASH_TOKENS = /\b([A-Za-z]{1,6})\/([A-Za-z]{1,6})\b/g;
-const FAKE_SCRIPT = /[A-Za-z0-9][_^][A-Za-z0-9{]/g;
+const FAKE_SCRIPT = /[A-Za-z0-9]+[_^](?:\{[^{}\n]{0,24}\}?|[A-Za-z0-9]+)/g;
 const PROSE_NOTATION_CODE = "prose-notation";
 function findAll(text, pattern, toFinding) {
   const out = [];

package/dist/reference/gate-retired-keys.d.ts

@@ -0,0 +1,35 @@
+import { CurriculumIssue } from '../curriculum/validation.js';
+
+/**
+ * The retired-key gate (invariant `retired-keys`). A content file that still
+ * sets a key the engine no longer reads fails the build, once per key and
+ * file, so a course stops maintaining a field that does nothing. The finding
+ * points at the key's line, and deleting that line clears it. See
+ * docs/authoring/structure.md#retired-keys.
+ */
+
+/** One content file as `loadContentRecords` (`compiler/collections.ts`) reads it. */
+interface ContentRecord {
+    /** Repository-relative path, e.g. `content/sources/hull.json`. */
+    readonly file: string;
+    /** Top-level fields: a page's frontmatter, or a JSON record's object. */
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly text: string;
+}
+/** Each retired key, with what an author does about it. Keys are plain identifiers. */
+declare const RETIRED_KEYS: Readonly<Record<string, string>>;
+/** One `retired-key` issue per retired key a record sets, in record order. */
+declare function findRetiredKeys(records: readonly ContentRecord[]): CurriculumIssue[];
+/** The 1-based line a `key:` (YAML) or `"key":` (JSON) first starts on. */
+declare function keyLine(text: string, key: string): number | undefined;
+/**
+ * Starlight frontmatter a lesson may set but explico cannot honour: the
+ * manifest, not Starlight, decides which pages a course lists and in what
+ * order (invariant `retired-keys`). `draft: true` is an error — Starlight
+ * drops the page from a production build while the sidebar still names it, so
+ * the build fails — and `sidebar.order` a warning, since chapters follow the
+ * tracks and the key does nothing.
+ */
+declare function findUnsupportedKeys(records: readonly ContentRecord[]): CurriculumIssue[];
+
+export { type ContentRecord, RETIRED_KEYS, findRetiredKeys, findUnsupportedKeys, keyLine };

package/dist/reference/gate-retired-keys.js

@@ -0,0 +1,58 @@
+const RETIRED_KEYS = {
+  editorialStatus: "explico no longer tracks a draft / in-review / reviewed status, because lessons are reviewed continuously. Delete the line."
+};
+function findRetiredKeys(records) {
+  const issues = [];
+  for (const { file, data, text } of records) {
+    for (const [key, advice] of Object.entries(RETIRED_KEYS)) {
+      if (!(key in data)) continue;
+      const line = keyLine(text, key);
+      const at = line === void 0 ? file : `${file}:${line}`;
+      issues.push({
+        kind: "retired-key",
+        message: `${at}: \`${key}\` is retired. ${advice}`,
+        file,
+        ...line === void 0 ? {} : { line }
+      });
+    }
+  }
+  return issues;
+}
+function keyLine(text, key) {
+  const match = new RegExp(`^[ \\t]*(?:"${key}"|${key})[ \\t]*:`, "m").exec(text);
+  return match === null ? void 0 : text.slice(0, match.index).split("\n").length;
+}
+function findUnsupportedKeys(records) {
+  const issues = [];
+  for (const { file, data, text } of records) {
+    if (!file.replace(/\\/g, "/").startsWith("content/docs/")) continue;
+    if (data.draft === true) {
+      const line = keyLine(text, "draft");
+      issues.push({
+        kind: "unsupported-key",
+        message: `${line === void 0 ? file : `${file}:${line}`}: \`draft: true\` is not supported in a course: Starlight leaves a draft out of a production build, but explico still lists and numbers it, so the build fails ("The slug \u2026 specified in the Starlight sidebar config does not exist"). Keep an unfinished lesson outside content/docs/ until it is ready.`,
+        file,
+        ...line === void 0 ? {} : { line }
+      });
+    }
+    const sidebar = data.sidebar;
+    const chapter = /^content\/docs\/[^/]+\/(?!index\.mdx?$)[^/]+\.mdx?$/.test(file.replace(/\\/g, "/"));
+    if (chapter && sidebar !== null && typeof sidebar === "object" && "order" in sidebar) {
+      const line = keyLine(text, "order");
+      issues.push({
+        kind: "ignored-key",
+        severity: "warning",
+        message: `${line === void 0 ? file : `${file}:${line}`}: \`sidebar.order\` does nothing in a course: chapters follow the order of the tracks (content/tracks/*.json), then their slugs. Order them there and delete the line.`,
+        file,
+        ...line === void 0 ? {} : { line }
+      });
+    }
+  }
+  return issues;
+}
+export {
+  RETIRED_KEYS,
+  findRetiredKeys,
+  findUnsupportedKeys,
+  keyLine
+};

package/dist/reference/gloss.d.ts

@@ -41,6 +41,8 @@ interface ResolvedGloss {
 interface GlyphScopeEntry {
     readonly key: string;
     readonly notation: string;
+    /** Rule N23: the entry's index is a fixed label, so it is no family. */
+    readonly fixedIndex?: true;
 }
 /**
  * The key segment derived from a gloss name: lower-cased, runs of anything

package/dist/reference/katex-measure.d.ts

@@ -0,0 +1,17 @@
+/** A formula's box at one font size, in px. */
+interface FormulaMetrics {
+    /** Advance width. */
+    readonly width: number;
+    /** Height above the baseline. */
+    readonly height: number;
+    /** Depth below the baseline. */
+    readonly depth: number;
+}
+/**
+ * Measure `latex` as the notation KaTeX renders it — the same macros
+ * (`\explain`, `\slot`), trust boundary and delimiter sizing as lesson math —
+ * at a font size of `fontPx`. Throws on LaTeX KaTeX cannot render.
+ */
+declare function measureFormula(latex: string, fontPx: number): FormulaMetrics;
+
+export { type FormulaMetrics, measureFormula };