Add scan explanations and confidence output

Author: PEDZEO

.github/workflows/ci.yml

@@ -41,6 +41,9 @@ jobs:
       - name: Generate draft change areas
         run: python tools/init_change_areas.py --target . --output CHANGE_AREAS.generated.md
 
+      - name: Explain scan
+        run: python tools/explain_scan.py --target . --format markdown --output SCAN_EXPLANATION.md
+
       - name: Copy canonical index for refresh smoke test
         run: >
           python -c

README.en.md

@@ -152,6 +152,7 @@ Codex should operate like this:
 - `init_test_index.py` — generate a draft `TEST_INDEX.md`
 - `init_change_areas.py` — generate a draft `CHANGE_AREAS.md`
 - `refresh_index.py` — refresh machine-generated sections of an existing `CODEBASE_INDEX.md`
+- `explain_scan.py` — explain what the scanner found and why
 - `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

@@ -160,6 +160,7 @@ python tools/bootstrap.py --target ..\my-project
 - `init_test_index.py` — сгенерировать черновик `TEST_INDEX.md`
 - `init_change_areas.py` — сгенерировать черновик `CHANGE_AREAS.md`
 - `refresh_index.py` — обновить машинные секции существующего `CODEBASE_INDEX.md`
+- `explain_scan.py` — объяснить, что именно сканер нашел и почему
 - `bootstrap.py` — развернуть mandatory core в новый проект
 - `scaffold_task.py` — создать или обновить `current-task.md`
 - `create_handoff.py` — добавить structured handoff

tools/README.md

@@ -39,6 +39,12 @@ python tools\validate_workflow.py
 python tools/scan_project.py --target .
 ```
 
+Можно писать в файл:
+
+```powershell
+python tools/scan_project.py --target . --output scan-summary.json
+```
+
 ### init_index.py
 
 Генерирует черновик `CODEBASE_INDEX` на основе structural scan.
@@ -47,6 +53,12 @@ python tools/scan_project.py --target .
 python tools/init_index.py --target . --output CODEBASE_INDEX.generated.md
 ```
 
+JSON-режим в stdout:
+
+```powershell
+python tools/init_index.py --target . --format json --output -
+```
+
 ### init_test_index.py
 
 Генерирует черновик `TEST_INDEX` на основе scan summary и команд проекта.
@@ -55,6 +67,12 @@ python tools/init_index.py --target . --output CODEBASE_INDEX.generated.md
 python tools/init_test_index.py --target . --output TEST_INDEX.generated.md
 ```
 
+Markdown в stdout:
+
+```powershell
+python tools/init_test_index.py --target . --output -
+```
+
 ### init_change_areas.py
 
 Генерирует черновик `CHANGE_AREAS` на основе directory и entrypoint heuristics.
@@ -63,6 +81,12 @@ python tools/init_test_index.py --target . --output TEST_INDEX.generated.md
 python tools/init_change_areas.py --target . --output CHANGE_AREAS.generated.md
 ```
 
+JSON-режим:
+
+```powershell
+python tools/init_change_areas.py --target . --format json --output -
+```
+
 ### refresh_index.py
 
 Обновляет машинные секции существующего `CODEBASE_INDEX.md` без полного перетирания файла.
@@ -71,6 +95,20 @@ python tools/init_change_areas.py --target . --output CHANGE_AREAS.generated.md
 python tools/refresh_index.py --target . --index CODEBASE_INDEX.md
 ```
 
+### explain_scan.py
+
+Кратко объясняет, что scanner обнаружил и почему.
+
+```powershell
+python tools/explain_scan.py --target .
+```
+
+Markdown-режим:
+
+```powershell
+python tools/explain_scan.py --target . --format markdown
+```
+
 ### bootstrap.py
 
 Разворачивает mandatory core в новый проект.
@@ -146,3 +184,4 @@ python tools/acceptance_check.py --scope --behavior --verification --regression
 - `scan_project.py` и `init_index.py` строят черновик архитектурной карты, но не заменяют ручной review.
 - `init_test_index.py` и `init_change_areas.py` дают черновики для test map и change areas, а не финальную архитектурную истину.
 - `refresh_index.py` обновляет только машинные секции и должен использоваться поверх уже просмотренного человеком индекса.
+- Генераторы поддерживают `--output -` для stdout и `--format json` там, где это имеет смысл.

tools/common.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+import json
 import os
 from pathlib import Path
 import sys
