@michaelxwb/code-flow 0.6.4 → 0.8.1

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

@@ -0,0 +1,174 @@
+"""Shared semantic checks for canonical scenarios and plan projections."""
+from __future__ import annotations
+
+import re
+from typing import Mapping, Sequence
+
+ENVIRONMENTS = ("none", "local", "local-api", "browser", "external", "staging", "capacity", "ci", "production")
+TARGET_PHASES = ("plan", "code", "review", "ci", "release")
+EXTRA_FIELDS = ("expected_refs", "expected_checks", "assertions", "defer_reason", "owner", "target_phase", "features", "tags")
+_PLACEHOLDERS = frozenset(("", "-", "n/a", "na", "none", "无", "todo", "tbd", "待定"))
+_VAGUE = re.compile(r"可观|不回归|表现良好|符合预期|适当提升|as expected|significant improvement", re.I)
+
+
+def meaningful(value: object) -> bool:
+    return str(value or "").strip().lower() not in _PLACEHOLDERS
+
+
+def issue(code: str, row: Mapping[str, object], field: str, message: str) -> dict[str, object]:
+    return {"code": code, "scenario": str(row.get("id", "")), "field": field, "message": message}
+
+
+def validate_expected_checks(row: Mapping[str, object]) -> list[dict[str, object]]:
+    """Validate explicit composition without weakening the scenario's checks."""
+    links = row.get("expected_checks")
+    expected, checks = row.get("expected", []), row.get("checks", [])
+    if not isinstance(links, list) or not links or not isinstance(expected, list) or not isinstance(checks, list):
+        raise ValueError("expected_checks 需要非空映射、expected 与 checks 列表")
+    seen: set[int] = set()
+    for link in links:
+        if not isinstance(link, Mapping):
+            raise ValueError("expected_checks 成员必须是映射")
+        index, members = link.get("expected"), link.get("checks")
+        if type(index) is not int or not 1 <= index <= len(expected) or index in seen:
+            raise ValueError("expected_checks 的 expected 索引无效或重复")
+        if (not isinstance(members, list) or not members
+                or not all(isinstance(member, str) and member in checks for member in members)
+                or len(set(members)) != len(members)):
+            raise ValueError("expected_checks 引用了无效 check")
+        seen.add(index)
+    if seen != set(range(1, len(expected) + 1)):
+        raise ValueError("expected_checks 必须覆盖所有 expected")
+    return [dict(link) for link in links]
+
+
+def validate_extensions(row: Mapping[str, object]) -> dict[str, object]:
+    env = str(row.get("env", "none")).lower()
+    if env not in ENVIRONMENTS:
+        raise ValueError(f"env 非法: {env!r}; allowed: {', '.join(ENVIRONMENTS)}")
+    result: dict[str, object] = {"env": env}
+    if "expected_checks" in row:
+        result["expected_checks"] = validate_expected_checks(row)
+    for field in ("features", "tags", "assertions"):
+        values = row.get(field, [])
+        if not isinstance(values, list) or not all(isinstance(value, str) and value.strip() for value in values):
+            raise ValueError(f"{field} 必须是非空字符串列表")
+        result[field] = list(values)
+    for component in row.get("components", []) or []:
+        if not isinstance(component, str) or not re.fullmatch(r"[a-zA-Z][a-zA-Z0-9_.:-]*", component):
+            raise ValueError("components 必须使用稳定标识符，不能使用自由描述文本")
+    refs = row.get("expected_refs", [])
+    if not isinstance(refs, list) or not all(isinstance(value, Mapping) for value in refs):
+        raise ValueError("expected_refs 必须是映射列表")
+    result["expected_refs"] = [dict(value) for value in refs]
+    for field in ("defer_reason", "owner", "target_phase"):
+        value = row.get(field, "")
+        if not isinstance(value, str):
+            raise ValueError(f"{field} 必须是字符串")
+        result[field] = value.strip()
+    if result["target_phase"] and result["target_phase"] not in TARGET_PHASES:
+        raise ValueError("target_phase 非法")
+    return result
+
+
+def browser_boundary(row: Mapping[str, object]) -> bool:
+    components = {str(value).lower() for value in row.get("components", []) or []}
+    return str(row.get("env", "")).lower() == "browser" or bool(components & {"frontend", "browser"})
+
+
+def _expected_links(row: Mapping[str, object], index: int) -> bool:
+    steps = row.get("steps", []) or []
+    for link in row.get("expected_refs", []) or []:
+        if not isinstance(link, Mapping) or type(link.get("expected")) is not int or link["expected"] != index:
+            continue
+        linked_steps = link.get("steps", [])
+        assertions = link.get("assertions", [])
+        if not isinstance(linked_steps, list) or not isinstance(assertions, list):
+            continue
+        valid_steps = linked_steps and all(type(value) is int and 1 <= value <= len(steps) for value in linked_steps)
+        declared = row.get("assertions", [])
+        valid_assertions = assertions and all(isinstance(value, str) and meaningful(value) and value in declared
+                                              for value in assertions)
+        if (valid_steps or valid_assertions) and (not linked_steps or valid_steps):
+            return True
+    return False
+
+
+def expectation_issues(row: Mapping[str, object]) -> list[dict[str, object]]:
+    errors: list[dict[str, object]] = []
+    for index, expected in enumerate(row.get("expected", []) or [], 1):
+        text = str(expected).strip()
+        if not meaningful(text) or _VAGUE.search(text):
+            errors.append(issue("scenario_expected_nondeterministic", row, "expected",
+                                f"expected[{index}] 需要具体可观察结果或量化阈值"))
+        if re.search(r"^(若|如果|if\b)", text, re.I) and not row.get("preconditions"):
+            errors.append(issue("scenario_expected_nondeterministic", row, "preconditions",
+                                "条件式预期必须声明可构造的前置条件"))
+        if not _expected_links(row, index):
+            errors.append(issue("scenario_expected_reference_missing", row, "expected_refs",
+                                f"expected[{index}] 必须引用存在的步骤或稳定断言 ID"))
+    return errors
+
+
+def deferred_issues(row: Mapping[str, object]) -> list[dict[str, object]]:
+    if row.get("exec") != "deferred":
+        return []
+    missing = [field for field in ("defer_reason", "owner", "target_phase") if not meaningful(row.get(field))]
+    return [issue("scenario_defer_metadata_missing", row, "exec", "延后信息缺少: " + ", ".join(missing))] if missing else []
+
+
+def e2e_issues(row: Mapping[str, object]) -> list[dict[str, object]]:
+    errors: list[dict[str, object]] = []
+    requirements = (("why_e2e", "e2e_justification_missing"), ("boundary", "e2e_boundary_missing"))
+    for field, code in requirements:
+        if not meaningful(row.get(field)):
+            errors.append(issue(code, row, field, "E2E 必须声明真实边界和低层测试不足的理由"))
+    for field in ("steps", "expected"):
+        if not any(meaningful(value) for value in row.get(field, []) or []):
+            errors.append(issue(f"e2e_{field}_missing", row, field, "E2E 必须声明可复现步骤及可观察结果"))
+    if str(row.get("priority", "")).upper() not in ("P0", "P1"):
+        errors.append(issue("e2e_priority_not_critical", row, "priority", "E2E 只允许 P0/P1"))
+    if not browser_boundary(row):
+        errors.append(issue("e2e_browser_boundary_missing", row, "components",
+                            "浏览器 E2E 必须声明 browser/frontend；API/CLI 全链路使用 system/integration"))
+    if browser_boundary(row) and not re.search(r"browser|frontend|浏览器|前端|\bUI\b", str(row.get("boundary", "")), re.I):
+        errors.append(issue("scenario_boundary_components_mismatch", row, "boundary",
+                            "声明的浏览器组件必须出现在真实边界中"))
+    if row.get("exec") == "aspirational":
+        errors.append(issue("e2e_aspirational", row, "exec", "aspirational 不能作为 E2E 验收"))
+    paths = row.get("trigger_paths", []) or []
+    if not row.get("smoke") and not paths:
+        errors.append(issue("e2e_trigger_paths_missing", row, "trigger_paths", "非 smoke E2E 必须声明触发路径"))
+    if any(not meaningful(value) for value in paths):
+        errors.append(issue("e2e_trigger_path_placeholder", row, "trigger_paths", "触发路径不能使用占位值"))
+    return errors
+
+
+def quality_report(scenarios: Sequence[Mapping[str, object]]) -> dict[str, object]:
+    errors: list[dict[str, object]] = []
+    warnings: list[dict[str, object]] = []
+    e2e = [row for row in scenarios if str(row.get("level", "")).lower() == "e2e"]
+    signatures: dict[str, str] = {}
+    for row in scenarios:
+        errors.extend(expectation_issues(row))
+        errors.extend(deferred_issues(row))
+        if row in e2e:
+            errors.extend(e2e_issues(row))
+            signature = repr((row.get("steps"), row.get("expected"), row.get("boundary")))
+            if signature in signatures:
+                warnings.append(issue("duplicate_e2e_journey", row, "steps", f"与 {signatures[signature]} 重复"))
+            signatures[signature] = str(row.get("id"))
+        elif meaningful(row.get("why_e2e")):
+            errors.append(issue("why_e2e_on_non_e2e", row, "why_e2e", "why_e2e 只属于浏览器 E2E"))
+    ratio = len(e2e) / len(scenarios) if scenarios else 0.0
+    smoke = sum(bool(row.get("smoke")) for row in e2e)
+    if ratio > 0.3:
+        warnings.append(issue("e2e_ratio_high", {}, "level", f"E2E 占比 {ratio:.0%}；优先下沉低层"))
+    if e2e and not smoke:
+        warnings.append(issue("e2e_smoke_missing", {}, "smoke", "没有声明 smoke E2E"))
+    return {"ok": not errors, "errors": errors, "warnings": warnings, "total": len(scenarios),
+            "e2e_count": len(e2e), "e2e_browser_count": sum(browser_boundary(row) for row in e2e),
+            "system_count": sum(row.get("level") == "system" for row in scenarios),
+            "capacity_count": sum(row.get("level") == "capacity" or "capacity" in row.get("tags", []) for row in scenarios),
+            "smoke_count": smoke, "e2e_ratio": round(ratio, 4),
+            "runnable_smoke_count": None, "verified_browser_count": None, "registration_status": "not_checked"}

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

