@descent-vtt/spec-graph 0.2.0

package/dist/state.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Item state resolution.
+ *
+ * The premise of this module is that `- [ ]` and `- [x]` are the *least*
+ * reliable statement a document makes about an obligation. Real specifications
+ * record outcomes in prose, on a continuation line, days after the checkbox was
+ * written and nobody went back to tick it:
+ *
+ * ```md
+ * - [ ] Should the write path shard before the migration?
+ *       **Resolved (2026-03):** no - one node holds three years of growth.
+ * ```
+ *
+ * A grep for `- [ ]` calls that an open question and re-opens a settled debate.
+ * A grep for `- [x]` misses it entirely. spec-graph reads both signals, lets the
+ * more specific one win, and *reports the disagreement* rather than hiding it,
+ * because a checkbox that contradicts its own body is itself a defect worth
+ * knowing about.
+ */
+import type { Directive } from './directives.js';
+import type { ListItem } from './markdown.js';
+import { type LineIndex } from './source.js';
+import { type Disposition, type Openness, type StateSignal } from './types.js';
+export interface StateInput {
+    readonly file: string;
+    readonly index: LineIndex;
+    readonly item: ListItem;
+    /** Heading path the item sits under. */
+    readonly section: readonly string[];
+    /** A `@spec-item` directive attached to the item, when there is one. */
+    readonly directive: Directive | null;
+    /** True when the item sits under a heading that declares obligations. */
+    readonly inObligationSection: boolean;
+}
+export interface ResolvedState {
+    readonly disposition: Disposition;
+    readonly openness: Openness;
+    readonly evidence: StateSignal;
+    /** Signals that disagree with `evidence` about how open the item is. */
+    readonly conflicts: readonly StateSignal[];
+}
+/** Collects every state signal on an item and decides between them. */
+export declare function resolveItemState(input: StateInput): ResolvedState;
+/** Exposed for the query language, which lets users filter on these names. */
+export declare const KNOWN_STATE_WORDS: readonly string[];

package/dist/state.js

