Add project scanning and index generation

Author: PEDZEO

.github/workflows/ci.yml

@@ -29,6 +29,12 @@ jobs:
       - name: Validate workflow templates
         run: python tools/validate_workflow.py --memory-dir memory
 
+      - name: Scan project
+        run: python tools/scan_project.py --target . --output scan-summary.json
+
+      - name: Generate draft index
+        run: python tools/init_index.py --target . --output CODEBASE_INDEX.generated.md
+
       - name: Scaffold task
         run: >
           python tools/scaffold_task.py

README.en.md

@@ -147,6 +147,8 @@ Codex should operate like this:
 
 `tools/` already includes CLI commands that enforce the workflow:
 
+- `scan_project.py` — produce a structured JSON summary of a repository
+- `init_index.py` — generate a draft `CODEBASE_INDEX.md`
 - `bootstrap.py` — bootstrap the mandatory core into a new project
 - `scaffold_task.py` — create or replace `current-task.md`
 - `create_handoff.py` — append a structured handoff

README.md

@@ -155,6 +155,8 @@ python tools/bootstrap.py --target ..\my-project
 
 В `tools/` уже есть CLI для принуждения к процессу:
 
+- `scan_project.py` — собрать структурированный JSON summary проекта
+- `init_index.py` — сгенерировать черновик `CODEBASE_INDEX.md`
 - `bootstrap.py` — развернуть mandatory core в новый проект
 - `scaffold_task.py` — создать или обновить `current-task.md`
 - `create_handoff.py` — добавить structured handoff

tools/README.md

@@ -31,6 +31,22 @@ python tools\validate_workflow.py
 
 ## Commands
 
+### scan_project.py
+
+Сканирует репозиторий и выводит структурированный JSON summary.
+
+```powershell
+python tools/scan_project.py --target .
+```
+
+### init_index.py
+
+Генерирует черновик `CODEBASE_INDEX` на основе structural scan.
+
+```powershell
+python tools/init_index.py --target . --output CODEBASE_INDEX.generated.md
+```
+
 ### bootstrap.py
 
 Разворачивает mandatory core в новый проект.
@@ -103,3 +119,4 @@ python tools/acceptance_check.py --scope --behavior --verification --regression
 - Они не пытаются анализировать архитектуру за тебя.
 - Их цель: сделать нарушение процесса более заметным и дорогим.
 - `bootstrap.py` копирует только mandatory core, а не весь kit целиком.
+- `scan_project.py` и `init_index.py` строят черновик архитектурной карты, но не заменяют ручной review.

tools/init_index.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from common import configure_stdout, write_text
+from scan_project import build_summary
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Generate a draft CODEBASE_INDEX.md from a structural project scan")
+    parser.add_argument("--target", default=".", help="Target project directory")
+    parser.add_argument(
+        "--output",
+        default="CODEBASE_INDEX.generated.md",
+        help="Output file path for the generated index draft",
+    )
+    return parser
+
+
+def bullet_lines(items: list[str], placeholder: str) -> str:
+    if not items:
+        return f"- {placeholder}"
+    return "\n".join(f"- {item}" for item in items)
+
+
+def render_commands(commands: list[dict[str, str]]) -> str:
+    if not commands:
+        return "# No commands detected automatically"
+    lines = []
+    for item in commands[:12]:
+        lines.append(f"# {item['name']}")
+        lines.append(item["command"])
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def render_directories(entries: list[dict[str, str]]) -> str:
+    if not entries:
+        return "- No top-level directories detected"
+    lines: list[str] = []
+    for item in entries:
+        lines.append(f"- `{item['path']}/`")
+        lines.append(f"  - {item['description']}")
+    return "\n".join(lines)
+
+
+def render_entrypoints(entries: list[dict[str, object]]) -> str:
+    if not entries:
+        return "- No entrypoint candidates detected"
+    lines: list[str] = []
+    for item in entries[:8]:
+        reasons = ", ".join(item.get("reasons", [])) or "needs review"
+        lines.append(f"- {item['path']}  ({reasons})")
+    return "\n".join(lines)
+
+
+def render_area_hints(entries: list[dict[str, object]]) -> str:
+    if not entries:
+        return "- No area hints detected automatically"
+    lines: list[str] = []
+    for item in entries:
+        matches = ", ".join(item.get("matches", []))
+        lines.append(f"- {item['area']}: {matches}")
+    return "\n".join(lines)
+
+
+def render(summary: dict[str, object]) -> str:
+    languages = summary.get("languages", [])
+    frameworks = summary.get("frameworks", [])
+    important_files = summary.get("important_files", [])
+    ci_files = summary.get("ci_files", [])
+    tests = summary.get("tests", {})
+    commands = summary.get("commands", [])
+
+    primary_language = summary.get("primary_language") or "Needs review"
+    frameworks_text = ", ".join(frameworks) if frameworks else "Needs review"
+    package_manager = summary.get("package_manager") or "Needs review"
+    test_dirs = tests.get("directories", []) if isinstance(tests, dict) else []
+    test_samples = tests.get("sample_files", []) if isinstance(tests, dict) else []
+    test_count = tests.get("count", 0) if isinstance(tests, dict) else 0
+
+    return f"""# CODEBASE_INDEX.md
+
+Generated draft. Review and refine before treating it as canonical.
+
+## Project Summary
+
+- Project name: {summary.get("project_name", "Needs review")}
+- Main purpose: Needs review
+- Primary language: {primary_language}
+- Frameworks: {frameworks_text}
+- Package manager: {package_manager}
+- Test runner: Needs review
+
+## Entry Points
+
+{render_entrypoints(summary.get("entrypoints", []))}
+
+## Main Directories
+
+{render_directories(summary.get("main_directories", []))}
+
+## Important Files
+
+{bullet_lines(important_files[:20], "No important config or manifest files detected")}
+
+## CI Files
+
+{bullet_lines(ci_files[:10], "No CI files detected")}
+
+## Area Hints
+
+{render_area_hints(summary.get("area_hints", []))}
+
+## Test Map
+
+- Test directories: {", ".join(test_dirs) if test_dirs else "Needs review"}
+- Detected test files: {test_count}
+- Sample test files:
+{bullet_lines(test_samples[:10], "No test files detected automatically")}
+
+## Common Commands
+
+```text
+{render_commands(commands)}
+```
+
+## Notes For Codex
+
+- This file was generated from structural scanning and heuristics.
+- Verify entry points, test runner, and business-purpose descriptions manually.
+- Update this file when architecture or repository structure changes.
+"""
+
+
+def main() -> int:
+    configure_stdout()
+    parser = build_parser()
+    args = parser.parse_args()
+    target = Path(args.target).resolve()
+    summary = build_summary(target)
+    output = Path(args.output)
+    if not output.is_absolute():
+        output = target / output
+    write_text(output, render(summary))
+    print(f"Generated {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+