@michaelxwb/code-flow 0.8.1 → 1.0.0

package/src/core/code-flow/scripts/codeflow/core/cf_core.py

@@ -1,609 +0,0 @@
-#!/usr/bin/env python3
-import fnmatch
-import json
-import os
-import re
-import sys
-import time
-
-from codeflow.core import cf_log
-from codeflow.core.cf_markdown import parse_frontmatter
-
-# --- Config cache (fix #3: avoid re-parsing YAML on every hook call) ---
-
-_config_cache: dict = {}
-_spec_domains_cache: dict = {}
-_effective_mapping_cache: dict = {}
-_ext_set_cache: dict = {}
-
-
-class ConfigError(ValueError):
-    """An existing project configuration cannot be read or validated."""
-
-    code = "invalid_config"
-
-
-def project_instruction_file(project_root: str, platform: str = "") -> str:
-    """Select the installed platform's instruction file, with legacy fallback."""
-    names = ("CLAUDE.md", "AGENTS.md") if platform in ("claude", "costrict") else ("AGENTS.md", "CLAUDE.md")
-    return next((name for name in names if os.path.isfile(os.path.join(project_root, name))), names[0])
-
-
-def load_config(project_root: str) -> dict:
-    config_path = os.path.join(project_root, ".code-flow", "config.yml")
-    if not os.path.exists(config_path):
-        return {}
-    try:
-        info = os.stat(config_path)
-        signature = (info.st_mtime_ns, info.st_ctime_ns, info.st_size)
-    except OSError as exc:
-        raise ConfigError(f"{config_path}: {exc}") from exc
-    cached = _config_cache.get(config_path)
-    if cached and cached["mtime"] == signature:
-        return cached["data"]
-    try:
-        import yaml
-    except ImportError as exc:
-        raise ConfigError("PyYAML is required to read code-flow configuration") from exc
-    try:
-        with open(config_path, "r", encoding="utf-8") as file:
-            data = yaml.safe_load(file)
-        if not isinstance(data, dict):
-            raise ConfigError(f"{config_path}: configuration must be a YAML mapping")
-        result = data
-        _config_cache[config_path] = {"mtime": signature, "data": result}
-        return result
-    except (OSError, UnicodeError, yaml.YAMLError) as exc:
-        raise ConfigError(f"{config_path}: {exc}") from exc
-
-
-def estimate_tokens(text: str) -> int:
-    return len(text) // 4
-
-
-def normalize_path(path: str) -> str:
-    # Unconditional backslash replacement, not `os.sep`, so paths pasted from
-    # a Windows machine into a prompt on macOS/Linux still normalize correctly.
-    # On Windows `os.sep == '\\'`, so behavior there is unchanged.
-    return path.replace("\\", "/")
-
-
-def effective_project_root(project_root: str, absolute_path: str) -> str:
-    """Resolve the project root that owns an edited file.
-
-    Parallel subagents edit `.code-flow/worktrees/<run>/<TASK>/...`; the nearest
-    `.code-flow` ancestor is that worktree's root, not the session root. Files
-    outside the session root and unresolvable paths fall back to `project_root`.
-    Lexical `abspath` (not `realpath`) keeps caller/returned paths in the same
-    coordinates (macOS /var ↔ /private/var symlink).
-    """
-    root = os.path.abspath(project_root)
-    target = os.path.abspath(absolute_path) if absolute_path else root
-    if target != root and not target.startswith(root + os.sep):
-        return root
-    current = target
-    while True:
-        if os.path.isdir(os.path.join(current, ".code-flow")):
-            return current
-        if current == root:
-            return root
-        parent = os.path.dirname(current)
-        if parent == current:
-            return root
-        current = parent
-
-
-def _spec_path_from_entry(entry) -> str:
-    cfg = normalize_spec_entry(entry)
-    return normalize_path(cfg.get("path", ""))
-
-
-def discover_spec_domains(project_root: str) -> dict:
-    specs_root = os.path.join(project_root, ".code-flow", "specs")
-    discovered = {}
-    if not os.path.isdir(specs_root):
-        _spec_domains_cache[project_root] = discovered
-        return discovered
-
-    for root, _, files in os.walk(specs_root):
-        for filename in files:
-            if not filename.endswith(".md"):
-                continue
-            full_path = os.path.join(root, filename)
-            rel = normalize_path(os.path.relpath(full_path, specs_root))
-            parts = rel.split("/", 1)
-            if len(parts) < 2:
-                continue
-            domain = parts[0]
-            discovered.setdefault(domain, []).append(rel)
-
-    for domain in discovered:
-        discovered[domain] = sorted(set(discovered[domain]))
-    _spec_domains_cache[project_root] = discovered
-    return discovered
-
-
-def _default_spec_entry(rel: str) -> dict:
-    tier = 0 if rel.endswith("/_map.md") else 1
-    # shared/ 下非 _map.md 的文件是供 cf-task:align / cf-task:prd 命令
-    # 显式 Read 的模板，不是约束规范，禁止通配符自动注入。
-    if rel.startswith("shared/") and not rel.endswith("/_map.md"):
-        return {"path": rel, "tags": [], "tier": tier}
-    return {"path": rel, "tags": ["*"], "tier": tier}
-
-
-def _mapping_signature(mapping: dict) -> str:
-    """Content signature for the mapping cache.
-
-    `id(mapping)` keys were reused after GC, potentially serving a mapping
-    built from stale config contents. Hash the JSON projection instead.
-    """
-    try:
-        return json.dumps(mapping or {}, ensure_ascii=False, sort_keys=True, default=str)
-    except (TypeError, ValueError):
-        return ""
-
-
-def build_effective_mapping(project_root: str, mapping: dict) -> dict:
-    discovered = discover_spec_domains(project_root)
-    cache_key = (project_root, _mapping_signature(mapping), _mapping_signature(discovered))
-    cached = _effective_mapping_cache.get(cache_key)
-    if cached is not None:
-        return cached
-    effective = {}
-
-    for domain, rel_paths in discovered.items():
-        source_cfg = mapping.get(domain) or {}
-        normalized_specs = []
-        seen = set()
-
-        for entry in source_cfg.get("specs") or []:
-            rel = _spec_path_from_entry(entry)
-            if not rel or rel in seen:
-                continue
-            normalized_specs.append(normalize_spec_entry(entry))
-            seen.add(rel)
-
-        for rel in rel_paths:
-            if rel in seen:
-                continue
-            normalized_specs.append(_default_spec_entry(rel))
-            seen.add(rel)
-
-        effective[domain] = {
-            "patterns": source_cfg.get("patterns") or [],
-            "specs": normalized_specs,
-        }
-
-    for domain, source_cfg in (mapping or {}).items():
-        if domain in effective:
-            continue
-        normalized_specs = []
-        seen = set()
-        for entry in source_cfg.get("specs") or []:
-            rel = _spec_path_from_entry(entry)
-            if not rel or rel in seen:
-                continue
-            normalized_specs.append(normalize_spec_entry(entry))
-            seen.add(rel)
-        effective[domain] = {
-            "patterns": source_cfg.get("patterns") or [],
-            "specs": normalized_specs,
-        }
-
-    _effective_mapping_cache[cache_key] = effective
-    return effective
-
-
-def is_code_file(rel_path: str, runtime_config: dict) -> bool:
-    rel_path = normalize_path(rel_path)
-    for pattern in runtime_config.get("skip_paths") or []:
-        if fnmatch.fnmatch(rel_path, pattern):
-            return False
-    _, ext = os.path.splitext(rel_path)
-    if ext in (runtime_config.get("skip_extensions") or []):
-        return False
-    code_exts = runtime_config.get("code_extensions") or []
-    # Content key: id() reuse after GC could serve a stale extension set.
-    ext_key = tuple(code_exts)
-    ext_set = _ext_set_cache.get(ext_key)
-    if ext_set is None:
-        ext_set = frozenset(code_exts)
-        _ext_set_cache[ext_key] = ext_set
-    return ext in ext_set
-
-
-def match_domains(rel_path: str, mapping: dict) -> list:
-    rel_path = normalize_path(rel_path)
-    domains = []
-    for domain, cfg in (mapping or {}).items():
-        patterns = cfg.get("patterns") or []
-        for pattern in patterns:
-            if fnmatch.fnmatch(rel_path, pattern):
-                domains.append(domain)
-                break
-    return domains
-
-
-def normalize_spec_entry(entry) -> dict:
-    """Normalize spec config entry. Supports both old (string) and new (dict) format."""
-    if isinstance(entry, str):
-        return {"path": entry, "tags": ["*"], "tier": 1}
-    if isinstance(entry, dict):
-        return {
-            "path": entry.get("path", ""),
-            "tags": entry.get("tags", ["*"]),
-            "tier": entry.get("tier", 1),
-        }
-    return {}
-
-
-_BULLET_PREFIXES = ("- ", "* ", "+ ")
-_COMPRESS_HTML_RE = re.compile(r"<!--.*?-->", re.DOTALL)
-_COMPRESS_TRAILING_WS_RE = re.compile(r"[ \t]+$", re.MULTILINE)
-_COMPRESS_BLANK_LINES_RE = re.compile(r"\n{3,}")
-
-
-def compress_content(text: str) -> str:
-    """Lossless compression for spec content injected at Hook time.
-
-    Five conservative, semantics-preserving transforms:
-    1. Strip multi-line HTML comments ``<!-- ... -->``.
-    2. Strip trailing whitespace on every line.
-    3. Collapse runs of 2+ blank lines into a single blank line.
-    4. Drop a bullet line ( ``-`` / ``*`` / ``+`` ) equal to the previous line.
-    5. Strip leading/trailing blank lines of the whole text.
-
-    Idempotent: ``compress_content(compress_content(x)) == compress_content(x)``.
-    On any exception, log to stderr and return the original text so Hook
-    injection is never broken by a compression bug.
-    """
-    if not isinstance(text, str) or not text:
-        return text
-    try:
-        result = _COMPRESS_HTML_RE.sub("", text)
-        result = _COMPRESS_TRAILING_WS_RE.sub("", result)
-        result = _COMPRESS_BLANK_LINES_RE.sub("\n\n", result)
-        lines = result.split("\n")
-        out_lines: list = []
-        prev_line: str = ""
-        in_fence = False
-        for line in lines:
-            stripped = line.lstrip()
-            if stripped.startswith("```"):
-                in_fence = not in_fence
-            # never dedup inside fenced code blocks — ✅/❌ example snippets
-            # may legitimately repeat identical bullet-looking lines (FEAT-07)
-            is_bullet = (not in_fence) and stripped.startswith(_BULLET_PREFIXES)
-            if is_bullet and out_lines and line == prev_line:
-                continue
-            out_lines.append(line)
-            prev_line = line
-        result = "\n".join(out_lines)
-        return result.strip()
-    except Exception as exc:
-        _log(f"compress_content error: {exc}")
-        return text
-
-
-def non_injectable_specs(effective_mapping: dict) -> set:
-    """tags: [] 的命令专用模板（如 shared 的 PRD/设计模板）——永不自动注入，
-    预算统计（cf-stats/cf-scan）必须排除，避免利用率虚高。"""
-    excluded = set()
-    for domain_cfg in (effective_mapping or {}).values():
-        for entry in (domain_cfg or {}).get("specs") or []:
-            cfg = normalize_spec_entry(entry)
-            if cfg.get("path") and not cfg.get("tags"):
-                excluded.add(cfg["path"])
-    return excluded
-
-
-def resolve_quality_loop(config: dict) -> dict:
-    """Resolve quality_loop feature switches with safe defaults (RULE-06).
-
-    Master `enabled`: only literal True enables — missing/other keeps the
-    pre-0.6 behavior for upgraded users; new inits opt in via the config
-    template. Sub-switches follow the master and only literal False disables
-    them (resolve_compress philosophy).
-    """
-    if not isinstance(config, dict):
-        return {"enabled": False, "post_check": False,
-                "stop_check": False, "finish_check": False,
-                "correction_capture": False,
-                "compress_reminder": False,
-                "heavy_at_finish": False,
-                "finish_verifier_budget": 300.0}
-    cfg = config.get("quality_loop")
-    cfg = cfg if isinstance(cfg, dict) else {}
-    enabled = cfg.get("enabled") is True
-
-    def _sub(key: str) -> bool:
-        return enabled and cfg.get(key) is not False
-
-    # 任务级 verifier 执行预算（秒）：超预算的 command/test verifier 延后到
-    # 需求级 verify-e2e；0 = 不限制（恢复旧行为）。非法值回落默认 300。
-    budget = cfg.get("finish_verifier_budget", 300)
-    if isinstance(budget, bool) or not isinstance(budget, (int, float)) or budget < 0 or budget != budget:
-        budget = 300.0
-
-    return {
-        "enabled": enabled,
-        "post_check": _sub("post_check"),
-        "stop_check": _sub("stop_check"),
-        "finish_check": _sub("finish_check"),
-        "correction_capture": _sub("correction_capture"),
-        "compress_reminder": _sub("compress_reminder"),
-        # heavy validator 默认只在归档 cf_validation / /cf-validate 全量执行
-        "heavy_at_finish": enabled and cfg.get("heavy_at_finish") is True,
-        "finish_verifier_budget": float(budget),
-    }
-
-
-ENFORCEMENT_MODES = frozenset(("required", "warn", "inject"))
-
-
-def resolve_enforcement(config: dict) -> str:
-    """Project-wide Spec Workflow enforcement tier (light-mode ladder).
-
-    required — full fail-closed gates (default; upgraded projects keep it);
-    warn    — gates run but only log/report, never block the session;
-    inject  — routing/injection only; gates and blocks are disabled.
-    Missing or invalid values fail closed to "required".
-    """
-    if not isinstance(config, dict):
-        return "required"
-    workflow = config.get("spec_workflow")
-    workflow = workflow if isinstance(workflow, dict) else {}
-    value = workflow.get("enforcement")
-    if isinstance(value, str) and value in ENFORCEMENT_MODES:
-        return value
-    return "required"
-
-
-def parse_spec_frontmatter(content: str) -> tuple:
-    """Split optional YAML frontmatter from spec content → (meta, body).
-
-    Flat `key: value` parsing keeps the hook hot path free of pyyaml; content
-    without frontmatter returns ({}, content) unchanged.
-    """
-    return parse_frontmatter(content)
-
-
-def spec_description(content: str) -> str:
-    """One-line applicability summary for the spec catalog.
-
-    Priority: frontmatter `description:` → first blockquote line → H1 text.
-    Returns "" when none is found (cf-scan flags those specs).
-    """
-    meta, body = parse_spec_frontmatter(content)
-    desc = (meta.get("description") or "").strip()
-    if desc:
-        return desc
-    h1 = ""
-    for line in body.splitlines():
-        stripped = line.strip()
-        if stripped.startswith(">"):
-            return stripped.lstrip("> ").strip()
-        if not h1 and stripped.startswith("# "):
-            h1 = stripped[2:].strip()
-    return h1
-
-
-_catalog_cache: dict = {}
-
-CATALOG_HEADER = (
-    "## Spec Catalog (code-flow)\n\n"
-    "以下规范文件位于 `.code-flow/specs/`。开始编码或修改文件前，"
-    "必须先 Read 与当前任务场景匹配的 spec 全文；与场景无关的不要读取。"
-)
-
-
-class CatalogBudgetError(ConfigError):
-    """Catalog cannot fit its mandatory header and complete-list notice."""
-
-    def __init__(self, minimum: int) -> None:
-        self.minimum = minimum
-        super().__init__(f"catalog_max is too small; minimum is {minimum} estimated tokens")
-
-
-def _catalog_entries(project_root: str, effective_mapping: dict) -> list:
-    """Collect injectable specs as (tier, rel_path, abs_path) sorted tier1-first."""
-    specs_root = os.path.join(project_root, ".code-flow", "specs")
-    entries = []
-    for domain in sorted(effective_mapping.keys()):
-        for entry in (effective_mapping[domain] or {}).get("specs") or []:
-            cfg = normalize_spec_entry(entry)
-            rel = cfg.get("path", "")
-            # tags: [] marks command-only templates — never advertised either
-            if not rel or rel.startswith("_session/") or not cfg.get("tags"):
-                continue
-            entries.append((cfg.get("tier", 1), rel, os.path.join(specs_root, rel)))
-    # Tier 1 constraints first so budget truncation drops navigation maps first
-    entries.sort(key=lambda item: (item[0] != 1, item[1]))
-    return entries
-
-
-def _catalog_lines(entries: list[tuple[int, str, str]]) -> list[str]:
-    lines = []
-    for tier, rel, abs_path in entries:
-        try:
-            with open(abs_path, "r", encoding="utf-8") as f:
-                desc = spec_description(f.read())
-        except (OSError, UnicodeError) as exc:
-            _log(f"Spec Catalog read failed: {rel}: {exc}")
-            continue
-        suffix = "（导航地图）" if tier == 0 else ""
-        lines.append(f"- `{rel}` — {desc or '(no description)'}{suffix}")
-    return lines
-
-
-def _bounded_catalog(lines: list[str], maximum: int) -> str:
-    catalog = CATALOG_HEADER
-    included = 0
-    def footer(count: int) -> str:
-        if count == len(lines):
-            return ""
-        return (f"\n已展示 {count}/{len(lines)} 项；其余规范请运行 "
-                "`code-flow spec catalog --root . --stage code --json` 获取。")
-    for line in lines:
-        candidate = catalog + "\n" + line
-        if estimate_tokens(candidate + footer(included + 1)) > maximum:
-            continue
-        catalog = candidate
-        included += 1
-    text = catalog + footer(included)
-    if estimate_tokens(text) > maximum:
-        raise CatalogBudgetError(estimate_tokens(text))
-    return text
-
-
-def build_spec_catalog(project_root: str, effective_mapping: dict, catalog_max: int = 200) -> str:
-    """Publish bounded navigation with an explicit complete-catalog entry point."""
-    entries = _catalog_entries(project_root, effective_mapping)
-    if not entries:
-        return ""
-    signature = []
-    for _, _, path in entries:
-        try:
-            info = os.stat(path)
-            signature.append((path, info.st_mtime_ns, info.st_ctime_ns, info.st_size))
-        except OSError:
-            signature.append((path, 0, 0, 0))
-    cached = _catalog_cache.get(project_root)
-    if cached and cached["signature"] == signature and cached["catalog_max"] == catalog_max:
-        return cached["catalog"]
-    lines = _catalog_lines(entries)
-    catalog = _bounded_catalog(lines, catalog_max) if lines else ""
-    _catalog_cache[project_root] = {"signature": signature, "catalog_max": catalog_max, "catalog": catalog}
-    return catalog
-
-
-def catalog_omissions(project_root: str, effective_mapping: dict, catalog_max: int) -> dict[str, object]:
-    """Compute omissions from the actual bounded catalog without changing its ordering."""
-    from collections import Counter
-    lines = _catalog_lines(_catalog_entries(project_root, effective_mapping))
-    text = build_spec_catalog(project_root, effective_mapping, catalog_max)
-    remaining = Counter(line for line in text.splitlines() if line.startswith('- `'))
-    dropped: list[str] = []
-    for line in lines:
-        if remaining[line]:
-            remaining[line] -= 1
-        else:
-            dropped.append(line.split('`', 2)[1])
-    return {"dropped_count": len(dropped),
-            "dropped_domains": sorted({path.split('/', 1)[0] for path in dropped})}
-
-
-def assemble_context(specs: list, heading: str) -> str:
-    parts = [heading]
-    parts.append("以上规范是本次开发的约束条件，生成代码必须遵循。")
-    parts.append("---")
-    tier0 = [s for s in specs if s.get("tier", 1) == 0]
-    tier1 = [s for s in specs if s.get("tier", 1) != 0]
-
-    if tier0:
-        parts.append("### Navigation (Retrieval Map)")
-        for spec in tier0:
-            parts.append(f"#### {spec['path']}")
-            parts.append(spec["content"])
-
-    if tier1:
-        parts.append("### Constraints (matched by file context)")
-        for spec in tier1:
-            parts.append(f"#### {spec['path']}")
-            parts.append(spec["content"])
-
-    return "\n\n".join(parts)
-
-
-def _log(msg: str) -> None:
-    """Diagnostics go to stderr through the shared L0 writer (fix #9)."""
-    cf_log.warn(msg)
-
-
-_PROCESS_START = time.monotonic()
-
-
-def timing_log(name: str) -> None:
-    """Emit process-elapsed ms to stderr only when CF_DEBUG=1 (diagnostics).
-
-    Never touches stdout, so the hook JSON protocol is unaffected; a default
-    run pays one env lookup and no IO.
-    """
-    if os.environ.get("CF_DEBUG") == "1":
-        _log(f"{name}: {int((time.monotonic() - _PROCESS_START) * 1000)}ms")
-
-
-def phase_timing(name: str, started: float) -> None:
-    """Emit a named phase duration to stderr when CF_DEBUG=1."""
-    if os.environ.get("CF_DEBUG") == "1":
-        _log(f"cf_phase {name}: {int((time.monotonic() - started) * 1000)}ms")
-
-
-def ensure_utf8_io() -> None:
-    """Force stdin/stdout/stderr to UTF-8 so Windows hooks don't mojibake.
-
-    Claude Code/Codex pass UTF-8 JSON over stdin and expect UTF-8 over stdout,
-    but Python on Windows defaults streams to the system codepage (cp936 on
-    zh-CN locales). That corrupts CJK content end-to-end — both the parsed
-    prompt and anything written back, including the CF_DEBUG=1 .debug.log.
-    ``reconfigure`` is a TextIOWrapper-only method, so test doubles built on
-    ``io.StringIO`` are silently skipped.
-    """
-    for stream in (sys.stdin, sys.stdout, sys.stderr):
-        reconfigure = getattr(stream, "reconfigure", None)
-        if callable(reconfigure):
-            try:
-                reconfigure(encoding="utf-8")
-            except Exception:
-                pass
-
-
-def resolve_compress(quality_config: dict) -> bool:
-    """Return whether Hook-time spec compression is enabled.
-
-    Only a literal ``False`` turns it off; missing, ``None``, or any
-    non-bool value falls back to ``True`` so upgrades pick up compression
-    without requiring a config edit.
-    """
-    if not isinstance(quality_config, dict):
-        return True
-    value = quality_config.get("compress")
-    if value is False:
-        return False
-    return True
-
-
-def resolve_session_id(hook_data: dict) -> str:
-    """Derive a session id consistent across PreToolUse / UserPromptSubmit hooks.
-
-    Prefer the platform-provided id so prompt, edit, feedback, and stop events
-    share one trace. Fall back to the PID for older runtimes and unit tests.
-    """
-    if isinstance(hook_data, dict):
-        sid = hook_data.get("session_id")
-        if sid:
-            return str(sid)
-    return str(os.getpid())
-
-
-def debug_log(msg: str, project_root: str = None) -> None:
-    """Append a debug line to .code-flow/.debug.log when CF_DEBUG=1.
-    Silent no-op unless CF_DEBUG=1 so default runs don't pay any IO cost.
-    Writes to a dotfile so cf_scan.py skips it and processDir upgrades don't overwrite it.
-    Failures (missing dir, unwritable fs) are swallowed on purpose
-    — we must never break the hook JSON protocol over logging.
-    """
-    if os.environ.get("CF_DEBUG") != "1":
-        return
-    root = project_root or os.getcwd()
-    debug_dir = os.path.join(root, ".code-flow")
-    log_path = os.path.join(debug_dir, ".debug.log")
-    try:
-        os.makedirs(debug_dir, exist_ok=True)
-        from datetime import datetime
-        ts = datetime.now().isoformat(timespec="seconds")
-        with open(log_path, "a", encoding="utf-8") as f:
-            f.write(f"{ts} {msg}\n")
-    except Exception:
-        return