artifact-graph 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.9.1
+
+### Fixed
+
+- Scenario explicit relation fields (`关联决策`, `关联功能`, `关联实体`) and design-document
+  frontmatter `related_decisions` now validate each reference against the project's configured
+  `idPatterns`, so custom identifier schemes such as `ADR-0002` or `FEAT-12` produce graph edges.
+  Invalid identifiers emit diagnostics with file and line numbers instead of being silently
+  dropped, while explicit empty markers such as `无` produce neither edges nor diagnostics.
+- Design documents now read `related_decisions` as a structured frontmatter field (edge source
+  `frontmatter`), scan only the body for prose references, and never emit duplicate edges for
+  the same relation.
+- `query --from` and `render --from` now resolve a bare identifier to its unique graph node
+  regardless of the configured `idPatterns`, and report an ambiguity diagnostic asking for a
+  full `type:id` when multiple artifact types share the same bare identifier.
+
 ## 0.9.0
 
 ### Changed

package/dist/cli.js

@@ -5268,7 +5268,7 @@ function validateCodeCommentScenarioFeatureConsistency(graph) {
 }
 function queryGraph(graph, options) {
   const depth = options.depth ?? 1;
-  const start = normalizeUid(options.from ?? options.to ?? "");
+  const start = resolveQueryStartUid(graph, options.from ?? options.to ?? "");
   const reverse = Boolean(options.to && !options.from);
   const selected = /* @__PURE__ */ new Set([start]);
   let frontier = /* @__PURE__ */ new Set([start]);
@@ -5370,7 +5370,7 @@ function parseFile(type, path, raw, schema = DEFAULT_SCHEMA) {
     return { ...parseFeature(path, raw), diagnostics: [] };
   }
   if (type === "scenario") {
-    return { ...parseScenarios(path, raw, schema), diagnostics: [] };
+    return parseScenarios(path, raw, schema);
   }
   if (type === "entity") {
     return { ...parseEntityRegistry(path, raw), diagnostics: [] };
@@ -5382,7 +5382,7 @@ function parseFile(type, path, raw, schema = DEFAULT_SCHEMA) {
     return { ...parseTest(path, raw, schema), diagnostics: [] };
   }
   if (type === "design") {
-    return { ...parseDesign(path, raw), diagnostics: [] };
+    return parseDesign(path, raw, schema);
   }
   if (type === "e2e_test") {
     return { ...parseE2eTest(path, raw), diagnostics: [] };
@@ -5584,13 +5584,14 @@ function parseScenarios(path, raw, schema = DEFAULT_SCHEMA) {
   });
   const nodes = [];
   const edges = [];
+  const diagnostics = [];
   for (let i = 0; i < starts.length; i += 1) {
     const start = starts[i];
     const end = starts[i + 1]?.index ?? lines.length;
     const block = lines.slice(start.index, end);
-    const featureRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u529F\u80FD", "feature");
-    const decisionRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u51B3\u7B56", "decision");
-    const entityRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u5B9E\u4F53", "entity");
+    const featureRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u529F\u80FD", "feature", schema);
+    const decisionRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u51B3\u7B56", "decision", schema);
+    const entityRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u5B9E\u4F53", "entity", schema);
     nodes.push({
       type: "scenario",
       code: start.code,
@@ -5608,8 +5609,19 @@ function parseScenarios(path, raw, schema = DEFAULT_SCHEMA) {
     edges.push(...featureRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("feature", ref.target), "references", "markdown", path, ref.line)));
     edges.push(...decisionRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("decision", ref.target), "references", "markdown", path, ref.line)));
     edges.push(...entityRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("entity", ref.target), "references", "markdown", path, ref.line)));
+    for (const ref of [...featureRefs, ...decisionRefs, ...entityRefs]) {
+      if (ref.valid === false) {
+        diagnostics.push(issue(
+          "FORMAT_ERROR",
+          `scenario:${start.code} has invalid ${ref.targetType} reference "${ref.target}" in field ${ref.field} (expected ${schema.idPatterns[ref.targetType] ?? DEFAULT_SCHEMA.idPatterns[ref.targetType]})`,
+          ref.path,
+          ref.line,
+          { node: toUid("scenario", start.code) }
+        ));
+      }
+    }
   }
