kld-sdd 2.6.13 → 2.6.15

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

@@ -0,0 +1,452 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+let formatArtifactSize;
+try {
+  ({ formatArtifactSize } = require('../metrics-v3.cjs'));
+} catch {
+  formatArtifactSize = null;
+}
+
+function formatArtifactSizeDisplay(bytes) {
+  if (typeof formatArtifactSize === 'function') return formatArtifactSize(bytes);
+  const n = Number(bytes);
+  if (!Number.isFinite(n) || n < 0) return '0.00 KB';
+  const mib = 1024 * 1024;
+  if (n < mib) return `${(n / 1024).toFixed(2)} KB`;
+  return `${(n / mib).toFixed(2)} MB`;
+}
+
+const EVIDENCE_LABELS = {
+  TASK_UPDATE_MISSING: '任务状态事件缺失',
+  TASK_TEST_EVIDENCE_MISSING: '任务验证证据缺失',
+  TASK_TEST_LINKAGE_DEFECT: '任务测试链接缺陷',
+  TDD_RED_GREEN_INCOMPLETE: 'TDD 红绿链路不完整',
+  TDD_PAIR_RED_DID_NOT_FAIL: 'TDD RED 未有效失败',
+  TDD_PAIR_RED_MISSING: 'TDD RED 证据缺失',
+  TDD_PAIR_GREEN_MISSING: 'TDD GREEN 证据缺失',
+  TDD_PAIR_UNCLASSIFIED: 'TDD 对证据不可判定',
+  LEGACY_TASK_PARSER: '任务文档仍使用旧格式',
+  apply_test_missing: '实现阶段缺少测试证据',
+  tdd_red_missing: 'TDD 缺少有效失败测试',
+  process_note_missing: '过程说明缺失',
+  task_update_reuse: '测试结果被重复引用',
+};
+
+function eventTimestamp(event) {
+  const raw = event?.timestamp || event?.ended_at || event?.started_at;
+  const value = Date.parse(raw || '');
+  return Number.isFinite(value) ? value : 0;
+}
+
+function scopedEventsForChange(events = [], change = null) {
+  if (!change) return events;
+  return events.filter((event) => (
+    event?.change === change
+    || event?.attribution?.target_change === change
+  ));
+}
+
+function extractFinalTestResult(events = [], fallback = null, change = null) {
+  const testEvents = scopedEventsForChange(events, change)
+    .filter((event) => event?.type === 'test_result')
+    .sort((a, b) => eventTimestamp(b) - eventTimestamp(a));
+  const candidates = testEvents
+    .filter((event) => {
+      if (event?.type !== 'test_result') return false;
+      const result = event.details?.test_results || {};
+      return result.evidence_tier === 'strict'
+        && ['green', 'refactor', 'regression'].includes(result.tdd_phase)
+        && result.counts_known === true;
+    });
+  const event = candidates.find(item => item.details?.test_results?.snapshot_kind === 'final')
+    || candidates[0];
+  const history = testEvents
+    .filter(item => item !== event)
+    .map(item => ({
+      event_id: item.event_id || null,
+      timestamp: item.timestamp || null,
+      passed: Number.isFinite(Number(item.details?.test_results?.passed))
+        ? Number(item.details.test_results.passed)
+        : null,
+      failed: Number.isFinite(Number(item.details?.test_results?.failed))
+        ? Number(item.details.test_results.failed)
+        : null,
+      snapshot_kind: item.details?.test_results?.snapshot_kind || 'unspecified',
+      evidence_tier: item.details?.test_results?.evidence_tier || 'legacy',
+    }));
+  if (!event) {
+    return fallback || {
+      passed: null,
+      failed: null,
+      total: null,
+      status: 'unavailable',
+      source_event_id: null,
+      source: 'unavailable',
+      history,
+    };
+  }
+  const result = event.details.test_results;
+  const passed = Number(result.passed);
+  const failed = Number(result.failed);
+  const skipped = Number(result.skipped || 0);
+  return {
+    passed,
+    failed,
+    skipped,
+    total: passed + failed + skipped,
+    status: result.result === 'success' && failed === 0 ? 'passed' : 'failed',
+    source_event_id: event.event_id || null,
+    source: 'strict-test-result',
+    snapshot_kind: result.snapshot_kind || 'unspecified',
+    history,
+  };
+}
+
+function normalizeTaskSummary(report) {
+  const completion = report.archive_result?.task_completion || {};
+  const primary = completion.primary_tasks || {};
+  const taskEvidence = report.task_evidence_audit || {};
+  const documentTotal = taskEvidence.document_completion?.total
+    ?? primary.total
+    ?? completion.total
+    ?? null;
+  const documentCompleted = taskEvidence.document_completion?.completed
+    ?? primary.completed
+    ?? completion.completed
+    ?? null;
+  const audit = report.apply_evidence_audit || {};
+  const auditTasks = audit.tasks || audit.summary || {};
+  const traceabilityVerified = taskEvidence.strict_test_coverage?.verified
+    ?? auditTasks.with_test_evidence
+    ?? auditTasks.verified
+    ?? null;
+  const traceabilityTotal = taskEvidence.strict_test_coverage?.total
+    ?? auditTasks.completed
+    ?? auditTasks.total
+    ?? documentTotal;
+  return {
+    document: {
+      completed: documentCompleted,
+      total: documentTotal,
+      status: documentTotal == null
+        ? 'unavailable'
+        : (documentCompleted === documentTotal ? 'complete' : 'incomplete'),
+      source: 'tasks-document',
+    },
+    direct_test_backlink: taskEvidence.direct_test_backlink || null,
+    strict_test_coverage: taskEvidence.strict_test_coverage || null,
+    traceability: {
+      verified: traceabilityVerified,
+      total: traceabilityTotal,
+      status: traceabilityTotal == null || traceabilityVerified == null
+        ? 'unavailable'
+        : (traceabilityVerified === traceabilityTotal ? 'complete' : 'incomplete'),
+      source: 'strict-event-audit',
+    },
+  };
+}
+
+function issueGuidance(code) {
+  return ({
+    TASK_UPDATE_MISSING: {
+      expected: '已完成任务应有对应的 completed task_update 事件。',
+      root_cause: '任务文档状态与结构化事件没有同步。',
+      impact: '任务完成状态不能被事件链直接验证。',
+      remediation: '补录真实 task_update；若历史证据不存在，明确标记不可追溯。',
+    },
+    TASK_TEST_LINKAGE_DEFECT: {
+      expected: 'task_update 应直接引用覆盖当前任务的 strict 成功测试。',
+      root_cause: 'test_event_id 缺失、无效或没有覆盖当前任务。',
+      impact: '测试存在，但任务到测试的直接审计链不完整。',
+      remediation: '将 task_update 精确关联到覆盖当前任务的 strict 测试事件。',
+    },
+    TASK_TEST_EVIDENCE_MISSING: {
+      expected: '任务应有严格成功测试，或有可审计的不适用理由。',
+      root_cause: '没有找到直接引用、间接严格覆盖或有效豁免。',
+      impact: '无法验证任务完成状态是否经过测试。',
+      remediation: '执行并记录覆盖测试；确实不适用时填写具体原因。',
+    },
+    TDD_RED_GREEN_INCOMPLETE: {
+      expected: 'TDD 证据应按 pair 形成有效 RED→GREEN 顺序。',
+      root_cause: '旧版逐任务算法无法正确表达成对 TDD 证据。',
+      impact: '可能把已有配对证据误报为缺失。',
+      remediation: '使用 pair 级审计结果，不再生成逐任务 TDD 告警。',
+    },
+  }[code] || {
+    expected: '相关规则所要求的证据应完整且可定位。',
+    root_cause: '当前事件或文档证据未满足该规则。',
+    impact: '对应结论的可信度会降低。',
+    remediation: '根据规则编码定位证据源，补充或纠正真实记录。',
+  });
+}
+
+function normalizeIssue(alert, index) {
+  const code = alert.warning || alert.code || 'UNKNOWN';
+  const guidance = issueGuidance(code);
+  const eventIds = [...new Set([
+    alert.opened_by_event_id,
+    alert.last_seen_event_id,
+    alert.resolved_by_event_id,
+    alert.evidence_event_id,
+    ...(Array.isArray(alert.evidence_event_ids) ? alert.evidence_event_ids : []),
+  ].filter(Boolean))];
+  const subject = alert.subject || alert.task_id || alert.pair_id || null;
+  const status = alert.status
+    || (['fixed', 'accepted', 'waived'].includes(alert.disposition) ? 'resolved' : 'open');
+  return {
+    issue_id: alert.issue_id || alert.key || `${code}:${subject || 'change'}:${index + 1}`,
+    category: alert.category || 'evidence',
+    code,
+    label: EVIDENCE_LABELS[code] || code,
+    severity: alert.severity || 'warning',
+    verdict: alert.verdict || (status === 'resolved' ? 'resolved' : 'evidence-gap'),
+    status,
+    subject,
+    task_id: alert.task_id || null,
+    pair_id: alert.pair_id || null,
+    expected: alert.expected || guidance.expected,
+    actual: alert.actual || alert.message || alert.reason || '当前证据未满足规则要求。',
+    root_cause: alert.root_cause || guidance.root_cause,
+    impact: alert.impact || guidance.impact,
+    remediation: alert.remediation || guidance.remediation,
+    evidence_event_ids: eventIds,
+    related_event_ids: Array.isArray(alert.related_event_ids) ? alert.related_event_ids : [],
+    disposition: alert.disposition || (status === 'resolved' ? 'fixed' : 'open'),
+    occurrence_count: Math.max(1, Number(alert.occurrences) || 1),
+    history: {
+      first_seen_at: alert.first_seen_at || null,
+      last_seen_at: alert.last_seen_at || null,
+      resolved_at: alert.resolved_at || null,
+    },
+  };
+}
+
+function normalizeEvidenceSummary(report) {
+  const alerts = report.evidence_alerts || {};
+  const alertHistory = Array.isArray(alerts.history) && alerts.history.length > 0
+    ? alerts.history
+    : [...(alerts.open || []), ...(alerts.resolved || [])];
+  const history = [
+    ...alertHistory,
+    ...(report.check_warning_dispositions || []).map(item => ({
+      ...item,
+      code: item.warning,
+      occurrences: 1,
+      status: ['fixed', 'accepted', 'waived'].includes(item.disposition) ? 'resolved' : 'open',
+      last_seen_event_id: item.evidence_event_id,
+    })),
+  ];
+  const issues = history.map(normalizeIssue);
+  const groups = new Map();
+  for (const issue of issues) {
+    const code = issue.code;
+    if (!groups.has(code)) {
+      groups.set(code, {
+        code,
+        label: EVIDENCE_LABELS[code] || code,
+        occurrence_count: 0,
+        affected_tasks: [],
+        event_ids: [],
+        dispositions: {},
+        issues: [],
+      });
+    }
+    const group = groups.get(code);
+    group.occurrence_count += issue.occurrence_count;
+    group.issues.push(issue);
+    const task = issue.task_id || issue.subject;
+    if (task && !group.affected_tasks.includes(task)) group.affected_tasks.push(task);
+    for (const eventId of issue.evidence_event_ids) {
+      if (eventId && !group.event_ids.includes(eventId)) group.event_ids.push(eventId);
+    }
+    const disposition = issue.disposition;
+    group.dispositions[disposition] = (group.dispositions[disposition] || 0) + 1;
+  }
+  const categories = [...groups.values()];
+  return {
+    category_count: categories.length,
+    occurrence_count: categories.reduce((sum, item) => sum + item.occurrence_count, 0),
+    categories,
+    issues,
+    note: '一次任务或事件可能同时命中多条规则；命中次数不等于独立缺陷数。',
+  };
+}
+
+function normalizeChangedFiles(changedFiles = {}) {
+  const taskEventFiles = Array.isArray(changedFiles.task_event_files)
+    ? [...new Set(changedFiles.task_event_files)]
+    : null;
+  const finalOutputFiles = Array.isArray(changedFiles.final_output_files)
+    ? [...new Set(changedFiles.final_output_files)]
+    : (Array.isArray(changedFiles.files) ? [...new Set(changedFiles.files)] : null);
+  const taskCount = changedFiles.task_event_files_changed
+    ?? changedFiles.files_changed
+    ?? taskEventFiles?.length
+    ?? null;
+  const finalCount = changedFiles.final_output_files_changed
+    ?? finalOutputFiles?.length
+    ?? null;
+  const countsDiffer = taskCount != null && finalCount != null && taskCount !== finalCount;
+  const normalized = {
+    ...changedFiles,
+    task_event_files: taskEventFiles,
+    task_event_files_changed: taskCount,
+    final_output_files: finalOutputFiles,
+    final_output_files_changed: finalCount,
+    diff_source: changedFiles.diff_source || 'dual-source',
+    line_count_estimate: changedFiles.line_count_estimate ?? null,
+    reconciliation_status: changedFiles.reconciliation_status
+      || (countsDiffer ? 'count-mismatch' : 'consistent'),
+    reconciliation_note: changedFiles.reconciliation_note
+      || (countsDiffer
+        ? `任务事件累计涉及 ${taskCount} 个文件；最终输出快照包含 ${finalCount} 个文件。两者用途不同，不应合并为一个口径。`
+        : '任务事件与最终输出文件口径一致。'),
+  };
+  // v4：不再对外输出 legacy_fields；若调用方传入则显式剔除
+  delete normalized.legacy_fields;
+  return normalized;
+}
+
+function resolveArtifact(projectRoot, artifactPath, options = {}) {
+  if (!artifactPath) return { path: null, exists: false, size_bytes: null, size_display: null, sha256: null };
+  const absolute = path.isAbsolute(artifactPath)
+    ? artifactPath
+    : path.resolve(projectRoot || process.cwd(), artifactPath);
+  try {
+    const stat = fs.statSync(absolute);
+    if (!stat.isFile()) {
+      return { path: artifactPath, exists: false, size_bytes: null, size_display: null, sha256: null };
+    }
+    const sizeBytes = stat.size;
+    const sizeDisplay = formatArtifactSizeDisplay(sizeBytes);
+    if (options.selfReferential) {
+      return {
+        path: artifactPath,
+        exists: true,
+        size_bytes: sizeBytes,
+        size_display: sizeDisplay,
+        sha256: null,
+        integrity_note: '报告可展示自身大小；哈希不内嵌自身，请以归档 Manifest 为准',
+      };
+    }
+    const sha256 = crypto.createHash('sha256').update(fs.readFileSync(absolute)).digest('hex');
+    return {
+      path: artifactPath,
+      exists: true,
+      size_bytes: sizeBytes,
+      size_display: sizeDisplay,
+      sha256: `sha256:${sha256}`,
+    };
+  } catch {
+    return { path: artifactPath, exists: false, size_bytes: null, size_display: null, sha256: null };
+  }
+}
+
+function normalizeArtifacts(report) {
+  const archive = report.archive_result || {};
+  const existing = report.artifacts || {};
+  const projectRoot = report.project_root;
+  const paths = {
+    markdown_report: archive.report_path,
+    html_report: archive.report_html_path,
+    json_report: archive.report_json_path,
+    execution_log: archive.execution_log_path
+      || existing.execution_log_path
+      || (archive.archive_path ? path.join(archive.archive_path, 'logs', 'execution-log.md') : null),
+    manifest: archive.manifest_path || existing.manifest_path,
+    archive_zip: archive.archive_zip_path
+      || archive.zip_path
+      || archive.package_path
+      || existing.archive_zip_path
+      || existing.package_path,
+  };
+  return {
+    ...existing,
+    files: Object.fromEntries(
+      Object.entries(paths).map(([name, artifactPath]) => [
+        name,
+        resolveArtifact(projectRoot, artifactPath, {
+          selfReferential: [
+            'markdown_report',
+            'html_report',
+            'json_report',
+            'manifest',
+            'archive_zip',
+          ].includes(name),
+        }),
+      ]),
+    ),
+  };
+}
+
+function buildWarningDispositions(report) {
+  const alerts = [
+    ...(report.evidence_alerts?.open || []),
+    ...(report.evidence_alerts?.resolved || []),
+    ...(report.check_warning_dispositions || []),
+  ];
+  const allowed = new Set(['fixed', 'accepted', 'waived', 'needs_input', 'open']);
+  const checkWarnings = new Set((report.check_warning_dispositions || []).map(item => item.warning));
+  const byWarning = new Map();
+  for (const alert of alerts) {
+    const inferred = alert.status === 'resolved' ? 'fixed' : 'open';
+    const disposition = allowed.has(alert.disposition) ? alert.disposition : inferred;
+    const normalized = {
+      warning: alert.warning || alert.code || 'UNKNOWN',
+      subject: alert.subject || alert.task_id || null,
+      disposition,
+      reason: alert.disposition_reason || alert.reason || alert.message || null,
+      evidence_event_id: alert.evidence_event_id || alert.resolved_by_event_id || alert.last_seen_event_id || null,
+    };
+    if (!byWarning.has(normalized.warning) || checkWarnings.has(normalized.warning)) {
+      byWarning.set(normalized.warning, normalized);
+    }
+  }
+  return [...byWarning.values()];
+}
+
+function buildChangeReportModel(report, events = []) {
+  if (!report || report.level !== 'change' || !report.change) return report;
+  const scopedEvents = scopedEventsForChange(events, report.change);
+  const inputEventCount = Array.isArray(events) ? events.length : 0;
+  const changedFiles = normalizeChangedFiles(report.changed_files);
+  const existingSummary = report.change_summary || {};
+  const changeSummary = {
+    tests: scopedEvents.length > 0
+      ? extractFinalTestResult(scopedEvents, report.final_test_result || existingSummary.tests || null, report.change)
+      : (existingSummary.tests || extractFinalTestResult(scopedEvents, report.final_test_result || null, report.change)),
+    tasks: existingSummary.tasks || normalizeTaskSummary(report),
+    evidence: existingSummary.evidence || normalizeEvidenceSummary(report),
+  };
+  return {
+    ...report,
+    report_scope: {
+      ...(report.report_scope || {}),
+      kind: 'single-change',
+      change: report.change,
+      input_event_count: report.report_scope?.input_event_count ?? inputEventCount,
+      included_event_count: report.report_scope?.included_event_count ?? scopedEvents.length,
+      excluded_event_count: report.report_scope?.excluded_event_count
+        ?? Math.max(0, inputEventCount - scopedEvents.length),
+      cross_change_data_included: false,
+    },
+    metric_provenance: report.metric_provenance || report.metric_evidence || null,
+    change_summary: changeSummary,
+    changed_files: changedFiles,
+    warning_dispositions: buildWarningDispositions(report),
+    artifacts: normalizeArtifacts(report),
+  };
+}
+
+module.exports = {
+  EVIDENCE_LABELS,
+  buildChangeReportModel,
+  extractFinalTestResult,
+  normalizeEvidenceSummary,
+  normalizeChangedFiles,
+  formatArtifactSizeDisplay,
+};