explico 0.11.1 → 0.13.0

package/src/reference/gate-mdx-expression.ts

@@ -0,0 +1,45 @@
+/**
+ * The MDX-expression gate (invariant `prop-text`, with the prop gate). MDX
+ * reads `{…}` in a lesson's text as JavaScript: `The set {a} has one element` renders nothing
+ * and fails the build with "a is not defined", in a compiled chunk, with no
+ * file or line. `validate:content` and `content check` parse no expression, so
+ * the build was the first to notice. This gate finds a brace pair in the prose
+ * (code, math, JSX tags, comments, references and import/export lines blanked;
+ * a directive's attributes, `:::note{icon=""}`, kept out) and says what to
+ * write instead. See docs/authoring/components.md#braces-in-prose.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import { lessonLine, proseOnly } from './gate-prose-notation';
+import type { NotationLessonInput } from './types';
+
+/** `export const …` lines: MDX's own JavaScript, not prose. */
+const EXPORT_LINE = /^[ \t]*export\b[^\n]*$/gm;
+/** A directive and its attributes, `:::note{icon=""}` or `:::note[Title]{…}`. */
+const DIRECTIVE = /:{1,3}[A-Za-z][\w-]*(?:\[[^\]\n]*\])?\{[^{}\n]*\}/g;
+
+export function gateMdxExpressions(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[] {
+  const blank = (match: string) => match.replace(/[^\n]/g, ' ');
+  const diagnostics: MathGateDiagnostic[] = [];
+  for (const lesson of lessons) {
+    if (!lesson.body.includes('{')) continue;
+    const prose = proseOnly(lesson.body).replace(EXPORT_LINE, blank).replace(DIRECTIVE, blank);
+    for (const match of prose.matchAll(/\{([^{}\n]*)\}/g)) {
+      const index = match.index ?? 0;
+      if (lesson.body[index - 1] === '\\') continue;
+      const inner = lesson.body.slice(index + 1, index + match[0].length - 1);
+      diagnostics.push({
+        context: 'prose',
+        code: 'mdx-expression',
+        severity: 'error',
+        file: lesson.source.file,
+        line: lessonLine(lesson, index),
+        token: `{${inner}}`,
+        message:
+          `{${inner}} in the prose is a JavaScript expression to MDX, and the build fails on it ` +
+          `("${inner.trim() || '…'} is not defined"). Write \\{${inner}\\} for braces in the text, ` +
+          `or $\\{${inner}\\}$ for a set.`,
+      });
+    }
+  }
+  return diagnostics;
+}

package/src/reference/gate-non-chapter-pages.ts

@@ -0,0 +1,241 @@
+/**
+ * The non-chapter page gate (rule S10). A page that is not a chapter — the
+ * landing page, a part's overview page, any other page outside a part
+ * directory — explains its symbols like a chapter does, but numbers nothing:
+ *
+ * - no numbered block: `<Table>`, `<Figure>`, `<Diagram>`, `<CompactExamples>`,
+ *   `<AssessmentSet>`, and no lab (a component imported from a `labs/` module,
+ *   or any hydrated `client:*` island) — code `non-chapter-float`;
+ * - no `\label{eq:…}` on a display equation — the same code;
+ * - no `notation.local` / `notation.suspend`: the page recalls symbols and
+ *   defines none — code `non-chapter-local-notation`;
+ * - no `$…$` or `[[…]]` in the plain-text strings a page shows outside its
+ *   Markdown body (`hero.title`, `hero.tagline`, a `<PartOverview chain>`
+ *   step), where they would print literally — code `non-chapter-plain-text`.
+ *
+ * A float needs a chapter number, which such a page does not have; linking
+ * the chapter's float (`[[lesson#tab-key]]`) shows it in the reference card
+ * instead. The rule is locked: turning it off would not give the page a
+ * number, so each finding is an error with no waiver. See
+ * docs/authoring/structure-rules.md#s10.
+ */
+import type { MathGateDiagnostic } from './gate-math';
+import { scannable } from './gate-part-pages';
+import { lessonLine } from './gate-prose-notation';
+
+/** One non-chapter page, as the manifest compiler loads it. */
+export interface NonChapterPageInput {
+  readonly file: string;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly body: string;
+  readonly bodyLine: number;
+}
+
+/** A numbered block, with the reference prefix of the float a chapter would give it. */
+const NUMBERED_BLOCKS: Readonly<Record<string, { noun: string; ref: string }>> = {
+  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 = /\$|\[\[/;
+
+interface Finding {
+  readonly index: number;
+  readonly code: 'non-chapter-float' | 'non-chapter-local-notation' | 'non-chapter-plain-text';
+  readonly token: string;
+  readonly message: string;
+  /** Frontmatter findings have no body offset; they report the file's first line. */
+  readonly inFrontmatter?: true;
+}
+
+/** Local names an `import … from '<…>labs/…'` binds, e.g. `{ A, B as C }` → A, C. */
+function labComponentNames(text: string): Set<string> {
+  const names = new Set<string>();
+  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: string): Finding[] {
+  const findings: Finding[] = [];
+
+  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 = new Set<number>();
+  for (const name of labs) {
+    // A lab bound to a numbered block's name (`import Diagram from
+    // '../labs/…'`) was reported above, under that name.
+    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’s <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’s ' +
+        '<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’s own with [[<chapter>#eq-<key>]].',
+    });
+  }
+
+  return findings;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function frontmatterFindings(data: Readonly<Record<string, unknown>>): Finding[] {
+  const findings: Finding[] = [];
+  const notation = record(data.notation);
+  for (const field of ['local', 'suspend'] as const) {
+    if (notation?.[field] === undefined) 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'] as const) {
+    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 $…$ or [[…]] prints literally ` +
+        '(rule S10). Write the words here, and put the symbol in the page ' +
+        'body, where it gets its card.',
+    });
+  }
+  return findings;
+}
+
+/** `<PartOverview chain={[ '…', "…" ]}>`: each quoted step is plain text. */
+function chainFindings(text: string): Finding[] {
+  const findings: Finding[] = [];
+  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 $…$ or [[…]] ' +
+          'prints literally (rule S10). Write the step in words; a symbol ' +
+          'with its card goes in <PartScope>.',
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Check every non-chapter page for what rule S10 keeps off it. Returns one
+ * `MathGateDiagnostic` (context `'structure'`, always an error) per finding.
+ */
+export function gateNonChapterPages(
+  pages: readonly NonChapterPageInput[],
+): MathGateDiagnostic[] {
+  const diagnostics: MathGateDiagnostic[] = [];
+  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;
+}

package/src/reference/gate-part-pages.ts

@@ -52,7 +52,7 @@ interface Occurrence {
 }
 
 /** Blank MDX comments (`{/* … *\/}`) and code, keeping every newline. */
-function scannable(body: string): string {
+export function scannable(body: string): string {
   return stripFencedCode(body).replace(/\{\/\*[\s\S]*?\*\/\}/g, (comment) =>
     comment.replace(/[^\n]/g, ' '),
   );

package/src/reference/gate-prop-text.ts

@@ -0,0 +1,145 @@
+/**
+ * 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.
+ */
+import type { CurriculumIssue } from '../curriculum/validation';
+import type { ContentRecord } from './gate-retired-keys';
+
+/** One quoted prop of a JSX opening tag: `name="value"`. */
+export interface PropString {
+  readonly tag: string;
+  readonly name: string;
+  readonly value: string;
+  /** Index of `value` in the text it was read from. */
+  readonly offset: number;
+}
+
+const blank = (text: string) => text.replace(/[^\n]/g, ' ');
+
+/** Code, MDX comments and a leading frontmatter, blanked so offsets hold. */
+function blankNonJsx(text: string): string {
+  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: string) => lead + blank(match.slice(lead.length)));
+}
+
+/**
+ * The tag that opens at `start` (on its `<`), with every `{…}` expression
+ * blanked so a quoted string inside one is not read as a prop: its end and
+ * that copy, or `undefined` when the tag never closes.
+ */
+function readTag(text: string, start: number): { readonly end: number; readonly props: string } | undefined {
+  let quote: string | undefined;
+  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 !== undefined) {
+      if (char === quote) quote = undefined;
+      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 undefined;
+}
+
+/** Every quoted prop of every JSX opening tag in `text`, outside code, comments and frontmatter. */
+export function propStrings(text: string): PropString[] {
+  const searchable = blankNonJsx(text);
+  const found: PropString[] = [];
+  const opening = /<([A-Za-z][\w.:-]*)/g;
+  let match: RegExpExecArray | null;
+  while ((match = opening.exec(searchable))) {
+    const tag = readTag(searchable, match.index);
+    if (tag === undefined) 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;
+}
+
+/** `text` with every quoted JSX prop value blanked: the scans for math and prose skip what never renders as either. */
+export function blankPropStrings(text: string): string {
+  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]*\]/;
+
+/** What a prop holds that only renders in prose, and what to write instead. */
+function markupIn(value: string): { readonly found: string; readonly advice: string } | undefined {
+  const math = INLINE_MATH.exec(value);
+  if (math) {
+    return {
+      found: `math (\`${math[0]}\`)`,
+      advice:
+        'Write the symbol in Unicode or words ("v₀", "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 undefined;
+}
+
+/** One `markup-in-prop` issue per quoted prop of a page's JSX that holds math, a reference or a citation. */
+export function findMarkupInProps(records: readonly ContentRecord[]): CurriculumIssue[] {
+  const issues: CurriculumIssue[] = [];
+  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 === undefined) 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;
+}

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

@@ -49,6 +49,12 @@ const KEY_REFERENCE = /\[\[[^\]\n]*\]\]/g;
 // 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;
+// A link's destination, `[text](https://…/basically/ "title")`: an address,
+// not prose a reader sees; its text stays. A definition line,
+// `[text]: https://…`, is all address. An autolink `<https://…>` is a JSX-tag
+// shape and goes with them.
+const LINK_DESTINATION = /\]\((?:[^()\n]|\([^()\n]*\))*\)/g;
+const LINK_DEFINITION = /^[ \t]{0,3}\[[^\]\n]+\]:[ \t]*\S[^\n]*$/gm;
 
 /**
  * Blank code, math, reference, and JSX-tag spans so offsets don't shift.
@@ -62,9 +68,13 @@ const MDX_COMMENT = /\{\/\*[\s\S]*?\*\/\}/g;
 /**
  * `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.
  */
-export function proseOnly(body: string, options: { readonly keepMath?: boolean } = {}): string {
+export function proseOnly(
+  body: string,
+  options: { readonly keepMath?: boolean; readonly keepReferences?: boolean } = {},
+): string {
   const blank = (match: string) => match.replace(/[^\n]/g, ' ');
   const code = body
     .replace(MDX_COMMENT, blank)
@@ -73,7 +83,9 @@ export function proseOnly(body: string, options: { readonly keepMath?: boolean }
   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(KEY_REFERENCE, (match) => (options.keepReferences ? match : blank(match)))
+    .replace(LINK_DESTINATION, (match) => `]${blank(match.slice(1))}`)
+    .replace(LINK_DEFINITION, blank)
     .replace(JSX_TAG, blank);
 }
 
@@ -130,8 +142,10 @@ const SLASH_IDIOMS = new Set([
 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;
+// hand-typed sub/superscript that was never wrapped in `$…$`. The match takes
+// the whole runs on both sides (or a braced group), so the message quotes
+// `2^10`, not `2^1`.
+const FAKE_SCRIPT = /[A-Za-z0-9]+[_^](?:\{[^{}\n]{0,24}\}?|[A-Za-z0-9]+)/g;
 
 /** Every N9 finding that is not a spelled-out unit. */
 const PROSE_NOTATION_CODE = 'prose-notation' as const;

package/src/reference/gate-retired-keys.ts

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+import type { CurriculumIssue } from '../curriculum/validation';
+
+/** One content file as `loadContentRecords` (`compiler/collections.ts`) reads it. */
+export 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. */
+export const RETIRED_KEYS: Readonly<Record<string, string>> = {
+  editorialStatus:
+    'explico no longer tracks a draft / in-review / reviewed status, because lessons are reviewed continuously. Delete the line.',
+};
+
+/** One `retired-key` issue per retired key a record sets, in record order. */
+export function findRetiredKeys(
+  records: readonly ContentRecord[],
+): CurriculumIssue[] {
+  const issues: CurriculumIssue[] = [];
+  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 === undefined ? file : `${file}:${line}`;
+      issues.push({
+        kind: 'retired-key',
+        message: `${at}: \`${key}\` is retired. ${advice}`,
+        file,
+        ...(line === undefined ? {} : { line }),
+      });
+    }
+  }
+  return issues;
+}
+
+/** The 1-based line a `key:` (YAML) or `"key":` (JSON) first starts on. */
+export function keyLine(text: string, key: string): number | undefined {
+  const match = new RegExp(`^[ \\t]*(?:"${key}"|${key})[ \\t]*:`, 'm').exec(text);
+  return match === null
+    ? undefined
+    : text.slice(0, match.index).split('\n').length;
+}
+
+/**
+ * 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.
+ */
+export function findUnsupportedKeys(
+  records: readonly ContentRecord[],
+): CurriculumIssue[] {
+  const issues: CurriculumIssue[] = [];
+  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 === undefined ? 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 … specified in the Starlight ' +
+          'sidebar config does not exist"). Keep an unfinished lesson outside content/docs/ ' +
+          'until it is ready.',
+        file,
+        ...(line === undefined ? {} : { line }),
+      });
+    }
+    // A chapter's order: a page outside a part (the glossary, the curriculum
+    // map) is placed by the engine and has no tracks to point to.
+    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 === undefined ? 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 === undefined ? {} : { line }),
+      });
+    }
+  }
+  return issues;
+}

package/src/reference/gloss.ts

@@ -43,6 +43,8 @@ export interface ResolvedGloss {
 export 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;
 }
 
 /**