chorus-cli 0.4.0

package/tools/mapper.py

@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""
+mapper.py — Generate a codebase map for the coder agent.
+
+Scans a project directory and produces a compact .coder/map.md that coder
+loads into its system prompt, so it starts every session already knowing
+the file structure, key modules, exports, dependencies, and test status.
+
+Usage:
+    mapper.py [path]          # defaults to cwd
+    mapper.py ~/my-project
+"""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# ── Skip rules ──────────────────────────────────────────────────────────────
+
+SKIP_DIRS = {
+    ".git", ".svn", ".hg", "node_modules", "__pycache__", ".venv", "venv",
+    ".tox", ".mypy_cache", ".pytest_cache", ".next", ".nuxt", ".output",
+    "dist", "build", "out", "target", "coverage", ".turbo", ".cache",
+    ".idea", ".vscode", "vendor", "bower_components", ".terraform",
+}
+
+SKIP_FILES = {
+    ".DS_Store", "Thumbs.db", "package-lock.json", "yarn.lock",
+    "pnpm-lock.yaml", "poetry.lock", "Pipfile.lock", "composer.lock",
+    "Cargo.lock", "go.sum",
+}
+
+BINARY_EXTENSIONS = {
+    ".png", ".jpg", ".jpeg", ".gif", ".ico", ".svg", ".webp", ".bmp",
+    ".woff", ".woff2", ".ttf", ".eot", ".otf",
+    ".zip", ".tar", ".gz", ".bz2", ".7z", ".rar",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx",
+    ".exe", ".dll", ".so", ".dylib", ".o", ".a",
+    ".pyc", ".pyo", ".class", ".jar", ".war",
+    ".mp3", ".mp4", ".avi", ".mov", ".wav",
+    ".sqlite", ".db", ".mdb",
+}
+
+CODE_EXTENSIONS = {
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+    ".go", ".rs", ".rb", ".java", ".kt", ".scala",
+    ".c", ".cpp", ".h", ".hpp", ".cs",
+    ".php", ".swift", ".dart", ".lua", ".ex", ".exs",
+    ".vue", ".svelte",
+}
+
+MAX_FILE_SIZE = 200 * 1024  # skip files over 200KB for signature extraction
+MAX_TREE_ENTRIES = 300
+MAX_SIGNATURE_FILES = 150
+MAX_SYMBOLS_PER_FILE = 25
+
+# ── Signature extraction ────────────────────────────────────────────────────
+
+PYTHON_PATTERNS = [
+    (re.compile(r"^class\s+(\w+)"), "class"),
+    (re.compile(r"^(?:async\s+)?def\s+(\w+)"), "fn"),
+]
+
+JS_PATTERNS = [
+    (re.compile(r"^export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)"), "fn"),
+    (re.compile(r"^export\s+(?:default\s+)?class\s+(\w+)"), "class"),
+    (re.compile(r"^export\s+(?:const|let|var)\s+(\w+)"), "const"),
+    (re.compile(r"^export\s+interface\s+(\w+)"), "interface"),
+    (re.compile(r"^export\s+type\s+(\w+)"), "type"),
+    (re.compile(r"^export\s+enum\s+(\w+)"), "enum"),
+    (re.compile(r"^(?:async\s+)?function\s+(\w+)"), "fn"),
+    (re.compile(r"^class\s+(\w+)"), "class"),
+    (re.compile(r"^const\s+(\w+)\s*=\s*(?:\(|async|function|class|React)"), "const"),
+]
+
+GO_PATTERNS = [
+    (re.compile(r"^func\s+(\w+)\s*\("), "fn"),
+    (re.compile(r"^func\s+\(\w+\s+\*?\w+\)\s+(\w+)\s*\("), "method"),
+    (re.compile(r"^type\s+(\w+)\s+struct"), "struct"),
+    (re.compile(r"^type\s+(\w+)\s+interface"), "interface"),
+]
+
+RUST_PATTERNS = [
+    (re.compile(r"^pub\s+(?:async\s+)?fn\s+(\w+)"), "fn"),
+    (re.compile(r"^pub\s+struct\s+(\w+)"), "struct"),
+    (re.compile(r"^pub\s+enum\s+(\w+)"), "enum"),
+    (re.compile(r"^pub\s+trait\s+(\w+)"), "trait"),
+    (re.compile(r"^pub\s+type\s+(\w+)"), "type"),
+]
+
+JAVA_PATTERNS = [
+    (re.compile(r"^(?:public|protected)\s+(?:static\s+)?(?:abstract\s+)?class\s+(\w+)"), "class"),
+    (re.compile(r"^(?:public|protected)\s+interface\s+(\w+)"), "interface"),
+    (re.compile(r"^(?:public|protected)\s+enum\s+(\w+)"), "enum"),
+]
+
+PATTERN_MAP = {
+    ".py": PYTHON_PATTERNS,
+    ".js": JS_PATTERNS, ".jsx": JS_PATTERNS, ".mjs": JS_PATTERNS, ".cjs": JS_PATTERNS,
+    ".ts": JS_PATTERNS, ".tsx": JS_PATTERNS,
+    ".go": GO_PATTERNS,
+    ".rs": RUST_PATTERNS,
+    ".java": JAVA_PATTERNS, ".kt": JAVA_PATTERNS, ".scala": JAVA_PATTERNS,
+}
+
+
+def extract_signatures(filepath):
+    """Extract top-level symbols from a source file."""
+    ext = filepath.suffix.lower()
+    patterns = PATTERN_MAP.get(ext)
+    if not patterns:
+        return []
+
+    if filepath.stat().st_size > MAX_FILE_SIZE:
+        return []
+
+    try:
+        text = filepath.read_text(encoding="utf-8", errors="replace")
+    except (OSError, PermissionError):
+        return []
+
+    symbols = []
+    for line in text.splitlines():
+        if not line or line[0] in (" ", "\t"):
+            continue
+        for pattern, kind in patterns:
+            m = pattern.match(line)
+            if m:
+                name = m.group(1)
+                if name.startswith("_") and not name.startswith("__"):
+                    break
+                symbols.append((name, kind))
+                if len(symbols) >= MAX_SYMBOLS_PER_FILE:
+                    return symbols
+                break
+
+    return symbols
+
+# ── File tree ───────────────────────────────────────────────────────────────
+
+def format_size(size):
+    if size < 1024:
+        return f"{size}b"
+    elif size < 1024 * 1024:
+        return f"{size / 1024:.1f}kb"
+    else:
+        return f"{size / (1024 * 1024):.1f}mb"
+
+
+def should_skip(name, is_dir=False):
+    if is_dir:
+        return name in SKIP_DIRS or name.startswith(".")
+    return name in SKIP_FILES or name.endswith(".map")
+
+
+def build_tree(root, base_root, prefix="", depth=0, max_depth=5, counter=None):
+    """Build indented file tree lines."""
+    if counter is None:
+        counter = [0]
+
+    if counter[0] >= MAX_TREE_ENTRIES:
+        return []
+
+    try:
+        entries = sorted(root.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+    except PermissionError:
+        return []
+
+    lines = []
+    for entry in entries:
+        if counter[0] >= MAX_TREE_ENTRIES:
+            lines.append(f"{prefix}... (truncated)")
+            break
+
+        if should_skip(entry.name, entry.is_dir()):
+            continue
+
+        if entry.is_dir():
+            lines.append(f"{prefix}{entry.name}/")
+            counter[0] += 1
+            if depth < max_depth:
+                lines.extend(build_tree(entry, base_root, prefix + "  ", depth + 1, max_depth, counter))
+        elif entry.is_file():
+            ext = entry.suffix.lower()
+            if ext in BINARY_EXTENSIONS:
+                continue
+            size = format_size(entry.stat().st_size)
+            lines.append(f"{prefix}{entry.name} ({size})")
+            counter[0] += 1
+
+    return lines
+
+# ── Project detection ───────────────────────────────────────────────────────
+
+def detect_project(root):
+    """Detect project type, name, entry points, dependencies."""
+    info = {}
+
+    # package.json
+    pkg_path = root / "package.json"
+    if pkg_path.exists():
+        try:
+            data = json.loads(pkg_path.read_text())
+            info["type"] = data.get("type", "commonjs")
+            info["name"] = data.get("name", "")
+            info["description"] = data.get("description", "")
+            info["entry"] = data.get("main", "")
+            info["scripts"] = list(data.get("scripts", {}).keys())
+            info["deps"] = list(data.get("dependencies", {}).keys())
+            info["dev_deps"] = list(data.get("devDependencies", {}).keys())
+            info["framework"] = "Node.js"
+
+            # Detect framework
+            all_deps = info["deps"] + info["dev_deps"]
+            if "next" in all_deps:
+                info["framework"] = "Next.js"
+            elif "react" in all_deps:
+                info["framework"] = "React"
+            elif "vue" in all_deps:
+                info["framework"] = "Vue"
+            elif "svelte" in all_deps:
+                info["framework"] = "Svelte"
+            elif "express" in all_deps:
+                info["framework"] = "Express"
+            elif "fastify" in all_deps:
+                info["framework"] = "Fastify"
+            elif "angular" in [d.split("/")[-1] for d in all_deps]:
+                info["framework"] = "Angular"
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # requirements.txt / pyproject.toml
+    req_path = root / "requirements.txt"
+    pyp_path = root / "pyproject.toml"
+
+    if req_path.exists():
+        info.setdefault("framework", "Python")
+        try:
+            deps = [
+                line.split("==")[0].split(">=")[0].split("[")[0].strip()
+                for line in req_path.read_text().splitlines()
+                if line.strip() and not line.startswith("#") and not line.startswith("-")
+            ]
+            info["deps"] = deps
+            if "django" in [d.lower() for d in deps]:
+                info["framework"] = "Django"
+            elif "flask" in [d.lower() for d in deps]:
+                info["framework"] = "Flask"
+            elif "fastapi" in [d.lower() for d in deps]:
+                info["framework"] = "FastAPI"
+        except OSError:
+            pass
+
+    if pyp_path.exists():
+        info.setdefault("framework", "Python")
+
+    # Go
+    if (root / "go.mod").exists():
+        info.setdefault("framework", "Go")
+        try:
+            mod_text = (root / "go.mod").read_text()
+            mod_match = re.search(r"^module\s+(.+)$", mod_text, re.MULTILINE)
+            if mod_match:
+                info["name"] = mod_match.group(1).strip()
+        except OSError:
+            pass
+
+    # Rust
+    if (root / "Cargo.toml").exists():
+        info.setdefault("framework", "Rust")
+
+    return info
+
+
+def detect_tests(root):
+    """Check if the project has substantive test coverage."""
+    test_dir_names = {"test", "tests", "__tests__", "spec", "specs", "test_suite"}
+    test_file_patterns = [
+        "test_*.py", "*_test.py", "*_test.go",
+        "*.test.js", "*.test.ts", "*.test.jsx", "*.test.tsx",
+        "*.spec.js", "*.spec.ts", "*.spec.jsx", "*.spec.tsx",
+        "*_spec.rb",
+    ]
+
+    has_test_dir = any((root / d).is_dir() for d in test_dir_names)
+
+    test_files = []
+    for pattern in test_file_patterns:
+        for match in root.rglob(pattern):
+            try:
+                rel = match.relative_to(root)
+            except ValueError:
+                continue
+            if any(part in SKIP_DIRS for part in rel.parts):
+                continue
+            test_files.append(str(rel))
+            if len(test_files) > 50:
+                break
+
+    if not test_files:
+        return "none", []
+    elif len(test_files) <= 3:
+        return "minimal", test_files
+    else:
+        return "substantive", test_files
+
+# ── Map generation ──────────────────────────────────────────────────────────
+
+def collect_code_files(root):
+    """Collect all code files for signature extraction."""
+    files = []
+    for fp in sorted(root.rglob("*")):
+        if not fp.is_file():
+            continue
+        try:
+            rel = fp.relative_to(root)
+        except ValueError:
+            continue
+        if any(part in SKIP_DIRS for part in rel.parts):
+            continue
+        if fp.suffix.lower() in CODE_EXTENSIONS:
+            files.append(fp)
+        if len(files) >= MAX_SIGNATURE_FILES:
+            break
+    return files
+
+
+def generate_map(root):
+    """Generate the full codebase map."""
+    root = root.resolve()
+    lines = []
+
+    lines.append(f"CODEBASE MAP")
+    lines.append(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}")
+    lines.append(f"Root: {root}")
+    lines.append("")
+
+    # Project info
+    info = detect_project(root)
+    if info:
+        lines.append("PROJECT")
+        if info.get("framework"):
+            lines.append(f"  Framework: {info['framework']}")
+        if info.get("name"):
+            lines.append(f"  Name: {info['name']}")
+        if info.get("description"):
+            lines.append(f"  Description: {info['description']}")
+        if info.get("entry"):
+            lines.append(f"  Entry: {info['entry']}")
+        if info.get("scripts"):
+            lines.append(f"  Scripts: {', '.join(info['scripts'])}")
+        if info.get("deps"):
+            dep_str = ", ".join(info["deps"][:30])
+            if len(info["deps"]) > 30:
+                dep_str += f" (+{len(info['deps']) - 30} more)"
+            lines.append(f"  Dependencies: {dep_str}")
+        if info.get("dev_deps"):
+            dev_str = ", ".join(info["dev_deps"][:20])
+            if len(info["dev_deps"]) > 20:
+                dev_str += f" (+{len(info['dev_deps']) - 20} more)"
+            lines.append(f"  Dev dependencies: {dev_str}")
+        lines.append("")
+
+    # Tests
+    test_status, test_files = detect_tests(root)
+    lines.append("TESTS")
+    if test_status == "none":
+        lines.append("  No tests found.")
+    elif test_status == "minimal":
+        lines.append(f"  Minimal ({len(test_files)} test file(s))")
+        for tf in test_files:
+            lines.append(f"    {tf}")
+    else:
+        lines.append(f"  Substantive ({len(test_files)} test file(s))")
+        for tf in test_files[:10]:
+            lines.append(f"    {tf}")
+        if len(test_files) > 10:
+            lines.append(f"    ... and {len(test_files) - 10} more")
+    lines.append("")
+
+    # File tree
+    lines.append("STRUCTURE")
+    tree = build_tree(root, root)
+    for tl in tree:
+        lines.append(f"  {tl}")
+    lines.append("")
+
+    # Signatures
+    code_files = collect_code_files(root)
+    if code_files:
+        lines.append("SYMBOLS")
+        for fp in code_files:
+            sigs = extract_signatures(fp)
+            if not sigs:
+                continue
+            try:
+                rel = str(fp.relative_to(root))
+            except ValueError:
+                rel = str(fp)
+            sig_strs = [f"{name} ({kind})" for name, kind in sigs]
+            lines.append(f"  {rel}")
+            # Compact: fit on one or two lines
+            sig_line = ", ".join(sig_strs)
+            if len(sig_line) <= 90:
+                lines.append(f"    {sig_line}")
+            else:
+                # Split into chunks
+                chunk = []
+                chunk_len = 0
+                for s in sig_strs:
+                    if chunk_len + len(s) + 2 > 90 and chunk:
+                        lines.append(f"    {', '.join(chunk)}")
+                        chunk = []
+                        chunk_len = 0
+                    chunk.append(s)
+                    chunk_len += len(s) + 2
+                if chunk:
+                    lines.append(f"    {', '.join(chunk)}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+# ── CLI ─────────────────────────────────────────────────────────────────────
+
+def main():
+    root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
+
+    if not root.is_dir():
+        print(f"Error: {root} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    map_content = generate_map(root)
+
+    out_dir = root / ".coder"
+    out_dir.mkdir(exist_ok=True)
+    out_file = out_dir / "map.md"
+    out_file.write_text(map_content, encoding="utf-8")
+
+    # Add .coder to .gitignore if not already there
+    gitignore = root / ".gitignore"
+    if gitignore.exists():
+        gi_text = gitignore.read_text()
+        if ".coder" not in gi_text and ".coder/" not in gi_text:
+            with open(gitignore, "a") as f:
+                f.write("\n.coder/\n")
+            print(f"Added .coder/ to .gitignore", file=sys.stderr)
+    elif (root / ".git").is_dir():
+        gitignore.write_text(".coder/\n")
+        print(f"Created .gitignore with .coder/", file=sys.stderr)
+
+    # Stats
+    line_count = map_content.count("\n")
+    size = len(map_content)
+    est_tokens = size // 4
+    print(f"Map: {out_file} ({line_count} lines, ~{est_tokens} tokens)", file=sys.stderr)
+
+    # Also print to stdout for piping
+    print(map_content)
+
+
+if __name__ == "__main__":
+    main()