diffctx 1.11.0__tar.gz → 1.12.0__tar.gz

{diffctx-1.11.0 → diffctx-1.12.0}/CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.12.0] - 2026-07-23
+
+### Added
+
+- `--timeout SECONDS` — wall-clock deadline for `--diff` analysis (default
+  300); exceeding it exits `124` instead of hanging indefinitely (#70).
+- `--no-ignores` — turns off every ignore rule (built-in patterns, project
+  `.gitignore`, `.diffctx/ignore`). `--no-default-ignores` only disables the
+  built-in list; its help now says so. Not supported with `--diff`.
+- Output format is inferred from the `-o` extension when `-f` is omitted, so
+  `-o out.json` no longer writes Markdown into a `.json` file; a mismatch
+  between `-f` and the extension warns.
+
+### Fixed
+
+- **All error logging was dead.** An import-time `NullHandler` made
+  `setup_logging` skip attaching a real handler, so `--log-level` was a no-op
+  and all 19 `logger.error/warning/exception` sites were silent — `diffctx . -o
+  /bad/path.md` exited 1 with no message at all.
+- **diffctx invoked from inside a git hook silently analyzed the wrong
+  repository.** Git exports repo-locating env vars (`GIT_DIR`,
+  `GIT_INDEX_FILE`, `GIT_WORK_TREE`, ...) to hook subprocesses; inherited,
+  they overrode `-C` on every internal git call. All git spawns now scrub
+  these variables (`git_command()` in `git.rs`).
+- YAML output preserved file content byte-exactly except for trailing
+  newlines; the block chomping indicator is now chosen per content.
+- Arrow-function fragments bound to variables were never stub-eligible (#106).
+- Decorated definitions rendered as a bare `@decorator` line without the
+  `class X:` / `def x():` header.
+- `--max-depth`-pruned directories were labelled `_(empty directory)_` — a
+  factual lie to the reader; they now read
+  `_(children omitted: --max-depth reached)_` (`truncated: true` in
+  YAML/JSON).
+- Mixed directory + glob arguments dropped the glob files' parent path from
+  node names.
+- Double Ctrl-C printed a ~60-line traceback.
+- Lock files `uv.lock`, `pdm.lock`, `bun.lock`, `bun.lockb`, `deno.lock` and
+  `flake.lock` leaked into output; they now join the other lock files in the
+  default ignore patterns.
+- Large-repo hangs/OOM on trivial diffs (#70, #95): discovery no longer
+  re-reads and re-tokenizes the whole candidate universe per ensemble
+  strategy (one shared pass + a persistent per-blob token cache keyed by
+  `(blob OID, tokenizer epoch)`), and edge construction is two-pass with a
+  bounded per-source top-K instead of materializing up to tens of millions
+  of raw edges before the cap; pass 2 replays a compact 16-byte-per-emission
+  log instead of re-running the builders, so generation cost stays 1x.
+  Verified: gitpod 8000s-hang -> 35.7s,
+  pytorch 1848s-SIGKILL -> 7.4s, mui/material-ui OOM class recovered.
+  Outputs are bit-identical (gated by `benchmarks/equivalence_gate.py`).
+
+### Known limitations
+
+- Near-dense edge emission on huge same-directory trees (observed: 199M
+  raw edges, 37GB peak on one mui/material-ui instance) remains expensive
+  even with bounded construction; tracked in #116.
+
+### Changed
+
+- **The token budget is now a hard cap.** The changed-files post-pass no
+  longer exceeds the budget to guarantee representation: a changed file
+  whose cheapest representative does not fit stays unrepresented (visible
+  as changed-file retention < 1). `--budget 0` therefore yields an empty
+  selection (use `--full` for changed files only); CLI help updated.
+- Latency telemetry: new `graph_build_ms` phase (graph construction was
+  previously misattributed to `scoring_ms`, which now measures pure
+  ranking) and `peak_rss_bytes` (in-process peak memory). Release builds
+  carry line tables (`debug = "line-tables-only"`) for profiling at no
+  runtime cost.
+- CLI diagnostics are honest end to end: an exit-code table in `--help`
+  (2 usage, 3 environment, 4 empty diff, 124 timeout), flag-value validation
+  exits 2 instead of 1, git failures report a single line plus a
+  `git log --oneline` hint on unknown revisions, conflicting flags warn
+  (`-q`+`--log-level`, `--full`+selection flags, ...), a failed clipboard
+  copy warns before falling back to stdout, and `--tau` / `--scoring` /
+  `--alpha` / `--budget 0` help text describes what actually happens.
+- `graph --summary` reports category shares as percentages, suppresses
+  degenerate top-referenced lists, detects cycles over dominant-direction
+  edges only, derives churn from `git log --since`, and disambiguates
+  duplicate mermaid labels to relative paths.
+
 ## [1.11.0] - 2026-07-07
 
 ### Changed

{diffctx-1.11.0 → diffctx-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffctx
-Version: 1.11.0
+Version: 1.12.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -36,7 +36,6 @@ Requires-Dist: radon>=6.0,<7.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.4,<1.0 ; extra == 'dev'
 Requires-Dist: tiktoken>=0.9,<1.0 ; extra == 'dev'
 Requires-Dist: types-pyyaml>=6.0,<7.0 ; extra == 'dev'
-Requires-Dist: numpy>=1.24,<3.0 ; extra == 'diffctx'
 Requires-Dist: charset-normalizer>=3.0,<4.0 ; extra == 'full'
 Requires-Dist: diffctx[tree-sitter] ; extra == 'full'
 Requires-Dist: anyio>=4.5,<5.0 ; extra == 'mcp'
@@ -59,7 +58,6 @@ Requires-Dist: tree-sitter-scala>=0.24,<1.0 ; extra == 'tree-sitter'
 Requires-Dist: tree-sitter-swift>=0.0.1,<1.0 ; extra == 'tree-sitter'
 Requires-Dist: tree-sitter-typescript>=0.21,<1.0 ; extra == 'tree-sitter'
 Provides-Extra: dev
-Provides-Extra: diffctx
 Provides-Extra: full
 Provides-Extra: mcp
 Provides-Extra: tree-sitter
@@ -85,6 +83,10 @@ Project-URL: Repository, https://github.com/nikolay-e/diffctx
 Instead of pasting whole files, it walks the dependency graph from the changed
 lines outward and stops as soon as additional context stops paying for itself.
 
+> Coming from [`treemapper`](https://pypi.org/project/treemapper/)? That name is
+> deprecated — it was a thin wrapper around diffctx. Every command, flag, and
+> API call works unchanged: `treemapper` → `diffctx`, `treemapper-mcp` → `diffctx-mcp`.
+
 ## Why not just use `tree` or repomix?
 
 | | `tree` | repomix | Claude Code Review | **diffctx** |
@@ -98,90 +100,57 @@ lines outward and stops as soon as additional context stops paying for itself.
 | Python API | ✗ | ✗ | ✗ | ✓ |
 | MCP server | ✗ | ✗ | ✗ | ✓ |
 
-## Install (30 seconds)
+## Install
 
 ```bash
 uvx diffctx . --diff HEAD~1             # zero-install, run once via uv
-pipx install diffctx                    # recommended for repeat use — isolated CLI, no venv needed
+pipx install diffctx                    # recommended: isolated CLI, no venv needed
 pip install diffctx                     # or: into an active environment
 pipx install 'diffctx[mcp]'             # + MCP server for AI assistants
 ```
 
-> For everyday use, install once with `pipx` and call `diffctx` from any
-> directory. Do **not** `source` the project's `.venv` to run `diffctx` from
-> another repo — that runs a working-tree build and mutates the shell's
-> `PATH`/`PYTHONHOME` for every subsequent command.
+A standalone binary (no Python required) is on the
+[releases page](https://github.com/nikolay-e/diffctx/releases/latest).
+The `[tree-sitter]` extra adds AST-level parsing for more accurate context
+selection across 30+ languages.
+
+## Quick start
 
 ```bash
 diffctx . --diff HEAD~1       # smart context for last commit → paste into Claude/ChatGPT
-diffctx . -f md -c            # full export → clipboard in Markdown
-```
-
-![diffctx demo: running `diffctx . --diff HEAD~1` inside a git repo and copying the relevance-ranked YAML output to the clipboard for an LLM](https://raw.githubusercontent.com/nikolay-e/diffctx/main/docs/demo.gif)
-
-*Demo: `diffctx . --diff HEAD~1` selects only the fragments — functions,
-imports, type definitions — that an LLM actually needs to review the last
-commit, instead of dumping every changed file in full.*
-
-**Standalone binary** (no Python required): download from the
-[releases page](https://github.com/nikolay-e/diffctx/releases/latest).
-
-> Diff context mode works out of the box. Adding `[tree-sitter]` enables AST-level
-> parsing for more accurate context selection across 30+ languages.
-
-## Diff Context Mode
-
-Automatically finds the minimal set of code fragments needed to understand
-a change — imports, callers, type definitions, config dependencies — without
-dumping entire files. Understands 50+ file types.
-
-```yaml
-name: myproject
-type: diff_context
-fragment_count: 5
-fragments:
-  - path: src/main.py
-    lines: "10-25"
-    kind: function
-    symbol: process_data
-    content: |
-      def process_data(items):
-          ...
+diffctx . -f md -c            # full codebase export → clipboard in Markdown
 ```
 
-### How it works
+![diffctx demo](https://raw.githubusercontent.com/nikolay-e/diffctx/main/docs/demo.gif)
 
-Builds a code graph (imports, co-changes, type refs) and propagates
-relevance from changed lines outward across it. Three scoring modes are
-available — pick one with `--scoring`:
+*`diffctx . --diff HEAD~1` selects only the fragments — functions, imports,
+type definitions — that an LLM actually needs to review the last commit,
+instead of dumping every changed file in full.*
 
-| `--scoring` | What it does                                              |
-|-------------|-----------------------------------------------------------|
-| `ego` (default) | Bounded ego-network expansion around changed nodes — fast, predictable radius, the current default |
-| `ppr`       | Personalized PageRank with damping `--alpha` — global, smoother decay, slower |
-| `bm25`      | Lexical fragment retrieval against the diff hunks — useful as a baseline / fallback when the graph is sparse |
+## Diff context mode
 
-Selection stops when relevance drops below `--tau` (the minimum score a
-fragment must beat to be kept), or once `--budget` tokens have been
-emitted, whichever comes first.
+Finds the minimal set of code fragments needed to understand a change —
+imports, callers, type definitions, config dependencies — across 50+ file
+types. It builds a code graph (imports, co-changes, type refs), propagates
+relevance from the changed lines outward, and stops when relevance drops below
+`--tau` or the `--budget` token cap is reached.
 
 | Flag        | Default | Description                                                              |
 |-------------|---------|--------------------------------------------------------------------------|
-| `--scoring` | `ego`   | Scoring mode: `ego`, `ppr`, or `bm25`                                    |
-| `--budget`  | auto    | Token cap. `auto` lets selection converge; `-1` disables the cap; `N` enforces a fixed cap |
-| `--alpha`   | 0.60    | How tightly context clusters around changes (PPR damping; 0–1, higher = more focused) |
-| `--tau`     | 0.12    | Minimum relevance required to include a fragment (lower = more context)  |
-| `--full`    | false   | Include every changed fragment; skip the smart-selection step entirely   |
+| `--scoring` | `ego`   | `ego` = bounded expansion around changed nodes (fast, predictable radius); `ppr` = Personalized PageRank (global, smoother decay, slower); `bm25` = lexical retrieval against the diff hunks (baseline for sparse graphs) |
+| `--budget`  | auto    | Hard token cap: `N` enforces a fixed cap, `-1` disables it, `0` is a strict-zero floor (empty selection; use `--full` for changed files only) |
+| `--alpha`   | 0.60    | PPR damping; higher = context clusters tighter around changes (`--scoring ppr` only) |
+| `--tau`     | 0.12    | Relevance threshold for full fragment content; lower-scoring fragments are stubbed or dropped (lower = more context) |
+| `--full`    | false   | Only the changed files, every fragment, no related-code context          |
+| `--timeout` | 300     | Wall-clock deadline in seconds; on expiry diffctx exits 124 instead of hanging |
 
-Calibration of `--alpha`, `--tau`, and the edge-weight priors is documented
-in [`docs/parameter-strategy.md`](docs/parameter-strategy.md).
-
-*Theory: [Context-Selection for Git Diff (Zenodo, 2026)](https://doi.org/10.5281/zenodo.18824580).*
+Calibration of `--alpha`, `--tau`, and the edge-weight priors:
+[`docs/parameter-strategy.md`](docs/parameter-strategy.md). Theory:
+[Context-Selection for Git Diff (Zenodo, 2026)](https://doi.org/10.5281/zenodo.18824580).
 
 ### `graph` subcommand
 
-For exploring the underlying dependency graph directly (without a diff),
-use the `graph` subcommand:
+Explore the underlying dependency graph directly, without a diff:
 
 ```bash
 diffctx graph .                                  # Mermaid graph of directory deps (default)
@@ -190,12 +159,6 @@ diffctx graph . --level fragment -f json         # fragment-level graph as JSON
 diffctx graph . --level file -f graphml -o g.xml # file-level graph as GraphML
 ```
 
-| Flag        | Default      | Description                                              |
-|-------------|--------------|----------------------------------------------------------|
-| `-f/--format` | `mermaid`  | Output format: `mermaid`, `json`, or `graphml`           |
-| `--level`   | `directory`  | Granularity: `fragment`, `file`, or `directory`          |
-| `--summary` | false        | Print graph statistics (cycles, hotspots, coupling)      |
-
 ## Usage
 
 <!-- BEGIN USAGE -->
@@ -217,111 +180,49 @@ diffctx . --diff HEAD~1 -c               # diff context to clipboard
 ```
 <!-- END USAGE -->
 
-Full codebase export output format:
-
-```yaml
-name: myproject
-type: directory
-children:
-  - name: main.py
-    type: file
-    content: |
-      def hello():
-          print("Hello, World!")
-  - name: utils/
-    type: directory
-    children:
-      - name: helpers.py
-        type: file
-        content: |
-          def add(a, b):
-              return a + b
-```
-
-## Token Counting
-
-Token count and size are always displayed on stderr:
-
-```text
-12,847 tokens (o200k_base), 52.3 KB
-```
-
-For large outputs (>1MB), approximate counts with `~` prefix:
-
-```text
-~125,000 tokens (o200k_base), 5.2 MB
-```
-
-Uses tiktoken with `o200k_base` encoding (GPT-4o tokenizer).
-
-## Clipboard Support
-
-Copy output directly to clipboard with `-c` or `--copy`:
-
-```bash
-diffctx . -c                       # copy (stdout suppressed, stderr: token count)
-diffctx . -c -o tree.yaml          # copy + save to file
-```
-
-**System Requirements:**
-
-- **macOS:** `pbcopy` (pre-installed)
-- **Windows:** `clip` (pre-installed)
-- **Linux (Wayland):** `wl-copy`
-- **Linux (X11):** `xclip` or `xsel`
+Every run reports token count and size on stderr — `12,847 tokens
+(o200k_base), 52.3 KB` (tiktoken, the GPT-4o tokenizer; `~`-prefixed
+approximation above 1 MB). `-c/--copy` sends output to the clipboard via
+`pbcopy` (macOS), `clip` (Windows), or `wl-copy`/`xclip`/`xsel` (Linux).
+Unreadable files are replaced by placeholders such as `<binary file: N bytes>`,
+`<file too large: N bytes>`, or `<unreadable content: not utf-8>`.
 
 ## Python API
 
 ```python
-from diffctx import map_directory
-from diffctx import to_yaml, to_json, to_text, to_markdown
-
-tree = map_directory(
-    path,                     # directory path
-    max_depth=None,           # limit traversal depth
-    no_content=False,         # exclude file contents
-    max_file_bytes=None,      # skip large files
-    ignore_file=None,         # custom ignore file
-    no_default_ignores=False, # disable default ignores
-    whitelist_file=None,      # include-only filter
-)
-
-yaml_str = to_yaml(tree)
-json_str = to_json(tree)
-text_str = to_text(tree)
-md_str = to_markdown(tree)
-
-# Diff context mode
 from pathlib import Path
-from diffctx import build_diff_context, to_yaml
+from diffctx import build_diff_context, map_directory, to_json, to_markdown, to_text, to_yaml
 
 ctx = build_diff_context(
-    Path("."),                # repository root
-    "HEAD~1..HEAD",           # diff range; also accepts "main..feature"
-    budget_tokens=None,       # None = convergence-based (default)
-                              #   0  = diff only, no expansion (recall floor)
-                              #  <0  = unlimited (10M-token soft ceiling)
-                              #  >0  = explicit token cap
-    alpha=0.6,                # PPR damping factor
-    tau=0.12,                 # stopping threshold
-    full=False,               # skip smart selection
-    scoring_mode="ego",       # "ego" (default), "ppr", or "bm25"
-    timeout=300,              # seconds before the pipeline aborts
+    Path("."),
+    "HEAD~1..HEAD",
+    budget_tokens=None,       # None = auto; 0 = strict-zero floor (empty); -1 = uncapped; N = hard cap
+    alpha=0.6,
+    tau=0.12,
+    full=False,
+    scoring_mode="ego",
+    timeout=300,
 )
-yaml_str = to_yaml(ctx)
-```
-
-## MCP Server
+print(to_markdown(ctx))
 
-diffctx includes an [MCP](https://modelcontextprotocol.io) server that lets
-AI assistants (Claude Code, Cursor, Windsurf, etc.) call diff context analysis
-automatically during code review.
-
-```bash
-pip install 'diffctx[mcp]'
+tree = map_directory(
+    ".",
+    max_depth=None,
+    no_content=False,
+    max_file_bytes=None,
+    ignore_file=None,
+    no_default_ignores=False,
+    whitelist_file=None,
+)
+print(to_yaml(tree))
 ```
 
-Add to your MCP client config (e.g. `~/.claude/mcp.json` for Claude Code):
+## MCP server
+
+diffctx includes an [MCP](https://modelcontextprotocol.io) server that lets AI
+assistants (Claude Code, Cursor, Windsurf, etc.) call diff context analysis
+automatically during code review. Install with `pip install 'diffctx[mcp]'`
+and add to your MCP client config (e.g. `~/.claude/mcp.json` for Claude Code):
 
 ```json
 {
@@ -333,30 +234,21 @@ Add to your MCP client config (e.g. `~/.claude/mcp.json` for Claude Code):
 }
 ```
 
-The server exposes a `get_diff_context` tool. Your AI assistant will
-automatically call it when reviewing PRs, explaining changes, or investigating
-broken tests — no manual invocation needed.
-
-See [`src/diffctx/mcp/README.md`](src/diffctx/mcp/README.md) for configs
-for Cursor, Continue, Windsurf, and Zed.
+The server exposes a `get_diff_context` tool that assistants call when
+reviewing PRs, explaining changes, or investigating broken tests. Configs for
+Cursor, Continue, Windsurf, and Zed:
+[`src/diffctx/mcp/README.md`](src/diffctx/mcp/README.md).
 
-## Ignore Patterns
+## Ignore patterns
 
-Respects `.gitignore` and `.diffctx/ignore` automatically.
-Use `--no-default-ignores` to disable built-in patterns
-(`.gitignore` and `.diffctx/ignore` still apply).
+Respects `.gitignore` and `.diffctx/ignore` automatically — hierarchically at
+every directory level, with gitignore semantics (negation `!important.log`,
+anchored `/root_only.txt`). `.diffctx/whitelist` acts as an include-only
+filter, and the output file is always auto-ignored. `--no-default-ignores`
+disables the built-in patterns; `--no-ignores` disables all ignore rules
+(tree mode only).
 
-- Hierarchical: nested ignore files at each directory level
-- Negation patterns: `!important.log` un-ignores a file
-- Anchored patterns: `/root_only.txt` matches only in root
-- Output file is always auto-ignored
-
-Auto-discovered files:
-
-- `.diffctx/ignore` — diffctx-specific ignore patterns
-- `.diffctx/whitelist` — Include-only filter (only matched files included)
-
-## Exit Codes
+## Exit codes
 
 | Code | Meaning |
 |------|---------|
@@ -364,17 +256,10 @@ Auto-discovered files:
 | `1`  | Runtime error (bad path, permission denied, etc.) |
 | `2`  | Usage error (invalid flags/arguments) |
 | `3`  | Environment error (`--diff` outside a git repo, git not installed, no commits yet) |
-| `4`  | `--diff` produced no semantic context (clean working tree, binary-only, everything filtered out) — output is still emitted, but scripts can detect the empty case. Deletion/rename-only diffs are NOT empty: they list `deleted_files`/`renamed_files` and exit `0` |
+| `4`  | `--diff` produced no semantic context (clean tree, binary-only, everything filtered); output is still emitted. Deletion/rename-only diffs list `deleted_files`/`renamed_files` and exit `0` |
 | `130`| Interrupted (Ctrl-C) |
 | `141`| Broken pipe (e.g. piping into `head`) |
 
-## Content Placeholders
-
-- `<file too large: N bytes>` — exceeds `--max-file-bytes`
-- `<binary file: N bytes>` — binary file detected
-- `<unreadable content: not utf-8>` — not valid UTF-8
-- `<unreadable content>` — permission denied or I/O error
-
 ## License
 
 Apache 2.0

diffctx-1.12.0/README.md

@@ -0,0 +1,197 @@
+# diffctx — smart diff context for LLM code review
+
+[![CI](https://github.com/nikolay-e/diffctx/actions/workflows/ci.yml/badge.svg)](https://github.com/nikolay-e/diffctx/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/diffctx)](https://pypi.org/project/diffctx/)
+[![License](https://img.shields.io/pypi/l/diffctx)](https://pypi.org/project/diffctx/)
+
+**diffctx selects the minimum code an LLM needs to review a git diff.**
+Instead of pasting whole files, it walks the dependency graph from the changed
+lines outward and stops as soon as additional context stops paying for itself.
+
+> Coming from [`treemapper`](https://pypi.org/project/treemapper/)? That name is
+> deprecated — it was a thin wrapper around diffctx. Every command, flag, and
+> API call works unchanged: `treemapper` → `diffctx`, `treemapper-mcp` → `diffctx-mcp`.
+
+## Why not just use `tree` or repomix?
+
+| | `tree` | repomix | Claude Code Review | **diffctx** |
+|---|:---:|:---:|:---:|:---:|
+| **Primary use case** | directory listing | full repo export | automated PR review | **diff context for code review** |
+| Smart diff context | ✗ | ✗ | ✓ | ✓ |
+| Works with any LLM | ✓ | ✓ | Claude only | ✓ |
+| Free / local / offline | ✓ | ✓ | $15–25/review | ✓ |
+| GitHub required | ✗ | ✗ | ✓ | ✗ |
+| Multiple output formats | ✗ | limited | — | YAML/JSON/MD/txt |
+| Python API | ✗ | ✗ | ✗ | ✓ |
+| MCP server | ✗ | ✗ | ✗ | ✓ |
+
+## Install
+
+```bash
+uvx diffctx . --diff HEAD~1             # zero-install, run once via uv
+pipx install diffctx                    # recommended: isolated CLI, no venv needed
+pip install diffctx                     # or: into an active environment
+pipx install 'diffctx[mcp]'             # + MCP server for AI assistants
+```
+
+A standalone binary (no Python required) is on the
+[releases page](https://github.com/nikolay-e/diffctx/releases/latest).
+The `[tree-sitter]` extra adds AST-level parsing for more accurate context
+selection across 30+ languages.
+
+## Quick start
+
+```bash
+diffctx . --diff HEAD~1       # smart context for last commit → paste into Claude/ChatGPT
+diffctx . -f md -c            # full codebase export → clipboard in Markdown
+```
+
+![diffctx demo](https://raw.githubusercontent.com/nikolay-e/diffctx/main/docs/demo.gif)
+
+*`diffctx . --diff HEAD~1` selects only the fragments — functions, imports,
+type definitions — that an LLM actually needs to review the last commit,
+instead of dumping every changed file in full.*
+
+## Diff context mode
+
+Finds the minimal set of code fragments needed to understand a change —
+imports, callers, type definitions, config dependencies — across 50+ file
+types. It builds a code graph (imports, co-changes, type refs), propagates
+relevance from the changed lines outward, and stops when relevance drops below
+`--tau` or the `--budget` token cap is reached.
+
+| Flag        | Default | Description                                                              |
+|-------------|---------|--------------------------------------------------------------------------|
+| `--scoring` | `ego`   | `ego` = bounded expansion around changed nodes (fast, predictable radius); `ppr` = Personalized PageRank (global, smoother decay, slower); `bm25` = lexical retrieval against the diff hunks (baseline for sparse graphs) |
+| `--budget`  | auto    | Hard token cap: `N` enforces a fixed cap, `-1` disables it, `0` is a strict-zero floor (empty selection; use `--full` for changed files only) |
+| `--alpha`   | 0.60    | PPR damping; higher = context clusters tighter around changes (`--scoring ppr` only) |
+| `--tau`     | 0.12    | Relevance threshold for full fragment content; lower-scoring fragments are stubbed or dropped (lower = more context) |
+| `--full`    | false   | Only the changed files, every fragment, no related-code context          |
+| `--timeout` | 300     | Wall-clock deadline in seconds; on expiry diffctx exits 124 instead of hanging |
+
+Calibration of `--alpha`, `--tau`, and the edge-weight priors:
+[`docs/parameter-strategy.md`](docs/parameter-strategy.md). Theory:
+[Context-Selection for Git Diff (Zenodo, 2026)](https://doi.org/10.5281/zenodo.18824580).
+
+### `graph` subcommand
+
+Explore the underlying dependency graph directly, without a diff:
+
+```bash
+diffctx graph .                                  # Mermaid graph of directory deps (default)
+diffctx graph . --summary                        # cycles, hotspots, coupling metrics
+diffctx graph . --level fragment -f json         # fragment-level graph as JSON
+diffctx graph . --level file -f graphml -o g.xml # file-level graph as GraphML
+```
+
+## Usage
+
+<!-- BEGIN USAGE -->
+```bash
+# full codebase export:
+diffctx .                                # Markdown to stdout + token count
+diffctx . -f md -c                       # Markdown → clipboard
+diffctx . -f json -o tree.json           # JSON → file
+diffctx . --no-content                   # structure only, no file contents
+diffctx . --max-depth 3                  # limit depth
+diffctx . -i custom.ignore               # custom ignore patterns
+
+# diff context mode (requires git repo):
+diffctx . --diff                         # uncommitted changes (working tree vs HEAD)
+diffctx . --diff HEAD~1                  # context for last commit
+diffctx . --diff main..feature           # context for feature branch
+diffctx . --diff HEAD~1 --budget 30000   # limit to ~30k tokens
+diffctx . --diff HEAD~1 -c               # diff context to clipboard
+```
+<!-- END USAGE -->
+
+Every run reports token count and size on stderr — `12,847 tokens
+(o200k_base), 52.3 KB` (tiktoken, the GPT-4o tokenizer; `~`-prefixed
+approximation above 1 MB). `-c/--copy` sends output to the clipboard via
+`pbcopy` (macOS), `clip` (Windows), or `wl-copy`/`xclip`/`xsel` (Linux).
+Unreadable files are replaced by placeholders such as `<binary file: N bytes>`,
+`<file too large: N bytes>`, or `<unreadable content: not utf-8>`.
+
+## Python API
+
+```python
+from pathlib import Path
+from diffctx import build_diff_context, map_directory, to_json, to_markdown, to_text, to_yaml
+
+ctx = build_diff_context(
+    Path("."),
+    "HEAD~1..HEAD",
+    budget_tokens=None,       # None = auto; 0 = strict-zero floor (empty); -1 = uncapped; N = hard cap
+    alpha=0.6,
+    tau=0.12,
+    full=False,
+    scoring_mode="ego",
+    timeout=300,
+)
+print(to_markdown(ctx))
+
+tree = map_directory(
+    ".",
+    max_depth=None,
+    no_content=False,
+    max_file_bytes=None,
+    ignore_file=None,
+    no_default_ignores=False,
+    whitelist_file=None,
+)
+print(to_yaml(tree))
+```
+
+## MCP server
+
+diffctx includes an [MCP](https://modelcontextprotocol.io) server that lets AI
+assistants (Claude Code, Cursor, Windsurf, etc.) call diff context analysis
+automatically during code review. Install with `pip install 'diffctx[mcp]'`
+and add to your MCP client config (e.g. `~/.claude/mcp.json` for Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "diffctx": {
+      "command": "diffctx-mcp"
+    }
+  }
+}
+```
+
+The server exposes a `get_diff_context` tool that assistants call when
+reviewing PRs, explaining changes, or investigating broken tests. Configs for
+Cursor, Continue, Windsurf, and Zed:
+[`src/diffctx/mcp/README.md`](src/diffctx/mcp/README.md).
+
+## Ignore patterns
+
+Respects `.gitignore` and `.diffctx/ignore` automatically — hierarchically at
+every directory level, with gitignore semantics (negation `!important.log`,
+anchored `/root_only.txt`). `.diffctx/whitelist` acts as an include-only
+filter, and the output file is always auto-ignored. `--no-default-ignores`
+disables the built-in patterns; `--no-ignores` disables all ignore rules
+(tree mode only).
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Success — output contains content |
+| `1`  | Runtime error (bad path, permission denied, etc.) |
+| `2`  | Usage error (invalid flags/arguments) |
+| `3`  | Environment error (`--diff` outside a git repo, git not installed, no commits yet) |
+| `4`  | `--diff` produced no semantic context (clean tree, binary-only, everything filtered); output is still emitted. Deletion/rename-only diffs list `deleted_files`/`renamed_files` and exit `0` |
+| `130`| Interrupted (Ctrl-C) |
+| `141`| Broken pipe (e.g. piping into `head`) |
+
+## License
+
+Apache 2.0
+
+---
+
+- [Changelog](CHANGELOG.md)
+- [Security policy](SECURITY.md) — threat model and vulnerability reporting
+- [Parameter strategy](docs/parameter-strategy.md) — how `--alpha`,
+  `--tau`, and edge weights are calibrated