diffctx 1.10.2__tar.gz → 1.12.0__tar.gz

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

@@ -7,6 +7,98 @@ 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
+
+- **The default `--format` is now `md` (Markdown), previously `yaml`.** Markdown
+  is ~7% more token-efficient than YAML on real diffs and is preferred by
+  reviewers for code-fragment-heavy output (evidence:
+  `benchmarks/real_world_diff_bench/`). YAML remains available via `-f yaml`.
+  This also changes the default stdout format of `treemapper` (a passthrough
+  wrapper over this engine); downstream scripts that parse the default output
+  must now pass `-f yaml` explicitly. (#104)
+
 ## [1.10.0] - 2026-06-20
 
 ### Changed

diffctx-1.12.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: diffctx
+Version: 1.12.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: pathspec>=0.11,<2.0
+Requires-Dist: black>=23.0.0,<27.0 ; extra == 'dev'
+Requires-Dist: charset-normalizer>=3.0,<4.0 ; extra == 'dev'
+Requires-Dist: coverage>=7.0,<8.0 ; extra == 'dev'
+Requires-Dist: diffctx[tree-sitter] ; extra == 'dev'
+Requires-Dist: hypothesis>=6.0,<7.0 ; extra == 'dev'
+Requires-Dist: import-linter>=2.0,<3.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.0,<3.0 ; extra == 'dev'
+Requires-Dist: pre-commit>=3.0,<5.0 ; extra == 'dev'
+Requires-Dist: pygit2>=1.12,<2.0 ; extra == 'dev'
+Requires-Dist: pytest>=7.0,<10.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23,<2.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=3.0,<8.0 ; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1,<3.0 ; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0,<4.0 ; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.2,<8.0 ; extra == 'dev'
+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: charset-normalizer>=3.0,<4.0 ; extra == 'full'
+Requires-Dist: diffctx[tree-sitter] ; extra == 'full'
+Requires-Dist: anyio>=4.5,<5.0 ; extra == 'mcp'
+Requires-Dist: mcp>=1.27,<2.0 ; extra == 'mcp'
+Requires-Dist: tree-sitter>=0.21,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-c>=0.21,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-c-sharp>=0.21,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-cpp>=0.22,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-elixir>=0.3,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-go>=0.21,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-html>=0.23,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-java>=0.21,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-javascript>=0.21,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-lua>=0.5,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-php>=0.24,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-python>=0.21,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-ruby>=0.21,<1.0 ; extra == 'tree-sitter'
+Requires-Dist: tree-sitter-rust>=0.21,<1.0 ; extra == 'tree-sitter'
+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: full
+Provides-Extra: mcp
+Provides-Extra: tree-sitter
+License-File: LICENSE
+Summary: Export codebase structure and contents for AI/LLM context
+Keywords: ai,chatgpt,claude,code-analysis,code-context,code-review,code-to-prompt,codebase,context,context-selection,diff-context,directory-tree,export,git-diff,json,llm,llm-context,mcp,model-context-protocol,tree,yaml
+Author-email: Nikolay Eremeev <nikolay.eremeev@outlook.com>
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/nikolay-e/diffctx/releases
+Project-URL: Homepage, https://github.com/nikolay-e/diffctx
+Project-URL: Issues, https://github.com/nikolay-e/diffctx/issues
+Project-URL: Repository, https://github.com/nikolay-e/diffctx
+
+# 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
+

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

{diffctx-1.10.2 → diffctx-1.12.0}/diffctx/Cargo.lock

@@ -63,9 +63,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.102"
+version = "1.0.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
 
 [[package]]
 name = "base64"
@@ -123,9 +123,9 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "clap"
-version = "4.6.1"
+version = "4.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
+checksum = "dd059f9da4f5c36b3787f65d38ccaab1cc315f07b01f89abc8359ee6a8205011"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -133,9 +133,9 @@ dependencies = [
 
 [[package]]
 name = "clap_builder"
-version = "4.6.0"
+version = "4.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
+checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
 dependencies = [
  "anstream",
  "anstyle",
@@ -194,11 +194,12 @@ checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
 [[package]]
 name = "diffctx"
-version = "1.10.0"
+version = "1.12.0"
 dependencies = [
  "anyhow",
  "clap",
  "glob",
+ "libc",
  "libtest-mimic",
  "mimalloc",
  "once_cell",
@@ -210,7 +211,6 @@ dependencies = [
  "serde_json",
  "serde_yaml",
  "similar",
- "smallvec",
  "tempfile",
  "thiserror",
  "tiktoken-rs",
@@ -399,9 +399,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.185"
+version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "libmimalloc-sys"
@@ -606,9 +606,9 @@ dependencies = [
 
 [[package]]
 name = "regex"
-version = "1.12.4"
+version = "1.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1292b7759ae1cb9ec195452d1390a074f0cd8541ab7a5a8c31cd6db45d4a6ba"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -618,9 +618,9 @@ dependencies = [
 
 [[package]]
 name = "regex-automata"
-version = "0.4.14"
+version = "0.4.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -635,9 +635,9 @@ checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
 
 [[package]]
 name = "rustc-hash"
-version = "2.1.2"
+version = "2.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
 
 [[package]]
 name = "rustix"
@@ -964,9 +964,9 @@ dependencies = [
 
 [[package]]
 name = "tree-sitter-cmake"
-version = "0.7.1"
+version = "0.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7c1b35d1dd7396d24b3e826bb0f975b915ec7e9125b989d5e9d24ebb6a08509a"
+checksum = "164e0c4f4236ec5ceff14824a5528615cf462e100467e49826442ff57d327061"
 dependencies = [
  "cc",
  "tree-sitter-language",