squeze-cli 2.2.1 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.0.1 — 2026-11-15
4
+
5
+ ### Changed
6
+ - The README opens as a landing page: install and quick start, measured results with confidence intervals (including the failed non-inferiority test), a good-fit note and a not-measured note. The evidence sections are unchanged.
7
+ - npm metadata: keywords expanded, `mcpName` set to `io.github.2002-rokkam/squeze` for the MCP Registry, and `server.json` added. No code changes.
8
+
9
+ ## 3.0.0 — 2026-11-14
10
+
11
+ ### Evidence
12
+ - Public corpus (9 pinned repositories, 40 cases each, seed 1729, budget 3,000 tokens): squeze recall 96.9% [95.0, 98.6] against grep 95.6% [93.3, 97.5]. The non-inferiority test at a 2.0-point margin **failed**: squeze loses 3.1 points [1.4, 5.0]. Express (12.5% loss), bat (7.5%) and flask, gin and django (2.5% each) account for the losses. The McNemar test is not significant (p = 0.42). Input tokens fall 87.3% against grep. Raw output: `bench/proof/results/public.md`.
13
+ - One private repository, aggregate numbers only: squeze recall 100% against grep 95%, non-inferiority passed, input tokens fall 86.2%.
14
+ - Per-call overhead of the MCP tool list (`npm run measure:overhead`): `--tools core` is 548 tokens for 4 tools, `--tools all` is 765 tokens for 6 tools.
15
+
16
+ ### Added
17
+ - VS Code **Code Explorer** (`Squeze: Open Code Explorer`): a searchable, interactive map of the code graph with subsystems, hubs and links. It renders under a per-render nonce CSP that blocks network requests, and shows at most 600 nodes by default (2,000 maximum). Incomplete graphs are labelled "partial graph".
18
+ - `Squeze: Refresh Index` and the `squeze.autoRefresh` setting (on by default). The index follows file changes through a debounced, single-flight refresh.
19
+ - `Squeze: Show Token Savings`: a local ledger of input tokens avoided by each pack, estimated as the whole-repository input minus the pack output. It records pack calls only and is not billing data.
20
+ - Browser UI tests (`npm run test:ui`, Playwright at 1440, 768 and 360 px).
21
+ - Proof harness `bench/proof/`: `npm run bench:proof` runs the public corpus; `local <path>` runs a private repository and writes aggregate output only.
22
+
23
+ ### Changed
24
+ - `Squeze: Show Code Graph` opens the Code Explorer. The HTML export (`squeze graph --html`) keeps its output: the layout code moved to a shared module, and output is byte-identical before and after on express, gin and requests.
25
+ - Index reuse also checks change time and inode, so a same-size edit whose modification time was restored is re-read. Files whose newest timestamp is within two seconds of the scan are always re-read (`RACY_WINDOW_MS`). Cache format version is 2; older caches are discarded once.
26
+
27
+ ### Fixed
28
+ - A nested `.gitignore` that re-includes a file is honoured, and a directory excluded by a parent cannot be re-included. Checked against `git ls-files`.
29
+ - The MCP server reported version `2.2.0` while the package was 2.2.1.
30
+ - A file changed between indexing and text load no longer fails the whole `context` call; the pack is rebuilt (bounded to three attempts).
31
+ - Test scratch repositories and caches live in the OS temp directory, not under the repository root.
32
+
3
33
  ## 2.2.1
4
34
 
5
35
  Evidence for every item is in the README, section "Evidence".
package/README.md CHANGED
@@ -1,15 +1,41 @@
1
1
  # Squeze
2
2
 
3
- **Local, deterministic, token-budgeted repository context for coding agents.**
4
- Give it a task, an error or a stack trace; it returns the few verbatim, line-cited source excerpts that matter, inside a token budget you choose. It runs as a CLI, an MCP server and a VS Code / GitHub Copilot tool. No model calls, no network, no telemetry.
3
+ **Give your coding agent the right code, not the whole repository.**
5
4
 
