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 +30 -0
- package/README.md +109 -23
- package/dist/cli.cjs +185 -62
- package/dist/extension.cjs +825 -113
- package/docs/ARCHITECTURE.md +1 -1
- package/docs/GRAPH.md +1 -1
- package/docs/SCALE_EVALUATION.md +19 -1
- package/docs/STANDARD.md +27 -0
- package/media/explorer.css +317 -0
- package/media/explorer.js +869 -0
- package/package.json +33 -4
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
7
|
+
[](https://www.npmjs.com/package/squeze-cli) [](https://www.npmjs.com/package/squeze-cli) [](LICENSE) 
|
|
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) ·
|
|
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
|
|
29
|
-
npx squeze-cli --help
|
|
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-
|
|
47
|
-
code --install-extension releases/squeze-cli-
|
|
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 (
|
|
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. "
|
|
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 |
|
|
260
|
+
| Item | 2.1.0 | 3.0 |
|
|
193
261
|
| --- | ---: | ---: |
|
|
194
|
-
| MCP tool list
|
|
195
|
-
|
|
|
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 |
|
|
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).
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
| `
|
|
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).
|