@@ -90,3 +91,15 @@ def configure_stdout() -> None:
     if hasattr(stream, "reconfigure"):
         # Windows CI can default to cp1252 and crash on Cyrillic output.
         stream.reconfigure(encoding="utf-8", errors="backslashreplace")
+
+
+def emit_output(output: str, text: str) -> None:
+    if output == "-":
+        print(text)
+    else:
+        write_text(Path(output), text)
+
+
+def emit_json(output: str, payload: object) -> None:
+    text = json.dumps(payload, ensure_ascii=False, indent=2)
+    emit_output(output, text)

tools/explain_scan.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from common import configure_stdout, emit_json, emit_output
+from scan_project import build_summary
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Explain what the repository scanner detected and why")
+    parser.add_argument("--target", default=".", help="Target project directory")
+    parser.add_argument("--output", default="-", help="Output path, or - for stdout")
+    parser.add_argument("--format", choices=["text", "markdown", "json"], default="text", help="Output format")
+    return parser
+
+
+def build_payload(summary: dict[str, object]) -> dict[str, object]:
+    confidence = summary.get("confidence_notes", {})
+    return {
+        "project_name": summary.get("project_name"),
+        "primary_language": {
+            "value": summary.get("primary_language"),
+            **confidence.get("primary_language", {}),
+        },
+        "entrypoints": summary.get("entrypoints", []),
+        "tests": {
+            **summary.get("tests", {}),
+            **({"confidence": confidence.get("tests", {}).get("confidence"), "reason": confidence.get("tests", {}).get("reason")} if confidence.get("tests") else {}),
+        },
+        "commands": {
+            "items": summary.get("commands", []),
+            **({"confidence": confidence.get("commands", {}).get("confidence"), "reason": confidence.get("commands", {}).get("reason")} if confidence.get("commands") else {}),
+        },
+        "areas": {
+            "items": summary.get("area_hints", []),
+            **({"confidence": confidence.get("areas", {}).get("confidence"), "reason": confidence.get("areas", {}).get("reason")} if confidence.get("areas") else {}),
+        },
+    }
+
+
+def render_text(summary: dict[str, object]) -> str:
+    confidence = summary.get("confidence_notes", {})
+    entrypoints = summary.get("entrypoints", [])
+    commands = summary.get("commands", [])
+    area_hints = summary.get("area_hints", [])
+    tests = summary.get("tests", {})
+
+    lines = [
+        f"Project: {summary.get('project_name')}",
+        f"Primary language: {summary.get('primary_language') or 'unknown'}",
+        f"  Confidence: {confidence.get('primary_language', {}).get('confidence', 'unknown')}",
+        f"  Reason: {confidence.get('primary_language', {}).get('reason', 'Needs review')}",
+        "",
+        "Entrypoints:",
+    ]
+    if entrypoints:
+        for item in entrypoints[:8]:
+            reasons = ", ".join(item.get("reasons", [])) or "Needs review"
+            lines.append(f"- {item['path']} [{item.get('confidence', 'unknown')}]")
+            lines.append(f"  Reasons: {reasons}")
+    else:
+        lines.append("- none detected")
+
+    lines.extend(
+        [
+            "",
+            f"Tests: {tests.get('count', 0) if isinstance(tests, dict) else 0} detected",
+            f"  Confidence: {confidence.get('tests', {}).get('confidence', 'unknown')}",
+            f"  Reason: {confidence.get('tests', {}).get('reason', 'Needs review')}",
+            "",
+            f"Commands: {len(commands)} detected",
+            f"  Confidence: {confidence.get('commands', {}).get('confidence', 'unknown')}",
+            f"  Reason: {confidence.get('commands', {}).get('reason', 'Needs review')}",
+            "",
+            "Area hints:",
+        ]
+    )
+    if area_hints:
+        for item in area_hints:
+            lines.append(f"- {item['area']} [{item.get('confidence', 'unknown')}] -> {', '.join(item.get('matches', []))}")
+    else:
+        lines.append("- none detected")
+    return "\n".join(lines)
+
+
+def render_markdown(summary: dict[str, object]) -> str:
+    payload = build_payload(summary)
+    entrypoints = payload["entrypoints"]
+    tests = payload["tests"]
+    commands = payload["commands"]
+    areas = payload["areas"]
+
+    lines = [
+        "# Scan Explanation",
+        "",
+        f"- Project: {payload['project_name']}",
+        f"- Primary language: {payload['primary_language'].get('value') or 'unknown'}",
+        f"- Language confidence: {payload['primary_language'].get('confidence', 'unknown')}",
+        f"- Language reason: {payload['primary_language'].get('reason', 'Needs review')}",
+        "",
+        "## Entrypoints",
+    ]
+    if entrypoints:
+        for item in entrypoints[:8]:
+            lines.append(f"- `{item['path']}`")
+            lines.append(f"  - confidence: {item.get('confidence', 'unknown')}")
+            lines.append(f"  - reasons: {', '.join(item.get('reasons', [])) or 'Needs review'}")
+    else:
+        lines.append("- none detected")
+
+    lines.extend(
+        [
+            "",
+            "## Tests",
+            f"- count: {tests.get('count', 0)}",
+            f"- confidence: {tests.get('confidence', 'unknown')}",
+            f"- reason: {tests.get('reason', 'Needs review')}",
+            "",
+            "## Commands",
+            f"- count: {len(commands.get('items', []))}",
+            f"- confidence: {commands.get('confidence', 'unknown')}",
+            f"- reason: {commands.get('reason', 'Needs review')}",
+            "",
+            "## Areas",
+            f"- confidence: {areas.get('confidence', 'unknown')}",
+            f"- reason: {areas.get('reason', 'Needs review')}",
+        ]
+    )
+    if areas.get("items"):
+        for item in areas["items"]:
+            lines.append(f"- {item['area']}: {', '.join(item.get('matches', []))}")
+    else:
+        lines.append("- none detected")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    configure_stdout()
+    parser = build_parser()
+    args = parser.parse_args()
+    summary = build_summary(Path(args.target).resolve())
+    output = args.output
+    if args.format == "json":
+        emit_json(output, build_payload(summary))
+    elif args.format == "markdown":
+        emit_output(output, render_markdown(summary))
+    else:
+        emit_output(output, render_text(summary))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/init_change_areas.py

