explico 0.7.0 → 0.11.0

package/src/reference/unit-words.ts

@@ -0,0 +1,233 @@
+/**
+ * Units written out as English words — "2 meters per second squared",
+ * "30 degrees", "$x = 3$ meters" — for rule N9's `spelled-unit` check
+ * (`gate-prose-notation.ts`). A unit is an upright symbol inside `$…$`
+ * (`$2\ \text{m/s}^2$`, `$30^{\circ}$`, `$x = 3\ \text{m}$`), so a spelled-out
+ * unit that quantifies something is the same mistake as `45 m/s` in plain
+ * text.
+ *
+ * A unit word on its own is not flagged — "measured in meters" names the
+ * unit, it does not state a quantity. What is flagged is a unit word
+ *
+ * - after a number, written in digits or as a word, in prose or typeset
+ *   (`2 meters`, `two-meter`, `$x = 3$ meters`);
+ * - after `per`, or before it (`rotations per second`, `meters per unit`);
+ * - with `square` / `cubic` before it or `squared` / `cubed` after it.
+ *
+ * "Degrees of freedom" is not a unit. Calendar time (day, week, month, year)
+ * and currency are left out on purpose: they are ordinary words in a finance
+ * course's prose, not SI units. `notation` `units:` strings are a different
+ * vocabulary (`units-vocab.ts`, rule N19) and are never scanned here.
+ */
+
+/** One unit: the regex stem of its English name (singular), and its symbol. */
+interface UnitWord {
+  readonly stem: string;
+  /** The symbol inside `\text{…}`, or `°` for an angle in degrees. */
+  readonly symbol: string;
+}
+
+// Prefixed forms first, so a suggestion names the right symbol; `\b` on both
+// sides keeps `gram` from matching inside `kilogram` or `program` anyway.
+const UNIT_WORDS: readonly UnitWord[] = [
+  { 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: '°' },
+];
+
+const NUMBER_WORDS: Readonly<Record<string, number>> = {
+  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: 1000,
+};
+
+const UNIT = `(?:${UNIT_WORDS.map((u) => `${u.stem}s?`).join('|')})`;
+// A unit word not glued to a hyphenated compound (`second-order`) and not the
+// start of "degrees of freedom".
+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('|')})`;
+
+/** Each shape that makes a unit word a stated quantity (or rate). */
+const PATTERNS: readonly RegExp[] = [
+  // 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'),
+];
+
+// An inline `$…$` whose last visible character is a digit, then a unit word
+// in the prose after it: `$x = 3$ meters`.
+const INLINE_MATH = /(?<![\\$])\$(?!\s)([^$\n]+?)(?<![\\\s])\$(?!\d)/g;
+const AFTER_MATH = new RegExp(String.raw`^(?:[ \t]+|-)(${COMPOUND})`, 'i');
+
+export interface SpelledUnit {
+  readonly index: number;
+  readonly token: string;
+  /** What to write instead, as `$…$`. */
+  readonly suggestion: string;
+}
+
+function unitOf(word: string): UnitWord | undefined {
+  return UNIT_WORDS.find((u) => new RegExp(`^${u.stem}s?$`, 'i').test(word));
+}
+
+/** The unit words a phrase contains, lowercased. */
+function unitWordsIn(phrase: string): string[] {
+  return [...phrase.matchAll(new RegExp(UNIT_WORD, 'gi'))].map((m) => m[0].toLowerCase());
+}
+
+/** `{2 meters per second squared}` → `\text{m/s}^{2}`, or undefined when it has no clean form. */
+function unitLatex(compound: string): string | undefined {
+  const groups = compound.trim().split(/\s+per\s+/i);
+  const segments: { text: string; power?: string }[] = [];
+  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'
+          : undefined;
+    const unit = words.map(unitOf).find(Boolean);
+    if (unit === undefined) return undefined;
+    if (unit.symbol === '°') {
+      // An angle alone is `^{\circ}`; degrees inside a rate has no tidy form.
+      return groups.length === 1 && power === undefined ? '^{\\circ}' : undefined;
+    }
+    segments.push({ text: `${i > 0 ? '/' : ''}${unit.symbol}`, ...(power ? { power } : {}) });
+  }
+  let out = '';
+  let pending = '';
+  for (const segment of segments) {
+    pending += segment.text;
+    if (segment.power !== undefined) {
+      out += `\\text{${pending}}^{${segment.power}}`;
+      pending = '';
+    }
+  }
+  return pending === '' ? out : `${out}\\text{${pending}}`;
+}
+
+function numberOf(word: string): string {
+  return /^\d/.test(word) ? word : String(NUMBER_WORDS[word.toLowerCase()] ?? word);
+}
+
+const GENERIC = 'a unit symbol in `$…$` (`$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');
+
+/** What to write instead of `phrase`, as a backticked `$…$`. */
+function suggest(phrase: string): string {
+  const numbered = LEADING_NUMBER.exec(phrase.trim());
+  const number = numbered ? numberOf(numbered[1]!) : undefined;
+  const rest = numbered ? numbered[2]! : phrase.trim();
+
+  // `rotations per second` / `per second`: only the part after `per` is a unit.
+  if (!STARTS_WITH_UNIT.test(rest)) {
+    const after = /\bper\s+([\s\S]*)$/i.exec(rest)?.[1];
+    const latex = after === undefined ? undefined : unitLatex(after);
+    return latex === undefined ? GENERIC : `the rate in \`$…$\`, with \`${latex}\` after the slash (\`$…/${latex}$\`)`;
+  }
+  // `meters per unit time`: the unit before a `per` that no unit follows.
+  const unit = rest.replace(/\s+per$/i, '');
+  const latex = unitLatex(unit);
+  if (latex === undefined) return GENERIC;
+  const trailingPer = unit !== rest ? '/…' : '';
+  if (number === undefined) return `\`$${latex}${trailingPer}$\``;
+  return `\`$${number}${latex.startsWith('^') ? '' : '\\ '}${latex}${trailingPer}$\``;
+}
+
+/** Overlapping matches collapse to the earliest, then longest. */
+function merge(found: SpelledUnit[]): SpelledUnit[] {
+  const sorted = [...found].sort((a, b) => a.index - b.index || b.token.length - a.token.length);
+  const out: SpelledUnit[] = [];
+  let end = -1;
+  for (const item of sorted) {
+    if (item.index < end) continue;
+    out.push(item);
+    end = item.index + item.token.length;
+  }
+  return out;
+}
+
+/**
+ * Every spelled-out unit in a lesson or assessment text. `prose` has code,
+ * math, references, JSX tags and comments blanked (`proseOnly`); `withMath`
+ * is the same text with math left in, for the `$x = 3$ meters` shape. Both
+ * must share offsets. A phrase whose unit words are all in `allow`
+ * (`rules.N9.allow`, singular or plural) is skipped.
+ */
+export function findSpelledUnits(
+  prose: string,
+  withMath: string,
+  allow: readonly string[] = [],
+): SpelledUnit[] {
+  const allowed = new Set(allow.map((word) => word.toLowerCase()));
+  const isAllowed = (phrase: string) => {
+    const words = unitWordsIn(phrase);
+    return words.length > 0 && words.every((w) => allowed.has(w) || allowed.has(w.replace(/s$/, '')));
+  };
+
+  const found: SpelledUnit[] = [];
+  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;
+    // The unit must sit in prose, not in a code span or tag that withMath kept.
+    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 === undefined
+      ? 'the unit inside the same `$…$` as its number'
+      : `\`$${content.trim()}${latex.startsWith('^') ? '' : '\\ '}${latex}$\``;
+    found.push({
+      index: m.index,
+      token: `${m[0]}${unit[0]}`,
+      suggestion: typeset,
+    });
+  }
+
+  return merge(found);
+}