Merge pull request #219 from calchiwo/feat/repo-map

feat(cli, prompt): add repo map mode

Author: calchiwo

README.md

@@ -1,6 +1,6 @@
 # ExplainThisRepo
 
-_The fastest way to understand any codebase in plain English using real project signals. Not blind AI summarization._
+_The fastest way to understand any codebase in plain English using real project signals. Not blind AI guessing._
 
 ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests, dependencies graph, file structure and high-signal files producing a clear, structured `EXPLAIN.md` that explains what the codebase actually does and how it is organized in plain English.
 
@@ -18,16 +18,19 @@ ExplainThisRepo analyzes real project signals; configs, entrypoints, manifests,
 
 - Understand any GitHub repository in seconds
 - Derives architectural summaries from repository structure and code signals.
-Not blind AI summarization.
-- Deterministic repo signal extractor that feeds LLMs correctly
+Not blind AI guessing
+- Deterministic repo signal extractor that feeds LLMs correctly. Signals first. LLM second
 - Translates complex code structures into plain English
 - Speeds up understanding of unfamiliar codebases
 - Solves the "**garbage in, garbage out**" problem specifically for codebases
 - Extract architecture signals from configs, entrypoints, and manifests
-- Works with GitHub repositories, local directories, private repositories, individual files and monorepos
+- System map that shows you where to start, what matters and what to ignore
+- Works with GitHub repositories, Local repositories, GitHub directories, local directories, GitHub files and local files 
+- Supports private repositories and monorepos
 - Zero-cloning and remote analysis
-- Outputs the explanation to an `EXPLAIN.md` file in your current directory, prints it directly in the terminal, or a specified output file (`.txt`, `.pdf`, `.docx`)
+- Outputs the explanation to an `EXPLAIN.md` file in your current directory, prints it directly in the terminal, or a specified output file (`.txt`, `.pdf`, `.docx`, `.md`)
 - Multiple explanation modes (quick, simple, detailed)
+- Additional tools: stack detection, repo map
 
 ## Installation
 
@@ -115,8 +118,8 @@ npx explainthisrepo owner/repo
 
 ExplainThisRepo uses a hybrid architecture:
 
-- Python → core implementaion (analysis, prompts, providers, output)
-- npm → ships prebuilt native binaries (no Python required)
+- Python → core implementation (analysis, prompts, providers, output)
+- npm → launches prebuilt native binaries (no Python install required)
 - pip → installs the full Python package
 
 > The npm and pip versions run the same core engine.
@@ -185,7 +188,7 @@ Run:
 explainthisrepo init
 ```
 
-For step-by-step instructions, see [docs/GITHUB_TOKEN.md](docs/GITHUB_TOKEN.md)
+For step-by-step instructions, see [docs/GITHUB_TOKEN.md](https://github.com/calchiwo/ExplainThisRepo/blob/main/docs/GITHUB_TOKEN.md)
 
 ## Flag options
 
@@ -199,6 +202,8 @@ For step-by-step instructions, see [docs/GITHUB_TOKEN.md](docs/GITHUB_TOKEN.md)
 
 - `--stack` → Tech stack breakdown from repo signals
 
+- `--map` → System map for understanding a codebase before changing it
+
 - `--version` → Check installed CLI version
 
 - `--help` → Show usage guide
@@ -209,7 +214,7 @@ For step-by-step instructions, see [docs/GITHUB_TOKEN.md](docs/GITHUB_TOKEN.md)
 
 - `--output` / `-o` → Specify output file or directory (default: `EXPLAIN.md`)
 
-## Flexible Repository and Local Directory Input
+## Flexible Input Types
 
 Accepts various formats for repository input, full GitHub URLs (with or without https), `owner/repo` format, issue links, query strings, and SSH clone links
 
@@ -226,7 +231,7 @@ explainthisrepo ./path/to/directory
 explainthisrepo ./path/to/file.py
 ```
 
-All inputs are normalized internally to `owner/repo`.
+GitHub inputs are normalized internally to `owner/repo`.
 
 ## CLI aliases
 
