@michaelxwb/code-flow 0.5.1 → 0.6.0

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

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""Deterministic stage/path candidate resolution for schema-v1 Specs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import fnmatch
+from pathlib import Path
+from typing import Mapping, Optional, Sequence
+
+import yaml
+
+from cf_spec_metadata import ALLOWED_STAGES, SpecMetadata, SpecRule, load_spec_metadata
+
+
+SCOPE_PRIORITY = {"global": 1, "path": 2, "task": 3}
+_config_cache: dict[str, tuple[int, int, Mapping[str, object]]] = {}
+_metadata_cache: dict[str, tuple[int, int, SpecMetadata]] = {}
+
+
+class SpecResolutionError(ValueError):
+    """An explicit resolver/configuration failure."""
+
+    def __init__(self, path: str, field: str, message: str) -> None:
+        self.path = path
+        self.field = field
+        self.message = message
+        super().__init__(f"{path}: resolution_error {field}: {message}")
+
+
+@dataclass(frozen=True)
+class SpecCandidate:
+    spec_id: str
+    path: str
+    scope: str
+    priority: int
+    matched_paths: tuple[str, ...]
+    metadata: SpecMetadata
+
+    @property
+    def required_rule_count(self) -> int:
+        if self.metadata.enforcement == "advisory":
+            return 0
+        return sum(rule.enforcement == "required" for rule in self.metadata.rules)
+
+
+@dataclass(frozen=True)
+class ResolvedRule:
+    ref: str
+    spec_id: str
+    text: str
+    enforcement: str
+    scope: str
+    priority: int
+    overridden_spec_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class RuleConflict:
+    ref: str
+    priority: int
+    spec_ids: tuple[str, ...]
+    text_sha256: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class PrecedenceResolution:
+    candidates: tuple[SpecCandidate, ...]
+    effective_rules: tuple[ResolvedRule, ...]
+    conflicts: tuple[RuleConflict, ...]
+
+
+@dataclass(frozen=True)
+class CandidatePage:
+    items: tuple[SpecCandidate, ...]
+    total: int
+    has_more: bool
+
+
+@dataclass(frozen=True)
+class _RuleSource:
+    candidate: SpecCandidate
+    rule: SpecRule
+    enforcement: str
+
+
+def _fingerprint(path: Path, field: str) -> tuple[int, int]:
+    try:
+        stat = path.stat()
+    except OSError as exc:
+        raise SpecResolutionError(str(path), field, f"读取状态失败: {exc}") from exc
+    return stat.st_mtime_ns, stat.st_size
+
+
+def _load_config(root: str) -> Mapping[str, object]:
+    path = Path(root) / ".code-flow" / "config.yml"
+    if not path.is_file():
+        raise SpecResolutionError(str(path), "config", "缺失 config.yml")
+    mtime, size = _fingerprint(path, "config")
+    cached = _config_cache.get(str(path))
+    if cached and cached[:2] == (mtime, size):
+        return cached[2]
+    try:
+        loaded = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except (OSError, UnicodeError, yaml.YAMLError) as exc:
+        raise SpecResolutionError(str(path), "config", f"解析失败: {exc}") from exc
+    if not isinstance(loaded, dict) or not all(isinstance(key, str) for key in loaded):
+        raise SpecResolutionError(str(path), "config", "顶层必须是字符串 key mapping")
+    _config_cache[str(path)] = (mtime, size, loaded)
+    return loaded
+
+
+def _path_mapping(config: Mapping[str, object], path: str) -> Mapping[str, object]:
+    value = config.get("path_mapping")
+    if not isinstance(value, dict) or not all(isinstance(key, str) for key in value):
+        raise SpecResolutionError(path, "path_mapping", "必须是字符串 key mapping")
+    return value
+
+
+def _domain_config(mapping: Mapping[str, object], domain: str, config_path: str) -> Mapping[str, object]:
+    value = mapping.get(domain, {})
+    if not isinstance(value, dict):
+        raise SpecResolutionError(config_path, f"path_mapping.{domain}", "必须是 mapping")
+    return value
+
+
+def _patterns(config: Mapping[str, object], field: str, config_path: str) -> tuple[str, ...]:
+    value = config.get("patterns", [])
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise SpecResolutionError(config_path, field, "patterns 必须是字符串列表")
+    return tuple(item.replace("\\", "/") for item in value)
+
+
+def _non_injectable(mapping: Mapping[str, object], config_path: str) -> set[str]:
+    excluded: set[str] = set()
+    for domain in mapping:
+        config = _domain_config(mapping, domain, config_path)
+        entries = config.get("specs", [])
+        if not isinstance(entries, list):
+            raise SpecResolutionError(config_path, f"path_mapping.{domain}.specs", "必须是列表")
+        for entry in entries:
+            if isinstance(entry, dict) and entry.get("tags") == [] and isinstance(entry.get("path"), str):
+                excluded.add(str(entry["path"]).replace("\\", "/"))
+    return excluded
+
+
+def _load_metadata(path: Path) -> SpecMetadata:
+    mtime, size = _fingerprint(path, "spec")
+    cached = _metadata_cache.get(str(path))
+    if cached and cached[:2] == (mtime, size):
+        return cached[2]
+    metadata = load_spec_metadata(str(path))
+    _metadata_cache[str(path)] = (mtime, size, metadata)
+    return metadata
+
+
+def _candidate_scope(relative: str, patterns: Sequence[str], paths: Sequence[str]) -> tuple[str, tuple[str, ...]]:
+    if relative.startswith("_session/"):
+        return "task", ()
+    matched = tuple(path for path in paths if any(fnmatch.fnmatch(path, pattern) for pattern in patterns))
+    return ("path", matched) if matched else ("global", ())
+
+
+def _candidate_for(
+    path: Path,
+    spec_root: Path,
+    mapping: Mapping[str, object],
+    config_path: str,
+    stage: str,
+    paths: Sequence[str],
+) -> Optional[SpecCandidate]:
+    relative = path.relative_to(spec_root).as_posix()
+    metadata = _load_metadata(path)
+    if stage not in metadata.stages:
+        return None
+    domain = relative.split("/", 1)[0]
+    config = _domain_config(mapping, domain, config_path)
+    patterns = _patterns(config, f"path_mapping.{domain}.patterns", config_path)
+    scope, matched = _candidate_scope(relative, patterns, paths)
+    return SpecCandidate(metadata.id, relative, scope, SCOPE_PRIORITY[scope], matched, metadata)
+
+
+def resolve_candidates(root: str, stage: str, paths: Sequence[str]) -> tuple[SpecCandidate, ...]:
+    if stage not in ALLOWED_STAGES:
+        raise SpecResolutionError(root, "stage", f"不支持 stage: {stage!r}")
+    normalized_paths = tuple(path.replace("\\", "/") for path in paths)
+    config = _load_config(root)
+    config_path = str(Path(root) / ".code-flow" / "config.yml")
+    mapping = _path_mapping(config, config_path)
+    excluded = _non_injectable(mapping, config_path)
+    spec_root = Path(root) / ".code-flow" / "specs"
+    if not spec_root.is_dir():
+        raise SpecResolutionError(str(spec_root), "specs", "缺失 specs 目录")
+    candidates: list[SpecCandidate] = []
+    ids: dict[str, str] = {}
+    for path in sorted(spec_root.rglob("*.md")):
+        relative = path.relative_to(spec_root).as_posix()
+        if path.name == "_map.md" or relative.startswith("_session/") or relative in excluded:
+            continue
+        candidate = _candidate_for(path, spec_root, mapping, config_path, stage, normalized_paths)
+        if candidate is None:
+            continue
+        if candidate.spec_id in ids:
+            detail = f"重复 id {candidate.spec_id}: {ids[candidate.spec_id]}, {candidate.path}"
+            raise SpecResolutionError(str(spec_root), "spec_id", detail)
+        ids[candidate.spec_id] = candidate.path
+        candidates.append(candidate)
+    return tuple(sorted(candidates, key=lambda item: (-item.priority, item.path)))
+
+
+def _effective_enforcement(candidate: SpecCandidate, rule: SpecRule) -> str:
+    if candidate.metadata.enforcement == "advisory" and rule.enforcement == "required":
+        return "advisory"
+    return rule.enforcement
+
+
+def _rule_sources(candidates: Sequence[SpecCandidate]) -> dict[str, list[_RuleSource]]:
+    grouped: dict[str, list[_RuleSource]] = {}
+    for candidate in candidates:
+        for rule in candidate.metadata.rules:
+            source = _RuleSource(candidate, rule, _effective_enforcement(candidate, rule))
+            grouped.setdefault(rule.ref, []).append(source)
+    for sources in grouped.values():
+        sources.sort(key=lambda item: (-item.candidate.priority, item.candidate.path))
+    return grouped
+
+
+def _resolve_rule(ref: str, sources: Sequence[_RuleSource]) -> tuple[Optional[ResolvedRule], Optional[RuleConflict]]:
+    priority = sources[0].candidate.priority
+    top = tuple(source for source in sources if source.candidate.priority == priority)
+    required = tuple(source for source in top if source.enforcement == "required")
+    hashes = {source.rule.text_sha256 for source in required}
+    if len(required) > 1 and len(hashes) > 1:
+        conflict = RuleConflict(
+            ref,
+            priority,
+            tuple(source.candidate.spec_id for source in required),
+            tuple(source.rule.text_sha256 for source in required),
+        )
+        return None, conflict
+    winner = required[0] if required else top[0]
+    overridden = tuple(source.candidate.spec_id for source in sources if source is not winner)
+    resolved = ResolvedRule(
+        ref,
+        winner.candidate.spec_id,
+        winner.rule.text,
+        winner.enforcement,
+        winner.candidate.scope,
+        priority,
+        overridden,
+    )
+    return resolved, None
+
+
+def resolve_precedence(candidates: Sequence[SpecCandidate]) -> PrecedenceResolution:
+    effective: list[ResolvedRule] = []
+    conflicts: list[RuleConflict] = []
+    for ref, sources in sorted(_rule_sources(candidates).items()):
+        resolved, conflict = _resolve_rule(ref, sources)
+        if resolved is not None:
+            effective.append(resolved)
+        if conflict is not None:
+            conflicts.append(conflict)
+    return PrecedenceResolution(tuple(candidates), tuple(effective), tuple(conflicts))
+
+
+def build_candidate_page(candidates: Sequence[SpecCandidate], limit: int) -> CandidatePage:
+    if limit <= 0:
+        raise SpecResolutionError("<memory>", "limit", "必须大于 0")
+    items = tuple(candidates[:limit])
+    return CandidatePage(items=items, total=len(candidates), has_more=len(candidates) > limit)

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

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Context-first prompt router for task, path, and Catalog modes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import tempfile
+from typing import Mapping, Sequence
+
+from cf_core import assemble_context, build_effective_mapping, build_spec_catalog, load_config, parse_spec_frontmatter
+from cf_spec_context import ContextError, load_active_task, load_context
+from cf_spec_resolver import resolve_candidates
+from cf_spec_session import context_sha256, project_task_session
+
+
+@dataclass(frozen=True)
+class RouteResult:
+    mode: str
+    text: str
+    specs: tuple[str, ...]
+
+
+class RouterError(ValueError):
+    """Fail-closed routing error with a stable code."""
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        super().__init__(message)
+
+
+def _task_file(task_dir: Path, task_id: str) -> Path:
+    matches = []
+    for path in sorted(task_dir.glob("*.md")):
+        if path.name.endswith((".prd.md", ".design.md")):
+            continue
+        if f"## {task_id}:" in path.read_text(encoding="utf-8"):
+            matches.append(path)
+    if len(matches) != 1:
+        raise RouterError("task_file_ambiguous", f"{task_id} matched {len(matches)} task files")
+    return matches[0]
+
+
+def _active_route(root: str) -> RouteResult:
+    try:
+        active = load_active_task(root)
+        task_dir = (Path(root) / active.task_dir).resolve()
+        context = load_context(str(task_dir / "spec-context.yml"))
+    except (ContextError, OSError, ValueError) as exc:
+        raise RouterError("invalid_active_task", str(exc)) from exc
+    current_hash = context_sha256(context)
+    if current_hash != active.context_sha256:
+        raise RouterError("active_context_drift", "active marker Context hash does not match")
+    projection = project_task_session(context, str(_task_file(task_dir, active.task_id)), active.task_id)
+    if projection.truncated:
+        raise RouterError("task_projection_truncated", "split the TASK before coding")
+    refs = tuple(binding.spec_id for binding in context.bindings)
+    return RouteResult("task", projection.text, refs)
+
+
+def _read_candidates(root: str, paths: Sequence[str]) -> RouteResult:
+    try:
+        candidates = resolve_candidates(root, "code", tuple(paths))
+    except ValueError as exc:
+        raise RouterError("invalid_spec_metadata", str(exc)) from exc
+    specs = []
+    for candidate in candidates:
+        target = Path(root) / ".code-flow/specs" / candidate.path
+        try:
+            raw = target.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise RouterError("spec_read_failed", f"{candidate.path}: {exc}") from exc
+        unused_frontmatter, content = parse_spec_frontmatter(raw)
+        del unused_frontmatter
+        specs.append({"path": candidate.path, "content": content.strip(), "tier": 1})
+    text = assemble_context(specs, "## Active Specs (path-mapped)") if specs else ""
+    return RouteResult("path", text, tuple(item.path for item in candidates))
+
+
+def _catalog_path(root: str) -> Path:
+    return Path(root) / ".code-flow/.catalog-state.json"
+
+
+def _load_catalog_state(root: str) -> dict[str, object]:
+    path = _catalog_path(root)
+    if not path.exists():
+        return {"version": 1, "session_id": "", "prompt_count": 0, "last_emitted": 0}
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RouterError("invalid_catalog_state", str(exc)) from exc
+    if not isinstance(value, dict) or value.get("version") != 1:
+        raise RouterError("invalid_catalog_state", "Catalog state schema must be version 1")
+    return value
+
+
+def _save_catalog_state(root: str, state: Mapping[str, object]) -> None:
+    path = _catalog_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = ""
+    try:
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
+            temporary = handle.name
+            json.dump(state, handle, ensure_ascii=False)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except OSError as exc:
+        if temporary and Path(temporary).exists():
+            Path(temporary).unlink()
+        raise RouterError("catalog_state_write_failed", str(exc)) from exc
+
+
+def _catalog_route(root: str, session_id: str, config: Mapping[str, object]) -> RouteResult:
+    state = _load_catalog_state(root)
+    same_session = state.get("session_id") == session_id
+    count = int(state.get("prompt_count", 0)) + 1 if same_session else 1
+    last = int(state.get("last_emitted", 0)) if same_session else 0
+    workflow = config.get("spec_workflow") if isinstance(config.get("spec_workflow"), dict) else {}
+    catalog_config = workflow.get("catalog") if isinstance(workflow.get("catalog"), dict) else {}
+    window = int(catalog_config.get("dedup_window", 5))
+    due = window <= 0 or last == 0 or count - last >= window
+    next_state = {"version": 1, "session_id": session_id, "prompt_count": count, "last_emitted": count if due else last}
+    _save_catalog_state(root, next_state)
+    if not due:
+        return RouteResult("catalog", "", ())
+    budget = config.get("budget") if isinstance(config.get("budget"), dict) else {}
+    maximum = int(budget.get("catalog_max", 200))
+    mapping = build_effective_mapping(root, config.get("path_mapping") or {})
+    return RouteResult("catalog", build_spec_catalog(root, mapping, maximum), ())
+
+
+def route_prompt(root: str, paths: Sequence[str], session_id: str) -> RouteResult:
+    """Choose exactly one route; an invalid active marker never falls back."""
+    marker = Path(root) / ".code-flow/.active-task.json"
+    if marker.exists():
+        return _active_route(root)
+    config = load_config(root)
+    if not config:
+        return RouteResult("none", "", ())
+    if paths:
+        return _read_candidates(root, paths)
+    return _catalog_route(root, session_id, config)

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Project one TASK's bound rules into a bounded session document."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path
+import re
+import sys
+from typing import IO, Mapping, Optional, Sequence
+
+import yaml
+
+from cf_spec_context import RuleBinding, SpecContext, context_to_data, load_context
+
+
+@dataclass(frozen=True)
+class SessionProjection:
+    text: str
+    included_rules: int
+    total_rules: int
+    truncated: bool
+
+
+def context_sha256(context: SpecContext) -> str:
+    data = yaml.safe_dump(context_to_data(context), sort_keys=True, allow_unicode=True).encode()
+    return hashlib.sha256(data).hexdigest()
+
+
+def _task_section(text: str, task_id: str) -> str:
+    match = re.search(rf"(?m)^## {re.escape(task_id)}:[^\n]*$", text)
+    if match is None:
+        raise ValueError(f"task_not_found: {task_id}")
+    following = re.search(r"(?m)^## TASK-\d+:", text[match.end():])
+    end = match.end() + following.start() if following else len(text)
+    return text[match.start():end]
+
+
+def _refs(section: str) -> tuple[str, ...]:
+    match = re.search(r"(?m)^- \*\*Spec-Refs\*\*:\s*(.+)$", section)
+    if match is None:
+        raise ValueError("spec_refs_missing")
+    return tuple(item.strip() for item in match.group(1).split(",") if item.strip())
+
+
+def _rule_index(context: SpecContext) -> Mapping[str, RuleBinding]:
+    return {
+        f"{binding.spec_id}#{rule.ref}": rule
+        for binding in context.bindings
+        for rule in binding.rules
+    }
+
+
+def _acceptance_contract(section: str) -> str:
+    match = re.search(r"(?ms)^### Acceptance Contract\s*$\n(.*?)(?=^### |^## |\Z)", section)
+    if match is None:
+        raise ValueError("acceptance_contract_missing")
+    return match.group(1).strip()
+
+
+def _rule_line(ref: str, rule: RuleBinding, compact: bool = False) -> str:
+    hashes = f"rule_sha256={rule.text_sha256} verifier={rule.verifier_ref}"
+    if compact:
+        return f"- `{ref}` {hashes}\n"
+    artifacts = sorted({item.artifact for status in rule.stage_status.values() for item in status.refs})
+    return f"- `{ref}`: {rule.summary}\n  - {hashes}; artifacts={','.join(artifacts) or 'none'}\n"
+
+
+def project_task_session(
+    context: SpecContext, task_file: str, task_id: str, max_chars: int = 4000
+) -> SessionProjection:
+    section = _task_section(Path(task_file).read_text(encoding="utf-8"), task_id)
+    refs = _refs(section)
+    index = _rule_index(context)
+    missing = tuple(ref for ref in refs if ref not in index)
+    if missing:
+        raise ValueError(f"unknown_spec_refs: {', '.join(missing)}")
+    acceptance = _acceptance_contract(section)
+    header = f"# {task_id} Spec Context\n\n- Context-SHA256: `{context_sha256(context)}`\n\n## Required Rules\n"
+    footer = f"\n## Acceptance Contract\n{acceptance}\n"
+    lines: list[str] = []
+    for ref in refs:
+        candidate = _rule_line(ref, index[ref])
+        if len(header + "".join(lines) + candidate + footer) > max_chars:
+            break
+        lines.append(candidate)
+    truncated = len(lines) < len(refs)
+    if truncated:
+        footer = "\n> 投影超过预算；完整 Context 保留在需求目录，请拆分 TASK。\n" + footer
+    text = (header + "".join(lines) + footer)[:max_chars]
+    return SessionProjection(text, len(lines), len(refs), truncated)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cf_spec_session.py")
+    parser.add_argument("--task-dir", required=True)
+    parser.add_argument("--task-file", required=True)
+    parser.add_argument("--task", required=True)
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--budget", type=int, default=4000)
+    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 = project_task_session(context, args.task_file, args.task, args.budget)
+        Path(args.output).write_text(result.text, encoding="utf-8")
+        stdout.write(json.dumps(result.__dict__, ensure_ascii=False))
+        return 0
+    except Exception as exc:
+        stdout.write(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())