@llman-sdd/core 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llman-sdd/core",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Pure domain logic for llman-sdd (config, gherkin specs, validation, templates)",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -33,8 +33,22 @@ export {
   localeToGherkinLang,
   parseCapability,
   parseFeatureSource,
+  sourceDialect,
 } from './spec/parser.ts';
-export { buildReqRegistry, type ReqRegistry, type RegistryDuplicate } from './spec/reqRegistry.ts';
+export {
+  BLOCK_KEYWORD_LINE_RE,
+  officialKeywords,
+  officialKeywordsOrEn,
+  stepKeywordToOfficialKind,
+  STEP_KIND_BY_KEYWORD,
+  type GherkinKeywords,
+} from './spec/keywords.ts';
+export {
+  buildReqRegistry,
+  type RegistryDuplicate,
+  type RegistryOccurrence,
+  type ReqRegistry,
+} from './spec/reqRegistry.ts';
 export {
   analyzeLegacy,
   hasNativeRules,
@@ -187,7 +201,12 @@ export { graphData, graphMermaid, type GraphDataIr, type GraphFsIo } from './rep
 export { parseDeps } from './report/graph.ts';
 export { renderMachine, type MachineFormat } from './render/machine.ts';
 export { showChangeJson, type ShowDeps, type ShowFsIo } from './report/show.ts';
-export { nextReqId, scaffoldSpec, type SpecHelperIo } from './report/specHelpers.ts';
+export {
+  nextReqId,
+  scaffoldSpec,
+  skeletonContent,
+  type SpecHelperIo,
+} from './report/specHelpers.ts';
 export {
   collectSpecs,
   morphologyOf,

package/src/report/specHelpers.ts

@@ -1,3 +1,4 @@
+import { officialKeywords, officialKeywordsOrEn } from '../spec/keywords.ts';
 import { localeToGherkinLang, parseCapability } from '../spec/parser.ts';
 import { buildReqRegistry } from '../spec/reqRegistry.ts';
 /**
@@ -57,22 +58,23 @@ export function nextReqId(io: SpecHelperIo, specsDir: string): string {
 export function skeletonContent(capability: string, reqId: string, locale: string): string {
   const zh = localeFallbacks(locale)[0] === 'zh-Hans';
   // r7: the `# language:` header derives from the locale mapping — never a
-  // second hardcoded caliber.
-  const language = localeToGherkinLang(zh ? 'zh-Hans' : 'en');
+  // second hardcoded caliber. Table-less locales fall back to en wholesale
+  // (header + keywords same-source) so the skeleton stays parseable.
+  const mapped = localeToGherkinLang(locale);
+  const language = officialKeywords(mapped) !== null ? mapped : 'en';
+  const kw = officialKeywordsOrEn(language);
   const header = zh
     ? `# language: ${language}\n# capability: ${capability}\n# purpose: TODO: 一句话描述该能力与其目的。\n# scope: llmanspec/`
     : `# language: ${language}\n# capability: ${capability}\n# purpose: TODO: Describe this capability and its purpose.\n# scope: llmanspec/`;
-  const feature = zh ? `功能: ${capability}` : `Feature: ${capability}`;
-  const ruleKw = zh ? '规则' : 'Rule';
-  const scenarioKw = zh ? '场景' : 'Scenario';
-  const ruleTitle = 'TODO-rule';
   const ruleDesc = zh ? 'TODO: 需求描述(自由文本)。' : 'TODO: requirement statement (free text).';
-  const scTitle = 'TODO-acceptance';
-  // native v2 skeleton: a `规则:` block (with @req handle) + one nested example
+  // Skeleton placeholder prose is not vocabulary — the zh/en copy stays; keywords do not.
+  const steps = zh
+    ? `      ${kw.given} TODO 前置\n      ${kw.when} TODO 动作\n      ${kw.thenText} TODO 断言`
+    : `      ${kw.given} TODO precondition\n      ${kw.when} TODO action\n      ${kw.thenText} TODO assertion`;
+  // native v2 skeleton: a rule block (with @req handle) + one nested example
   return (
-    `${header}\n\n${feature}\n\n  @req:${reqId}\n  ${ruleKw}: ${ruleTitle}\n` +
-    `    ${ruleDesc}\n\n    ${scenarioKw}: ${scTitle}\n` +
-    `      假如 TODO 前置\n      当 TODO 动作\n      那么 TODO 断言\n`
+    `${header}\n\n${kw.feature}: ${capability}\n\n  @req:${reqId}\n  ${kw.rule}: TODO-rule\n` +
+    `    ${ruleDesc}\n\n    ${kw.scenario}: TODO-acceptance\n${steps}\n`
   );
 }
 

package/src/spec/authoring.ts

@@ -7,6 +7,9 @@
 
 import type { CapabilityDoc, RuleIR } from './ir.ts';
 import { specIdOf } from './ir.ts';
+import { BLOCK_KEYWORD_LINE_RE, officialKeywordsOrEn } from './keywords.ts';
+import { sourceDialect } from './parser.ts';
+import type { RegistryDuplicate } from './reqRegistry.ts';
 
 export class AuthoringError extends Error {}
 
@@ -30,9 +33,14 @@ interface KeywordSet {
 }
 
 function keywordsOf(content: string): KeywordSet {
-  return content.includes('功能:')
-    ? { rule: '规则', scenario: '场景', given: '假如', when: '当', thenText: '那么' }
-    : { rule: 'Rule', scenario: 'Scenario', given: 'Given', when: 'When', thenText: 'Then' };
+  const kw = officialKeywordsOrEn(sourceDialect(content));
+  return {
+    rule: kw.rule,
+    scenario: kw.scenario,
+    given: kw.given,
+    when: kw.when,
+    thenText: kw.thenText,
+  };
 }
 
 function findRule(
@@ -137,15 +145,16 @@ export function addScenario(
   const lines = content.split('\n');
   const tagIdx = lines.findIndex((l) => l.trim() === `@req:${opts.reqId}`);
   if (tagIdx === -1) throw new AuthoringError(`req id not found in file: ${opts.reqId}`);
-  // block end = first line after the tag's own `规则:` header at 2-space top-level
-  // indent that is a tag line or a `规则:/场景:` keyword line (2-space + keyword
-  // immediately). The rule header directly following the tag opens the block, so
-  // the scan starts after it — otherwise the header itself is mistaken for the
-  // boundary and the scenario is inserted before the `规则:` line (broken output).
+  // block end = first line after the tag's own rule header at 2-space top-level
+  // indent that is a tag line or an official block keyword line (2-space +
+  // keyword immediately, any official dialect). The rule header directly
+  // following the tag opens the block, so the scan starts after it — otherwise
+  // the header itself is mistaken for the boundary and the scenario is
+  // inserted before the rule line (broken output).
   let end = lines.length;
   for (let i = tagIdx + 2; i < lines.length; i++) {
     const l = lines[i] ?? '';
-    if (l.startsWith('  @') || /^  (规则|Rule|场景|Scenario|功能|Feature):/u.test(l)) {
+    if (l.startsWith('  @') || BLOCK_KEYWORD_LINE_RE.test(l)) {
       end = i;
       break;
     }
@@ -187,21 +196,44 @@ export function resolveReq(entries: readonly SpecEntryLike[], reqId: string): Re
 
 export interface DedupePlanItem {
   reqId: string;
+  /** File of the kept (first) occurrence. */
   keepFile: string;
   remapFile: string;
   newReqId: string;
+  /** 1-based ordinal of the remapped `@req:<id>` occurrence within remapFile's text. */
+  occurrenceOrdinal: number;
+}
+
+/**
+ * Replace the ordinal-th `@req:<id>` tag in raw text. The tag match is
+ * boundary-exact (`@req:r1` never matches inside `@req:r10`), and only the
+ * target ordinal is rewritten so a kept first occurrence in the same file
+ * stays untouched (r43: 按出现顺序首现保留、其余出现逐个重取号).
+ */
+function replaceNthReqTag(
+  content: string,
+  reqId: string,
+  newReqId: string,
+  ordinal: number,
+): string {
+  const pattern = new RegExp(`@req:${reqId}(?!\\d)`, 'gu');
+  let seen = 0;
+  return content.replace(pattern, (tag) => {
+    seen += 1;
+    return seen === ordinal ? `@req:${newReqId}` : tag;
+  });
 }
 
 /**
- * Plan (and optionally apply) a re-map of globally duplicated rN ids: the
- * first file keeps the id, later files get the next free id (r43). `apply:
- * false` (`--dry-run`) returns the plan without writing anything.
+ * Plan (and optionally apply) a re-map of globally duplicated rN ids
+ * (r43: 同文件内共用或跨文件,按出现顺序首现保留、其余出现逐个重取号).
+ * `apply: false` (`--dry-run`) returns the plan without writing anything.
  */
 export function planDedupe(
   entries: readonly SpecEntryLike[],
   io: WriteIo,
   specsRoot: string,
-  duplicates: readonly { reqId: string; files: string[] }[],
+  duplicates: readonly RegistryDuplicate[],
   opts: { apply?: boolean } = {},
 ): DedupePlanItem[] {
   const used = ruleReqIds(entries);
@@ -213,12 +245,25 @@ export function planDedupe(
   };
   const plan: DedupePlanItem[] = [];
   for (const dup of duplicates) {
-    const [keep, ...rest] = dup.files;
-    for (const remapFile of rest) {
-      const newReqId = fresh();
-      if (keep !== undefined) {
-        plan.push({ reqId: dup.reqId, keepFile: keep, remapFile, newReqId });
+    // occurrences are in scan order (sorted files, in-file rule order); the
+    // per-file ordinal counts every occurrence so kept ones hold their slot
+    // in the text and remapped ones target the exact `@req:` tag to rewrite.
+    const perFileOrdinal = new Map<string, number>();
+    let keepFile: string | null = null;
+    for (const occ of dup.occurrences) {
+      const ordinal = (perFileOrdinal.get(occ.fileName) ?? 0) + 1;
+      perFileOrdinal.set(occ.fileName, ordinal);
+      if (keepFile === null) {
+        keepFile = occ.fileName;
+        continue;
       }
+      plan.push({
+        reqId: dup.reqId,
+        keepFile,
+        remapFile: occ.fileName,
+        newReqId: fresh(),
+        occurrenceOrdinal: ordinal,
+      });
     }
   }
   if (opts.apply === false) return plan;
@@ -228,7 +273,10 @@ export function planDedupe(
       ? item.remapFile
       : `${specsRoot}/${item.remapFile}`;
     const content = io.readText(path);
-    io.writeText(path, content.replaceAll(`@req:${item.reqId}`, `@req:${item.newReqId}`));
+    io.writeText(
+      path,
+      replaceNthReqTag(content, item.reqId, item.newReqId, item.occurrenceOrdinal),
+    );
   }
   return plan;
 }

package/src/spec/keywords.ts

@@ -0,0 +1,147 @@
+/**
+ * Official Gherkin dialect keyword lookup — the vocabulary SSOT is the
+ * official table shipped with @cucumber/gherkin (`dialects`, i.e.
+ * gherkin-languages.json, 80 dialects). Emitting keywords from anything
+ * else risks mixed-dialect output the official parser rejects.
+ *
+ * Selection policy (deterministic): the official tables list synonyms in an
+ * order that reproduces no contract (en `scenario: ["Example", "Scenario"]`,
+ * zh-CN `rule: ["Rule", "规则"]`), so position heuristics cannot work. The
+ * en and zh-CN contract keywords (r88 — 不得漂移) are pinned explicitly and
+ * MUST be members of their official table (runtime-checked, tests pin the
+ * bytes); every other dialect takes the first non-star synonym.
+ */
+import { dialects, type Dialect } from '@cucumber/gherkin';
+
+export interface GherkinKeywords {
+  feature: string;
+  rule: string;
+  scenario: string;
+  given: string;
+  when: string;
+  thenText: string;
+}
+
+/**
+ * GherkinKeywords keys ↔ official Dialect field keys (thenText ↔ then).
+ */
+const TABLE_KEY_PAIRS = [
+  ['feature', 'feature'],
+  ['rule', 'rule'],
+  ['scenario', 'scenario'],
+  ['given', 'given'],
+  ['when', 'when'],
+  ['then', 'thenText'],
+] as const;
+
+/** Contract-locked keyword bytes (r88) — membership-checked against the table. */
+const LOCKED_KEYWORDS: Record<string, GherkinKeywords> = {
+  en: {
+    feature: 'Feature',
+    rule: 'Rule',
+    scenario: 'Scenario',
+    given: 'Given',
+    when: 'When',
+    thenText: 'Then',
+  },
+  'zh-CN': {
+    feature: '功能',
+    rule: '规则',
+    scenario: '场景',
+    given: '假如',
+    when: '当',
+    thenText: '那么',
+  },
+};
+
+function pickKeyword(entries: readonly string[]): string {
+  return entries.map((k) => k.trim()).find((k) => k !== '' && k !== '*') ?? '';
+}
+
+function keywordsFromTable(table: Dialect): GherkinKeywords | null {
+  const kw: GherkinKeywords = {
+    feature: pickKeyword(table.feature),
+    rule: pickKeyword(table.rule),
+    scenario: pickKeyword(table.scenario),
+    given: pickKeyword(table.given),
+    when: pickKeyword(table.when),
+    thenText: pickKeyword(table.then),
+  };
+  if (Object.values(kw).some((v) => v === '')) return null;
+  return kw;
+}
+
+/** Official keywords for a gherkin dialect, or null when the language has no table. */
+export function officialKeywords(language: string): GherkinKeywords | null {
+  const table = dialects[language];
+  if (!table) return null;
+  const locked = LOCKED_KEYWORDS[language];
+  if (locked === undefined) return keywordsFromTable(table);
+  // A locked byte that left the official table would silently drift the
+  // dialect — fall through to the table instead of emitting it.
+  const fromTable = keywordsFromTable(table);
+  if (fromTable === null) return null;
+  return TABLE_KEY_PAIRS.every(([tableKey, kwKey]) =>
+    table[tableKey].map((k) => k.trim()).includes(locked[kwKey]),
+  )
+    ? locked
+    : fromTable;
+}
+
+/** Official keywords, falling back to the en table for table-less languages. */
+export function officialKeywordsOrEn(language: string): GherkinKeywords {
+  return officialKeywords(language) ?? officialKeywords('en') ?? LOCKED_KEYWORDS['en']!;
+}
+
+/**
+ * Official step keyword → kind across every dialect (star-filtered,
+ * trimmed). And/But/`*` are absent by construction — callers decide their
+ * inheritance. en/zh-CN resolve to the same kinds as the former hand-rolled
+ * regexes; other official dialects (fr Soit/Quand/Alors, …) now classify
+ * correctly instead of falling into a default.
+ */
+export const STEP_KIND_BY_KEYWORD: ReadonlyMap<string, 'given' | 'when' | 'then'> = (() => {
+  const map = new Map<string, 'given' | 'when' | 'then'>();
+  for (const table of Object.values(dialects)) {
+    for (const kind of ['given', 'when', 'then'] as const) {
+      for (const raw of table[kind]) {
+        const k = raw.trim();
+        if (k !== '' && k !== '*' && !map.has(k)) map.set(k, kind);
+      }
+    }
+  }
+  return map;
+})();
+
+export function stepKeywordToOfficialKind(keyword: string): 'given' | 'when' | 'then' | null {
+  return STEP_KIND_BY_KEYWORD.get(keyword.trim()) ?? null;
+}
+
+function escapeRegExp(k: string): string {
+  return k.replaceAll(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/**
+ * Top-level block keywords across every official dialect (2-space indent +
+ * keyword + `:`) — next-block boundary scanning must recognize a block end
+ * in any language, not just the four hardcoded ones.
+ */
+export const BLOCK_KEYWORD_LINE_RE: RegExp = new RegExp(
+  `^  (?:${[
+    ...new Set(
+      Object.values(dialects)
+        .flatMap((table) => [
+          ...table.feature,
+          ...table.rule,
+          ...table.scenario,
+          ...table.scenarioOutline,
+          ...table.background,
+        ])
+        .map((k) => k.trim())
+        .filter((k) => k !== '' && k !== '*'),
+    ),
+  ]
+    .map(escapeRegExp)
+    .join('|')}):`,
+  'u',
+);

package/src/spec/migrateNative.ts

@@ -9,7 +9,8 @@
  * derived from the tag set the official parser exposes per scenario.
  */
 
-import { parseFeatureSource } from './parser.ts';
+import { officialKeywordsOrEn } from './keywords.ts';
+import { parseFeatureSource, sourceDialect } from './parser.ts';
 
 export interface MigrateBlock {
   reqIds: string[];
@@ -22,6 +23,8 @@ export interface MigrateBlock {
 }
 
 export interface MigrateAnalysis {
+  /** Gherkin dialect the source resolved to (en start, zh-CN fallback). */
+  language: string;
   blocks: MigrateBlock[];
 }
 
@@ -86,7 +89,7 @@ export function analyzeLegacy(source: string): MigrateAnalysis | { ok: false; me
       steps: sc.steps.map((s) => ({ keyword: s.keyword.trim(), text: s.text.trim() })),
     });
   }
-  return { blocks };
+  return { language: sourceDialect(source), blocks };
 }
 
 /** Strip `- ` list markers from a rule-statement line (legacy prose residue). */
@@ -106,11 +109,20 @@ export function migrateNativeSource(source: string): MigrateResult {
   const analysis = analyzeLegacy(source);
   if ('ok' in analysis) return { ok: false, message: analysis.message };
 
-  const { blocks } = analysis as MigrateAnalysis;
+  const { language, blocks } = analysis as MigrateAnalysis;
   if (blocks.length === 0) {
     return { ok: false, message: 'no legacy scenarios found (already native?)' };
   }
 
+  // Keywords come from the official gherkin dialect table so the output
+  // stays parseable in one language — the preamble (`# language:` header,
+  // `Feature:`/`功能:` line) is kept verbatim and already matches it. The
+  // trailing parse self-check guards the rest.
+  const kw = officialKeywordsOrEn(language);
+  // The auto-nested acceptance title is a synthesized name, not a keyword —
+  // no official source exists, so it keeps its localized map.
+  const autoAcceptance = language === 'zh-CN' ? '验收示例' : 'Acceptance example';
+
   // preamble: everything before the first top-level tag line (headers,
   // feature line, comments) — cut textually, preserved verbatim.
   const lines = source.split('\n');
@@ -130,11 +142,21 @@ export function migrateNativeSource(source: string): MigrateResult {
     if (!b.isRule) continue;
     rules++;
     out.push(`  @req:${b.reqIds[0] ?? ''}`);
-    out.push(`  规则: ${b.title}`);
+    out.push(`  ${kw.rule}: ${b.title}`);
     for (const line of b.descriptionLines) {
       const text = stripBullet(line);
       if (text !== '') out.push(`    ${text}`);
     }
+    // A legacy rule scenario may carry its own acceptance steps inline
+    // (description + steps in one block). They become the rule's first
+    // nested scenario — file-order semantics, never dropped.
+    if (b.steps.length > 0) {
+      out.push('');
+      if (b.skip) out.push('    @skip');
+      out.push(`    ${kw.scenario}: ${autoAcceptance}`);
+      for (const s of b.steps) out.push(`      ${s.keyword} ${s.text}`);
+      scenarios++;
+    }
     for (const [ai, a] of blocks.entries()) {
       if (a.isRule || consumed.has(ai)) continue;
       if (!a.reqIds.some((rid) => b.reqIds.includes(rid))) continue;
@@ -142,7 +164,7 @@ export function migrateNativeSource(source: string): MigrateResult {
       scenarios++;
       out.push('');
       if (a.skip) out.push('    @skip');
-      out.push(`    场景: ${a.title}`);
+      out.push(`    ${kw.scenario}: ${a.title}`);
       for (const s of a.steps) out.push(`      ${s.keyword} ${s.text}`);
     }
   }
@@ -156,12 +178,24 @@ export function migrateNativeSource(source: string): MigrateResult {
     scenarios++;
     out.push('');
     if (a.skip) out.push('  @skip');
-    out.push(`  场景: ${a.title}`);
+    out.push(`  ${kw.scenario}: ${a.title}`);
     for (const s of a.steps) out.push(`    ${s.keyword} ${s.text}`);
   }
 
   if (rules === 0) {
     return { ok: false, message: 'no legacy rule scenarios found (@req + @rule/@human)' };
   }
-  return { ok: true, content: `${out.join('\n')}\n`, rules, scenarios };
+
+  const content = `${out.join('\n')}\n`;
+  // Fail closed: never hand back content the official parser rejects — a
+  // dialect mismatch would otherwise land on disk as silent corruption.
+  try {
+    parseFeatureSource(content);
+  } catch (error) {
+    return {
+      ok: false,
+      message: `migrated output failed parse self-check: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  return { ok: true, content, rules, scenarios };
 }

package/src/spec/parser.ts

@@ -19,6 +19,7 @@ import {
   type ScenarioStepKind,
   type SpecStructuralError,
 } from './ir.ts';
+import { stepKeywordToOfficialKind } from './keywords.ts';
 
 export class SpecParseError extends Error {}
 
@@ -52,15 +53,30 @@ export function parseFeatureSource(source: string): { doc: GherkinDocument; lang
   );
 }
 
+/**
+ * Unified source-dialect policy (r41/r88): an explicit per-file
+ * `# language:` header wins; headerless content is auto-discovered through
+ * the official matcher chain (en start, zh-CN fallback); anything still
+ * undiscoverable falls back to en. Unknown header names are returned
+ * as-is — callers pick vocabulary via officialKeywordsOrEn, and the
+ * migration parse self-check fail-closes genuinely broken headers.
+ */
+export function sourceDialect(source: string): string {
+  const firstLine = source.split('\n').find((l) => l.trim() !== '');
+  const header = firstLine?.match(/^#\s*language:\s*(\S+)\s*$/u)?.[1];
+  if (header !== undefined) return header;
+  try {
+    return parseFeatureSource(source).language;
+  } catch {
+    return 'en';
+  }
+}
+
 const REQ_TAG_RE = /^@?req:(r\d+)$/u;
 
-/** Gherkin keyword (zh-CN + en) → step kind; And/But/* inherit via fallback. */
+/** Gherkin keyword → step kind, from the official dialect tables; And/But/* inherit via fallback. */
 function stepKeywordToKind(keyword: string): ScenarioStepKind {
-  const kw = keyword.trim();
-  if (/^(假如|Given)/iu.test(kw)) return 'given';
-  if (/^(当|When)/iu.test(kw)) return 'when';
-  if (/^(那么|Then)/iu.test(kw)) return 'then';
-  return 'given';
+  return stepKeywordToOfficialKind(keyword) ?? 'given';
 }
 
 const HEADER_RE = /^#\s*(capability|purpose|scope):\s*(.*)$/u;

package/src/spec/reqRegistry.ts

@@ -1,36 +1,53 @@
 /**
  * Global rN registry (spec-parsing capability): @req:rN ids on `规则:` blocks
- * form a single global namespace across all capability specs; duplicates are
- * reported with the conflicting file pairs.
+ * form a single global namespace across all capability specs. A duplicate is
+ * any id carried by more than one rule — within one file or across files
+ * (r10: 按携带该 id 的规则条数 > 1 判定).
  */
 import type { CapabilityDoc } from './ir.ts';
 
+export interface RegistryOccurrence {
+  fileName: string;
+  /** 0-based index of the rule within its doc (in-file locating). */
+  ruleIndex: number;
+  title: string;
+}
+
 export interface RegistryDuplicate {
   reqId: string;
+  /** Unique files referencing the id (sorted, display surface). */
   files: string[];
+  /** Every rule occurrence referencing the id, in scan order. */
+  occurrences: RegistryOccurrence[];
 }
 
 export interface ReqRegistry {
-  /** reqId → files referencing it (sorted). */
-  byId: Map<string, string[]>;
+  /** reqId → every rule occurrence referencing it (scan order). */
+  byId: Map<string, RegistryOccurrence[]>;
   duplicates: RegistryDuplicate[];
 }
 
 export function buildReqRegistry(
   docs: readonly { fileName: string; doc: CapabilityDoc }[],
 ): ReqRegistry {
-  const byId = new Map<string, string[]>();
+  const byId = new Map<string, RegistryOccurrence[]>();
   for (const { fileName, doc } of docs) {
-    for (const rule of doc.rules) {
-      if (rule.reqId === '') continue;
-      const files = byId.get(rule.reqId) ?? [];
-      if (!files.includes(fileName)) files.push(fileName);
-      byId.set(rule.reqId, files);
-    }
+    doc.rules.forEach((rule, ruleIndex) => {
+      if (rule.reqId === '') return;
+      const occurrences = byId.get(rule.reqId) ?? [];
+      occurrences.push({ fileName, ruleIndex, title: rule.title });
+      byId.set(rule.reqId, occurrences);
+    });
   }
   const duplicates: RegistryDuplicate[] = [];
-  for (const [reqId, files] of byId) {
-    if (files.length > 1) duplicates.push({ reqId, files: files.toSorted() });
+  for (const [reqId, occurrences] of byId) {
+    if (occurrences.length > 1) {
+      duplicates.push({
+        reqId,
+        files: [...new Set(occurrences.map((o) => o.fileName))].toSorted(),
+        occurrences,
+      });
+    }
   }
   duplicates.sort((a, b) => a.reqId.localeCompare(b.reqId));
   return { byId, duplicates };