@@ -0,0 +1,330 @@
+/**
+ * Item state resolution.
+ *
+ * The premise of this module is that `- [ ]` and `- [x]` are the *least*
+ * reliable statement a document makes about an obligation. Real specifications
+ * record outcomes in prose, on a continuation line, days after the checkbox was
+ * written and nobody went back to tick it:
+ *
+ * ```md
+ * - [ ] Should the write path shard before the migration?
+ *       **Resolved (2026-03):** no - one node holds three years of growth.
+ * ```
+ *
+ * A grep for `- [ ]` calls that an open question and re-opens a settled debate.
+ * A grep for `- [x]` misses it entirely. spec-graph reads both signals, lets the
+ * more specific one win, and *reports the disagreement* rather than hiding it,
+ * because a checkbox that contradicts its own body is itself a defect worth
+ * knowing about.
+ */
+import { attr } from './directives.js';
+import { refOf } from './source.js';
+import { OPENNESS_OF } from './types.js';
+/** Which signal wins when two disagree. Higher is more specific. */
+const SIGNAL_PRIORITY = {
+    directive: 5,
+    marker: 4,
+    strikethrough: 3,
+    checkbox: 2,
+    section: 1,
+    default: 0,
+};
+/**
+ * Checkbox characters.
+ *
+ * `[ ]` and `[x]` are universal; the rest come from conventions that several
+ * ecosystems share (`[~]` partial, `[-]` dropped, `[?]` question, `[/]` in
+ * progress). Reading them costs nothing and refusing to would throw away the
+ * one place a document states its nuance unambiguously.
+ */
+const CHECKBOX_STATE = {
+    ' ': 'unresolved',
+    x: 'satisfied',
+    X: 'satisfied',
+    '+': 'satisfied',
+    '~': 'narrowed',
+    '/': 'narrowed',
+    '-': 'rejected',
+    '?': 'unresolved',
+    '!': 'unresolved',
+    '*': 'unresolved',
+};
+/**
+ * Prose markers, by the state they announce.
+ *
+ * Matched only in the qualified forms real documents use - `**Resolved:**`,
+ * `RESOLVED -`, `**Moot**` - never as bare words, so ordinary prose such as
+ * "we resolved to keep the queue" does not close an item.
+ */
+const MARKERS = {
+    satisfied: [
+        'resolved',
+        'answered',
+        'decided',
+        'settled',
+        'done',
+        'complete',
+        'completed',
+        'closed',
+        'fixed',
+        'shipped',
+        'addressed',
+        'implemented',
+        'solved',
+        'confirmed',
+    ],
+    narrowed: [
+        'partially resolved',
+        'partially answered',
+        'partially done',
+        'partly resolved',
+        'narrowed',
+        'narrowed to',
+        'scoped down',
+        'reduced scope',
+        'reduced to',
+        'partial',
+        'in progress',
+        'remaining',
+        'split',
+    ],
+    delegated: [
+        'delegated',
+        'delegated to',
+        'moved to',
+        'tracked in',
+        'tracked by',
+        'handed off',
+        'handed off to',
+        'handed to',
+        'deferred to',
+        'follow up in',
+        'follow-up in',
+        'followup in',
+        'continued in',
+        'owned by',
+    ],
+    'accepted-debt': [
+        'accepted debt',
+        'accepted as debt',
+        'accepted risk',
+        'known limitation',
+        'known issue',
+        'known gap',
+        'technical debt',
+        'tech debt',
+        'wontfix',
+        "won't fix",
+        'will not fix',
+        'by design',
+        'tolerated',
+        'living with it',
+    ],
+    rejected: [
+        'rejected',
+        'declined',
+        'dropped',
+        'not doing',
+        'will not do',
+        'abandoned',
+        'cancelled',
+        'canceled',
+        'withdrawn',
+    ],
+    obviated: [
+        'no longer applicable',
+        'no longer relevant',
+        'no longer needed',
+        'overtaken by events',
+        'premise invalid',
+        'obviated',
+        'obsolete',
+        'not applicable',
+        'moot',
+        'void',
+        'n/a',
+        'obe',
+    ],
+    unresolved: ['unresolved', 'still open', 'open question', 'tbd', 'undecided', 'reopened'],
+};
+/** Words accepted in a `state=` attribute, including friendly synonyms. */
+const STATE_ALIASES = {
+    open: 'unresolved',
+    unresolved: 'unresolved',
+    todo: 'unresolved',
+    narrowed: 'narrowed',
+    partial: 'narrowed',
+    delegated: 'delegated',
+    satisfied: 'satisfied',
+    resolved: 'satisfied',
+    done: 'satisfied',
+    closed: 'satisfied',
+    'accepted-debt': 'accepted-debt',
+    debt: 'accepted-debt',
+    wontfix: 'accepted-debt',
+    rejected: 'rejected',
+    declined: 'rejected',
+    obviated: 'obviated',
+    moot: 'obviated',
+};
+const MARKER_PATTERN = buildMarkerPattern();
+const MARKER_LOOKUP = markerLookup();
+/** Collects every state signal on an item and decides between them. */
+export function resolveItemState(input) {
+    const { file, index, item } = input;
+    const signals = [];
+    const at = (start, end) => refOf(file, index, start, end);
+    if (input.directive) {
+        const declared = attr(input.directive, 'state');
+        if (declared) {
+            const mapped = STATE_ALIASES[declared.value.toLowerCase()];
+            if (mapped) {
+                signals.push({
+                    source: 'directive',
+                    disposition: mapped,
+                    raw: declared.value,
+                    at: at(declared.start, declared.end),
+                });
+            }
+        }
+    }
+    // Markers are searched in the masked body: a fenced example nested under an
+    // item must never be able to close it.
+    for (const found of findMarkers(item.maskedBody)) {
+        signals.push({
+            source: 'marker',
+            disposition: found.disposition,
+            raw: found.raw,
+            at: at(item.textStart + found.start, item.textStart + found.end),
+        });
+    }
+    const struck = strikethroughOf(item.firstLine);
+    if (struck) {
+        signals.push({
+            source: 'strikethrough',
+            disposition: 'satisfied',
+            raw: struck,
+            at: at(item.textStart, item.textStart + item.firstLine.length),
+        });
+    }
+    if (item.checkbox !== null && item.checkboxStart !== null) {
+        const mapped = CHECKBOX_STATE[item.checkbox];
+        if (mapped) {
+            signals.push({
+                source: 'checkbox',
+                disposition: mapped,
+                raw: `[${item.checkbox}]`,
+                at: at(item.checkboxStart, item.checkboxStart + 3),
+            });
+        }
+    }
+    if (input.inObligationSection) {
+        signals.push({
+            source: 'section',
+            disposition: 'unresolved',
+            raw: input.section[input.section.length - 1] ?? '',
+            at: at(item.start, item.end),
+        });
+    }
+    if (signals.length === 0) {
+        const fallback = {
+            source: 'default',
+            disposition: 'unresolved',
+            raw: '',
+            at: at(item.start, item.end),
+        };
+        return { disposition: 'unresolved', openness: 'open', evidence: fallback, conflicts: [] };
+    }
+    // The most specific signal wins; ties go to the one written last, which is
+    // the one a reader of the document sees as the final word.
+    let winner = signals[0];
+    for (const signal of signals) {
+        const better = SIGNAL_PRIORITY[signal.source] - SIGNAL_PRIORITY[winner.source];
+        if (better > 0 || (better === 0 && signal.at.span.start.offset > winner.at.span.start.offset)) {
+            winner = signal;
+        }
+    }
+    const openness = OPENNESS_OF[winner.disposition];
+    // Only disagreement about *openness* is a conflict. A body that says
+    // "Resolved" under a ticked checkbox agrees with it; one under an empty
+    // checkbox does not, and that is worth a human looking at.
+    const conflicts = signals.filter((signal) => signal !== winner && signal.source !== 'section' && OPENNESS_OF[signal.disposition] !== openness);
+    return { disposition: winner.disposition, openness, evidence: winner, conflicts };
+}
+function buildMarkerPattern() {
+    const phrases = Object.values(MARKERS)
+        .flat()
+        // Longest first so `partially resolved` is not eaten by `resolved`.
+        .sort((a, b) => b.length - a.length)
+        .map(escapeRegExp)
+        // Allow the writer to hyphenate or space multi-word markers either way.
+        .map((phrase) => phrase.replace(/\\?[ -]/g, '[ \\-]'));
+    return new RegExp(
+    // A marker only counts at the start of a statement: the start of the item,
+    // a new line, after a sentence ends, or after an emphasis opener.
+    String.raw `(?:^|\n|[.?!]\s+|[(\[])` +
+        // Skip block-quote and list markers, but only when the marker character is
+        // followed by whitespace. Without that guard the `*` of `**Resolved**`
+        // reads as a bullet and the emphasis wrapper is lost.
+        String.raw `(?:[ \t>•]|(?:[-*+]|\d{1,9}[.)])[ \t]+)*` +
+        // Optional emphasis wrapper, remembered so `**Moot**` qualifies without a colon.
+        String.raw `(\*{1,2}|_{1,2})?` +
+        String.raw `\s*(${phrases.join('|')})` +
+        String.raw `(\*{1,2}|_{1,2})?` +
+        // An optional dated parenthetical: `Resolved (2026-03):`.
+        String.raw `\s*(?:[(\[][^)\]\n]{0,60}[)\]])?` +
+        // Optional, and validated in code below: an emphasised or shouted marker
+        // stands on its own, a bare lower-case word never does.
+        String.raw `\s*([:：]|[-–—]\s|\.|$|\n)?`, 'gim');
+}
+function findMarkers(body) {
+    const out = [];
+    MARKER_PATTERN.lastIndex = 0;
+    for (let m = MARKER_PATTERN.exec(body); m !== null; m = MARKER_PATTERN.exec(body)) {
+        const phrase = m[2];
+        const emphasisOpen = m[1];
+        const emphasisClose = m[3];
+        const qualifier = (m[4] ?? '').trim();
+        const emphasised = emphasisOpen !== undefined && emphasisClose !== undefined;
+        const punctuated = qualifier === ':' || qualifier === '：' || qualifier.startsWith('-') || qualifier === '.';
+        const shouted = phrase === phrase.toUpperCase() && /[A-Z]/.test(phrase);
+        // Without one of these three the match is ordinary prose. "We resolved to
+        // keep the queue" must not close an item.
+        if (!emphasised && !punctuated && !shouted)
+            continue;
+        const disposition = MARKER_LOOKUP.get(normalisePhrase(phrase));
+        if (!disposition)
+            continue;
+        const start = (m.index ?? 0) + m[0].indexOf(phrase);
+        out.push({ disposition, raw: phrase, start, end: start + phrase.length });
+        // Overlapping alternatives would double-count; resume after this match.
+        MARKER_PATTERN.lastIndex = start + phrase.length;
+    }
+    return out;
+}
+/** Built once: this used to be rebuilt for every item in the corpus. */
+function markerLookup() {
+    const map = new Map();
+    for (const [disposition, phrases] of Object.entries(MARKERS)) {
+        for (const phrase of phrases)
+            map.set(normalisePhrase(phrase), disposition);
+    }
+    return map;
+}
+function normalisePhrase(phrase) {
+    return phrase.toLowerCase().replace(/[\s-]+/g, ' ').trim();
+}
+/** Returns the struck text when the whole line is wrapped in `~~`. */
+function strikethroughOf(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('~~') || !trimmed.endsWith('~~') || trimmed.length < 5)
+        return null;
+    const inner = trimmed.slice(2, -2);
+    return inner.includes('~~') ? null : trimmed;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Exposed for the query language, which lets users filter on these names. */
+export const KNOWN_STATE_WORDS = Object.keys(STATE_ALIASES);
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Item state resolution.\n *\n * The premise of this module is that `- [ ]` and `- [x]` are the *least*\n * reliable statement a document makes about an obligation. Real specifications\n * record outcomes in prose, on a continuation line, days after the checkbox was\n * written and nobody went back to tick it:\n *\n * ```md\n * - [ ] Should the write path shard before the migration?\n *       **Resolved (2026-03):** no - one node holds three years of growth.\n * ```\n *\n * A grep for `- [ ]` calls that an open question and re-opens a settled debate.\n * A grep for `- [x]` misses it entirely. spec-graph reads both signals, lets the\n * more specific one win, and *reports the disagreement* rather than hiding it,\n * because a checkbox that contradicts its own body is itself a defect worth\n * knowing about.\n */\n\nimport type { Directive } from './directives.js';\nimport { attr } from './directives.js';\nimport type { ListItem } from './markdown.js';\nimport { refOf, type LineIndex } from './source.js';\nimport { OPENNESS_OF, type Disposition, type Openness, type SourceRef, type StateSignal } from './types.js';\n\n/** Which signal wins when two disagree. Higher is more specific. */\nconst SIGNAL_PRIORITY: Readonly<Record<StateSignal['source'], number>> = {\n  directive: 5,\n  marker: 4,\n  strikethrough: 3,\n  checkbox: 2,\n  section: 1,\n  default: 0,\n};\n\n/**\n * Checkbox characters.\n *\n * `[ ]` and `[x]` are universal; the rest come from conventions that several\n * ecosystems share (`[~]` partial, `[-]` dropped, `[?]` question, `[/]` in\n * progress). Reading them costs nothing and refusing to would throw away the\n * one place a document states its nuance unambiguously.\n */\nconst CHECKBOX_STATE: Readonly<Record<string, Disposition>> = {\n  ' ': 'unresolved',\n  x: 'satisfied',\n  X: 'satisfied',\n  '+': 'satisfied',\n  '~': 'narrowed',\n  '/': 'narrowed',\n  '-': 'rejected',\n  '?': 'unresolved',\n  '!': 'unresolved',\n  '*': 'unresolved',\n};\n\n/**\n * Prose markers, by the state they announce.\n *\n * Matched only in the qualified forms real documents use - `**Resolved:**`,\n * `RESOLVED -`, `**Moot**` - never as bare words, so ordinary prose such as\n * \"we resolved to keep the queue\" does not close an item.\n */\nconst MARKERS: Readonly<Record<Disposition, readonly string[]>> = {\n  satisfied: [\n    'resolved',\n    'answered',\n    'decided',\n    'settled',\n    'done',\n    'complete',\n    'completed',\n    'closed',\n    'fixed',\n    'shipped',\n    'addressed',\n    'implemented',\n    'solved',\n    'confirmed',\n  ],\n  narrowed: [\n    'partially resolved',\n    'partially answered',\n    'partially done',\n    'partly resolved',\n    'narrowed',\n    'narrowed to',\n    'scoped down',\n    'reduced scope',\n    'reduced to',\n    'partial',\n    'in progress',\n    'remaining',\n    'split',\n  ],\n  delegated: [\n    'delegated',\n    'delegated to',\n    'moved to',\n    'tracked in',\n    'tracked by',\n    'handed off',\n    'handed off to',\n    'handed to',\n    'deferred to',\n    'follow up in',\n    'follow-up in',\n    'followup in',\n    'continued in',\n    'owned by',\n  ],\n  'accepted-debt': [\n    'accepted debt',\n    'accepted as debt',\n    'accepted risk',\n    'known limitation',\n    'known issue',\n    'known gap',\n    'technical debt',\n    'tech debt',\n    'wontfix',\n    \"won't fix\",\n    'will not fix',\n    'by design',\n    'tolerated',\n    'living with it',\n  ],\n  rejected: [\n    'rejected',\n    'declined',\n    'dropped',\n    'not doing',\n    'will not do',\n    'abandoned',\n    'cancelled',\n    'canceled',\n    'withdrawn',\n  ],\n  obviated: [\n    'no longer applicable',\n    'no longer relevant',\n    'no longer needed',\n    'overtaken by events',\n    'premise invalid',\n    'obviated',\n    'obsolete',\n    'not applicable',\n    'moot',\n    'void',\n    'n/a',\n    'obe',\n  ],\n  unresolved: ['unresolved', 'still open', 'open question', 'tbd', 'undecided', 'reopened'],\n};\n\n/** Words accepted in a `state=` attribute, including friendly synonyms. */\nconst STATE_ALIASES: Readonly<Record<string, Disposition>> = {\n  open: 'unresolved',\n  unresolved: 'unresolved',\n  todo: 'unresolved',\n  narrowed: 'narrowed',\n  partial: 'narrowed',\n  delegated: 'delegated',\n  satisfied: 'satisfied',\n  resolved: 'satisfied',\n  done: 'satisfied',\n  closed: 'satisfied',\n  'accepted-debt': 'accepted-debt',\n  debt: 'accepted-debt',\n  wontfix: 'accepted-debt',\n  rejected: 'rejected',\n  declined: 'rejected',\n  obviated: 'obviated',\n  moot: 'obviated',\n};\n\nconst MARKER_PATTERN = buildMarkerPattern();\nconst MARKER_LOOKUP = markerLookup();\n\nexport interface StateInput {\n  readonly file: string;\n  readonly index: LineIndex;\n  readonly item: ListItem;\n  /** Heading path the item sits under. */\n  readonly section: readonly string[];\n  /** A `@spec-item` directive attached to the item, when there is one. */\n  readonly directive: Directive | null;\n  /** True when the item sits under a heading that declares obligations. */\n  readonly inObligationSection: boolean;\n}\n\nexport interface ResolvedState {\n  readonly disposition: Disposition;\n  readonly openness: Openness;\n  readonly evidence: StateSignal;\n  /** Signals that disagree with `evidence` about how open the item is. */\n  readonly conflicts: readonly StateSignal[];\n}\n\n/** Collects every state signal on an item and decides between them. */\nexport function resolveItemState(input: StateInput): ResolvedState {\n  const { file, index, item } = input;\n  const signals: StateSignal[] = [];\n\n  const at = (start: number, end: number): SourceRef => refOf(file, index, start, end);\n\n  if (input.directive) {\n    const declared = attr(input.directive, 'state');\n    if (declared) {\n      const mapped = STATE_ALIASES[declared.value.toLowerCase()];\n      if (mapped) {\n        signals.push({\n          source: 'directive',\n          disposition: mapped,\n          raw: declared.value,\n          at: at(declared.start, declared.end),\n        });\n      }\n    }\n  }\n\n  // Markers are searched in the masked body: a fenced example nested under an\n  // item must never be able to close it.\n  for (const found of findMarkers(item.maskedBody)) {\n    signals.push({\n      source: 'marker',\n      disposition: found.disposition,\n      raw: found.raw,\n      at: at(item.textStart + found.start, item.textStart + found.end),\n    });\n  }\n\n  const struck = strikethroughOf(item.firstLine);\n  if (struck) {\n    signals.push({\n      source: 'strikethrough',\n      disposition: 'satisfied',\n      raw: struck,\n      at: at(item.textStart, item.textStart + item.firstLine.length),\n    });\n  }\n\n  if (item.checkbox !== null && item.checkboxStart !== null) {\n    const mapped = CHECKBOX_STATE[item.checkbox];\n    if (mapped) {\n      signals.push({\n        source: 'checkbox',\n        disposition: mapped,\n        raw: `[${item.checkbox}]`,\n        at: at(item.checkboxStart, item.checkboxStart + 3),\n      });\n    }\n  }\n\n  if (input.inObligationSection) {\n    signals.push({\n      source: 'section',\n      disposition: 'unresolved',\n      raw: input.section[input.section.length - 1] ?? '',\n      at: at(item.start, item.end),\n    });\n  }\n\n  if (signals.length === 0) {\n    const fallback: StateSignal = {\n      source: 'default',\n      disposition: 'unresolved',\n      raw: '',\n      at: at(item.start, item.end),\n    };\n    return { disposition: 'unresolved', openness: 'open', evidence: fallback, conflicts: [] };\n  }\n\n  // The most specific signal wins; ties go to the one written last, which is\n  // the one a reader of the document sees as the final word.\n  let winner = signals[0] as StateSignal;\n  for (const signal of signals) {\n    const better = SIGNAL_PRIORITY[signal.source] - SIGNAL_PRIORITY[winner.source];\n    if (better > 0 || (better === 0 && signal.at.span.start.offset > winner.at.span.start.offset)) {\n      winner = signal;\n    }\n  }\n\n  const openness = OPENNESS_OF[winner.disposition];\n  // Only disagreement about *openness* is a conflict. A body that says\n  // \"Resolved\" under a ticked checkbox agrees with it; one under an empty\n  // checkbox does not, and that is worth a human looking at.\n  const conflicts = signals.filter(\n    (signal) => signal !== winner && signal.source !== 'section' && OPENNESS_OF[signal.disposition] !== openness,\n  );\n\n  return { disposition: winner.disposition, openness, evidence: winner, conflicts };\n}\n\n/* -------------------------------------------------------------------------- */\n/* Marker matching                                                            */\n/* -------------------------------------------------------------------------- */\n\ninterface MarkerHit {\n  readonly disposition: Disposition;\n  readonly raw: string;\n  readonly start: number;\n  readonly end: number;\n}\n\nfunction buildMarkerPattern(): RegExp {\n  const phrases = Object.values(MARKERS)\n    .flat()\n    // Longest first so `partially resolved` is not eaten by `resolved`.\n    .sort((a, b) => b.length - a.length)\n    .map(escapeRegExp)\n    // Allow the writer to hyphenate or space multi-word markers either way.\n    .map((phrase) => phrase.replace(/\\\\?[ -]/g, '[ \\\\-]'));\n\n  return new RegExp(\n    // A marker only counts at the start of a statement: the start of the item,\n    // a new line, after a sentence ends, or after an emphasis opener.\n    String.raw`(?:^|\\n|[.?!]\\s+|[(\\[])` +\n      // Skip block-quote and list markers, but only when the marker character is\n      // followed by whitespace. Without that guard the `*` of `**Resolved**`\n      // reads as a bullet and the emphasis wrapper is lost.\n      String.raw`(?:[ \\t>•]|(?:[-*+]|\\d{1,9}[.)])[ \\t]+)*` +\n      // Optional emphasis wrapper, remembered so `**Moot**` qualifies without a colon.\n      String.raw`(\\*{1,2}|_{1,2})?` +\n      String.raw`\\s*(${phrases.join('|')})` +\n      String.raw`(\\*{1,2}|_{1,2})?` +\n      // An optional dated parenthetical: `Resolved (2026-03):`.\n      String.raw`\\s*(?:[(\\[][^)\\]\\n]{0,60}[)\\]])?` +\n      // Optional, and validated in code below: an emphasised or shouted marker\n      // stands on its own, a bare lower-case word never does.\n      String.raw`\\s*([:：]|[-–—]\\s|\\.|$|\\n)?`,\n    'gim',\n  );\n}\n\nfunction findMarkers(body: string): MarkerHit[] {\n  const out: MarkerHit[] = [];\n\n  MARKER_PATTERN.lastIndex = 0;\n  for (let m = MARKER_PATTERN.exec(body); m !== null; m = MARKER_PATTERN.exec(body)) {\n    const phrase = m[2] as string;\n    const emphasisOpen = m[1];\n    const emphasisClose = m[3];\n    const qualifier = (m[4] ?? '').trim();\n\n    const emphasised = emphasisOpen !== undefined && emphasisClose !== undefined;\n    const punctuated = qualifier === ':' || qualifier === '：' || qualifier.startsWith('-') || qualifier === '.';\n    const shouted = phrase === phrase.toUpperCase() && /[A-Z]/.test(phrase);\n\n    // Without one of these three the match is ordinary prose. \"We resolved to\n    // keep the queue\" must not close an item.\n    if (!emphasised && !punctuated && !shouted) continue;\n\n    const disposition = MARKER_LOOKUP.get(normalisePhrase(phrase));\n    if (!disposition) continue;\n\n    const start = (m.index ?? 0) + (m[0] as string).indexOf(phrase);\n    out.push({ disposition, raw: phrase, start, end: start + phrase.length });\n\n    // Overlapping alternatives would double-count; resume after this match.\n    MARKER_PATTERN.lastIndex = start + phrase.length;\n  }\n\n  return out;\n}\n\n/** Built once: this used to be rebuilt for every item in the corpus. */\nfunction markerLookup(): Map<string, Disposition> {\n  const map = new Map<string, Disposition>();\n  for (const [disposition, phrases] of Object.entries(MARKERS) as [Disposition, readonly string[]][]) {\n    for (const phrase of phrases) map.set(normalisePhrase(phrase), disposition);\n  }\n  return map;\n}\n\nfunction normalisePhrase(phrase: string): string {\n  return phrase.toLowerCase().replace(/[\\s-]+/g, ' ').trim();\n}\n\n/** Returns the struck text when the whole line is wrapped in `~~`. */\nfunction strikethroughOf(line: string): string | null {\n  const trimmed = line.trim();\n  if (!trimmed.startsWith('~~') || !trimmed.endsWith('~~') || trimmed.length < 5) return null;\n  const inner = trimmed.slice(2, -2);\n  return inner.includes('~~') ? null : trimmed;\n}\n\nfunction escapeRegExp(value: string): string {\n  return value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/** Exposed for the query language, which lets users filter on these names. */\nexport const KNOWN_STATE_WORDS: readonly string[] = Object.keys(STATE_ALIASES);\n"]}