explainthisrepo 0.22.5 → 0.24.0

package/README.md

@@ -2,8 +2,7 @@
 
 _The fastest way to understand any codebase in plain English using real project signals. Not blind AI summarization._
 
-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 does and how it is organized in plain English.
-This is a deterministic repo signal extractor that feeds LLMs correctly.
+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.
 
 [![PyPI Version](https://img.shields.io/pypi/v/explainthisrepo?color=blue)](https://pypi.org/project/explainthisrepo/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/explainthisrepo?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/explainthisrepo)
@@ -20,11 +19,14 @@ This is a deterministic repo signal extractor that feeds LLMs correctly.
 - 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
 - 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
-- 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`, `.docs`)
+- 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`)
 - Multiple explanation modes (quick, simple, detailed)
 
 ## Installation
@@ -37,8 +39,10 @@ Requirements: Python 3.9+
 pip install explainthisrepo
 explainthisrepo owner/repo
 
-# pip install explainthisrepo
 # explainthisrepo .
+# explainthisrepo ./path/to/directory
+# explainthisrepo ./path/to/file.py
+# explainthisrepo owner/repo/path/to/file.py
 ```
 
 Alternatively,
@@ -74,18 +78,35 @@ Install globally and use forever:
 ```bash
 npm install -g explainthisrepo
 explainthisrepo owner/repo
+```
 
-# npm install -g explainthisrepo
+<details>
+<pre>
+<code>
 # explainthisrepo .
-```
+# explainthisrepo ./path/to/directory
+# explainthisrepo ./path/to/file.py
+# explainthisrepo owner/repo/path/to/file.py
+</details>
+</pre>
+</code>
 
 Or without install:
 
 ```bash
 npx explainthisrepo owner/repo
+```
 
+<details>
+<pre>
+<code>
 # npx explainthisrepo .
-```
+# npx explainthisrepo ./path/to/directory
+# npx explainthisrepo ./path/to/file.py
+# npx explainthisrepo owner/repo/path/to/file.py
+</code>
+</pre>
+</details>
 
 ## How it works
 
@@ -195,8 +216,10 @@ 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/file.py
 explainthisrepo .
 explainthisrepo ./path/to/directory
+explainthisrepo ./path/to/file.py
 ```
 
 All inputs are normalized internally to `owner/repo`.
@@ -344,6 +367,38 @@ When analyzing a file:
 - The explanation focuses on purpose, logic, and behavior
 - This makes it easy to understand unfamiliar files without scanning entire repositories.
 
+## GitHub File Analysis
+
+ExplainThisRepo can analyze a single file directly from a GitHub repository without cloning it.
+
+```bash
+explainthisrepo owner/repo/path/to/file.py
+```
+Supports all explanation modes:
+
+```bash
+explainthisrepo owner/repo/path/to/file.py --quick
+explainthisrepo owner/repo/path/to/file.py --simple
+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
+- The explanation focuses on the file’s purpose, logic, and behavior
+
+Input format must be:
+
+```bash
+explainthisrepo owner/repo/path/to/file
+```
+
+This is different from local file analysis:
+
+```bash
+explainthisrepo ./path/to/file.py
+```
 ### Custom output
 
 `--output`, `-o` → Specify output file or directory (default: `EXPLAIN.md`)

package/package.json

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