explico 0.8.0 → 0.11.0

package/dist/reference/unit-words.js

@@ -0,0 +1,170 @@
+const UNIT_WORDS = [
+  { stem: "kilomet(?:er|re)", symbol: "km" },
+  { stem: "centimet(?:er|re)", symbol: "cm" },
+  { stem: "millimet(?:er|re)", symbol: "mm" },
+  { stem: "met(?:er|re)", symbol: "m" },
+  { stem: "millisecond", symbol: "ms" },
+  { stem: "second", symbol: "s" },
+  { stem: "minute", symbol: "min" },
+  { stem: "hour", symbol: "h" },
+  { stem: "kilogram", symbol: "kg" },
+  { stem: "milligram", symbol: "mg" },
+  { stem: "gram", symbol: "g" },
+  { stem: "newton", symbol: "N" },
+  { stem: "kilojoule", symbol: "kJ" },
+  { stem: "joule", symbol: "J" },
+  { stem: "kilowatt", symbol: "kW" },
+  { stem: "watt", symbol: "W" },
+  { stem: "hertz", symbol: "Hz" },
+  { stem: "kilopascal", symbol: "kPa" },
+  { stem: "pascal", symbol: "Pa" },
+  { stem: "volt", symbol: "V" },
+  { stem: "amp(?:ere)?", symbol: "A" },
+  { stem: "coulomb", symbol: "C" },
+  { stem: "kelvin", symbol: "K" },
+  { stem: "mole", symbol: "mol" },
+  { stem: "lit(?:er|re)", symbol: "L" },
+  { stem: "radian", symbol: "rad" },
+  { stem: "degree", symbol: "\xB0" }
+];
+const NUMBER_WORDS = {
+  zero: 0,
+  one: 1,
+  two: 2,
+  three: 3,
+  four: 4,
+  five: 5,
+  six: 6,
+  seven: 7,
+  eight: 8,
+  nine: 9,
+  ten: 10,
+  eleven: 11,
+  twelve: 12,
+  twenty: 20,
+  thirty: 30,
+  forty: 40,
+  fifty: 50,
+  sixty: 60,
+  seventy: 70,
+  eighty: 80,
+  ninety: 90,
+  hundred: 100,
+  thousand: 1e3
+};
+const UNIT = `(?:${UNIT_WORDS.map((u) => `${u.stem}s?`).join("|")})`;
+const UNIT_WORD = String.raw`\b${UNIT}\b(?!-)(?!\s+of\s+freedom\b)`;
+const POWER_BEFORE = String.raw`(?:(?:square|cubic)\s+)`;
+const POWER_AFTER = String.raw`(?:\s+(?:squared|cubed)\b)`;
+const TERM = String.raw`${POWER_BEFORE}?${UNIT_WORD}${POWER_AFTER}?`;
+const COMPOUND = String.raw`${TERM}(?:\s+per\s+${TERM})*`;
+const NUMBER = String.raw`(?:\d+(?:\.\d+)?|${Object.keys(NUMBER_WORDS).join("|")})`;
+const PATTERNS = [
+  // 2 meters per second squared · two-meter · 4 seconds
+  new RegExp(String.raw`(?<![\w.])${NUMBER}(?:\s+|-)${COMPOUND}`, "gi"),
+  // meters per second · rotations per second
+  new RegExp(String.raw`(?:${TERM}\s+)?\bper\s+${COMPOUND}`, "gi"),
+  // meters per unit time
+  new RegExp(String.raw`${TERM}\s+per\b`, "gi"),
+  // square meters · seconds squared
+  new RegExp(String.raw`${POWER_BEFORE}${UNIT_WORD}${POWER_AFTER}?|${UNIT_WORD}${POWER_AFTER}`, "gi")
+];
+const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
+const AFTER_MATH = new RegExp(String.raw`^(?:[ \t]+|-)(${COMPOUND})`, "i");
+function unitOf(word) {
+  return UNIT_WORDS.find((u) => new RegExp(`^${u.stem}s?$`, "i").test(word));
+}
+function unitWordsIn(phrase) {
+  return [...phrase.matchAll(new RegExp(UNIT_WORD, "gi"))].map((m) => m[0].toLowerCase());
+}
+function unitLatex(compound) {
+  const groups = compound.trim().split(/\s+per\s+/i);
+  const segments = [];
+  for (const [i, group] of groups.entries()) {
+    const words = group.toLowerCase().split(/\s+/);
+    const power = words.includes("square") || words.includes("squared") ? "2" : words.includes("cubic") || words.includes("cubed") ? "3" : void 0;
+    const unit = words.map(unitOf).find(Boolean);
+    if (unit === void 0) return void 0;
+    if (unit.symbol === "\xB0") {
+      return groups.length === 1 && power === void 0 ? "^{\\circ}" : void 0;
+    }
+    segments.push({ text: `${i > 0 ? "/" : ""}${unit.symbol}`, ...power ? { power } : {} });
+  }
+  let out = "";
+  let pending = "";
+  for (const segment of segments) {
+    pending += segment.text;
+    if (segment.power !== void 0) {
+      out += `\\text{${pending}}^{${segment.power}}`;
+      pending = "";
+    }
+  }
+  return pending === "" ? out : `${out}\\text{${pending}}`;
+}
+function numberOf(word) {
+  return /^\d/.test(word) ? word : String(NUMBER_WORDS[word.toLowerCase()] ?? word);
+}
+const GENERIC = "a unit symbol in `$\u2026$` (`$2\\ \\text{m/s}^2$`, `$30^{\\circ}$`)";
+const LEADING_NUMBER = new RegExp(String.raw`^(${NUMBER})(?:\s+|-)([\s\S]*)$`, "i");
+const STARTS_WITH_UNIT = new RegExp(String.raw`^${TERM}`, "i");
+function suggest(phrase) {
+  const numbered = LEADING_NUMBER.exec(phrase.trim());
+  const number = numbered ? numberOf(numbered[1]) : void 0;
+  const rest = numbered ? numbered[2] : phrase.trim();
+  if (!STARTS_WITH_UNIT.test(rest)) {
+    const after = /\bper\s+([\s\S]*)$/i.exec(rest)?.[1];
+    const latex2 = after === void 0 ? void 0 : unitLatex(after);
+    return latex2 === void 0 ? GENERIC : `the rate in \`$\u2026$\`, with \`${latex2}\` after the slash (\`$\u2026/${latex2}$\`)`;
+  }
+  const unit = rest.replace(/\s+per$/i, "");
+  const latex = unitLatex(unit);
+  if (latex === void 0) return GENERIC;
+  const trailingPer = unit !== rest ? "/\u2026" : "";
+  if (number === void 0) return `\`$${latex}${trailingPer}$\``;
+  return `\`$${number}${latex.startsWith("^") ? "" : "\\ "}${latex}${trailingPer}$\``;
+}
+function merge(found) {
+  const sorted = [...found].sort((a, b) => a.index - b.index || b.token.length - a.token.length);
+  const out = [];
+  let end = -1;
+  for (const item of sorted) {
+    if (item.index < end) continue;
+    out.push(item);
+    end = item.index + item.token.length;
+  }
+  return out;
+}
+function findSpelledUnits(prose, withMath, allow = []) {
+  const allowed = new Set(allow.map((word) => word.toLowerCase()));
+  const isAllowed = (phrase) => {
+    const words = unitWordsIn(phrase);
+    return words.length > 0 && words.every((w) => allowed.has(w) || allowed.has(w.replace(/s$/, "")));
+  };
+  const found = [];
+  for (const pattern of PATTERNS) {
+    for (const m of prose.matchAll(new RegExp(pattern.source, pattern.flags))) {
+      if (isAllowed(m[0])) continue;
+      found.push({ index: m.index, token: m[0], suggestion: suggest(m[0]) });
+    }
+  }
+  for (const m of withMath.matchAll(INLINE_MATH)) {
+    const content = m[1];
+    if (!/\d\s*$/.test(content.replace(/\\[,;:! ]|~|\\quad/g, ""))) continue;
+    const after = withMath.slice(m.index + m[0].length);
+    const unit = AFTER_MATH.exec(after);
+    if (unit === null || isAllowed(unit[1])) continue;
+    const at = m.index + m[0].length + unit[0].indexOf(unit[1]);
+    if (prose.slice(at, at + unit[1].length) !== unit[1]) continue;
+    const latex = unitLatex(unit[1]);
+    const typeset = latex === void 0 ? "the unit inside the same `$\u2026$` as its number" : `\`$${content.trim()}${latex.startsWith("^") ? "" : "\\ "}${latex}$\``;
+    found.push({
+      index: m.index,
+      token: `${m[0]}${unit[0]}`,
+      suggestion: typeset
+    });
+  }
+  return merge(found);
+}
+export {
+  findSpelledUnits
+};