@@ -3,14 +3,15 @@
 import argparse
 from pathlib import Path
 
-from common import configure_stdout, write_text
+from common import configure_stdout, emit_json, emit_output
 from scan_project import build_change_area_summary, build_summary
 
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Generate a draft CHANGE_AREAS.md from repository structure")
     parser.add_argument("--target", default=".", help="Target project directory")
     parser.add_argument("--output", default="CHANGE_AREAS.generated.md", help="Output file path")
+    parser.add_argument("--format", choices=["markdown", "json"], default="markdown", help="Output format")
     return parser
 
 
@@ -21,13 +22,15 @@ def render_area(area: dict[str, object]) -> str:
     return f"""- {area['area']}
   - Основные директории: {directories}
   - Главные entrypoints: {entrypoints}
+  - Confidence: {area.get('confidence', 'unknown')}
   - Основные риски: Needs review
   - Типичные тесты: {tests}"""
 
 
 def render(summary: dict[str, object]) -> str:
     areas = build_change_area_summary(summary)
     area_text = "\n\n".join(render_area(area) for area in areas) if areas else "- No change areas detected automatically"
+    confidence_notes = summary.get("confidence_notes", {})
     return f"""# CHANGE_AREAS.md
 
 Generated draft. Review and refine before using it for strict delegation.
@@ -38,6 +41,7 @@ def render(summary: dict[str, object]) -> str:
 
 ## Delegation Rule
 
+- Confidence: {confidence_notes.get('areas', {}).get('confidence', 'unknown')} ({confidence_notes.get('areas', {}).get('reason', 'Needs review')})
 - Один агент должен владеть одной зоной записи.
 - Если задача затрагивает две зоны, критический путь лучше держать локально.
 - Если зона не определена, сначала отправляй `explorer`.
@@ -49,15 +53,25 @@ def main() -> int:
     parser = build_parser()
     args = parser.parse_args()
     target = Path(args.target).resolve()
-    output = Path(args.output)
-    if not output.is_absolute():
-        output = target / output
     summary = build_summary(target)
-    write_text(output, render(summary))
-    print(f"Generated {output}")
+    output = args.output
+    if output != "-":
+        output_path = Path(output)
+        if not output_path.is_absolute():
+            output_path = target / output_path
+        output = str(output_path)
+    payload = {
+        "areas": build_change_area_summary(summary),
+        "confidence_notes": summary.get("confidence_notes", {}).get("areas", {}),
+    }
+    if args.format == "json":
+        emit_json(output, payload)
+    else:
+        emit_output(output, render(summary))
+    if output != "-":
+        print(f"Generated {output}")
     return 0
 
 
 if __name__ == "__main__":
     raise SystemExit(main())
-