6
- [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![node](https://img.shields.io/badge/node-%E2%89%A520.19-green) ![version](https://img.shields.io/badge/version-2.2.1-informational)
5
+ Squeze is a local, deterministic context engine for coding agents. Give it a task, an error or a stack trace; it returns the few verbatim, line-cited source excerpts that matter, inside a token budget you choose. It runs as a CLI, an MCP server for any MCP-capable agent, and a VS Code / GitHub Copilot extension. No model calls, no network, no telemetry.
7
6
 
8
- > **Status of the evidence.** Every number in this document comes from a script in this repository and a raw result file you can inspect. Section [Evidence](#evidence) lists what was measured, how, the confidence intervals and what was **not** proven. Nothing here claims 100% accuracy, answer quality or billing savings.
7
+ [![npm](https://img.shields.io/npm/v/squeze-cli)](https://www.npmjs.com/package/squeze-cli) [![downloads](https://img.shields.io/npm/dm/squeze-cli)](https://www.npmjs.com/package/squeze-cli) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) ![node](https://img.shields.io/badge/node-%E2%89%A520.19-green)
8
+
9
+ ## Quick start
10
+
11
+ ```sh
12
+ npm install -g squeze-cli
13
+ squeze context --root . --query "where is retry backoff computed?" --budget 3000
14
+ squeze map --root .
15
+ ```
16
+
17
+ Then connect it to your agent: [MCP setup](#mcp) or the [VS Code extension](#vs-code).
18
+
19
+ ## Results at a glance
20
+
21
+ Public proof on 9 pinned open-source repositories, 360 symbol-lookup cases. Method, losses and confidence intervals are in [Evidence](#evidence).
22
+
23
+ | Metric | Result |
24
+ | --- | --- |
25
+ | Input tokens vs. a grep-and-read baseline | 87.3% fewer [84.8%, 89.2%] |
26
+ | Input tokens vs. reading the whole repository | 99.8% fewer |
27
+ | Recall (finds the defining file): squeze / grep / whole repository | 96.9% / 95.6% / 100% (ceiling) |
28
+ | Squeze vs. grep recall | not significantly different (McNemar p = 0.42) |
29
+ | Squeze vs. whole-repository recall | 3.1-point loss; the non-inferiority test at a 2-point margin **failed** |
30
+
31
+ **Good fit:** large repositories where an agent would otherwise read thousands of irrelevant lines, and repeated queries in the same session.
32
+ **Not measured:** output tokens, model answer quality and billing. No model is called in these tests.
33
+
34
+ > **Status of the evidence.** Every public number in this document comes from a script in this repository and a raw result file you can inspect. The one private-repository result in section 0 of [Evidence](#evidence) is aggregate only and cannot be reproduced from this repository. For 3.0, the public non-inferiority test against whole-repository reading **failed**; section 0 gives the numbers. Section [Evidence](#evidence) lists what was measured, how, the confidence intervals and what was **not** proven. Nothing here claims 100% accuracy, answer quality or billing savings.
9
35
 
10
36
  ## Contents
11
37
 
12
- 1. [Why](#why) · 2. [Install](#install) · 3. [Use](#use) · 4. [How it works](#how-it-works) · 5. [What is new in 2.2](#what-is-new-in-22) · 6. [Evidence](#evidence) · 7. [Configuration](#configuration) · 8. [Security model](#security-model) · 9. [Limitations](#limitations) · 10. [Reproduce](#reproduce) · 11. [Repository map](#repository-map)
38
+ 1. [Why](#why) · 2. [Install](#install) · 3. [Use](#use) · 4. [How it works](#how-it-works) · 5. [What is new in 3.0](#what-is-new-in-30) · 6. [What is new in 2.2](#what-is-new-in-22) · 7. [Evidence](#evidence) · 8. [Configuration](#configuration) · 9. [Security model](#security-model) · 10. [Limitations](#limitations) · 11. [Reproduce](#reproduce) · 12. [Repository map](#repository-map)
13
39
 
14
40
  ## Why
15
41
 
@@ -25,10 +51,12 @@ An agent that reads whole files to answer "where is retry backoff computed?" pay
25
51
  Requires Node.js 20.19 or newer.
26
52
 
27
53
  ```sh
28
- npm install -g squeze-cli # installs the `squeze` command
29
- npx squeze-cli --help # or run without installing
54
+ npm install -g squeze-cli # installs the `squeze` command
55
+ npx -y squeze-cli --help # or run without installing
30
56
  ```
31
57
 
58
+ > Note: `npm install -g squeze-cli` installs the release tagged `latest` on npm. To pin a version, use `squeze-cli@3.0.0` (or an earlier version such as `squeze-cli@2.2.1`).
59
+
32
60
  From source:
33
61
 
34
62
  ```sh
@@ -43,12 +71,14 @@ The older `reposqueeze-v2` command name still works as an alias. Tool names chan
43
71
  ### VS Code
44
72
 
45
73
  ```sh
46
- npm run package # writes releases/squeze-cli-2.2.1.vsix
47
- code --install-extension releases/squeze-cli-2.2.1.vsix
74
+ npm run package # writes releases/squeze-cli-3.0.1.vsix
75
+ code --install-extension releases/squeze-cli-3.0.1.vsix
48
76
  ```
49
77
 
50
78
  Enable **Squeze Context**, **Expand** and **Map** in Copilot's tool picker, or write `#squeze` in a prompt. Run **Squeze: Install Copilot Instructions** once per repository for retrieval-first guidance.
51
79
 
80
+ The extension also provides **Squeze: Open Code Explorer** (an interactive map of the code graph), **Squeze: Refresh Index** and **Squeze: Show Token Savings**. The index refreshes after file changes when `squeze.autoRefresh` is on (the default). Above 5,000 files the default index parses a candidate subset, so the graph is marked partial; timings are in [docs/SCALE_EVALUATION.md](docs/SCALE_EVALUATION.md#incremental-refresh-on-a-real-repository).
81
+
52
82
  ### MCP
53
83
 
54
84
  ```json
@@ -117,13 +147,30 @@ flowchart LR
117
147
  K --> O[Verbatim cited excerpts]
118
148
  ```
119
149
 
120
- 1. **Index.** Files are enumerated through Git (or a bounded walk), filtered (ignored, binary, oversized, symlinks, secret paths), redacted, chunked and written to a cache directory *outside* the repository (`$XDG_CACHE_HOME/reposqueeze`, `~/Library/Caches/reposqueeze`, or `REPOSQUEEZE_CACHE_DIR`). Unchanged files are not re-parsed. Above 5,000 files a file-level sketch selects candidates before parsing.
150
+ 1. **Index.** Files are enumerated through Git (or a bounded walk), filtered (ignored, binary, oversized, symlinks, secret paths), redacted, chunked and written to a cache directory *outside* the repository (`%LOCALAPPDATA%\reposqueeze` on Windows, `~/Library/Caches/reposqueeze` on macOS, `$XDG_CACHE_HOME/reposqueeze` or `~/.cache/reposqueeze` elsewhere; override with `REPOSQUEEZE_CACHE_DIR`). Each repository gets its own subfolder. Unchanged files are not re-parsed. Above 5,000 files a file-level sketch selects candidates before parsing.
121
151
  2. **Perturbation-consensus retrieval (PCR).** The request is ranked as up to six deterministic views (original, diagnostic lines, identifiers, three leave-one-bucket-out views). Reciprocal-rank fusion rewards evidence that survives wording removal; rare query terms become *evidence obligations* that are reported when missing.
122
152
  3. **Signals.** Pseudo-relevance feedback terms, identifier-name and adjacent-word matches, and a mild prior against tests, docs and vendored code unless the query asks for them. Optional (opt-in): stack-frame localisation and Git history signals.
123
153
  4. **Packing.** Greedy selection by marginal value per token: whole definitions when they fit, otherwise the query-densest window with the declaration line kept, identical copies collapsed, leftover budget spent on one-line pointers.
124
154
 
125
155
  Details and rationale: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). A source-verified survey of the techniques considered (about 95 sources, each marked verified or unverified): [docs/V3_RESEARCH.md](docs/V3_RESEARCH.md).
126
156
 
157
+ ## What is new in 3.0
158
+
159
+ 3.0 adds a VS Code Code Explorer, background index refresh, a token-savings ledger, fixes, and a proof harness. The public proof is mixed: the non-inferiority test failed (section 0 of [Evidence](#evidence)).
160
+
161
+ | Area | Change |
162
+ | --- | --- |
163
+ | Code Explorer | `Squeze: Open Code Explorer`: a searchable, interactive map of the code graph with subsystems, hubs and links. Renders under a per-render nonce CSP with no network requests. Draws the top 600 files by rank by default (2,000 maximum) with at most 6,000 edges; when files are left out the summary reads "showing top N files", and graphs built from a candidate subset are labelled "PARTIAL graph" |
164
+ | Index freshness | `squeze.autoRefresh` (on by default) and `Squeze: Refresh Index`. File changes are picked up through a debounced, single-flight refresh |
165
+ | Token savings | `Squeze: Show Token Savings`: a local ledger of input tokens avoided by each pack call (whole-repository input minus pack output). It is an estimate from pack calls only, not billing data |
166
+ | Reuse safety | Index reuse also checks change time and inode. Files whose newest timestamp is within 2 s of the scan are always re-read. Cache format 2: older caches are discarded once |
167
+ | Graph command | `Squeze: Show Code Graph` now opens the Code Explorer. The `squeze graph --html` export is unchanged (byte-identical on express, gin and requests) |
168
+ | Fixes | A nested `.gitignore` that re-includes a file is honoured (checked against `git ls-files`); the MCP server reported 2.2.0 while the package was 2.2.1; a file changed between indexing and loading no longer fails `context` (the pack is rebuilt, at most three attempts); test scratch repositories moved out of the repository root |
169
+ | Tests | `npm test` (678 tests); `npm run test:ui` (9 browser tests of the Explorer at 1440, 768 and 360 px; run `npx playwright install chromium` first); `npm run test:editor` (VS Code extension host; set `VSCODE_EXECUTABLE_PATH` to a VS Code binary) |
170
+ | Proof | `npm run bench:proof` (public corpus at pinned commits; needs network); `node --import tsx bench/proof/run.ts local <path>` (private repository; aggregate output only) |
171
+
172
+ Behaviour changes to know about: `Squeze: Show Code Graph` opens the Explorer, and the cache format moved to version 2 (older caches are discarded once).
173
+
127
174
  ## What is new in 2.2
128
175
 
129
176
  | Area | Change |
@@ -140,9 +187,30 @@ Details and rationale: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). A source-ve
140
187
  | MCP | Four tools by default (context, expand, map, graph); smaller schemas |
141
188
  | Bug fix | Python files no longer get a spurious whole-file chunk named after their first line |
142
189
 
190
+ ## Standard and status
191
+
192
+ The bar for the code graph and the caveman output style, with each target marked met or not met, is in [docs/STANDARD.md](docs/STANDARD.md). Squeze is not yet better than Graphify on every measure. It has call edges, but on gin they agree with Graphify's calls at 67% precision and 52% recall (the proxies in the standard; target not met). The only head-to-head run covers calls on one repository. Dependents, path queries and token counts against Graphify have not been compared, and the graph covers only source files in the 19 languages in [src/langs.ts](src/langs.ts), so docs and config files are not in it.
193
+
143
194
  ## Evidence
144
195
 
145
- All results below are retrieval metrics under a fixed token budget, not model answer quality. "Baseline" is the unmodified upstream 2.1.0.
196
+ All results below are retrieval metrics under a fixed token budget, not model answer quality. In sections 1 to 4, "baseline" is the unmodified upstream 2.1.0.
197
+
198
+ ### 0. Retrieval against grep and whole-repository reading (3.0)
199
+
200
+ Symbol lookups on 9 pinned public repositories (up to 40 cases each, 360 in total) and one private repository (40 cases; aggregate numbers only). Budget 3,000 tokens, `o200k_base`, seed 1729. Grep arm: `\bNAME\b` across the repository, files ranked by match count, 200 listing lines, up to 8 whole files read. Squeze arm: one `context` pack with no follow-up `expand`, which is conservative for squeze. Raw output: [bench/proof/results/public.md](bench/proof/results/public.md) (public) and [bench/proof/results/private-A.md](bench/proof/results/private-A.md) (private; aggregate only, the repository is not named and cannot be re-run from this repository).
201
+
202
+ | Metric | Public (9 repos, n = 360) | Private (1 repo, n = 40) |
203
+ | --- | ---: | ---: |
204
+ | Recall, squeze | 96.9% [95.0, 98.6] | 100% |
205
+ | Recall, grep | 95.6% [93.3, 97.5] | 95.0% [87.5, 100] |
206
+ | Recall loss vs whole-repository reading (100%); non-inferiority margin 2.0 points | 3.1 points [1.4, 5.0]: **fails** | 0.0 points: passes |
207
+ | Input tokens vs grep | 87.3% fewer [84.8, 89.2] | 86.2% fewer [79.8, 90.4] |
208
+ | Cases only squeze gets right / only grep gets right (McNemar) | 15 / 10, p = 0.42 | 2 / 0, p = 0.5 |
209
+ | Pack latency p50 / p90 (warm) | 1,443 / 4,462 ms | 923 / 1,973 ms |
210
+
211
+ Per repository, five of nine fail the margin on their own: express (12.5-point loss), bat (7.5), and flask, gin and django (2.5 each). requests, ripgrep, gson and preact have no loss. Squeze is cheaper than grep in 280 of 360 public cases.
212
+
213
+ What this shows: on symbol lookups, squeze's recall is not significantly different from grep's, and it uses about 87% fewer input tokens. What it does not show: on the public corpus squeze does not meet the non-inferiority margin against whole-repository reading. The 2.0-point margin was not changed after the run. The private result passes, but it cannot be reproduced here and is not a substitute for the public result. These are symbol lookups; no model wrote an answer, so answer quality is not measured.
146
214
 
147
215
  ### 1. Real GitHub issues: SWE-bench (60 development instances)
148
216
 
@@ -189,12 +257,15 @@ Reading the table honestly: a Squeze pack costs about **4% of what the whole-fil
189
257
 
190
258
  `npm run measure:overhead`
191
259
 
192
- | Item | 2.1.0 | 2.2 |
260
+ | Item | 2.1.0 | 3.0 |
193
261
  | --- | ---: | ---: |
194
- | MCP tool list (default tools) | 731 tokens (5 tools) | 368 tokens (3 tools) |
195
- | Pack header | 125 tokens | 40 tokens |
262
+ | MCP tool list, default `--tools core` | 731 tokens (5 tools; earlier measurement, not re-run) | 548 tokens (4 tools) |
263
+ | MCP tool list, `--tools all` | not measured | 765 tokens (6 tools) |
264
+ | Pack header | 125 tokens | 41 tokens |
196
265
  | Framing per excerpt | 24 tokens | 15 tokens |
197
- | Closing note | 28 tokens | 0 tokens |
266
+ | Closing note | 26 tokens | 0 tokens |
267
+
268
+ The 3.0 column was measured with `npm run measure:overhead` on 3.0.0. The 2.1.0 pack-header, framing and closing-note values are the script's own baseline; the 2.1.0 tool-list figure is from an earlier run.
198
269
 
199
270
  ### 4. Repository map
200
271
 
@@ -234,7 +305,11 @@ Structural chunkers on real repositories: Markdown 807 files / 98.6% of non-blan
234
305
 
235
306
  ### 9. Code graph (structural questions)
236
307
 
237
- `squeze graph` answers "what depends on X?", "how does A reach B?" and "what are the subsystems?" from a dependency graph. On 6 repositories (express, flask, gin, gson, ripgrep, thor; about 20 questions each) the graph answer is **94.8–99.3% smaller than reading the files that contain the identifier**, with medians of 60 tokens (path), 111 (neighbours), 264 (impact) and 860 (overview). Against a bare `grep` match listing the saving is small or negative (impact 4%, overview −12%), and importer precision of impact queries averages 59% (recall 86%) because name-based references over-report. All 300 sampled import edges (50 per repository) were verified to exist. Details, limits and real output: [benchmarks/v22/graph.md](benchmarks/v22/graph.md), [docs/GRAPH.md](docs/GRAPH.md).
308
+ `squeze graph` answers "what depends on X?", "how does A reach B?" and "what are the subsystems?" from a dependency graph. On 6 repositories (express, flask, gin, gson, ripgrep, thor; about 20 questions each) the graph answer is **94.8–99.3% smaller than reading the files that contain the identifier**, with medians of 60 tokens (path), 111 (neighbours), 264 (impact) and 860 (overview).
309
+
310
+ Importer accuracy of `--impact` (8 files per repository, checked against a grep ground truth): **precision 75%, recall 79%** on average. Per repository: flask 100% / 87%, gson 100% / 100%, thor 100% / 100%, express 88% / 60%, ripgrep 39% / 71%, gin 25% / 58%. The low values are real: Go imports are resolved to one file rather than to the whole package, so gin and ripgrep over-report importers. An earlier version of this section said 59%; that came from a broken Go ground truth in the eval, now fixed.
311
+
312
+ Against a plain grep listing the saving is small (impact 4%) and negative for overview (−12%). All 300 sampled import edges (50 per repository) exist and are spelled as the source says. The graph has `calls` edges (a `name(` site that resolves to a definition in the same file, in an imported file, or to a name defined once in the repository; marked `EXTRACTED` or `INFERRED`) but no Go package-level edges yet; see "What is not proven". Details and real output: [benchmarks/v22/graph.md](benchmarks/v22/graph.md), [docs/GRAPH.md](docs/GRAPH.md).
238
313
 
239
314
  ### 10. Speed and memory
240
315
 
@@ -251,7 +326,7 @@ The 2.1.0 profile on the 921-file repo: tokenizing the whole repository only to
251
326
 
252
327
  ### 11. Tests and robustness
253
328
 
254
- `npm test` runs 532 tests (unit, property, adversarial, MCP protocol, cache corruption and concurrency, read-only checkout). On the final tree 530 passed on the first run and the 2 that failed were wall-clock limits exceeded while the shared machine's load average was above 60 (a 60 s MCP request timeout and a 1 s bound on 2 MiB of adversarial text); both pass when re-run (11 s and 1.6 s).
329
+ `npm test` runs 678 tests (unit, property, adversarial, MCP protocol, cache corruption and concurrency, read-only checkout). All 678 pass on the 3.0.1 tree. Two tests have wall-clock limits (a 60 s MCP request timeout and a 1 s bound on 2 MiB of adversarial text) and can fail under heavy machine load, so re-run before treating a failure as a regression.
255
330
 
256
331
  A many-repository robustness and adversarial suite is in [bench/robustness](bench/robustness). Only a partial run was completed on the final build: 2 repositories (gin, requests), 32 commands, 0 crashes, 0 timeouts, 0 budget violations, 0 secret-regex hits in outputs ([report](benchmarks/v3/robustness-final.md)). That run flagged 4 of 8 repeat comparisons as non-identical while the machine load was about 50; serial re-runs of `map` on the same checkout were byte-identical 3 of 3 times and `context` cold and warm were identical on a second checkout, so the cause was not identified. The adversarial section did not finish and is **not** claimed.
257
332
 
@@ -262,6 +337,9 @@ A many-repository robustness and adversarial suite is in [bench/robustness](benc
262
337
  - Each new ranking feature (feedback terms, phrase matching, priors, windows, pointers, tokenizer v2) is **on by default** on the strength of the aggregate results above; a one-feature-at-a-time ablation has not been published. Switch any of them off with `RSQ_FEATURES` and report regressions.
263
338
  - Stack-frame localisation (`+frames`) and Git-history signals (`+git`) are implemented and unit-tested, use proposed boost constants, and are **off by default** until validated.
264
339
  - Timings were taken on a loaded machine.
340
+ - 3.0 public proof: the non-inferiority test against whole-repository reading **failed** (loss 3.1 points, CI [1.4, 5.0], margin 2.0). The proof covers symbol lookups only, not whole questions or model answers.
341
+ - The private-repository result (section 0) is aggregate only and cannot be reproduced from this repository.
342
+ - The code graph's call edges are name-based, without type resolution, and it resolves Go imports to a single file, so its impact answers are weak for gin and ripgrep (precision 25% and 39%).
265
343
  - The multi-repository robustness run is partial (2 repositories) and the byte-for-byte determinism flag raised during it is unexplained (see section 11).
266
344
 
267
345
  ## Configuration
@@ -271,11 +349,12 @@ A many-repository robustness and adversarial suite is in [bench/robustness](benc
271
349
  | `--budget N` / `squeze.tokenBudget` | Token budget, 256–32,000 (default 3,000) |
272
350
  | `RSQ_FEATURES` / `--features` / `squeze.features` | Comma list, e.g. `-prf,-priors`, `+frames,+git`, `none` (closest to 2.1.0 behaviour). Features: `compactfmt windows pointers priors prf phrase frames git redact condense` |
273
351
  | `RSQ_TOKENIZER=v1` | 2.1.0 tokenizer (for comparisons) |
274
- | `REPOSQUEEZE_CACHE_DIR` | Cache location (`repo` restores the old in-repo `.reposqueeze-v2/`) |
352
+ | `REPOSQUEEZE_CACHE_DIR` | Cache location: a directory (each repository gets a subfolder); `off`, `none` or `memory` keeps the index in memory only; `repo` restores the old in-repo `.reposqueeze-v2/` |
275
353
  | `REPOSQUEEZE_REFRESH_INDEX=1` | Force re-reading files in repositories above 5,000 files |
276
354
  | `REPOSQUEEZE_EXACT_STATS=1` | Exact (slow) input-token statistic instead of the sampled estimate |
277
355
  | `REPOSQUEEZE_MAX_CANDIDATES` | Candidates parsed in large-repository mode (100–5,000) |
278
356
  | `--semantic-model all-minilm` | Optional local Ollama embeddings of the 300 strongest lexical candidates; sent to `127.0.0.1:11434` only |
357
+ | `squeze.autoRefresh` (VS Code) | Index in the background when a trusted folder opens and refresh after file changes (on by default); off means indexing runs only when you use a Squeze command |
279
358
  | `.reposqueeze-v2ignore` | Extra ignore rules (gitignore syntax) |
280
359
 
281
360
  ## Security model
@@ -289,17 +368,23 @@ A many-repository robustness and adversarial suite is in [bench/robustness](benc
289
368
  ## Limitations
290
369
 
291
370
  - Retrieval is lexical and structural; a task whose words never appear near the relevant code can be missed. Read the "Also relevant" pointers, `expand`, and fall back to normal search when the pack says evidence is weak.
292
- - Above 5,000 files a file-level sketch chooses the candidates that get parsed. Timestamp-preserving edits need `REPOSQUEEZE_REFRESH_INDEX=1`.
371
+ - Above 5,000 files a file-level sketch chooses the candidates that get parsed. Index reuse trusts size, modification time, change time and inode. Change time cannot be set from user space, so a same-size edit is still caught when its modification time was restored. Files whose newest timestamp is within two seconds of the scan are always re-read, because a rewrite in the same timestamp tick can leave the stamps unchanged. Set `REPOSQUEEZE_REFRESH_INDEX=1` to force a full re-read.
293
372
  - Safety limits: 100,000 files, 2 GiB indexed text, 2 MiB per file, depth 60. Exceeding one is reported in the output.
294
373
  - Token counts use `o200k_base`; provider counts differ.
374
+ - Public non-inferiority failure: against whole-repository reading, squeze loses 3.1 points of symbol-lookup recall on the public corpus, outside the 2.0-point margin (section 0 of Evidence).
375
+ - Explorer: the top 600 files by rank are drawn by default (2,000 maximum); the summary then reads "showing top N files". Graphs built from a candidate subset are labelled "PARTIAL graph".
295
376
  - Windows: the CLI and extension are built for it, but some benchmark and chunker tests still assume `/` path separators, so the Windows CI job is informational.
296
377
 
297
378
  ## Reproduce
298
379
 
299
380
  ```sh
300
- npm ci && npm run check && npm test # type-check and the full test suite
381
+ npm ci && npm run check && npm test # type-check and the 678-test suite
301
382
  npm run measure:overhead # section 3
302
383
  npm run bench:fetch && npm run bench:devsuite # section 2 (runs the current checkout)
384
+ npx playwright install chromium && npm run test:ui # browser tests of the Explorer
385
+ VSCODE_EXECUTABLE_PATH=/path/to/VSCode npm run test:editor # VS Code extension-host tests
386
+ npm run bench:proof # section 0 (clones pinned public repositories; needs network)
387
+ node --import tsx bench/proof/run.ts local /path/to/repo # private repository; aggregate output only
303
388
  node --import tsx bench/run.ts --help # section 1: SWE-bench harness (dev split only)
304
389
  node --import tsx scripts/repomap-eval.ts --help # section 4
305
390
  node --import tsx scripts/logs-eval.ts # section 5
@@ -311,9 +396,10 @@ Earlier frozen evaluations of 2.0/2.1 (Agent Retrieval Bench `trace2code`, 50,00
311
396
 
312
397
  | Path | Contents |
313
398
  | --- | --- |
314
- | `src/` | `engine` (pipeline), `repository` + `store` + `search-index` (index), `parser` + `langs` + `chunkers` (chunking), `v2` (PCR ranking), `pack` (packing), `repomap` + `skeleton` + `symbols` (maps), `trace`, `gitsignals`, `redact`, `compact` + `logs/` (logs), `mcp`, `cli`, `extension` |
315
- | `tests/` | Unit, integration, MCP and adversarial tests |
316
- | `bench/`, `scripts/`, `benchmarks/` | Evaluation harnesses, scripts and raw results |
399
+ | `src/` | `engine` (pipeline), `repository` + `store` + `search-index` (index), `parser` + `langs` + `chunkers` (chunking), `v2` (PCR ranking), `pack` (packing), `repomap` + `skeleton` + `symbols` (maps), `trace`, `gitsignals`, `redact`, `compact` + `logs/` (logs), `mcp`, `cli`, `extension`; Explorer and index: `explorer-html`, `explorer-model`, `graph-algos`, `graph-html`, `graph-layout`, `graph-render`, `graph-store`, `index-pool`, `index-worker`, `live-refresh`, `status-text`, `token-ledger` |
400
+ | `tests/` | Unit, integration, MCP and adversarial tests; `tests/ui/` browser tests of the Explorer |
401
+ | `media/` | Explorer stylesheet and script, loaded under a nonce CSP |
402
+ | `bench/`, `scripts/`, `benchmarks/` | Evaluation harnesses, scripts and raw results; `bench/proof/` is the 3.0 proof harness (public corpus, and private repositories with aggregate output only) |
317
403
  | `docs/` | Architecture, research and evaluation reports |
318
404
 
319
405
  MIT licence. Third-party notices: [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).