@@ -0,0 +1,300 @@
+"""Parse and reconcile canonical requirement scenario sources."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Mapping, Optional, Sequence
+
+import yaml
+
+from codeflow.core.cf_markdown import frontmatter_block
+
+
+SCHEMA_VERSION = 1
+SCENARIO_ID = re.compile(r"^[SEB]-\d+$")
+PRIORITIES = ("P0", "P1", "P2")
+LEVELS = ("unit", "component", "contract", "integration", "system", "capacity", "e2e", "manual")
+EXEC_MODES = ("auto", "deferred", "manual", "aspirational")
+E2E_CRITICAL_PRIORITIES = ("P0", "P1")
+E2E_RATIO_WARNING = 0.3
+_PLACEHOLDERS = frozenset(("", "-", "n/a", "na", "none", "无", "todo", "tbd", "待定"))
+
+
+class ScenarioError(ValueError):
+    """Stable parse/merge failure with a machine-readable code."""
+
+    def __init__(self, code: str, message: str, details: Optional[Mapping[str, object]] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = dict(details) if details else {}
+
+
+def _frontmatter_text(text: str) -> str:
+    """YAML body for `yaml.safe_load`; unclosed delimiters fail closed."""
+    block = frontmatter_block(text)
+    if block is not None:
+        return block
+    if text.startswith("---"):
+        raise ScenarioError("scenario_source_invalid_frontmatter", "frontmatter 缺少闭合 ---")
+    return text
+
+
+def _mapping(value: object, field: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping):
+        raise ScenarioError("invalid_scenario_source", f"{field} 必须是 mapping")
+    return value
+
+
+def _string_list(value: object, field: str) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise ScenarioError("invalid_scenario_source", f"{field} 必须是字符串列表")
+    return tuple(item.strip() for item in value if item.strip())
+
+
+def _boolean(value: object, field: str, default: bool = False) -> bool:
+    if value is None:
+        return default
+    if not isinstance(value, bool):
+        raise ScenarioError("invalid_scenario_source", f"{field} 必须是布尔值")
+    return value
+
+
+def _meaningful(value: object) -> bool:
+    return str(value or "").strip().lower() not in _PLACEHOLDERS
+
+
+def _validate_one(item: Mapping[str, object]) -> dict[str, object]:
+    scenario_id = item.get("id")
+    if not isinstance(scenario_id, str) or not SCENARIO_ID.fullmatch(scenario_id):
+        raise ScenarioError("invalid_scenario_id", f"非法场景 ID: {scenario_id!r}")
+    priority = str(item.get("priority", "P1")).upper()
+    if priority not in PRIORITIES:
+        raise ScenarioError("invalid_priority", f"{scenario_id}: priority 非法: {priority!r}")
+    level = str(item.get("level", "integration")).lower()
+    if level not in LEVELS:
+        raise ScenarioError("invalid_level", f"{scenario_id}: level 非法: {level!r}")
+    exec_mode = str(item.get("exec", "auto")).lower()
+    if exec_mode not in EXEC_MODES:
+        raise ScenarioError("invalid_exec", f"{scenario_id}: exec 非法: {exec_mode!r}")
+    try:
+        from codeflow.acceptance.cf_scenario_quality import validate_extensions
+        extra = validate_extensions(item)
+    except ValueError as exc:
+        raise ScenarioError("invalid_scenario_contract", f"{scenario_id}: {exc}") from exc
+    return {
+        **extra,
+        "id": scenario_id,
+        "title": str(item.get("title", "")).strip(),
+        "priority": priority,
+        "level": level,
+        "exec": exec_mode,
+        "env": extra["env"],
+        "components": list(_string_list(item.get("components"), f"{scenario_id}.components")),
+        "boundary": str(item.get("boundary", "")).strip(),
+        "preconditions": list(_string_list(item.get("preconditions"), f"{scenario_id}.preconditions")),
+        "steps": list(_string_list(item.get("steps"), f"{scenario_id}.steps")),
+        "expected": list(_string_list(item.get("expected"), f"{scenario_id}.expected")),
+        "design_refs": list(_string_list(item.get("design_refs"), f"{scenario_id}.design_refs")),
+        "rules": list(_string_list(item.get("rules"), f"{scenario_id}.rules")),
+        "checks": list(_string_list(item.get("checks"), f"{scenario_id}.checks")),
+        "sources": list(_string_list(item.get("sources"), f"{scenario_id}.sources")),
+        "why_e2e": str(item.get("why_e2e", "")).strip(),
+        "trigger_paths": list(_string_list(item.get("trigger_paths"), f"{scenario_id}.trigger_paths")),
+        "smoke": _boolean(item.get("smoke"), f"{scenario_id}.smoke"),
+    }
+
+
+def parse_scenarios(path: object, *, text: Optional[str] = None) -> dict[str, object]:
+    """Parse and validate one scenarios source file."""
+    target = Path(path)
+    try:
+        raw = target.read_text(encoding="utf-8") if text is None else text
+    except (OSError, UnicodeError) as exc:
+        raise ScenarioError("scenario_source_unreadable", str(exc), {"path": str(target)}) from exc
+    try:
+        data = yaml.safe_load(_frontmatter_text(raw))
+    except yaml.YAMLError as exc:
+        raise ScenarioError("scenario_source_invalid_yaml", str(exc), {"path": str(target)}) from exc
+    document = _mapping(data, "scenarios")
+    schema = document.get("schema")
+    if isinstance(schema, bool) or schema not in (None, SCHEMA_VERSION):
+        raise ScenarioError("unsupported_scenario_schema", str(document.get("schema")))
+    raw = document.get("scenarios")
+    if not isinstance(raw, list) or not raw:
+        raise ScenarioError("scenarios_missing", "scenarios 必须是非空列表")
+    seen: set[str] = set()
+    scenarios: list[dict[str, object]] = []
+    for item in raw:
+        scenario = _validate_one(_mapping(item, "scenarios[]"))
+        if scenario["id"] in seen:
+            raise ScenarioError("duplicate_scenario_id", str(scenario["id"]))
+        seen.add(scenario["id"])
+        scenarios.append(scenario)
+    return {
+        "schema": SCHEMA_VERSION,
+        "requirement": str(document.get("requirement", target.parent.name)),
+        "source": str(target),
+        "scenarios": scenarios,
+    }
+
+
+def _definition(scenario: Mapping[str, object]) -> dict[str, object]:
+    fields = ("title", "priority", "level", "exec", "env", "components", "boundary",
+              "preconditions", "steps", "expected", "rules", "why_e2e", "trigger_paths", "smoke")
+    from codeflow.acceptance.cf_scenario_quality import EXTRA_FIELDS
+    return {field: scenario.get(field) for field in (*fields, *EXTRA_FIELDS)}
+
+
+def merge_scenarios(sets: Sequence[Mapping[str, object]]) -> list[dict[str, object]]:
+    """Union scenario sets by global ID; reject conflicting definitions."""
+    merged: dict[str, dict[str, object]] = {}
+    for source in sets:
+        for raw in source.get("scenarios", []) or []:
+            scenario = _validate_one(_mapping(raw, "scenarios[]"))
+            current = merged.get(str(scenario["id"]))
+            if current is None:
+                merged[str(scenario["id"])] = scenario
+                continue
+            if _definition(current) != _definition(scenario):
+                fields = [key for key in _definition(current) if _definition(current)[key] != _definition(scenario)[key]]
+                raise ScenarioError(
+                    "design_scenario_conflict",
+                    f"{scenario['id']} 定义冲突: {', '.join(fields)}",
+                    {"scenario": scenario["id"], "fields": fields},
+                )
+            current["sources"] = sorted(set(current.get("sources", [])) | set(scenario.get("sources", [])))
+            current["design_refs"] = sorted(set(current.get("design_refs", [])) | set(scenario.get("design_refs", [])))
+            current["checks"] = sorted(set(current.get("checks", [])) | set(scenario.get("checks", [])))
+    return [merged[key] for key in sorted(merged)]
+
+
+def _quality_issue(code: str, scenario: str, field: str, message: str) -> dict[str, object]:
+    return {"code": code, "scenario": scenario, "field": field, "message": message}
+
+
+def validate_e2e_quality(scenarios: Sequence[Mapping[str, object]]) -> dict[str, object]:
+    """Validate semantic acceptance contracts through one shared quality gate."""
+    from codeflow.acceptance.cf_scenario_quality import quality_report
+    return quality_report(scenarios)
+
+
+def scenario_status(scenario: Mapping[str, object], checks: Mapping[str, str]) -> str:
+    """Derive scenario state from all required checks (AND semantics)."""
+    required = [str(item) for item in scenario.get("checks", [])]
+    if not required:
+        return "aspirational" if scenario.get("exec") == "aspirational" else "designed"
+    states = [checks.get(check_id, "designed") for check_id in required]
+    for bad in ("failed", "env_blocked", "incomplete"):
+        if bad in states:
+            return bad
+    if all(state in ("passed", "verified") for state in states):
+        return "verified"
+    return "designed"
+
+
+def require_source(task_dir: object) -> Path:
+    """Return the single scenarios source for a requirement directory."""
+    directory = Path(task_dir)
+    matches = sorted(directory.glob("*.scenarios.md")) if directory.is_dir() else []
+    if not matches:
+        raise ScenarioError("scenario_source_missing", f"缺少 <需求>.scenarios.md: {directory}")
+    if len(matches) > 1:
+        raise ScenarioError("scenario_source_ambiguous", f"多个场景源: {', '.join(path.name for path in matches)}")
+    return matches[0]
+
+
+def reconcile_coverage(scenarios: Sequence[Mapping[str, object]],
+                       coverage: Sequence[Mapping[str, object]]) -> dict[str, object]:
+    """Reconcile canonical scenarios with Acceptance Coverage rows."""
+    by_scenario = {str(item.get("id")): item for item in scenarios}
+    owners: dict[str, list[str]] = {}
+    unknown: list[str] = []
+    for row in coverage:
+        scenario_id = row.get("scenario_id") or row.get("id")
+        if not isinstance(scenario_id, str) or not scenario_id:
+            continue
+        if scenario_id not in by_scenario:
+            unknown.append(scenario_id)
+            continue
+        owner = row.get("owner")
+        if isinstance(owner, str) and owner.strip():
+            owners.setdefault(scenario_id, []).append(owner.strip())
+    covered = set(owners) | {str(row.get("scenario_id") or row.get("id")) for row in coverage
+                              if isinstance(row.get("scenario_id") or row.get("id"), str)}
+    missing = sorted(set(by_scenario) - covered)
+    duplicate = sorted(key for key, values in owners.items() if len(set(values)) > 1)
+    unowned = sorted(set(by_scenario) - set(owners))
+    return {
+        "ok": not missing and not unknown and not duplicate and not unowned,
+        "missing": missing,
+        "unknown": sorted(unknown),
+        "duplicate_owner": duplicate,
+        "unowned": unowned,
+    }
+
+
+def load_requirement_scenarios(task_dir: object, allow_legacy: bool = False) -> dict[str, object]:
+    """Load the requirement source, or an explicit deprecated legacy marker."""
+    directory = Path(task_dir)
+    try:
+        source = require_source(directory)
+    except ScenarioError as exc:
+        if exc.code != "scenario_source_missing" or not allow_legacy:
+            raise
+        return {"schema": SCHEMA_VERSION, "requirement": directory.name,
+                "source": "", "scenarios": [], "deprecated": True}
+    return parse_scenarios(source)
+
+
+def audit_scenario_source(scenarios: Sequence[Mapping[str, object]],
+                          coverage: Sequence[Mapping[str, object]],
+                          manifest_ids: Optional[Sequence[str]] = None) -> dict[str, object]:
+    """Three-way audit: scenarios, coverage, manifest."""
+    report = reconcile_coverage(scenarios, coverage)
+    scenario_ids = {str(item.get("id")) for item in scenarios}
+    coverage_ids = {str(item.get("scenario_id") or item.get("id")) for item in coverage}
+    manifest = {str(item) for item in manifest_ids} if manifest_ids is not None else None
+    report["manifest_missing"] = sorted(scenario_ids - manifest) if manifest is not None else []
+    report["manifest_unknown"] = sorted(manifest - scenario_ids) if manifest is not None else []
+    report["coverage_unknown"] = sorted(coverage_ids - scenario_ids)
+    report["ok"] = bool(report["ok"] and not report["coverage_unknown"]
+                        and not report["manifest_missing"] and not report["manifest_unknown"])
+    return report
+
+
+def migrate_from_coverage(coverage: Sequence[Mapping[str, object]]) -> dict[str, object]:
+    """Build an initial scenarios source from legacy Acceptance Coverage."""
+    scenarios: list[dict[str, object]] = []
+    invalid: list[str] = []
+    for row in coverage:
+        scenario_id = str(row.get("scenario_id") or row.get("id") or "")
+        if not SCENARIO_ID.fullmatch(scenario_id):
+            invalid.append(scenario_id)
+            continue
+        priority = str(row.get("priority") or "P1").upper()
+        level = str(row.get("level") or "integration").lower()
+        if priority not in PRIORITIES:
+            priority = "P1"
+        if level not in LEVELS:
+            level = "integration"
+        scenarios.append({
+            "id": scenario_id,
+            "title": str(row.get("title") or scenario_id),
+            "priority": priority,
+            "level": level,
+            "exec": "auto",
+            "env": "none",
+            "components": [],
+            "boundary": str(row.get("boundary") or ""),
+            "preconditions": [],
+            "steps": [],
+            "expected": [],
+            "design_refs": [],
+            "rules": [],
+            "checks": [],
+            "sources": ["legacy-coverage"],
+        })
+    return {"schema": SCHEMA_VERSION, "scenarios": scenarios, "migrated": True, "invalid": invalid}