explico 0.8.0 → 0.11.1

package/src/rules/settings.ts

@@ -0,0 +1,448 @@
+/**
+ * A course's per-rule settings — `rules` in `CourseConfig` — resolved against
+ * the catalog.
+ *
+ * The block is flat by rule ID and holds only deviations from the defaults:
+ *
+ * ```json
+ * "rules": {
+ *   "P5": { "enabled": false },
+ *   "S1": { "maxLength": 72 },
+ *   "N14": { "allow": ["GDP"] }
+ * }
+ * ```
+ *
+ * It also resolves the course's *own* rules — `courseRules`, a separate block
+ * with a separate module (`src/rules/course-rules.ts`) — so that one call hands
+ * the compiler every rule decision the course made, engine or not.
+ *
+ * `resolveRules` validates it (an unknown ID, an unknown key, a value outside
+ * its spec, or `enabled: false` on a locked rule is an error — the settings
+ * file is wrong, and a wrong bump would ship), applies every default from the
+ * catalog, folds in the deprecated top-level `operators` / `romanLabels` /
+ * `abbreviations` blocks, and hands the gates one object to ask. It never
+ * decides *what* a rule means — that is the catalog's job.
+ *
+ * `rulesJsonSchema` renders the same catalog as the JSON Schema fragment the
+ * course's settings form uses (`dist/rules/rules.schema.json`, built by
+ * `scripts/gen-rules-schema.mjs`), with properties ordered by element and an
+ * `x-element` hint per rule so the form can group them.
+ */
+import {
+  CATALOG,
+  ELEMENTS,
+  enforcementOf,
+  entryById,
+  isCourseRuleId,
+  retiredRule,
+  ruleById,
+  rules as catalogRules,
+  type Element,
+  type RuleEntry,
+  type RuleId,
+  type SettingSpec,
+} from './catalog';
+import { resolveCourseRules, type CourseRule } from './course-rules';
+import type { CourseConfig, NormalizedPartPages } from '../compiler/course-config';
+
+/** One rule's block in the settings file. Every key is optional. */
+export interface RuleSettingsInput {
+  readonly enabled?: boolean;
+  readonly [key: string]: unknown;
+}
+
+/** `CourseConfig.rules` — flat by rule ID. */
+export type CourseRulesConfig = Readonly<Record<string, RuleSettingsInput>>;
+
+/** A non-fatal finding about the settings file itself. */
+export interface ConfigDiagnostic {
+  readonly code: 'config-deprecated-key' | 'config-retired-rule';
+  readonly severity: 'warning';
+  readonly message: string;
+}
+
+export interface ResolvedRules {
+  /** False only for a rule the course turned off. An invariant is always on. */
+  isEnabled(id: string): boolean;
+  /** The course's own rules (`courseRules`), validated, in file order. */
+  readonly course: readonly CourseRule[];
+  /** The rule's settings with every default applied. `{}` for a rule without any. */
+  settings(id: string): Readonly<Record<string, unknown>>;
+  number(id: string, key: string): number;
+  strings(id: string, key: string): readonly string[];
+  /** Rules the course turned off — catalog order, then its own `X` rules. */
+  readonly disabled: readonly RuleId[];
+  readonly diagnostics: readonly ConfigDiagnostic[];
+}
+
+/** Top-level keys that predate `rules`, and the rule each one configures. */
+const LEGACY_KEYS = {
+  operators: 'N8',
+  romanLabels: 'N10',
+  abbreviations: 'N14',
+} as const;
+
+/** Cross-field checks a single `SettingSpec` cannot express. */
+const EXTRA_VALIDATION: Partial<
+  Record<RuleId, (settings: Readonly<Record<string, unknown>>) => string | undefined>
+> = {
+  S2: (s) => {
+    for (const slot of ['bridge', 'scope'] as const) {
+      const min = s[`${slot}MinWords`] as number;
+      const max = s[`${slot}MaxWords`] as number;
+      if (min > max) {
+        return `${slot}MinWords (${min}) is larger than ${slot}MaxWords (${max}).`;
+      }
+    }
+    return undefined;
+  },
+};
+
+function describe(value: unknown): string {
+  return JSON.stringify(value) ?? String(value);
+}
+
+function validateSetting(id: string, spec: SettingSpec, value: unknown): void {
+  const at = `CourseConfig rules.${id}.${spec.key}`;
+  const { schema } = spec;
+  switch (schema.type) {
+    case 'integer': {
+      if (!Number.isInteger(value)) {
+        throw new Error(`${at} must be an integer; received ${describe(value)}.`);
+      }
+      if (schema.minimum !== undefined && (value as number) < schema.minimum) {
+        throw new Error(`${at} must be at least ${schema.minimum}; received ${describe(value)}.`);
+      }
+      return;
+    }
+    case 'boolean': {
+      if (typeof value !== 'boolean') {
+        throw new Error(`${at} must be true or false; received ${describe(value)}.`);
+      }
+      return;
+    }
+    case 'array': {
+      if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(`${at} must be an array of strings; received ${describe(value)}.`);
+      }
+      return;
+    }
+  }
+}
+
+function suggestion(id: string): string {
+  const area = id.charAt(0).toUpperCase();
+  const ids = catalogRules()
+    .filter((rule) => rule.id.startsWith(area))
+    .map((rule) => rule.id);
+  return ids.length === 0
+    ? `Rule IDs are a letter (N, V, C, S, P) and a number, e.g. N9.`
+    : `Rules in area ${area}: ${ids.join(', ')}.`;
+}
+
+function defaultsOf(rule: RuleEntry): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const spec of rule.settings ?? []) out[spec.key] = spec.schema.default;
+  return out;
+}
+
+/**
+ * Validate `config.rules` (plus the deprecated top-level blocks) against the
+ * catalog and apply defaults. Throws on anything that would make a gate run
+ * with a value the author did not mean.
+ */
+export function resolveRules(config: CourseConfig): ResolvedRules {
+  const diagnostics: ConfigDiagnostic[] = [];
+  const given: Record<string, RuleSettingsInput> = { ...(config.rules ?? {}) };
+
+  for (const [legacyKey, id] of Object.entries(LEGACY_KEYS) as [keyof typeof LEGACY_KEYS, RuleId][]) {
+    const value = config[legacyKey];
+    if (value === undefined) continue;
+    if (given[id] !== undefined) {
+      throw new Error(
+        `CourseConfig sets both the deprecated \`${legacyKey}\` and \`rules.${id}\`; ` +
+          `keep \`rules.${id}\` and delete \`${legacyKey}\`.`,
+      );
+    }
+    given[id] = value as RuleSettingsInput;
+    diagnostics.push({
+      code: 'config-deprecated-key',
+      severity: 'warning',
+      message:
+        `CourseConfig \`${legacyKey}\` is deprecated — move it to \`rules.${id}\` ` +
+        `(same \`allow\` / \`deny\` shape). The old key is honoured for now.`,
+    });
+  }
+
+  const enabled = new Map<string, boolean>();
+  const settings = new Map<string, Readonly<Record<string, unknown>>>();
+
+  for (const rule of catalogRules()) {
+    enabled.set(rule.id, true);
+    settings.set(rule.id, defaultsOf(rule));
+  }
+
+  for (const [id, block] of Object.entries(given)) {
+    const rule = ruleById(id);
+    if (rule === undefined) {
+      const gone = retiredRule(id);
+      if (gone !== undefined) {
+        diagnostics.push({
+          code: 'config-retired-rule',
+          severity: 'warning',
+          message:
+            `CourseConfig rules.${id}: rule ${id} was retired on ${gone.date}` +
+            `${gone.into === undefined ? '' : ` into rule ${gone.into}`}; the block has no effect. ` +
+            'See docs/authoring/retired.md.',
+        });
+        continue;
+      }
+      const invariant = entryById(id);
+      if (isCourseRuleId(id)) {
+        throw new Error(
+          `CourseConfig rules.${id}: \`${id}\` is one of this course's own rules. ` +
+            'A course rule is defined *and* switched in `courseRules` (its `enabled` key); ' +
+            '`rules` is for the rules the engine ships.',
+        );
+      }
+      throw new Error(
+        invariant !== undefined
+          ? `CourseConfig rules.${id}: \`${id}\` is an invariant — always on, with no settings. Remove the block.`
+          : `CourseConfig rules.${id}: no such rule. ${suggestion(id)}`,
+      );
+    }
+    if (block === null || typeof block !== 'object' || Array.isArray(block)) {
+      throw new Error(
+        `CourseConfig rules.${id} must be an object such as { "enabled": false }; received ${describe(block)}.`,
+      );
+    }
+    const specs = new Map((rule.settings ?? []).map((spec) => [spec.key, spec]));
+    const resolved: Record<string, unknown> = defaultsOf(rule);
+    for (const [key, value] of Object.entries(block)) {
+      if (key === 'enabled') {
+        if (typeof value !== 'boolean') {
+          throw new Error(`CourseConfig rules.${id}.enabled must be true or false; received ${describe(value)}.`);
+        }
+        if (value === false && rule.locked !== undefined) {
+          throw new Error(
+            `CourseConfig rules.${id}: rule ${id} is locked and cannot be turned off — ${rule.locked}`,
+          );
+        }
+        enabled.set(id, value);
+        continue;
+      }
+      const spec = specs.get(key);
+      if (spec === undefined) {
+        const known = [...specs.keys()];
+        throw new Error(
+          `CourseConfig rules.${id}: unknown setting \`${key}\`. ` +
+            (known.length === 0
+              ? `Rule ${id} has no settings besides \`enabled\`.`
+              : `Rule ${id} takes: enabled, ${known.join(', ')}.`),
+        );
+      }
+      validateSetting(id, spec, value);
+      resolved[key] = value;
+    }
+    const problem = EXTRA_VALIDATION[rule.id]?.(resolved);
+    if (problem !== undefined) throw new Error(`CourseConfig rules.${id}: ${problem}`);
+    settings.set(id, resolved);
+  }
+
+  const course = resolveCourseRules(config);
+  const disabled: RuleId[] = [
+    ...catalogRules()
+      .map((rule) => rule.id)
+      .filter((id) => enabled.get(id) === false),
+    ...course.filter((rule) => !rule.enabled).map((rule) => rule.id),
+  ];
+  for (const rule of course) enabled.set(rule.id, rule.enabled);
+
+  const settingsOf = (id: string): Readonly<Record<string, unknown>> => {
+    const found = settings.get(id);
+    if (found === undefined) {
+      // An invariant has no settings; a course rule carries its own fields in
+      // `course` rather than a settings block.
+      if (entryById(id) !== undefined || isCourseRuleId(id)) return {};
+      throw new Error(`resolveRules: no rule ${id} in the catalog.`);
+    }
+    return found;
+  };
+
+  return {
+    isEnabled: (id) => enabled.get(id) ?? true,
+    course,
+    settings: settingsOf,
+    number: (id, key) => {
+      const value = settingsOf(id)[key];
+      if (typeof value !== 'number') throw new Error(`resolveRules: rules.${id}.${key} is not a number setting.`);
+      return value;
+    },
+    strings: (id, key) => {
+      const value = settingsOf(id)[key];
+      if (!Array.isArray(value)) throw new Error(`resolveRules: rules.${id}.${key} is not a string-array setting.`);
+      return value as readonly string[];
+    },
+    disabled,
+    diagnostics,
+  };
+}
+
+/** Rule S2's word ranges in the shape `gatePartPages` takes. */
+export function partPageLimits(rules: ResolvedRules): NormalizedPartPages {
+  return {
+    bridge: {
+      minWords: rules.number('S2', 'bridgeMinWords'),
+      maxWords: rules.number('S2', 'bridgeMaxWords'),
+    },
+    scope: {
+      minWords: rules.number('S2', 'scopeMinWords'),
+      maxWords: rules.number('S2', 'scopeMaxWords'),
+    },
+  };
+}
+
+// --- JSON Schema -------------------------------------------------------------
+
+type JsonSchema = Record<string, unknown>;
+
+function settingSchema(spec: SettingSpec): JsonSchema {
+  const { schema } = spec;
+  const base: JsonSchema = { title: spec.title, description: spec.description };
+  switch (schema.type) {
+    case 'integer':
+      return {
+        ...base,
+        type: 'integer',
+        ...(schema.minimum === undefined ? {} : { minimum: schema.minimum }),
+        default: schema.default,
+      };
+    case 'boolean':
+      return { ...base, type: 'boolean', default: schema.default };
+    case 'array':
+      return {
+        ...base,
+        type: 'array',
+        items: { title: 'Entry', type: 'string', minLength: 1 },
+        default: [...schema.default],
+      };
+  }
+}
+
+function ruleSchema(rule: RuleEntry): JsonSchema {
+  const enforcement = enforcementOf(rule);
+  const properties: Record<string, JsonSchema> = {};
+  if (rule.locked === undefined) {
+    properties.enabled = {
+      title: 'Enabled',
+      description:
+        enforcement === 'guide'
+          ? 'Off: the rule leaves the rules-in-effect page and an agent neither applies it nor flags it in review.'
+          : 'Off: the check does not run, and the rule leaves the rules-in-effect page.',
+      type: 'boolean',
+      default: true,
+    };
+  }
+  for (const spec of rule.settings ?? []) properties[spec.key] = settingSchema(spec);
+  const description =
+    rule.summary +
+    (rule.locked === undefined ? '' : ` Locked — ${rule.locked}`) +
+    (rule.unchecked === undefined ? '' : ` Not checked by the build: ${rule.unchecked}`);
+  return {
+    title: `${rule.id} — ${rule.short ?? rule.title}`,
+    description,
+    'x-element': rule.elements[0],
+    'x-elements': [...rule.elements],
+    'x-enforcement': rule.locked === undefined ? enforcement : 'locked',
+    'x-doc': `docs/authoring/${rule.doc}`,
+    type: 'object',
+    additionalProperties: false,
+    properties,
+  };
+}
+
+/**
+ * The `rules` property for a course's `course.settings.schema.json`:
+ * self-contained (no `$ref`), properties ordered by primary element, then
+ * catalog order. A retired rule is not in the catalog at all, so it cannot be a
+ * form field; a block for one is a warning at resolve time.
+ */
+export function rulesJsonSchema(): JsonSchema {
+  const properties: Record<string, JsonSchema> = {};
+  const byElement = new Map<Element, RuleEntry[]>();
+  for (const rule of catalogRules()) {
+    const primary = rule.elements[0];
+    if (!byElement.has(primary)) byElement.set(primary, []);
+    byElement.get(primary)!.push(rule);
+  }
+  for (const element of ELEMENTS) {
+    for (const rule of byElement.get(element) ?? []) properties[rule.id] = ruleSchema(rule);
+  }
+  return {
+    title: 'Rules',
+    description:
+      'Authoring rules this course turns off or tunes, by rule ID. List only what differs from the defaults: every rule is on, with the defaults shown, until a block here says otherwise. A locked rule has no `enabled`. Invariants (always-on syntax checks) are not listed. See docs/authoring/README.md for the index.',
+    type: 'object',
+    additionalProperties: false,
+    properties,
+  };
+}
+
+/** Every rule and invariant ID, for tooling that wants the closed list. */
+export function catalogIds(): readonly string[] {
+  return CATALOG.map((entry) => entry.id);
+}
+
+// --- applying the switches ---------------------------------------------------
+
+/** What the manifest publishes about the course's rule settings. */
+export interface ManifestRules {
+  /** Rules the course turned off — catalog order, then its own `X` rules. */
+  readonly disabled: readonly RuleId[];
+  /** Every rule's settings with defaults applied, by ID. `{}` for a rule without any. */
+  readonly settings: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  /**
+   * The course's own rules, as written in `courseRules` and validated. Carried
+   * in the manifest so the rules-in-effect page and `content rules` list them
+   * beside the engine's without re-reading the settings file.
+   */
+  readonly course: readonly CourseRule[];
+}
+
+export function rulesSnapshot(rules: ResolvedRules): ManifestRules {
+  const settings: Record<string, Readonly<Record<string, unknown>>> = {};
+  for (const rule of catalogRules()) settings[rule.id] = rules.settings(rule.id);
+  return { disabled: rules.disabled, settings, course: rules.course };
+}
+
+/** The diagnostic codes owned by every rule the course turned off. */
+export function disabledCodes(rules: ResolvedRules): ReadonlySet<string> {
+  const codes = new Set<string>();
+  for (const id of rules.disabled) {
+    // A course rule's one code is its ID; its gate is skipped at the call site
+    // as well, so this is belt and braces.
+    if (isCourseRuleId(id)) codes.add(id);
+    for (const check of ruleById(id)?.checks ?? []) codes.add(check.code);
+  }
+  return codes;
+}
+
+/**
+ * Drop every diagnostic a disabled rule owns. This is how a switch takes
+ * effect for a validator that hosts several owners (`consistency.ts`,
+ * `raw-floats-validate.ts`, the resolver behind `gate-math.ts`): the
+ * validator stays ignorant of the catalog and the manifest filters by code.
+ * A whole-rule gate (N9, N14, S1, S2) is additionally skipped at its call
+ * site so its work is not done at all. Curriculum issues carry `kind`, not
+ * `code`.
+ */
+export function dropDisabled<T extends { readonly code?: string; readonly kind?: string }>(
+  diagnostics: readonly T[],
+  disabled: ReadonlySet<string>,
+): T[] {
+  if (disabled.size === 0) return [...diagnostics];
+  return diagnostics.filter((d) => {
+    const code = d.code ?? d.kind;
+    return code === undefined || !disabled.has(code);
+  });
+}

