explico 0.8.0 → 0.11.1

package/dist/rules/settings.d.ts

@@ -0,0 +1,3 @@
+import './catalog.js';
+import './course-rules.js';
+export { e as ConfigDiagnostic, j as CourseRulesConfig, M as ManifestRules, R as ResolvedRules, k as RuleSettingsInput, l as catalogIds, m as disabledCodes, n as dropDisabled, p as partPageLimits, r as resolveRules, o as rulesJsonSchema, q as rulesSnapshot } from '../course-config-Dsnri9Tk.js';

package/dist/rules/settings.js

@@ -0,0 +1,290 @@
+import {
+  CATALOG,
+  ELEMENTS,
+  enforcementOf,
+  entryById,
+  isCourseRuleId,
+  retiredRule,
+  ruleById,
+  rules as catalogRules
+} from "./catalog.js";
+import { resolveCourseRules } from "./course-rules.js";
+const LEGACY_KEYS = {
+  operators: "N8",
+  romanLabels: "N10",
+  abbreviations: "N14"
+};
+const EXTRA_VALIDATION = {
+  S2: (s) => {
+    for (const slot of ["bridge", "scope"]) {
+      const min = s[`${slot}MinWords`];
+      const max = s[`${slot}MaxWords`];
+      if (min > max) {
+        return `${slot}MinWords (${min}) is larger than ${slot}MaxWords (${max}).`;
+      }
+    }
+    return void 0;
+  }
+};
+function describe(value) {
+  return JSON.stringify(value) ?? String(value);
+}
+function validateSetting(id, spec, value) {
+  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 !== void 0 && value < 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) {
+  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) {
+  const out = {};
+  for (const spec of rule.settings ?? []) out[spec.key] = spec.schema.default;
+  return out;
+}
+function resolveRules(config) {
+  const diagnostics = [];
+  const given = { ...config.rules ?? {} };
+  for (const [legacyKey, id] of Object.entries(LEGACY_KEYS)) {
+    const value = config[legacyKey];
+    if (value === void 0) continue;
+    if (given[id] !== void 0) {
+      throw new Error(
+        `CourseConfig sets both the deprecated \`${legacyKey}\` and \`rules.${id}\`; keep \`rules.${id}\` and delete \`${legacyKey}\`.`
+      );
+    }
+    given[id] = value;
+    diagnostics.push({
+      code: "config-deprecated-key",
+      severity: "warning",
+      message: `CourseConfig \`${legacyKey}\` is deprecated \u2014 move it to \`rules.${id}\` (same \`allow\` / \`deny\` shape). The old key is honoured for now.`
+    });
+  }
+  const enabled = /* @__PURE__ */ new Map();
+  const settings = /* @__PURE__ */ new Map();
+  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 === void 0) {
+      const gone = retiredRule(id);
+      if (gone !== void 0) {
+        diagnostics.push({
+          code: "config-retired-rule",
+          severity: "warning",
+          message: `CourseConfig rules.${id}: rule ${id} was retired on ${gone.date}${gone.into === void 0 ? "" : ` 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 !== void 0 ? `CourseConfig rules.${id}: \`${id}\` is an invariant \u2014 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 = 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 !== void 0) {
+          throw new Error(
+            `CourseConfig rules.${id}: rule ${id} is locked and cannot be turned off \u2014 ${rule.locked}`
+          );
+        }
+        enabled.set(id, value);
+        continue;
+      }
+      const spec = specs.get(key);
+      if (spec === void 0) {
+        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 !== void 0) throw new Error(`CourseConfig rules.${id}: ${problem}`);
+    settings.set(id, resolved);
+  }
+  const course = resolveCourseRules(config);
+  const disabled = [
+    ...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) => {
+    const found = settings.get(id);
+    if (found === void 0) {
+      if (entryById(id) !== void 0 || 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;
+    },
+    disabled,
+    diagnostics
+  };
+}
+function partPageLimits(rules) {
+  return {
+    bridge: {
+      minWords: rules.number("S2", "bridgeMinWords"),
+      maxWords: rules.number("S2", "bridgeMaxWords")
+    },
+    scope: {
+      minWords: rules.number("S2", "scopeMinWords"),
+      maxWords: rules.number("S2", "scopeMaxWords")
+    }
+  };
+}
+function settingSchema(spec) {
+  const { schema } = spec;
+  const base = { title: spec.title, description: spec.description };
+  switch (schema.type) {
+    case "integer":
+      return {
+        ...base,
+        type: "integer",
+        ...schema.minimum === void 0 ? {} : { 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) {
+  const enforcement = enforcementOf(rule);
+  const properties = {};
+  if (rule.locked === void 0) {
+    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 === void 0 ? "" : ` Locked \u2014 ${rule.locked}`) + (rule.unchecked === void 0 ? "" : ` Not checked by the build: ${rule.unchecked}`);
+  return {
+    title: `${rule.id} \u2014 ${rule.short ?? rule.title}`,
+    description,
+    "x-element": rule.elements[0],
+    "x-elements": [...rule.elements],
+    "x-enforcement": rule.locked === void 0 ? enforcement : "locked",
+    "x-doc": `docs/authoring/${rule.doc}`,
+    type: "object",
+    additionalProperties: false,
+    properties
+  };
+}
+function rulesJsonSchema() {
+  const properties = {};
+  const byElement = /* @__PURE__ */ new Map();
+  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
+  };
+}
+function catalogIds() {
+  return CATALOG.map((entry) => entry.id);
+}
+function rulesSnapshot(rules) {
+  const settings = {};
+  for (const rule of catalogRules()) settings[rule.id] = rules.settings(rule.id);
+  return { disabled: rules.disabled, settings, course: rules.course };
+}
+function disabledCodes(rules) {
+  const codes = /* @__PURE__ */ new Set();
+  for (const id of rules.disabled) {
+    if (isCourseRuleId(id)) codes.add(id);
+    for (const check of ruleById(id)?.checks ?? []) codes.add(check.code);
+  }
+  return codes;
+}
+function dropDisabled(diagnostics, disabled) {
+  if (disabled.size === 0) return [...diagnostics];
+  return diagnostics.filter((d) => {
+    const code = d.code ?? d.kind;
+    return code === void 0 || !disabled.has(code);
+  });
+}
+export {
+  catalogIds,
+  disabledCodes,
+  dropDisabled,
+  partPageLimits,
+  resolveRules,
+  rulesJsonSchema,
+  rulesSnapshot
+};

package/dist/rules/waivers.d.ts

@@ -0,0 +1,53 @@
+import { RuleId, RuleEntry } from './catalog.js';
+import { CourseRule } from './course-rules.js';
+
+/**
+ * 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.
+ */
+interface WaiverRuleSet {
+    readonly courseRules?: readonly CourseRule[];
+}
+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;
+}
+type WaiverDiagnosticCode = 'waiver-malformed' | 'waiver-invalid' | 'waiver-unused';
+interface WaiverDiagnostic {
+    readonly code: WaiverDiagnosticCode;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly file: string;
+    readonly line: number;
+}
+interface WaiverLessonInput {
+    readonly body: string;
+    readonly bodyLine?: number;
+    readonly source: {
+        readonly file: string;
+    };
+}
+/** True when `rule` may be waived with an inline comment. */
+declare function isWaivable(rule: RuleEntry): boolean;
+declare function collectWaivers(lesson: WaiverLessonInput, set?: WaiverRuleSet): {
+    readonly waivers: Waiver[];
+    readonly diagnostics: WaiverDiagnostic[];
+};
+/** Drop the located diagnostics the waivers cover; report waivers that covered nothing. */
+declare 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[];
+};
+
+export { type Waiver, type WaiverDiagnostic, type WaiverDiagnosticCode, type WaiverLessonInput, type WaiverRuleSet, applyWaivers, collectWaivers, isWaivable };

package/dist/rules/waivers.js

@@ -0,0 +1,132 @@
+import { lessonLine } from "../reference/gate-prose-notation.js";
+import {
+  entryById,
+  isCourseRuleId,
+  retiredRule,
+  ruleById,
+  ruleIdOf
+} from "./catalog.js";
+import { courseRuleEntry } from "./course-rules.js";
+function ruleEntry(id, set) {
+  const shipped = ruleById(id);
+  if (shipped !== void 0) return shipped;
+  const own = set.courseRules?.find((rule) => rule.id === id);
+  return own === void 0 ? void 0 : courseRuleEntry(own);
+}
+function isWaivable(rule) {
+  if (rule.locked !== void 0) 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+$/;
+function notWaivableBecause(id, set) {
+  const rule = ruleEntry(id, set);
+  if (rule === void 0) {
+    if (entryById(id) !== void 0) {
+      return `\`${id}\` is an invariant \u2014 always on, never waived`;
+    }
+    const gone = retiredRule(id);
+    if (gone !== void 0) {
+      return `rule ${id} was retired on ${gone.date}${gone.into === void 0 ? "" : ` into rule ${gone.into}, which is what to name instead`}`;
+    }
+    return isCourseRuleId(id) ? `no rule \`${id}\` \u2014 the \`X\` area is this course's own, and \`courseRules\` defines no ${id}` : `no rule \`${id}\``;
+  }
+  if (rule.locked !== void 0) return `rule ${id} is locked \u2014 ${rule.locked}`;
+  if (!isWaivable(rule)) {
+    return `rule ${id} is not waivable inline \u2014 its check is corpus- or file-level; silence it per key in \`lint-ignore.yml\`, or turn it off in \`rules.${id}\``;
+  }
+  return void 0;
+}
+function blockAfter(body, commentEnd) {
+  const lines = body.split("\n");
+  const commentLine = body.slice(0, commentEnd).split("\n").length;
+  let from = commentLine + 1;
+  while (from <= lines.length && lines[from - 1].trim() === "") from += 1;
+  if (from > lines.length) return void 0;
+  let to = from;
+  while (to + 1 <= lines.length && lines[to].trim() !== "") to += 1;
+  return { from, to };
+}
+function collectWaivers(lesson, set = {}) {
+  const waivers = [];
+  const diagnostics = [];
+  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> */}\` \u2014 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 !== void 0);
+    if (problems.length > 0) {
+      diagnostics.push({
+        code: "waiver-invalid",
+        severity: "error",
+        file,
+        line,
+        message: `waiver cannot apply \u2014 ${problems.join("; ")}.`
+      });
+      continue;
+    }
+    const block = blockAfter(lesson.body, match.index + match[0].length);
+    waivers.push({
+      file,
+      line,
+      ids,
+      reason,
+      fromLine: block === void 0 ? line : block.from + offset,
+      toLine: block === void 0 ? line : block.to + offset
+    });
+  }
+  return { waivers, diagnostics };
+}
+function applyWaivers(diagnostics, waivers, set = {}) {
+  if (waivers.length === 0) return { kept: [...diagnostics], unused: [] };
+  const used = new Map(waivers.map((w) => [w, /* @__PURE__ */ new Set()]));
+  const kept = diagnostics.filter((diagnostic) => {
+    if (diagnostic.code === void 0 || diagnostic.file === void 0 || diagnostic.line === void 0) {
+      return true;
+    }
+    const ownerId = ruleIdOf(diagnostic.code);
+    if (ownerId === void 0) 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 = [];
+  for (const waiver of waivers) {
+    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}\u2013${waiver.toLine}; remove it, or move it above the block it is for.`
+    });
+  }
+  return { kept, unused };
+}
+export {
+  applyWaivers,
+  collectWaivers,
+  isWaivable
+};

