diffctx 1.15.0 → 1.17.0

package/README.md

@@ -45,8 +45,15 @@ scoop bucket add diffctx https://github.com/nikolay-e/diffctx
 scoop install diffctx/diffctx
 ```
 
-Prebuilt binaries for linux (x86_64/aarch64), macOS (arm64) and Windows (x64)
-are attached to every [release](https://github.com/nikolay-e/diffctx/releases/latest).
+Every [release](https://github.com/nikolay-e/diffctx/releases/latest) carries
+prebuilt binaries; the current target set is Linux (x86_64/aarch64), macOS
+(arm64/x86_64) and Windows (x64/arm64), and a release older than a target's
+first build lacks it (v1.16.0 predates the macOS x86_64 and Windows arm64
+archives). On Windows on ARM, `diffctx[mcp]` builds `cryptography` from source,
+which needs OpenSSL: that project publishes no wheel for the platform.
+Free-threaded CPython (`3.14t`) cannot load the `abi3` wheel, so each release
+after 1.16.0 also ships a `cp314t` wheel per platform (the extension runs with
+the GIL off); on 1.16.0 itself `pip` and `uv` fall back to compiling the sdist.
 The native binary and Docker image cover diff mode with YAML/JSON output and
 write to stdout (redirect to capture); tree mode, Markdown output, the `graph`
 subcommand and the MCP server live in the Python package.
@@ -81,15 +88,22 @@ keeps its git meaning.
 
 | 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); `rrf` = reciprocal-rank fusion of `ego` and `bm25` (widest recall, no scale calibration between the two signals) |
-| `--budget`  | auto    | Hard cap in o200k_base tokens (see [Token counting](docs/product/token-budget.md)): `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) |
+| `--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); `rrf` = reciprocal-rank fusion of `ego` and `bm25` (widest recall, no scale calibration between the two signals); `pit` = the same fusion on score percentiles |
+| `--budget`  | auto    | Cap in o200k_base tokens on the whole rendered artifact (see [Token counting](docs/product/token-budget.md)): every changed file gets one witness first, relevance fills the rest, and the renderer drops context from the tail until the document fits. A budget smaller than the summary yields the summary alone. `N` = fixed cap, `-1` disables it, `0` is a strict-zero floor (no fragments; use `--full` for changed files only) |
+| `--alpha`   | 0.60    | PPR continuation probability: higher = relevance travels further from the change, lower = tighter around it (`--scoring ppr` only) |
 | `--tau`     | 0.05    | 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 |
+| `--timeout` | 300     | Wall-clock deadline in seconds; on expiry the run stops cooperatively and emits a partial artifact whose `coverage` block names the limit (exit 0). 124 is the watchdog behind it, 30 s later, for a phase that could not stop |
 | `--with-raw-diff` | false | Also embed git's raw unified diff ahead of the selected fragments — additive (selection unchanged), not charged to `--budget`, lock/ignored/secret-like sections omitted. Python CLI only |
 | `--mode` | `pack` | `locate` emits the same ranked selection as compact `diffctx.locate.v1` JSON — path, lines, score, provenance reasons, a blast-radius `summary` and per-item impact `group` (`test`/`type`/`config`), NO source bodies. Adds a `coverage` block naming what the run could not see (`unparsed_files`, `zero_edge_files`, `ppr_truncated`, `next_up`, a heuristic `confidence`) and an `overflow` ranking of what the budget left behind — omitted entirely when there is nothing to disclose. `diffctx . --diff --mode locate` = impact of your uncommitted change. The MCP tool takes it as `mode="locate"` |
 
+Every JSON/YAML artifact opens with `schema: diffctx.context.v1` and validates
+against [`schemas/diffctx.context.v1.json`](schemas/diffctx.context.v1.json),
+generated from the engine's own type; it closes with a `provenance` block
+(engine version, input object ids, the effective configuration and its hash,
+the selection parameters, the tokenizer) and, when a limit stopped the run
+short, a `coverage` block naming it.
+
 ### `graph` subcommand
 
 Explore the underlying dependency graph directly, without a diff:
@@ -141,7 +155,7 @@ from diffctx import build_diff_context, map_directory, to_json, to_markdown, to_
 ctx = build_diff_context(
     Path("."),
     "HEAD~1..HEAD",
-    budget_tokens=None,       # None = auto; 0 = strict-zero floor (empty); -1 = uncapped; N = hard cap
+    budget_tokens=None,       # None = auto; 0 = no fragments; -1 = uncapped; N = cap on the whole artifact
     alpha=0.6,
     tau=0.05,
     full=False,
@@ -193,17 +207,46 @@ reviewing PRs, explaining changes, or investigating broken tests. It ranks the
 code that explains a diff, then reads only the fragments the assistant picked —
 two calls that pay for the selection instead of a whole pack. The wider
 `get_tree_map` and `get_file_context` tools are opt-in via
-`DIFFCTX_MCP_LEGACY_TOOLS=1`. Tool reference and JSON configs for Claude
-Desktop, Cursor, Continue, Windsurf, and Zed:
-[`src/diffctx/mcp/README.md`](src/diffctx/mcp/README.md).
+`DIFFCTX_MCP_LEGACY_TOOLS=1`. Filesystem confinement via
+`DIFFCTX_ALLOWED_PATHS`: see [SECURITY.md](SECURITY.md).
+
+Every stdio client takes the same server shape; only the config file differs:
+
+| Client | Config file | Key |
+|---|---|---|
+| Claude Code (project) | `.mcp.json` | `mcpServers` |
+| Claude Desktop | `claude_desktop_config.json` | `mcpServers` |
+| Cursor | `~/.cursor/mcp.json` | `mcpServers` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
+| Continue | `~/.continue/config.json` | `experimental.modelContextProtocolServers` (transport object) |
+| Zed | `~/.config/zed/settings.json` | `context_servers` (`command.path`) |
+
+```json
+{
+  "mcpServers": {
+    "diffctx": {
+      "command": "uvx",
+      "args": ["--from", "diffctx[mcp]", "diffctx-mcp"]
+    }
+  }
+}
+```
+
+With `pip install 'diffctx[mcp]'` already done, `"command": "diffctx-mcp"` with
+no args works everywhere instead. Use the `diffctx-mcp` entry point, not the
+`diffctx mcp` subcommand: the latter only exists from 1.12.3 onward and would
+map a directory named `mcp` on older releases.
 
 ## Ignore patterns
 
 Respects `.gitignore` and `.diffctx/ignore` automatically — hierarchically at
 every directory level, with full 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).
+anchored `/root_only.txt`), and in tree mode the output file is always
+auto-ignored (`--diff` reports a saved `tree.md` like any other change). Three
+controls are tree mode only and are refused with `--diff` and `graph`: `.diffctx/whitelist`
+(`-w`) as an include-only filter, `-i` for an extra ignore file, and
+`--no-default-ignores` / `--no-ignores` to drop the built-in patterns or every
+ignore rule.
 
 An excluded path never appears in the output in any role: in diff mode it is
 dropped both from `changed_files` and from the candidate universe, so it cannot
@@ -224,10 +267,10 @@ its size (default 512 MB, `0` disables eviction).
 |------|---------|
 | `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) |
