@michaelxwb/code-flow 0.5.2 → 0.6.0

package/src/core/code-flow/scripts/cf_spec_gate.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Fail-closed Stage Gate for required Spec Context rules."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import re
+import sys
+from typing import IO, Mapping, Optional, Sequence
+
+from cf_spec_context import Decision, RuleBinding, RuleStageStatus, SpecBinding, SpecContext, load_context
+
+
+@dataclass(frozen=True)
+class GateIssue:
+    code: str
+    spec_id: str
+    rule_ref: str
+    stage: str
+    message: str
+
+
+@dataclass(frozen=True)
+class GateResult:
+    decision: str
+    errors: tuple[GateIssue, ...]
+    warnings: tuple[GateIssue, ...]
+    affected_refs: tuple[str, ...]
+
+
+def _parse_time(value: str) -> Optional[datetime]:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo is not None else None
+
+
+def _decision_valid(decision: Optional[Decision]) -> bool:
+    if decision is None:
+        return False
+    return all((decision.reason, decision.confirmed_by, decision.confirmed_at, decision.source))
+
+
+def _waiver_issue(decision: Optional[Decision], now: datetime) -> Optional[str]:
+    if not _decision_valid(decision) or decision is None or not decision.expires_at:
+        return "waiver_invalid"
+    expires = _parse_time(decision.expires_at)
+    if expires is None:
+        return "waiver_invalid"
+    return "waiver_expired" if expires <= now else None
+
+
+def _evidence_issue(rule: RuleBinding, status: RuleStageStatus) -> Optional[str]:
+    if not status.evidence:
+        return "evidence_missing"
+    for evidence in status.evidence:
+        if evidence.get("status") != "verified":
+            continue
+        if evidence.get("rule_text_sha256") != rule.text_sha256:
+            continue
+        result_hash = evidence.get("result_sha256")
+        if isinstance(result_hash, str) and result_hash:
+            return None
+    return "stale_evidence"
+
+
+def _status_issue(rule: RuleBinding, status: RuleStageStatus, now: datetime) -> Optional[str]:
+    if status.status == "applied":
+        return None
+    if status.status == "verified":
+        return _evidence_issue(rule, status)
+    if status.status == "not_applicable":
+        return None if _decision_valid(status.decision) else "decision_invalid"
+    if status.status == "waived":
+        return _waiver_issue(status.decision, now)
+    return status.status
+
+
+def _binding_issues(binding: SpecBinding, stage: str, now: datetime) -> tuple[list[GateIssue], list[GateIssue]]:
+    errors: list[GateIssue] = []
+    warnings: list[GateIssue] = []
+    for rule in binding.rules:
+        status = rule.stage_status.get(stage)
+        if status is None:
+            continue
+        if rule.enforcement == "advisory" and status.status == "pending":
+            continue
+        code = "missing_spec" if binding.status == "missing" else _status_issue(rule, status, now)
+        if code is None:
+            continue
+        issue = GateIssue(code, binding.spec_id, rule.ref, stage, f"{binding.spec_id}#{rule.ref}: {code}")
+        target = errors if rule.enforcement == "required" else warnings
+        target.append(issue)
+    return errors, warnings
+
+
+def validate_stage(
+    context: SpecContext,
+    stage: str,
+    artifact: str = "",
+    task_id: str = "",
+    now: Optional[datetime] = None,
+) -> GateResult:
+    del artifact, task_id
+    current = now or datetime.now(timezone.utc)
+    errors: list[GateIssue] = []
+    warnings: list[GateIssue] = []
+    for binding in context.bindings:
+        binding_errors, binding_warnings = _binding_issues(binding, stage, current)
+        errors.extend(binding_errors)
+        warnings.extend(binding_warnings)
+    refs = tuple(sorted({f"{item.spec_id}#{item.rule_ref}" for item in (*errors, *warnings)}))
+    return GateResult("block" if errors else "pass", tuple(errors), tuple(warnings), refs)
+
+
+def _task_sections(text: str) -> Mapping[str, str]:
+    matches = list(re.finditer(r"(?m)^## (TASK-\d+):[^\n]*$", text))
+    sections: dict[str, str] = {}
+    for index, match in enumerate(matches):
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(text)
+        sections[match.group(1)] = text[match.start():end]
+    return sections
+
+
+def _plan_issue(code: str, binding: SpecBinding, rule: RuleBinding, message: str) -> GateIssue:
+    return GateIssue(code, binding.spec_id, rule.ref, "plan", message)
+
+
+def _rule_plan_issues(
+    binding: SpecBinding, rule: RuleBinding, sections: Mapping[str, str]
+) -> tuple[GateIssue, ...]:
+    full_ref = f"{binding.spec_id}#{rule.ref}"
+    owners = tuple(task for task, section in sections.items() if full_ref in section)
+    if not owners:
+        return (_plan_issue("plan_owner_missing", binding, rule, f"{full_ref} 没有责任 TASK"),)
+    if len(owners) > 1:
+        return (_plan_issue("plan_owner_duplicate", binding, rule, f"{full_ref} 有多个责任 TASK"),)
+    section = sections[owners[0]]
+    issues: list[GateIssue] = []
+    if rule.verifier_ref == "advisory:none":
+        issues.append(_plan_issue("plan_verifier_missing", binding, rule, f"{full_ref} 缺 verifier"))
+    checklist = section.partition("### Checklist")[2].partition("### Acceptance Contract")[0]
+    if rule.ref not in checklist or "verifier" not in checklist.lower():
+        issues.append(_plan_issue("plan_checklist_missing", binding, rule, f"{full_ref} 缺 verifier Checklist"))
+    contract = section.partition("### Acceptance Contract")[2]
+    if not contract.strip() or not re.search(r"\b(unit|integration|E2E|manual)\b", contract):
+        issues.append(_plan_issue("plan_acceptance_missing", binding, rule, f"{full_ref} 缺测试层级/真实边界"))
+    return tuple(issues)
+
+
+def validate_plan_coverage(context: SpecContext, artifact: str) -> GateResult:
+    try:
+        text = Path(artifact).read_text(encoding="utf-8")
+    except OSError as exc:
+        issue = GateIssue("plan_read_error", "", "", "plan", str(exc))
+        return GateResult("block", (issue,), (), ())
+    sections = _task_sections(text)
+    errors: list[GateIssue] = []
+    for binding in context.bindings:
+        for rule in binding.rules:
+            if rule.enforcement == "required" and "plan" in rule.stage_status:
+                errors.extend(_rule_plan_issues(binding, rule, sections))
+    refs = tuple(sorted(f"{item.spec_id}#{item.rule_ref}" for item in errors))
+    return GateResult("block" if errors else "pass", tuple(errors), (), refs)
+
+
+def _issue_data(issue: GateIssue) -> dict[str, str]:
+    return {
+        "code": issue.code,
+        "spec_id": issue.spec_id,
+        "rule_ref": issue.rule_ref,
+        "stage": issue.stage,
+        "message": issue.message,
+    }
+
+
+def result_to_data(result: GateResult) -> dict[str, object]:
+    return {
+        "decision": result.decision,
+        "errors": [_issue_data(item) for item in result.errors],
+        "warnings": [_issue_data(item) for item in result.warnings],
+        "affected_refs": list(result.affected_refs),
+    }
+
+
+def _merge_results(first: GateResult, second: GateResult) -> GateResult:
+    errors = (*first.errors, *second.errors)
+    warnings = (*first.warnings, *second.warnings)
+    refs = tuple(sorted(set((*first.affected_refs, *second.affected_refs))))
+    return GateResult("block" if errors else "pass", errors, warnings, refs)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cf_spec_gate.py")
+    parser.add_argument("--task-dir", required=True)
+    parser.add_argument("--stage", required=True)
+    parser.add_argument("--task", default="")
+    parser.add_argument("--artifact", default="")
+    parser.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None, stdout: IO[str] = sys.stdout) -> int:
+    try:
+        args = _parser().parse_args(argv)
+        context = load_context(str(Path(args.task_dir) / "spec-context.yml"))
+        result = validate_stage(context, args.stage, task_id=args.task)
+        if args.stage == "plan" and args.artifact:
+            result = _merge_results(result, validate_plan_coverage(context, args.artifact))
+        stdout.write(json.dumps(result_to_data(result), ensure_ascii=False))
+        return 0 if result.decision == "pass" else 3
+    except Exception as exc:
+        sys.stderr.write(f"cf_spec_gate error: {exc}\n")
+        stdout.write(json.dumps({"decision": "block", "errors": [{"code": "gate_error"}]}, ensure_ascii=False))
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/core/code-flow/scripts/cf_spec_metadata.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""Schema-v1 Spec metadata parser and deterministic content hashes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path
+import re
+from typing import Mapping, Optional
+
+import yaml
+
+
+ALLOWED_STAGES = frozenset(("prd", "design", "plan", "code", "review"))
+ALLOWED_ENFORCEMENT = frozenset(("required", "advisory"))
+ALLOWED_VERIFIERS = frozenset(("document", "regex", "ast", "command", "test", "manual"))
+_ID_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_RULE_ID_RE = re.compile(r"^RULE-[a-z0-9]+(?:-[a-z0-9]+)*-\d{3}$")
+_EXPLICIT_RULE_RE = re.compile(r"^\[(RULE-[a-z0-9-]+-\d{3})\]\s+(.+)$")
+_FRONTMATTER_RE = re.compile(r"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|$)", re.DOTALL)
+_SECTION_RE = re.compile(r"^##\s+(Rules|Anti-Patterns|Patterns|Examples)\s*$")
+_H2_RE = re.compile(r"^##\s+")
+_BULLET_RE = re.compile(r"^\s*-\s+(.+\S|\S)\s*$")
+
+
+class SpecMetadataError(ValueError):
+    """A schema error with a stable field and source location."""
+
+    def __init__(self, path: str, field: str, line: int, message: str) -> None:
+        self.path = path
+        self.field = field
+        self.line = max(1, line)
+        self.message = message
+        super().__init__(f"{path}:{self.line}: metadata_error {field}: {message}")
+
+
+@dataclass(frozen=True)
+class SpecHashes:
+    file_sha256: str
+    metadata_sha256: str
+    rules_sha256: str
+
+    def values(self) -> tuple[str, str, str]:
+        return (self.file_sha256, self.metadata_sha256, self.rules_sha256)
+
+
+@dataclass(frozen=True)
+class SpecVerifier:
+    rule: str
+    type: str
+    config: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class SpecRule:
+    ref: str
+    text: str
+    section: str
+    enforcement: str
+    text_sha256: str
+    line: int
+
+
+@dataclass(frozen=True)
+class SpecMetadata:
+    id: str
+    description: str
+    stages: tuple[str, ...]
+    enforcement: str
+    owner: Optional[str]
+    checks: tuple[Mapping[str, object], ...]
+    verifiers: tuple[SpecVerifier, ...]
+    rules: tuple[SpecRule, ...]
+    hashes: SpecHashes
+    path: str
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _normalized_text(text: str) -> str:
+    return " ".join(text.split())
+
+
+def _canonical_json(value: object, path: str, field: str, line: int) -> bytes:
+    try:
+        text = json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    except (TypeError, ValueError) as exc:
+        raise SpecMetadataError(path, field, line, f"无法规范化: {exc}") from exc
+    return text.encode("utf-8")
+
+
+def _field_line(frontmatter: str, key: str) -> int:
+    pattern = re.compile(rf"^\s*{re.escape(key)}\s*:")
+    for number, line in enumerate(frontmatter.splitlines(), start=2):
+        if pattern.match(line):
+            return number
+    return 1
+
+
+def _verifier_field_line(frontmatter: str, index: int, key: str) -> int:
+    current = -1
+    for number, line in enumerate(frontmatter.splitlines(), start=2):
+        if re.match(r"^\s*-\s+rule\s*:", line):
+            current += 1
+        if current == index and re.match(rf"^\s+{re.escape(key)}\s*:", line):
+            return number
+    return _field_line(frontmatter, "verifiers")
+
+
+def _split_frontmatter(content: str, path: str) -> tuple[Mapping[str, object], str, str]:
+    match = _FRONTMATTER_RE.match(content)
+    if not match:
+        raise SpecMetadataError(path, "frontmatter", 1, "缺失或未闭合 YAML frontmatter")
+    raw = match.group(1)
+    try:
+        loaded = yaml.safe_load(raw) or {}
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        line = (mark.line + 2) if mark is not None else 1
+        raise SpecMetadataError(path, "frontmatter", line, f"YAML 解析失败: {exc}") from exc
+    if not isinstance(loaded, dict):
+        raise SpecMetadataError(path, "frontmatter", 2, "顶层必须是 mapping")
+    if not all(isinstance(key, str) for key in loaded):
+        raise SpecMetadataError(path, "frontmatter", 2, "所有顶层 key 必须是字符串")
+    return loaded, raw, content[match.end():]
+
+
+def _required_string(meta: Mapping[str, object], key: str, path: str, raw: str) -> str:
+    value = meta.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise SpecMetadataError(path, key, _field_line(raw, key), "必须是非空字符串")
+    return value.strip()
+
+
+def _validate_stages(meta: Mapping[str, object], path: str, raw: str) -> tuple[str, ...]:
+    value = meta.get("stages")
+    line = _field_line(raw, "stages")
+    if not isinstance(value, list) or not value or not all(isinstance(item, str) for item in value):
+        raise SpecMetadataError(path, "stages", line, "必须是非空字符串列表")
+    stages = tuple(item.strip() for item in value)
+    invalid = sorted(set(stages) - ALLOWED_STAGES)
+    if invalid or len(set(stages)) != len(stages):
+        detail = f"非法或重复 stage: {invalid or list(stages)}"
+        raise SpecMetadataError(path, "stages", line, detail)
+    return stages
+
+
+def _validate_checks(meta: Mapping[str, object], path: str, raw: str) -> tuple[Mapping[str, object], ...]:
+    value = meta.get("checks", [])
+    if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
+        raise SpecMetadataError(path, "checks", _field_line(raw, "checks"), "必须是 mapping 列表")
+    return tuple(value)
+
+
+def _parse_verifiers(meta: Mapping[str, object], path: str, raw: str) -> tuple[SpecVerifier, ...]:
+    value = meta.get("verifiers", [])
+    if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
+        raise SpecMetadataError(path, "verifiers", _field_line(raw, "verifiers"), "必须是 mapping 列表")
+    result: list[SpecVerifier] = []
+    seen: set[str] = set()
+    for index, item in enumerate(value):
+        rule = item.get("rule")
+        kind = item.get("type")
+        config = item.get("config")
+        if not isinstance(rule, str) or not _RULE_ID_RE.fullmatch(rule):
+            line = _verifier_field_line(raw, index, "rule")
+            raise SpecMetadataError(path, f"verifiers[{index}].rule", line, "必须是稳定 RULE ID")
+        if kind not in ALLOWED_VERIFIERS:
+            line = _verifier_field_line(raw, index, "type")
+            raise SpecMetadataError(path, f"verifiers[{index}].type", line, f"不支持 type: {kind!r}")
+        if not isinstance(config, dict):
+            line = _verifier_field_line(raw, index, "config")
+            raise SpecMetadataError(path, f"verifiers[{index}].config", line, "必须是 mapping")
+        if rule in seen:
+            raise SpecMetadataError(path, "verifiers", _field_line(raw, "verifiers"), f"重复 verifier: {rule}")
+        seen.add(rule)
+        result.append(SpecVerifier(rule=rule, type=kind, config=config))
+    return tuple(result)
+
+
+def _domain_from_path(path: str) -> str:
+    source = Path(path)
+    parts = source.parts
+    if "specs" in parts:
+        index = parts.index("specs")
+        candidate = parts[index + 1] if index + 1 < len(parts) - 1 else source.stem
+    else:
+        candidate = source.parent.name or source.stem
+    normalized = re.sub(r"[^a-z0-9]+", "-", candidate.lower()).strip("-")
+    return normalized or "spec"
+
+
+def _entry_details(section: str) -> tuple[str, str]:
+    if section in ("Rules", "Anti-Patterns"):
+        return "RULE", "required"
+    if section == "Patterns":
+        return "PATTERN", "advisory"
+    return "EXAMPLE", "informational"
+
+
+def _parse_rules(body: str, path: str, line_offset: int) -> tuple[SpecRule, ...]:
+    domain = _domain_from_path(path)
+    counters = {"RULE": 0, "PATTERN": 0, "EXAMPLE": 0}
+    rules: list[SpecRule] = []
+    section = ""
+    fence = ""
+    used: set[str] = set()
+    for relative_line, line in enumerate(body.splitlines(), start=1):
+        number = relative_line + line_offset
+        stripped = line.strip()
+        if not fence and stripped.startswith(("```", "~~~")):
+            marker = stripped[:3]
+            fence = marker
+            continue
+        if fence and stripped.startswith(fence):
+            fence = ""
+            continue
+        heading = _SECTION_RE.match(line) if not fence else None
+        if heading:
+            section = heading.group(1)
+            continue
+        if not fence and _H2_RE.match(line):
+            section = ""
+            continue
+        bullet = _BULLET_RE.match(line) if section and not fence else None
+        if not bullet:
+            continue
+        prefix, enforcement = _entry_details(section)
+        counters[prefix] += 1
+        ref = f"{prefix}-{domain}-{counters[prefix]:03d}"
+        text = bullet.group(1).strip()
+        explicit = _EXPLICIT_RULE_RE.match(text) if prefix == "RULE" else None
+        if prefix == "RULE" and text.startswith("[RULE-") and not explicit:
+            raise SpecMetadataError(path, "rules", number, "显式 Rule ID 必须是 RULE-<domain>-NNN")
+        if explicit:
+            ref, text = explicit.group(1), explicit.group(2).strip()
+        while ref in used and not explicit:
+            counters[prefix] += 1
+            ref = f"{prefix}-{domain}-{counters[prefix]:03d}"
+        if ref in used:
+            raise SpecMetadataError(path, "rules", number, f"重复规则 ID: {ref}")
+        used.add(ref)
+        normalized = _normalized_text(text)
+        rules.append(SpecRule(ref, normalized, section, enforcement, _sha256(normalized.encode()), number))
+    return tuple(rules)
+
+
+def _validate_links(
+    rules: tuple[SpecRule, ...], verifiers: tuple[SpecVerifier, ...], path: str, raw: str
+) -> None:
+    required = {rule.ref for rule in rules if rule.enforcement == "required"}
+    linked = {verifier.rule for verifier in verifiers}
+    missing = sorted(required - linked)
+    unknown = sorted(linked - required)
+    line = _field_line(raw, "verifiers")
+    if missing:
+        raise SpecMetadataError(path, "verifiers", line, f"required Rule 缺 verifier: {', '.join(missing)}")
+    if unknown:
+        raise SpecMetadataError(path, "verifiers", line, f"verifier 引用未知 required Rule: {', '.join(unknown)}")
+
+
+def parse_spec_metadata(content: str, path: str = "<memory>", raw_bytes: Optional[bytes] = None) -> SpecMetadata:
+    meta, raw_frontmatter, body = _split_frontmatter(content, path)
+    spec_id = _required_string(meta, "id", path, raw_frontmatter)
+    if not _ID_RE.fullmatch(spec_id):
+        raise SpecMetadataError(path, "id", _field_line(raw_frontmatter, "id"), "必须是 kebab-case")
+    description = _required_string(meta, "description", path, raw_frontmatter)
+    stages = _validate_stages(meta, path, raw_frontmatter)
+    enforcement = _required_string(meta, "enforcement", path, raw_frontmatter)
+    if enforcement not in ALLOWED_ENFORCEMENT:
+        line = _field_line(raw_frontmatter, "enforcement")
+        raise SpecMetadataError(path, "enforcement", line, f"必须是 {sorted(ALLOWED_ENFORCEMENT)}")
+    owner = meta.get("owner")
+    if owner is not None and (not isinstance(owner, str) or not owner.strip()):
+        raise SpecMetadataError(path, "owner", _field_line(raw_frontmatter, "owner"), "必须是非空字符串")
+    checks = _validate_checks(meta, path, raw_frontmatter)
+    verifiers = _parse_verifiers(meta, path, raw_frontmatter)
+    body_line_offset = raw_frontmatter.count("\n") + 3
+    rules = _parse_rules(body, path, body_line_offset)
+    _validate_links(rules, verifiers, path, raw_frontmatter)
+    required_rules = [(rule.ref, rule.text) for rule in rules if rule.enforcement == "required"]
+    source_bytes = raw_bytes if raw_bytes is not None else content.encode("utf-8")
+    hashes = SpecHashes(
+        file_sha256=_sha256(source_bytes),
+        metadata_sha256=_sha256(_canonical_json(meta, path, "frontmatter", 1)),
+        rules_sha256=_sha256(_canonical_json(required_rules, path, "rules", 1)),
+    )
+    return SpecMetadata(spec_id, description, stages, enforcement, owner, checks, verifiers, rules, hashes, path)
+
+
+def load_spec_metadata(path: str) -> SpecMetadata:
+    try:
+        raw = Path(path).read_bytes()
+    except OSError as exc:
+        raise SpecMetadataError(path, "file", 1, f"读取失败: {exc}") from exc
+    try:
+        content = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise SpecMetadataError(path, "encoding", 1, f"必须是 UTF-8: {exc}") from exc
+    return parse_spec_metadata(content, path=path, raw_bytes=raw)