@jahanxu/code-flow 0.1.0

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+import json
+import os
+import sys
+
+from cf_core import estimate_tokens, load_config
+
+
+def read_text(path: str) -> str:
+    try:
+        with open(path, "r", encoding="utf-8") as file:
+            return file.read().strip()
+    except Exception:
+        return ""
+
+
+def main() -> None:
+    project_root = os.getcwd()
+    config = load_config(project_root)
+    budget_cfg = config.get("budget") or {}
+
+    human_output = "--human" in sys.argv
+    json_output = not human_output
+    domain_filter = None
+    for arg in sys.argv[1:]:
+        if arg.startswith("--domain="):
+            domain_filter = arg.split("=", 1)[1]
+
+    l0_budget = budget_cfg.get("l0_max", 800)
+    l1_budget = budget_cfg.get("l1_max", 1700)
+    total_budget = budget_cfg.get("total", l0_budget + l1_budget)
+
+    try:
+        l0_budget = int(l0_budget)
+    except Exception:
+        l0_budget = 800
+    try:
+        total_budget = int(total_budget)
+    except Exception:
+        total_budget = l0_budget + l1_budget
+
+    claude_path = os.path.join(project_root, "CLAUDE.md")
+    l0_tokens = 0
+    if os.path.exists(claude_path):
+        l0_tokens = estimate_tokens(read_text(claude_path))
+
+    l1 = {}
+    total_tokens = l0_tokens
+    specs_root = os.path.join(project_root, ".code-flow", "specs")
+    spec_domain_map = {}
+    for domain, domain_cfg in (config.get("path_mapping") or {}).items():
+        if domain_filter and domain_filter != domain:
+            continue
+        items = []
+        for rel in domain_cfg.get("specs") or []:
+            spec_domain_map[rel] = domain
+            full_path = os.path.join(specs_root, rel)
+            if not os.path.exists(full_path):
+                continue
+            content = read_text(full_path)
+            if not content:
+                continue
+            tokens = estimate_tokens(content)
+            items.append({"path": rel, "tokens": tokens})
+            total_tokens += tokens
+        if items:
+            l1[domain] = items
+
+    utilization = "0%"
+    if total_budget:
+        utilization = f"{round(total_tokens * 100 / total_budget)}%"
+
+    warnings = []
+    if l0_tokens > l0_budget:
+        warnings.append("L0 超出预算")
+    l1_tokens = total_tokens - l0_tokens
+    if l1_tokens > l1_budget:
+        warnings.append("L1 超出预算")
+    if total_tokens > total_budget:
+        warnings.append("总预算超出")
+
+    output = {
+        "l0": {"file": "CLAUDE.md", "tokens": l0_tokens, "budget": l0_budget},
+        "l1": l1,
+        "total_tokens": total_tokens,
+        "total_budget": total_budget,
+        "utilization": utilization,
+        "warnings": warnings,
+        "spec_domain_map": spec_domain_map,
+    }
+    if json_output:
+        print(json.dumps(output, ensure_ascii=False))
+        return
+
+    print("L0 (CLAUDE.md):", f"{l0_tokens} / {l0_budget}")
+    for domain, items in l1.items():
+        total_domain = sum(item["tokens"] for item in items)
+        print(f"L1 {domain}:", total_domain)
+        for item in items:
+            print(" -", item["path"], item["tokens"])
+    print("TOTAL:", f"{total_tokens} / {total_budget}")
+    print("UTILIZATION:", utilization)
+    if warnings:
+        print("WARNINGS:", "; ".join(warnings))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+import fnmatch
+import json
+import os
+import subprocess
+import sys
+
+
+def load_validation(project_root: str) -> dict:
+    config_path = os.path.join(project_root, ".code-flow", "validation.yml")
+    if os.path.exists(config_path):
+        try:
+            import yaml
+        except Exception:
+            return {}
+        try:
+            with open(config_path, "r", encoding="utf-8") as file:
+                data = yaml.safe_load(file)
+            return data or {}
+        except Exception:
+            return {}
+
+    package_path = os.path.join(project_root, "package.json")
+    if not os.path.exists(package_path):
+        return {}
+    try:
+        with open(package_path, "r", encoding="utf-8") as file:
+            data = json.load(file)
+    except Exception:
+        return {}
+
+    scripts = data.get("scripts") or {}
+    validators = []
+    if "lint" in scripts:
+        validators.append(
+            {
+                "name": "npm run lint",
+                "trigger": "**/*.{ts,tsx,js,jsx}",
+                "command": "npm run lint",
+                "timeout": 30000,
+                "on_fail": "检查 lint 配置",
+            }
+        )
+    if "test" in scripts:
+        validators.append(
+            {
+                "name": "npm test",
+                "trigger": "**/*.{ts,tsx,js,jsx}"
+                if "lint" in scripts
+                else "**/*.{ts,tsx,js,jsx,py}",
+                "command": "npm test",
+                "timeout": 60000,
+                "on_fail": "检查测试用例",
+            }
+        )
+
+    return {"validators": validators}
+
+
+def expand_pattern(pattern: str) -> list:
+    if "{" in pattern and "}" in pattern:
+        prefix, rest = pattern.split("{", 1)
+        options, suffix = rest.split("}", 1)
+        return [f"{prefix}{opt}{suffix}" for opt in options.split(",")]
+    return [pattern]
+
+
+def normalize_path(path: str) -> str:
+    return path.replace(os.sep, "/")
+
+
+def match_files(pattern: str, files: list) -> list:
+    matches = []
+    patterns = expand_pattern(pattern)
+    for file_path in files:
+        normalized = normalize_path(file_path)
+        for pat in patterns:
+            if "**/" in pat:
+                pat_variants = [pat, pat.replace("**/", "")]
+            else:
+                pat_variants = [pat]
+            for variant in pat_variants:
+                if fnmatch.fnmatch(normalized, variant):
+                    matches.append(file_path)
+                    break
+    return sorted(set(matches))
+
+
+def truncate(text: str, limit: int = 2000) -> str:
+    if len(text) <= limit:
+        return text
+    return text[:limit] + "..."
+
+
+def quote_single(path: str) -> str:
+    return "'" + path.replace("'", "'\"'\"'") + "'"
+
+
+def normalize_requested_files(
+    project_root: str,
+    requested: list,
+    require_exists: bool,
+) -> tuple:
+    normalized = []
+    root_abs = os.path.abspath(project_root)
+    for raw_path in requested:
+        if not raw_path:
+            continue
+        if os.path.isabs(raw_path):
+            abs_path = os.path.abspath(raw_path)
+        else:
+            abs_path = os.path.abspath(os.path.join(project_root, raw_path))
+        try:
+            common = os.path.commonpath([root_abs, abs_path])
+        except Exception:
+            return [], "invalid_path"
+        if common != root_abs:
+            return [], "outside_project_root"
+        if require_exists and not os.path.exists(abs_path):
+            return [], "file_missing"
+        rel_path = os.path.relpath(abs_path, project_root)
+        normalized.append(normalize_path(rel_path))
+    return sorted(set(normalized)), ""
+
+
+def main() -> None:
+    project_root = os.getcwd()
+    config = load_validation(project_root)
+    validators = config.get("validators") or []
+    if not validators:
+        print(json.dumps({"error": "validation_config_missing"}, ensure_ascii=False))
+        return
+
+    args = sys.argv[1:]
+    requested_files = []
+    for arg in args:
+        if arg.startswith("--files="):
+            raw = arg.split("=", 1)[1]
+            requested_files.extend([part.strip() for part in raw.split(",") if part.strip()])
+        elif arg in {"--json-short", "--only-failed"}:
+            continue
+        elif arg.startswith("--output="):
+            continue
+        else:
+            requested_files.append(arg)
+
+    git_dir = os.path.join(project_root, ".git")
+    has_git = os.path.isdir(git_dir)
+    files = []
+
+    if has_git:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            print(
+                json.dumps(
+                    {"error": "git_diff_failed", "hint": "检查 git 仓库状态或 HEAD 是否存在"},
+                    ensure_ascii=False,
+                )
+            )
+            return
+        diff_files = [
+            normalize_path(line.strip())
+            for line in result.stdout.splitlines()
+            if line.strip()
+        ]
+        if requested_files:
+            normalized, error = normalize_requested_files(
+                project_root, requested_files, require_exists=False
+            )
+            if error:
+                print(
+                    json.dumps(
+                        {
+                            "error": "invalid_files",
+                            "hint": "确认文件路径位于项目根目录内",
+                        },
+                        ensure_ascii=False,
+                    )
+                )
+                return
+            diff_set = set(diff_files)
+            invalid = [path for path in normalized if path not in diff_set]
+            if invalid:
+                print(
+                    json.dumps(
+                        {
+                            "error": "files_not_in_diff",
+                            "hint": "仅允许使用 `git diff --name-only HEAD` 中的文件路径",
+                            "files": invalid,
+                        },
+                        ensure_ascii=False,
+                    )
+                )
+                return
+            files = normalized
+        else:
+            files = diff_files
+    else:
+        if not requested_files:
+            print(
+                json.dumps(
+                    {
+                        "error": "no_git_repo",
+                        "hint": "无 git 仓库时请通过 --files 或位置参数显式传入文件路径",
+                    },
+                    ensure_ascii=False,
+                )
+            )
+            return
+        normalized, error = normalize_requested_files(
+            project_root, requested_files, require_exists=True
+        )
+        if error:
+            print(
+                json.dumps(
+                    {
+                        "error": "invalid_files",
+                        "hint": "确认文件存在且位于项目根目录内",
+                    },
+                    ensure_ascii=False,
+                )
+            )
+            return
+        files = normalized
+
+    if not files:
+        print(json.dumps({"error": "no_files"}, ensure_ascii=False))
+        return
+
+    results = []
+    all_passed = True
+
+    for validator in validators:
+        name = validator.get("name", "unnamed")
+        trigger = validator.get("trigger", "")
+        command = validator.get("command", "")
+        timeout_ms = validator.get("timeout", 30000)
+        on_fail = validator.get("on_fail", "")
+
+        matched_files = match_files(trigger, files) if trigger else []
+        if not matched_files:
+            results.append(
+                {
+                    "name": name,
+                    "status": "skipped",
+                    "matched_files": [],
+                    "command": command,
+                }
+            )
+            continue
+
+        quoted_files = " ".join(quote_single(path) for path in matched_files)
+        run_command = command.replace("{files}", quoted_files)
+
+        try:
+            timeout = int(timeout_ms) / 1000
+        except Exception:
+            timeout = 30
+
+        status = "passed"
+        exit_code = 0
+        stdout = ""
+        stderr = ""
+
+        try:
+            proc = subprocess.run(
+                run_command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+            exit_code = proc.returncode
+            stdout = proc.stdout.strip()
+            stderr = proc.stderr.strip()
+            if exit_code != 0:
+                status = "failed"
+                all_passed = False
+        except subprocess.TimeoutExpired:
+            status = "timeout"
+            all_passed = False
+        except Exception:
+            status = "error"
+            all_passed = False
+
+        results.append(
+            {
+                "name": name,
+                "status": status,
+                "matched_files": matched_files,
+                "command": run_command,
+                "exit_code": exit_code,
+                "stdout": truncate(stdout),
+                "stderr": truncate(stderr),
+                "on_fail": on_fail,
+            }
+        )
+
+    output = {"passed": all_passed, "results": results}
+    if "--only-failed" in sys.argv:
+        output = {
+            "passed": all_passed,
+            "results": [
+                item
+                for item in results
+                if item["status"] in {"failed", "timeout", "error"}
+            ],
+        }
+
+    if "--json-short" in sys.argv:
+        output = {
+            "passed": all_passed,
+            "results": [
+                {
+                    "name": item["name"],
+                    "status": item["status"],
+                    "on_fail": item.get("on_fail", ""),
+                }
+                for item in output.get("results", [])
+            ],
+        }
+
+    if "--output=table" in sys.argv:
+        print("NAME | STATUS | MATCHED_FILES | COMMAND")
+        for item in output.get("results", []):
+            matched = ",".join(item.get("matched_files", []))
+            command = item.get("command", "")
+            print(f"{item.get('name')} | {item.get('status')} | {matched} | {command}")
+        return
+
+    print(json.dumps(output, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/src/core/code-flow/specs/backend/code-quality-performance.md

@@ -0,0 +1,13 @@
+# Backend Code Quality & Performance
+
+## Rules
+- 所有数据库查询必须参数化，禁止字符串拼接 SQL。
+- 关键路径必须有结构化日志。
+
+## Patterns
+- 对外部依赖调用设置超时与重试策略。
+
+## Anti-Patterns
+- 禁止在请求链路中吞掉异常。
+
+## Learnings

package/src/core/code-flow/specs/backend/database.md

@@ -0,0 +1,13 @@
+# Backend Database
+
+## Rules
+- 所有查询必须参数化，禁止字符串拼接 SQL。
+- 迁移脚本必须可回滚或可幂等。
+
+## Patterns
+- 读写分离场景需要标注读库与写库。
+
+## Anti-Patterns
+- 禁止在事务内发起外部网络调用。
+
+## Learnings

package/src/core/code-flow/specs/backend/directory-structure.md

@@ -0,0 +1,13 @@
+# Backend Directory Structure
+
+## Rules
+- 服务入口放在 services/，接口层放在 api/。
+- 数据模型放在 models/，禁止业务逻辑散落在入口文件。
+
+## Patterns
+- 模块按业务域拆分，保持目录深度可控。
+
+## Anti-Patterns
+- 禁止在根目录堆放脚本与临时代码。
+
+## Learnings

package/src/core/code-flow/specs/backend/logging.md

@@ -0,0 +1,13 @@
+# Backend Logging
+
+## Rules
+- 关键路径必须输出结构化日志。
+- 日志中不得包含明文密钥与个人敏感信息。
+
+## Patterns
+- 统一日志字段：request_id、user_id、latency_ms。
+
+## Anti-Patterns
+- 禁止在高频循环中打印大量日志。
+
+## Learnings

package/src/core/code-flow/specs/backend/platform-rules.md

@@ -0,0 +1,13 @@
+# Backend Platform Rules
+
+## Rules
+- API 变更必须保持向后兼容或提供版本化路径。
+- 外部依赖变更需更新配置与运行手册。
+
+## Patterns
+- 使用 feature flag 控制灰度发布。
+
+## Anti-Patterns
+- 禁止在生产环境使用调试级别配置。
+
+## Learnings

package/src/core/code-flow/specs/frontend/component-specs.md

@@ -0,0 +1,14 @@
+# Component Specs
+
+## Rules
+- Props 使用 interface 定义。
+- 组件文件名与组件名一致。
+
+## Patterns
+- 组件拆分为 UI 与容器层，避免单文件过大。
+
+## Anti-Patterns
+- 禁止在组件内直接修改 props。
+
+## Learnings
+- [2026-03-14] 示例学习

package/src/core/code-flow/specs/frontend/directory-structure.md

@@ -0,0 +1,14 @@
+# Frontend Directory Structure
+
+## Rules
+- 组件放在 src/components。
+- 页面放在 src/pages。
+- 业务复用逻辑放在 src/hooks。
+
+## Patterns
+- 新增目录需同步更新路由与入口索引。
+
+## Anti-Patterns
+- 禁止在 src 下新增未登记的一级目录。
+
+## Learnings

package/src/core/code-flow/specs/frontend/quality-standards.md

@@ -0,0 +1,15 @@
+# Frontend Quality Standards
+
+## Rules
+- 禁止 any 类型。
+- 组件使用函数组件。
+- 关键交互必须有明确的错误提示。
+
+## Patterns
+- 公共状态使用集中式状态管理，避免跨组件隐式依赖。
+
+## Anti-Patterns
+- 禁止在 render 中发起异步请求。
+
+## Learnings
+- [2026-03-14] 学习条目

package/src/core/code-flow/validation.yml

@@ -0,0 +1,30 @@
+validators:
+    - name: "Python 语法检查"
+      trigger: "**/*.py"
+      command: "python3 -m py_compile {files}"
+      timeout: 30000
+      on_fail: "检查语法错误"
+
+    - name: "TypeScript 类型检查"
+      trigger: "**/*.{ts,tsx}"
+      command: "npx tsc --noEmit"
+      timeout: 30000
+      on_fail: "检查类型定义"
+
+    - name: "ESLint"
+      trigger: "**/*.{ts,tsx,js,jsx}"
+      command: "npx eslint {files}"
+      timeout: 15000
+      on_fail: "运行 npx eslint --fix 自动修复"
+
+    - name: "Python 类型检查"
+      trigger: "**/*.py"
+      command: "python3 -m mypy {files}"
+      timeout: 30000
+      on_fail: "检查类型注解，参见 specs/backend/code-quality-performance.md"
+
+    - name: "Pytest"
+      trigger: "**/*.py"
+      command: "python3 -m pytest --tb=short -q"
+      timeout: 60000
+      on_fail: "测试失败，检查断言和 mock 是否需要更新"