package/dist/session/PreferenceStore.d.ts

@@ -15,6 +15,11 @@
 interface PreferenceStore {
     get(key: string): string | null;
     set(key: string, value: string): void;
+    /**
+     * Forget `key`. Optional, so a store written for an older version still
+     * fits; a caller without it writes an empty value instead.
+     */
+    remove?(key: string): void;
 }
 /**
  * A `localStorage`-backed store. Every call is wrapped: storage can be absent

package/dist/session/PreferenceStore.js

@@ -12,6 +12,12 @@ function createBrowserPreferenceStore() {
         window.localStorage.setItem(key, value);
       } catch {
       }
+    },
+    remove(key) {
+      try {
+        window.localStorage.removeItem(key);
+      } catch {
+      }
     }
   };
 }
@@ -21,6 +27,9 @@ function createMemoryPreferenceStore() {
     get: (key) => map.get(key) ?? null,
     set: (key, value) => {
       map.set(key, value);
+    },
+    remove: (key) => {
+      map.delete(key);
     }
   };
 }

package/docs/VERSIONING.md

@@ -17,12 +17,12 @@ consumer-visible surface is:
 | Surface | Where |
 | --- | --- |
 | Published module entry points | `package.json` `publishConfig.exports` — the `explico/*` specifiers and their `.d.ts` |
-| Astro / React components | names + props of everything under `components/` that the README wires |
+| Astro / React components | names + props of everything under `components/` that the README wires, and the functions a component documents for authors to call (`setFigureState` in `components/figure/figure-state.ts`) |
 | remark / rehype adapter options | the option objects of `reference/*.mjs` (`remarkNotation`, `remarkCitation`, `createNotationKatexOptions`, …) |
 | The compiler manifest | `MANIFEST_SCHEMA_VERSION` and the shape of `Manifest` |
 | The `content` CLI | the commands, their flags, and every diagnostic `code` string |
 | `CourseConfig` | the interface in `compiler/course-config.ts` |
-| Build-enforced authoring rules | the `N*` / `V*` / `C*` rules marked *Build-enforced* in `docs/authoring/` |
+| Build-enforced authoring rules | the `N*` / `V*` / `C*` / `S*` / `P*` rules the catalog marks *script* or *partial* (`src/rules/catalog.ts`, indexed in `docs/authoring/README.md`). The `X*` area is a course's own (`courseRules`) and is not an engine surface — but the shape it is written in is, through `CourseConfig` |
 
 ## What each bump means
 
@@ -105,7 +105,9 @@ applies every intervening section in order.
    the `migrating.md` section.
 6. Run `pnpm build && pnpm test`, then inspect `pnpm pack --dry-run` and confirm
    that `docs/authoring/migrating.md` and `docs/authoring/agents.md` are listed.
-7. Commit, then `git tag vx.y.z`.
+7. Commit, then tag it annotated: `git tag -a vx.y.z -m "explico x.y.z"`. With
+   `push.followTags` on, a plain `git push` sends an annotated tag with its
+   commit; a lightweight tag never travels that way.
 
 ## When you change the engine