package/src/rules/waivers.ts

@@ -0,0 +1,249 @@
+/**
+ * Per-place waivers — the in-source form of "record the reason in the diff".
+ *
+ * ```mdx
+ * {/* explico-allow N9: the unit is being defined here, not used *\/}
+ * The unit of acceleration is written m/s² …
+ * ```
+ *
+ * The comment sits on its own line and covers the next block: from the first
+ * non-blank line after it to the line before the next blank line (or the end
+ * of the file). Several rules: `explico-allow N9, N14: reason`. The reason is
+ * mandatory.
+ *
+ * A waiver may name any non-locked rule that is *waivable inline* — one with
+ * no check (a guide rule, where the waiver is documentation and never
+ * "unused"), or one whose every check reports a lesson-body `line`
+ * (`RuleCheck.located`). A rule whose checks are corpus-level (a notation
+ * entry, a per-lesson count) is waived per key in `lint-ignore.yml` instead;
+ * a per-file rule (S2) is turned off in `rules`. An invariant or a locked rule
+ * cannot be waived at all.
+ *
+ * One of the course's own rules (`X1`, from `courseRules`) is always waivable
+ * inline, whichever kind it is: an enforced one reports a line, a guide one has
+ * nothing to silence. Both functions take the course's rules so they can say
+ * "no rule `X9`" for an ID the settings never defined.
+ *
+ * `collectWaivers` parses a lesson body; `applyWaivers` drops the located
+ * diagnostics the waivers cover and reports a script-rule waiver that
+ * silenced nothing (`waiver-unused`), so stale waivers get cleaned up.
+ */
+import { lessonLine } from '../reference/gate-prose-notation';
+import {
+  entryById,
+  isCourseRuleId,
+  retiredRule,
+  ruleById,
+  ruleIdOf,
+  type RuleEntry,
+  type RuleId,
+} from './catalog';
+import { courseRuleEntry, type CourseRule } from './course-rules';
+
+/**
+ * The course's own rules, when it has any — a waiver may name one (`X1`) just
+ * like an engine rule, so both the validation and the "silenced nothing" check
+ * need to see them.
+ */
+export interface WaiverRuleSet {
+  readonly courseRules?: readonly CourseRule[];
+}
+
+/** Every rule a waiver may name, engine or course, as a catalog-shaped entry. */
+function ruleEntry(id: string, set: WaiverRuleSet): RuleEntry | undefined {
+  const shipped = ruleById(id);
+  if (shipped !== undefined) return shipped;
+  const own = set.courseRules?.find((rule) => rule.id === id);
+  return own === undefined ? undefined : courseRuleEntry(own);
+}
+
+export interface Waiver {
+  readonly file: string;
+  /** Line of the comment itself. */
+  readonly line: number;
+  readonly ids: readonly RuleId[];
+  readonly reason: string;
+  /** Inclusive line range of the block the waiver covers, in file coordinates. */
+  readonly fromLine: number;
+  readonly toLine: number;
+}
+
+export type WaiverDiagnosticCode = 'waiver-malformed' | 'waiver-invalid' | 'waiver-unused';
+
+export interface WaiverDiagnostic {
+  readonly code: WaiverDiagnosticCode;
+  readonly severity: 'error' | 'warning';
+  readonly message: string;
+  readonly file: string;
+  readonly line: number;
+}
+
+export interface WaiverLessonInput {
+  readonly body: string;
+  readonly bodyLine?: number;
+  readonly source: { readonly file: string };
+}
+
+/** True when `rule` may be waived with an inline comment. */
+export function isWaivable(rule: RuleEntry): boolean {
+  if (rule.locked !== undefined) return false;
+  return rule.checks.length === 0 || rule.checks.every((check) => check.located);
+}
+
+const WAIVER_COMMENT = /\{\/\*\s*explico-allow\b([\s\S]*?)\*\/\}/g;
+const RULE_ID = /^[A-Z]\d+$/;
+
+/** Why a rule cannot be waived inline, or undefined when it can. */
+function notWaivableBecause(id: string, set: WaiverRuleSet): string | undefined {
+  const rule = ruleEntry(id, set);
+  if (rule === undefined) {
+    if (entryById(id) !== undefined) {
+      return `\`${id}\` is an invariant — always on, never waived`;
+    }
+    const gone = retiredRule(id);
+    if (gone !== undefined) {
+      return (
+        `rule ${id} was retired on ${gone.date}` +
+        `${gone.into === undefined ? '' : ` into rule ${gone.into}, which is what to name instead`}`
+      );
+    }
+    return isCourseRuleId(id)
+      ? `no rule \`${id}\` — the \`X\` area is this course's own, and \`courseRules\` defines no ${id}`
+      : `no rule \`${id}\``;
+  }
+  if (rule.locked !== undefined) return `rule ${id} is locked — ${rule.locked}`;
+  if (!isWaivable(rule)) {
+    return (
+      `rule ${id} is not waivable inline — its check is corpus- or file-level; ` +
+      `silence it per key in \`lint-ignore.yml\`, or turn it off in \`rules.${id}\``
+    );
+  }
+  return undefined;
+}
+
+/** The inclusive line range of the block that starts after `commentEnd`. */
+function blockAfter(body: string, commentEnd: number): { from: number; to: number } | undefined {
+  const lines = body.split('\n');
+  const commentLine = body.slice(0, commentEnd).split('\n').length; // 1-based
+  let from = commentLine + 1;
+  while (from <= lines.length && lines[from - 1]!.trim() === '') from += 1;
+  if (from > lines.length) return undefined;
+  let to = from;
+  while (to + 1 <= lines.length && lines[to]!.trim() !== '') to += 1;
+  return { from, to };
+}
+
+export function collectWaivers(
+  lesson: WaiverLessonInput,
+  set: WaiverRuleSet = {},
+): {
+  readonly waivers: Waiver[];
+  readonly diagnostics: WaiverDiagnostic[];
+} {
+  const waivers: Waiver[] = [];
+  const diagnostics: WaiverDiagnostic[] = [];
+  const file = lesson.source.file;
+  const offset = (lesson.bodyLine ?? 1) - 1;
+
+  for (const match of lesson.body.matchAll(WAIVER_COMMENT)) {
+    const line = lessonLine(lesson, match.index);
+    const inner = (match[1] ?? '').trim();
+    const colon = inner.indexOf(':');
+    const idsText = colon === -1 ? inner : inner.slice(0, colon);
+    const reason = colon === -1 ? '' : inner.slice(colon + 1).trim();
+    const ids = idsText
+      .split(/[,\s]+/)
+      .map((id) => id.trim())
+      .filter(Boolean);
+
+    if (ids.length === 0 || !ids.every((id) => RULE_ID.test(id)) || reason === '') {
+      diagnostics.push({
+        code: 'waiver-malformed',
+        severity: 'error',
+        file,
+        line,
+        message:
+          `a waiver is \`{/* explico-allow <ID>[, <ID>]: <reason> */}\` — ` +
+          `rule IDs, a colon, and a non-empty reason; got ${JSON.stringify(inner)}.`,
+      });
+      continue;
+    }
+
+    const problems = ids
+      .map((id) => notWaivableBecause(id, set))
+      .filter((p): p is string => p !== undefined);
+    if (problems.length > 0) {
+      diagnostics.push({
+        code: 'waiver-invalid',
+        severity: 'error',
+        file,
+        line,
+        message: `waiver cannot apply — ${problems.join('; ')}.`,
+      });
+      continue;
+    }
+
+    const block = blockAfter(lesson.body, match.index + match[0].length);
+    waivers.push({
+      file,
+      line,
+      ids: ids as RuleId[],
+      reason,
+      fromLine: block === undefined ? line : block.from + offset,
+      toLine: block === undefined ? line : block.to + offset,
+    });
+  }
+
+  return { waivers, diagnostics };
+}
+
+/** Drop the located diagnostics the waivers cover; report waivers that covered nothing. */
+export function applyWaivers<
+  T extends { readonly code?: string; readonly file?: string; readonly line?: number },
+>(
+  diagnostics: readonly T[],
+  waivers: readonly Waiver[],
+  set: WaiverRuleSet = {},
+): { readonly kept: T[]; readonly unused: WaiverDiagnostic[] } {
+  if (waivers.length === 0) return { kept: [...diagnostics], unused: [] };
+  const used = new Map<Waiver, Set<RuleId>>(waivers.map((w) => [w, new Set()]));
+
+  const kept = diagnostics.filter((diagnostic) => {
+    if (diagnostic.code === undefined || diagnostic.file === undefined || diagnostic.line === undefined) {
+      return true;
+    }
+    const ownerId = ruleIdOf(diagnostic.code);
+    if (ownerId === undefined) return true;
+    for (const waiver of waivers) {
+      if (
+        waiver.file === diagnostic.file &&
+        diagnostic.line >= waiver.fromLine &&
+        diagnostic.line <= waiver.toLine &&
+        waiver.ids.includes(ownerId)
+      ) {
+        used.get(waiver)!.add(ownerId);
+        return false;
+      }
+    }
+    return true;
+  });
+
+  const unused: WaiverDiagnostic[] = [];
+  for (const waiver of waivers) {
+    // A guide rule's waiver is documentation; only a checked rule can be "unused".
+    const silent = waiver.ids.filter(
+      (id) => (ruleEntry(id, set)?.checks.length ?? 0) > 0 && !used.get(waiver)!.has(id),
+    );
+    if (silent.length === 0) continue;
+    unused.push({
+      code: 'waiver-unused',
+      severity: 'warning',
+      file: waiver.file,
+      line: waiver.line,
+      message:
+        `waiver for ${silent.join(', ')} silenced nothing on ` +
+        `lines ${waiver.fromLine}–${waiver.toLine}; remove it, or move it above the block it is for.`,
+    });
+  }
+  return { kept, unused };
+}