kld-sdd 2.6.16 → 2.6.21

package/skywalk-sdd/ontology/runtime.cjs

@@ -28,9 +28,16 @@ const {
   resolveRevisionBundlePaths,
   removeLegacyOntologyStateFiles,
 } = require('./ontology-paths.cjs');
+const {
+  sha256: sharedSha256,
+  readJson: sharedReadJson,
+  writeIfChanged,
+  ensureDir,
+  stripBom,
+} = require('../lib/shared.cjs');
 
 function sha256(value) {
-  return crypto.createHash('sha256').update(value).digest('hex');
+  return sharedSha256(value);
 }
 
 function resolveChangeDir(projectRoot, changeName) {
@@ -56,17 +63,11 @@ function serialized(value) {
   return JSON.stringify(value, null, 2) + '\n';
 }
 
-function atomicWriteIfChanged(filePath, value) {
+// atomicWriteIfChanged 已迁移至 lib/shared.cjs
+const atomicWriteIfChanged = (filePath, value) => {
   const content = typeof value === 'string' ? value : serialized(value);
-  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) {
-    return false;
-  }
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  const tempPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
-  fs.writeFileSync(tempPath, content, 'utf8');
-  fs.renameSync(tempPath, filePath);
-  return true;
-}
+  return writeIfChanged(filePath, content);
+};
 
 function stateError(code, message) {
   const error = new Error(`${code}: ${message}`);
@@ -74,9 +75,12 @@ function stateError(code, message) {
   return error;
 }
 
+// readJson 改用 shared.cjs 版本（带 BOM 剥离），保留 stateError 包装
 function readJson(filePath, code) {
   try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    let raw = fs.readFileSync(filePath, 'utf8');
+    raw = stripBom(raw);
+    return JSON.parse(raw);
   } catch (error) {
     throw stateError(code, `无法读取状态文件 ${filePath}: ${error.message}`);
   }

package/skywalk-sdd/ontology/traceability-validator.cjs

@@ -137,7 +137,10 @@ function validateIdentitySemantics(facts, diagnostics, identityHistory) {
     }
   }
 
-  if (!Array.isArray(identityHistory)) return;
+  // 当本地无身份历史（单变更、无 confirmed archive）时，跳过基于历史的校验。
+  // 此场景下 modified/unchanged 实体的 predecessor-version 来自 KB resolve，
+  // lineage 由 KB 后端 version_id 唯一性约束兜底，不由本地校验阻断。
+  if (!Array.isArray(identityHistory) || identityHistory.length === 0) return;
   const historyByEntityId = new Map();
   const historyByVersionId = new Map();
   const historyByAnchor = new Map();
@@ -515,7 +518,7 @@ function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
         DIAGNOSTIC_CODES.EXTERNAL_KEY_FORMAT_INVALID,
         'error',
         format.message,
-        { file: 'proposal.md', suggestion: '回需求管理系统核实/换发编号，禁止改写' },
+        { file: 'proposal.md', suggestion: '检查外部编号格式（仅允许大写字母、数字、连字符、下划线），禁止改写' },
       ));
       continue;
     }
@@ -578,7 +581,7 @@ function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
           {
             ...sourceContext(entity),
             entity_id: entity.id,
-            suggestion: '编号不合规回需求系统换发；场景键回 opsx-spec 修正',
+            suggestion: '编号格式不合规（仅允许大写字母、数字、连字符、下划线）；场景键回 opsx-spec 修正',
           },
         ));
       }
@@ -605,7 +608,7 @@ function validateContinuityAndExternalRefs(facts, diagnostics, options = {}) {
           diagnostics.push(diagnostic(
             DIAGNOSTIC_CODES.EXTERNAL_KEY_SCOPE_MISMATCH,
             'error',
-            `场景键 REQ 前缀不在 frontmatter requirement-refs 申报集合: ${normalizedScenario}`,
+            `场景键需求编号前缀不在 frontmatter requirement-refs 申报集合: ${normalizedScenario}`,
             { ...sourceContext(entity), entity_id: entity.id },
           ));
         }

package/skywalk-sdd/reporting/change-report-markdown.cjs

