explico 0.8.0 → 0.11.1

package/src/rules/course-rules.ts

@@ -0,0 +1,456 @@
+/**
+ * A course's own rules — `courseRules` in `course.settings.json`.
+ *
+ * The engine ships the `N` / `V` / `C` / `S` / `P` areas and a course tunes or
+ * turns them off through `rules` (`src/rules/settings.ts`). This is the other
+ * half: a classroom's house style, written and edited by the people who teach
+ * the course, with no engine change and no fork. `X` is permanently reserved
+ * for them, so an `X` rule reads like any other rule everywhere it appears —
+ * a diagnostic, a waiver, the rules-in-effect page, a review comment.
+ *
+ * ```json
+ * "courseRules": [
+ *   {
+ *     "id": "X1",
+ *     "title": "A paragraph never ends in an exclamation.",
+ *     "summary": "End a paragraph on a statement…",
+ *     "severity": "error",
+ *     "forbid": [{ "scope": "paragraph", "pattern": "Ni!$", "message": "…" }]
+ *   },
+ *   { "id": "X2", "title": "Every fifth paragraph is four sentences.", "enabled": false }
+ * ]
+ * ```
+ *
+ * A rule with a `forbid` pattern is **enforced**: the pattern is matched
+ * against prose the same way rule N9's gate sees it (`gate-course-rules.ts`),
+ * and each match is a diagnostic at the rule's `severity`, carrying the rule's
+ * ID as its code — so `enforcementOf` calls it `script`, and it can be waived
+ * at one place with `{/* explico-allow X1: reason *\/}` like any located rule.
+ * A rule with no pattern is a **guide**: it appears on the rules-in-effect page
+ * for an author or an agent to follow, and nothing runs. `enabled: false`
+ * keeps a rule in the file and moves it to the page's "Off" list — the way to
+ * park a house rule that is drafted but not yet in force.
+ *
+ * Everything here is validated strictly and throws: the settings file is the
+ * course's own, a mistake in it is a mistake the author wants to hear about
+ * before a build runs with a rule that silently does nothing.
+ */
+import {
+  ELEMENTS,
+  isCourseRuleId,
+  type CourseRuleId,
+  type Element,
+  type RuleCheck,
+  type RuleEntry,
+} from './catalog';
+
+/** Where a `forbid` pattern is matched. */
+export type CourseRuleScope = 'paragraph' | 'prose' | 'heading';
+
+export const COURSE_RULE_SCOPES: readonly CourseRuleScope[] = ['paragraph', 'prose', 'heading'];
+
+/** Regular-expression flags a course may set. `g` is always added. */
+const ALLOWED_FLAGS = 'imsu';
+
+/**
+ * One forbidden pattern, as the settings file gives it. `scope` is a plain
+ * `string` on purpose: this is the shape of untrusted JSON, and a
+ * `course.settings.json` imported by `course.config.ts` widens every literal to
+ * `string`, so a union here would make the course's own file fail to typecheck.
+ * The value is checked at resolve time, with the setting's path in the message.
+ */
+export interface CourseRulePatternInput {
+  readonly pattern: string;
+  readonly flags?: string;
+  readonly scope?: string;
+  readonly message?: string;
+}
+
+/** One course rule, as the settings file gives it. See {@link CourseRulePatternInput}. */
+export interface CourseRuleInput {
+  readonly id: string;
+  readonly title: string;
+  readonly summary?: string;
+  readonly elements?: readonly string[];
+  readonly enabled?: boolean;
+  readonly severity?: string;
+  readonly forbid?: readonly CourseRulePatternInput[];
+  readonly unchecked?: string;
+  readonly doc?: string;
+}
+
+/** `CourseConfig.courseRules` — an array, so the settings form can add and remove one. */
+export type CourseRuleDefinitions = readonly CourseRuleInput[];
+
+export interface CourseRulePattern {
+  readonly pattern: string;
+  readonly flags: string;
+  readonly scope: CourseRuleScope;
+  readonly message: string;
+}
+
+/** A course rule with every default applied and every value checked. */
+export interface CourseRule {
+  readonly id: CourseRuleId;
+  readonly title: string;
+  readonly summary: string;
+  readonly elements: readonly [Element, ...Element[]];
+  readonly enabled: boolean;
+  readonly severity: 'error' | 'warning';
+  readonly forbid: readonly CourseRulePattern[];
+  readonly unchecked?: string;
+  readonly doc?: string;
+}
+
+/**
+ * Where a course rule's text lives when the course names no page of its own.
+ * Relative to `build/`, like every other link on the rules-in-effect page.
+ */
+const SETTINGS_DOC = '../content/course.settings.json';
+
+function describe(value: unknown): string {
+  return JSON.stringify(value) ?? String(value);
+}
+
+function at(index: number, id?: string): string {
+  return `CourseConfig courseRules[${index}]${id === undefined ? '' : ` (${id})`}`;
+}
+
+function requireString(value: unknown, where: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`${where} must be a non-empty string; received ${describe(value)}.`);
+  }
+  return value;
+}
+
+function resolveElements(value: unknown, where: string): readonly [Element, ...Element[]] {
+  if (value === undefined) return ['prose'];
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(
+      `${where}.elements must be a non-empty array of elements; received ${describe(value)}.`,
+    );
+  }
+  for (const element of value) {
+    if (!(ELEMENTS as readonly unknown[]).includes(element)) {
+      throw new Error(
+        `${where}.elements: ${describe(element)} is not an element. One of: ${ELEMENTS.join(', ')}.`,
+      );
+    }
+  }
+  return value as unknown as readonly [Element, ...Element[]];
+}
+
+function resolvePattern(
+  input: unknown,
+  where: string,
+  index: number,
+  fallbackMessage: string,
+): CourseRulePattern {
+  const spot = `${where}.forbid[${index}]`;
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error(
+      `${spot} must be an object such as { "pattern": "…" }; received ${describe(input)}.`,
+    );
+  }
+  const raw = input as Record<string, unknown>;
+  for (const key of Object.keys(raw)) {
+    if (!['pattern', 'flags', 'scope', 'message'].includes(key)) {
+      throw new Error(`${spot}: unknown key \`${key}\`. Takes: pattern, flags, scope, message.`);
+    }
+  }
+  const pattern = requireString(raw.pattern, `${spot}.pattern`);
+  const flags = raw.flags === undefined ? '' : requireString(raw.flags, `${spot}.flags`);
+  for (const flag of flags) {
+    if (!ALLOWED_FLAGS.includes(flag)) {
+      throw new Error(
+        `${spot}.flags: \`${flag}\` is not allowed. Use any of \`${ALLOWED_FLAGS}\` — \`g\` is always applied.`,
+      );
+    }
+  }
+  if (new Set(flags).size !== flags.length) {
+    throw new Error(`${spot}.flags: ${describe(flags)} repeats a flag.`);
+  }
+  const scope = raw.scope === undefined ? 'paragraph' : raw.scope;
+  if (!COURSE_RULE_SCOPES.includes(scope as CourseRuleScope)) {
+    throw new Error(
+      `${spot}.scope: ${describe(scope)} is not a scope. One of: ${COURSE_RULE_SCOPES.join(', ')}.`,
+    );
+  }
+  let compiled: RegExp;
+  try {
+    compiled = new RegExp(pattern, `${flags}g`);
+  } catch (error) {
+    throw new Error(
+      `${spot}.pattern: ${pattern} is not a valid regular expression — ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+  // A pattern that matches nothing at all would flag every block of the corpus.
+  if (compiled.test('')) {
+    throw new Error(
+      `${spot}.pattern: ${pattern} matches the empty string, so it would flag every ${scope}. Make it match the text you mean to forbid.`,
+    );
+  }
+  const message =
+    raw.message === undefined ? fallbackMessage : requireString(raw.message, `${spot}.message`);
+  return { pattern, flags, scope: scope as CourseRuleScope, message };
+}
+
+/**
+ * Validate `config.courseRules` and apply the defaults. Throws on anything that
+ * would leave a rule doing something the author did not write: an ID outside
+ * the `X` namespace, a duplicate ID, an unknown key, a pattern that does not
+ * compile.
+ */
+export function resolveCourseRules(config: {
+  readonly courseRules?: CourseRuleDefinitions;
+}): readonly CourseRule[] {
+  const given = config.courseRules;
+  if (given === undefined) return [];
+  if (!Array.isArray(given)) {
+    throw new Error(
+      `CourseConfig courseRules must be an array of rules; received ${describe(given)}. ` +
+        'It is a list, not a map, so the settings form can add and remove one.',
+    );
+  }
+
+  const seen = new Map<string, number>();
+  const out: CourseRule[] = [];
+
+  given.forEach((input, index) => {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+      throw new Error(
+        `${at(index)} must be an object such as { "id": "X1", "title": "…" }; received ${describe(input)}.`,
+      );
+    }
+    const raw = input as Record<string, unknown>;
+    const known = ['id', 'title', 'summary', 'elements', 'enabled', 'severity', 'forbid', 'unchecked', 'doc'];
+    for (const key of Object.keys(raw)) {
+      if (!known.includes(key)) {
+        throw new Error(`${at(index)}: unknown key \`${key}\`. Takes: ${known.join(', ')}.`);
+      }
+    }
+    const id = requireString(raw.id, `${at(index)}.id`);
+    if (!isCourseRuleId(id)) {
+      throw new Error(
+        `${at(index)}.id: ${describe(id)} is not a course-rule ID. A course's own rules are \`X1\`…\`X99\` — ` +
+          'the `X` area is reserved for them, and the engine never ships one, so no release can collide with yours. ' +
+          'To change an engine rule, use `rules` instead.',
+      );
+    }
+    const first = seen.get(id);
+    if (first !== undefined) {
+      throw new Error(
+        `${at(index, id)}.id: ${id} is already used by courseRules[${first}]. An ID names one rule.`,
+      );
+    }
+    seen.set(id, index);
+
+    const where = at(index, id);
+    const title = requireString(raw.title, `${where}.title`);
+    const summary = raw.summary === undefined ? title : requireString(raw.summary, `${where}.summary`);
+    const elements = resolveElements(raw.elements, where);
+    if (raw.enabled !== undefined && typeof raw.enabled !== 'boolean') {
+      throw new Error(`${where}.enabled must be true or false; received ${describe(raw.enabled)}.`);
+    }
+    if (raw.severity !== undefined && raw.severity !== 'error' && raw.severity !== 'warning') {
+      throw new Error(
+        `${where}.severity must be "error" or "warning"; received ${describe(raw.severity)}.`,
+      );
+    }
+    const forbidInput = raw.forbid;
+    if (forbidInput !== undefined && !Array.isArray(forbidInput)) {
+      throw new Error(`${where}.forbid must be an array of patterns; received ${describe(forbidInput)}.`);
+    }
+    const forbid = (forbidInput ?? []).map((pattern, i) =>
+      resolvePattern(pattern, where, i, title),
+    );
+    if (raw.severity !== undefined && forbid.length === 0) {
+      throw new Error(
+        `${where}.severity is set but the rule has no \`forbid\` pattern, so nothing is reported. ` +
+          'Add a pattern, or drop `severity` and keep it a guide rule.',
+      );
+    }
+
+    out.push({
+      id: id as CourseRuleId,
+      title,
+      summary,
+      elements,
+      enabled: raw.enabled !== false,
+      severity: (raw.severity as 'error' | 'warning' | undefined) ?? 'error',
+      forbid,
+      ...(raw.unchecked === undefined ? {} : { unchecked: requireString(raw.unchecked, `${where}.unchecked`) }),
+      ...(raw.doc === undefined ? {} : { doc: requireString(raw.doc, `${where}.doc`) }),
+    });
+  });
+
+  return out;
+}
+
+/**
+ * A course rule as a catalog entry, so the rules-in-effect page, the waiver
+ * validator and `enforcementOf` treat it like any other rule. Its one check
+ * carries the rule's ID as its code, and is `located` — every finding names a
+ * lesson file and line, which is what makes an inline waiver possible.
+ */
+export function courseRuleEntry(rule: CourseRule): RuleEntry {
+  const checks: RuleCheck[] =
+    rule.forbid.length === 0
+      ? []
+      : [
+          {
+            code: rule.id,
+            severity: rule.severity,
+            located: true,
+            emitters: [
+              { module: 'src/reference/gate-course-rules.ts', fn: 'gateCourseRules' },
+            ],
+          },
+        ];
+  return {
+    kind: 'rule',
+    id: rule.id,
+    title: rule.title,
+    elements: rule.elements,
+    doc: rule.doc ?? SETTINGS_DOC,
+    summary: rule.summary,
+    checks,
+    ...(rule.unchecked === undefined ? {} : { unchecked: rule.unchecked }),
+    source: 'course',
+  };
+}
+
+// --- JSON Schema -------------------------------------------------------------
+
+type JsonSchema = Record<string, unknown>;
+
+/**
+ * The `courseRules` property for a course's `course.settings.schema.json`,
+ * written to `dist/rules/course-rules.schema.json` by
+ * `scripts/gen-rules-schema.mjs`. Self-contained (no `$ref`), so the settings
+ * form editor can inline it: an array of objects, which is what gives the form
+ * its add / remove / reorder controls.
+ */
+export function courseRulesJsonSchema(): JsonSchema {
+  return {
+    title: 'Course rules',
+    description:
+      "This course's own authoring rules, on top of the engine's. IDs are `X1`…`X99` — the `X` area is reserved for a course, so no engine release collides with one. A rule with a `forbid` pattern is enforced by the build; a rule without one is a guide an author or an agent reads. Every rule here appears in `build/rules-in-effect.md` beside the engine's, and can be waived at one place with `{/* explico-allow X1: reason */}`.",
+    type: 'array',
+    default: [],
+    items: {
+      title: 'Course rule',
+      type: 'object',
+      additionalProperties: false,
+      required: ['id', 'title'],
+      properties: {
+        id: {
+          title: 'ID',
+          description:
+            'Permanent name of this rule, `X1`…`X99`. It is what a diagnostic, a waiver and a review comment say. Never renumber a rule that is in use.',
+          type: 'string',
+          pattern: '^X[1-9][0-9]?$',
+          'x-patternMessage': 'An `X` and a number, 1–99 — for example `X1`.',
+        },
+        title: {
+          title: 'Rule',
+          description:
+            'One imperative sentence, as a rule page would open: "A paragraph never ends in an exclamation."',
+          type: 'string',
+          minLength: 1,
+          'x-widget': 'textarea',
+        },
+        summary: {
+          title: 'What to do',
+          description:
+            'One to three sentences telling an author or an agent how to comply — no rationale. This is what `build/rules-in-effect.md` prints. Defaults to the rule sentence.',
+          type: 'string',
+          'x-widget': 'textarea',
+        },
+        elements: {
+          title: 'Elements',
+          description:
+            'The parts of a page this rule is about; the first is primary and decides which section of the rules-in-effect page lists it.',
+          type: 'array',
+          default: ['prose'],
+          items: { title: 'Element', type: 'string', enum: [...ELEMENTS] },
+        },
+        enabled: {
+          title: 'Enabled',
+          description:
+            'Off: the rule stays in this file and moves to the "Off" list on the rules-in-effect page — nothing runs, and an agent neither applies it nor flags it in review. Use it to park a rule that is drafted but not in force.',
+          type: 'boolean',
+          default: true,
+        },
+        severity: {
+          title: 'Severity',
+          description:
+            'What a match of a `forbid` pattern is: an error fails `pnpm validate:content`, a warning is reported and does not. Only for a rule that has a pattern.',
+          type: 'string',
+          enum: ['error', 'warning'],
+          default: 'error',
+        },
+        forbid: {
+          title: 'Forbidden patterns',
+          description:
+            'What makes this rule enforced. Each entry is a regular expression matched against the lesson text — with code, math, MDX comments and JSX tags blanked out first, exactly as rule N9 sees prose. Leave empty for a guide rule.',
+          type: 'array',
+          default: [],
+          items: {
+            title: 'Pattern',
+            type: 'object',
+            additionalProperties: false,
+            required: ['pattern'],
+            properties: {
+              pattern: {
+                title: 'Regular expression',
+                description:
+                  'JavaScript regular-expression source, e.g. `Ni!\\s*$`. It must not match the empty string.',
+                type: 'string',
+                minLength: 1,
+              },
+              scope: {
+                title: 'Matched against',
+                description:
+                  'paragraph — each block of prose separated by a blank line, so `^` and `$` are its start and end. prose — the lesson\'s whole prose, so a pattern can span paragraphs. heading — the text of each Markdown heading.',
+                type: 'string',
+                enum: [...COURSE_RULE_SCOPES],
+                default: 'paragraph',
+              },
+              flags: {
+                title: 'Flags',
+                description:
+                  'Any of `i` (ignore case), `m` (`^`/`$` match each line), `s` (`.` matches a newline), `u` (unicode). `g` is always applied.',
+                type: 'string',
+                pattern: '^[imsu]*$',
+                'x-patternMessage': 'Only the letters i, m, s and u.',
+              },
+              message: {
+                title: 'Message',
+                description:
+                  'What the build says at each match. Defaults to the rule sentence. Say what to do, not only what is wrong.',
+                type: 'string',
+                'x-widget': 'textarea',
+              },
+            },
+          },
+        },
+        unchecked: {
+          title: 'Not checked',
+          description:
+            'What the patterns cannot see, in one clause ("that the four sentences are in OSV order"). On a rule that has patterns it marks the rule `partial`, so a reader knows a green build is not the whole rule; on a guide rule it says why no pattern could do the job.',
+          type: 'string',
+          'x-widget': 'textarea',
+        },
+        doc: {
+          title: 'Full text',
+          description:
+            'Link to the course page that states this rule in full, as it should appear on the rules-in-effect page (a path relative to `build/`, or a URL). Defaults to the settings file itself.',
+          type: 'string',
+        },
+      },
+    },
+  };
+}

