explico 0.12.0 → 0.13.1

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-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;
 }
 
 /**