@@ -1,6 +1,32 @@
 'use strict';
 
 const { buildChangeReportViewModel } = require('./change-report-view-model.cjs');
+const { buildChangeReportModel } = require('./change-report-model.cjs');
+
+function escapeMarkdownText(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/\\/g, '\')
+    .replace(/\[/g, '[')
+    .replace(/\]/g, ']')
+    .replace(/`/g, '`')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+    .replace(/[\r\n]+/g, ' ');
+}
+
+function sanitizeMarkdownValue(value) {
+  if (typeof value === 'string') return escapeMarkdownText(value);
+  if (Array.isArray(value)) return value.map(sanitizeMarkdownValue);
+  if (!value || typeof value !== 'object') return value;
+  const sanitized = {};
+  for (const [key, item] of Object.entries(value)) {
+    sanitized[escapeMarkdownText(key)] = sanitizeMarkdownValue(item);
+  }
+  return sanitized;
+}
 
 function formatValue(value) {
   if (value == null || value === '') return '暂无数据';
@@ -12,6 +38,59 @@ function formatRatioToPercent(ratio) {
   return `${(Number(ratio) * 100).toFixed(1)}%`;
 }
 
+function renderMetricDetail(detail) {
+  if (!detail) return [];
+  const lines = [
+    '',
+    `### ${detail.name}（${detail.code}）`,
+    '',
+    `- 指标定义：${detail.definition}`,
+    `- 指标用途：${detail.purpose}`,
+    `- 计算公式：${detail.formula}`,
+    `- 数据来源：${detail.source_description}`,
+    `- 对应方案：${detail.scheme_reference}`,
+    '',
+    '#### 本次原始数据',
+  ];
+  const inputs = detail.raw_inputs || [];
+  if (inputs.length === 0) {
+    lines.push('- 暂无可展示的原始数据。');
+  } else {
+    for (const input of inputs) {
+      const value = input.display_value ?? input.value ?? '暂无数据';
+      const inclusion = input.included === false
+        ? `；不计入公式：${input.exclusion_reason || '仅作辅助说明'}`
+        : '';
+      lines.push(`- ${input.label}：${value}（来源：${input.source || '未记录'}${inclusion}）`);
+    }
+  }
+  lines.push('', '#### 计算步骤');
+  for (const step of detail.calculation_steps || ['暂无可复算步骤。']) {
+    lines.push(`- ${step}`);
+  }
+  lines.push(
+    '',
+    '#### 本次结果',
+    `- ${detail.result?.display_value || '暂无数据'}`,
+    `- 可信度：${detail.trust?.explanation || '未记录'}`,
+    '',
+    '#### 证据与限制',
+  );
+  const evidence = detail.evidence || [];
+  if (evidence.length === 0) {
+    lines.push('- 当前没有可定位的证据编号；计算值可能来自兼容字段。');
+  } else {
+    for (const item of evidence) {
+      lines.push(`- ${item.path || item.event_id || item.type || '证据'}${item.count == null ? '' : `（${item.count} 条）`}`);
+      for (const scenario of item.scenarios || []) {
+        lines.push(`  - 场景：${scenario.title || '未命名'}（第 ${scenario.line ?? '未知'} 行）`);
+      }
+    }
+  }
+  for (const caveat of detail.caveats || []) lines.push(`- ${caveat}`);
+  return lines;
+}
+
 function renderSectionOverview(section, report) {
   const minSet = report.minimum_metric_set || {};
   const lines = [
@@ -47,7 +126,7 @@ function renderSectionOverview(section, report) {
 
 function renderSectionMetrics(section, report) {
   const tdd = section.tdd_pairs || {};
-  const reasons = report.metrics?.process?.rework_summary?.reasons;
+  const reasons = report.metric_details?.p_r?.raw_values?.reasons;
   const lines = [
     `## ${section.title}`,
     '',
@@ -58,9 +137,12 @@ function renderSectionMetrics(section, report) {
   for (const metric of section.metric_cards || []) {
     lines.push(`- ${metric.name}（${metric.code}）：${metric.value} · ${metric.state}`);
   }
-  if (reasons?.by_category) {
-    const parts = Object.entries(reasons.by_category)
-      .map(([k, v]) => `${k}=${v}`)
+  for (const metric of section.metric_cards || []) {
+    lines.push(...renderMetricDetail(metric.detail));
+  }
+  if (reasons) {
+    const parts = Object.values(reasons)
+      .map(item => `${item.label}=${item.count}`)
       .join(', ');
     lines.push(`- 重复执行原因分布：${parts || '无'}`);
   }
@@ -97,6 +179,11 @@ function renderSectionIssues(section, report) {
     '',
     section.summary,
     '',
+    '### 这些内容是怎么收集的',
+    `- ${section.collection_method}`,
+    `- 功能验证：${section.functional_result?.summary || '未记录'}${section.functional_result?.explanation ? ` ${section.functional_result.explanation}` : ''}`,
+    `- 证据链判断：${section.traceability_result?.summary || '未记录'}${section.traceability_result?.explanation ? ` ${section.traceability_result.explanation}` : ''}`,
+    '',
   ];
   const audit = section.task_evidence_audit || {};
   if (audit.direct_test_backlink || audit.strict_test_coverage) {
@@ -129,7 +216,7 @@ function renderSectionIssues(section, report) {
     lines.push('', '### 问题明细');
     for (const issue of issues) {
       lines.push(
-        `- [${issue.code}] ${issue.subject || '本次变更'} · 状态：${issue.status} · 判定：${issue.verdict}`,
+        `- [${issue.code}] ${issue.subject || '本次变更'} · 状态：${issue.status_label || issue.status}`,
         `  - 根因：${issue.root_cause}`,
         `  - 预期：${issue.expected}`,
         `  - 实际：${issue.actual}`,
@@ -150,7 +237,7 @@ function renderSectionIssues(section, report) {
   if (dispositions.length > 0) {
     lines.push('', '### 告警处置');
     for (const item of dispositions) {
-      lines.push(`- [告警处置] ${item.warning || item.code || 'UNKNOWN'}：${item.disposition || 'open'}`);
+      lines.push(`- [告警处置] ${item.warning || item.code || 'UNKNOWN'}：${item.disposition_label || '待处理'}`);
     }
   }
 
@@ -168,8 +255,16 @@ function renderSectionIssues(section, report) {
       lines.push(`- 警告：${warning.command || 'check'} 阶段 ${count} 个${statusLabel}`);
       if (items && items.length > 0) {
         for (const item of items) {
+          const itemStatus = ({
+            fixed: '已解决',
+            accepted: '已接受，保留观察',
+            waived: '已豁免，不阻断',
+            ignored: '不重要，已标记',
+            needs_input: '等待补充信息',
+            open: '待处理',
+          }[item.disposition] || statusLabel);
           lines.push(
-            `  - ${item.description || '待确认项'}${item.target ? `（${item.target}）` : ''}`,
+            `  - [${itemStatus}] ${item.description || '待确认项'}${item.target ? `（${item.target}）` : ''}`,
           );
         }
       }
@@ -178,12 +273,12 @@ function renderSectionIssues(section, report) {
     lines.push('- 无警告（无需修复）');
   }
 
-  const notes = report.process_notes || {};
+  const notes = section.process_notes || {};
   lines.push('', '## 过程记录');
   lines.push(`- 数据可用：${notes._available ? '是' : '否'}`);
   lines.push(`- 过程事件总数：${notes.total ?? 'null'}`);
   if (notes.by_kind) {
-    lines.push(`- 按 kind 分布：${JSON.stringify(notes.by_kind)}`);
+    lines.push(`- 按类型分布：${JSON.stringify(notes.by_kind)}`);
   }
   if (Array.isArray(notes.notes) && notes.notes.length > 0) {
     for (const note of notes.notes) {
@@ -209,10 +304,34 @@ function renderSectionArtifacts(section, report) {
     '',
     '### 变更文件',
     `- 数据可用：${rawChanged._available ? '是' : '否'}`,
-    `- 最终变更文件数：${formatValue(changed.files_changed)}`,
     `- 新增行数：${formatValue(changed.added_lines)}`,
-    `- 对账状态：${formatValue(changed.reconciliation_status)}`,
+    `- 对账状态：${formatValue(changed.reconciliation_status_label)}`,
   ];
+  const taskScope = changed.task_scope || {};
+  const finalScope = changed.final_scope || {};
+  lines.push(
+    '',
+    `#### ${taskScope.label || '任务过程中涉及的文件'}`,
+    `- 口径说明：${taskScope.explanation || '汇总任务完成事件中记录的文件。'}`,
+    `- 文件数：${formatValue(taskScope.count)}`,
+    `- 文件清单：${Array.isArray(taskScope.files) ? (taskScope.files.join(', ') || '无') : '暂无数据'}`,
+    `- 来源：${formatValue(taskScope.source)}；任务：${(taskScope.task_ids || []).join(', ') || '未记录'}；最新记录时间：${formatValue(taskScope.latest_at)}`,
+  );
+  if ((taskScope.no_file_change_reasons || []).length > 0) {
+    for (const item of taskScope.no_file_change_reasons) {
+      lines.push(`- 未改文件说明：${item.task_id || '未标识任务'}：${item.reason || item}`);
+    }
+  }
+  lines.push(
+    '',
+    `#### ${finalScope.label || '最终实际交付的文件'}`,
+    `- 口径说明：${finalScope.explanation || '读取最后一次输出快照。'}`,
+    `- 文件数：${formatValue(finalScope.count)}`,
+    `- 文件清单：${Array.isArray(finalScope.files) ? (finalScope.files.join(', ') || '无') : '暂无数据'}`,
+    `- 来源：${formatValue(finalScope.source)}；事件：${formatValue(finalScope.event_id)}；快照时间：${formatValue(finalScope.captured_at)}`,
+    `- 未产生交付文件的原因：${formatValue(finalScope.no_output_reason)}`,
+    `- 行数统计说明：${finalScope.line_statistics_explanation || '未记录'}`,
+  );
   if ((changed.only_in_task_events || []).length > 0) {
     lines.push(`- 仅任务事件：${changed.only_in_task_events.join(', ')}`);
   }
@@ -237,12 +356,6 @@ function renderSectionArtifacts(section, report) {
     `- 迁移文件数：${Array.isArray(copied) ? copied.length : 'null'}`,
   );
   lines.push(
-    '',
-    '### 归因审计',
-    `- 显式关联历史事件：${section.attribution_summary?.linked_source_event_count ?? 0}`,
-    `- 有效关联：${section.attribution_summary?.active_link_count ?? 0}`,
-    `- 未归属候选：${section.attribution_summary?.unassigned_candidate_count ?? 0}`,
-    `- 被拒绝的跨变更碰撞：${section.attribution_summary?.rejected_collision_count ?? 0}`,
     '',
     '### 归档结果',
     `- 归档原因：${archive?.reason || 'null'}`,
@@ -261,15 +374,20 @@ function renderSectionArtifacts(section, report) {
 }
 
 function renderChangeReportMarkdown(report) {
-  const view = buildChangeReportViewModel(report);
+  if (!report.change_summary || !report.artifacts?.files || !report.metric_details) {
+    report = buildChangeReportModel(report);
+  }
   const projectLabel = report.project_root
     ? String(report.project_root).replace(/[\\/]+$/, '').split(/[\\/]/).pop()
     : null;
+  const view = sanitizeMarkdownValue(buildChangeReportViewModel(report));
+  report = sanitizeMarkdownValue(report);
+  const safeProjectLabel = projectLabel ? escapeMarkdownText(projectLabel) : null;
   const lines = [
     `# SDD 效果度量报告${view.change ? ` - ${view.change}` : ''}`,
     '',
     `- 生成时间：${report.generated_at || '未知'}`,
-    ...(projectLabel ? [`- 项目路径：${projectLabel}`] : []),
+    ...(safeProjectLabel ? [`- 项目路径：${safeProjectLabel}`] : []),
     `- 统计范围：change/${view.change || 'unknown'}`,
     `- 报告 Schema：${view.schema_version || 'unknown'}（指标契约 ${view.metrics_contract || 'unknown'}）`,
     `<!-- sdd-semantic-digest:${view.semantic_digest} -->`,