qfai 0.5.0 → 0.6.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/core/config.ts
-import { readFile } from "fs/promises";
+import { access, readFile } from "fs/promises";
 import path from "path";
 import { parse as parseYaml } from "yaml";
 var defaultConfig = {
@@ -31,7 +31,7 @@ var defaultConfig = {
       testFileGlobs: [],
       testFileExcludeGlobs: [],
       scNoTestSeverity: "error",
-      allowOrphanContracts: false,
+      orphanContractsPolicy: "error",
       unknownContractIdSeverity: "error"
     }
   },
@@ -42,6 +42,26 @@ var defaultConfig = {
 function getConfigPath(root) {
   return path.join(root, "qfai.config.yaml");
 }
+async function findConfigRoot(startDir) {
+  const resolvedStart = path.resolve(startDir);
+  let current = resolvedStart;
+  while (true) {
+    const configPath = getConfigPath(current);
+    if (await exists(configPath)) {
+      return { root: current, configPath, found: true };
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return {
+    root: resolvedStart,
+    configPath: getConfigPath(resolvedStart),
+    found: false
+  };
+}
 async function loadConfig(root) {
   const configPath = getConfigPath(root);
   const issues = [];
@@ -231,10 +251,10 @@ function normalizeValidation(raw, configPath, issues) {
         configPath,
         issues
       ),
-      allowOrphanContracts: readBoolean(
-        traceabilityRaw?.allowOrphanContracts,
-        base.traceability.allowOrphanContracts,
-        "validation.traceability.allowOrphanContracts",
+      orphanContractsPolicy: readOrphanContractsPolicy(
+        traceabilityRaw?.orphanContractsPolicy,
+        base.traceability.orphanContractsPolicy,
+        "validation.traceability.orphanContractsPolicy",
         configPath,
         issues
       ),
@@ -330,6 +350,20 @@ function readTraceabilitySeverity(value, fallback, label, configPath, issues) {
   }
   return fallback;
 }
+function readOrphanContractsPolicy(value, fallback, label, configPath, issues) {
+  if (value === "error" || value === "warning" || value === "allow") {
+    return value;
+  }
+  if (value !== void 0) {
+    issues.push(
+      configIssue(
+        configPath,
+        `${label} \u306F error|warning|allow \u306E\u3044\u305A\u308C\u304B\u3067\u3042\u308B\u5FC5\u8981\u304C\u3042\u308A\u307E\u3059\u3002`
+      )
+    );
+  }
+  return fallback;
+}
 function configIssue(file, message) {
   return {
     code: "QFAI_CONFIG_INVALID",
@@ -345,6 +379,14 @@ function isMissingFile(error) {
   }
   return false;
 }
+async function exists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function formatError(error) {
   if (error instanceof Error) {
     return error.message;
@@ -410,17 +452,17 @@ function isValidId(value, prefix) {
 
 // src/core/report.ts
 import { readFile as readFile11 } from "fs/promises";
-import path11 from "path";
+import path12 from "path";
 
 // src/core/contractIndex.ts
 import { readFile as readFile2 } from "fs/promises";
 import path4 from "path";
 
 // src/core/discovery.ts
-import { access as access2 } from "fs/promises";
+import { access as access3 } from "fs/promises";
 
 // src/core/fs.ts
-import { access, readdir } from "fs/promises";
+import { access as access2, readdir } from "fs/promises";
 import path2 from "path";
 import fg from "fast-glob";
 var DEFAULT_IGNORE_DIRS = /* @__PURE__ */ new Set([
@@ -433,7 +475,7 @@ var DEFAULT_IGNORE_DIRS = /* @__PURE__ */ new Set([
 ]);
 async function collectFiles(root, options = {}) {
   const entries = [];
-  if (!await exists(root)) {
+  if (!await exists2(root)) {
     return entries;
   }
   const ignoreDirs = /* @__PURE__ */ new Set([
@@ -478,9 +520,9 @@ async function walk(base, current, ignoreDirs, extensions, out) {
     }
   }
 }
-async function exists(target) {
+async function exists2(target) {
   try {
-    await access(target);
+    await access2(target);
     return true;
   } catch {
     return false;
@@ -552,15 +594,15 @@ async function collectContractFiles(uiRoot, apiRoot, dbRoot) {
 async function filterExisting(files) {
   const existing = [];
   for (const file of files) {
-    if (await exists2(file)) {
+    if (await exists3(file)) {
       existing.push(file);
     }
   }
   return existing;
 }
-async function exists2(target) {
+async function exists3(target) {
   try {
-    await access2(target);
+    await access3(target);
     return true;
   } catch {
     return false;
@@ -618,6 +660,113 @@ function record(index, id, file) {
   index.idToFiles.set(id, current);
 }
 
+// src/core/paths.ts
+import path5 from "path";
+function toRelativePath(root, target) {
+  if (!target) {
+    return target;
+  }
+  if (!path5.isAbsolute(target)) {
+    return toPosixPath(target);
+  }
+  const relative = path5.relative(root, target);
+  if (!relative) {
+    return ".";
+  }
+  return toPosixPath(relative);
+}
+function toPosixPath(value) {
+  return value.replace(/\\/g, "/");
+}
+
+// src/core/normalize.ts
+function normalizeIssuePaths(root, issues) {
+  return issues.map((issue7) => {
+    if (!issue7.file) {
+      return issue7;
+    }
+    const normalized = toRelativePath(root, issue7.file);
+    if (normalized === issue7.file) {
+      return issue7;
+    }
+    return {
+      ...issue7,
+      file: normalized
+    };
+  });
+}
+function normalizeScCoverage(root, sc) {
+  const refs = {};
+  for (const [scId, files] of Object.entries(sc.refs)) {
+    refs[scId] = files.map((file) => toRelativePath(root, file));
+  }
+  return {
+    ...sc,
+    refs
+  };
+}
+function normalizeValidationResult(root, result) {
+  return {
+    ...result,
+    issues: normalizeIssuePaths(root, result.issues),
+    traceability: {
+      ...result.traceability,
+      sc: normalizeScCoverage(root, result.traceability.sc)
+    }
+  };
+}
+
+// src/core/parse/contractRefs.ts
+var CONTRACT_REF_ID_RE = /^(?:API|UI|DB)-\d{4}$/;
+function parseContractRefs(text, options = {}) {
+  const linePattern = buildLinePattern(options);
+  const lines = [];
+  for (const match of text.matchAll(linePattern)) {
+    lines.push((match[1] ?? "").trim());
+  }
+  const ids = [];
+  const invalidTokens = [];
+  let hasNone = false;
+  for (const line of lines) {
+    if (line.length === 0) {
+      invalidTokens.push("(empty)");
+      continue;
+    }
+    const tokens = line.split(",").map((token) => token.trim());
+    for (const token of tokens) {
+      if (token.length === 0) {
+        invalidTokens.push("(empty)");
+        continue;
+      }
+      if (token === "none") {
+        hasNone = true;
+        continue;
+      }
+      if (CONTRACT_REF_ID_RE.test(token)) {
+        ids.push(token);
+        continue;
+      }
+      invalidTokens.push(token);
+    }
+  }
+  return {
+    lines,
+    ids: unique2(ids),
+    invalidTokens: unique2(invalidTokens),
+    hasNone
+  };
+}
+function buildLinePattern(options) {
+  const prefix = options.allowCommentPrefix ? "#" : "";
+  return new RegExp(
+    `^[ \\t]*${prefix}[ \\t]*QFAI-CONTRACT-REF:[ \\t]*([^\\r\\n]*)[ \\t]*$`,
+    "gm"
+  );
+}
+function unique2(values) {
+  return Array.from(new Set(values));
+}
+
 // src/core/parse/markdown.ts
 var HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
 function parseHeadings(md) {
@@ -664,8 +813,6 @@ var SPEC_ID_RE = /\bSPEC-\d{4}\b/;
 var BR_LINE_RE = /^\s*(?:[-*]\s*)?\[(BR-\d{4})\]\[(P[0-3])\]\s*(.+)$/;
 var BR_LINE_ANY_PRIORITY_RE = /^\s*(?:[-*]\s*)?\[(BR-\d{4})\]\[(P[^\]]+)\]\s*(.+)$/;
 var BR_LINE_NO_PRIORITY_RE = /^\s*(?:[-*]\s*)?\[(BR-\d{4})\](?!\s*\[P)\s*(.*\S.*)$/;
-var CONTRACT_REF_LINE_RE = /^[ \t]*QFAI-CONTRACT-REF:[ \t]*([^\r\n]*)[ \t]*$/gm;
-var CONTRACT_REF_ID_RE = /^(?:API|UI|DB)-\d{4}$/;
 var BR_SECTION_TITLE = "\u696D\u52D9\u30EB\u30FC\u30EB";
 var VALID_PRIORITIES = /* @__PURE__ */ new Set(["P0", "P1", "P2", "P3"]);
 function parseSpec(md, file) {
@@ -738,50 +885,10 @@ function parseSpec(md, file) {
   }
   return parsed;
 }
-function parseContractRefs(md) {
-  const lines = [];
-  for (const match of md.matchAll(CONTRACT_REF_LINE_RE)) {
-    lines.push((match[1] ?? "").trim());
-  }
-  const ids = [];
-  const invalidTokens = [];
-  let hasNone = false;
-  for (const line of lines) {
-    if (line.length === 0) {
-      invalidTokens.push("(empty)");
-      continue;
-    }
-    const tokens = line.split(",").map((token) => token.trim());
-    for (const token of tokens) {
-      if (token.length === 0) {
-        invalidTokens.push("(empty)");
-        continue;
-      }
-      if (token === "none") {
-        hasNone = true;
-        continue;
-      }
-      if (CONTRACT_REF_ID_RE.test(token)) {
-        ids.push(token);
-        continue;
-      }
-      invalidTokens.push(token);
-    }
-  }
-  return {
-    lines,
-    ids: unique2(ids),
-    invalidTokens: unique2(invalidTokens),
-    hasNone
-  };
-}
-function unique2(values) {
-  return Array.from(new Set(values));
-}
 
 // src/core/traceability.ts
 import { readFile as readFile3 } from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 
 // src/core/gherkin/parse.ts
 import {
@@ -816,9 +923,6 @@ function formatError2(error) {
 var SPEC_TAG_RE = /^SPEC-\d{4}$/;
 var SC_TAG_RE = /^SC-\d{4}$/;
 var BR_TAG_RE = /^BR-\d{4}$/;
-var UI_TAG_RE = /^UI-\d{4}$/;
-var API_TAG_RE = /^API-\d{4}$/;
-var DB_TAG_RE = /^DB-\d{4}$/;
 function parseScenarioDocument(text, uri) {
   const { gherkinDocument, errors } = parseGherkin(text, uri);
   if (!gherkinDocument) {
@@ -843,31 +947,21 @@ function parseScenarioDocument(text, uri) {
     errors
   };
 }
-function buildScenarioAtoms(document) {
+function buildScenarioAtoms(document, contractIds = []) {
+  const uniqueContractIds = unique3(contractIds).sort(
+    (a, b) => a.localeCompare(b)
+  );
   return document.scenarios.map((scenario) => {
     const specIds = scenario.tags.filter((tag) => SPEC_TAG_RE.test(tag));
     const scIds = scenario.tags.filter((tag) => SC_TAG_RE.test(tag));
     const brIds = unique3(scenario.tags.filter((tag) => BR_TAG_RE.test(tag)));
-    const contractIds = /* @__PURE__ */ new Set();
-    scenario.tags.forEach((tag) => {
-      if (UI_TAG_RE.test(tag) || API_TAG_RE.test(tag) || DB_TAG_RE.test(tag)) {
-        contractIds.add(tag);
-      }
-    });
-    for (const step of scenario.steps) {
-      for (const text of collectStepTexts(step)) {
-        extractIds(text, "UI").forEach((id) => contractIds.add(id));
-        extractIds(text, "API").forEach((id) => contractIds.add(id));
-        extractIds(text, "DB").forEach((id) => contractIds.add(id));
-      }
-    }
     const atom = {
       uri: document.uri,
       featureName: document.featureName ?? "",
       scenarioName: scenario.name,
       kind: scenario.kind,
       brIds,
-      contractIds: Array.from(contractIds).sort()
+      contractIds: uniqueContractIds
     };
     if (scenario.line !== void 0) {
       atom.line = scenario.line;
@@ -920,23 +1014,6 @@ function buildScenarioNode(scenario, featureTags, ruleTags) {
 function collectTagNames(tags) {
   return tags.map((tag) => tag.name.replace(/^@/, ""));
 }
-function collectStepTexts(step) {
-  const texts = [];
-  if (step.text) {
-    texts.push(step.text);
-  }
-  if (step.docString?.content) {
-    texts.push(step.docString.content);
-  }
-  if (step.dataTable?.rows) {
-    for (const row of step.dataTable.rows) {
-      for (const cell of row.cells) {
-        texts.push(cell.value);
-      }
-    }
-  }
-  return texts;
-}
 function unique3(values) {
   return Array.from(new Set(values));
 }
@@ -1038,7 +1115,7 @@ async function collectScTestReferences(root, globs, excludeGlobs) {
     };
   }
   const normalizedFiles = Array.from(
-    new Set(files.map((file) => path5.normalize(file)))
+    new Set(files.map((file) => path6.normalize(file)))
   );
   for (const file of normalizedFiles) {
     const text = await readFile3(file, "utf-8");
@@ -1099,11 +1176,11 @@ function formatError3(error) {
 
 // src/core/version.ts
 import { readFile as readFile4 } from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 import { fileURLToPath } from "url";
 async function resolveToolVersion() {
-  if ("0.5.0".length > 0) {
-    return "0.5.0";
+  if ("0.6.0".length > 0) {
+    return "0.6.0";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -1118,18 +1195,18 @@ async function resolveToolVersion() {
 function resolvePackageJsonPath() {
   const base = import.meta.url;
   const basePath = base.startsWith("file:") ? fileURLToPath(base) : base;
-  return path6.resolve(path6.dirname(basePath), "../../package.json");
+  return path7.resolve(path7.dirname(basePath), "../../package.json");
 }
 
 // src/core/validators/contracts.ts
 import { readFile as readFile5 } from "fs/promises";
-import path8 from "path";
+import path9 from "path";
 
 // src/core/contracts.ts
-import path7 from "path";
+import path8 from "path";
 import { parse as parseYaml2 } from "yaml";
 function parseStructuredContract(file, text) {
-  const ext = path7.extname(file).toLowerCase();
+  const ext = path8.extname(file).toLowerCase();
   if (ext === ".json") {
     return JSON.parse(text);
   }
@@ -1149,9 +1226,9 @@ var SQL_DANGEROUS_PATTERNS = [
 async function validateContracts(root, config) {
   const issues = [];
   const contractsRoot = resolvePath(root, config, "contractsDir");
-  issues.push(...await validateUiContracts(path8.join(contractsRoot, "ui")));
-  issues.push(...await validateApiContracts(path8.join(contractsRoot, "api")));
-  issues.push(...await validateDbContracts(path8.join(contractsRoot, "db")));
+  issues.push(...await validateUiContracts(path9.join(contractsRoot, "ui")));
+  issues.push(...await validateApiContracts(path9.join(contractsRoot, "api")));
+  issues.push(...await validateDbContracts(path9.join(contractsRoot, "db")));
   const contractIndex = await buildContractIndex(root, config);
   issues.push(...validateDuplicateContractIds(contractIndex));
   return issues;
@@ -1434,7 +1511,7 @@ function issue(code, message, severity, file, rule, refs) {
 
 // src/core/validators/delta.ts
 import { readFile as readFile6 } from "fs/promises";
-import path9 from "path";
+import path10 from "path";
 var SECTION_RE = /^##\s+変更区分/m;
 var COMPAT_LINE_RE = /^\s*-\s*\[[ xX]\]\s*Compatibility\b/m;
 var CHANGE_LINE_RE = /^\s*-\s*\[[ xX]\]\s*Change\/Improvement\b/m;
@@ -1448,7 +1525,7 @@ async function validateDeltas(root, config) {
   }
   const issues = [];
   for (const pack of packs) {
-    const deltaPath = path9.join(pack, "delta.md");
+    const deltaPath = path10.join(pack, "delta.md");
     let text;
     try {
       text = await readFile6(deltaPath, "utf-8");
@@ -1524,7 +1601,7 @@ function issue2(code, message, severity, file, rule, refs) {
 
 // src/core/validators/ids.ts
 import { readFile as readFile7 } from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 var SC_TAG_RE3 = /^SC-\d{4}$/;
 async function validateDefinedIds(root, config) {
   const issues = [];
@@ -1590,7 +1667,7 @@ function recordId(out, id, file) {
 }
 function formatFileList(files, root) {
   return files.map((file) => {
-    const relative = path10.relative(root, file);
+    const relative = path11.relative(root, file);
     return relative.length > 0 ? relative : file;
   }).join(", ");
 }
@@ -2027,7 +2104,7 @@ async function validateTraceability(root, config) {
       if (contractRefs.hasNone && contractRefs.ids.length > 0) {
         issues.push(
           issue6(
-            "QFAI-TRACE-021",
+            "QFAI-TRACE-023",
             "Spec \u306E QFAI-CONTRACT-REF \u306B none \u3068\u5951\u7D04 ID \u304C\u6DF7\u5728\u3057\u3066\u3044\u307E\u3059\u3002",
             "error",
             file,
@@ -2059,7 +2136,7 @@ async function validateTraceability(root, config) {
     if (unknownContractIds.length > 0) {
       issues.push(
         issue6(
-          "QFAI-TRACE-021",
+          "QFAI-TRACE-024",
           `Spec \u304C\u672A\u77E5\u306E\u5951\u7D04 ID \u3092\u53C2\u7167\u3057\u3066\u3044\u307E\u3059: ${unknownContractIds.join(
             ", "
           )}`,
@@ -2074,11 +2151,62 @@ async function validateTraceability(root, config) {
   for (const file of scenarioFiles) {
     const text = await readFile10(file, "utf-8");
     extractAllIds(text).forEach((id) => upstreamIds.add(id));
+    const scenarioContractRefs = parseContractRefs(text, {
+      allowCommentPrefix: true
+    });
+    if (scenarioContractRefs.lines.length === 0) {
+      issues.push(
+        issue6(
+          "QFAI-TRACE-031",
+          "Scenario \u306B QFAI-CONTRACT-REF \u304C\u3042\u308A\u307E\u305B\u3093\u3002",
+          "error",
+          file,
+          "traceability.scenarioContractRefRequired"
+        )
+      );
+    } else {
+      if (scenarioContractRefs.hasNone && scenarioContractRefs.ids.length > 0) {
+        issues.push(
+          issue6(
+            "QFAI-TRACE-033",
+            "Scenario \u306E QFAI-CONTRACT-REF \u306B none \u3068\u5951\u7D04 ID \u304C\u6DF7\u5728\u3057\u3066\u3044\u307E\u3059\u3002",
+            "error",
+            file,
+            "traceability.scenarioContractRefFormat"
+          )
+        );
+      }
+      if (scenarioContractRefs.invalidTokens.length > 0) {
+        issues.push(
+          issue6(
+            "QFAI-TRACE-032",
+            `Scenario \u306E\u5951\u7D04 ID \u304C\u4E0D\u6B63\u3067\u3059: ${scenarioContractRefs.invalidTokens.join(
+              ", "
+            )}`,
+            "error",
+            file,
+            "traceability.scenarioContractRefFormat",
+            scenarioContractRefs.invalidTokens
+          )
+        );
+      }
+    }
     const { document, errors } = parseScenarioDocument(text, file);
     if (!document || errors.length > 0) {
       continue;
     }
-    const atoms = buildScenarioAtoms(document);
+    if (document.scenarios.length !== 1) {
+      issues.push(
+        issue6(
+          "QFAI-TRACE-030",
+          `Scenario \u30D5\u30A1\u30A4\u30EB\u306F 1\u30D5\u30A1\u30A4\u30EB=1\u30B7\u30CA\u30EA\u30AA\u3067\u3059\u3002\u73FE\u5728: ${document.scenarios.length}\u4EF6 (file=${file})`,
+          "error",
+          file,
+          "traceability.scenarioOnePerFile"
+        )
+      );
+    }
+    const atoms = buildScenarioAtoms(document, scenarioContractRefs.ids);
     const scIdsInFile = /* @__PURE__ */ new Set();
     for (const [index, scenario] of document.scenarios.entries()) {
       const atom = atoms[index];
@@ -2223,7 +2351,7 @@ async function validateTraceability(root, config) {
     if (orphanBrIds.length > 0) {
       issues.push(
         issue6(
-          "QFAI_TRACE_BR_ORPHAN",
+          "QFAI-TRACE-009",
           `BR \u304C SC \u306B\u7D10\u3065\u3044\u3066\u3044\u307E\u305B\u3093: ${orphanBrIds.join(", ")}`,
           "error",
           specsRoot,
@@ -2293,17 +2421,19 @@ async function validateTraceability(root, config) {
       );
     }
   }
-  if (!config.validation.traceability.allowOrphanContracts) {
+  const orphanPolicy = config.validation.traceability.orphanContractsPolicy;
+  if (orphanPolicy !== "allow") {
     if (contractIds.size > 0) {
       const orphanContracts = Array.from(contractIds).filter(
         (id) => !specContractIds.has(id)
       );
       if (orphanContracts.length > 0) {
+        const severity = orphanPolicy === "warning" ? "warning" : "error";
         issues.push(
           issue6(
             "QFAI-TRACE-022",
             `\u5951\u7D04\u304C Spec \u304B\u3089\u53C2\u7167\u3055\u308C\u3066\u3044\u307E\u305B\u3093: ${orphanContracts.join(", ")}`,
-            "error",
+            severity,
             specsRoot,
             "traceability.contractCoverage",
             orphanContracts
@@ -2428,16 +2558,17 @@ function countIssues(issues) {
 // src/core/report.ts
 var ID_PREFIXES2 = ["SPEC", "BR", "SC", "UI", "API", "DB"];
 async function createReportData(root, validation, configResult) {
-  const resolved = configResult ?? await loadConfig(root);
+  const resolvedRoot = path12.resolve(root);
+  const resolved = configResult ?? await loadConfig(resolvedRoot);
   const config = resolved.config;
   const configPath = resolved.configPath;
-  const specsRoot = resolvePath(root, config, "specsDir");
-  const contractsRoot = resolvePath(root, config, "contractsDir");
-  const apiRoot = path11.join(contractsRoot, "api");
-  const uiRoot = path11.join(contractsRoot, "ui");
-  const dbRoot = path11.join(contractsRoot, "db");
-  const srcRoot = resolvePath(root, config, "srcDir");
-  const testsRoot = resolvePath(root, config, "testsDir");
+  const specsRoot = resolvePath(resolvedRoot, config, "specsDir");
+  const contractsRoot = resolvePath(resolvedRoot, config, "contractsDir");
+  const apiRoot = path12.join(contractsRoot, "api");
+  const uiRoot = path12.join(contractsRoot, "ui");
+  const dbRoot = path12.join(contractsRoot, "db");
+  const srcRoot = resolvePath(resolvedRoot, config, "srcDir");
+  const testsRoot = resolvePath(resolvedRoot, config, "testsDir");
   const specFiles = await collectSpecFiles(specsRoot);
   const scenarioFiles = await collectScenarioFiles(specsRoot);
   const {
@@ -2445,15 +2576,15 @@ async function createReportData(root, validation, configResult) {
     ui: uiFiles,
     db: dbFiles
   } = await collectContractFiles(uiRoot, apiRoot, dbRoot);
-  const contractIndex = await buildContractIndex(root, config);
+  const contractIndex = await buildContractIndex(resolvedRoot, config);
   const contractIdList = Array.from(contractIndex.ids);
   const specContractRefs = await collectSpecContractRefs(
     specFiles,
     contractIdList
   );
   const referencedContracts = /* @__PURE__ */ new Set();
-  for (const ids of specContractRefs.specToContractIds.values()) {
-    ids.forEach((id) => referencedContracts.add(id));
+  for (const entry of specContractRefs.specToContracts.values()) {
+    entry.ids.forEach((id) => referencedContracts.add(id));
   }
   const referencedContractCount = contractIdList.filter(
     (id) => referencedContracts.has(id)
@@ -2462,8 +2593,8 @@ async function createReportData(root, validation, configResult) {
     (id) => !referencedContracts.has(id)
   ).length;
   const contractIdToSpecsRecord = mapToSortedRecord(specContractRefs.idToSpecs);
-  const specToContractIdsRecord = mapToSortedRecord(
-    specContractRefs.specToContractIds
+  const specToContractsRecord = mapToSpecContractRecord(
+    specContractRefs.specToContracts
   );
   const idsByPrefix = await collectIds([
     ...specFiles,
@@ -2481,24 +2612,28 @@ async function createReportData(root, validation, configResult) {
     srcRoot,
     testsRoot
   );
-  const scIds = await collectScIdsFromScenarioFiles(scenarioFiles);
-  const scRefsResult = await collectScTestReferences(
-    root,
-    config.validation.traceability.testFileGlobs,
-    config.validation.traceability.testFileExcludeGlobs
+  const resolvedValidationRaw = validation ?? await validateProject(resolvedRoot, resolved);
+  const normalizedValidation = normalizeValidationResult(
+    resolvedRoot,
+    resolvedValidationRaw
   );
-  const scCoverage = validation?.traceability?.sc ?? buildScCoverage(scIds, scRefsResult.refs);
-  const testFiles = validation?.traceability?.testFiles ?? scRefsResult.scan;
+  const scCoverage = normalizedValidation.traceability.sc;
+  const testFiles = normalizedValidation.traceability.testFiles;
   const scSources = await collectScIdSourcesFromScenarioFiles(scenarioFiles);
-  const scSourceRecord = mapToSortedRecord(scSources);
-  const resolvedValidation = validation ?? await validateProject(root, resolved);
+  const scSourceRecord = mapToSortedRecord(
+    normalizeScSources(resolvedRoot, scSources)
+  );
   const version = await resolveToolVersion();
+  const reportFormatVersion = 1;
+  const displayRoot = toRelativePath(resolvedRoot, resolvedRoot);
+  const displayConfigPath = toRelativePath(resolvedRoot, configPath);
   return {
     tool: "qfai",
     version,
+    reportFormatVersion,
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    root,
-    configPath,
+    root: displayRoot,
+    configPath: displayConfigPath,
     summary: {
       specs: specFiles.length,
       scenarios: scenarioFiles.length,
@@ -2507,7 +2642,7 @@ async function createReportData(root, validation, configResult) {
         ui: uiFiles.length,
         db: dbFiles.length
       },
-      counts: resolvedValidation.counts
+      counts: normalizedValidation.counts
     },
     ids: {
       spec: idsByPrefix.SPEC,
@@ -2532,21 +2667,23 @@ async function createReportData(root, validation, configResult) {
       specs: {
         contractRefMissing: specContractRefs.missingRefSpecs.size,
         missingRefSpecs: toSortedArray2(specContractRefs.missingRefSpecs),
-        specToContractIds: specToContractIdsRecord
+        specToContracts: specToContractsRecord
       }
     },
-    issues: resolvedValidation.issues
+    issues: normalizedValidation.issues
   };
 }
 function formatReportMarkdown(data) {
   const lines = [];
   lines.push("# QFAI Report");
+  lines.push("");
   lines.push(`- \u751F\u6210\u65E5\u6642: ${data.generatedAt}`);
   lines.push(`- \u30EB\u30FC\u30C8: ${data.root}`);
   lines.push(`- \u8A2D\u5B9A: ${data.configPath}`);
   lines.push(`- \u7248: ${data.version}`);
   lines.push("");
   lines.push("## \u6982\u8981");
+  lines.push("");
   lines.push(`- specs: ${data.summary.specs}`);
   lines.push(`- scenarios: ${data.summary.scenarios}`);
   lines.push(
@@ -2557,6 +2694,7 @@ function formatReportMarkdown(data) {
   );
   lines.push("");
   lines.push("## ID\u96C6\u8A08");
+  lines.push("");
   lines.push(formatIdLine("SPEC", data.ids.spec));
   lines.push(formatIdLine("BR", data.ids.br));
   lines.push(formatIdLine("SC", data.ids.sc));
@@ -2565,12 +2703,14 @@ function formatReportMarkdown(data) {
   lines.push(formatIdLine("DB", data.ids.db));
   lines.push("");
   lines.push("## \u30C8\u30EC\u30FC\u30B5\u30D3\u30EA\u30C6\u30A3");
+  lines.push("");
   lines.push(`- \u4E0A\u6D41ID\u691C\u51FA\u6570: ${data.traceability.upstreamIdsFound}`);
   lines.push(
     `- \u30B3\u30FC\u30C9/\u30C6\u30B9\u30C8\u53C2\u7167: ${data.traceability.referencedInCodeOrTests ? "\u3042\u308A" : "\u306A\u3057"}`
   );
   lines.push("");
   lines.push("## \u5951\u7D04\u30AB\u30D0\u30EC\u30C3\u30B8");
+  lines.push("");
   lines.push(`- total: ${data.traceability.contracts.total}`);
   lines.push(`- referenced: ${data.traceability.contracts.referenced}`);
   lines.push(`- orphan: ${data.traceability.contracts.orphan}`);
@@ -2579,6 +2719,7 @@ function formatReportMarkdown(data) {
   );
   lines.push("");
   lines.push("## \u5951\u7D04\u2192Spec");
+  lines.push("");
   const contractToSpecs = data.traceability.contracts.idToSpecs;
   const contractIds = Object.keys(contractToSpecs).sort(
     (a, b) => a.localeCompare(b)
@@ -2597,24 +2738,25 @@ function formatReportMarkdown(data) {
   }
   lines.push("");
   lines.push("## Spec\u2192\u5951\u7D04");
-  const specToContracts = data.traceability.specs.specToContractIds;
+  lines.push("");
+  const specToContracts = data.traceability.specs.specToContracts;
   const specIds = Object.keys(specToContracts).sort(
     (a, b) => a.localeCompare(b)
   );
   if (specIds.length === 0) {
     lines.push("- (none)");
   } else {
-    for (const specId of specIds) {
-      const contractIds2 = specToContracts[specId] ?? [];
-      if (contractIds2.length === 0) {
-        lines.push(`- ${specId}: (none)`);
-      } else {
-        lines.push(`- ${specId}: ${contractIds2.join(", ")}`);
-      }
-    }
+    const rows = specIds.map((specId) => {
+      const entry = specToContracts[specId];
+      const contracts = entry?.status === "missing" ? "(missing)" : entry && entry.ids.length > 0 ? entry.ids.join(", ") : "(none)";
+      const status = entry?.status ?? "missing";
+      return [specId, status, contracts];
+    });
+    lines.push(...formatMarkdownTable(["Spec", "Status", "Contracts"], rows));
   }
   lines.push("");
   lines.push("## Spec\u3067 contract-ref \u672A\u5BA3\u8A00");
+  lines.push("");
   const missingRefSpecs = data.traceability.specs.missingRefSpecs;
   if (missingRefSpecs.length === 0) {
     lines.push("- (none)");
@@ -2625,6 +2767,7 @@ function formatReportMarkdown(data) {
   }
   lines.push("");
   lines.push("## SC\u30AB\u30D0\u30EC\u30C3\u30B8");
+  lines.push("");
   lines.push(`- total: ${data.traceability.sc.total}`);
   lines.push(`- covered: ${data.traceability.sc.covered}`);
   lines.push(`- missing: ${data.traceability.sc.missing}`);
@@ -2654,6 +2797,7 @@ function formatReportMarkdown(data) {
   }
   lines.push("");
   lines.push("## SC\u2192\u53C2\u7167\u30C6\u30B9\u30C8");
+  lines.push("");
   const scRefs = data.traceability.sc.refs;
   const scIds = Object.keys(scRefs).sort((a, b) => a.localeCompare(b));
   if (scIds.length === 0) {
@@ -2670,6 +2814,7 @@ function formatReportMarkdown(data) {
   }
   lines.push("");
   lines.push("## Spec:SC=1:1 \u9055\u53CD");
+  lines.push("");
   const specScIssues = data.issues.filter(
     (item) => item.code === "QFAI-TRACE-012"
   );
@@ -2684,6 +2829,7 @@ function formatReportMarkdown(data) {
   }
   lines.push("");
   lines.push("## Hotspots");
+  lines.push("");
   const hotspots = buildHotspots(data.issues);
   if (hotspots.length === 0) {
     lines.push("- (none)");
@@ -2696,6 +2842,7 @@ function formatReportMarkdown(data) {
   }
   lines.push("");
   lines.push("## \u30C8\u30EC\u30FC\u30B5\u30D3\u30EA\u30C6\u30A3\uFF08\u691C\u8A3C\uFF09");
+  lines.push("");
   const traceIssues = data.issues.filter(
     (item) => item.rule?.startsWith("traceability.") || item.code.startsWith("QFAI_TRACE") || item.code.startsWith("QFAI-TRACE-")
   );
@@ -2711,6 +2858,7 @@ function formatReportMarkdown(data) {
   }
   lines.push("");
   lines.push("## \u691C\u8A3C\u7D50\u679C");
+  lines.push("");
   if (data.issues.length === 0) {
     lines.push("- (none)");
   } else {
@@ -2728,7 +2876,7 @@ function formatReportJson(data) {
   return JSON.stringify(data, null, 2);
 }
 async function collectSpecContractRefs(specFiles, contractIdList) {
-  const specToContractIds = /* @__PURE__ */ new Map();
+  const specToContracts = /* @__PURE__ */ new Map();
   const idToSpecs = /* @__PURE__ */ new Map();
   const missingRefSpecs = /* @__PURE__ */ new Set();
   for (const contractId of contractIdList) {
@@ -2737,24 +2885,31 @@ async function collectSpecContractRefs(specFiles, contractIdList) {
   for (const file of specFiles) {
     const text = await readFile11(file, "utf-8");
     const parsed = parseSpec(text, file);
-    const specKey = parsed.specId ?? file;
+    const specKey = parsed.specId;
+    if (!specKey) {
+      continue;
+    }
     const refs = parsed.contractRefs;
     if (refs.lines.length === 0) {
       missingRefSpecs.add(specKey);
+      specToContracts.set(specKey, { status: "missing", ids: /* @__PURE__ */ new Set() });
       continue;
     }
-    const currentContracts = specToContractIds.get(specKey) ?? /* @__PURE__ */ new Set();
+    const current = specToContracts.get(specKey) ?? {
+      status: "declared",
+      ids: /* @__PURE__ */ new Set()
+    };
     for (const id of refs.ids) {
-      currentContracts.add(id);
+      current.ids.add(id);
       const specs = idToSpecs.get(id);
       if (specs) {
         specs.add(specKey);
       }
     }
-    specToContractIds.set(specKey, currentContracts);
+    specToContracts.set(specKey, current);
   }
   return {
-    specToContractIds,
+    specToContracts,
     idToSpecs,
     missingRefSpecs
   };
@@ -2831,6 +2986,20 @@ function formatList(values) {
   }
   return values.join(", ");
 }
+function formatMarkdownTable(headers, rows) {
+  const widths = headers.map((header, index) => {
+    const candidates = rows.map((row) => row[index] ?? "");
+    return Math.max(header.length, ...candidates.map((item) => item.length));
+  });
+  const formatRow = (cells) => {
+    const padded = cells.map(
+      (cell, index) => (cell ?? "").padEnd(widths[index] ?? 0)
+    );
+    return `| ${padded.join(" | ")} |`;
+  };
+  const separator = `| ${widths.map((width) => "-".repeat(width)).join(" | ")} |`;
+  return [formatRow(headers), separator, ...rows.map(formatRow)];
+}
 function toSortedArray2(values) {
   return Array.from(values).sort((a, b) => a.localeCompare(b));
 }
@@ -2841,6 +3010,27 @@ function mapToSortedRecord(values) {
   }
   return record2;
 }
+function mapToSpecContractRecord(values) {
+  const record2 = {};
+  for (const [key, entry] of values.entries()) {
+    record2[key] = {
+      status: entry.status,
+      ids: toSortedArray2(entry.ids)
+    };
+  }
+  return record2;
+}
+function normalizeScSources(root, sources) {
+  const normalized = /* @__PURE__ */ new Map();
+  for (const [id, files] of sources.entries()) {
+    const mapped = /* @__PURE__ */ new Set();
+    for (const file of files) {
+      mapped.add(toRelativePath(root, file));
+    }
+    normalized.set(id, mapped);
+  }
+  return normalized;
+}
 function buildHotspots(issues) {
   const map = /* @__PURE__ */ new Map();
   for (const issue7 of issues) {
@@ -2868,6 +3058,7 @@ export {
   extractAllIds,
   extractIds,
   extractInvalidIds,
+  findConfigRoot,
   formatReportJson,
   formatReportMarkdown,
   getConfigPath,