@michaelxwb/code-flow 0.6.5 → 1.0.0

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

@@ -1,347 +0,0 @@
-#!/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
-
-from cf_spec_metadata import (
-    ALLOWED_STAGES,
-    SpecHeader,
-    SpecMetadata,
-    SpecRule,
-    load_spec_header,
-    load_spec_metadata,
-)
-
-
-SCOPE_PRIORITY = {"unmatched": 0, "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 SpecCandidateHeader:
-    spec_id: str
-    path: str
-    scope: str
-    priority: int
-    matched_paths: tuple[str, ...]
-    enforcement: str
-
-
-@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]:
-    import yaml
-    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))
-    if matched:
-        return "path", matched
-    # A domain without patterns is truly global. A domain WITH patterns that
-    # match nothing is irrelevant to these paths ("unmatched") — discovery
-    # keeps it, but injection and scope expansion must not consume it.
-    return ("global", ()) if not patterns else ("unmatched", ())
-
-
-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 _candidate_header_for(
-    path: Path,
-    spec_root: Path,
-    mapping: Mapping[str, object],
-    config_path: str,
-    stage: str,
-    paths: Sequence[str],
-) -> Optional[SpecCandidateHeader]:
-    relative = path.relative_to(spec_root).as_posix()
-    header: SpecHeader = load_spec_header(str(path))
-    if stage not in header.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 SpecCandidateHeader(
-        header.id, relative, scope, SCOPE_PRIORITY[scope], matched, header.enforcement
-    )
-
-
-def _spec_paths(spec_root: Path, excluded: set[str]) -> tuple[Path, ...]:
-    result: list[Path] = []
-    for path in sorted(spec_root.rglob("*.md")):
-        relative = path.relative_to(spec_root).as_posix()
-        if path.name != "_map.md" and not relative.startswith("_session/") and relative not in excluded:
-            result.append(path)
-    return tuple(result)
-
-
-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 _spec_paths(spec_root, excluded):
-        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 resolve_candidate_headers(
-    root: str, stage: str, paths: Sequence[str]
-) -> tuple[SpecCandidateHeader, ...]:
-    """Resolve candidates from routing frontmatter without parsing bodies or hashes."""
-    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[SpecCandidateHeader] = []
-    ids: dict[str, str] = {}
-    for path in _spec_paths(spec_root, excluded):
-        candidate = _candidate_header_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

@@ -1,244 +0,0 @@
-#!/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, Optional, Sequence
-
-from cf_core import (
-    assemble_context,
-    build_effective_mapping,
-    build_spec_catalog,
-    compress_content,
-    load_config,
-    parse_spec_frontmatter,
-    resolve_compress,
-)
-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
-
-
-_PROJECTION_CACHE_PATH = ".code-flow/.task-projection-state.json"
-
-
-@dataclass(frozen=True)
-class RouteResult:
-    mode: str
-    text: str
-    specs: tuple[str, ...]
-    context_sha256: Optional[str] = None
-
-
-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 _projection_cache_path(root: str) -> Path:
-    return Path(root) / _PROJECTION_CACHE_PATH
-
-
-def _load_projection_cache(root: str) -> Mapping[str, object]:
-    try:
-        value = json.loads(_projection_cache_path(root).read_text(encoding="utf-8"))
-    except (OSError, UnicodeError, json.JSONDecodeError):
-        return {}
-    return value if isinstance(value, dict) else {}
-
-
-def _cached_projection(
-    root: str, task_dir: Path, task_id: str, current_hash: str
-) -> Optional[tuple[str, bool]]:
-    cache = _load_projection_cache(root)
-    if (
-        cache.get("version") != 1
-        or cache.get("task_id") != task_id
-        or cache.get("context_sha256") != current_hash
-        or not isinstance(cache.get("task_file"), str)
-        or not isinstance(cache.get("text"), str)
-        or not isinstance(cache.get("truncated"), bool)
-    ):
-        return None
-    task_file = Path(str(cache["task_file"]))
-    if task_file.parent != task_dir or not task_file.is_file():
-        return None
-    try:
-        directory_mtime = task_dir.stat().st_mtime_ns
-        task_mtime = task_file.stat().st_mtime_ns
-    except OSError:
-        return None
-    if cache.get("task_dir_mtime_ns") != directory_mtime or cache.get("task_mtime_ns") != task_mtime:
-        return None
-    return str(cache["text"]), bool(cache["truncated"])
-
-
-def _save_projection_cache(
-    root: str,
-    task_dir: Path,
-    task_file: Path,
-    task_id: str,
-    current_hash: str,
-    text: str,
-    truncated: bool,
-) -> None:
-    try:
-        payload = {
-            "version": 1,
-            "task_id": task_id,
-            "context_sha256": current_hash,
-            "task_file": str(task_file),
-            "task_dir_mtime_ns": task_dir.stat().st_mtime_ns,
-            "task_mtime_ns": task_file.stat().st_mtime_ns,
-            "text": text,
-            "truncated": truncated,
-        }
-        path = _projection_cache_path(root)
-        path.parent.mkdir(parents=True, exist_ok=True)
-        temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
-        temporary.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
-        os.replace(temporary, path)
-    except (OSError, TypeError, UnicodeError):
-        if "temporary" in locals() and temporary.exists():
-            try:
-                temporary.unlink()
-            except OSError:
-                pass
-
-
-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; run `cf_spec_context.py refresh --task-dir <dir> --root <root> --json` to re-sync it (refresh updates the marker hash), or `active doctor --resync` with the hash from `status --json`",
-        )
-    cached = _cached_projection(root, task_dir, active.task_id, current_hash)
-    if cached is None:
-        task_file = _task_file(task_dir, active.task_id)
-        projection = project_task_session(context, str(task_file), active.task_id)
-        _save_projection_cache(
-            root, task_dir, task_file, active.task_id, current_hash, projection.text, projection.truncated
-        )
-        text, truncated = projection.text, projection.truncated
-    else:
-        text, truncated = cached
-    if truncated:
-        raise RouterError("task_projection_truncated", "split the TASK before coding")
-    refs = tuple(binding.spec_id for binding in context.bindings)
-    return RouteResult("task", text, refs, current_hash)
-
-
-def _read_candidates(root: str, paths: Sequence[str], compress: bool = True) -> 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:
-        if candidate.scope == "unmatched":
-            continue
-        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
-        final_content = compress_content(content.strip()) if compress else content.strip()
-        specs.append({"path": candidate.path, "content": final_content, "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:
-        quality = config.get("quality_loop")
-        return _read_candidates(root, paths, resolve_compress(quality if isinstance(quality, dict) else {}))
-    return _catalog_route(root, session_id, config)