@descent-vtt/spec-graph 0.9.9 → 0.10.0

package/dist/lifecycle.js

@@ -22,11 +22,42 @@
  * A hyphenated term is found anywhere in the status, so a row needs no term
  * another in it already finds: `replaced` reads "replaced by", `review` reads
  * "in review" and "under review", and `in-progress` reads "work in progress".
+ *
+ * A Chinese term is the English word it translates, in Traditional and in
+ * Simplified characters, and sits in that word's row. Chinese writes no space
+ * between words, so a term in Han characters is found anywhere in the status,
+ * as a hyphenated one is, and the same economy applies: `棄用` reads `已棄用`,
+ * and `待審` reads `待審核`. The superseded forms are rules of their own, in
+ * {@link supersededInChinese}.
  */
 const VOCABULARY = [
     [
         'retired',
         [
+            // Read as itself, though it starts with a negation. The active row's
+            // `採納` inside it is not read, because that negation stands before it.
+            '不採納',
+            '不采纳',
+            '棄用',
+            '弃用',
+            '廢棄',
+            '废弃',
+            '已停用',
+            '已過時',
+            '已过时',
+            '否決',
+            '否决',
+            '已拒絕',
+            '已拒绝',
+            '撤回',
+            '作廢',
+            '作废',
+            '延後',
+            '延后',
+            '暫緩',
+            '暂缓',
+            '擱置',
+            '搁置',
             'superseded',
             // Misspelled in the wild often enough that omitting it would silently
             // mis-classify real documents as active.
@@ -67,18 +98,42 @@ const VOCABULARY = [
         // have to go somewhere (ADR-0011). After retirement, so a brief written
         // `archived, superseded by B-0007` is still retired.
         'record',
-        ['archived', 'archive'],
+        ['archived', 'archive', '封存', '歸檔', '归档'],
     ],
     [
         'frozen',
-        ['final', 'finalised', 'finalized', 'frozen', 'locked', 'ratified', 'immutable', 'sealed', 'standard', 'published'],
+        [
+            'final',
+            'finalised',
+            'finalized',
+            'frozen',
+            'locked',
+            'ratified',
+            'immutable',
+            'sealed',
+            'standard',
+            'published',
+            '定案',
+            '已凍結',
+            '已冻结',
+        ],
     ],
     // Ahead of `active`, whose `accepted` it contains: read after it, as the
-    // rest of the draft row is, `provisionally accepted` would be active.
-    ['draft', ['provisionally-accepted']],
+    // rest of the draft row is, `provisionally accepted` would be active. `暫定`
+    // is the same word, and `暫定接受` holds the active row's `接受`.
+    ['draft', ['provisionally-accepted', '暫定', '暂定']],
     [
         'active',
         [
+            '接受',
+            '採納',
+            '采纳',
+            '核准',
+            '批准',
+            '生效',
+            '已實施',
+            '已实施',
+            '已完成',
             'accepted',
             'active',
             'approved',
@@ -106,6 +161,19 @@ const VOCABULARY = [
     [
         'draft',
         [
+            '草稿',
+            '草案',
+            '提議',
+            '提议',
+            '提案',
+            '審查中',
+            '审查中',
+            '審核中',
+            '审核中',
+            '討論中',
+            '讨论中',
+            '待審',
+            '待审',
             'draft',
             'drafting',
             'proposed',
@@ -148,18 +216,50 @@ const RETIRING_DIRECTORIES = new Set([
     'superceded',
     'withdrawn',
 ]);
-/** Front-matter keys that may carry a status, in order of preference. */
-export const STATUS_KEYS = ['status', 'state', 'stage', 'lifecycle', 'phase', 'adr-status'];
+/**
+ * Front-matter keys that may carry a status, in order of preference. The
+ * Chinese key is the English one it translates, so it ranks beside it.
+ */
+export const STATUS_KEYS = ['status', '狀態', '状态', 'state', 'stage', 'lifecycle', 'phase', 'adr-status'];
 /** Heading names whose body declares the document status. */
-const STATUS_HEADINGS = new Set(['status', 'state', 'stage', 'lifecycle', 'current status']);
+const STATUS_HEADINGS = new Set([
+    'status',
+    'state',
+    'stage',
+    'lifecycle',
+    'current status',
+    '狀態',
+    '状态',
+]);
+/** A term written in Han characters, which is found anywhere in a status rather than as a word. */
+const HAN = /\p{Script=Han}/u;
 /**
- * Reduces a status string to lookup form.
- *
- * Strips Markdown emphasis, badge syntax, emoji and dates, so `**Accepted**`,
- * `` `accepted` ``, `Accepted ✅` and `Accepted (2026-03-01)` all land on the
- * same token.
+ * What cancels a Han term written directly after it: `未接受`, `尚未核准` and
+ * `不再生效` are not accepted, approved or in effect, and `未移交給 ADR-0002`
+ * hands nothing on. One list for status words and relation phrases alike, so
+ * the two cannot come to disagree about what a negation is. `尚未` ends in
+ * `未`, so it needs no entry of its own.
  */
-export function normaliseStatus(raw) {
+const HAN_NEGATIONS = ['不', '未', '非', '沒', '没', '無', '无', '勿', '不再'];
+/**
+ * `被 ADR-0003 取代`, and `被取代` with nothing between: superseded, in the
+ * passive, with the successor between `被` and the verb. Thirty characters
+ * leave room for a name or two and not for a clause, and the gap never runs
+ * past the end of a sentence: `被團隊接受。取代 ADR-0002 的方案另議` is no
+ * supersession of this document.
+ */
+const PASSIVE_SUPERSESSION = /被([^。；！？]{0,30}?)所?(?:取而代之|取代|替代)/gu;
+/**
+ * `已取代` said alone. Followed by a name - `已取代 ADR-0002`, `已取代舊方案`,
+ * after spaces or a colon - it usually says what *this* document replaced, and
+ * reading it either way would be a guess.
+ */
+const SUPERSEDED_ALONE = /已取代(?![\s:：]*[\p{L}\p{N}])/gu;
+/**
+ * Strips what decorates a status and keeps its punctuation: HTML, emphasis,
+ * link syntax, emoji and dates. Lower-cased, since every term is.
+ */
+function undecorated(raw) {
     // An underscore between two letters joins two words - `not_planned`,
     // `in_progress` - where one at either end of a word is emphasis. Stripped
     // with the emphasis, it ran the two words into one that is neither.
@@ -170,10 +270,52 @@ export function normaliseStatus(raw) {
         .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
         .replace(/\p{Extended_Pictographic}/gu, ' ')
         .replace(/\d{4}-\d{2}-\d{2}/g, ' ')
-        .toLowerCase()
+        .toLowerCase();
+}
+/**
+ * Reduces a status string to lookup form.
+ *
+ * Strips Markdown emphasis, badge syntax, emoji and dates, so `**Accepted**`,
+ * `` `accepted` ``, `Accepted ✅` and `Accepted (2026-03-01)` all land on the
+ * same token.
+ */
+export function normaliseStatus(raw) {
+    return undecorated(raw)
         .replace(/[^\p{L}\p{N}]+/gu, ' ')
         .trim();
 }
+/** Whether a Chinese negation stands directly before the offset. */
+export function negatedAt(text, offset) {
+    const before = text.slice(0, offset);
+    return HAN_NEGATIONS.some((negation) => before.endsWith(negation));
+}
+/** Whether a Han term occurs in the text with no negation directly before it. */
+function hanTermIn(text, term) {
+    for (let at = text.indexOf(term); at !== -1; at = text.indexOf(term, at + 1)) {
+        if (!negatedAt(text, at))
+            return true;
+    }
+    return false;
+}
+/** The text between `被` and the verb of every passive supersession not negated. */
+function passiveSupersessions(text) {
+    const out = [];
+    for (const match of text.matchAll(PASSIVE_SUPERSESSION)) {
+        if (!negatedAt(text, match.index))
+            out.push(match[1]);
+    }
+    return out;
+}
+/** Whether a status says it was superseded, in Chinese. */
+function supersededInChinese(text) {
+    if (passiveSupersessions(text).length > 0)
+        return true;
+    for (const match of text.matchAll(SUPERSEDED_ALONE)) {
+        if (!negatedAt(text, match.index))
+            return true;
+    }
+    return false;
+}
 /**
  * Maps a raw status string onto a lifecycle phase.
  *
@@ -185,12 +327,21 @@ export function normaliseStatus(raw) {
 export function phaseOf(raw) {
     if (raw === null || raw === undefined)
         return 'unknown';
-    const text = normaliseStatus(raw);
+    const plain = undecorated(raw);
+    // Retirement wins wherever it is written, so the superseded forms need no
+    // place in the table's order.
+    if (supersededInChinese(plain))
+        return 'retired';
+    const text = plain.replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
     const words = new Set(text.split(' '));
     const hyphenated = text.replace(/ /g, '-');
     for (const [phase, terms] of VOCABULARY) {
         for (const term of terms) {
-            if (term.includes('-')) {
+            if (HAN.test(term)) {
+                if (hanTermIn(plain, term))
+                    return phase;
+            }
+            else if (term.includes('-')) {
                 if (hyphenated.includes(term))
                     return phase;
             }
@@ -223,7 +374,7 @@ export function isRetired(phase) {
 }
 /** True when the heading names a section that declares the document status. */
 export function isStatusHeading(text) {
-    return STATUS_HEADINGS.has(text.toLowerCase().replace(/[:*_`]/g, '').trim());
+    return STATUS_HEADINGS.has(text.toLowerCase().replace(/[:：*_`]/g, '').trim());
 }
 /**
  * Infers retirement from where a file lives.
@@ -249,23 +400,31 @@ export function phaseFromPath(posixPath) {
  * recorded, and it is written in the status field rather than as a link. Reading
  * it here means the relation reaches the graph even in repositories that never
  * adopted an explicit field for it.
+ *
+ * In Chinese the successor stands between `被` and the verb: `已被 ADR-0003
+ * 取代`. Left unread, a document that said so and one that said it supersedes
+ * this one disagreed, and `unreciprocated-supersession` asked for a
+ * `superseded-by` key the status had already given.
  */
 export function supersessionTargetsIn(raw) {
     const out = [];
+    const plain = raw.replace(/[`*_]/g, '');
     // The tail runs to the end of the line, not of the string: a status that
     // wraps onto a second line still names its successor on the first.
     const pattern = /(?:super[sc]eded|replaced|obsoleted)\s*(?:by|with|through)?\s*[:\-–—]?\s*(.+)/i;
-    const match = pattern.exec(raw.replace(/[`*_]/g, ''));
-    if (!match)
-        return out;
-    const tail = match[1];
-    for (const token of tail.split(/[,;]|\band\b/)) {
-        const cleaned = token
-            .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
-            .replace(/[()<>"']/g, ' ')
-            .trim();
-        if (cleaned.length > 0 && cleaned.length < 200)
-            out.push(cleaned);
+    const match = pattern.exec(plain);
+    // A link inside the passive is read by its label, as a status is: its path
+    // would run the name past the thirty characters the form allows.
+    const tails = match ? [match[1]] : passiveSupersessions(plain.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1'));
+    for (const tail of tails) {
+        for (const token of tail.split(/[,;、，；和及與与]|\band\b/)) {
+            const cleaned = token
+                .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+                .replace(/[()<>"'（）]/g, ' ')
+                .trim();
+            if (cleaned.length > 0 && cleaned.length < 200)
+                out.push(cleaned);
+        }
     }
     return out;
 }

package/dist/lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Status vocabulary normalisation.\n *\n * Every specification ecosystem invented its own status words, and no two agree.\n * MADR says `accepted`; Kubernetes KEPs say `implementable`; Rust RFCs say\n * `merged`; a hundred internal wikis say `Live`, `Signed off`, or `DONE ✅`.\n *\n * spec-graph refuses to care. What it needs from a status is one bit - *can this\n * document still absorb an obligation?* - and that bit is recoverable from all\n * of those vocabularies at once. The tables below are the only place in the\n * codebase that knows any ecosystem-specific word, which is what keeps the\n * engine domain-agnostic: supporting a new convention is a table entry, never a\n * rule change.\n */\n\nimport type { Phase, Receptivity } from './types.js';\n\n/**\n * Recognised status words, most terminal first.\n *\n * Order matters. A status of \"accepted, superseded by ADR-0009\" is retired, not\n * active: retirement is terminal, so a retirement word anywhere in the string\n * wins over anything else in it.\n *\n * A hyphenated term is found anywhere in the status, so a row needs no term\n * another in it already finds: `replaced` reads \"replaced by\", `review` reads\n * \"in review\" and \"under review\", and `in-progress` reads \"work in progress\".\n */\nconst VOCABULARY: readonly (readonly [Phase, readonly string[]])[] = [\n  [\n    'retired',\n    [\n      'superseded',\n      // Misspelled in the wild often enough that omitting it would silently\n      // mis-classify real documents as active.\n      'superceded',\n      'supersedes-by',\n      'replaced',\n      'deprecated',\n      'obsolete',\n      'obsoleted',\n      'retired',\n      'rejected',\n      'declined',\n      'withdrawn',\n      'abandoned',\n      'cancelled',\n      'canceled',\n      'dropped',\n      'revoked',\n      'reverted',\n      'moved',\n      'historical',\n      'defunct',\n      'inactive',\n      'dead',\n      'void',\n      'closed',\n      'postponed',\n      'deferred',\n      'not-planned',\n      'wontfix',\n    ],\n  ],\n  [\n    // A finished round of work kept as it was left: spec-brief archives a brief\n    // by writing this word and moving the file. Every spec-* tool reads it as a\n    // record rather than as a retired decision - depending on one is normal,\n    // its unticked boxes were never going to be ticked, and its links still\n    // have to go somewhere (ADR-0011). After retirement, so a brief written\n    // `archived, superseded by B-0007` is still retired.\n    'record',\n    ['archived', 'archive'],\n  ],\n  [\n    'frozen',\n    ['final', 'finalised', 'finalized', 'frozen', 'locked', 'ratified', 'immutable', 'sealed', 'standard', 'published'],\n  ],\n  // Ahead of `active`, whose `accepted` it contains: read after it, as the\n  // rest of the draft row is, `provisionally accepted` would be active.\n  ['draft', ['provisionally-accepted']],\n  [\n    'active',\n    [\n      'accepted',\n      'active',\n      'approved',\n      'adopted',\n      'agreed',\n      'implementable',\n      'implemented',\n      'implementing',\n      'current',\n      'effective',\n      'in-effect',\n      'enforced',\n      'stable',\n      'merged',\n      'released',\n      'shipped',\n      'live',\n      'done',\n      'complete',\n      'completed',\n      'signed-off',\n      'committed',\n    ],\n  ],\n  [\n    'draft',\n    [\n      'draft',\n      'drafting',\n      'proposed',\n      'proposal',\n      'provisional',\n      'prospective',\n      'wip',\n      'in-progress',\n      'review',\n      'reviewing',\n      'discussion',\n      'discussing',\n      'pending',\n      'idea',\n      'exploratory',\n      'candidate',\n      'open',\n      'new',\n      'unreviewed',\n      'rfc',\n      'experimental',\n      'alpha',\n      'beta',\n      'incubating',\n    ],\n  ],\n];\n\n/** Path segments that retire every document beneath them. */\nconst RETIRING_DIRECTORIES: ReadonlySet<string> = new Set([\n  'archive',\n  'archived',\n  'attic',\n  'deprecated',\n  'graveyard',\n  'historical',\n  'obsolete',\n  'rejected',\n  'retired',\n  'superseded',\n  'superceded',\n  'withdrawn',\n]);\n\n/** Front-matter keys that may carry a status, in order of preference. */\nexport const STATUS_KEYS: readonly string[] = ['status', 'state', 'stage', 'lifecycle', 'phase', 'adr-status'];\n\n/** Heading names whose body declares the document status. */\nconst STATUS_HEADINGS: ReadonlySet<string> = new Set(['status', 'state', 'stage', 'lifecycle', 'current status']);\n\n/**\n * Reduces a status string to lookup form.\n *\n * Strips Markdown emphasis, badge syntax, emoji and dates, so `**Accepted**`,\n * `` `accepted` ``, `Accepted ✅` and `Accepted (2026-03-01)` all land on the\n * same token.\n */\nexport function normaliseStatus(raw: string): string {\n  // An underscore between two letters joins two words - `not_planned`,\n  // `in_progress` - where one at either end of a word is emphasis. Stripped\n  // with the emphasis, it ran the two words into one that is neither.\n  return raw\n    .replace(/<[^>]*>/g, ' ')\n    .replace(/(?<=[\\p{L}\\p{N}])_(?=[\\p{L}\\p{N}])/gu, ' ')\n    .replace(/[`*_~\"'#]/g, '')\n    .replace(/\\[([^\\]]*)\\]\\([^)]*\\)/g, '$1')\n    .replace(/\\p{Extended_Pictographic}/gu, ' ')\n    .replace(/\\d{4}-\\d{2}-\\d{2}/g, ' ')\n    .toLowerCase()\n    .replace(/[^\\p{L}\\p{N}]+/gu, ' ')\n    .trim();\n}\n\n/**\n * Maps a raw status string onto a lifecycle phase.\n *\n * Returns `unknown` rather than guessing when nothing matches: a document with\n * an unrecognised status is not evidence of anything, and inventing a phase for\n * it would produce exactly the confident-but-wrong findings this tool exists to\n * eliminate.\n */\nexport function phaseOf(raw: string | null | undefined): Phase {\n  if (raw === null || raw === undefined) return 'unknown';\n  const text = normaliseStatus(raw);\n  const words = new Set(text.split(' '));\n  const hyphenated = text.replace(/ /g, '-');\n\n  for (const [phase, terms] of VOCABULARY) {\n    for (const term of terms) {\n      if (term.includes('-')) {\n        if (hyphenated.includes(term)) return phase;\n      } else if (words.has(term)) {\n        return phase;\n      }\n    }\n  }\n  return 'unknown';\n}\n\n/** Whether a document in this phase can take on a new open obligation. */\nexport function receptivityOf(phase: Phase): Receptivity {\n  switch (phase) {\n    case 'draft':\n    case 'active':\n      return 'receptive';\n    case 'frozen':\n    case 'retired':\n    // A record was never asking for an obligation, so it cannot take one on.\n    // Sealed for the same reason a retired document is, by a different route.\n    case 'record':\n      return 'sealed';\n    case 'unknown':\n      return 'unknown';\n  }\n}\n\n/** True when the phase means the document no longer binds anybody. */\nexport function isRetired(phase: Phase): boolean {\n  return phase === 'retired';\n}\n\n/** True when the heading names a section that declares the document status. */\nexport function isStatusHeading(text: string): boolean {\n  return STATUS_HEADINGS.has(text.toLowerCase().replace(/[:*_`]/g, '').trim());\n}\n\n/**\n * Infers retirement from where a file lives.\n *\n * Moving an ADR into `docs/adr/archive/` is the most common way a team retires a\n * decision without touching its front matter, and a graph that misses it will\n * happily let obligations be delegated into the archive.\n */\nexport function phaseFromPath(posixPath: string): Phase {\n  const segments = posixPath.toLowerCase().split('/');\n  // The file name itself is not a directory; a document called `archive`, with\n  // or without an extension, is not retired.\n  for (let i = 0; i < segments.length - 1; i += 1) {\n    if (RETIRING_DIRECTORIES.has(segments[i] as string)) return 'retired';\n  }\n  return 'unknown';\n}\n\n/**\n * Pulls a supersession target out of a status string.\n *\n * `Superseded by ADR-0009` is the single most common way a supersession is ever\n * recorded, and it is written in the status field rather than as a link. Reading\n * it here means the relation reaches the graph even in repositories that never\n * adopted an explicit field for it.\n */\nexport function supersessionTargetsIn(raw: string): string[] {\n  const out: string[] = [];\n  // The tail runs to the end of the line, not of the string: a status that\n  // wraps onto a second line still names its successor on the first.\n  const pattern = /(?:super[sc]eded|replaced|obsoleted)\\s*(?:by|with|through)?\\s*[:\\-–—]?\\s*(.+)/i;\n  const match = pattern.exec(raw.replace(/[`*_]/g, ''));\n  if (!match) return out;\n  const tail = match[1] as string;\n  for (const token of tail.split(/[,;]|\\band\\b/)) {\n    const cleaned = token\n      .replace(/\\[([^\\]]*)\\]\\([^)]*\\)/g, '$1')\n      .replace(/[()<>\"']/g, ' ')\n      .trim();\n    if (cleaned.length > 0 && cleaned.length < 200) out.push(cleaned);\n  }\n  return out;\n}\n"]}
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Status vocabulary normalisation.\n *\n * Every specification ecosystem invented its own status words, and no two agree.\n * MADR says `accepted`; Kubernetes KEPs say `implementable`; Rust RFCs say\n * `merged`; a hundred internal wikis say `Live`, `Signed off`, or `DONE ✅`.\n *\n * spec-graph refuses to care. What it needs from a status is one bit - *can this\n * document still absorb an obligation?* - and that bit is recoverable from all\n * of those vocabularies at once. The tables below are the only place in the\n * codebase that knows any ecosystem-specific word, which is what keeps the\n * engine domain-agnostic: supporting a new convention is a table entry, never a\n * rule change.\n */\n\nimport type { Phase, Receptivity } from './types.js';\n\n/**\n * Recognised status words, most terminal first.\n *\n * Order matters. A status of \"accepted, superseded by ADR-0009\" is retired, not\n * active: retirement is terminal, so a retirement word anywhere in the string\n * wins over anything else in it.\n *\n * A hyphenated term is found anywhere in the status, so a row needs no term\n * another in it already finds: `replaced` reads \"replaced by\", `review` reads\n * \"in review\" and \"under review\", and `in-progress` reads \"work in progress\".\n *\n * A Chinese term is the English word it translates, in Traditional and in\n * Simplified characters, and sits in that word's row. Chinese writes no space\n * between words, so a term in Han characters is found anywhere in the status,\n * as a hyphenated one is, and the same economy applies: `棄用` reads `已棄用`,\n * and `待審` reads `待審核`. The superseded forms are rules of their own, in\n * {@link supersededInChinese}.\n */\nconst VOCABULARY: readonly (readonly [Phase, readonly string[]])[] = [\n  [\n    'retired',\n    [\n      // Read as itself, though it starts with a negation. The active row's\n      // `採納` inside it is not read, because that negation stands before it.\n      '不採納',\n      '不采纳',\n      '棄用',\n      '弃用',\n      '廢棄',\n      '废弃',\n      '已停用',\n      '已過時',\n      '已过时',\n      '否決',\n      '否决',\n      '已拒絕',\n      '已拒绝',\n      '撤回',\n      '作廢',\n      '作废',\n      '延後',\n      '延后',\n      '暫緩',\n      '暂缓',\n      '擱置',\n      '搁置',\n      'superseded',\n      // Misspelled in the wild often enough that omitting it would silently\n      // mis-classify real documents as active.\n      'superceded',\n      'supersedes-by',\n      'replaced',\n      'deprecated',\n      'obsolete',\n      'obsoleted',\n      'retired',\n      'rejected',\n      'declined',\n      'withdrawn',\n      'abandoned',\n      'cancelled',\n      'canceled',\n      'dropped',\n      'revoked',\n      'reverted',\n      'moved',\n      'historical',\n      'defunct',\n      'inactive',\n      'dead',\n      'void',\n      'closed',\n      'postponed',\n      'deferred',\n      'not-planned',\n      'wontfix',\n    ],\n  ],\n  [\n    // A finished round of work kept as it was left: spec-brief archives a brief\n    // by writing this word and moving the file. Every spec-* tool reads it as a\n    // record rather than as a retired decision - depending on one is normal,\n    // its unticked boxes were never going to be ticked, and its links still\n    // have to go somewhere (ADR-0011). After retirement, so a brief written\n    // `archived, superseded by B-0007` is still retired.\n    'record',\n    ['archived', 'archive', '封存', '歸檔', '归档'],\n  ],\n  [\n    'frozen',\n    [\n      'final',\n      'finalised',\n      'finalized',\n      'frozen',\n      'locked',\n      'ratified',\n      'immutable',\n      'sealed',\n      'standard',\n      'published',\n      '定案',\n      '已凍結',\n      '已冻结',\n    ],\n  ],\n  // Ahead of `active`, whose `accepted` it contains: read after it, as the\n  // rest of the draft row is, `provisionally accepted` would be active. `暫定`\n  // is the same word, and `暫定接受` holds the active row's `接受`.\n  ['draft', ['provisionally-accepted', '暫定', '暂定']],\n  [\n    'active',\n    [\n      '接受',\n      '採納',\n      '采纳',\n      '核准',\n      '批准',\n      '生效',\n      '已實施',\n      '已实施',\n      '已完成',\n      'accepted',\n      'active',\n      'approved',\n      'adopted',\n      'agreed',\n      'implementable',\n      'implemented',\n      'implementing',\n      'current',\n      'effective',\n      'in-effect',\n      'enforced',\n      'stable',\n      'merged',\n      'released',\n      'shipped',\n      'live',\n      'done',\n      'complete',\n      'completed',\n      'signed-off',\n      'committed',\n    ],\n  ],\n  [\n    'draft',\n    [\n      '草稿',\n      '草案',\n      '提議',\n      '提议',\n      '提案',\n      '審查中',\n      '审查中',\n      '審核中',\n      '审核中',\n      '討論中',\n      '讨论中',\n      '待審',\n      '待审',\n      'draft',\n      'drafting',\n      'proposed',\n      'proposal',\n      'provisional',\n      'prospective',\n      'wip',\n      'in-progress',\n      'review',\n      'reviewing',\n      'discussion',\n      'discussing',\n      'pending',\n      'idea',\n      'exploratory',\n      'candidate',\n      'open',\n      'new',\n      'unreviewed',\n      'rfc',\n      'experimental',\n      'alpha',\n      'beta',\n      'incubating',\n    ],\n  ],\n];\n\n/** Path segments that retire every document beneath them. */\nconst RETIRING_DIRECTORIES: ReadonlySet<string> = new Set([\n  'archive',\n  'archived',\n  'attic',\n  'deprecated',\n  'graveyard',\n  'historical',\n  'obsolete',\n  'rejected',\n  'retired',\n  'superseded',\n  'superceded',\n  'withdrawn',\n]);\n\n/**\n * Front-matter keys that may carry a status, in order of preference. The\n * Chinese key is the English one it translates, so it ranks beside it.\n */\nexport const STATUS_KEYS: readonly string[] = ['status', '狀態', '状态', 'state', 'stage', 'lifecycle', 'phase', 'adr-status'];\n\n/** Heading names whose body declares the document status. */\nconst STATUS_HEADINGS: ReadonlySet<string> = new Set([\n  'status',\n  'state',\n  'stage',\n  'lifecycle',\n  'current status',\n  '狀態',\n  '状态',\n]);\n\n/** A term written in Han characters, which is found anywhere in a status rather than as a word. */\nconst HAN = /\\p{Script=Han}/u;\n\n/**\n * What cancels a Han term written directly after it: `未接受`, `尚未核准` and\n * `不再生效` are not accepted, approved or in effect, and `未移交給 ADR-0002`\n * hands nothing on. One list for status words and relation phrases alike, so\n * the two cannot come to disagree about what a negation is. `尚未` ends in\n * `未`, so it needs no entry of its own.\n */\nconst HAN_NEGATIONS: readonly string[] = ['不', '未', '非', '沒', '没', '無', '无', '勿', '不再'];\n\n/**\n * `被 ADR-0003 取代`, and `被取代` with nothing between: superseded, in the\n * passive, with the successor between `被` and the verb. Thirty characters\n * leave room for a name or two and not for a clause, and the gap never runs\n * past the end of a sentence: `被團隊接受。取代 ADR-0002 的方案另議` is no\n * supersession of this document.\n */\nconst PASSIVE_SUPERSESSION = /被([^。；！？]{0,30}?)所?(?:取而代之|取代|替代)/gu;\n\n/**\n * `已取代` said alone. Followed by a name - `已取代 ADR-0002`, `已取代舊方案`,\n * after spaces or a colon - it usually says what *this* document replaced, and\n * reading it either way would be a guess.\n */\nconst SUPERSEDED_ALONE = /已取代(?![\\s:：]*[\\p{L}\\p{N}])/gu;\n\n/**\n * Strips what decorates a status and keeps its punctuation: HTML, emphasis,\n * link syntax, emoji and dates. Lower-cased, since every term is.\n */\nfunction undecorated(raw: string): string {\n  // An underscore between two letters joins two words - `not_planned`,\n  // `in_progress` - where one at either end of a word is emphasis. Stripped\n  // with the emphasis, it ran the two words into one that is neither.\n  return raw\n    .replace(/<[^>]*>/g, ' ')\n    .replace(/(?<=[\\p{L}\\p{N}])_(?=[\\p{L}\\p{N}])/gu, ' ')\n    .replace(/[`*_~\"'#]/g, '')\n    .replace(/\\[([^\\]]*)\\]\\([^)]*\\)/g, '$1')\n    .replace(/\\p{Extended_Pictographic}/gu, ' ')\n    .replace(/\\d{4}-\\d{2}-\\d{2}/g, ' ')\n    .toLowerCase();\n}\n\n/**\n * Reduces a status string to lookup form.\n *\n * Strips Markdown emphasis, badge syntax, emoji and dates, so `**Accepted**`,\n * `` `accepted` ``, `Accepted ✅` and `Accepted (2026-03-01)` all land on the\n * same token.\n */\nexport function normaliseStatus(raw: string): string {\n  return undecorated(raw)\n    .replace(/[^\\p{L}\\p{N}]+/gu, ' ')\n    .trim();\n}\n\n/** Whether a Chinese negation stands directly before the offset. */\nexport function negatedAt(text: string, offset: number): boolean {\n  const before = text.slice(0, offset);\n  return HAN_NEGATIONS.some((negation) => before.endsWith(negation));\n}\n\n/** Whether a Han term occurs in the text with no negation directly before it. */\nfunction hanTermIn(text: string, term: string): boolean {\n  for (let at = text.indexOf(term); at !== -1; at = text.indexOf(term, at + 1)) {\n    if (!negatedAt(text, at)) return true;\n  }\n  return false;\n}\n\n/** The text between `被` and the verb of every passive supersession not negated. */\nfunction passiveSupersessions(text: string): string[] {\n  const out: string[] = [];\n  for (const match of text.matchAll(PASSIVE_SUPERSESSION)) {\n    if (!negatedAt(text, match.index)) out.push(match[1] as string);\n  }\n  return out;\n}\n\n/** Whether a status says it was superseded, in Chinese. */\nfunction supersededInChinese(text: string): boolean {\n  if (passiveSupersessions(text).length > 0) return true;\n  for (const match of text.matchAll(SUPERSEDED_ALONE)) {\n    if (!negatedAt(text, match.index)) return true;\n  }\n  return false;\n}\n\n/**\n * Maps a raw status string onto a lifecycle phase.\n *\n * Returns `unknown` rather than guessing when nothing matches: a document with\n * an unrecognised status is not evidence of anything, and inventing a phase for\n * it would produce exactly the confident-but-wrong findings this tool exists to\n * eliminate.\n */\nexport function phaseOf(raw: string | null | undefined): Phase {\n  if (raw === null || raw === undefined) return 'unknown';\n  const plain = undecorated(raw);\n  // Retirement wins wherever it is written, so the superseded forms need no\n  // place in the table's order.\n  if (supersededInChinese(plain)) return 'retired';\n  const text = plain.replace(/[^\\p{L}\\p{N}]+/gu, ' ').trim();\n  const words = new Set(text.split(' '));\n  const hyphenated = text.replace(/ /g, '-');\n\n  for (const [phase, terms] of VOCABULARY) {\n    for (const term of terms) {\n      if (HAN.test(term)) {\n        if (hanTermIn(plain, term)) return phase;\n      } else if (term.includes('-')) {\n        if (hyphenated.includes(term)) return phase;\n      } else if (words.has(term)) {\n        return phase;\n      }\n    }\n  }\n  return 'unknown';\n}\n\n/** Whether a document in this phase can take on a new open obligation. */\nexport function receptivityOf(phase: Phase): Receptivity {\n  switch (phase) {\n    case 'draft':\n    case 'active':\n      return 'receptive';\n    case 'frozen':\n    case 'retired':\n    // A record was never asking for an obligation, so it cannot take one on.\n    // Sealed for the same reason a retired document is, by a different route.\n    case 'record':\n      return 'sealed';\n    case 'unknown':\n      return 'unknown';\n  }\n}\n\n/** True when the phase means the document no longer binds anybody. */\nexport function isRetired(phase: Phase): boolean {\n  return phase === 'retired';\n}\n\n/** True when the heading names a section that declares the document status. */\nexport function isStatusHeading(text: string): boolean {\n  return STATUS_HEADINGS.has(text.toLowerCase().replace(/[:：*_`]/g, '').trim());\n}\n\n/**\n * Infers retirement from where a file lives.\n *\n * Moving an ADR into `docs/adr/archive/` is the most common way a team retires a\n * decision without touching its front matter, and a graph that misses it will\n * happily let obligations be delegated into the archive.\n */\nexport function phaseFromPath(posixPath: string): Phase {\n  const segments = posixPath.toLowerCase().split('/');\n  // The file name itself is not a directory; a document called `archive`, with\n  // or without an extension, is not retired.\n  for (let i = 0; i < segments.length - 1; i += 1) {\n    if (RETIRING_DIRECTORIES.has(segments[i] as string)) return 'retired';\n  }\n  return 'unknown';\n}\n\n/**\n * Pulls a supersession target out of a status string.\n *\n * `Superseded by ADR-0009` is the single most common way a supersession is ever\n * recorded, and it is written in the status field rather than as a link. Reading\n * it here means the relation reaches the graph even in repositories that never\n * adopted an explicit field for it.\n *\n * In Chinese the successor stands between `被` and the verb: `已被 ADR-0003\n * 取代`. Left unread, a document that said so and one that said it supersedes\n * this one disagreed, and `unreciprocated-supersession` asked for a\n * `superseded-by` key the status had already given.\n */\nexport function supersessionTargetsIn(raw: string): string[] {\n  const out: string[] = [];\n  const plain = raw.replace(/[`*_]/g, '');\n  // The tail runs to the end of the line, not of the string: a status that\n  // wraps onto a second line still names its successor on the first.\n  const pattern = /(?:super[sc]eded|replaced|obsoleted)\\s*(?:by|with|through)?\\s*[:\\-–—]?\\s*(.+)/i;\n  const match = pattern.exec(plain);\n  // A link inside the passive is read by its label, as a status is: its path\n  // would run the name past the thirty characters the form allows.\n  const tails = match ? [match[1] as string] : passiveSupersessions(plain.replace(/\\[([^\\]]*)\\]\\([^)]*\\)/g, '$1'));\n  for (const tail of tails) {\n    for (const token of tail.split(/[,;、，；和及與与]|\\band\\b/)) {\n      const cleaned = token\n        .replace(/\\[([^\\]]*)\\]\\([^)]*\\)/g, '$1')\n        .replace(/[()<>\"'（）]/g, ' ')\n        .trim();\n      if (cleaned.length > 0 && cleaned.length < 200) out.push(cleaned);\n    }\n  }\n  return out;\n}\n"]}

package/dist/report.d.ts

@@ -47,6 +47,14 @@ export interface ReporterOptions {
         readonly ratchet?: boolean | undefined;
         readonly entries?: readonly StaleEntry[] | undefined;
     } | undefined;
+    /**
+     * The baseline's path as it is typed where the run was started, for the
+     * command that re-records it; `baseline.source` when unset. The source reads
+     * from the root, and typed in a directory below it, it names another file.
+     * Beside the baseline rather than in it, because the JSON report writes the
+     * baseline whole.
+     */
+    readonly recordAs?: string | undefined;
 }
 export interface ColorEnvironment {
     readonly isTTY?: boolean | undefined;
@@ -142,6 +150,20 @@ export declare function formatSarif(result: AnalysisResult, graph: SpecGraph, op
 export declare function formatGitlab(result: AnalysisResult, options?: {
     escalated?: ReadonlySet<AnyRuleId> | undefined;
 }): string;
+/**
+ * Findings as GitHub Actions workflow commands, one line each, which a job's
+ * log turns into annotations on the pull request's diff with no upload step -
+ * what SARIF does through code scanning, for a repository that has none.
+ *
+ * An error is `error`, a warning `warning` and a note `notice`, as spec-guard
+ * writes them. The rule is the title, marked `(strict)` where only `--strict`
+ * made it an error, as the Markdown report marks it; the message carries the
+ * hint, since a finding without its next action is the half a reader cannot
+ * act on. Nothing at all for a clean run.
+ */
+export declare function formatGithub(result: AnalysisResult, options?: {
+    escalated?: ReadonlySet<AnyRuleId> | undefined;
+}): string;
 export declare function formatJson(result: AnalysisResult, options?: {
     escalated?: ReadonlySet<AnyRuleId>;
     baseline?: ReporterOptions['baseline'];

package/dist/report.js

@@ -14,6 +14,7 @@ import { createHash } from 'node:crypto';
 import { fingerprintOf } from './baseline.js';
 import { formatRef } from './source.js';
 import { DEFAULT_SEVERITIES, RULE_DESCRIPTIONS, RULE_IDS } from './rules.js';
+import { displayWidth } from './vendor/spec-core/text/index.js';
 /** Honours `NO_COLOR`, `FORCE_COLOR` and `TERM=dumb` before falling back to TTY. */
 export function shouldUseColor(environment = {}) {
     const env = environment.env ?? process.env;
@@ -139,7 +140,7 @@ export function formatReport(result, options = {}) {
         // anything that is not one counts the same zero.
         const gone = (baseline.entries ?? []).filter((entry) => entry.reason === 'gone').length;
         const because = gone === 0
-            ? `tighten it: spec-graph check --record-baseline ${baseline.source}`
+            ? `tighten it: spec-graph check --record-baseline ${options.recordAs ?? baseline.source}`
             : `${gone} of them ${gone === 1 ? 'names a document' : 'name documents'} this run did not see - check the include patterns before re-recording`;
         const text = `${baseline.stale} baseline ${plural(baseline.stale, 'entry', 'entries')} no longer ${baseline.stale === 1 ? 'occurs' : 'occur'} - ${because}`;
         lines.push(ratcheted ? `${paint.error(marks.error)} ${text}` : paint.dim(text));
@@ -164,10 +165,14 @@ function formatDiagnostic(diagnostic, paint, marks, escalated) {
         `${mark} ${paint.location(formatRef(diagnostic.at))}  ${paint.dim(label)}`,
         `    ${diagnostic.message}`,
     ];
-    const width = Math.max(0, ...diagnostic.related.map((entry) => formatRef(entry.at).length));
+    // Padded to the columns a terminal draws, not to UTF-16 units: `docs/決策.md`
+    // is ten units and twelve columns, so `.padEnd` left the notes beside it two
+    // columns out of line.
+    const width = Math.max(0, ...diagnostic.related.map((entry) => displayWidth(formatRef(entry.at))));
     for (const entry of diagnostic.related) {
         const reference = formatRef(entry.at);
-        lines.push(`    ${paint.dim(marks.related)} ${paint.dim(reference.padEnd(width))}  ${paint.dim(entry.note)}`);
+        const padded = `${reference}${' '.repeat(width - displayWidth(reference))}`;
+        lines.push(`    ${paint.dim(marks.related)} ${paint.dim(padded)}  ${paint.dim(entry.note)}`);
     }
     lines.push(`    ${paint.hint(marks.hint)} ${paint.hint(diagnostic.hint)}`);
     return lines;
@@ -525,6 +530,48 @@ function gitlabSeverity(severity, escalated) {
             return 'info';
     }
 }
+/* -------------------------------------------------------------------------- */
+/* GitHub workflow commands                                                   */
+/* -------------------------------------------------------------------------- */
+/** A workflow command's message: `%`, and the line breaks that would end the command. */
+function escapeData(text) {
+    return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+/** A workflow command's property: as a message, and the `:` and `,` that would end the property. */
+function escapeProperty(text) {
+    return escapeData(text).replace(/:/g, '%3A').replace(/,/g, '%2C');
+}
+/**
+ * Findings as GitHub Actions workflow commands, one line each, which a job's
+ * log turns into annotations on the pull request's diff with no upload step -
+ * what SARIF does through code scanning, for a repository that has none.
+ *
+ * An error is `error`, a warning `warning` and a note `notice`, as spec-guard
+ * writes them. The rule is the title, marked `(strict)` where only `--strict`
+ * made it an error, as the Markdown report marks it; the message carries the
+ * hint, since a finding without its next action is the half a reader cannot
+ * act on. Nothing at all for a clean run.
+ */
+export function formatGithub(result, options = {}) {
+    const escalated = options.escalated ?? EMPTY_RULES;
+    return result.diagnostics
+        .map((diagnostic) => {
+        const title = escalated.has(diagnostic.rule) ? `${diagnostic.rule} (strict)` : diagnostic.rule;
+        const place = `file=${escapeProperty(diagnostic.at.file)},line=${diagnostic.at.span.start.line}`;
+        return `::${githubLevel(diagnostic.severity)} ${place},title=${escapeProperty(title)}::${escapeData(`${diagnostic.message}. ${diagnostic.hint}`)}\n`;
+    })
+        .join('');
+}
+function githubLevel(severity) {
+    switch (severity) {
+        case 'error':
+            return 'error';
+        case 'warn':
+            return 'warning';
+        default:
+            return 'notice';
+    }
+}
 export function formatJson(result, options = {}) {
     const escalated = options.escalated ?? EMPTY_RULES;
     return `${JSON.stringify({