-  return { nodes, edges };
+  return { nodes, edges, diagnostics };
 }
 function parseEntityRegistry(path, raw) {
   const nodes = [];
@@ -5921,7 +5933,7 @@ function containsTraceabilityTag(value, schema = DEFAULT_SCHEMA) {
   const alternatives = [...tokens].sort((a, b) => b.length - a.length).map((token) => token.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&")).join("|");
   return new RegExp(`(?:^|\\s)@(?:${alternatives})(?=\\s|$)`).test(value);
 }
-function parseDesign(path, raw) {
+function parseDesign(path, raw, schema = DEFAULT_SCHEMA) {
   const parsed = matter(raw);
   const data = parsed.data;
   const code = normalizeDesignCode(path);
@@ -5931,15 +5943,45 @@ function parseDesign(path, raw) {
     ...designFrontmatterEdges(path, code, data.related_features, "feature", "references"),
     ...designFrontmatterEdges(path, code, data.related_scenarios, "scenario", "references")
   ];
-  raw.split(/\r?\n/).forEach((line, index) => {
+  const diagnostics = [];
+  const decisionPattern = relationIdPattern("decision", schema);
+  const frontmatterDecisions = /* @__PURE__ */ new Set();
+  for (const value of toArray(data.related_decisions)) {
+    const candidate = String(value).trim();
+    if (!candidate || EMPTY_RELATION_FIELD_VALUES.has(candidate.toLowerCase())) {
+      continue;
+    }
+    if (!decisionPattern.test(candidate)) {
+      diagnostics.push(issue(
+        "FORMAT_ERROR",
+        `design:${code} has invalid decision reference "${candidate}" in related_decisions (expected ${schema.idPatterns.decision ?? DEFAULT_SCHEMA.idPatterns.decision})`,
+        path,
+        1,
+        { node: toUid("design", code) }
+      ));
+      continue;
+    }
+    if (frontmatterDecisions.has(candidate)) {
+      continue;
+    }
+    frontmatterDecisions.add(candidate);
+    edges.push(edge(toUid("design", code), toUid("decision", candidate), "references", "frontmatter", path, 1));
+  }
+  const hasFrontmatter = /^---\r?\n/.test(raw);
+  const contentStart = hasFrontmatter && parsed.content ? Math.max(raw.indexOf(parsed.content), 0) : 0;
+  const lineOffset = contentStart > 0 ? raw.slice(0, contentStart).split(/\r?\n/).length - 1 : 0;
+  parsed.content.split(/\r?\n/).forEach((line, index) => {
     for (const codeValue of extractCodes(line, "entity")) {
-      edges.push(edge(toUid("design", code), toUid("entity", codeValue), "references", "markdown", path, index + 1));
+      edges.push(edge(toUid("design", code), toUid("entity", codeValue), "references", "markdown", path, lineOffset + index + 1));
     }
     for (const codeValue of extractCodes(line, "decision")) {
-      edges.push(edge(toUid("design", code), toUid("decision", codeValue), "references", "markdown", path, index + 1));
+      if (frontmatterDecisions.has(codeValue)) {
+        continue;
+      }
+      edges.push(edge(toUid("design", code), toUid("decision", codeValue), "references", "markdown", path, lineOffset + index + 1));
     }
   });
-  return { nodes, edges };
+  return { nodes, edges, diagnostics };
 }
 function parseE2eTest(path, raw) {
   const parsed = matter(raw);
@@ -6784,20 +6826,23 @@ function decisionFrontmatterEdges(path, decisionCode, value, targetType, kind) {
     return [edge(toUid("decision", decisionCode), toUid(targetType, code), kind, "frontmatter", path, 1)];
   });
 }
-function markdownRelationOccurrences(path, scenario, block, label, targetType, schema) {
+function markdownRelationOccurrences(path, scenario, block, label, targetType, schema = DEFAULT_SCHEMA) {
   const result = [];
   block.forEach((line, index) => {
     if (!line.includes(label)) {
       return;
     }
-    const relationText = line.split(/[:：]/).slice(1).join(":").split(/\s+[—-]\s+/)[0] ?? line;
+    const relationText = line.split(/[:：]/).slice(1).join(":").trim();
+    if (!relationText) {
+      return;
+    }
     const lineNumber = scenario.index + index + 1;
-    const codes = extractCodes(relationText, targetType, schema);
-    for (const code of codes) {
-      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText.trim() });
+    const { valid, invalid } = parseExplicitRelationField(relationText, targetType, schema);
+    for (const code of valid) {
+      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText, valid: true });
     }
-    for (const invalid of invalidRelationCandidates(relationText, targetType, codes)) {
-      result.push({ field: label, targetType, target: invalid, path, line: lineNumber, raw: relationText.trim() });
+    for (const code of invalid) {
+      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText, valid: false });
     }
   });
   return result;
@@ -6835,28 +6880,40 @@ function pushDuplicateIssues(issues, nodeUid, refs, targetType) {
   }
 }
 function isValidRelationOccurrence(ref) {
+  if (ref.valid !== void 0) {
+    return ref.valid;
+  }
   return relationTargetPattern(ref.targetType).test(ref.target);
 }
-function invalidRelationCandidates(text, targetType, validCodes) {
-  const valid = new Set(validCodes);
-  const candidates = text.split(/[\s,，、;；()[\]（）]+/).map((token) => token.trim().replace(/^["'`]+|["'`.:：]+$/g, "")).filter(Boolean);
-  const pattern = relationTargetPattern(targetType);
-  return [...new Set(candidates.filter((candidate) => looksLikeRelationId(candidate, targetType) && !valid.has(candidate) && !pattern.test(candidate)))];
+function relationIdPattern(targetType, schema) {
+  return new RegExp(schema.idPatterns[targetType] ?? DEFAULT_SCHEMA.idPatterns[targetType] ?? "^.+$");
 }
-function looksLikeRelationId(candidate, targetType) {
-  if (targetType === "feature") {
-    return /^[A-Z][A-Z0-9-]*$/.test(candidate) && (/\d/.test(candidate) || candidate.includes("-")) && !/^AC\d+$/.test(candidate);
-  }
-  if (targetType === "scenario") {
-    return /^S[-A-Z0-9]+[a-z]?$/.test(candidate);
+function stripRelationItemAnnotation(item) {
+  let result = item.trim();
+  let previous = "";
+  while (result !== previous) {
+    previous = result;
+    result = result.replace(/\s*[（(][^（）()]*[)）]\s*$/, "").trim();
+    result = result.replace(/\s+[—–-]\s+.*$/, "").trim();
   }
-  if (targetType === "decision") {
-    return /^D[-A-Z0-9]+$/.test(candidate);
-  }
-  if (targetType === "entity") {
-    return /^E[-0-9]+$/.test(candidate);
+  return result;
+}
+function parseExplicitRelationField(text, targetType, schema) {
+  const pattern = relationIdPattern(targetType, schema);
+  const valid = [];
+  const invalid = [];
+  for (const item of text.split(/[,，、;；]/)) {
+    const candidate = stripRelationItemAnnotation(item);
+    if (!candidate || EMPTY_RELATION_FIELD_VALUES.has(candidate.toLowerCase())) {
+      continue;
+    }
+    if (pattern.test(candidate)) {
+      valid.push(candidate);
+    } else if (!invalid.includes(candidate)) {
+      invalid.push(candidate);
+    }
   }
-  return false;
+  return { valid, invalid };
 }
 function relationTargetPattern(targetType) {
   const patterns = {
@@ -7979,21 +8036,19 @@ function globToRegExp(pattern) {
   }
   return new RegExp(`${source}$`);
 }
-function normalizeUid(value) {
+function resolveQueryStartUid(graph, value) {
   if (value.includes(":")) {
     return value;
   }
-  if (/^S-\d+[a-z]?$/.test(value)) {
-    return toUid("scenario", value);
-  }
-  if (/^D-[A-Z]+-\d+$/.test(value)) {
-    return toUid("decision", value);
-  }
-  if (/^E-\d{3,}$/.test(value)) {
-    return toUid("entity", value);
+  const matches = graph.nodes.filter((node) => node.code === value);
+  if (matches.length === 1) {
+    return matches[0].uid;
   }
-  if (/^[A-Z]{1,4}\d+$/.test(value)) {
-    return toUid("feature", value);
+  if (matches.length > 1) {
+    const candidates = matches.map((node) => node.uid).sort();
+    throw new Error(
+      `Ambiguous artifact id "${value}": matches ${candidates.join(", ")}. Use a fully qualified uid (type:id), for example ${candidates[0]}`
+    );
   }
   return value;
 }
@@ -8497,7 +8552,7 @@ function formatContextMarkdown(manifest) {
   }
   return lines.join("\n");
 }
-var TARGET_ARTIFACT_TYPES, NON_TARGET_ROLES, DEFAULT_SCHEMA, VALID_TC_STATUSES, VALID_CHAIN_TYPES, DEPRECATED_CHAIN_TYPE_ALIASES, CONTEXT_CATEGORIES, TIER_ORDER;
+var TARGET_ARTIFACT_TYPES, NON_TARGET_ROLES, DEFAULT_SCHEMA, EMPTY_RELATION_FIELD_VALUES, VALID_TC_STATUSES, VALID_CHAIN_TYPES, DEPRECATED_CHAIN_TYPE_ALIASES, CONTEXT_CATEGORIES, TIER_ORDER;
 var init_index = __esm({
   "src/index.ts"() {
     "use strict";
@@ -8551,7 +8606,7 @@ var init_index = __esm({
       relationFields: {
         feature: ["scenarios", "decisions", "depends_on", "design_docs"],
         scenario: ["\u5173\u8054\u529F\u80FD", "\u5173\u8054\u51B3\u7B56"],
-        design: ["related_features", "related_scenarios"],
+        design: ["related_features", "related_scenarios", "related_decisions"],
         test: ["@scenario", "@feature", "@entity", "@decision"],
         e2e_test: ["test_batch", "scope", "ac_coverage", "related_scenarios", "related_decisions", "related_entities", "\u8986\u76D6\u573A\u666F", "\u8986\u76D6\u529F\u80FD"],
         e2e_registry: ["batches"]
@@ -8566,6 +8621,7 @@ var init_index = __esm({
         runners: []
       }
     };
+    EMPTY_RELATION_FIELD_VALUES = /* @__PURE__ */ new Set(["\u65E0", "none", "n/a", "-"]);
     VALID_TC_STATUSES = /* @__PURE__ */ new Set(["created", "automated", "verified", "waived"]);
     VALID_CHAIN_TYPES = /* @__PURE__ */ new Set([
       "desktop_chain",

package/dist/index.cjs

@@ -5246,7 +5246,7 @@ function validateCodeCommentScenarioFeatureConsistency(graph) {
 }
 function queryGraph(graph, options) {
   const depth = options.depth ?? 1;
-  const start = normalizeUid(options.from ?? options.to ?? "");
+  const start = resolveQueryStartUid(graph, options.from ?? options.to ?? "");
   const reverse = Boolean(options.to && !options.from);
   const selected = /* @__PURE__ */ new Set([start]);
   let frontier = /* @__PURE__ */ new Set([start]);
@@ -5348,7 +5348,7 @@ function parseFile(type, path, raw, schema = DEFAULT_SCHEMA) {
     return { ...parseFeature(path, raw), diagnostics: [] };
   }
   if (type === "scenario") {
-    return { ...parseScenarios(path, raw, schema), diagnostics: [] };
+    return parseScenarios(path, raw, schema);
   }
   if (type === "entity") {
     return { ...parseEntityRegistry(path, raw), diagnostics: [] };
@@ -5360,7 +5360,7 @@ function parseFile(type, path, raw, schema = DEFAULT_SCHEMA) {
     return { ...parseTest(path, raw, schema), diagnostics: [] };
   }
   if (type === "design") {
-    return { ...parseDesign(path, raw), diagnostics: [] };
+    return parseDesign(path, raw, schema);
   }
   if (type === "e2e_test") {
     return { ...parseE2eTest(path, raw), diagnostics: [] };
@@ -5562,13 +5562,14 @@ function parseScenarios(path, raw, schema = DEFAULT_SCHEMA) {
   });
   const nodes = [];
   const edges = [];
+  const diagnostics = [];
   for (let i = 0; i < starts.length; i += 1) {
     const start = starts[i];
     const end = starts[i + 1]?.index ?? lines.length;
     const block = lines.slice(start.index, end);
-    const featureRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u529F\u80FD", "feature");
-    const decisionRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u51B3\u7B56", "decision");
-    const entityRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u5B9E\u4F53", "entity");
+    const featureRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u529F\u80FD", "feature", schema);
+    const decisionRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u51B3\u7B56", "decision", schema);
+    const entityRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u5B9E\u4F53", "entity", schema);
     nodes.push({
       type: "scenario",
       code: start.code,
@@ -5586,8 +5587,19 @@ function parseScenarios(path, raw, schema = DEFAULT_SCHEMA) {
     edges.push(...featureRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("feature", ref.target), "references", "markdown", path, ref.line)));
     edges.push(...decisionRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("decision", ref.target), "references", "markdown", path, ref.line)));
     edges.push(...entityRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("entity", ref.target), "references", "markdown", path, ref.line)));
+    for (const ref of [...featureRefs, ...decisionRefs, ...entityRefs]) {
+      if (ref.valid === false) {
+        diagnostics.push(issue(
+          "FORMAT_ERROR",
+          `scenario:${start.code} has invalid ${ref.targetType} reference "${ref.target}" in field ${ref.field} (expected ${schema.idPatterns[ref.targetType] ?? DEFAULT_SCHEMA.idPatterns[ref.targetType]})`,
+          ref.path,
+          ref.line,
+          { node: toUid("scenario", start.code) }
+        ));
+      }
+    }
   }
-  return { nodes, edges };
+  return { nodes, edges, diagnostics };
 }
 function parseEntityRegistry(path, raw) {
   const nodes = [];
@@ -5899,7 +5911,7 @@ function containsTraceabilityTag(value, schema = DEFAULT_SCHEMA) {
   const alternatives = [...tokens].sort((a, b) => b.length - a.length).map((token) => token.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&")).join("|");
   return new RegExp(`(?:^|\\s)@(?:${alternatives})(?=\\s|$)`).test(value);
 }
-function parseDesign(path, raw) {
+function parseDesign(path, raw, schema = DEFAULT_SCHEMA) {
   const parsed = (0, import_gray_matter.default)(raw);
   const data = parsed.data;
   const code = normalizeDesignCode(path);
@@ -5909,15 +5921,45 @@ function parseDesign(path, raw) {
     ...designFrontmatterEdges(path, code, data.related_features, "feature", "references"),
     ...designFrontmatterEdges(path, code, data.related_scenarios, "scenario", "references")
   ];
-  raw.split(/\r?\n/).forEach((line, index) => {
+  const diagnostics = [];
+  const decisionPattern = relationIdPattern("decision", schema);
+  const frontmatterDecisions = /* @__PURE__ */ new Set();
+  for (const value of toArray(data.related_decisions)) {
+    const candidate = String(value).trim();
+    if (!candidate || EMPTY_RELATION_FIELD_VALUES.has(candidate.toLowerCase())) {
+      continue;
+    }
+    if (!decisionPattern.test(candidate)) {
+      diagnostics.push(issue(
+        "FORMAT_ERROR",
+        `design:${code} has invalid decision reference "${candidate}" in related_decisions (expected ${schema.idPatterns.decision ?? DEFAULT_SCHEMA.idPatterns.decision})`,
+        path,
+        1,
+        { node: toUid("design", code) }
+      ));
+      continue;
+    }
+    if (frontmatterDecisions.has(candidate)) {
+      continue;
+    }
+    frontmatterDecisions.add(candidate);
+    edges.push(edge(toUid("design", code), toUid("decision", candidate), "references", "frontmatter", path, 1));
+  }
+  const hasFrontmatter = /^---\r?\n/.test(raw);
+  const contentStart = hasFrontmatter && parsed.content ? Math.max(raw.indexOf(parsed.content), 0) : 0;
+  const lineOffset = contentStart > 0 ? raw.slice(0, contentStart).split(/\r?\n/).length - 1 : 0;
+  parsed.content.split(/\r?\n/).forEach((line, index) => {
     for (const codeValue of extractCodes(line, "entity")) {
-      edges.push(edge(toUid("design", code), toUid("entity", codeValue), "references", "markdown", path, index + 1));
+      edges.push(edge(toUid("design", code), toUid("entity", codeValue), "references", "markdown", path, lineOffset + index + 1));
     }
     for (const codeValue of extractCodes(line, "decision")) {
-      edges.push(edge(toUid("design", code), toUid("decision", codeValue), "references", "markdown", path, index + 1));
+      if (frontmatterDecisions.has(codeValue)) {
+        continue;
+      }
+      edges.push(edge(toUid("design", code), toUid("decision", codeValue), "references", "markdown", path, lineOffset + index + 1));
     }
   });
-  return { nodes, edges };
+  return { nodes, edges, diagnostics };
 }
 function parseE2eTest(path, raw) {
   const parsed = (0, import_gray_matter.default)(raw);
@@ -6762,20 +6804,23 @@ function decisionFrontmatterEdges(path, decisionCode, value, targetType, kind) {
     return [edge(toUid("decision", decisionCode), toUid(targetType, code), kind, "frontmatter", path, 1)];
   });
 }
-function markdownRelationOccurrences(path, scenario, block, label, targetType, schema) {
+function markdownRelationOccurrences(path, scenario, block, label, targetType, schema = DEFAULT_SCHEMA) {
   const result = [];
   block.forEach((line, index) => {
     if (!line.includes(label)) {
       return;
     }
-    const relationText = line.split(/[:：]/).slice(1).join(":").split(/\s+[—-]\s+/)[0] ?? line;
+    const relationText = line.split(/[:：]/).slice(1).join(":").trim();
+    if (!relationText) {
+      return;
+    }
     const lineNumber = scenario.index + index + 1;
-    const codes = extractCodes(relationText, targetType, schema);
-    for (const code of codes) {
-      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText.trim() });
+    const { valid, invalid } = parseExplicitRelationField(relationText, targetType, schema);
+    for (const code of valid) {
+      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText, valid: true });
     }
-    for (const invalid of invalidRelationCandidates(relationText, targetType, codes)) {
-      result.push({ field: label, targetType, target: invalid, path, line: lineNumber, raw: relationText.trim() });
+    for (const code of invalid) {
+      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText, valid: false });
     }
   });
   return result;
@@ -6813,28 +6858,40 @@ function pushDuplicateIssues(issues, nodeUid, refs, targetType) {
   }
 }
 function isValidRelationOccurrence(ref) {
+  if (ref.valid !== void 0) {
+    return ref.valid;
+  }
   return relationTargetPattern(ref.targetType).test(ref.target);
 }
-function invalidRelationCandidates(text, targetType, validCodes) {
-  const valid = new Set(validCodes);
-  const candidates = text.split(/[\s,，、;；()[\]（）]+/).map((token) => token.trim().replace(/^["'`]+|["'`.:：]+$/g, "")).filter(Boolean);
-  const pattern = relationTargetPattern(targetType);
-  return [...new Set(candidates.filter((candidate) => looksLikeRelationId(candidate, targetType) && !valid.has(candidate) && !pattern.test(candidate)))];
+function relationIdPattern(targetType, schema) {
+  return new RegExp(schema.idPatterns[targetType] ?? DEFAULT_SCHEMA.idPatterns[targetType] ?? "^.+$");
 }
-function looksLikeRelationId(candidate, targetType) {
-  if (targetType === "feature") {
-    return /^[A-Z][A-Z0-9-]*$/.test(candidate) && (/\d/.test(candidate) || candidate.includes("-")) && !/^AC\d+$/.test(candidate);
-  }
-  if (targetType === "scenario") {
-    return /^S[-A-Z0-9]+[a-z]?$/.test(candidate);
+function stripRelationItemAnnotation(item) {
+  let result = item.trim();
+  let previous = "";
+  while (result !== previous) {
+    previous = result;
+    result = result.replace(/\s*[（(][^（）()]*[)）]\s*$/, "").trim();
+    result = result.replace(/\s+[—–-]\s+.*$/, "").trim();
   }
-  if (targetType === "decision") {
-    return /^D[-A-Z0-9]+$/.test(candidate);
-  }
-  if (targetType === "entity") {
-    return /^E[-0-9]+$/.test(candidate);
+  return result;
+}
+function parseExplicitRelationField(text, targetType, schema) {
+  const pattern = relationIdPattern(targetType, schema);
+  const valid = [];
+  const invalid = [];
+  for (const item of text.split(/[,，、;；]/)) {
+    const candidate = stripRelationItemAnnotation(item);
+    if (!candidate || EMPTY_RELATION_FIELD_VALUES.has(candidate.toLowerCase())) {
+      continue;
+    }
+    if (pattern.test(candidate)) {
+      valid.push(candidate);
+    } else if (!invalid.includes(candidate)) {
+      invalid.push(candidate);
+    }
   }
-  return false;
+  return { valid, invalid };
 }
 function relationTargetPattern(targetType) {
   const patterns = {
@@ -7957,21 +8014,19 @@ function globToRegExp(pattern) {
   }
   return new RegExp(`${source}$`);
 }
-function normalizeUid(value) {
+function resolveQueryStartUid(graph, value) {
   if (value.includes(":")) {
     return value;
   }
-  if (/^S-\d+[a-z]?$/.test(value)) {
-    return toUid("scenario", value);
-  }
-  if (/^D-[A-Z]+-\d+$/.test(value)) {
-    return toUid("decision", value);
-  }
-  if (/^E-\d{3,}$/.test(value)) {
-    return toUid("entity", value);
+  const matches = graph.nodes.filter((node) => node.code === value);
+  if (matches.length === 1) {
+    return matches[0].uid;
   }
-  if (/^[A-Z]{1,4}\d+$/.test(value)) {
-    return toUid("feature", value);
+  if (matches.length > 1) {
+    const candidates = matches.map((node) => node.uid).sort();
+    throw new Error(
+      `Ambiguous artifact id "${value}": matches ${candidates.join(", ")}. Use a fully qualified uid (type:id), for example ${candidates[0]}`
+    );
   }
   return value;
 }
@@ -8475,7 +8530,7 @@ function formatContextMarkdown(manifest) {
   }
   return lines.join("\n");
 }
-var import_better_sqlite3, import_gray_matter, import_js_yaml, import_node_fs4, import_promises7, import_node_path8, TARGET_ARTIFACT_TYPES, NON_TARGET_ROLES, DEFAULT_SCHEMA, VALID_TC_STATUSES, VALID_CHAIN_TYPES, DEPRECATED_CHAIN_TYPE_ALIASES, CONTEXT_CATEGORIES, TIER_ORDER;
+var import_better_sqlite3, import_gray_matter, import_js_yaml, import_node_fs4, import_promises7, import_node_path8, TARGET_ARTIFACT_TYPES, NON_TARGET_ROLES, DEFAULT_SCHEMA, EMPTY_RELATION_FIELD_VALUES, VALID_TC_STATUSES, VALID_CHAIN_TYPES, DEPRECATED_CHAIN_TYPE_ALIASES, CONTEXT_CATEGORIES, TIER_ORDER;
 var init_index = __esm({
   "src/index.ts"() {
     import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
@@ -8534,7 +8589,7 @@ var init_index = __esm({
       relationFields: {
         feature: ["scenarios", "decisions", "depends_on", "design_docs"],
         scenario: ["\u5173\u8054\u529F\u80FD", "\u5173\u8054\u51B3\u7B56"],
-        design: ["related_features", "related_scenarios"],
+        design: ["related_features", "related_scenarios", "related_decisions"],
         test: ["@scenario", "@feature", "@entity", "@decision"],
         e2e_test: ["test_batch", "scope", "ac_coverage", "related_scenarios", "related_decisions", "related_entities", "\u8986\u76D6\u573A\u666F", "\u8986\u76D6\u529F\u80FD"],
         e2e_registry: ["batches"]
@@ -8549,6 +8604,7 @@ var init_index = __esm({
         runners: []
       }
     };
+    EMPTY_RELATION_FIELD_VALUES = /* @__PURE__ */ new Set(["\u65E0", "none", "n/a", "-"]);
     VALID_TC_STATUSES = /* @__PURE__ */ new Set(["created", "automated", "verified", "waived"]);
     VALID_CHAIN_TYPES = /* @__PURE__ */ new Set([
       "desktop_chain",

package/dist/index.js

@@ -5136,7 +5136,7 @@ function validateCodeCommentScenarioFeatureConsistency(graph) {
 }
 function queryGraph(graph, options) {
   const depth = options.depth ?? 1;
-  const start = normalizeUid(options.from ?? options.to ?? "");
+  const start = resolveQueryStartUid(graph, options.from ?? options.to ?? "");
   const reverse = Boolean(options.to && !options.from);
   const selected = /* @__PURE__ */ new Set([start]);
   let frontier = /* @__PURE__ */ new Set([start]);
@@ -5238,7 +5238,7 @@ function parseFile(type, path, raw, schema = DEFAULT_SCHEMA) {
     return { ...parseFeature(path, raw), diagnostics: [] };
   }
   if (type === "scenario") {
-    return { ...parseScenarios(path, raw, schema), diagnostics: [] };
+    return parseScenarios(path, raw, schema);
   }
   if (type === "entity") {
     return { ...parseEntityRegistry(path, raw), diagnostics: [] };
@@ -5250,7 +5250,7 @@ function parseFile(type, path, raw, schema = DEFAULT_SCHEMA) {
     return { ...parseTest(path, raw, schema), diagnostics: [] };
   }
   if (type === "design") {
-    return { ...parseDesign(path, raw), diagnostics: [] };
+    return parseDesign(path, raw, schema);
   }
   if (type === "e2e_test") {
     return { ...parseE2eTest(path, raw), diagnostics: [] };
@@ -5452,13 +5452,14 @@ function parseScenarios(path, raw, schema = DEFAULT_SCHEMA) {
   });
   const nodes = [];
   const edges = [];
+  const diagnostics = [];
   for (let i = 0; i < starts.length; i += 1) {
     const start = starts[i];
     const end = starts[i + 1]?.index ?? lines.length;
     const block = lines.slice(start.index, end);
-    const featureRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u529F\u80FD", "feature");
-    const decisionRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u51B3\u7B56", "decision");
-    const entityRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u5B9E\u4F53", "entity");
+    const featureRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u529F\u80FD", "feature", schema);
+    const decisionRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u51B3\u7B56", "decision", schema);
+    const entityRefs = markdownRelationOccurrences(path, start, block, "\u5173\u8054\u5B9E\u4F53", "entity", schema);
     nodes.push({
       type: "scenario",
       code: start.code,
@@ -5476,8 +5477,19 @@ function parseScenarios(path, raw, schema = DEFAULT_SCHEMA) {
     edges.push(...featureRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("feature", ref.target), "references", "markdown", path, ref.line)));
     edges.push(...decisionRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("decision", ref.target), "references", "markdown", path, ref.line)));
     edges.push(...entityRefs.filter(isValidRelationOccurrence).map((ref) => edge(toUid("scenario", start.code), toUid("entity", ref.target), "references", "markdown", path, ref.line)));
+    for (const ref of [...featureRefs, ...decisionRefs, ...entityRefs]) {
+      if (ref.valid === false) {
+        diagnostics.push(issue(
+          "FORMAT_ERROR",
+          `scenario:${start.code} has invalid ${ref.targetType} reference "${ref.target}" in field ${ref.field} (expected ${schema.idPatterns[ref.targetType] ?? DEFAULT_SCHEMA.idPatterns[ref.targetType]})`,
+          ref.path,
+          ref.line,
+          { node: toUid("scenario", start.code) }
+        ));
+      }
+    }
   }
-  return { nodes, edges };
+  return { nodes, edges, diagnostics };
 }
 function parseEntityRegistry(path, raw) {
   const nodes = [];
@@ -5789,7 +5801,7 @@ function containsTraceabilityTag(value, schema = DEFAULT_SCHEMA) {
   const alternatives = [...tokens].sort((a, b) => b.length - a.length).map((token) => token.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&")).join("|");
   return new RegExp(`(?:^|\\s)@(?:${alternatives})(?=\\s|$)`).test(value);
 }
-function parseDesign(path, raw) {
+function parseDesign(path, raw, schema = DEFAULT_SCHEMA) {
   const parsed = matter(raw);
   const data = parsed.data;
   const code = normalizeDesignCode(path);
@@ -5799,15 +5811,45 @@ function parseDesign(path, raw) {
     ...designFrontmatterEdges(path, code, data.related_features, "feature", "references"),
     ...designFrontmatterEdges(path, code, data.related_scenarios, "scenario", "references")
   ];
-  raw.split(/\r?\n/).forEach((line, index) => {
+  const diagnostics = [];
+  const decisionPattern = relationIdPattern("decision", schema);
+  const frontmatterDecisions = /* @__PURE__ */ new Set();
+  for (const value of toArray(data.related_decisions)) {
+    const candidate = String(value).trim();
+    if (!candidate || EMPTY_RELATION_FIELD_VALUES.has(candidate.toLowerCase())) {
+      continue;
+    }
+    if (!decisionPattern.test(candidate)) {
+      diagnostics.push(issue(
+        "FORMAT_ERROR",
+        `design:${code} has invalid decision reference "${candidate}" in related_decisions (expected ${schema.idPatterns.decision ?? DEFAULT_SCHEMA.idPatterns.decision})`,
+        path,
+        1,
+        { node: toUid("design", code) }
+      ));
+      continue;
+    }
+    if (frontmatterDecisions.has(candidate)) {
+      continue;
+    }
+    frontmatterDecisions.add(candidate);
+    edges.push(edge(toUid("design", code), toUid("decision", candidate), "references", "frontmatter", path, 1));
+  }
+  const hasFrontmatter = /^---\r?\n/.test(raw);
+  const contentStart = hasFrontmatter && parsed.content ? Math.max(raw.indexOf(parsed.content), 0) : 0;
+  const lineOffset = contentStart > 0 ? raw.slice(0, contentStart).split(/\r?\n/).length - 1 : 0;
+  parsed.content.split(/\r?\n/).forEach((line, index) => {
     for (const codeValue of extractCodes(line, "entity")) {
-      edges.push(edge(toUid("design", code), toUid("entity", codeValue), "references", "markdown", path, index + 1));
+      edges.push(edge(toUid("design", code), toUid("entity", codeValue), "references", "markdown", path, lineOffset + index + 1));
     }
     for (const codeValue of extractCodes(line, "decision")) {
-      edges.push(edge(toUid("design", code), toUid("decision", codeValue), "references", "markdown", path, index + 1));
+      if (frontmatterDecisions.has(codeValue)) {
+        continue;
+      }
+      edges.push(edge(toUid("design", code), toUid("decision", codeValue), "references", "markdown", path, lineOffset + index + 1));
     }
   });
-  return { nodes, edges };
+  return { nodes, edges, diagnostics };
 }
 function parseE2eTest(path, raw) {
   const parsed = matter(raw);
@@ -6652,20 +6694,23 @@ function decisionFrontmatterEdges(path, decisionCode, value, targetType, kind) {
     return [edge(toUid("decision", decisionCode), toUid(targetType, code), kind, "frontmatter", path, 1)];
   });
 }
-function markdownRelationOccurrences(path, scenario, block, label, targetType, schema) {
+function markdownRelationOccurrences(path, scenario, block, label, targetType, schema = DEFAULT_SCHEMA) {
   const result = [];
   block.forEach((line, index) => {
     if (!line.includes(label)) {
       return;
     }
-    const relationText = line.split(/[:：]/).slice(1).join(":").split(/\s+[—-]\s+/)[0] ?? line;
+    const relationText = line.split(/[:：]/).slice(1).join(":").trim();
+    if (!relationText) {
+      return;
+    }
     const lineNumber = scenario.index + index + 1;
-    const codes = extractCodes(relationText, targetType, schema);
-    for (const code of codes) {
-      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText.trim() });
+    const { valid, invalid } = parseExplicitRelationField(relationText, targetType, schema);
+    for (const code of valid) {
+      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText, valid: true });
     }
-    for (const invalid of invalidRelationCandidates(relationText, targetType, codes)) {
-      result.push({ field: label, targetType, target: invalid, path, line: lineNumber, raw: relationText.trim() });
+    for (const code of invalid) {
+      result.push({ field: label, targetType, target: code, path, line: lineNumber, raw: relationText, valid: false });
     }
   });
   return result;
@@ -6703,28 +6748,40 @@ function pushDuplicateIssues(issues, nodeUid, refs, targetType) {
   }
 }
 function isValidRelationOccurrence(ref) {
+  if (ref.valid !== void 0) {
+    return ref.valid;
+  }
   return relationTargetPattern(ref.targetType).test(ref.target);
 }
-function invalidRelationCandidates(text, targetType, validCodes) {
-  const valid = new Set(validCodes);
-  const candidates = text.split(/[\s,，、;；()[\]（）]+/).map((token) => token.trim().replace(/^["'`]+|["'`.:：]+$/g, "")).filter(Boolean);
-  const pattern = relationTargetPattern(targetType);
-  return [...new Set(candidates.filter((candidate) => looksLikeRelationId(candidate, targetType) && !valid.has(candidate) && !pattern.test(candidate)))];
+function relationIdPattern(targetType, schema) {
+  return new RegExp(schema.idPatterns[targetType] ?? DEFAULT_SCHEMA.idPatterns[targetType] ?? "^.+$");
 }
-function looksLikeRelationId(candidate, targetType) {
-  if (targetType === "feature") {
-    return /^[A-Z][A-Z0-9-]*$/.test(candidate) && (/\d/.test(candidate) || candidate.includes("-")) && !/^AC\d+$/.test(candidate);
-  }
-  if (targetType === "scenario") {
-    return /^S[-A-Z0-9]+[a-z]?$/.test(candidate);
+function stripRelationItemAnnotation(item) {
+  let result = item.trim();
+  let previous = "";
+  while (result !== previous) {
+    previous = result;
+    result = result.replace(/\s*[（(][^（）()]*[)）]\s*$/, "").trim();
+    result = result.replace(/\s+[—–-]\s+.*$/, "").trim();
   }
-  if (targetType === "decision") {
-    return /^D[-A-Z0-9]+$/.test(candidate);
-  }
-  if (targetType === "entity") {
-    return /^E[-0-9]+$/.test(candidate);
+  return result;
+}
+function parseExplicitRelationField(text, targetType, schema) {
+  const pattern = relationIdPattern(targetType, schema);
+  const valid = [];
+  const invalid = [];
+  for (const item of text.split(/[,，、;；]/)) {
+    const candidate = stripRelationItemAnnotation(item);
+    if (!candidate || EMPTY_RELATION_FIELD_VALUES.has(candidate.toLowerCase())) {
+      continue;
+    }
+    if (pattern.test(candidate)) {
+      valid.push(candidate);
+    } else if (!invalid.includes(candidate)) {
+      invalid.push(candidate);
+    }
   }
-  return false;
+  return { valid, invalid };
 }
 function relationTargetPattern(targetType) {
   const patterns = {
@@ -7847,21 +7904,19 @@ function globToRegExp(pattern) {
   }
   return new RegExp(`${source}$`);
 }
-function normalizeUid(value) {
+function resolveQueryStartUid(graph, value) {
   if (value.includes(":")) {
     return value;
   }
-  if (/^S-\d+[a-z]?$/.test(value)) {
-    return toUid("scenario", value);
-  }
-  if (/^D-[A-Z]+-\d+$/.test(value)) {
-    return toUid("decision", value);
-  }
-  if (/^E-\d{3,}$/.test(value)) {
-    return toUid("entity", value);
+  const matches = graph.nodes.filter((node) => node.code === value);
+  if (matches.length === 1) {
+    return matches[0].uid;
   }
-  if (/^[A-Z]{1,4}\d+$/.test(value)) {
-    return toUid("feature", value);
+  if (matches.length > 1) {
+    const candidates = matches.map((node) => node.uid).sort();
+    throw new Error(
+      `Ambiguous artifact id "${value}": matches ${candidates.join(", ")}. Use a fully qualified uid (type:id), for example ${candidates[0]}`
+    );
   }
   return value;
 }
@@ -8365,7 +8420,7 @@ function formatContextMarkdown(manifest) {
   }
   return lines.join("\n");
 }
-var TARGET_ARTIFACT_TYPES, NON_TARGET_ROLES, DEFAULT_SCHEMA, VALID_TC_STATUSES, VALID_CHAIN_TYPES, DEPRECATED_CHAIN_TYPE_ALIASES, CONTEXT_CATEGORIES, TIER_ORDER;
+var TARGET_ARTIFACT_TYPES, NON_TARGET_ROLES, DEFAULT_SCHEMA, EMPTY_RELATION_FIELD_VALUES, VALID_TC_STATUSES, VALID_CHAIN_TYPES, DEPRECATED_CHAIN_TYPE_ALIASES, CONTEXT_CATEGORIES, TIER_ORDER;
 var init_index = __esm({
   "src/index.ts"() {
     init_packet_constants();
@@ -8418,7 +8473,7 @@ var init_index = __esm({
       relationFields: {
         feature: ["scenarios", "decisions", "depends_on", "design_docs"],
         scenario: ["\u5173\u8054\u529F\u80FD", "\u5173\u8054\u51B3\u7B56"],
-        design: ["related_features", "related_scenarios"],
+        design: ["related_features", "related_scenarios", "related_decisions"],
         test: ["@scenario", "@feature", "@entity", "@decision"],
         e2e_test: ["test_batch", "scope", "ac_coverage", "related_scenarios", "related_decisions", "related_entities", "\u8986\u76D6\u573A\u666F", "\u8986\u76D6\u529F\u80FD"],
         e2e_registry: ["batches"]
@@ -8433,6 +8488,7 @@ var init_index = __esm({
         runners: []
       }
     };
+    EMPTY_RELATION_FIELD_VALUES = /* @__PURE__ */ new Set(["\u65E0", "none", "n/a", "-"]);
     VALID_TC_STATUSES = /* @__PURE__ */ new Set(["created", "automated", "verified", "waived"]);
     VALID_CHAIN_TYPES = /* @__PURE__ */ new Set([
       "desktop_chain",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifact-graph",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Git-native Markdown artifact graph scanner and validator",
   "license": "Apache-2.0",
   "type": "module",