diffctx 1.16.0__tar.gz → 1.18.0__tar.gz

{diffctx-1.16.0 → diffctx-1.18.0}/CHANGELOG.md

@@ -7,6 +7,127 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.18.0] - 2026-09-29
+
+### Added
+
+- **`--mode impact`: what a change reaches outside its own diff, under 2k
+  tokens.** For each changed symbol, the callers in files the diff does not
+  touch, whether a test guards each one, and which symbols more than one
+  commit of the range edited; public API and schema changes are listed as
+  facts. It walks the graph the other modes already build, with a discovery
+  pass that follows references *into* the changed files (the other modes
+  only follow what the changed files import), and filters name-only links
+  the way a reader would: the caller must name the symbol in code and
+  reference its module. An empty impact is an answer, not an error. CLI
+  (`-f md` is the text form), MCP `mode="impact"`, the GitHub Action's
+  `mode` input, and `schemas/diffctx.impact.v1.json`.
+- **`diffctx hook pretooluse` / `posttooluse`: the Claude Code plugin hands
+  the agent a change's impact without asking it to call anything.** Eight
+  agent sessions with the tool installed made zero unprompted calls (#289).
+  Before a commit, merge, cherry-pick, push or pull request the impact of
+  what that command records is injected as context — a plain `git commit`
+  reviews the index, `-a` the working tree, a merge the branch since its
+  merge base; after a `git diff` or `git status` the agent ran itself, the
+  pending change's impact rides on the answer it asked for. Once per change
+  (content-keyed with `git patch-id`, so a manual `--mode impact` run
+  counts), silent when nothing outside the diff depends on the change, and
+  never blocking: a range that runs out of the 30 s deadline is marked
+  reviewed rather than retried on every push. `impact_gate` (off by default)
+  denies a commit until its impact was shown once. At session start the
+  plugin fetches the release binary for the platform, verified against
+  `checksums.json`, into its data directory, backs off for six hours after a
+  failed download, and puts the one-line recipe into the session's context;
+  `impact_hook` turns all of it off (#310).
+- **`/diffctx:commit`**: the impact first, then the commit.
+- **`diffctx_context` is always loaded** under Claude Code's tool search
+  (`_meta.anthropic/alwaysLoad`), and its description names `impact` as the
+  pre-commit call; both skills default to the server's own range choice.
+- **The PR review comment opens with the impact view.**
+- **Plugin eval `breaking-caller`** measures the number under the goal: with
+  a contract change uncommitted and two callers about to break, does the
+  agent handle or name them before committing.
+
+## [1.17.0] - 2026-09-23
+
+### Added
+
+- **The site lives at <https://diffctx.com>.** It was a 301 to
+  `nikolay-e.github.io/diffctx/`, so search engines indexed the github.io
+  URL and the product domain had no presence of its own. It is now the
+  GitHub Pages custom domain (github.io redirects to it), with a
+  `robots.txt` and `sitemap.xml`; package metadata points at it.
+- **Windows and Intel-Mac are release targets.** Every test matrix runs on
+  Linux, macOS and Windows on x64 and ARM; wheels and binaries ship for
+  `x86_64-apple-darwin` and `aarch64-pc-windows-msvc` as well, and `npm
+  install diffctx` and the Scoop bucket select them. What that exposed is
+  fixed: `--output-file` on Windows, backslashes in MCP output and in the
+  Rust path matching (discovery, C#/Go/Cargo edges), datasets checked out
+  byte-exact under a CRLF `autocrlf`, and a `--timeout 0` that now always
+  reports the timeout instead of racing the subprocess.
+- **The landing page installs and opens offline** — a web manifest, icons
+  and a service worker that keeps every visit network-first.
+- **Free-threaded CPython gets a wheel.** Each platform ships a `cp314t`
+  wheel beside the `abi3` one; `uvx` on 3.14t no longer compiles the sdist
+  (which timed MCP clients out), and the extension keeps the GIL off.
+- **The GitHub Action works on a default shallow checkout**: with no
+  `diff-range` it fetches the pull request's base and head (or `HEAD~1`)
+  itself, so `fetch-depth: 0` is no longer required.
+- **`provenance.engine.build` names the release commit** in wheels, binaries
+  and the image.
+- **A glossary line under the scoring modes** on the landing page: three
+  independent first-visit probes stalled on `ego-network`, `PPR`, `rrf`,
+  `pit`, `τ` and `o200k_base` with nothing on the page defining them.
+
+### Removed
+
+- **`build_diff_context(ignore_file=…, whitelist_file=…, no_default_ignores=…)`.**
+  The engine never applied a custom path-spec layer in diff mode and the three
+  arguments existed only to raise `NotImplementedError`; passing one is now a
+  `TypeError`. `.gitignore` and `.diffctx/ignore` still apply.
+
+### Fixed
+
+- **The MCP server no longer hangs on Windows.** Every git child inherited the
+  server's stdin, which under an MCP client is the JSON-RPC pipe the client
+  holds open, and on Windows such a git never exited: any tool call that reached
+  git hung. Child processes now get a null stdin in both the engine and the
+  Python layer.
+- **A long range says how many commits it held.** The commit list stops at
+  the newest twenty; the artifact read "20 commits" over a 42-commit range. It
+  now carries `commit_count` and reads "newest 20 of 42 commits" when the list
+  is cut, in both CLIs, pack and locate.
+- **`--budget` fitting never passes context off as the change.** The witness
+  clip shortened any file's last fragment, so a context file shrank line by line
+  under a "more lines of this change" marker before it dropped; only a changed
+  fragment is shortened now.
+- **MCP `fragment_ids` on a bare `diff_ref` read the code the change
+  replaced.** `HEAD` (or `HEAD~3`, or a duration window) is git's
+  base-versus-working-tree, so the locate ranking describes the files on
+  disk; the fetch read the base blob instead and returned the old body under
+  the ranking's own id. Bodies for a `..`-less ref now come from the working
+  tree, and a file the named revision lacks (or a revision git cannot
+  resolve) is reported as not found instead of being substituted with the
+  working-tree file under a historical label.
+- **The native binary fits the written artifact to `--budget`** (#277).
+  npm, Scoop, Docker and the release archives ship the Rust binary, which
+  documented `--budget` as a cap on the whole artifact and enforced nothing on
+  the document it wrote: 9,121 tokens at `--budget 8000` on a real range. It
+  now runs the same render-count-drop loop as the Python CLI (context from the
+  tail first, a changed file's second fragment next, mechanical witnesses
+  before hand-written ones), records `selection_budget_exceeded` in
+  `coverage`, and exits 4 when nothing fits — the two CLIs deliver one set.
+- **Eval harness: gold paths git had quoted** (`"b/caf\303\251.py"`) were
+  taken literally, so every non-ASCII gold file scored as a miss; the patch
+  header parser unquotes them. A checkpoint whose last line a kill left
+  unterminated no longer swallows the next appended row on resume.
+
+### Changed
+
+- The GitHub Action's `python-version` defaults to `3.13` (`--output-file`
+  needs `os.fchmod`, which Windows Python gained in 3.13); the action
+  reference page says so. `--budget --help` names what `auto` resolves to.
+
 ## [1.16.0] - 2026-09-16
 
 ### Added
@@ -1551,7 +1672,9 @@ Earlier releases shipped as `treemapper`; see
 <https://github.com/nikolay-e/diffctx/releases> for the corresponding GitHub
 release notes (`1.0.0` through `1.6.1`).
 
-[Unreleased]: https://github.com/nikolay-e/diffctx/compare/v1.16.0...HEAD
+[Unreleased]: https://github.com/nikolay-e/diffctx/compare/v1.18.0...HEAD
+[1.18.0]: https://github.com/nikolay-e/diffctx/compare/v1.17.0...v1.18.0
+[1.17.0]: https://github.com/nikolay-e/diffctx/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/nikolay-e/diffctx/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/nikolay-e/diffctx/compare/v1.14.0...v1.15.0
 [1.14.0]: https://github.com/nikolay-e/diffctx/compare/v1.13.0...v1.14.0

{diffctx-1.16.0 → diffctx-1.18.0}/Cargo.lock

@@ -123,9 +123,9 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "clap"
-version = "4.6.6"
+version = "4.6.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca"
+checksum = "aa8876b300ab35ba921adea3dfd70157a46249b33f95c9084ae5709785478946"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -133,9 +133,9 @@ dependencies = [
 
 [[package]]
 name = "clap_builder"
-version = "4.6.6"
+version = "4.6.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889"
+checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d"
 dependencies = [
  "anstream",
  "anstyle",
@@ -145,9 +145,9 @@ dependencies = [
 
 [[package]]
 name = "clap_derive"
-version = "4.6.4"
+version = "4.6.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+checksum = "f9c751b79415d4e559e3d1fcf128e09e720eb673a06d26cf6f392d37d75b66e0"
 dependencies = [
  "heck",
  "proc-macro2",
@@ -194,11 +194,12 @@ checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
 [[package]]
 name = "diffctx"
-version = "1.16.0"
+version = "1.18.0"
 dependencies = [
  "aho-corasick",
  "anyhow",
  "clap",
+ "dunce",
  "glob",
  "libc",
  "libtest-mimic",
@@ -260,6 +261,12 @@ dependencies = [
  "walkdir",
 ]
 
+[[package]]
+name = "dunce"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
+
 [[package]]
 name = "dyn-clone"
 version = "1.0.20"

{diffctx-1.16.0 → diffctx-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffctx
-Version: 1.16.0
+Version: 1.18.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -44,15 +44,15 @@ Provides-Extra: mcp
 License-File: LICENSE
 Summary: Selects the minimum code an LLM needs to review a git diff
 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
-Home-Page: https://github.com/nikolay-e/diffctx
+Home-Page: https://diffctx.com/
 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: Author, https://nikolay-eremeev.com
 Project-URL: Changelog, https://github.com/nikolay-e/diffctx/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://nikolay-e.github.io/diffctx/
-Project-URL: Homepage, https://nikolay-e.github.io/diffctx/
+Project-URL: Documentation, https://diffctx.com/
+Project-URL: Homepage, https://diffctx.com/
 Project-URL: Issues, https://github.com/nikolay-e/diffctx/issues
 Project-URL: Paper, https://doi.org/10.5281/zenodo.18824579
 Project-URL: Repository, https://github.com/nikolay-e/diffctx
@@ -104,8 +104,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.
@@ -241,7 +248,10 @@ as `io.github.nikolay-e/diffctx`. One-line setup (zero-install via
 [uv](https://docs.astral.sh/uv/)):
 
 ```bash
-# Claude Code
+# Claude Code plugin: the server plus /diffctx:diffctx and /diffctx:impact
+claude plugin marketplace add nikolay-e/diffctx
+claude plugin install diffctx@diffctx
+# Claude Code, server only
 claude mcp add diffctx -- uvx --from 'diffctx[mcp]' diffctx-mcp
 # Codex CLI
 codex mcp add diffctx -- uvx --from 'diffctx[mcp]' diffctx-mcp
@@ -293,8 +303,9 @@ map a directory named `mcp` on older releases.
 
 Respects `.gitignore` and `.diffctx/ignore` automatically — hierarchically at
 every directory level, with full gitignore semantics (negation `!important.log`,
-anchored `/root_only.txt`), and the output file is always auto-ignored. Three
-controls are tree mode only and are refused with `--diff`: `.diffctx/whitelist`
+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.
@@ -318,8 +329,8 @@ 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` ran 30 s past the `--timeout` deadline without stopping cooperatively (the deadline itself yields a partial artifact and exit 0) |
 | `130`| Interrupted (Ctrl-C) |
@@ -335,7 +346,7 @@ 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`

{diffctx-1.16.0 → diffctx-1.18.0}/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.
@@ -182,7 +189,10 @@ as `io.github.nikolay-e/diffctx`. One-line setup (zero-install via
 [uv](https://docs.astral.sh/uv/)):
 
 ```bash
-# Claude Code
+# Claude Code plugin: the server plus /diffctx:diffctx and /diffctx:impact
+claude plugin marketplace add nikolay-e/diffctx
+claude plugin install diffctx@diffctx
+# Claude Code, server only
 claude mcp add diffctx -- uvx --from 'diffctx[mcp]' diffctx-mcp
 # Codex CLI
 codex mcp add diffctx -- uvx --from 'diffctx[mcp]' diffctx-mcp
@@ -234,8 +244,9 @@ map a directory named `mcp` on older releases.
 
 Respects `.gitignore` and `.diffctx/ignore` automatically — hierarchically at
 every directory level, with full gitignore semantics (negation `!important.log`,
-anchored `/root_only.txt`), and the output file is always auto-ignored. Three
-controls are tree mode only and are refused with `--diff`: `.diffctx/whitelist`
+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.
@@ -259,8 +270,8 @@ 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` ran 30 s past the `--timeout` deadline without stopping cooperatively (the deadline itself yields a partial artifact and exit 0) |
 | `130`| Interrupted (Ctrl-C) |
@@ -276,7 +287,7 @@ 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`

{diffctx-1.16.0 → diffctx-1.18.0}/crates/diffctx-native/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "diffctx"
-version = "1.16.0"
+version = "1.18.0"
 edition = "2024"
 rust-version = "1.85"
 description = "Selects the minimum code an LLM needs to review a git diff: walks the dependency graph outward from changed lines and stops when extra context stops paying for itself"
 license = "Apache-2.0"
 repository = "https://github.com/nikolay-e/diffctx"
-homepage = "https://github.com/nikolay-e/diffctx"
+homepage = "https://diffctx.com/"
 documentation = "https://docs.rs/diffctx"
 readme = "README.md"
 keywords = ["git", "diff", "llm", "context", "tree-sitter"]
@@ -71,6 +71,7 @@ lang-extra = [
 [dependencies]
 mimalloc = { version = "0.1", default-features = false }
 clap = { version = "4", features = ["derive"] }
+dunce = "1"
 tree-sitter = "0.25"
 tree-sitter-python = { version = "0.25", optional = true }
 tree-sitter-javascript = { version = "0.25", optional = true }

{diffctx-1.16.0 → diffctx-1.18.0}/crates/diffctx-native/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.
@@ -182,7 +189,10 @@ as `io.github.nikolay-e/diffctx`. One-line setup (zero-install via
 [uv](https://docs.astral.sh/uv/)):
 
 ```bash
-# Claude Code
+# Claude Code plugin: the server plus /diffctx:diffctx and /diffctx:impact
+claude plugin marketplace add nikolay-e/diffctx
+claude plugin install diffctx@diffctx
+# Claude Code, server only
 claude mcp add diffctx -- uvx --from 'diffctx[mcp]' diffctx-mcp
 # Codex CLI
 codex mcp add diffctx -- uvx --from 'diffctx[mcp]' diffctx-mcp
@@ -234,8 +244,9 @@ map a directory named `mcp` on older releases.
 
 Respects `.gitignore` and `.diffctx/ignore` automatically — hierarchically at
 every directory level, with full gitignore semantics (negation `!important.log`,
-anchored `/root_only.txt`), and the output file is always auto-ignored. Three
-controls are tree mode only and are refused with `--diff`: `.diffctx/whitelist`
+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.
@@ -259,8 +270,8 @@ 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` ran 30 s past the `--timeout` deadline without stopping cooperatively (the deadline itself yields a partial artifact and exit 0) |
 | `130`| Interrupted (Ctrl-C) |
@@ -276,7 +287,7 @@ 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`

diffctx-1.18.0/crates/diffctx-native/src/candidate_files.rs

@@ -0,0 +1,201 @@
+use std::path::{Path, PathBuf};
+
+use rayon::prelude::*;
+use rustc_hash::{FxHashMap, FxHashSet};
+use walkdir::WalkDir;
+
+use crate::config::graph_filtering::GRAPH_FILTERING;
+use crate::config::limits::LIMITS;
+use crate::git;
+use crate::languages::get_language_for_file;
+
+const SHEBANG_SNIFF_BYTES: usize = 128;
+
+fn is_allowed_file(path: &Path) -> bool {
+    let name = path.to_string_lossy();
+    get_language_for_file(&name).is_some()
+        || (path.extension().is_none() && has_known_shebang(path, &name))
+}
+
+fn has_known_shebang(path: &Path, name: &str) -> bool {
+    use std::io::Read;
+    let mut head = [0u8; SHEBANG_SNIFF_BYTES];
+    let Ok(read) = std::fs::File::open(path).and_then(|mut f| f.read(&mut head)) else {
+        return false;
+    };
+    crate::languages::sniff_language(name, &String::from_utf8_lossy(&head[..read])).is_some()
+}
+
+fn is_candidate_file(
+    file_path: &Path,
+    root_dir: &Path,
+    included_set: &FxHashSet<PathBuf>,
+    ctx: &crate::resource::RunContext,
+) -> bool {
+    // `is_file()` and `metadata()` both follow symlinks, and every path here is
+    // only LEXICALLY under the root — `git ls-files` reports the link, not its
+    // target. Without this the universe admits `repo/evil -> /etc/shadow`,
+    // discovery reads it with a bare `read_to_string`, and the content is a
+    // context fragment. The boundary is checked once, here, so the readers
+    // downstream stay simple; a link pointing INSIDE the repo still resolves.
+    if crate::paths::resolve_within(root_dir, file_path).is_none() {
+        return false;
+    }
+    if !file_path.is_file() {
+        return false;
+    }
+    if !is_allowed_file(file_path) {
+        return false;
+    }
+    if included_set.contains(file_path) {
+        return false;
+    }
+    match file_path.metadata() {
+        Ok(meta) if meta.len() as usize > LIMITS.max_file_size => {
+            // A source file the universe will not read is a hole in the
+            // context, and the artifact says so rather than rendering as
+            // complete (#T4.2: a 237 KB helper importing the changed file
+            // vanished with no coverage block).
+            ctx.note(crate::resource::LimitReason::FileTooLarge);
+            return false;
+        }
+        Err(_) => return false,
+        _ => {}
+    }
+    true
+}
+
+/// The discovery universe under `scope` (repo-relative pathspecs; empty is
+/// the whole repository), with every size exclusion recorded on `ctx`.
+pub fn collect_candidate_files(
+    root_dir: &Path,
+    included_set: &FxHashSet<PathBuf>,
+    scope: &[String],
+    ctx: &crate::resource::RunContext,
+) -> Vec<PathBuf> {
+    match tracked_candidates(root_dir, included_set, scope, ctx) {
+        Some(files) => filter_ignored_and_secret(root_dir, files),
+        // The walk sees untracked paths, so ancestor-inherited rules must count
+        // (`.venv/x.py` is ignored BY `.venv/`); the attribution variant drops them.
+        None => filter_ignored_and_secret_walked(
+            root_dir,
+            walked_candidates(root_dir, included_set, scope, ctx),
+        ),
+    }
+}
+
+fn tracked_candidates(
+    root_dir: &Path,
+    included_set: &FxHashSet<PathBuf>,
+    scope: &[String],
+    ctx: &crate::resource::RunContext,
+) -> Option<Vec<PathBuf>> {
+    let mut args: Vec<&str> = vec!["ls-files", "-z"];
+    if !scope.is_empty() {
+        args.push("--");
+        args.extend(scope.iter().map(String::as_str));
+    }
+    let parts = git::run_git_z(root_dir, &args).ok()?;
+    Some(
+        parts
+            .into_iter()
+            .map(|f| crate::paths::repo_join(root_dir, &f))
+            .collect::<Vec<PathBuf>>()
+            .into_par_iter()
+            .filter(|f| is_candidate_file(f, root_dir, included_set, ctx))
+            .collect(),
+    )
+}
+
+fn is_walk_skipped_dir(entry: &walkdir::DirEntry) -> bool {
+    entry.depth() > 0
+        && entry.file_type().is_dir()
+        && entry.file_name().to_str().is_some_and(|name| {
+            name.starts_with('.') || name == "node_modules" || name == "__pycache__"
+        })
+}
+
+fn walked_candidates(
+    root_dir: &Path,
+    included_set: &FxHashSet<PathBuf>,
+    scope: &[String],
+    ctx: &crate::resource::RunContext,
+) -> Vec<PathBuf> {
+    let walk_roots: Vec<PathBuf> = if scope.is_empty() {
+        vec![root_dir.to_path_buf()]
+    } else {
+        scope
+            .iter()
+            .map(|rel| crate::paths::repo_join(root_dir, rel))
+            .collect()
+    };
+    let mut admitted: Vec<PathBuf> = Vec::new();
+    for walk_root in walk_roots {
+        let files = WalkDir::new(walk_root)
+            .sort_by_file_name()
+            .into_iter()
+            .filter_entry(|e| !is_walk_skipped_dir(e))
+            .filter_map(Result::ok)
+            .filter(|e| e.file_type().is_file());
+        for entry in files {
+            let path = entry.into_path();
+            if is_candidate_file(&path, root_dir, included_set, ctx) {
+                admitted.push(path);
+            }
+            // Counted AFTER admission: capping raw entries meant a repository
+            // whose first N walked files are ignored (a vendored tree, a build
+            // directory) produced a nearly empty universe while the useful files
+            // sat just past the cut.
+            if admitted.len() >= GRAPH_FILTERING.fallback_max_files {
+                return admitted;
+            }
+        }
+    }
+    admitted
+}
+
+fn filter_ignored_and_secret_walked(root_dir: &Path, files: Vec<PathBuf>) -> Vec<PathBuf> {
+    let rel_paths: Vec<String> = files
+        .iter()
+        .filter_map(|f| crate::pipeline::rel_path_string(root_dir, f))
+        .collect();
+    let ignored: FxHashMap<String, git::IgnoreSource> =
+        git::find_ignored_paths_any(root_dir, &rel_paths)
+            .into_iter()
+            .map(|p| (p, git::IgnoreSource::Gitignore))
+            .collect();
+    files
+        .into_par_iter()
+        .filter(|f| !crate::pipeline::is_withheld(root_dir, f, &ignored))
+        .collect()
+}
+
+/// Discovery's candidate universe otherwise skips straight from a language
+/// check to the graph: an unchanged file a changed file imports would render
+/// as neighbour context even when `.diffctx/ignore` explicitly excludes it,
+/// or when it is secret-like (`id_rsa`, `*.pem`, ...) — `changed_files` is
+/// filtered this way already (`pipeline::compute_scored_state`), the
+/// discovery universe was not. One batched `git check-ignore` call covers
+/// every survivor of the language filter, so cost stays O(1) subprocess
+/// invocations regardless of repo size, and the final filter still runs in
+/// parallel via rayon.
+fn filter_ignored_and_secret(root_dir: &Path, files: Vec<PathBuf>) -> Vec<PathBuf> {
+    let rel_paths: Vec<String> = files
+        .iter()
+        .filter_map(|f| crate::pipeline::rel_path_string(root_dir, f))
+        .collect();
+    let ignored_rel_paths = git::find_ignored_paths_with_source(root_dir, &rel_paths);
+    files
+        .into_par_iter()
+        .filter(|f| !crate::pipeline::is_withheld(root_dir, f, &ignored_rel_paths))
+        .collect()
+}
+
+pub fn normalize_path(path: &Path, root_dir: &Path) -> PathBuf {
+    if path.is_absolute() {
+        dunce::canonicalize(path).unwrap_or_else(|_| path.to_path_buf())
+    } else {
+        let joined = crate::paths::repo_join(root_dir, &path.to_string_lossy());
+        dunce::canonicalize(&joined).unwrap_or(joined)
+    }
+}