explainthisrepo 0.25.0 → 0.26.0

package/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
 
@@ -43,6 +46,7 @@ explainthisrepo owner/repo
 # explainthisrepo ./path/to/directory
 # explainthisrepo ./path/to/file.py
 # explainthisrepo owner/repo/path/to/file.py
+# explainthisrepo owner/repo/path/to/directory
 ```
 
 Alternatively,
@@ -87,6 +91,7 @@ explainthisrepo owner/repo
 # explainthisrepo ./path/to/directory
 # explainthisrepo ./path/to/file.py
 # explainthisrepo owner/repo/path/to/file.py
+# explainthisrepo owner/repo/path/to/directory
 </details>
 </pre>
 </code>
@@ -104,6 +109,7 @@ npx explainthisrepo owner/repo
 # npx explainthisrepo ./path/to/directory
 # npx explainthisrepo ./path/to/file.py
 # npx explainthisrepo owner/repo/path/to/file.py
+# npx explainthisrepo owner/repo/path/to/directory
 </code>
 </pre>
 </details>
@@ -112,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.
@@ -182,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
 
@@ -196,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
@@ -206,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
 
@@ -216,13 +224,14 @@ explainthisrepo github.com/owner/repo
 explainthisrepo https://github.com/owner/repo/issues/123
 explainthisrepo https://github.com/owner/repo?tab=readme
 explainthisrepo git@github.com:owner/repo.git
+explainthisrepo owner/repo/path/to/directory
 explainthisrepo owner/repo/path/to/file.py
 explainthisrepo .
 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
 
@@ -318,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
@@ -334,6 +363,7 @@ explainthisrepo . --quick
 explainthisrepo . --simple
 explainthisrepo . --detailed
 explainthisrepo . --stack
+explainthisrepo . --map
 ```
 
 When analyzing a local directory:
@@ -347,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
@@ -384,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:
 
@@ -399,6 +431,30 @@ This is different from local file analysis:
 ```bash
 explainthisrepo ./path/to/file.py
 ```
+
+## GitHub Directory Analysis
+
+ExplainThisRepo can analyze a specific directory inside a GitHub repository without cloning it.
+
+```bash
+explainthisrepo owner/repo/path/to/directory
+```
+Supports all explanation modes:
+```bash
+explainthisrepo owner/repo/path/to/directory --quick
+explainthisrepo owner/repo/path/to/directory --simple
+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
 
 `--output`, `-o` → Specify output file or directory (default: `EXPLAIN.md`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainthisrepo",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "The fastest way to understand any codebase in plain English. Not blind AI summarization",
   "license": "MIT",
   "type": "module",