@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/core/code-flow/scripts/codeflow/acceptance/cf_traceability.py

@@ -0,0 +1,502 @@
+#!/usr/bin/env python3
+"""Generate the requirement traceability matrix from design §2.5 + manifest.
+
+The matrix is a derived view, never hand-edited: every design scenario is joined
+with its manifest scenario/check so priority, exec mode, env, inputs, command,
+owner and status all come from data. A scenario without a check is only allowed
+when it is explicitly marked ``aspirational``.
+"""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import re
+import sys
+from typing import IO, Mapping, Optional, Sequence
+
+if __package__ in (None, ""):
+    sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from codeflow.acceptance.cf_acceptance_schema import EXEC_MODES, load_manifest, scenario_check_ids
+from codeflow.core.cf_markdown import column_index, is_separator_row, table_cells
+
+
+_SCENARIO_ID_RE = re.compile(r"^[SEB]-\d+$")
+
+
+@dataclass(frozen=True)
+class DesignScenario:
+    """One scenario declared in design §2.5, independent of the manifest."""
+
+    id: str
+    feature: str
+    priority: str
+    level: str
+    boundary: str
+    exec: str
+    env: str
+    inputs: str
+
+
+def _acceptance_section(text: str) -> str:
+    match = re.search(r"(?m)^(#{2,4})\s+2\.5(?:\s+[^\n]*)?$", text)
+    if match is None:
+        raise ValueError("design §2.5 验收条件缺失")
+    level = len(match.group(1))
+    tail = text[match.end():]
+    end = re.search(rf"(?m)^#{{1,{level}}}\s+", tail)
+    return tail[:end.start()] if end else tail
+
+
+def _table_blocks(text: str) -> list[tuple[list[str], list[list[str]]]]:
+    blocks: list[tuple[list[str], list[list[str]]]] = []
+    header: Optional[list[str]] = None
+    rows: list[list[str]] = []
+    for line in text.splitlines():
+        cells = table_cells(line)
+        if cells:
+            if is_separator_row(cells):
+                continue
+            if header is None:
+                header = list(cells)
+            else:
+                rows.append(list(cells))
+            continue
+        if header is not None:
+            blocks.append((header, rows))
+            header, rows = None, []
+    if header is not None:
+        blocks.append((header, rows))
+    return blocks
+
+
+def _cell(row: Sequence[str], index: int) -> str:
+    return row[index].strip() if 0 <= index < len(row) else ""
+
+
+def _design_exec(value: str, scenario_id: str) -> str:
+    text = value.strip().strip("`")
+    if not text or text in {"-", "N/A"}:
+        return ""
+    normalized = text.lower()
+    if normalized not in EXEC_MODES:
+        raise ValueError(f"{scenario_id} 执行方式非法: {value}（允许 {', '.join(EXEC_MODES)}）")
+    return normalized
+
+
+def _require_full_design_scenarios(text: str) -> None:
+    """Only complete legacy definitions can substitute for a missing source."""
+    references = False
+    for header, rows in _table_blocks(text):
+        column = column_index(header, "场景id", "场景编号")
+        if column < 0 or not any(_SCENARIO_ID_RE.match(_cell(row, column)) for row in rows):
+            continue
+        if column_index(header, "测试层级") >= 0:
+            return
+        references = True
+    if references:
+        raise ValueError("scenario_source_missing: reference-only design requires the original .scenarios.md; "
+                         "restore the scenario source before audit")
+
+
+def parse_design_scenarios(design_file: str) -> tuple[DesignScenario, ...]:
+    """Parse all S-/E-/B- rows under design §2.5 tables."""
+    try:
+        text = Path(design_file).read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise ValueError(f"design_read_error: {exc}") from exc
+    _require_full_design_scenarios(text)
+    section = _acceptance_section(text)
+    scenarios: dict[str, DesignScenario] = {}
+    for header, rows in _table_blocks(section):
+        id_index = column_index(header, "场景id", "场景编号")
+        level_index = column_index(header, "测试层级")
+        if id_index == -1 or level_index == -1:
+            continue
+        feature_index = column_index(header, "功能id", "feature")
+        priority_index = column_index(header, "优先级", "priority")
+        boundary_index = column_index(header, "关键真实边界", "真实边界")
+        exec_index = column_index(header, "执行方式", "exec")
+        env_index = column_index(header, "环境", "env")
+        inputs_index = column_index(header, "输入", "inputs")
+        for row in rows:
+            scenario_id = _cell(row, id_index)
+            if not _SCENARIO_ID_RE.match(scenario_id):
+                continue
+            if scenario_id in scenarios:
+                raise ValueError(f"duplicate design scenario id: {scenario_id}")
+            scenarios[scenario_id] = DesignScenario(
+                id=scenario_id,
+                feature=_cell(row, feature_index),
+                priority=_cell(row, priority_index).upper(),
+                level=_cell(row, level_index),
+                boundary=_cell(row, boundary_index),
+                exec=_design_exec(_cell(row, exec_index), scenario_id),
+                env=_cell(row, env_index),
+                inputs=_cell(row, inputs_index),
+            )
+    if not scenarios:
+        raise ValueError("design §2.5 未找到 S-/E-/B- 场景")
+    return tuple(scenarios.values())
+
+
+def _load_manifest(manifest_file: str) -> tuple[Mapping[str, object], dict[str, Mapping[str, object]],
+                                                dict[str, Mapping[str, object]]]:
+    try:
+        data = load_manifest(Path(manifest_file))
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        raise ValueError(f"manifest_read_error: {exc}") from exc
+    scenarios = {
+        str(item["id"]): item
+        for item in data.get("scenarios") or ()
+        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
+    }
+    checks = {
+        str(item["id"]): item
+        for item in data.get("checks") or ()
+        if isinstance(item, Mapping) and isinstance(item.get("id"), str)
+    }
+    return data, scenarios, checks
+
+
+def _design_inputs(value: str) -> list[str]:
+    text = (value or "").strip()
+    if not text or text in {"-", "none", "N/A"}:
+        return []
+    return [item.strip() for item in re.split(r"[,，、;；]", text) if item.strip()]
+
+
+def _binding(scenario: Mapping[str, object], check: Optional[Mapping[str, object]],
+             design: DesignScenario) -> tuple[str, str, str]:
+    check_id = next(iter(scenario_check_ids(scenario)), "")
+    exec_mode = str(scenario.get("exec") or design.exec or "")
+    if isinstance(check_id, str) and check_id and check is not None:
+        return "check", check_id, exec_mode or "auto"
+    if exec_mode == "aspirational":
+        return "aspirational", "-", exec_mode
+    return "unbound", "-", exec_mode
+
+
+def _row(design: DesignScenario, scenario: Optional[Mapping[str, object]],
+         check: Optional[Mapping[str, object]]) -> dict[str, object]:
+    if scenario is None:
+        return {
+            "id": design.id,
+            "feature": design.feature,
+            "priority": design.priority,
+            "level": design.level,
+            "boundary": design.boundary,
+            "exec": design.exec,
+            "env": design.env or "none",
+            "inputs": _design_inputs(design.inputs),
+            "check": "-",
+            "command": [],
+            "owner": "",
+            "status": "missing",
+            "binding": "missing",
+            "in_design": True,
+        }
+    binding, check_id, exec_mode = _binding(scenario, check, design)
+    command = check.get("command") if check else scenario.get("command")
+    inputs = check.get("inputs") if check else scenario.get("inputs") or _design_inputs(design.inputs)
+    return {
+        "id": design.id,
+        "feature": design.feature,
+        "priority": str(scenario.get("priority") or design.priority),
+        "level": str(scenario.get("level") or design.level),
+        "boundary": str(scenario.get("boundary") or design.boundary),
+        "exec": exec_mode or ("auto" if binding == "check" else ""),
+        "env": str(check.get("env", "none")) if check else str(scenario.get("env") or design.env or "none"),
+        "inputs": list(inputs) if isinstance(inputs, list) else _design_inputs(str(inputs or "")),
+        "check": check_id,
+        "checks": scenario_check_ids(scenario),
+        "command": list(command) if isinstance(command, list) else [],
+        "owner": str(scenario.get("owner") or ""),
+        "status": str(scenario.get("status") or ("aspirational" if binding == "aspirational" else "")),
+        "binding": binding,
+        "in_design": True,
+    }
+
+
+def _extra_rows(manifest_scenarios: Mapping[str, Mapping[str, object]],
+                checks: Mapping[str, Mapping[str, object]], design_ids: set[str]) -> list[dict[str, object]]:
+    rows: list[dict[str, object]] = []
+    for scenario_id in sorted(set(manifest_scenarios) - design_ids):
+        scenario = manifest_scenarios[scenario_id]
+        check_id = next(iter(scenario_check_ids(scenario)), "")
+        check = checks.get(check_id) if isinstance(check_id, str) else None
+        exec_mode = str(scenario.get("exec") or "")
+        binding = "check" if check is not None else ("aspirational" if exec_mode == "aspirational" else "unbound")
+        command = check.get("command") if check else scenario.get("command")
+        rows.append({
+            "id": scenario_id,
+            "feature": "",
+            "priority": str(scenario.get("priority") or ""),
+            "level": str(scenario.get("level") or ""),
+            "boundary": str(scenario.get("boundary") or ""),
+            "exec": exec_mode,
+            "env": str(check.get("env", "none")) if check else str(scenario.get("env") or "none"),
+            "inputs": list(check.get("inputs") or []) if check else list(scenario.get("inputs") or []),
+            "check": check_id if isinstance(check_id, str) and check is not None else "-",
+            "checks": scenario_check_ids(scenario),
+            "command": list(command) if isinstance(command, list) else [],
+            "owner": str(scenario.get("owner") or ""),
+            "status": str(scenario.get("status") or ""),
+            "binding": binding,
+            "in_design": False,
+        })
+    return rows
+
+
+def _extra_violations(rows: Sequence[Mapping[str, object]]) -> list[dict[str, str]]:
+    violations: list[dict[str, str]] = []
+    for row in rows:
+        violations.append({
+            "code": "extra_in_manifest",
+            "scenario": str(row["id"]),
+            "message": f"{row['id']} 存在于 manifest，但 design §2.5 未声明；请回填设计或移除场景。",
+        })
+        if row["binding"] == "unbound":
+            violations.append({
+                "code": "unbound_scenario",
+                "scenario": str(row["id"]),
+                "message": f"{row['id']} 没有可执行 check，且未显式标为 aspirational。",
+            })
+    return violations
+
+
+def _traceability_rows(
+    design: Sequence[DesignScenario], manifest_file: str, design_label: str
+) -> dict[str, object]:
+    _, manifest_scenarios, checks = _load_manifest(manifest_file)
+    design_ids = {item.id for item in design}
+    violations: list[dict[str, str]] = []
+    rows: list[dict[str, object]] = []
+    for item in design:
+        scenario = manifest_scenarios.get(item.id)
+        check_id = next(iter(scenario_check_ids(scenario)), "") if scenario is not None else None
+        check = checks.get(check_id) if isinstance(check_id, str) else None
+        row = _row(item, scenario, check)
+        rows.append(row)
+        if scenario is None:
+            violations.append({
+                "code": "missing_in_manifest",
+                "scenario": item.id,
+                "message": f"{item.id} 在 design §2.5 中声明，但未进入 manifest；请 plan 覆盖该场景。",
+            })
+        elif row["binding"] == "unbound":
+            violations.append({
+                "code": "unbound_scenario",
+                "scenario": item.id,
+                "message": (
+                    f"{item.id} 没有可执行 check，且未显式标为 aspirational；"
+                    "请登记执行命令或把执行方式改为 aspirational。"
+                ),
+            })
+    extras = _extra_rows(manifest_scenarios, checks, design_ids)
+    violations.extend(_extra_violations(extras))
+    all_rows = rows + extras
+    summary = {
+        "design_scenarios": len(design),
+        "manifest_scenarios": len(manifest_scenarios),
+        "bound": sum(1 for row in all_rows if row["binding"] == "check"),
+        "aspirational": sum(1 for row in all_rows if row["binding"] == "aspirational"),
+        "unbound": sum(1 for row in all_rows if row["binding"] == "unbound"),
+        "missing": sum(1 for row in all_rows if row["binding"] == "missing"),
+    }
+    return {
+        "decision": "block" if violations else "pass",
+        "generated": True,
+        "design_file": design_label,
+        "manifest_file": str(manifest_file),
+        "summary": summary,
+        "scenarios": all_rows,
+        "violations": violations,
+    }
+
+
+def build_traceability(design_file: str, manifest_file: str) -> dict[str, object]:
+    """Join design §2.5 scenarios with manifest checks and report binding gaps."""
+    return _traceability_rows(parse_design_scenarios(design_file), manifest_file, str(design_file))
+
+
+def merge_design_scenarios(design_files: Sequence[str]) -> tuple[DesignScenario, ...]:
+    """Merge frontend/backend design scenarios by global ID; conflicts fail closed."""
+    merged: dict[str, DesignScenario] = {}
+    for design_file in design_files:
+        for item in parse_design_scenarios(design_file):
+            previous = merged.get(item.id)
+            if previous is not None and previous != item:
+                raise ValueError(f"duplicate design scenario id with conflicting definition: {item.id}")
+            merged[item.id] = item
+    if not merged:
+        raise ValueError("design §2.5 未找到 S-/E-/B- 场景")
+    return tuple(merged.values())
+
+
+def build_traceability_many(design_files: Sequence[str], manifest_file: str) -> dict[str, object]:
+    """0.8 fallback: merge multiple design docs before joining the manifest."""
+    design = merge_design_scenarios(design_files)
+    return _traceability_rows(design, manifest_file, ", ".join(str(item) for item in design_files))
+
+
+def _md(value: object) -> str:
+    text = "" if value is None else str(value)
+    if not text:
+        return "-"
+    return text.replace("|", "\\|").replace("\n", " ")
+
+
+def _md_inputs(value: object) -> str:
+    if isinstance(value, list):
+        return _md(", ".join(str(item) for item in value))
+    return _md(value)
+
+
+def _md_command(value: object) -> str:
+    if isinstance(value, list):
+        return _md(json.dumps(value, ensure_ascii=False))
+    return _md(value)
+
+
+def render_markdown(report: Mapping[str, object]) -> str:
+    """Render the generated matrix; input is always build_traceability output."""
+    summary = report.get("summary") if isinstance(report.get("summary"), Mapping) else {}
+    lines = [
+        "> 由 `cf_traceability.py` 从 design §2.5 + manifest 生成，不手工维护。",
+        ">",
+        (
+            f"> 场景 {summary.get('design_scenarios', 0)} / 绑定 check {summary.get('bound', 0)}"
+            f" / aspirational {summary.get('aspirational', 0)}"
+            f" / 未绑定 {summary.get('unbound', 0)} / 缺失 {summary.get('missing', 0)}"
+        ),
+        "",
+        "| 场景ID | 优先级 | 测试层级 | 执行方式 | 环境 | 输入 | 追溯 check | 执行命令 | 负责任务 | 状态 |",
+        "|--------|--------|---------|---------|------|------|-----------|---------|---------|------|",
+    ]
+    for row in report.get("scenarios") or ():
+        if not isinstance(row, Mapping):
+            continue
+        lines.append(
+            "| {id} | {priority} | {level} | {exec} | {env} | {inputs} | {check} | {command} | {owner} | {status} |".format(
+                id=_md(row.get("id")),
+                priority=_md(row.get("priority")),
+                level=_md(row.get("level")),
+                exec=_md(row.get("exec")),
+                env=_md(row.get("env")),
+                inputs=_md_inputs(row.get("inputs")),
+                check=_md(row.get("check")),
+                command=_md_command(row.get("command")),
+                owner=_md(row.get("owner")),
+                status=_md(row.get("status")),
+            )
+        )
+    if report.get("violations"):
+        lines.extend(["", "**阻断项**", ""])
+        for violation in report["violations"]:
+            if isinstance(violation, Mapping):
+                lines.append(f"- `{violation.get('code')}` {violation.get('scenario')}: {violation.get('message')}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
+    parser = argparse.ArgumentParser(prog="cf_traceability.py")
+    parser.add_argument("--design", required=True)
+    parser.add_argument("--manifest", required=True)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        report = build_traceability(args.design, args.manifest)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        stdout.write(json.dumps({"decision": "block", "error": str(exc)}, ensure_ascii=False))
+        return 2
+    if args.json:
+        stdout.write(json.dumps(report, ensure_ascii=False))
+    else:
+        stdout.write(render_markdown(report))
+    return 0 if report["decision"] == "pass" else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+def build_traceability_from_scenarios(scenarios_file: str, manifest_file: str) -> dict[str, object]:
+    """Join the scenario source with manifest checks (0.9 source model)."""
+    from codeflow.acceptance.cf_scenario_source import parse_scenarios
+    source = parse_scenarios(scenarios_file)
+    manifest_scenarios, checks = _load_manifest(manifest_file)[1:]
+    source_ids = {str(item["id"]) for item in source["scenarios"]}
+    violations: list[dict[str, str]] = []
+    rows: list[dict[str, object]] = []
+    for item in source["scenarios"]:
+        scenario_id = str(item["id"])
+        row = manifest_scenarios.get(scenario_id)
+        required = [str(value) for value in item.get("checks", [])] or (
+            [str(row.get("check"))] if row is not None and isinstance(row.get("check"), str) else []
+        )
+        check_id = required[0] if required else None
+        check = checks.get(check_id) if check_id else None
+        missing_checks = [value for value in required if value not in checks]
+        exec_mode = str(item.get("exec") or "")
+        if row is None:
+            binding, status = "missing", "missing"
+            violations.append({"code": "missing_in_manifest", "scenario": scenario_id,
+                               "message": f"{scenario_id} 在场景源中声明，但未进入 manifest"})
+        elif missing_checks:
+            binding, status = "unbound", str(row.get("status") or "planned")
+            violations.append({"code": "missing_check", "scenario": scenario_id,
+                               "message": f"{scenario_id} 引用了不存在的 check: {', '.join(missing_checks)}"})
+        elif required and all(value in checks for value in required):
+            binding, status = "check", str(row.get("status") or "planned")
+        elif exec_mode == "aspirational":
+            binding, status = "aspirational", "aspirational"
+        else:
+            binding, status = "unbound", str(row.get("status") or "planned")
+            violations.append({"code": "unbound_scenario", "scenario": scenario_id,
+                               "message": f"{scenario_id} 没有可执行 check，且未显式 aspirational"})
+        rows.append({
+            "id": scenario_id,
+            "feature": "",
+            "priority": str(item.get("priority") or ""),
+            "level": str(item.get("level") or ""),
+            "boundary": str(item.get("boundary") or ""),
+            "exec": exec_mode,
+            "env": str(check.get("env", "none")) if check else str(item.get("env") or "none"),
+            "inputs": list(check.get("inputs") or []) if check else [],
+            "check": check_id if isinstance(check_id, str) and check is not None else "-",
+            "command": list(check.get("command") or []) if check else [],
+            "owner": str(row.get("owner") or "") if row else "",
+            "status": status,
+            "binding": binding,
+            "in_design": False,
+        })
+    extras = _extra_rows(manifest_scenarios, checks, source_ids)
+    for row in extras:
+        violations.append({"code": "extra_in_manifest", "scenario": str(row["id"]),
+                           "message": f"{row['id']} 存在于 manifest，但场景源未声明"})
+        if row["binding"] == "unbound":
+            violations.append({"code": "unbound_scenario", "scenario": str(row["id"]),
+                               "message": f"{row['id']} 没有可执行 check，且未显式 aspirational"})
+    all_rows = rows + extras
+    summary = {
+        "design_scenarios": len(source["scenarios"]),
+        "manifest_scenarios": len(manifest_scenarios),
+        "bound": sum(1 for row in all_rows if row["binding"] == "check"),
+        "aspirational": sum(1 for row in all_rows if row["binding"] == "aspirational"),
+        "unbound": sum(1 for row in all_rows if row["binding"] == "unbound"),
+        "missing": sum(1 for row in all_rows if row["binding"] == "missing"),
+    }
+    return {
+        "decision": "block" if violations else "pass",
+        "generated": True,
+        "source": str(scenarios_file),
+        "design_file": str(scenarios_file),
+        "manifest_file": str(manifest_file),
+        "summary": summary,
+        "scenarios": all_rows,
+        "violations": violations,
+    }