@@ -322,6 +327,26 @@ explainthisrepo owner/repo --stack
 ```
 ![Stack detector Output](assets/stack-command-output.png)
 
+### Repo map
+
+Navigation system map for understanding unfamiliar codebases that shows you where to start, what matters and what to ignore before touching it:
+
+```bash
+explainthisrepo owner/repo --map
+explainthisrepo . --map
+```
+
+By default, repo map mode writes to `REPO_MAP.md`.
+
+The map focuses on:
+
+- where to start reading
+- the likely main flow through the project
+- important files and why they matter
+- visible architecture boundaries
+- files or folders to ignore first
+- open questions that cannot be determined from repo signals
+
 ## Local Directory Analysis
 
 ExplainThisRepo can analyze local directories directly in the terminal, using the same modes and output formats as GitHub repositories
@@ -338,6 +363,7 @@ explainthisrepo . --quick
 explainthisrepo . --simple
 explainthisrepo . --detailed
 explainthisrepo . --stack
+explainthisrepo . --map
 ```
 
 When analyzing a local directory:
@@ -351,7 +377,7 @@ This allows analysis of projects directly from the local filesystem, without req
 
 ## File Analysis
 
-ExplanThisRepo analyzes individual files directly
+ExplainThisRepo analyzes individual files directly
 
 ```bash
 explainthisrepo ./path/to/file.py
@@ -388,9 +414,11 @@ explainthisrepo owner/repo/path/to/file.py --detailed
 
 When analyzing a GitHub file:
 - The file is fetched directly via the GitHub API
-- Only valid text files are processed (binary files are rejected)
-- File size is capped to prevent unsafe or truncated analysis
+- Raw bytes are passed into a unified ingestion pipeline
+- Binary detection, decoding, and size limits are handled in one place
+- File ingestion is identical to local file analysis
 - The explanation focuses on the file’s purpose, logic, and behavior
+- This removes divergence between local and GitHub file handling
 
 Input format must be:
 
@@ -421,14 +449,10 @@ explainthisrepo owner/repo/path/to/directory --detailed
 When analyzing a GitHub directory:
 
 - Directory contents are fetched via the GitHub API
-
 - Only structure and metadata are used (no full repo fetch)
-
 - Signals include files, subdirectories, and extension distribution
-
 - The explanation focuses on the directory’s role and structure
 
-
 `--stack` is not supported for directory targets.
 
 ### Custom output

_version.py

@@ -1 +1 @@
-VERSION = "0.25.3"
+VERSION = "0.26.0"

explain_this_repo/_version.py

@@ -1 +1 @@
-VERSION = "0.25.3"
+VERSION = "0.26.0"

explain_this_repo/cli.py

@@ -31,6 +31,7 @@
     build_file_simple_prompt,
     build_prompt,
     build_quick_prompt,
+    build_repo_map_prompt,
     build_simple_prompt,
 )
 from explain_this_repo.repo_reader import read_repo_signal_files
@@ -367,10 +368,19 @@ def _extract_directory_signals(contents: list[dict]) -> dict:
     }
 
 
+def _resolve_mode_output(args, default_output: str) -> str:
+    if args.output == "EXPLAIN.md":
+        return default_output
+    return args.output
+
+
 def _handle_file_mode(args, llm: str | None) -> None:
     if args.stack:
         print("error: --stack is not supported for file targets")
         raise SystemExit(1)
+    if args.map:
+        print("error: --map is not supported for file targets")
+        raise SystemExit(1)
 
     file_path = os.path.abspath(args.repository)
 
@@ -452,6 +462,9 @@ def _handle_github_file_mode(
     if args.stack:
         print("error: --stack is not supported for GitHub file targets")
         raise SystemExit(1)
+    if args.map:
+        print("error: --map is not supported for GitHub file targets")
+        raise SystemExit(1)
 
     if owner is None or repo is None or file_path is None:
         try:
@@ -533,6 +546,9 @@ def _handle_github_directory_mode(
     if args.stack:
         print("error: --stack is not supported for GitHub directory targets")
         raise SystemExit(1)
+    if args.map:
+        print("error: --map is not supported for GitHub directory targets")
+        raise SystemExit(1)
 
     if owner is None or repo is None or directory_path is None:
         try:
@@ -629,6 +645,40 @@ def _handle_directory_mode(args, llm: str | None) -> None:
         print_stack(report, args.repository, "")
         return
 
+    if args.map:
+        with console.status("Reading repository files...", spinner="dots"):
+            read_result = read_local_repo_signal_files(local_path)
+
+        readme_content = read_result.key_files.get(
+            next(
+                (k for k in read_result.key_files if k.lower().startswith("readme")),
+                "",
+            ),
+            None,
+        )
+
+        prompt = build_repo_map_prompt(
+            repo_name=local_path,
+            description=None,
+            readme=readme_content,
+            tree_text=read_result.tree_text,
+            files_text=read_result.files_text,
+        )
+
+        with console.status("Generating repo map...", spinner="dots"):
+            output = generate_with_exit(prompt, llm=llm)
+
+        output_path = _resolve_mode_output(args, "REPO_MAP.md")
+        print(f"Writing {output_path}...")
+        write_output(output, output_path)
+
+        word_count = len(output.split())
+        print(f"{output_path} generated successfully 🎉")
+        print(f"Words: {word_count}")
+        print(f"Location: {os.path.abspath(output_path)}")
+        print(f"Open {output_path} to navigate the codebase.")
+        return
+
     if args.quick:
         with console.status("Reading repository files...", spinner="dots"):
             read_result = read_local_repo_signal_files(local_path)
@@ -722,6 +772,38 @@ def _handle_github_mode(args, llm: str | None) -> None:
         print_stack(report, f"{owner}/{repo}", "")
         return
 
+    if args.map:
+        try:
+            with console.status(f"Fetching {owner}/{repo}...", spinner="dots"):
+                repo_data = fetch_repo(owner, repo)
+                readme = fetch_readme(owner, repo)
+                read_result = read_repo_signal_files(owner, repo)
+        except Exception as e:
+            print(f"error: {e}")
+            raise SystemExit(1)
+
+        prompt = build_repo_map_prompt(
+            repo_name=repo_data.get("full_name"),
+            description=repo_data.get("description"),
+            readme=readme,
+            tree_text=read_result.tree_text,
+            files_text=read_result.files_text,
+        )
+
+        with console.status("Generating repo map...", spinner="dots"):
+            output = generate_with_exit(prompt, llm=llm)
+
+        output_path = _resolve_mode_output(args, "REPO_MAP.md")
+        print(f"Writing {output_path}...")
+        write_output(output, output_path)
+
+        word_count = len(output.split())
+        print(f"{output_path} generated successfully 🎉")
+        print(f"Words: {word_count}")
+        print(f"Location: {os.path.abspath(output_path)}")
+        print(f"Open {output_path} to navigate the codebase.")
+        return
+
     try:
         with console.status(f"Fetching {owner}/{repo}...", spinner="dots"):
             repo_data = fetch_repo(owner, repo)
@@ -800,6 +882,7 @@ def main():
         "  explainthisrepo owner/repo --quick\n"
         "  explainthisrepo owner/repo --simple\n"
         "  explainthisrepo owner/repo --stack\n"
+        "  explainthisrepo owner/repo --map\n"
         "  explainthisrepo owner/repo/packages/react-dom\n"
         "  explainthisrepo owner/repo/packages/react-dom --quick\n"
         "  explainthisrepo owner/repo/packages/react-dom --simple\n"
@@ -814,6 +897,7 @@ def main():
         "  explainthisrepo . --quick\n"
         "  explainthisrepo . --simple\n"
         "  explainthisrepo . --stack\n"
+        "  explainthisrepo . --map\n"
         "  explainthisrepo ./path/to/file.py\n"
         "  explainthisrepo ./path/to/file.py --quick\n"
         "  explainthisrepo ./path/to/file.py --simple\n"
@@ -901,6 +985,11 @@ def main():
         action="store_true",
         help="Stack detection mode",
     )
+    mode_group.add_argument(
+        "--map",
+        action="store_true",
+        help="Map the system before changing it",
+    )
 
     args = parser.parse_args()
 
@@ -958,4 +1047,4 @@ def _run():
 
 
 if __name__ == "__main__":
-    _run()
+    _run()