@michaelxwb/code-flow 0.8.1 → 1.0.0

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

@@ -1,197 +0,0 @@
-"""One executable plan gate for manifest identity, semantics and design closure."""
-from __future__ import annotations
-
-import json
-import re
-from dataclasses import dataclass
-from pathlib import Path
-from shlex import quote
-from typing import Mapping, Optional
-
-
-@dataclass(frozen=True)
-class FileSnapshot:
-    """One file read once, with a stat fingerprint for drift detection."""
-
-    path: str
-    text: str
-    size: int
-    mtime_ns: int
-
-    def drift(self) -> bool:
-        try:
-            stat = Path(self.path).stat()
-        except OSError:
-            return True
-        return stat.st_size != self.size or stat.st_mtime_ns != self.mtime_ns
-
-
-@dataclass(frozen=True)
-class PlanSnapshot:
-    """Verified inputs of one verify_plan operation; no persistent cache."""
-
-    task: FileSnapshot
-    manifest: FileSnapshot
-    scenario_file: str
-    scenario: Optional[FileSnapshot]
-
-    def drift(self) -> bool:
-        if self.task.drift() or self.manifest.drift():
-            return True
-        return self.scenario is not None and self.scenario.drift()
-
-
-def _read_snapshot(path: Path) -> FileSnapshot:
-    stat = path.stat()
-    return FileSnapshot(str(path), path.read_text(encoding="utf-8"), stat.st_size, stat.st_mtime_ns)
-
-
-def load_plan_snapshot(directory: str, task_file: str,
-                       require_scenarios: bool = False) -> PlanSnapshot:
-    """Read TASK, manifest and scenario source at most once for one operation."""
-    from codeflow.acceptance.cf_scenario_source import ScenarioError
-    base = Path(directory)
-    manifest = _read_snapshot(base / ".acceptance-manifest.json")
-    task = _read_snapshot(Path(task_file))
-    try:
-        data = json.loads(manifest.text)
-    except ValueError:
-        data = {}
-    try:
-        source_file = _source(base, data if isinstance(data, Mapping) else {}, require_scenarios)
-    except ScenarioError:
-        source_file = ""
-    source = _read_snapshot(Path(source_file)) if source_file and Path(source_file).is_file() else None
-    return PlanSnapshot(task, manifest, source_file, source)
-
-
-def _root(directory: Path) -> Path:
-    return next((parent.parent for parent in (directory, *directory.parents)
-                 if parent.name == ".code-flow"), directory)
-
-
-def _source(directory: Path, manifest: Mapping[str, object], required: bool) -> str:
-    from codeflow.acceptance.cf_scenario_source import require_source
-    named = manifest.get("scenarios_file")
-    if isinstance(named, str) and named:
-        return str(directory / named)
-    candidates = sorted(directory.glob("*.scenarios.md"))
-    if required or candidates:
-        return str(require_source(directory))
-    return ""
-
-
-def _projection(source: Mapping[str, object], manifest: Mapping[str, object]) -> list[dict[str, object]]:
-    from codeflow.acceptance.cf_acceptance_schema import scenario_check_ids
-    rows = {str(row["id"]): row for row in manifest.get("scenarios", [])}
-    checks = {str(check["id"]) for check in manifest.get("checks", [])}
-    findings: list[dict[str, object]] = []
-    for row in source["scenarios"]:
-        required = scenario_check_ids(row)
-        current = rows.get(str(row["id"]), {})
-        unknown = set(required) - checks
-        if unknown:
-            findings.append({"code": "unknown_check", "scenario": row["id"], "checks": sorted(unknown)})
-        if required and set(required) != set(scenario_check_ids(current)):
-            findings.append({"code": "scenario_checks_not_projected", "scenario": row["id"]})
-    return findings
-
-
-def _scenario_snapshot(snapshot: PlanSnapshot, source_file: str) -> Optional[FileSnapshot]:
-    scenario = snapshot.scenario
-    if not source_file:
-        return None
-    if scenario is not None and Path(scenario.path).resolve() == Path(source_file).resolve():
-        return scenario
-    return _read_snapshot(Path(source_file)) if Path(source_file).is_file() else None
-
-
-def _scenario_ids(text: str) -> set[str]:
-    """Expand explicit IDs and `S-01~04` / `S-01~S-04` ranges."""
-    ids = {item.upper() for item in re.findall(r"\b(?:S|E|B)-\d+\b", text, re.IGNORECASE)}
-    for match in re.finditer(r"\b([SEB])-(\d+)\s*~\s*(?:\1-)?(\d+)\b", text, re.IGNORECASE):
-        prefix, start, end = match.group(1).upper(), int(match.group(2)), int(match.group(3))
-        width = max(len(match.group(2)), len(match.group(3)))
-        for value in range(start, end + 1):
-            ids.add(f"{prefix}-{value:0{width}d}")
-    return ids
-
-
-def _checklist_issues(text: str) -> list[dict[str, str]]:
-    """Flag scenario IDs used in a Checklist but not declared in Acceptance-Refs.
-
-    Cross-task boundaries start as this mismatch: a task writes another task's
-    scenario into its checklist, then the plan assigns the scenario to only one
-    owner. Reported as a non-blocking warning for existing plans.
-    """
-    from codeflow.task.cf_task_doc import TaskDocumentError, parse_task_document
-    try:
-        document = parse_task_document(text)
-    except TaskDocumentError:
-        return []
-    issues: list[dict[str, str]] = []
-    for task in document.tasks:
-        declared = _scenario_ids(str(task.fields.get("Acceptance-Refs", "")))
-        checklist = task.body.partition("### Checklist")[2].partition("### Acceptance Contract")[0]
-        used = _scenario_ids(checklist)
-        for scenario in sorted(used - declared):
-            issues.append({"code": "checklist_scenario_not_in_refs", "task": task.id, "scenario": scenario})
-        for scenario in sorted(declared - used):
-            issues.append({"code": "acceptance_ref_not_in_checklist", "task": task.id, "scenario": scenario})
-    return issues
-
-
-def verify_plan(directory: str, task_file: str, require_scenarios: bool = False,
-                *, snapshot: Optional[PlanSnapshot] = None) -> dict[str, object]:
-    from codeflow.acceptance.cf_acceptance_manifest_core import validate_manifest
-    from codeflow.acceptance.cf_acceptance_schema import load_manifest
-    from codeflow.acceptance.cf_check_registration import validate_registration
-    from codeflow.cli.cf_design_lint import lint_requirement
-    from codeflow.acceptance.cf_scenario_source import parse_scenarios, validate_e2e_quality
-    from codeflow.spec.cf_spec_context_model import load_context
-    from codeflow.spec.cf_stage_gate import result_to_data, validate_plan_coverage, validate_stage
-    base = Path(directory)
-    path = base / ".acceptance-manifest.json"
-    if not path.is_file():
-        return {"decision": "block", "reason": "acceptance_manifest_missing"}
-    plan = snapshot if snapshot is not None else load_plan_snapshot(directory, task_file, require_scenarios)
-    if plan.drift():
-        return {"decision": "block", "reason": "plan_snapshot_drift"}
-    try:
-        manifest = load_manifest(path, text=plan.manifest.text)
-    except (OSError, ValueError, json.JSONDecodeError) as exc:
-        return {"decision": "block", "reason": f"acceptance_manifest_invalid: {exc}"}
-    source_file = _source(base, manifest, require_scenarios)
-    scenario = _scenario_snapshot(plan, source_file)
-    valid, reason = validate_manifest(task_file, str(path), task_text=plan.task.text,
-                                      manifest=manifest, scenario_file=source_file,
-                                      scenario_text=scenario.text if scenario is not None else None)
-    if not valid:
-        return {"decision": "block", "reason": reason}
-    if scenario is not None:
-        source = parse_scenarios(scenario.path, text=scenario.text)
-    elif source_file:
-        source = parse_scenarios(source_file)
-    else:
-        source = {"scenarios": manifest["scenarios"]}
-    quality = validate_e2e_quality(source["scenarios"])
-    projection = _projection(source, manifest)
-    registration = validate_registration(str(_root(base)), manifest["scenarios"], manifest.get("checks", []))
-    quality.update({"runnable_smoke_count": registration["runnable_smoke_count"],
-                    "runnable_browser_count": registration["runnable_browser_count"],
-                    "registration_status": "passed" if registration["ok"] else "failed"})
-    design = lint_requirement(task_file, source_file, task_text=plan.task.text,
-                              scenarios=source["scenarios"] if source_file else None)
-    context = load_context(str(base / "spec-context.yml"))
-    gate = validate_stage(context, "plan", root=str(_root(base)), task_dir=directory)
-    coverage = validate_plan_coverage(context, task_file, text=plan.task.text)
-    checklist = _checklist_issues(plan.task.text)
-    blocked = (not quality["ok"] or projection or not registration["ok"] or
-               design["decision"] != "pass" or gate.decision != "pass" or coverage.decision != "pass")
-    recovery = (["code-flow spec refresh --task-dir " + quote(str(base)) +
-                 " --root " + quote(str(_root(base))) + " --json"]
-                if any(issue.code == "rule_artifact_stale" for issue in gate.errors) else [])
-    return {"decision": "block" if blocked else "pass", "gate": result_to_data(gate), "next": recovery,
-            "coverage": result_to_data(coverage), "e2e_quality": quality,
-            "registration": registration, "design_lint": design, "projection": projection,
-            "checklist": checklist}

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

@@ -1,174 +0,0 @@
-"""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"}