diffctx 1.12.2 → 1.12.3

package/README.md

@@ -27,6 +27,9 @@ changed lines and stops once more context stops paying for itself.
 | Python API | ✗ | ✗ | ✗ | ✓ |
 | MCP server | ✗ | ✗ | ✗ | ✓ |
 
+Fuller positioning — measured results, and when a whole-repo packer or a
+persistent code-graph server fits better: [COMPARISON.md](COMPARISON.md).
+
 ## Install
 
 ```bash
@@ -44,6 +47,13 @@ npx diffctx . --diff HEAD~1             # npm wrapper over the native binary
 docker run --rm -v "$PWD:/repo" ghcr.io/nikolay-e/diffctx . --diff HEAD~1
 ```
 
+On Windows, via Scoop (this repository is the bucket):
+
+```powershell
+scoop bucket add diffctx https://github.com/nikolay-e/diffctx
+scoop install diffctx/diffctx
+```
+
 The image runs as a non-root user (uid 10001) and writes to stdout — the
 native binary has no `-o` flag, so redirect to capture: `... --diff HEAD~1 >
 context.yaml`.
@@ -80,11 +90,12 @@ the `--budget` token cap is hit.
 | 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) |
+| `--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) |
 | `--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 |
+| `--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 |
 
 Calibration of `--alpha`, `--tau`, and the edge-weight priors:
 [`docs/engineering/parameter-strategy.md`](docs/engineering/parameter-strategy.md).
@@ -108,19 +119,20 @@ diffctx graph . --level file -f graphml -o g.xml # file-level graph as GraphML
 <!-- 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
+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
+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
+diffctx . --diff HEAD~1 --with-raw-diff   # raw patch + selected context
 ```
 <!-- END USAGE -->
 
@@ -131,6 +143,11 @@ Every run reports token count and size on stderr — `12,847 tokens
 `<binary file: N bytes>`, `<file too large: N bytes>`, or
 `<unreadable content: not utf-8>`.
 
+Counts come from tiktoken's `o200k_base` encoder and are exact only for the
+GPT-4o family; Claude, Gemini and others tokenize differently, so treat
+`--budget` as an upper bound in o200k tokens and leave headroom. Details:
+[`docs/product/token-budget.md`](docs/product/token-budget.md).
+
 ## Python API
 
 ```python
@@ -146,6 +163,7 @@ ctx = build_diff_context(
     full=False,
     scoring_mode="ego",
     timeout=300,
+    with_raw_diff=False,      # True also embeds the raw unified diff (not charged to budget)
 )
 print(to_markdown(ctx))
 
@@ -186,6 +204,12 @@ 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).
 
+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
+come back as a related-context fragment either (including under `--full`). The
+same guarantee covers secret-like paths (`id_rsa`, `*.pem`, `*.key`, ...),
+which are filtered even without an ignore entry.
+
 ## Token cache
 
 Diff mode caches per-blob tokenization under
@@ -235,6 +259,12 @@ Apache 2.0
 
 - [Documentation site](https://nikolay-e.github.io/diffctx/) — the pipeline
   end to end: diff → fragments → graph → relevance → selection
+- [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
 - [Changelog](CHANGELOG.md)
 - [Security policy](SECURITY.md) — threat model and vulnerability reporting
 - [Parameter strategy](docs/engineering/parameter-strategy.md) — how `--alpha`,

package/checksums.json

@@ -1,6 +1,6 @@
 {
-  "diffctx-1.12.2-aarch64-apple-darwin.tar.gz": "fa575452f5120305c7a6c2ce2abd9bc58b93a775fbe430c740f54c5646379295",
-  "diffctx-1.12.2-aarch64-unknown-linux-gnu.tar.gz": "c36b6a56241f96a410f291b5069001adf075fa0fbce152818d0ae8eab2af00cc",
-  "diffctx-1.12.2-x86_64-pc-windows-msvc.zip": "f2d063f64d9b4b23c28efa9b87e7d18aa57947e75c5fbe37eba99824e03eebfc",
-  "diffctx-1.12.2-x86_64-unknown-linux-gnu.tar.gz": "3faa5da74a60e3289a4f86110be397a80b4733ca3d0655e999c0bd53a679197b"
+  "diffctx-1.12.3-aarch64-apple-darwin.tar.gz": "d62da2cd29e08130dc82936080d0b5734dc91bf392b9d7beb7696d7869bbd56c",
+  "diffctx-1.12.3-aarch64-unknown-linux-gnu.tar.gz": "a064e1edf242ddd448d8ed12445dacdcc32c5084ee82c62d54854e3b6b15abca",
+  "diffctx-1.12.3-x86_64-pc-windows-msvc.zip": "daf1064d4a4983305812443f79cb9a3d350c53468a513a127a4d5f079a19489c",
+  "diffctx-1.12.3-x86_64-unknown-linux-gnu.tar.gz": "83019a9eb2fa8a49eaa7999f5f6f9d88c72a88719c6ab456135ef0ed38f6f7fa"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "diffctx",
   "mcpName": "io.github.nikolay-e/diffctx",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "Selects the minimum code an LLM needs to review a git diff",
   "keywords": [
     "git",