mergejudge-runner 0.2.1 → 0.4.0

package/README.md

@@ -63,7 +63,40 @@ mergejudge-runner run --concurrency 2 # capped by the concurrency registered wit
 - Network errors, 5xx and 429 back off exponentially with jitter; `Retry-After` is honoured.
 - `SIGINT`/`SIGTERM`: stop polling, give in-flight jobs 30 s to finish, then kill the engine and nack them ("runner shutting down") and exit. A second signal exits immediately.
 - The access token is rotated through `/token/rotate` when it has < 14 days left (or when a response carries an `x-mergejudge-rotate` header). The new token is written to the config file (atomic rename) **before** it is used.
-- Modes: `diff` and `context`. **`deep` is not supported** in this MVP: such a job is nacked with a clear reason (the runner advertises only `diff` and `context`, so the server should not lease it).
+- Modes: `diff`, `context` and `deep`. **Deep on a runner is a single pass**: the Worker builds a temporary index of the repo (nothing stored, no Cloud AI), looks up callers, importers and imports of the changed code, and sends them as context with the job. The engine still runs with no tools and no checkout, so it cannot browse further. If the repo is too big to index, the review falls back to `context` and says so. Runners older than 0.3.0 do not advertise `deep`, so they are never offered such jobs; upgrade and restart to receive them. With `runner.code_source: local` the runner reads its own clone instead; see below.
+
+## Local code (deep mode without code leaving your machine) — runner 0.4.0
+
+By default (`runner.code_source: worker`) the Worker reads the repo through the GitHub API and sends the diff and context with the job. With `code_source: local` in the repo's `.mergejudge.yml` (read from the base commit):
+
+```yaml
+review:
+  mode: deep
+runner:
+  code_source: local
+```
+
+the job carries only the repo, PR number, base/head SHAs, the config and the rules result. **No diff, no context, no file contents, no token.** The runner reads the code itself:
+
+1. keeps a persistent **partial bare clone** per repo, `~/.mergejudge/repos/<owner>__<repo>.git` (`git clone --bare --filter=blob:none`), and fetches the job's base and head SHAs;
+2. computes the PR diff locally (`git diff base...head`, renames detected, `diff_exclude` respected);
+3. builds an index of the base commit (symbols, import graph, code chunks) over `git ls-tree` / `git cat-file`, saved at `~/.mergejudge/idx/<owner>__<repo>/<sha>.json`. The next job on the repo updates it incrementally from the git diff between the saved commit and the new base; the PR's own changes are overlaid in memory. There is no 300-file cap (up to 20,000 files, 200 MB read, 15 min);
+4. retrieves callers, importers and imports of the changed code, reviews in one pass with your engine, and sends back only the structured result (verdict, findings, comments).
+
+**Git access.** The runner uses the machine's own git credentials, nothing from MergeJudge. Make sure `git clone https://github.com/<owner>/<repo>.git` works for the user that runs the runner (`gh auth setup-git`, a credential helper, or a deploy key). For SSH or a mirror, set a remote URL template with `{owner}` and `{repo}`:
+
+```sh
+MERGEJUDGE_REMOTE_URL_TEMPLATE='git@github.com:{owner}/{repo}.git' mergejudge-runner run
+mergejudge-runner run --remote-url-template 'https://git.example.com/{owner}/{repo}.git'
+```
+
+(precedence: flag, environment, `localCode.remoteUrlTemplate` in the config file, default `https://github.com/{owner}/{repo}.git`). If git cannot read the repo, the job **fails with an explicit message** ("cannot read owner/repo with this runner's own git access ...", shown on the PR); it never silently falls back to a diff-only review. Private-repo credentials are never logged; URLs in errors are scrubbed.
+
+**Cache.** `MERGEJUDGE_HOME` moves everything (default `~/.mergejudge`). After each job the runner keeps the newest **3** index snapshots per repo, evicts repos untouched for **30 days**, and, when `repos/` + `idx/` exceed **5 GB**, evicts the least recently used repos. Tune with `MERGEJUDGE_CACHE_MAX_GB`, `MERGEJUDGE_CACHE_KEEP_SNAPSHOTS`, `MERGEJUDGE_CACHE_MAX_AGE_DAYS`, `--cache-max-gb`, or `localCode` in the config file. An evicted repo is simply cloned and indexed again on its next job. Jobs on the same repo run one after another (lock); different repos run in parallel.
+
+**Compatibility.** The runner announces `features: ["local-code"]` at start and on every heartbeat. The Worker only sends the SHAs-only payload to a runner that announced it and was seen in the last 10 minutes; otherwise (older runner, none online) it uses the 0.3.0 path (the Worker builds the context). A 0.4.0 runner still handles those old-style jobs. The panel and `.mergejudge.yml` stay unchanged for repos that do not set `code_source: local`.
+
+The repo's contents stay on your disk: both the clone and the snapshots (which contain code chunks) live under `MERGEJUDGE_HOME`. The Worker also skips building its own R2/Vectorize index for such repos.
 
 ## Status