+| `2`  | Usage error (invalid flags/arguments, an empty `--diff ""`, a malformed duration such as `1.5h`, an out-of-range `--alpha`/`--tau`/`--budget`/`--timeout`, or a tree-mode flag — `-i`/`-w`/`--no-default-ignores`/`--no-ignores` — given with `--diff` or `graph`) |
+| `3`  | Environment error (`--diff` outside a git repo, in a bare one, or on a missing path, git not installed or refusing to start — its `fatal:` line is printed, no commits yet, a revision missing from a shallow clone) |
 | `4`  | `--diff` produced no semantic context (clean tree, binary-only, everything filtered); output is still emitted. Deletion/rename/lockfile-only diffs list `deleted_files`/`renamed_files`/`lockfile_changes` and exit `0` |
-| `124`| `--diff` exceeded the `--timeout` wall-clock deadline |
+| `124`| `--diff` ran 30 s past the `--timeout` deadline without stopping cooperatively (the deadline itself yields a partial artifact and exit 0) |
 | `130`| Interrupted (Ctrl-C) |
 | `141`| Broken pipe (e.g. piping into `head`) |
 
@@ -241,14 +284,20 @@ Apache 2.0
 
 ---
 
-- [Documentation site](https://nikolay-e.github.io/diffctx/) — the pipeline
+- [Documentation site](https://diffctx.com/) — the pipeline
   end to end: diff → fragments → graph → relevance → selection
+- [Command-line reference](docs/product/cli.md) — every flag with its default
+  and meaning, rendered from `diffctx --help`
 - [GitHub Action](docs/product/github-action.md) — diff context as a CI step
   for LLM review
 - [Token counting](docs/product/token-budget.md) — which encoder, and what
   `--budget` means for non-GPT models
 - [Comparison](COMPARISON.md) — measured results, and when a whole-repo packer
   or a persistent code-graph server fits better
+- [Benchmarks](BENCHMARKS.md) — every published number with what it was
+  measured on, and how to reproduce it
+- [FAQ](docs/product/faq.md) — heuristic or oracle, whose tokens, monorepos,
+  the raw diff, secrets
 - [Paper](https://doi.org/10.5281/zenodo.18824579) — budgeted typed-graph
   retrieval for diff-aware context selection (Zenodo, 2026)
 - [Changelog](CHANGELOG.md)

package/checksums.json

@@ -1,6 +1,8 @@
 {
-  "diffctx-1.15.0-aarch64-apple-darwin.tar.gz": "721f534c2f6c3c6b6bd1a8e9e1a9595116202cb9177c294d625f55d34fb00bed",
-  "diffctx-1.15.0-aarch64-unknown-linux-gnu.tar.gz": "1c9bc1fb064547f24f74401a9e7bab4b85b1c93006e740faae6c1ee2a9bf1a87",
-  "diffctx-1.15.0-x86_64-pc-windows-msvc.zip": "91bb8437cab735b674bb14a76ddc04f8477d8e37766336157551854dc5ab2e1d",
-  "diffctx-1.15.0-x86_64-unknown-linux-gnu.tar.gz": "bfe4b6efc300bd9f38832d10e8a1bb63d6c1e3a328ccf774901f34c914fa513f"
+  "diffctx-1.17.0-aarch64-apple-darwin.tar.gz": "5e69dcea8229c8622bca301c40dcd21edbd1867f2be0b8f65bb321c37864aea3",
+  "diffctx-1.17.0-aarch64-pc-windows-msvc.zip": "499d32a204a7e11e50009a9b244ca74eece0ca859c45257bb2060f5de797f4cd",
+  "diffctx-1.17.0-aarch64-unknown-linux-gnu.tar.gz": "dfb3408e07dc89175327a742f856f6b915a7aefcd73dbe12779138fe10e53086",
+  "diffctx-1.17.0-x86_64-apple-darwin.tar.gz": "6188aca98dae1bef57b1bdcb3602deb61c9b036a4e103c5681b058037e425663",
+  "diffctx-1.17.0-x86_64-pc-windows-msvc.zip": "c774f09790f64b6a104029dcf41b49b37cecea3176c52231417f0ecb58f6c84b",
+  "diffctx-1.17.0-x86_64-unknown-linux-gnu.tar.gz": "3106217351d1a7e00fbd1c29593814cf633be45931cb9a4a5eb9edb18910d74c"
 }

package/install.js

@@ -15,7 +15,9 @@ const TARGETS = {
   'linux-x64': { target: 'x86_64-unknown-linux-gnu', archive: 'tar.gz' },
   'linux-arm64': { target: 'aarch64-unknown-linux-gnu', archive: 'tar.gz' },
   'darwin-arm64': { target: 'aarch64-apple-darwin', archive: 'tar.gz' },
+  'darwin-x64': { target: 'x86_64-apple-darwin', archive: 'tar.gz' },
   'win32-x64': { target: 'x86_64-pc-windows-msvc', archive: 'zip' },
+  'win32-arm64': { target: 'aarch64-pc-windows-msvc', archive: 'zip' },
 };
 
 function selectTarget() {
@@ -24,7 +26,8 @@ function selectTarget() {
   if (!selected) {
     throw new Error(
       `diffctx has no prebuilt binary for ${key}. ` +
-        'Install via pip ("pip install diffctx") or cargo ("cargo install diffctx") instead.'
+        'Build from source with "pip install diffctx --no-binary diffctx" (needs Rust) ' +
+        'or "cargo install diffctx".'
     );
   }
   return selected;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "diffctx",
   "mcpName": "io.github.nikolay-e/diffctx",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Selects the minimum code an LLM needs to review a git diff",
   "keywords": [
     "git",
@@ -17,7 +17,7 @@
     "llm-context",
     "codebase"
   ],
-  "homepage": "https://github.com/nikolay-e/diffctx",
+  "homepage": "https://diffctx.com/",
   "bugs": "https://github.com/nikolay-e/diffctx/issues",
   "repository": {
     "type": "git",