package/src/rules/in-effect.ts

@@ -0,0 +1,235 @@
+/**
+ * The "rules in effect" page — the one short document an agent reads before
+ * drafting, instead of the 4,000-line rule set.
+ *
+ * Rendered from the catalog and the course's resolved settings
+ * (`manifest.rules`): every rule the course has *on* — the engine's, plus the
+ * course's own `X` rules from `courseRules` — grouped by the element it is
+ * about, with its enforcement, its diagnostic codes, its effective settings and
+ * a one-line summary; the invariants that are always on; and the rules the
+ * course turned off, which an agent neither applies nor flags.
+ * `pnpm validate:content` writes it to `build/rules-in-effect.md` (git-ignored,
+ * like the manifest — regenerated every run); `pnpm content rules` prints it,
+ * optionally filtered to an element or an enforcement kind.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  ELEMENTS,
+  enforcementOf,
+  invariants,
+  rules as catalogRules,
+  type CatalogEntry,
+  type Element,
+  type Enforcement,
+  type RuleEntry,
+} from './catalog';
+import { courseRuleEntry } from './course-rules';
+import type { ManifestRules } from './settings';
+import { isWaivable } from './waivers';
+
+/** The slice of a manifest the page needs. */
+export interface RulesInEffectInput {
+  readonly rules: ManifestRules;
+  readonly about: {
+    readonly engine: { readonly name: string; readonly version: string };
+    readonly material: { readonly name: string };
+    readonly knowledge: { readonly version: string };
+  };
+}
+
+export interface RulesFilter {
+  /** Keep a rule whose elements (any, not just primary) include one of these. */
+  readonly elements?: readonly Element[];
+  readonly enforcement?: Enforcement | 'locked';
+}
+
+/** One rule as `content rules --json` reports it. */
+export interface RuleInEffect {
+  readonly id: string;
+  readonly kind: 'rule' | 'invariant';
+  /** `course` for one of this course's own `X` rules; `engine` for the rest. */
+  readonly source: 'engine' | 'course';
+  readonly title: string;
+  readonly elements: readonly Element[];
+  readonly enforcement: Enforcement | 'locked';
+  readonly enabled: boolean;
+  /** May be waived at one place with `{/* explico-allow <ID>: reason *\/}`. */
+  readonly waivable: boolean;
+  readonly codes: readonly string[];
+  readonly settings: Readonly<Record<string, unknown>>;
+  readonly summary: string;
+  readonly doc: string;
+}
+
+/** Where a course's copy of the rule text lives, relative to `build/`. */
+const DOC_ROOT = '../node_modules/explico/docs/authoring';
+
+/** An engine rule's page, or a course rule's own link, as written. */
+function docLink(entry: CatalogEntry): string {
+  return entry.kind === 'rule' && entry.source === 'course' ? entry.doc : `${DOC_ROOT}/${entry.doc}`;
+}
+
+/**
+ * Every rule in force for this course: the engine's, then the course's own,
+ * which the manifest carries as written in `courseRules`. A retired rule is not
+ * in the catalog (`RetiredRule`), so there is nothing to filter out here.
+ */
+function liveRules(input: RulesInEffectInput): RuleEntry[] {
+  return [...catalogRules(), ...input.rules.course.map(courseRuleEntry)];
+}
+
+function enforcementLabel(entry: CatalogEntry): Enforcement | 'locked' {
+  return entry.kind === 'rule' && entry.locked !== undefined ? 'locked' : enforcementOf(entry);
+}
+
+function matches(entry: CatalogEntry, filter: RulesFilter): boolean {
+  if (filter.elements && !entry.elements.some((e) => filter.elements!.includes(e))) return false;
+  if (filter.enforcement && enforcementLabel(entry) !== filter.enforcement) return false;
+  return true;
+}
+
+export function rulesInEffect(input: RulesInEffectInput, filter: RulesFilter = {}): RuleInEffect[] {
+  const off = new Set<string>(input.rules.disabled);
+  const entries: CatalogEntry[] = [...liveRules(input), ...invariants()];
+  return entries.filter((entry) => matches(entry, filter)).map((entry) => ({
+    id: entry.id,
+    kind: entry.kind,
+    source: entry.kind === 'rule' && entry.source === 'course' ? 'course' : 'engine',
+    title: entry.title,
+    elements: entry.elements,
+    enforcement: enforcementLabel(entry),
+    enabled: !off.has(entry.id),
+    waivable: entry.kind === 'rule' && isWaivable(entry),
+    codes: entry.checks.map((c) => c.code),
+    settings: entry.kind === 'rule' ? (input.rules.settings[entry.id] ?? {}) : {},
+    summary: entry.summary,
+    doc: docLink(entry),
+  }));
+}
+
+/**
+ * A setting's value as the page shows it. A string array is printed item by
+ * item in backticks rather than as JSON, because a LaTeX value
+ * (`\mathbb{N} — the naturals`) comes out of `JSON.stringify` with its
+ * backslash doubled — not what the author writes in the settings file.
+ */
+function settingValue(value: unknown): string {
+  if (!Array.isArray(value)) return JSON.stringify(value) ?? String(value);
+  if (value.length === 0) return '[]';
+  const items = value.map((item) =>
+    typeof item === 'string' ? `\`${item}\`` : JSON.stringify(item),
+  );
+  return `[${items.join(', ')}]`;
+}
+
+function settingsText(rule: RuleEntry, settings: Readonly<Record<string, unknown>>): string {
+  const specs = rule.settings ?? [];
+  if (specs.length === 0) return '';
+  return ` (${specs.map((s) => `${s.key} = ${settingValue(settings[s.key])}`).join(', ')})`;
+}
+
+function ruleLine(rule: RuleEntry, settings: Readonly<Record<string, unknown>>): string {
+  const label = enforcementLabel(rule);
+  const codes = rule.checks.map((c) => `\`${c.code}\``).join(', ');
+  const head = [
+    `**${rule.id}**`,
+    rule.source === 'course' ? 'course' : '',
+    label,
+    codes,
+    isWaivable(rule) ? 'waivable' : '',
+  ]
+    .filter(Boolean)
+    .join(' · ');
+  const also = rule.elements.length > 1 ? ` (also: ${rule.elements.slice(1).join(', ')})` : '';
+  const unchecked = rule.unchecked ? ` Not checked by the build: ${rule.unchecked}` : '';
+  return `- ${head}${also} — ${rule.summary}${settingsText(rule, settings)}${unchecked} → [${rule.doc}](${docLink(rule)})`;
+}
+
+/**
+ * The page. With a filter, only the matching rules are listed and the
+ * header says so; the Off / Locked / Always-on sections still list IDs so
+ * the reader knows what was left out on purpose.
+ */
+export function renderRulesInEffect(input: RulesInEffectInput, filter: RulesFilter = {}): string {
+  const off = new Set<string>(input.rules.disabled);
+  const on = liveRules(input).filter((r) => !off.has(r.id));
+  const ours = on.filter((r) => r.source === 'course').length;
+  const locked = on.filter((r) => r.locked !== undefined).map((r) => r.id);
+  const filtered = filter.elements || filter.enforcement;
+  const visible = on.filter((r) => matches(r, filter));
+
+  const lines: string[] = [];
+  lines.push(
+    `# Rules in effect — ${input.about.material.name} (knowledge ${input.about.knowledge.version}, ${input.about.engine.name} ${input.about.engine.version})`,
+    '',
+    'Generated by `pnpm validate:content` (and `pnpm content rules`) from the rule',
+    'catalog and `rules` / `courseRules` in `course.settings.json`. Do not edit. Read this before',
+    'drafting, and open a rule page only when it is listed here and you need the',
+    'example: a rule absent from this page is either off for this course or does',
+    'not exist, and is neither applied nor flagged in review.',
+    '',
+    `${on.length} rules on (${locked.length} locked${ours === 0 ? '' : `, ${ours} this course's own`}), ` +
+      `${off.size} off, ${invariants().length} invariants always on.` +
+      (filtered
+        ? ` Filtered: ${[
+            filter.elements ? `element ${filter.elements.join(', ')}` : '',
+            filter.enforcement ? `enforcement ${filter.enforcement}` : '',
+          ]
+            .filter(Boolean)
+            .join('; ')} — ${visible.length} shown.`
+        : ''),
+    '',
+    'A line is `ID · enforcement · codes — what to do (settings in effect) → full',
+    'text`. **course**: this course wrote the rule in `courseRules` in',
+    '`course.settings.json`, where it can be edited; the `X` area is reserved for',
+    'them. **script**: the build reports every violation under those codes.',
+    '**partial**: the build reports the codes; the rest is on you. **guide**: nothing',
+    'runs; it is on you. **locked**: script, and the course cannot turn it off.',
+    '**waivable**: break it at one place with `{/* explico-allow <ID>[, <ID>]: <reason> */}`',
+    'on its own line above the block (a paragraph, heading, or tag; a blank line',
+    'ends it) — the reason is mandatory, and a waiver that silences nothing is a',
+    'warning. A finding without a line (a notation entry, a per-lesson count) is',
+    'silenced per key in `lint-ignore.yml` (`- <code>:<key> — <reason>`) instead.',
+  );
+
+  for (const element of ELEMENTS) {
+    const here = visible.filter((r) => r.elements[0] === element);
+    if (here.length === 0) continue;
+    lines.push('', `## ${element}`, '');
+    for (const rule of here) lines.push(ruleLine(rule, input.rules.settings[rule.id] ?? {}));
+  }
+
+  const visibleInvariants = invariants().filter((i) => matches(i, filter));
+  lines.push('', '## Always on (invariants)', '');
+  if (visibleInvariants.length === 0) {
+    lines.push('- (none match the filter)');
+  }
+  for (const inv of visibleInvariants) {
+    const codes = inv.checks.map((c) => `\`${c.code}\``).join(', ');
+    lines.push(
+      `- **${inv.id}** (${inv.elements.join(', ')}) — ${inv.summary} Codes: ${codes}. → [${inv.doc}](${DOC_ROOT}/${inv.doc})`,
+    );
+  }
+
+  lines.push('', '## Off', '');
+  lines.push(
+    off.size === 0
+      ? '- Nothing — every rule is on.'
+      : `- ${[...off].join(', ')} — turned off in \`course.settings.json\` (\`rules\`, or \`courseRules\` for an \`X\` rule). Do not apply them; do not flag them in review.`,
+  );
+
+  lines.push('', '## Locked', '');
+  lines.push(`- ${locked.join(', ')} — cannot be turned off; listed above under their element.`);
+
+  return `${lines.join('\n')}\n`;
+}
+
+/** Write `build/rules-in-effect.md` under `root` (the course package). Returns the path. */
+export function writeRulesInEffect(input: RulesInEffectInput, root = process.cwd()): string {
+  const dir = join(root, 'build');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, 'rules-in-effect.md');
+  writeFileSync(path, renderRulesInEffect(input));
+  return path;
+}