package/dist/rules/catalog.d.ts

@@ -0,0 +1,176 @@
+/**
+ * The rule catalog — every authoring rule and every always-on invariant the
+ * engine enforces, as data.
+ *
+ * The prose of a rule (rationale, how to apply, examples) lives in
+ * `docs/authoring/<area>.md`; this module holds only what a machine needs:
+ * the permanent ID, the element(s) a rule affects, the diagnostic codes it
+ * owns and where they are emitted, its settings, and whether a course may
+ * turn it off. `scripts/agent/gen-rules.mjs` renders the README index from
+ * it and checks the `.md` files against it; `tests/rules/catalog.test.ts`
+ * fails when a code is emitted that no entry owns, or when two entries claim
+ * one code. See `docs/plans/rule-catalog.md` for the design.
+ *
+ * Two kinds of entry share the catalog:
+ *
+ * - A **rule** is a choice — a house style that could have gone another way.
+ *   It has a lettered ID and, unless `locked`, a checkbox in the course
+ *   settings (`rules.<ID>.enabled`). A rule that is retired leaves this list
+ *   for the compact {@link RetiredRule} one, which costs a reader four lines
+ *   instead of a whole entry.
+ * - An **invariant** is what the syntax means — a `[[key]]` must resolve, a
+ *   `\label{eq:…}` key is unique. One entry per feature, always on,
+ *   documented next to the syntax rather than as a rule page.
+ *
+ * Enforcement is never typed by hand: it is derived from `checks` and
+ * `unchecked` by {@link enforcementOf}.
+ */
+/** The part of a page a rule is about. The first tag on an entry is primary. */
+type Element = 'prose' | 'math' | 'equation' | 'notation' | 'heading' | 'part-page' | 'plot' | 'diagram' | 'table' | 'assessment' | 'source' | 'changelog';
+/** Every element, in the order the rules-in-effect page lists them. */
+declare const ELEMENTS: readonly Element[];
+/**
+ * The five areas the engine ships, plus `X` — reserved for a course's own rules
+ * and never used by an engine rule (see {@link CourseRuleId}).
+ */
+type RuleArea = 'N' | 'V' | 'C' | 'S' | 'P' | 'X';
+type RuleId = `${RuleArea}${number}`;
+/**
+ * A course's own rule, defined in `courseRules` in the course settings rather
+ * than here (`src/rules/course-rules.ts`). `X` is permanently reserved for
+ * them: the engine never ships an `X` rule, so a course can number its own
+ * `X1`, `X2`, … without a future engine release colliding with them. The form
+ * is the same as an engine rule's, so one ID works everywhere — a commit
+ * message, a diagnostic, a waiver, the rules-in-effect page.
+ */
+type CourseRuleId = `X${number}`;
+/** True for a well-formed course-rule ID (`X1`…`X99`). */
+declare function isCourseRuleId(id: string): id is CourseRuleId;
+type Severity = 'error' | 'warning' | 'info';
+/** Where a code is emitted: engine source module + the function that pushes it. */
+interface Emitter {
+    /** Repo-relative engine source path, e.g. `src/reference/gate-heading-length.ts`. */
+    readonly module: string;
+    /** A `function`/`const` name in that module; existence-checked by the tests. */
+    readonly fn: string;
+}
+interface RuleCheck {
+    /** The `code` the diagnostic carries. Unique across the whole catalog. */
+    readonly code: string;
+    readonly severity: Severity;
+    readonly emitters: readonly [Emitter, ...Emitter[]];
+    /**
+     * True when a lesson-body emission carries `file` + `line`, so a per-place
+     * waiver can target it. Corpus-level and per-file checks are `false`.
+     */
+    readonly located: boolean;
+}
+/** A course-settable parameter of a rule — a tiny JSON-Schema subset. */
+type SettingSchema = {
+    readonly type: 'integer';
+    readonly minimum?: number;
+    readonly default: number;
+} | {
+    readonly type: 'boolean';
+    readonly default: boolean;
+} | {
+    readonly type: 'array';
+    readonly items: 'string';
+    readonly default: readonly string[];
+};
+interface SettingSpec {
+    readonly key: string;
+    readonly title: string;
+    readonly description: string;
+    readonly schema: SettingSchema;
+}
+interface RuleEntry {
+    readonly kind: 'rule';
+    /** Permanent. A rule that is retired keeps its ID in {@link RetiredRule}. */
+    readonly id: RuleId;
+    /** The bold first sentence of the rule page, verbatim. */
+    readonly title: string;
+    /** Index-table phrasing, one line; the README row uses it over `title`. */
+    readonly short?: string;
+    readonly elements: readonly [Element, ...Element[]];
+    /**
+     * Path + anchor under `docs/authoring/`, e.g. `notation.md#n9`. On a course
+     * rule (`source: 'course'`) it is instead a link the course owns, used as
+     * given.
+     */
+    readonly doc: string;
+    /** What an agent needs in order to comply — at most three sentences, no rationale. */
+    readonly summary: string;
+    readonly checks: readonly RuleCheck[];
+    /** What no script sees. Present → enforcement is `partial`. */
+    readonly unchecked?: string;
+    /** Why the rule has no checkbox. */
+    readonly locked?: string;
+    readonly settings?: readonly SettingSpec[];
+    /**
+     * Set only on the synthetic entry built from a course's own `courseRules`
+     * block (`courseRuleEntry`). The static catalog never sets it, so `source`
+     * absent means "shipped with the engine".
+     */
+    readonly source?: 'course';
+}
+interface InvariantEntry {
+    readonly kind: 'invariant';
+    /** A feature slug, e.g. `notation-references`. */
+    readonly id: string;
+    readonly title: string;
+    readonly elements: readonly [Element, ...Element[]];
+    readonly doc: string;
+    readonly summary: string;
+    readonly checks: readonly [RuleCheck, ...RuleCheck[]];
+}
+type CatalogEntry = RuleEntry | InvariantEntry;
+type Enforcement = 'script' | 'partial' | 'guide';
+/**
+ * A rule that is no longer in force. It keeps its ID forever — an old commit
+ * message, review comment or waiver naming `N3` must stay unambiguous — but it
+ * is deliberately *not* a {@link RuleEntry}: nothing iterates it as a rule, it
+ * has no page in `docs/authoring/`, it is absent from the settings schema and
+ * from `build/rules-in-effect.md`, and an agent never reads it while drafting.
+ * The one place it is written out is the generated table in
+ * `docs/authoring/retired.md`, which is where a migration guide links.
+ */
+interface RetiredRule {
+    readonly id: RuleId;
+    /** The sentence the rule had, so an old reference to it still resolves. */
+    readonly title: string;
+    /** `YYYY-MM-DD`. */
+    readonly date: string;
+    /** The rule it was folded into, when it was folded into one. */
+    readonly into?: RuleId;
+    /** Why, and what changed for an author — one or two sentences. */
+    readonly why: string;
+}
+declare const CATALOG: readonly CatalogEntry[];
+/** The rule or invariant that owns a diagnostic code, if any. */
+declare function ownerOf(code: string): CatalogEntry | undefined;
+/**
+ * The **rule** ID a diagnostic code belongs to — a lettered engine rule, or a
+ * course rule, whose single check carries the rule's own ID as its code.
+ * `undefined` for a code owned by an invariant (there is no rule page to read)
+ * and for a code nothing owns.
+ */
+declare function ruleIdOf(code: string): RuleId | undefined;
+declare function entryById(id: string): CatalogEntry | undefined;
+declare function ruleById(id: string): RuleEntry | undefined;
+declare function rules(): readonly RuleEntry[];
+/** Every retired rule, oldest ID first. Read by the generated table and nothing else. */
+declare function retiredRules(): readonly RetiredRule[];
+/** The retired rule with this ID, if the ID belonged to one. */
+declare function retiredRule(id: string): RetiredRule | undefined;
+declare function invariants(): readonly InvariantEntry[];
+/**
+ * `script` — every violation a check can see is reported; `partial` — checks
+ * exist but the rule says what they miss; `guide` — nothing runs, a reviewer
+ * (or the agent's own reading) is the enforcement.
+ */
+declare function enforcementOf(entry: CatalogEntry): Enforcement;
+/** Every code the catalog owns, sorted. */
+declare function ownedCodes(): readonly string[];
+
+export { CATALOG, type CatalogEntry, type CourseRuleId, ELEMENTS, type Element, type Emitter, type Enforcement, type InvariantEntry, type RetiredRule, type RuleArea, type RuleCheck, type RuleEntry, type RuleId, type SettingSchema, type SettingSpec, type Severity, enforcementOf, entryById, invariants, isCourseRuleId, ownedCodes, ownerOf, retiredRule, retiredRules, ruleById, ruleIdOf, rules };