fix(impact): harden agent output budgets

This commit is contained in:
Gergo Magyar 2026-10-31 20:00:27 +00:00
commit caccbb26df
119 changed files with 5124 additions and 566 deletions

View file

@ -87,6 +87,7 @@ Generates repository documentation from the knowledge graph using an LLM. HTTP p
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
| `--timeout <seconds>` | LLM request timeout in seconds (default: disabled) |
| `--retries <n>` | Max LLM retry attempts per request (default: 3) |
| `--max-completion-tokens <n>` | Max completion tokens per LLM request (default: 16384). `GITNEXUS_MAX_COMPLETION_TOKENS` overrides `maxCompletionTokens` in `~/.gitnexus/config.json`; the flag overrides both. |
| `--lang <lang>` | Output language for generated documentation (e.g. english, chinese, spanish, japanese) |
| `--gist` | Publish wiki as a public GitHub Gist |

View file

@ -0,0 +1,53 @@
name: Download test artifact
description: Download a required artifact from this run with bounded transport retries
inputs:
name:
description: Exact artifact name to download from this workflow run
required: true
path:
description: Destination directory
required: true
runs:
using: composite
steps:
# Restart the whole action after its internal retries are exhausted, so
# each attempt obtains a fresh download URL for the same required artifact.
- name: Download
id: first
continue-on-error: true
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
with:
name: ${{ inputs.name }}
path: ${{ inputs.path }}
digest-mismatch: error
- name: Wait before retry
if: ${{ !cancelled() && steps.first.outcome == 'failure' }}
shell: bash
run: sleep 10
- name: Retry download
id: second
if: ${{ !cancelled() && steps.first.outcome == 'failure' }}
continue-on-error: true
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
with:
name: ${{ inputs.name }}
path: ${{ inputs.path }}
digest-mismatch: error
- name: Wait before final attempt
if: ${{ !cancelled() && steps.second.outcome == 'failure' }}
shell: bash
run: sleep 30
# Keep the final failure fatal: shards must never run without the snapshot.
- name: Final download attempt
if: ${{ !cancelled() && steps.second.outcome == 'failure' }}
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
with:
name: ${{ inputs.name }}
path: ${{ inputs.path }}
digest-mismatch: error

View file

@ -140,7 +140,7 @@ jobs:
run: npx tsx scripts/ensure-fts.ts
working-directory: gitnexus
- name: Download frozen timing snapshot
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
uses: ./.github/actions/download-test-artifact
with:
name: shard-timing-input
path: gitnexus/.vitest/timings
@ -201,7 +201,7 @@ jobs:
path: gitnexus/.vitest/blob
merge-multiple: true
- name: Download frozen timing snapshot
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
uses: ./.github/actions/download-test-artifact
with:
name: shard-timing-input
path: gitnexus/.vitest/timings
@ -291,7 +291,7 @@ jobs:
- name: Reuse this run's timing input on a retry
id: previous-input
if: steps.execution.outputs.initialize != 'true'
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
uses: ./.github/actions/download-test-artifact
with:
name: shard-timing-input
path: .vitest/timings
@ -404,7 +404,7 @@ jobs:
run: npx tsx scripts/ensure-fts.ts
working-directory: gitnexus
- name: Download frozen timing snapshot
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
uses: ./.github/actions/download-test-artifact
with:
name: shard-timing-input
path: gitnexus/.vitest/timings
@ -455,7 +455,7 @@ jobs:
with:
lifecycle-scripts: 'false'
- name: Download frozen timing snapshot
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
uses: ./.github/actions/download-test-artifact
with:
name: shard-timing-input
path: gitnexus/.vitest/timings
@ -1534,10 +1534,8 @@ jobs:
sha="$(uv run --locked --extra dev python -m workflow_bench.release_report task-sha)"
[[ "$sha" =~ ^[0-9a-f]{40}$ ]]
git -C .. worktree add --detach "${RUNNER_TEMP}/tasks-base" "$sha"
cd "${RUNNER_TEMP}/tasks-base"
npm ci --audit=false --fund=false
npm ci --prefix gitnexus --audit=false --fund=false
npm run build --prefix gitnexus
uv run --locked --extra dev python -m workflow_bench.release_build \
--repo "${RUNNER_TEMP}/tasks-base"
- name: Prove process-tree and sandbox containment
env:
CLAUDE_CANARY_BIN: ${{ runner.temp }}/claude-canary/node_modules/@anthropic-ai/claude-code-linux-x64/claude
@ -1553,6 +1551,7 @@ jobs:
tests/test_mock_provider.py
tests/test_mcp_tool_loading.py
tests/test_release_evaluation_smoke.py
tests/test_release_controls.py
tests/test_evolve.py::test_outer_runner_pid_namespace_kills_setsid_descendant
tests/test_oracle_assets.py::test_hidden_vitest_config_executes_sibling_oracle_against_candidate_checkout
tests/test_oracle_assets.py::test_shipped_oracles_reject_task_base_and_accept_reference_fixes

View file

@ -394,11 +394,11 @@ jobs:
run: |
uv run --locked --extra dev python -m workflow_bench.diagnostic_experiments \
--tasks "$RUNNER_TEMP/release-evaluation/candidate/tasks.yaml" \
--repository "$GITHUB_WORKSPACE/candidate" --runtime "$GITHUB_WORKSPACE/candidate" \
--repository "$GITHUB_WORKSPACE/tasks-base" --runtime "$GITHUB_WORKSPACE/candidate" \
--harness-sha "$GITHUB_SHA" --runtime-sha "$RUNTIME_SHA" \
--model "$MODEL" --effort "$EFFORT" --seed 3762 --repeats 1 \
--variants no_graph mcp_eager --task-ids trivial-status-json-alias \
--max-budget-usd 5 --out "$RUNNER_TEMP/release-evaluation/trial"
--max-budget-usd 5 --bind-task-dependencies --out "$RUNNER_TEMP/release-evaluation/trial"
- name: Require historical task dependencies before paid PR sessions
if: inputs.candidate_pr != ''
working-directory: eval
@ -425,6 +425,7 @@ jobs:
if [[ "${DIAGNOSTIC_TRIAL:-false}" == true ]]; then
uv run --locked --extra dev python -m workflow_bench.release_preflight \
--tasks "$RUNNER_TEMP/release-evaluation/trial/cell-0000.tasks.json" \
--grading-controls \
--gitnexus-root "$GITHUB_WORKSPACE/candidate" \
--claude-bin "$RUNNER_TEMP/claude-canary/node_modules/@anthropic-ai/claude-code-linux-x64/claude"
exit 0
@ -433,6 +434,7 @@ jobs:
if [[ -n "$INPUT_PR" && "$runtime" == stable ]]; then continue; fi
uv run --locked --extra dev python -m workflow_bench.release_preflight \
--tasks "$RUNNER_TEMP/release-evaluation/$runtime/tasks.yaml" \
--grading-controls \
--gitnexus-root "$GITHUB_WORKSPACE/$runtime" \
--claude-bin "$RUNNER_TEMP/claude-canary/node_modules/@anthropic-ai/claude-code-linux-x64/claude"
done

View file

@ -1,5 +1,23 @@
# Migration Guide
## LadybugDB 0.22.0 storage and extensions
LadybugDB 0.22.0 reads indexes written by 0.21.1, but a write/checkpoint upgrades
their storage format from version 47 to 49. No manual data conversion is needed.
Use the packaged FTS and VECTOR binaries shipped with the new core; older
extension binaries can load successfully and then crash when building an index.
Before upgrading, stop index writers and readers and retain a backup of the
complete index storage directory if rollback is required. Include shared stores
when worktrees or sibling clones share an index. Keep clients sharing a writable
index on compatible engine versions.
After an index is written by 0.22.0, downgrading the dependency alone is not
enough: 0.21.1 refuses storage version 49. Restore the backup, or rebuild with the
older engine using `gitnexus analyze --force`. A rebuild under an engine that
cannot read the upgraded index cannot recover its cached embeddings; use the
backup to preserve them, or regenerate them with `--embeddings`.
## Automatic parser cache identities
Parser caches now use artifact-derived base and PDG identities instead of

View file

@ -43,6 +43,10 @@ query: shared `--http` ran the batch in 7.7 s at a flat 517 MB, versus 30.0 s an
You can also query the graph directly from the terminal — `gitnexus query`, `context`, `impact`, `trace`, `cypher`, `detect-changes`, and `check` mirror the MCP tools of the same names, and `gitnexus doctor` prints runtime platform capabilities.
`gitnexus impact <symbol> --max-tokens 1000` budgets compact JSON at four UTF-8 bytes per token, retaining the nearest dependants first. Counts and risk remain complete; `pagination.trimmedForBudget` describes omitted symbols. If the summary cannot fit, the command returns a JSON error and exits nonzero. Extremely small budgets return JSON `null` with the same failure status. Budgeted output is compact even on a terminal; other direct tool output is compact when piped and indented on a terminal.
Impact defaults to 30 symbols per depth when pagination is omitted. Use `--limit` and `--offset` for explicit pages, or `GITNEXUS_IMPACT_DEFAULT_LIMIT=0` for all symbols. `--summary-only`, group queries and PDG mode bypass this default. Symbols list at most three processes, with `processCount` preserving the full count when shortened. `--max-tokens` is explicit on the CLI; `GITNEXUS_MCP_DEFAULT_MAX_TOKENS` applies only to MCP.
`gitnexus analyze --watch` requires a Git repository. It runs one initial
analysis, then debounces scanner-admitted working-tree changes for 300 ms by
default and applies serialized incremental refreshes. Events arriving during a
@ -224,15 +228,15 @@ sampling limits, and recovery.
Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max-file-size`, `--verbose`). Use the env-var form when you'd otherwise repeat the same flag every run, or when invoking GitNexus from a long-running host (MCP server, eval-server, CI shell) that already manages its own environment. CLI flags take precedence over `.gitnexusrc`, which takes precedence over env vars, which take precedence over built-in defaults.
| Query variable | Default | Effect | When to tune |
| --- | --- | --- | --- |
| Query variable | Default | Effect | When to tune |
| --------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `GITNEXUS_QUERY_MAX_RSS_MB` | max(8192 MiB, 25% of available RAM), capped at 75% of available RAM | Process-memory ceiling while pooled reads run; available RAM is the smaller of physical RAM and a reported runtime/container constraint. Positive MiB values override it; `0` disables the guard. Invalid, overflowing, or sub-byte values use the default. A breach exits the process with code 70. | Set in the CLI/MCP/serve environment when a legitimate read workload needs a different budget. It does not resize the database buffer pool. |
| `GITNEXUS_QUERY_TRACE` | unset | `1` writes query duration, row count, and sampled memory to stderr. Bound parameters are omitted; query text is included. | Diagnose an expensive read or a memory-guard exit. Inspect trace output before sharing it. |
| `GITNEXUS_QUERY_TRACE` | unset | `1` writes query duration, row count, and sampled memory to stderr. Bound parameters are omitted; query text is included. | Diagnose an expensive read or a memory-guard exit. Inspect trace output before sharing it. |
| Variable | Default | Effect | Tune when… |
| ----------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GITNEXUS_TEST_REPORT` | unset | Write a JSON execution receipt from `scripts/run-cross-platform.ts`; accepts a basename ending in `.json`. | CI platform shards use distinct filenames so the completeness check can require every report. |
| `GITNEXUS_SHARD_PROFILE` | `coverage` | Selects the timing profile for Vitest shard balancing and merged timing reports: `coverage`, `windows-latest`, or `macos-latest`. | CI selects its native OS; set the matching profile when reproducing a shard locally. See [Automatic shard balancing](../TESTING.md#automatic-shard-balancing). |
| `GITNEXUS_SHARD_PROFILE` | `coverage` | Selects the timing profile for Vitest shard balancing and merged timing reports: `coverage`, `windows-latest`, or `macos-latest`. | CI selects its native OS; set the matching profile when reproducing a shard locally. See [Automatic shard balancing](../TESTING.md#automatic-shard-balancing). |
| `GITNEXUS_WORKER_POOL_SIZE` | `cores - 1`, capped at 16 | Parse worker pool size (must be ≥ 1). Equivalent to `--workers <n>`. The worker pool is the sole parse path — there is no sequential parser, so `0` is rejected with an actionable error (the pool self-heals via quarantine + respawn). | Constrained containers (cgroup CPU limits) or CI runners with explicit quotas. To narrow down a worker crash set `1` for a single-worker pool — not `0`. |
| `GITNEXUS_PARSE_CHUNK_CONCURRENCY` | `2` | Number of chunks whose file contents may be read into memory in parallel while the pool dispatches the current chunk. Worker dispatch itself stays serial. | Repos large enough to chunk (multi-MB total source) where disk I/O is a measurable fraction of analyze wall-clock. |
| `GITNEXUS_VERBOSE` | unset | When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`. | Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput. |
@ -247,7 +251,7 @@ Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max
| `GITNEXUS_PROFILE_DEFERRED_SLOW_MS` | `3000` (verbose) / `5000` | Per-file threshold in ms above which `processCallsFromExtracted` emits a `slow file …` log line. Parsed via `Number()`: accepts integers (`5000`), scientific notation (`2.5e3`), decimals (`.5`), and hex (`0x10`). Non-finite or non-positive values fall back to the default. | Hunting a few outlier files dominating the deferred call-resolution stage; lower to surface more, raise to focus only on the worst. |
| `PROF_LBUG_LOAD` | unset | When `1`, emits one `[lbug-load prof]` summary line per `loadGraphToLbug` call breaking the graph-DB persistence wall into stages (`csv-emit` / `copy-nodes` / `copy-rels` / `fallback` / `total`) plus node & edge counts. Zero-cost when unset. | Attributing large-repo analyze wall time across CSV generation vs. LadybugDB `COPY` (issue #2203) — the analyze "emit" timing is the scope-resolution bucket, not this DB-write path. |
| `GITNEXUS_MAX_FILE_SIZE` | `512` (KB) | Walker skip threshold in KB. Hard cap is `32768` (tree-sitter buffer ceiling). Equivalent to `--max-file-size <kb>`. | Indexing repos with intentionally-large source files (generated parsers, vendored bundles) that should still be parsed. |
| `GITNEXUS_INCLUDE_DOT_DIRS` | unset | Comma-separated dot-directory names to index, e.g. `.github,.scallywag`. Changes take effect on the next analyze; status replays the recorded list. Hidden files, credential paths, and symlinks under opted-in paths remain excluded. Ignore rules still apply. | Indexing trusted source under hidden directories. For `.github`, also add `!.github/` to `.gitnexusignore`. Path protection does not scan source text for secrets. |
| `GITNEXUS_INCLUDE_DOT_DIRS` | unset | Comma-separated dot-directory names to index, e.g. `.github,.scallywag`. Changes take effect on the next analyze; status replays the recorded list. Hidden files, credential paths, and symlinks under opted-in paths remain excluded. Ignore rules still apply. | Indexing trusted source under hidden directories. For `.github`, also add `!.github/` to `.gitnexusignore`. Path protection does not scan source text for secrets. |
| `GITNEXUS_MAX_PROCESSES` | dynamic (`max(20, round(symbols/10))`) | Analyze-time process-detection process cap. Equivalent to `--max-processes <n>` / `.gitnexusrc` `maxProcesses`. Explicit values replace the dynamic formula (not a multiplier). `0` is invalid, not unlimited. Changing this re-detects flows on the next analyze without `--force`. Distinct from query-time `IMPACT_MAX_CHUNKS`. | `[processes] … whole flows are MISSING` names `--max-processes` after entry points were never traced or flows were dropped. Tracing does not start the next entry once collected traces already reach `maxProcesses * 2`; a started entry can still emit every trace that entry produces. |
| `GITNEXUS_MAX_PROCESS_BRANCHING` | `4` | Analyze-time per-node branching cap during flow tracing. Equivalent to `--max-process-branching <n>`. Shape-only: raising it shortens fewer traces; it does not restore whole missing flows. | A flow is present but `calleesDropped` is high at debug. |
| `GITNEXUS_MAX_PROCESS_TRACE_DEPTH` | `10` | Analyze-time DFS depth cap during flow tracing. Equivalent to `--max-process-trace-depth <n>`. Shape-only. | A reported flow is shorter than the code path (`tracesDepthCapped` at debug). |
@ -274,6 +278,9 @@ Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max
| `GITNEXUS_NO_GITIGNORE` | unset | When set, skips `.gitignore` parsing. `.gitnexusignore` is still honored. | Indexing a repo whose `.gitignore` excludes files you actually want indexed (e.g., generated code committed for cross-repo lookup). |
| `GITNEXUS_SKIP_OPTIONAL_GRAMMARS` | unset | When exactly `1`, skips optional vendored Dart, Proto, Swift, Kotlin and Zig grammar setup. The C grammar and other native dependencies remain required. | Skipping optional language parsers when their prebuilds are unavailable and no source-build toolchain is installed. |
| `GITNEXUS_MCP_READ_ONLY` | unset | Set to `1` to expose only proven single-repository read tools and resources; `0` disables the policy and any other value fails startup. | The MCP server runs in an environment where graph mutation, raw Cypher, and cross-repository group routing must be unavailable. |
| `GITNEXUS_MCP_ENABLE_REFRESH` | unset | Set to `1` to list the `refresh_index` MCP tool on a local `gitnexus mcp` server (stdio or `--http`). `gitnexus serve` never exposes it, read-only mode hides and rejects it, and any value other than `0` or `1` fails startup. | Agents on a local server can see a stale index but have no shell to run `gitnexus analyze`. |
| `GITNEXUS_MCP_REFRESH_MAX_FILES` | `5000` | `refresh_index` refuses a repository whose working tree holds more files than this, counted the way analyze scans it before starting the rebuild. `0` removes the limit. | Raise it when larger repositories should be refreshable over MCP. |
| `GITNEXUS_MCP_REFRESH_TIMEOUT_MS` | `600000` | Maximum time one `refresh_index` call waits for its rebuild before returning an error. The worker is not interrupted and finishes in the background. At most `2147483647`. | A refresh needs longer than ten minutes. |
| `GITNEXUS_MCP_ALLOWED_REPOS` | unset | Comma-separated allowlist of canonical indexed repository names or absolute paths. Invalid, ambiguous, or blank entries fail startup. | One MCP process must expose only a bounded subset of the repositories in the global registry. |
| `GITNEXUS_MCP_DEFAULT_REPO` | unset | Canonical indexed repository name or absolute path used when a tool or resource omits its repository. Must belong to the allowlist when one is set. | Several repositories are available but unqualified MCP calls should resolve deterministically. |
| `GITNEXUS_MCP_DEFAULT_MAX_TOKENS` | unset | Default positive-integer response budget for MCP `query`, `context`, and `impact`, estimated at four UTF-8 bytes per token. Explicit `maxTokens` wins. | Long MCP responses consume too much model context and callers cannot reliably add a per-request budget. |

View file

@ -77,6 +77,17 @@ Set `GITNEXUS_MCP_READ_ONLY=1` before starting the MCP server to expose only the
The default is unchanged when the variable is unset or `0`. Any other value fails server startup rather than silently weakening the policy.
## MCP index refresh
A local server started with `GITNEXUS_MCP_ENABLE_REFRESH=1` also lists `refresh_index`, which rebuilds one registered repository's index from its working tree. It is meant for agents that can see a stale index (`staleness.status` of `behind` or `diverged`) but cannot run `gitnexus analyze` themselves.
- **Index-only.** The rebuild runs in the same forked analyze worker auto-sync uses, with `--skip-agents-md --skip-skills`: no `AGENTS.md`, `CLAUDE.md`, skill, hook, or other repository file is written. It is incremental where it can be and keeps existing embeddings and PDG mode.
- **Local only.** `gitnexus serve` (and so the Docker `/api/mcp` surface) never lists it, whatever its environment. With `GITNEXUS_MCP_READ_ONLY=1` it is hidden from discovery and rejected before dispatch.
- **Bounded.** Before starting, the server counts the repository's working tree the way analyze scans it (same patterns and ignore rules, stopping one past the limit) and refuses it when that count exceeds `GITNEXUS_MCP_REFRESH_MAX_FILES` (default `5000`; `0` for no limit, and no count). The count is taken before size filtering, so it can exceed what analyze then indexes. `dry_run` reports it as `estimatedFiles` (`null` when over the limit or with no limit) next to the last index's `lastIndexedFiles`. After `GITNEXUS_MCP_REFRESH_TIMEOUT_MS` (default ten minutes) the call stops waiting and returns an error. The analyze worker never interrupts an analysis it has started, so it finishes and publishes in the background, holding the index lock until then. Cancelling the request does not stop a started rebuild either. After timeout or cancellation, a new call gets "already running" and `dry_run` reports `inProgress` until the worker exits. Only one refresh per repository runs at a time. The file limit does not bound embedding generation, which `.gitnexusrc` can request.
- **Observable.** `dry_run: true` reports staleness, the indexed file count, whether `.gitnexusrc` makes the rebuild generate embeddings, and whether a refresh would run. A real call waits for the rebuild and returns `indexedAt`, `lastCommit`, `stats`, and `staleness`, with the values before the refresh under `previous`. A rebuild whose graph write collapsed is reported as an error, as `gitnexus analyze` and `serve` report it. Clients that send a progress token receive progress notifications; the MCP TypeScript SDK client gives up on a request after 60 seconds by default unless it resets that timeout on progress.
The tool takes `repo` and `dry_run` only. Like an applied `rename`, it needs an explicit `repo` unless one repository is indexed or an MCP default is configured.
## MCP repository policy
Set `GITNEXUS_MCP_ALLOWED_REPOS` to a comma-separated list of canonical registry names or absolute indexed paths. Entries are trimmed, resolved against the registry, and deduplicated at startup. When exactly one repository is allowed it becomes the implicit default; when several are allowed, callers must select one unless `GITNEXUS_MCP_DEFAULT_REPO` is also set.
@ -101,9 +112,13 @@ data; omission does not mean absence. Remove filters for a broader view. For
impact, existing `summaryOnly`, `limit` and `offset` already provide focused views.
Omitting these filters preserves the existing response.
The `query`, `context`, and `impact` tools accept an optional positive-integer `maxTokens` argument. It bounds the complete formatted MCP response, including hints and error text, using a deterministic four-UTF-8-bytes-per-token estimate. When truncation is required, the response ends with `…` and remains valid UTF-8.
The `query`, `context`, and `impact` tools accept an optional positive-integer `maxTokens` argument. It bounds the complete formatted MCP response, including hints and error text, using a deterministic four-UTF-8-bytes-per-token estimate. For `query` and `context`, truncation ends the response with `…` and preserves valid UTF-8.
Set `GITNEXUS_MCP_DEFAULT_MAX_TOKENS` to apply the same guardrail when callers do not send `maxTokens`. An explicit tool argument takes precedence. Leaving both unset preserves the existing response byte-for-byte; this is a transport guardrail, not semantic pagination or an exact model-specific tokenizer limit.
Set `GITNEXUS_MCP_DEFAULT_MAX_TOKENS` to apply the budget when callers do not send `maxTokens`. An explicit tool argument takes precedence. Leaving both unset disables token budgeting. The estimate is not an exact model-specific tokenizer limit.
`impact` removes whole symbols from the deepest levels first. Counts, risk and completeness warnings remain intact, and `pagination.trimmedForBudget.shownByDepth` records the returned counts. If metadata alone cannot fit, it returns a JSON error with MCP `isError: true`; increase `maxTokens` or narrow the request. Budgets too small for an error object return JSON `null` with `isError: true`. Group and PDG results are not paginated or trimmed by this mechanism; an oversized result also returns a budget error.
Without explicit pagination, single-repo callgraph impact returns up to 30 symbols per depth. Client-supplied `offset: 0` and `summaryOnly: false` still use this default. Set `GITNEXUS_IMPACT_DEFAULT_LIMIT=0` for an unpaged result, or set `limit` and `offset` for explicit pages. Each symbol lists at most three processes; `processCount` records the full count when the list is shortened. Backend results used by the web UI and internal callers are unchanged.
## Tool Examples
@ -201,7 +216,7 @@ affected_processes: [LoginFlow, RegistrationFlow, ...]
### Rename (Graph and Semantic Layer)
```js
rename({symbol_name: "validateUser", new_name: "verifyUser", repo: "my-app", dry_run: true})
rename({ symbol_name: 'validateUser', new_name: 'verifyUser', repo: 'my-app', dry_run: true });
// Omitting dry_run also previews. For an ambiguous name, repeat with the symbol_uid from context().
```

View file

@ -20,6 +20,12 @@ gitnexus wiki --force
gitnexus wiki --timeout <seconds> # LLM request timeout in seconds (default: disabled)
gitnexus wiki --retries <n> # Max LLM retry attempts per request (default: 3)
# Raise the completion-token limit (default: 16384)
gitnexus wiki --max-completion-tokens 131072
GITNEXUS_MAX_COMPLETION_TOKENS=131072 gitnexus wiki
# Or set "maxCompletionTokens": 131072 in ~/.gitnexus/config.json
# Precedence: flag, then the environment variable, then the config file.
# Allow a specific LAN/self-hosted HTTP LLM host (HTTPS is preferred for remote endpoints)
gitnexus wiki --base-url http://llama-box.local:8080/v1 --allow-insecure-connection llama-box.local
# Or set a comma-separated host allowlist:
@ -29,6 +35,17 @@ GITNEXUS_ALLOW_INSECURE_CONNECTION=llama-box.local,192.168.1.23
gitnexus wiki --lang <lang> # e.g. english, chinese, spanish, japanese
```
The completion limit must be a positive integer supported by your model. It applies to
OpenAI-compatible HTTP providers; local agent CLI providers manage their own limits.
For reasoning models, the limit includes reasoning tokens as well as the visible answer.
When a provider reports `finish_reason: "length"`, GitNexus rejects the incomplete response
instead of saving it as a finished page. Failed modules are listed, the command exits with
status 1, and a normal rerun retries them even if the repository commit has not changed.
Increase `--max-completion-tokens` within your model's supported limit before retrying.
Truncated grouping or overview responses also fail the run; batched grouping retains its
directory-based fallback. Incomplete runs are not published with `--gist`.
Use `--force` to replace incomplete pages already saved by an older version.
For safety, `http://` LLM base URLs are allowed by default only for loopback hosts (`localhost`, `127.0.0.1`, `::1`). `--allow-insecure-connection` and `GITNEXUS_ALLOW_INSECURE_CONNECTION` accept exact hostnames or IP addresses only; do not include schemes, ports, paths, credentials, or wildcards.
The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.

View file

@ -24,16 +24,20 @@ SHA = "a" * 40
def trial_plan(tmp_path, monkeypatch):
runtime = tmp_path / "candidate"
runtime.mkdir()
task_repo = tmp_path / "tasks-base"
task_repo.mkdir()
monkeypatch.setattr(diagnostic_experiments, "trial_task_bindings", lambda tasks, expected=None: [{"id": tasks[0]["id"]}])
output = tmp_path / "release-evaluation" / "trial"
monkeypatch.setattr(sys, "argv", [
"prepare", "--tasks", str(ROOT / "eval/workflow_bench/tasks.scenarios.yaml"),
"--repository", str(runtime), "--runtime", str(runtime), "--runtime-sha", SHA,
"--repository", str(task_repo), "--runtime", str(runtime), "--runtime-sha", SHA,
"--harness-sha", SHA, "--model", diagnostic_trial.MODEL, "--repeats", "1",
"--variants", "no_graph", "mcp_eager", "--task-ids", diagnostic_trial.TASK,
"--max-budget-usd", "5", "--out", str(output),
"--max-budget-usd", "5", "--bind-task-dependencies", "--out", str(output),
])
diagnostic_experiments.main()
monkeypatch.setattr(diagnostic_trial, "_head", lambda repository: SHA)
monkeypatch.setattr(diagnostic_trial, "_head", lambda repository:
"c4ecf398de637cf779ab2238e69958cfd5d601ce" if repository == task_repo else SHA)
return output / "plan.json", runtime

View file

@ -0,0 +1,71 @@
"""Reference grading must work before a paid release or telemetry session starts."""
from contextlib import nullcontext
import os
from pathlib import Path
from types import SimpleNamespace
import pytest
import yaml
from workflow_bench import release_controls
from workflow_bench.proposer_sandbox import SandboxError, preflight_bubblewrap
from workflow_bench.task_assets import TaskAssetCache
@pytest.mark.parametrize("failure", [None, "negative_passes", "startup", "permission", "patch", "typecheck", "reference"])
def test_controls_require_behavioral_failure_then_a_typed_reference(monkeypatch, tmp_path, failure):
task = {"id": "trivial-status-json-alias"}
clone = tmp_path / "clone"
clone.mkdir()
mounts, calls = [], []
sandbox = SimpleNamespace(clone=clone, environment=lambda: {},
command_prefix_for=lambda **kw: mounts.append(kw) or ["sandbox"])
monkeypatch.setattr(release_controls, "make_worktree", lambda *_: clone)
monkeypatch.setattr(release_controls, "sanitize_clone_for_hidden_oracles", lambda *_: None)
monkeypatch.setattr(release_controls, "stage_task_assets", lambda *_a, **_kw: [])
monkeypatch.setattr(release_controls, "capture_task_oracle", lambda *_: object())
monkeypatch.setattr(release_controls, "prepare_sandbox", lambda **_: nullcontext(sandbox))
def oracle(*_args, diagnostics=None):
calls.append("negative" if diagnostics is not None else "reference")
if diagnostics is not None:
diagnostics.update(exit_code=1, assertion_failure=True, startup_failure=failure == "startup",
permission_failure=failure == "permission")
return failure == "negative_passes", "hidden output withheld"
return failure != "reference", "hidden output withheld"
def verify(command, *_args, **_kwargs):
step = "patch" if command.startswith("git apply") else "typecheck"
calls.append(step)
return failure != step, "PRIVATE OUTPUT"
monkeypatch.setattr(release_controls, "_run_hidden_oracle", oracle)
monkeypatch.setattr(release_controls, "run_verify", verify)
if failure:
with pytest.raises(SandboxError) as error:
release_controls.check_task_controls(task, repo=tmp_path, sha="a" * 40, parent=tmp_path,
assets=object(), claude_bin=Path("claude"), bwrap_bin=Path("bwrap"))
assert "PRIVATE" not in str(error.value)
else:
release_controls.check_task_controls(task, repo=tmp_path, sha="a" * 40, parent=tmp_path,
assets=object(), claude_bin=Path("claude"), bwrap_bin=Path("bwrap"))
assert calls == ["negative", "patch", "typecheck", "reference"]
assert mounts[-1] == {"read_only_workspace": True, "unshare_network": True}
if failure in ("negative_passes", "startup", "permission"):
assert calls == ["negative"]
@pytest.mark.skipif(os.environ.get("GITNEXUS_REQUIRE_BWRAP_CANARY") != "1",
reason="requires the provisioned Linux containment runner")
def test_real_release_reference_controls_use_pinned_dependencies_and_read_only_grading(tmp_path):
# No provider, proxy, or agent process. The pinned CLI executable is only a
# sandbox mount; grading invokes the historical TypeScript/Vitest toolchain.
repo = Path(os.environ["GITNEXUS_ORACLE_TASK_DEPENDENCIES"])
claude = Path(os.environ["CLAUDE_CANARY_BIN"])
tasks = yaml.safe_load((Path(__file__).parents[1] / "workflow_bench/tasks.scenarios.yaml").read_text())["tasks"]
task = next(t for t in tasks if t["id"] == "trivial-status-json-alias")
with TaskAssetCache(tmp_path / "assets") as cache:
snapshot = cache.prepare(task, repo=repo, resolved_sha=task["ref"])
release_controls.check_task_controls(task, repo=repo, sha=task["ref"], parent=tmp_path,
assets=snapshot, claude_bin=claude, bwrap_bin=preflight_bubblewrap())

View file

@ -39,6 +39,7 @@ def prepared(monkeypatch, tmp_path):
monkeypatch.setattr(release_preflight, "preflight_bubblewrap", lambda: Path("/fake/bwrap"))
monkeypatch.setattr(release_preflight, "require_claude_sandbox_helpers", lambda: None)
monkeypatch.setattr(release_preflight, "trusted_gitnexus_runtime_mounts", lambda **_: ())
monkeypatch.setattr(release_preflight, "check_task_controls", lambda *_a, **_kw: None)
monkeypatch.setattr(task_assets, "_try_reflink", lambda *_: False)
# Only graph construction/containment are substituted. Binding resolution,
@ -101,3 +102,27 @@ def test_preflight_rejects_task_assets_that_replace_the_graph(prepared, tmp_path
release_preflight.preflight_release(
[{**task, "sandbox_copy": [".gitnexus/meta.json"]}], gitnexus_root=tmp_path, claude_bin=Path("claude"),
)
def test_grading_control_failure_stops_preflight_with_captured_task_dependencies(prepared, monkeypatch, tmp_path):
task, _, _ = prepared
dependency = Path(task["repo"]) / "node_modules" / "fixture"
dependency.mkdir(parents=True)
(dependency / "index.js").write_bytes(b"module.exports = 'pinned dependency';\n")
task["sandbox_dependencies"] = [{"source": "node_modules", "target": "node_modules"}]
calls = []
def reject(task_arg, **kwargs):
calls.append(kwargs)
assets = kwargs["assets"]
assert task_arg == task
assert assets.dependency_declarations == (("node_modules", "node_modules"),)
assert len(assets.dependencies) == 1
captured = assets.root / assets.dependencies[0].snapshot_path / "fixture/index.js"
assert captured.read_bytes() == b"module.exports = 'pinned dependency';\n"
raise SandboxError("reference grading control failed")
monkeypatch.setattr(release_preflight, "check_task_controls", reject)
with pytest.raises(SandboxError, match="reference grading control failed"):
release_preflight.preflight_release([task], gitnexus_root=tmp_path, claude_bin=Path("claude"), grading_controls=True)
assert len(calls) == 1 and calls[0]["sha"] == task["ref"]

View file

@ -214,7 +214,7 @@ def _expectation(**overrides: Any) -> ComparatorReuseExpectation:
binding = TaskReuseBinding(
task_base_sha=SHA,
task_prompt_digest=runner.hashlib.sha256(b"review it").hexdigest(),
task_prompt_digest=runner.task_prompt_digest({"prompt": "review it"}),
oracle_digest="oracle-content",
oracle_command_digest="oracle-command",
oracle_manifest_digest="oracle-manifest",
@ -258,7 +258,7 @@ def test_a_changed_binding_rejects_the_same_emitted_row(
binding = TaskReuseBinding(
task_base_sha=SHA,
task_prompt_digest=runner.hashlib.sha256(b"review it").hexdigest(),
task_prompt_digest=runner.task_prompt_digest({"prompt": "review it"}),
oracle_digest="oracle-content",
oracle_command_digest="oracle-command",
oracle_manifest_digest="oracle-manifest",
@ -266,3 +266,14 @@ def test_a_changed_binding_rejects_the_same_emitted_row(
sandbox_dependency_manifest_digest="DIFFERENT-dependencies",
)
assert row_is_reusable_comparator(row, _expectation(tasks={TASK_ID: binding})) is False
def test_old_prompt_identity_cannot_reuse_a_row_without_the_environment_instruction(emitted_row):
legacy = {**emitted_row, "task_prompt_digest": runner.hashlib.sha256(b"review it").hexdigest()}
assert not row_is_reusable_comparator(legacy, _expectation())
def test_changed_environment_instruction_invalidates_a_previously_matching_row(emitted_row, monkeypatch):
assert row_is_reusable_comparator(emitted_row, _expectation())
monkeypatch.setattr(runner, "MCP_REPOSITORY_PROMPT", runner.MCP_REPOSITORY_PROMPT + " Changed instruction.")
assert not row_is_reusable_comparator(emitted_row, _expectation())

View file

@ -0,0 +1,101 @@
"""Prepared trials must reject dependency drift before launching paid cells."""
import json
from pathlib import Path
import subprocess
import sys
from typing import get_args
import pytest
import yaml
from tests import test_diagnostic_trial
from workflow_bench import diagnostic_experiments, diagnostic_trial
from workflow_bench.process_control import ProcessState
from workflow_bench.verification_diagnostics import public_verification
@pytest.fixture
def bound_trial(tmp_path, monkeypatch):
repo, runtime = tmp_path / "tasks-base", tmp_path / "runtime"
repo.mkdir()
runtime.mkdir()
(repo / ".gitignore").write_text("node_modules/\n")
(repo / "package-lock.json").write_text('{"lockfileVersion": 3}\n')
for args in (
["init", "-q"], ["add", "."],
["-c", "user.name=Test", "-c", "user.email=test@example.test", "commit", "-qm", "fixture"],
):
subprocess.run(["git", "-C", str(repo), *args], check=True, capture_output=True)
sha = subprocess.check_output(["git", "-C", str(repo), "rev-parse", "HEAD"], text=True).strip()
dependency = repo / "node_modules" / "fixture.js"
dependency.parent.mkdir()
dependency.write_text("module.exports = 'pinned';\n")
corpus = yaml.safe_load((Path(__file__).parents[1] / "workflow_bench/tasks.scenarios.yaml").read_text())
task = next(task for task in corpus["tasks"] if task["id"] == diagnostic_trial.TASK)
task.update(ref=sha, sandbox_dependencies=[{"source": "node_modules", "target": "node_modules"}])
manifest = tmp_path / "tasks.yaml"
manifest.write_text(yaml.safe_dump({"tasks": [task]}))
output = tmp_path / "trial"
monkeypatch.setattr(sys, "argv", [
"prepare", "--tasks", str(manifest), "--repository", str(repo), "--runtime", str(runtime),
"--runtime-sha", test_diagnostic_trial.SHA, "--harness-sha", test_diagnostic_trial.SHA,
"--model", diagnostic_trial.MODEL, "--repeats", "1", "--variants", "no_graph", "mcp_eager",
"--max-budget-usd", "5", "--bind-task-dependencies", "--out", str(output),
])
diagnostic_experiments.main()
monkeypatch.setattr(diagnostic_trial, "_head", lambda path: sha if path == repo else test_diagnostic_trial.SHA)
return output / "plan.json", runtime, repo, dependency
def test_prepared_bindings_reach_both_runner_processes(bound_trial, monkeypatch):
path, runtime, _, _ = bound_trial
plan = json.loads(path.read_text())
calls = []
monkeypatch.setattr(diagnostic_trial.subprocess, "run", test_diagnostic_trial.fake_runner(calls))
assert diagnostic_trial.execute_trial(path, runtime, "claude") == 0
assert len(calls) == 2
for (command, _), cell in zip(calls, plan["cells"], strict=True):
bound = json.loads(command[command.index("--task-bindings-json") + 1])
assert bound == cell["task_bindings"]
assert bound[0]["sandbox_dependency_content_digest"]
@pytest.mark.parametrize("change", ["tracked", "staged", "modified_dependency", "new_dependency", "deleted_dependency", "missing_binding"])
def test_trial_rejects_checkout_or_dependency_drift_before_execution(bound_trial, monkeypatch, change):
path, runtime, repo, dependency = bound_trial
if change in ("tracked", "staged"):
(repo / "package-lock.json").write_text('{"lockfileVersion": 2}\n')
if change == "staged":
subprocess.run(["git", "-C", str(repo), "add", "package-lock.json"], check=True)
elif change == "modified_dependency":
dependency.write_text("module.exports = 'changed';\n")
elif change == "new_dependency":
(dependency.parent / "extra.js").write_text("unexpected dependency\n")
elif change == "deleted_dependency":
dependency.unlink()
else:
plan = json.loads(path.read_text())
del plan["cells"][0]["task_bindings"]
path.write_text(json.dumps(plan))
monkeypatch.setattr(diagnostic_trial.subprocess, "run", lambda *_a, **_kw: pytest.fail("paid executor reached"))
with pytest.raises(ValueError, match="clean pinned|definition drifted|pin task dependency"):
diagnostic_trial.execute_trial(path, runtime, "claude")
assert not (path.parent / "execution.json").exists()
def test_planning_rejects_dirty_dependency_source_before_pinning(bound_trial):
path, _, repo, _ = bound_trial
(repo / "package-lock.json").write_text("dirty\n")
tasks = json.loads((path.parent / "cell-0000.tasks.json").read_text())["tasks"]
with pytest.raises(ValueError, match="clean pinned"):
diagnostic_experiments.trial_task_bindings(tasks)
@pytest.mark.parametrize("state", get_args(ProcessState))
def test_public_verification_preserves_every_terminal_process_state(state):
assert public_verification({"state": state})["state"] == state
def test_public_verification_withholds_unknown_process_state():
assert public_verification({"state": "private unrecognized output"})["state"] == "unknown"

View file

@ -0,0 +1,190 @@
"""Regressions from the first paid two-cell telemetry trial. No model calls."""
import hashlib
import json
import os
from pathlib import Path
import subprocess
import sys
import pytest
from tests import test_diagnostic_trial
from tests.test_workflow_bench_sessions import _probe_cell_provisioning
from workflow_bench import cost_diagnostics, diagnostic_experiments, diagnostic_trial, runner
from workflow_bench.process_control import ManagedProcessResult
from workflow_bench.runner_artifacts import VerificationResult
from workflow_bench.runner_sessions import allowed_agent_tools
from workflow_bench.session_diagnostics import diagnose_session, public_cell_diagnostics
from workflow_bench.verification_diagnostics import public_verification, verification_metrics
trial_plan = test_diagnostic_trial.trial_plan
def test_real_trial_planner_command_keeps_task_dependencies_separate_from_runtime(tmp_path, monkeypatch):
step = next(s for s in test_diagnostic_trial.workflow()["jobs"]["evaluate"]["steps"] if s.get("name") == "Prepare the capped diagnostic trial")
capture = tmp_path / "argv.json"
uv = tmp_path / "uv"
uv.write_text(f"#!{sys.executable}\nimport json,os,sys\nopen(os.environ['CAPTURE'],'w').write(json.dumps(sys.argv[1:]))\n")
uv.chmod(0o755)
subprocess.run(["bash", "-c", step["run"]], check=True, env={
**os.environ, "PATH": f"{tmp_path}:{os.defpath}", "CAPTURE": str(capture),
"RUNNER_TEMP": str(tmp_path), "GITHUB_WORKSPACE": str(tmp_path),
"GITHUB_SHA": "a" * 40, "RUNTIME_SHA": "b" * 40, "MODEL": diagnostic_trial.MODEL, "EFFORT": "xhigh",
})
argv = json.loads(capture.read_text())
assert "--bind-task-dependencies" in argv
monkeypatch.setattr(diagnostic_experiments, "trial_task_bindings", lambda tasks: [{"id": tasks[0]["id"]}])
manifest = Path(argv[argv.index("--tasks") + 1])
manifest.parent.mkdir(parents=True)
source = Path(__file__).parents[1] / "workflow_bench/tasks.scenarios.yaml"
manifest.write_bytes(source.read_bytes())
monkeypatch.setattr(sys, "argv", ["prepare", *argv[argv.index("workflow_bench.diagnostic_experiments") + 1:]])
diagnostic_experiments.main()
plan_path = tmp_path / "release-evaluation/trial/plan.json"
plan = json.loads(plan_path.read_text())
for cell in plan["cells"]:
task = json.loads((plan_path.parent / f"{cell['cell_id']}.tasks.json").read_text())["tasks"][0]
assert task["repo"] == str(tmp_path / "tasks-base")
assert task["repo"] == plan["task_repository"]
assert task["ref"] == "c4ecf398de637cf779ab2238e69958cfd5d601ce"
assert cell["argv"][cell["argv"].index("--gitnexus-root") + 1] == str(tmp_path / "candidate")
def test_old_candidate_dependency_override_fails_before_paid_executor(trial_plan, monkeypatch):
path, runtime = trial_plan
plan = json.loads(path.read_text())
plan["task_repository"] = str(runtime)
for cell in plan["cells"]:
manifest = path.parent / f"{cell['cell_id']}.tasks.json"
doc = json.loads(manifest.read_text())
doc["tasks"][0]["repo"] = str(runtime)
manifest.write_text(json.dumps(doc))
cell["task_manifest_sha256"] = hashlib.sha256(manifest.read_bytes()).hexdigest()
path.write_text(json.dumps(plan))
monkeypatch.setattr(diagnostic_trial.subprocess, "run", lambda *_a, **_k: pytest.fail("paid executor reached"))
with pytest.raises(ValueError, match="pinned task checkout"):
diagnostic_trial.execute_trial(path, runtime, "claude")
assert not (path.parent / "execution.json").exists()
def test_placeholder_cli_usage_does_not_claim_zero_context():
fields = ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "output_tokens")
work = diagnose_session([{"type": "assistant", "message": {
"id": "placeholder", "usage": dict.fromkeys(fields, 0), "content": [{"type": "text", "text": "done"}],
}}], [1], 2)["workload"]
assert work["usage_snapshots"] == 1 and work["complete_input_snapshots"] == 0
for field in ("first_input_tokens", "max_input_tokens", "sum_input_tokens", "sum_output_tokens"):
assert work[field] is None
def test_provider_request_context_uses_native_cache_semantics_and_withholds_conflicts():
event = {"response_id": "r1", "provider": "litellm-normalized", "native_usage": {
"prompt_tokens": 100, "prompt_tokens_details": {"cached_tokens": 80}, "completion_tokens": 10,
}}
report = cost_diagnostics.provider_summary([event, event])
assert report["request_tokens"]["total_input_tokens"]["max"] == 100
assert report["request_tokens"]["cache_read_input_tokens"]["max"] == 80
assert report["request_tokens"]["total_input_tokens"]["observed"] == 1
conflicted = cost_diagnostics.provider_summary([event, {**event, "status": "failure"}])
assert conflicted["request_tokens"]["total_input_tokens"]["max"] is None
def test_grading_evidence_survives_publication_without_hidden_output():
result = VerificationResult("private command", ManagedProcessResult(
state="exited", returncode=1, stdout_tail="PRIVATE hidden source", stderr_tail="EROFS", duration_s=2.5,
), "PRIVATE hidden source\nAssertionError: private test\nEROFS")
evidence = verification_metrics(result, 2.5)
public = public_cell_diagnostics({"verification_diagnostics": {"hidden": evidence | {"output": result.output}}})
assert "PRIVATE" not in json.dumps(public)
assert public["verification_diagnostics"]["hidden"]["exit_code"] == 1
assert public["verification_diagnostics"]["hidden"]["assertion_failure"] is True
assert public_verification({"state": "PRIVATE", "exit_code": True, "duration_s": float("nan")})["exit_code"] is None
def test_failed_cells_keep_task_provenance_and_budget(monkeypatch, tmp_path):
ctx, *_ = _probe_cell_provisioning(monkeypatch, tmp_path)
ctx.args.max_budget_usd = 5
ctx.args.measurement_revisions = {"runtime_sha": "b" * 40, "harness_sha": "c" * 40}
row = runner.run_cell(ctx, 0, "baseline_nomcp")
assert row["error_kind"] == "infra-error"
assert row["runtime_sha"] == "b" * 40 and row["harness_sha"] == "c" * 40
assert row["max_budget_usd"] == 5 and row["task_base_sha"] == ctx.task_sha
assert row["task_prompt_digest"] and row["model"] == ctx.args.model
def test_mcp_read_tools_are_permitted_and_measured_without_mutating_permissions():
tools = allowed_agent_tools(implementation=True)
assert {"mcp__gitnexus__grep", "mcp__gitnexus__read_file"} <= set(tools)
assert "mcp__gitnexus__rename" not in tools and "mcp__gitnexus__cypher" not in tools
events = [{"type": "assistant", "message": {"content": [
{"type": "tool_use", "id": "grep", "name": "mcp__gitnexus__grep", "input": {}},
]}}]
assert diagnose_session(events, [0], 1)["workload"]["graph_calls"] == 1
def test_cost_summary_displays_setup_grading_and_provider_tokens(tmp_path, monkeypatch):
results = tmp_path / "results.jsonl"
results.write_text(json.dumps({"arm": "baseline", "task": "fixture", "verification_diagnostics": {
"hidden": {"passed": False, "state": "exited", "exit_code": 1, "duration_s": 3, "typecheck_failure": True},
}}) + "\n")
timing = {"complete": True, "workers": 1, "total_s": 600, "before_first_cell_s": 500,
"dependency_setup_s": 100, "foreground_graph_setup_s": 400, "private": "PRIVATE"}
(tmp_path / "sweep-timing.json").write_text(json.dumps(timing))
out, markdown = tmp_path / "public.json", tmp_path / "public.md"
monkeypatch.setattr(sys, "argv", ["diagnostics", "--results", str(results), "--out", str(out), "--markdown-out", str(markdown)])
cost_diagnostics.main()
assert json.loads(out.read_text())["sweep_timing"]["before_first_cell_s"] == 500
assert "PRIVATE" not in out.read_text()
text = markdown.read_text()
assert "before_first_cell_s | 500" in text and "typecheck_failure" in text
def test_release_preflight_requires_grading_controls_in_both_workflow_paths():
step = next(s for s in test_diagnostic_trial.workflow()["jobs"]["evaluate"]["steps"] if s.get("name") == "Materialize both release graphs before paid sessions")
assert step["run"].count("workflow_bench.release_preflight") == step["run"].count("--grading-controls") == 2
def test_public_release_rows_keep_comparable_provenance_and_budget():
from tests.test_release_report import metadata, rows
from workflow_bench.release_report import build_report
source = rows()
for row in source:
row.update(runtime_sha="a" * 40, harness_sha="c" * 40, task_prompt_digest="d" * 64,
max_budget_usd=5.0, mcp_tool_loading="eager" if row["arm"] == "baseline" else "none")
exported = build_report(source, metadata())["per_run"]
report = cost_diagnostics.build_cost_report(exported)
assert all(group["provenance_complete"] for group in report["groups"])
assert all(group["cohort"]["max_budget_usd"] == "5.0" for group in report["groups"])
assert all(group["cohort"]["runtime_digest"] == "" for group in report["groups"])
def test_mcp_session_prompt_names_the_isolated_repository(monkeypatch, tmp_path):
from tests.test_workflow_bench_sessions import VALID_REPORT, bench_args, fake_cli_result, fake_sandbox
from workflow_bench import runner_sessions
prompts = []
def execute(command, **kwargs):
prompts.append(kwargs["stdin_data"].decode())
return fake_cli_result(VALID_REPORT)
monkeypatch.setattr(runner_sessions, "run_managed", execute)
monkeypatch.setattr(runner, "run_verify", lambda *_a, **_k: (True, "ok"))
for arm in ("baseline", "baseline_nomcp"):
runner.run_arm(arm, {"prompt": "Repair the task", "verify": "true"}, tmp_path,
bench_args(), sandbox=fake_sandbox(tmp_path))
assert "benchmark-target" in prompts[0]
assert "benchmark-target" not in prompts[1]
def test_interrupted_timing_does_not_discard_cell_evidence(tmp_path, monkeypatch):
results, out = tmp_path / "results.jsonl", tmp_path / "public.json"
results.write_text('{"arm":"baseline_nomcp","task":"fixture"}\n')
(tmp_path / "sweep-timing.json").write_text('{"complete":')
monkeypatch.setattr(sys, "argv", ["diagnostics", "--results", str(results), "--out", str(out), "--allow-incomplete"])
cost_diagnostics.main()
report = json.loads(out.read_text())
assert report["cells"] == 1 and report["sweep_timing"] is None
assert "Sweep timing file is unreadable." in report["input_problems"]

View file

@ -255,6 +255,9 @@ def test_eval_ci_uses_locked_uv_and_blocking_native_containment_jobs():
"npm ci",
"npm run build",
]
task_build = containment_steps["Build the pinned task toolchain that grades release evaluation"]["run"]
assert "python -m workflow_bench.release_build" in task_build
assert '--repo "${RUNNER_TEMP}/tasks-base"' in task_build
selected_containment_tests = containment_steps["Prove process-tree and sandbox containment"]["run"].split()
assert selected_containment_tests == [
"uv",
@ -281,6 +284,7 @@ def test_eval_ci_uses_locked_uv_and_blocking_native_containment_jobs():
# Paired prepare/session/oracle/report composition uses that same native
# CLI and containment; it must execute here rather than skip everywhere.
"tests/test_release_evaluation_smoke.py",
"tests/test_release_controls.py",
# These also need runtime dependencies absent from the locked pytest job.
"tests/test_evolve.py::test_outer_runner_pid_namespace_kills_setsid_descendant",
"tests/test_oracle_assets.py::test_hidden_vitest_config_executes_sibling_oracle_against_candidate_checkout",
@ -298,7 +302,8 @@ def test_eval_ci_uses_locked_uv_and_blocking_native_containment_jobs():
for path in (repo_root / "eval" / "tests").glob("test_*.py")
if bwrap_canary_marker.search(path.read_text())
)
assert bwrap_canary_files == ["test_cli_shim.py", "test_proposer_sandbox.py", "test_workflow_bench_sessions.py"]
assert bwrap_canary_files == ["test_cli_shim.py", "test_proposer_sandbox.py", "test_release_controls.py",
"test_workflow_bench_sessions.py"]
assert all(f"tests/{name}" in selected_containment_tests for name in bwrap_canary_files)
assert "eval-containment-windows:" in workflow
@ -411,6 +416,62 @@ def test_test_artifact_retries_cannot_hide_missing_evidence(ci_test_jobs):
)
def test_test_artifact_download_retries_require_a_verified_artifact():
repo_root = Path(__file__).resolve().parents[2]
action = yaml.safe_load((repo_root / ".github/actions/download-test-artifact/action.yml").read_text())
assert action["runs"]["using"] == "composite"
assert action["inputs"]["name"]["required"] is True
assert action["inputs"]["path"]["required"] is True
first, wait, second, final_wait, final = action["runs"]["steps"]
assert "if" not in first
assert first["id"] == "first" and second["id"] == "second"
assert first["continue-on-error"] is True
assert second["continue-on-error"] is True
assert not final.get("continue-on-error", False)
# Use raw outcomes: continue-on-error turns a failed attempt's conclusion
# into success. Stop retrying after recovery or cancellation.
for pause, attempt, previous, delay in (
(wait, second, "first", 10),
(final_wait, final, "second", 30),
):
assert pause["if"] == attempt["if"] == "${{ !cancelled() && steps." + previous + ".outcome == 'failure' }}"
assert pause["shell"] == "bash"
assert pause["run"] == f"sleep {delay}"
assert len({step["uses"] for step in (first, second, final)}) == 1
for step in (first, second, final):
assert re.fullmatch(r"actions/download-artifact@[a-f0-9]{40}", step["uses"])
# Every attempt must fetch and verify the same artifact in this run;
# no pattern, alternate run, or relaxed digest check may substitute it.
assert step["with"] == {
"name": "${{ inputs.name }}",
"path": "${{ inputs.path }}",
"digest-mismatch": "error",
}
@pytest.mark.parametrize("job_name", ["tests", "coverage-merge", "shard-plan", "cross-platform", "native-timings"])
def test_frozen_timing_consumers_retry_required_downloads(ci_test_jobs, job_name):
job = ci_test_jobs[job_name]
downloads = [
step for step in job["steps"]
if step.get("with", {}).get("name") == "shard-timing-input"
and step.get("uses") != "./.github/actions/upload-test-artifact"
]
assert len(downloads) == 1
download = downloads[0]
assert download["uses"] == "./.github/actions/download-test-artifact"
assert not download.get("continue-on-error", False)
assert not job.get("continue-on-error", False)
expected_path = ".vitest/timings" if job_name == "shard-plan" else "gitnexus/.vitest/timings"
assert download["with"] == {"name": "shard-timing-input", "path": expected_path}
assert any(
step.get("uses", "").startswith("actions/checkout@")
for step in job["steps"][:job["steps"].index(download)]
)
def test_shard_plan_retry_cannot_replace_frozen_timing_input(ci_test_jobs):
steps = ci_test_jobs["shard-plan"]["steps"]
restore = next(step for step in steps if step.get("id") == "previous-input")

View file

@ -1016,13 +1016,29 @@ budget stop per cell. This checks telemetry delivery before a larger comparison:
```bash
uv run --locked python -m workflow_bench.diagnostic_experiments \
--tasks workflow_bench/tasks.scenarios.yaml \
--repository /path/to/GitNexus --runtime /path/to/built/GitNexus \
--repository /path/to/tasks-base --runtime /path/to/built/GitNexus \
--harness-sha FULL_HARNESS_SHA --runtime-sha FULL_RUNTIME_SHA \
--model gpt-5.6-sol --effort xhigh --seed 3762 --repeats 1 \
--variants no_graph mcp_eager --task-ids trivial-status-json-alias \
--max-budget-usd 5 --out /tmp/gitnexus-diagnostics-trial
--max-budget-usd 5 --bind-task-dependencies --out /tmp/gitnexus-diagnostics-trial
```
`--repository` must be the checkout built at the task's pinned commit, including
its dependency trees. `--runtime` is the separately built GitNexus candidate.
`--bind-task-dependencies` requires a clean tracked checkout at the task ref and
records the built dependency contents. The trial executor rejects missing bindings,
dirty tracked files, a different HEAD, or dependency drift. Each runner receives
the saved bindings and checks its captured dependencies again before model calls.
The release workflow also runs offline negative and reference grading controls
with those dependency snapshots and the runner's read-only verifier sandbox.
The unmodified source must fail a behavioral assertion; the reference repair
must pass the hidden oracle and TypeScript. A setup crash is not a negative
control. These checks make no model requests.
The recorded task prompt digest includes the conditional MCP environment
instruction. Comparator reuse rejects older raw-prompt hashes and changes to
that instruction, while keeping the two arms under the same task identity.
The runner forwards `--max-budget-usd` to Claude Code and accepts it only for
single-session baseline arms. The default remains uncapped. Budget-stopped
sessions stay failed and retain reported spend; they cannot establish savings
@ -1064,7 +1080,7 @@ new dispatch after failure; the executor never retries or resumes a used plan.
| Task fit and quality ceiling | Per-task cost distribution, solved/failed/missing counts, cost per solved task | Add harder independently validated tasks before claiming a quality improvement at 100% success |
| Order, concurrency, warm caches | Seeded rotated order, one worker and separate ledger per cell | Run matched worker-count/cold-start studies separately; fresh processes do not guarantee cold provider/filesystem caches |
| Retries, provider translation and accounting | CLI retry events; deduplicated success/failure callbacks, native normalized usage, reasoning tokens, proxy durations and estimates | Reconcile with provider billing; do not join concurrent requests to cells by timestamp |
| Setup, indexing and infrastructure | Cell start/finish timestamps, total duration, clone/index-materialization/dependency/MCP-startup/sandbox/agent-and-verification/artifact/cleanup spans | Shared index-build preparation, CPU/RSS, isolated oracle spans and infrastructure prices need separate evidence; do not fold them into model dollars |
| Setup, indexing and infrastructure | Sweep wall time, time before the first cell, dependency preparation, foreground graph setup/waits, cell phases, authored/hidden grading durations | Background graph work can overlap cells; CPU/RSS, workflow provisioning, proxy startup and infrastructure prices need separate evidence; do not fold them into model dollars |
Summarize a runner result file (including failed cells) and optionally its proxy
ledger. Historical release reports with `per_run` rows are also accepted:
@ -1078,6 +1094,15 @@ uv run --locked python -m workflow_bench.cost_diagnostics \
Unknown fields remain null. Distinct model/effort/source/prompt/runtime/loading
cohorts are kept separate. Duplicate exported cell identities are rejected.
Runtime and harness commit SHAs, task prompt digest, and the per-cell CLI budget
survive public export. The legacy evolution `runtime_digest` is optional when
the required commit provenance is present. All-zero CLI usage snapshots are
treated as unavailable; provider-normalized per-request token distributions
give a separate view of context size without guessing from aggregate usage.
When `sweep-timing.json` exists beside the results, the summary includes its
setup measurements. They overlap and must not be added together. Grading
receipts expose duration, exit code, process state, and fixed failure markers;
they never expose hidden-test output. Failure markers are clues, not diagnoses.
Provider response-ID conflicts withhold token totals; missing IDs prevent a
deduplicated total. Failed requests remain in the accounting. Proxy cost is an
estimate, not a provider invoice. The report is descriptive and does not change

View file

@ -13,10 +13,11 @@ from typing import Any
from .provider_usage import NormalizedUsage, UsageSemanticsError, normalize_usage
from .session_diagnostics import CELL_PHASES, public_diagnostics, render_diagnostics
from .verification_diagnostics import public_verification
NUMERIC = ("cost_usd", "duration_s", "cell_duration_s", "num_turns", "diff_insertions", "diff_deletions", "diff_files",
"input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "output_tokens")
COHORT = ("model", "effort", "task_base_sha", "task_prompt_digest", "runtime_digest", "mcp_tool_loading",
COHORT = ("model", "effort", "task_base_sha", "task_prompt_digest", "runtime_sha", "harness_sha", "runtime_digest", "mcp_tool_loading",
"sandbox_dependency_content_digest", "oracle_digest", "max_budget_usd")
REQUEST_METRICS = ("messages_bytes", "tools_bytes", "system_bytes", "messages_count", "tools_count",
"duration_s", "proxy_estimated_cost_usd")
@ -90,6 +91,9 @@ def provider_summary(events: list[dict[str, Any]]) -> dict[str, Any]:
"requests_with_session_id": sum(isinstance(e.get("session_id"), str) and bool(e["session_id"]) for e in unique),
"unique_actual_models": len({e["actual_model"] for e in unique if isinstance(e.get("actual_model"), str)}),
"token_totals": token_totals,
"request_tokens": {field: distribution([
row.get(field) if not conflicts and not unidentified else None for row in normalized
]) for field in token_fields},
"request_metrics": {field: distribution([m.get(field) for m in metrics]) for field in REQUEST_METRICS},
"identity_complete": bool(unique) and not conflicts and unidentified == 0,
"attribution": "ledger_only_no_cell_join",
@ -131,7 +135,15 @@ def build_cost_report(rows: list[dict[str, Any]], provider_events: list[dict[str
"diagnostic_group": len(summaries) + 1,
"arm": arm, "task": task, "cells": len(cells), "solved": solved,
"cohort": dict(zip(COHORT, cohort, strict=True)),
"provenance_complete": all(cohort),
# runtime_digest is a legacy evolution launcher field. Release
# measurements bind the actual runtime and harness commits instead.
"provenance_complete": all(value for field, value in zip(COHORT, cohort, strict=True)
if field != "runtime_digest"),
"verification": {
phase: [public_verification(row.get("verification_diagnostics", {}).get(phase))
for row in cells if isinstance(row.get("verification_diagnostics"), dict)]
for phase in ("authored", "hidden")
},
"quality_missing": sum(type(row.get("resolved")) is not bool for row in cells),
"failed_cells": sum(row.get("ok") is False for row in cells),
"diagnostic_cells": sum(bool(public_diagnostics(row.get("session_diagnostics"))) for row in cells),
@ -197,6 +209,27 @@ def render_markdown(report: dict[str, Any]) -> str:
for field, value in group["cohort"].items()], "",
*table(group["metrics"]), "", "Cell phases (seconds; agent_and_verification includes grading):", "",
*table(group["cell_phases"]), "", "</details>", ""]
lines += ["Grading checks (failure markers are observations, not proven root causes):", "",
"| Check | Passed | Exit code | State | Seconds | Observed failure markers |",
"| --- | --- | --- | --- | ---: | --- |"]
for phase, checks in group["verification"].items():
for check in checks:
markers = ", ".join(field for field in ("assertion_failure", "startup_failure", "permission_failure", "typecheck_failure")
if check.get(field) is True)
lines.append(f"| {phase} | {check.get('passed', 'unknown')} | {check.get('exit_code')} | "
f"{check.get('state', 'unknown')} | {number(check.get('duration_s'))} | {markers or 'none observed'} |")
lines += [""]
timing = report.get("sweep_timing")
if timing:
lines += ["### Runner setup and wall time", "",
f"Complete sweep: {'yes' if timing['complete'] else 'no'}; workers: {number(timing['workers'])}.",
("Times overlap: before-first-cell includes dependency and foreground graph setup. "
"Graph time includes foreground waits; background indexing can overlap cells. "
"Total excludes CLI/proxy startup and report rendering."), "",
"| Measurement | Seconds |", "| --- | ---: |",
*[f"| {field} | {number(timing[field])} |" for field in (
"total_s", "before_first_cell_s", "dependency_setup_s", "foreground_graph_setup_s",
)], ""]
provider = report["provider"]
lines += ["### Provider requests", ""]
if provider is None:
@ -211,6 +244,8 @@ def render_markdown(report: dict[str, Any]) -> str:
"| Provider token field | Observed total |", "| --- | ---: |",
*[f"| {field} | {number(value)} |" for field, value in provider["token_totals"].items()], "",
*table(provider["request_metrics"]), "",
"Provider-reported tokens per request (includes cached input; independent of CLI context snapshots):", "",
*table(provider["request_tokens"]), "",
*provider["limitations"], ""]
lines += [report["tool_markdown"], "", *report["limitations"], ""]
return "\n".join(lines)
@ -265,6 +300,23 @@ def main() -> None:
provider = None
problems += provider_problems
report = build_cost_report(rows, provider)
timing_path = args.results.parent / "sweep-timing.json"
report["sweep_timing"] = None
if timing_path.is_file():
try:
timing = json.loads(timing_path.read_text())
except (OSError, ValueError):
if not args.allow_incomplete:
raise
timing = None
problems.append("Sweep timing file is unreadable.")
if isinstance(timing, dict):
report["sweep_timing"] = {
"complete": timing.get("complete") is True,
**{field: timing.get(field) if _number(timing.get(field)) else None for field in (
"total_s", "before_first_cell_s", "dependency_setup_s", "foreground_graph_setup_s", "workers",
)},
}
if report["provider"] is not None:
report["provider"]["ledger_complete"] = not provider_problems
if provider_problems:

View file

@ -13,7 +13,8 @@ from typing import Any
import yaml
from .runner_tasks import normalized_model_identifier, select_tasks
from .process_control import run_checked
from .runner_tasks import normalized_model_identifier, resolve_task_bindings, select_tasks
from .session_budget import session_budget
VARIANTS = {
@ -103,6 +104,7 @@ def prepare_plan(
return {
"schema": "gitnexus.diagnostic-experiments/v1", "execution": "not_started",
"harness_sha": harness_sha, "runtime_sha": runtime_sha, "seed": seed,
"task_repository": repository,
"model": model, "effort": effort, "repeats": repeats, "workers": 1,
"max_budget_usd_per_cell": max_budget_usd,
"planned_cli_budget_usd": len(cells) * max_budget_usd if max_budget_usd is not None else None,
@ -120,6 +122,19 @@ def prepare_plan(
}
def trial_task_bindings(tasks: list[dict[str, Any]], expected: list[dict[str, Any]] | None = None) -> list[dict[str, Any]]:
"""Pin built dependencies only after checking their tracked source checkout."""
for task in tasks:
repo = str(Path(task["repo"]).resolve())
head = run_checked(["git", "-C", repo, "rev-parse", "HEAD"], timeout=60).stdout_tail.strip()
dirty = run_checked(
["git", "-C", repo, "status", "--porcelain", "--untracked-files=no"], timeout=60,
).stdout_tail.strip()
if head != task["ref"] or dirty:
raise ValueError("trial dependencies require a clean pinned task checkout")
return resolve_task_bindings(tasks, expected)
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--tasks", type=Path, required=True)
@ -134,6 +149,8 @@ def main() -> None:
parser.add_argument("--max-budget-usd", type=float, help="CLI-reported budget stop per cell, not an invoice cap")
parser.add_argument("--variants", nargs="+", choices=VARIANTS, default=list(VARIANTS))
parser.add_argument("--task-ids", nargs="+")
parser.add_argument("--bind-task-dependencies", action="store_true",
help="pin built task dependencies for execution; requires a clean pinned checkout")
parser.add_argument("--out", type=Path, required=True)
args = parser.parse_args()
plan = prepare_plan(
@ -142,6 +159,14 @@ def main() -> None:
model=args.model, effort=args.effort, repeats=args.repeats, seed=args.seed,
variants=args.variants, task_ids=args.task_ids, max_budget_usd=args.max_budget_usd,
)
if args.bind_task_dependencies:
bindings = {}
for cell in plan["cells"]:
tasks = cell["task_document"]["tasks"]
key = json.dumps(tasks, sort_keys=True)
if key not in bindings:
bindings[key] = trial_task_bindings(tasks)
cell["task_bindings"] = bindings[key]
# Refuse overwrite: a previous plan/ledger may already be evidence.
args.out.mkdir(parents=True, exist_ok=False)
root = args.out.resolve()

View file

@ -11,6 +11,8 @@ import subprocess
import sys
from typing import Any
from . import diagnostic_experiments
MODEL = "gpt-5.6-sol"
TASK = "trivial-status-json-alias"
BUDGET_USD = 5.0
@ -66,8 +68,16 @@ def _validated_cells(plan_path: Path, runtime: Path) -> tuple[dict[str, Any], li
tasks = document.get("tasks") if isinstance(document, dict) else None
if not isinstance(tasks, list) or len(tasks) != 1 or not isinstance(tasks[0], dict) or tasks[0].get("id") != TASK:
raise ValueError("trial manifest must contain only the authorized task")
task_repo = tasks[0].get("repo")
if (not isinstance(task_repo, str) or task_repo != plan.get("task_repository")
or _head(Path(task_repo)) != tasks[0].get("ref")):
raise ValueError("task source and dependencies must come from the pinned task checkout")
if output.exists() or output.is_symlink() or ledger.exists() or ledger.is_symlink():
raise ValueError("trial results already exist; refusing to repeat paid work")
bindings = cell.get("task_bindings")
if not isinstance(bindings, list) or len(bindings) != 1 or not isinstance(bindings[0], dict):
raise ValueError("trial plan must pin task dependency bindings before execution")
diagnostic_experiments.trial_task_bindings(tasks, bindings)
return plan, cells
@ -86,7 +96,8 @@ def execute_trial(plan_path: Path, runtime: Path, claude_bin: str) -> int:
stream.write(json.dumps(state, indent=2) + "\n")
failed = False
for cell in cells:
command = [sys.executable, *cell["argv"][4:], "--timeout", "900", "--claude-bin", claude_bin]
command = [sys.executable, *cell["argv"][4:], "--timeout", "900", "--claude-bin", claude_bin,
"--task-bindings-json", json.dumps(cell["task_bindings"])]
item: dict[str, Any] = {"cell_id": cell["cell_id"], "variant": cell["variant"], "status": "started"}
state["cells"].append(item)
receipt.write_text(json.dumps(state, indent=2) + "\n")

View file

@ -0,0 +1,61 @@
"""Offline grading controls using the runner's dependency and sandbox boundaries."""
from __future__ import annotations
import argparse
from pathlib import Path
from typing import Any
from .oracle_assets import ORACLE_ROOT, capture_task_oracle, sanitize_clone_for_hidden_oracles
from .proposer_sandbox import ReadOnlyMount, SandboxError, prepare_sandbox
from .runner import _run_hidden_oracle, _verification_outcome
from .runner_artifacts import make_worktree, run_verify
from .task_assets import stage_task_assets
REFERENCES = {
"trivial-status-json-alias": "trivial-status-json-alias",
"inv-feature-c-include-provenance": "inv-feature-c-include-provenance-flag",
"inv-feature-list-repos-filter": "inv-feature-list-repos-filter",
"cross-module-parse-retry": "cross-module-parse-retry",
}
def check_task_controls(task: dict[str, Any], *, repo: Path, sha: str, parent: Path,
assets: Any, claude_bin: Path, bwrap_bin: Path) -> None:
"""Reject broken setup before spending: base fails assertions, reference passes.
Reference patches and oracle bytes never enter a paid cell. The probe uses
the same immutable dependency snapshot and read-only verifier as the runner.
"""
reference = REFERENCES.get(task["id"])
if reference is None:
raise ValueError(f"no offline grading control for release task {task['id']}")
clone = make_worktree(repo, sha, parent)
sanitize_clone_for_hidden_oracles(clone)
mounts = stage_task_assets(task, repo=repo, clone=clone, snapshot=assets)
snapshot = capture_task_oracle(task)
args = argparse.Namespace(timeout=180)
with prepare_sandbox(clone=clone, claude_bin=claude_bin, bwrap_bin=bwrap_bin,
read_only_mounts=mounts, preflight=False, gitnexus_available=False) as sandbox:
negative: dict[str, Any] = {}
passed, _ = _run_hidden_oracle(snapshot, clone, args, sandbox, diagnostics=negative)
if (passed or negative.get("exit_code") != 1 or not negative.get("assertion_failure")
or negative.get("startup_failure") or negative.get("permission_failure")):
raise SandboxError("negative grading control did not fail on a behavioral assertion")
patch_mount = ReadOnlyMount(ORACLE_ROOT / "reference" / f"{reference}.patch", "/tmp/reference.patch")
applied = run_verify(
"git apply /tmp/reference.patch", clone, 60,
command_prefix=sandbox.command_prefix_for(unshare_network=True, extra_read_only_mounts=(patch_mount,)),
env=sandbox.environment(), require_pid_namespace=True,
)
if not _verification_outcome(applied)[0]:
raise SandboxError("reference patch could not be applied in grading control")
typed = run_verify(
"cd gitnexus && ./node_modules/.bin/tsc --noEmit", clone, 180,
command_prefix=sandbox.command_prefix_for(read_only_workspace=True, unshare_network=True),
env=sandbox.environment(), require_pid_namespace=True,
)
if not _verification_outcome(typed)[0]:
raise SandboxError("reference grading control failed typecheck")
if not _run_hidden_oracle(snapshot, clone, args, sandbox)[0]:
raise SandboxError("reference grading control failed the hidden oracle")

View file

@ -13,11 +13,13 @@ from .process_control import ManagedProcessError, cancellation_scope
from .proposer_sandbox import SandboxError, preflight_bubblewrap, require_claude_sandbox_helpers
from .runner_tasks import resolve_task_bindings, select_tasks
from .runtime_mounts import trusted_gitnexus_runtime_mounts
from .release_controls import check_task_controls
from .sanitized_graph import prepare_sanitized_graph, validate_no_prebuilt_graph_assets
from .task_assets import TaskAssetCache, stage_task_assets
def preflight_release(tasks: list[dict[str, Any]], *, gitnexus_root: Path, claude_bin: Path) -> None:
def preflight_release(tasks: list[dict[str, Any]], *, gitnexus_root: Path, claude_bin: Path,
grading_controls: bool = False) -> None:
"""Exercise the real snapshot/copy path on the same temp filesystem as the runner.
No provider or session code is involved. Graphs are rebuilt by the paid
@ -49,6 +51,10 @@ def preflight_release(tasks: list[dict[str, Any]], *, gitnexus_root: Path, claud
clone = Path(probe)
graph.materialize(clone, sanitized_head=graph.sanitized_head)
stage_task_assets(task, repo=repo, clone=clone, snapshot=assets)
if grading_controls:
check_task_controls(task, repo=repo, sha=sha, parent=Path(directory), assets=assets,
claude_bin=claude_bin, bwrap_bin=bwrap_bin)
print(f"Preflight {task['id']}: negative, reference, and typecheck controls passed", flush=True)
print(f"Preflight {task['id']}: materialization passed", flush=True)
@ -57,6 +63,7 @@ def main() -> None:
parser.add_argument("--tasks", required=True, type=Path)
parser.add_argument("--gitnexus-root", required=True, type=Path)
parser.add_argument("--claude-bin", required=True, type=Path)
parser.add_argument("--grading-controls", action="store_true", help="require offline controls for the release corpus")
args = parser.parse_args()
try:
document = yaml.safe_load(args.tasks.read_text())
@ -64,7 +71,8 @@ def main() -> None:
raise ValueError("task file must contain a tasks list")
tasks, _ = select_tasks(document["tasks"], include_expensive=True)
with cancellation_scope(handle_signals=True):
preflight_release(tasks, gitnexus_root=args.gitnexus_root, claude_bin=args.claude_bin)
preflight_release(tasks, gitnexus_root=args.gitnexus_root, claude_bin=args.claude_bin,
grading_controls=args.grading_controls)
except (ManagedProcessError, OSError, SandboxError, RuntimeError, ValueError, yaml.YAMLError) as exc:
parser.error(str(exc))

View file

@ -31,6 +31,12 @@ ROW_FIELDS = (
"model",
"effort",
"task_base_sha",
"task_prompt_digest",
"runtime_sha",
"harness_sha",
"runtime_digest",
"max_budget_usd",
"mcp_tool_loading",
"oracle_digest",
"sandbox_backend",
"runtime_exposure",

View file

@ -172,6 +172,7 @@ from .runner_sessions import (
sandbox_mcp_config,
sum_sessions,
)
from .verification_diagnostics import verification_metrics
from .runner_tasks import (
normalized_model_identifier,
resolve_task_bindings,
@ -333,6 +334,8 @@ def _run_hidden_oracle(
worktree: Path,
args: argparse.Namespace,
sandbox: SandboxSession,
*,
diagnostics: dict[str, Any] | None = None,
) -> tuple[bool, str]:
"""Stage a captured oracle after the model exits, execute it, then erase it."""
@ -355,22 +358,24 @@ def _run_hidden_oracle(
# credited patch is captured.
oracle_mount = f"{SANDBOX_WORKSPACE}/{mount_name}"
oracle_env[ORACLE_ENV_VAR] = str(stage_root) if host_unsafe else oracle_mount
passed, _output = _verification_outcome(
run_verify(
snapshot.command,
sandbox.clone,
args.timeout,
command_prefix=sandbox.command_prefix_for(
read_only_workspace=True,
unshare_network=True,
extra_read_only_mounts=()
if host_unsafe
else (ReadOnlyMount(source=stage_root, target=oracle_mount),),
),
env=oracle_env,
require_pid_namespace=getattr(sandbox, "require_pid_namespace", True),
)
started = time.monotonic()
result = run_verify(
snapshot.command,
sandbox.clone,
args.timeout,
command_prefix=sandbox.command_prefix_for(
read_only_workspace=True,
unshare_network=True,
extra_read_only_mounts=()
if host_unsafe
else (ReadOnlyMount(source=stage_root, target=oracle_mount),),
),
env=oracle_env,
require_pid_namespace=getattr(sandbox, "require_pid_namespace", True),
)
if diagnostics is not None:
diagnostics.update(verification_metrics(result, time.monotonic() - started))
passed, _output = _verification_outcome(result)
# Candidate code executes in this process. Never persist its stdout
# or stderr: it can read the mounted hidden test bytes and print them.
return passed, "hidden oracle passed" if passed else "hidden oracle failed"
@ -451,6 +456,13 @@ def _unchanged(value: Any) -> Any:
return value
MCP_REPOSITORY_PROMPT = (
"\n\nBenchmark environment: the isolated GitNexus repository is registered as "
"benchmark-target. Use that repo name, or omit repo to use the default. "
"Repository aliases in checked-in guidance refer to the original checkout."
)
def run_arm(
arm: str,
task: dict[str, Any],
@ -467,6 +479,8 @@ def run_arm(
mcp_config_json: str | None = None,
) -> dict[str, Any]:
sessions: list[dict[str, Any]] = []
if arm != "baseline_nomcp":
task = {**task, "prompt": task["prompt"] + MCP_REPOSITORY_PROMPT}
environment_builder = getattr(sandbox, "environment", build_sandbox_environment)
host_text = getattr(sandbox, "host_text", _unchanged)
host_path = getattr(sandbox, "host_path", lambda value: str(value))
@ -709,20 +723,23 @@ def run_arm(
verify_mounts = (
ReadOnlyMount(source=review_artifact.parent, target=SANDBOX_REVIEW_OUTPUT),
)
authored_tests_passed, authored_test_output = _verification_outcome(
run_verify(
task["verify"],
worktree,
args.timeout,
command_prefix=sandbox.command_prefix_for(
read_only_workspace=True,
unshare_network=True,
extra_read_only_mounts=verify_mounts,
),
env=verify_env,
require_pid_namespace=getattr(sandbox, "require_pid_namespace", True),
)
verification_started = time.monotonic()
authored_result = run_verify(
task["verify"],
worktree,
args.timeout,
command_prefix=sandbox.command_prefix_for(
read_only_workspace=True,
unshare_network=True,
extra_read_only_mounts=verify_mounts,
),
env=verify_env,
require_pid_namespace=getattr(sandbox, "require_pid_namespace", True),
)
record["verification_diagnostics"] = {
"authored": verification_metrics(authored_result, time.monotonic() - verification_started),
}
authored_tests_passed, authored_test_output = _verification_outcome(authored_result)
review_score: dict[str, Any] | None = None
if arm in ("review", "ce_review"):
try:
@ -751,12 +768,15 @@ def run_arm(
)
oracle_output = "hidden review labels matched" if oracle_passed else "hidden review labels not fully matched"
else:
hidden_diagnostics: dict[str, Any] = {}
oracle_passed, oracle_output = _run_hidden_oracle(
oracle_snapshot,
worktree,
args,
sandbox,
diagnostics=hidden_diagnostics,
)
record["verification_diagnostics"]["hidden"] = hidden_diagnostics
record["authored_tests_passed"] = authored_tests_passed
record["authored_test_output"] = authored_test_output
record["oracle_passed"] = oracle_passed
@ -836,7 +856,10 @@ def task_prompt_digest(task: Mapping[str, Any]) -> str:
stop rows matching, or match rows that should not.
"""
return hashlib.sha256(str(task["prompt"]).encode()).hexdigest()
# Bind the conditional harness instruction as well as the task text. Both
# arms retain the same experiment identity; old raw-prompt hashes expire.
payload = {"task": str(task["prompt"]), "mcp_environment": MCP_REPOSITORY_PROMPT}
return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
# A sustained upstream outage shows up as a run of session/infra/cleanup
@ -1489,6 +1512,11 @@ def run_cell(ctx: TaskCellContext, run_idx: int, arm: str) -> dict[str, Any]:
"run": run_idx,
"sandbox_backend": ctx.sandbox_backend,
"runtime_exposure": runtime_exposure,
"max_budget_usd": getattr(args, "max_budget_usd", None),
"model": args.model,
"effort": args.effort,
"task_base_sha": ctx.task_sha,
"task_prompt_digest": task_prompt_digest(task),
**getattr(args, "measurement_revisions", {}),
"mcp_tool_loading": (
getattr(args, "mcp_tool_loading", "eager") if execution_arm == "baseline"
@ -2566,6 +2594,11 @@ def _run_sweep(
total_cells = len(tasks) * args.runs * len(args.arms)
started_cells = 0
sweep_started = time.monotonic()
timing: dict[str, Any] = {"complete": False, "workers": args.workers, "total_s": None,
"before_first_cell_s": None, "dependency_setup_s": None,
"foreground_graph_setup_s": 0.0}
timing_path = out_dir / "sweep-timing.json"
timing_path.write_text(json.dumps(timing) + "\n")
with (
tempfile.TemporaryDirectory(prefix="wfbench-trees-") as trees,
TaskAssetCache(Path(trees) / ".task-assets") as task_asset_cache,
@ -2603,6 +2636,8 @@ def _run_sweep(
except (OSError, SandboxError, ValueError) as exc:
asset_snapshot_errors[str(_task["id"])] = exc
timing["dependency_setup_s"] = time.monotonic() - sweep_started
timing_path.write_text(json.dumps(timing) + "\n")
reuse_source = args.reuse_results.expanduser().resolve() if args.reuse_results is not None else None
reusable_rows: dict[tuple[str, str, int], dict[str, Any]] = {}
if reuse_source is not None:
@ -2695,12 +2730,15 @@ def _run_sweep(
asset_snapshot = asset_snapshots.get(str(task["id"]))
asset_snapshot_error: BaseException | None = asset_snapshot_errors.get(str(task["id"]))
graph_key = (str(repo), task_sha)
graph_started = time.monotonic()
if graph_prefetch is not None and graph_prefetch.key == graph_key:
_join_graph_prefetch()
if paid_cells:
ensure_task_graph(
task=task, repo=repo, task_sha=task_sha, graph_key=graph_key, env=graph_env
)
timing["foreground_graph_setup_s"] += time.monotonic() - graph_started
timing_path.write_text(json.dumps(timing) + "\n")
graph_snapshot = graph_env.graph_snapshots.get(graph_key)
graph_snapshot_error = graph_env.graph_snapshot_errors.get(graph_key)
clone_template, template_head = graph_env.clone_templates.get(graph_key, (None, None))
@ -2728,6 +2766,9 @@ def _run_sweep(
def announce(run_idx: int, arm: str) -> None:
nonlocal started_cells
if timing["before_first_cell_s"] is None:
timing["before_first_cell_s"] = time.monotonic() - sweep_started
timing_path.write_text(json.dumps(timing) + "\n")
started_cells += 1
print(
f"[{task['id']}][{arm}][run {run_idx}] starting "
@ -2792,6 +2833,8 @@ def _run_sweep(
finally:
_join_graph_prefetch()
timing.update(complete=not outage_tripped and not cancel_event.is_set(), total_s=time.monotonic() - sweep_started)
timing_path.write_text(json.dumps(timing) + "\n")
selection_report = [
"## Run provenance",
"",

View file

@ -356,6 +356,8 @@ GITNEXUS_READ_ONLY_TOOLS = (
"mcp__gitnexus__list_repos",
"mcp__gitnexus__query",
"mcp__gitnexus__context",
"mcp__gitnexus__grep",
"mcp__gitnexus__read_file",
"mcp__gitnexus__check",
"mcp__gitnexus__impact",
"mcp__gitnexus__explain",

View file

@ -16,6 +16,7 @@ from pathlib import PurePosixPath
from typing import Any
from .workload_diagnostics import COUNT_FIELDS, TOKEN_FIELDS, public_workload, workload_metrics
from .verification_diagnostics import public_verification
SCHEMA = "gitnexus.session-diagnostics/v1"
MAX_EVENTS = 100_000
@ -23,7 +24,7 @@ MAX_CALLS = 2048
CELL_PHASES = ("validation", "clone", "graph_materialize", "dependencies", "mcp_startup",
"sandbox_setup", "agent_and_verification", "artifacts", "cleanup")
COMMANDS = frozenset({
"list_repos", "query", "context", "check", "impact", "explain", "pdg_query",
"list_repos", "query", "context", "grep", "read_file", "check", "impact", "explain", "pdg_query",
"route_map", "tool_map", "shape_check", "api_impact", "trace", "detect_changes",
})
TOOLS = frozenset({
@ -364,6 +365,12 @@ def public_diagnostics(value: Any) -> list[dict[str, Any]]:
def public_cell_diagnostics(row: dict[str, Any]) -> dict[str, Any]:
"""Shared publication boundary for release and optional-arm artifacts."""
safe = {}
verification = row.get("verification_diagnostics")
if isinstance(verification, dict):
safe["verification_diagnostics"] = {
phase: public_verification(verification[phase])
for phase in ("authored", "hidden") if phase in verification
}
if "session_diagnostics" in row:
safe["session_diagnostics"] = public_diagnostics(row["session_diagnostics"])
if "cell_duration_s" in row:

View file

@ -0,0 +1,41 @@
"""Bounded verifier evidence without publishing candidate or hidden-test output."""
from __future__ import annotations
from typing import Any
from .runner_artifacts import VerificationResult
# These are observed text markers, not authoritative diagnoses. Never publish
# matched text: candidate code can print source, credentials, or hidden tests.
MARKERS = {
"assertion_failure": ("AssertionError",),
"startup_failure": ("Failed Suites", "Startup Error", "Unhandled Errors", "Cannot find module"),
"permission_failure": ("EACCES", "EROFS", "Permission denied", "Failed to create Vitest API token"),
"typecheck_failure": ("error TS",),
}
def verification_metrics(result: VerificationResult | tuple[bool, str], elapsed: float) -> dict[str, Any]:
passed, output = result
return {
"passed": passed,
"duration_s": elapsed,
"exit_code": result.process.returncode if isinstance(result, VerificationResult) else None,
"state": result.process.state if isinstance(result, VerificationResult) else "unknown",
**{field: any(marker in output for marker in markers) for field, markers in MARKERS.items()},
}
def public_verification(value: Any) -> dict[str, Any]:
if not isinstance(value, dict):
return {}
code, elapsed, state = value.get("exit_code"), value.get("duration_s"), value.get("state")
return {
"exit_code": code if type(code) is int and -255 <= code <= 255 else None,
"duration_s": elapsed if type(elapsed) in (int, float) and 0 <= elapsed <= 10**12 else None,
"state": state if state in ("exited", "timeout", "cancelled", "input-failure", "spawn-failure", "forced-kill",
"ownership-failure", "reap-failure", "cleanup-failure", "unknown") else "unknown",
**{field: value.get(field) if type(value.get(field)) is bool else None
for field in ("passed", *MARKERS)},
}

View file

@ -211,6 +211,11 @@ def workload_metrics(
counts["edits"] += 1
counts["edits_after_verification"] += verified
counts["usage_snapshots"] = len(usage)
# Some CLI/provider adapters emit all-zero placeholders for completed
# assistant turns. They are not evidence of an empty model context.
usage = [u if any(type(u.get(f)) is int and u[f] > 0 for f in (
"input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens", "output_tokens",
)) else {"event_index": u["event_index"]} for u in usage]
input_fields = ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens")
totals = [sum(u[f] for f in input_fields)
if all(type(u.get(f)) is int and u[f] >= 0 for f in input_fields) else None for u in usage]

View file

@ -87,6 +87,7 @@ Generates repository documentation from the knowledge graph using an LLM. HTTP p
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
| `--timeout <seconds>` | LLM request timeout in seconds (default: disabled) |
| `--retries <n>` | Max LLM retry attempts per request (default: 3) |
| `--max-completion-tokens <n>` | Max completion tokens per LLM request (default: 16384). `GITNEXUS_MAX_COMPLETION_TOKENS` overrides `maxCompletionTokens` in `~/.gitnexus/config.json`; the flag overrides both. |
| `--lang <lang>` | Output language for generated documentation (e.g. english, chinese, spanish, japanese) |
| `--gist` | Publish wiki as a public GitHub Gist |

View file

@ -5084,9 +5084,9 @@
}
},
"node_modules/follow-redirects": {
"version": "1.16.1",
"resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.1.tgz",
"integrity": "sha512-FNvFGzoMLWmE6Yj9spb/zjd7yiNCHiAW9/Tg9CXrQ8wuu32HtlJOwWO11OJafl5FfY3DxTdQ0vj42zU1kvv5jg==",
"version": "1.16.2",
"resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.2.tgz",
"integrity": "sha512-/kVP2U8z596Ia0gwFrwyIeo74ta5aVmSeU1FfAUMAmcEP5EP7zydmag3SLiN64NaRKef3lxsq7i/g7ltJQDGow==",
"funding": [
{
"type": "individual",

View file

@ -29,10 +29,13 @@ candidate. Without `--check`, `--sessions 1 --rounds 1` is a smoke run and canno
establish a performance verdict. For an identical-code control, point both roots
at the same build. Do not discard slow samples or rerun until a check turns green.
The candidate indexes one fixed generated repository containing 32 short and 32
oversized TypeScript functions. Both servers read that same index. Index creation
is outside the timing window. Schemas must be compatible; an incompatible base
fails explicitly. Corpus generation and dependency installation use no model.
Both runtimes index the same fixed generated repository containing 32 short and
32 oversized TypeScript functions. Each server uses its own index and registry,
so engine upgrades can compare different native storage formats. Index creation
is outside the timing window. Both indexes must be complete and their responses
must pass the parity checks below. The report retains both indexes' metadata in
`indexes`; `index` remains the candidate metadata for existing report consumers.
Corpus generation and dependency installation use no model.
Eight fresh server pairs each run a warmup cycle and five measured rounds.
Request order alternates between baseline and candidate. Workloads cover small
@ -44,7 +47,9 @@ first query are recorded separately. Filesystem caches are not flushed.
- Response identities, order and diagnostics must agree; timing, guidance and
source representation are excluded from query equality. Indexed context source
must agree. At least ten known matches must survive each nonempty query.
must agree. Each staleness receipt timestamp must match its own index metadata;
only that timestamp is excluded from cross-runtime staleness equality. At least
ten known matches must survive each nonempty query.
- Candidate query source cannot exceed 16,000 Unicode characters, cannot disappear
entirely, and large previews must announce truncation. Context must retain the
original indexed snippet (the indexer separately caps long function snippets).

View file

@ -60,15 +60,12 @@ const runtimes = Object.fromEntries(
}),
);
const repo = path.join(out, 'repo');
const index = path.join(out, 'index');
const env = {
PATH: process.env.PATH,
HOME: process.env.HOME,
LANG: 'C.UTF-8',
TZ: 'UTC',
...(process.env.LD_LIBRARY_PATH ? { LD_LIBRARY_PATH: process.env.LD_LIBRARY_PATH } : {}),
GITNEXUS_HOME: path.join(out, 'home'),
GITNEXUS_STORAGE_PATH: index,
GITNEXUS_SHARED_STORE: 'off',
GITNEXUS_MEMORY: 'off',
GITNEXUS_CONTENT_RETENTION: 'full',
@ -76,6 +73,16 @@ const env = {
GITNEXUS_MCP_READ_ONLY: '1',
GITNEXUS_LBUG_EXTENSION_INSTALL: 'load-only',
};
const runtimeEnvs = Object.fromEntries(
['baseline', 'candidate'].map((variant) => [
variant,
{
...env,
GITNEXUS_HOME: path.join(out, 'home', variant),
GITNEXUS_STORAGE_PATH: path.join(out, 'index', variant),
},
]),
);
const queries = [
{ name: 'small_source', symbol: 'lookupSmallSource', source: true },
{ name: 'small_metadata', symbol: 'lookupSmallSource', source: false },
@ -109,7 +116,8 @@ function canonical(value) {
}
function inspect(response, entry, variant) {
assert(!response.isError, `MCP error in ${entry.name}`);
if (response.isError)
assert.fail(`MCP error in ${variant}/${entry.name}: ${JSON.stringify(response)}`);
if (entry.tool === 'tools/list') {
for (const name of ['query', 'context'])
assert(
@ -128,6 +136,12 @@ function inspect(response, entry, variant) {
!body.error && !body.partial,
`Incomplete ${variant}/${entry.name} response: ${JSON.stringify({ error: body.error, partial: body.partial, warning: body.warning })}`,
);
// Separate builds have different receipt timestamps. Validate each against its
// own index before excluding that timestamp from cross-runtime parity.
if (body.staleness) {
assert.equal(body.staleness.indexedAt, report.indexes[variant].indexedAt);
delete body.staleness.indexedAt;
}
const rows = entry.tool === 'query' ? [...body.process_symbols, ...body.definitions] : [];
if (entry.tool === 'query') {
if (entry.name === 'empty') assert.equal(rows.length, 0);
@ -185,7 +199,7 @@ async function open(variant, clients) {
command: process.execPath,
args: [runtimes[variant].cli, 'mcp'],
cwd: repo,
env,
env: runtimeEnvs[variant],
stderr: 'pipe',
});
const stderr = fs.createWriteStream(path.join(out, `${variant}.log`), { flags: 'a' });
@ -288,22 +302,33 @@ try {
execFileSync('git', args, { cwd: repo, env: gitEnv, stdio: 'pipe' });
}
report.fixtureSha256 = hash(JSON.stringify(source));
report.indexes = {};
const log = fs.openSync(path.join(out, 'index.log'), 'wx');
try {
execFileSync(process.execPath, [runtimes.candidate.cli, 'analyze', repo, '--index-only'], {
cwd: repo,
env,
stdio: ['ignore', log, log],
});
// Native storage formats can differ across engine upgrades. Each runtime
// builds its own index from the same fixture; response parity is checked below.
for (const variant of ['baseline', 'candidate']) {
const runtimeEnv = runtimeEnvs[variant];
fs.writeSync(log, `\n${variant} index (${runtimes[variant].sha})\n`);
execFileSync(process.execPath, [runtimes[variant].cli, 'analyze', repo, '--index-only'], {
cwd: repo,
env: runtimeEnv,
stdio: ['ignore', log, log],
});
const metadata = JSON.parse(
fs.readFileSync(path.join(runtimeEnv.GITNEXUS_STORAGE_PATH, 'gitnexus.json'), 'utf8'),
);
report.indexes[variant] = metadata;
assert(
metadata.stats.nodes >= 128 && metadata.stats.files === 64,
`Incomplete ${variant} fixture index`,
);
assert.equal(metadata.stats.embeddings ?? 0, 0, 'Benchmark must not generate embeddings');
}
} finally {
fs.closeSync(log);
}
report.index = JSON.parse(fs.readFileSync(path.join(index, 'gitnexus.json'), 'utf8'));
assert(
report.index.stats.nodes >= 128 && report.index.stats.files === 64,
'Incomplete fixture index',
);
assert.equal(report.index.stats.embeddings ?? 0, 0, 'Benchmark must not generate embeddings');
report.index = report.indexes.candidate; // Preserve the existing report field.
for (let session = 0; session < sessions; session++) {
const clients = {};
try {

View file

@ -172,7 +172,7 @@ export function formatReport(report) {
Base \`${report.runtimes.baseline.sha}\`; candidate \`${report.runtimes.candidate.sha}\`.
${report.sessions} fresh process pairs × ${report.rounds} rounds. Real MCP stdio, one shared keyword-search index, alternating requests. No model calls.
${report.sessions} fresh process pairs × ${report.rounds} rounds. Real MCP stdio, the same source fixture indexed by each runtime, alternating requests. No model calls.
| Workload | Median ms, base → candidate | p95 ms, base → candidate | Paired change (95% interval) | Assessment |
| --- | ---: | ---: | --- | --- |

View file

@ -23,7 +23,7 @@
"hasInstallScript": true,
"license": "PolyForm-Noncommercial-1.0.0",
"dependencies": {
"@ladybugdb/core": "0.21.1",
"@ladybugdb/core": "0.22.0",
"@modelcontextprotocol/sdk": "^1.0.0",
"@scarf/scarf": "^1.4.0",
"busboy": "^1.6.0",
@ -34,7 +34,7 @@
"express": "^5.2.1",
"express-rate-limit": "^8.4.1",
"fast-xml-parser": "^5.11.1",
"glob": "^13.0.6",
"glob": "^14.0.2",
"graphology": "^0.26.0",
"graphology-indices": "^0.17.0",
"graphology-utils": "^2.3.0",
@ -1719,6 +1719,12 @@
"node": ">=18.0.0"
}
},
"node_modules/@isaacs/nonrecursive-glob-match": {
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/@isaacs/nonrecursive-glob-match/-/nonrecursive-glob-match-1.0.3.tgz",
"integrity": "sha512-SI7kyKHq4XXDRozw+r9GlRZkia1ZkFrpLW98r2IC2Bpr8YkFGE3fvjzmxCG0x78A++69HmDNrDvSMYBZmHGpKA==",
"license": "BlueOak-1.0.0"
},
"node_modules/@jridgewell/gen-mapping": {
"version": "0.4.0-beta.0",
"resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.4.0-beta.0.tgz",
@ -1759,9 +1765,9 @@
}
},
"node_modules/@ladybugdb/core": {
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core/-/core-0.21.1.tgz",
"integrity": "sha512-G0LWyn/dIqX9yHlyjpR12Rvou2o1dvCB9EkuzGa5ykCYbzur8EQhRUbi4fw3FlbckWvR6rK/tVbnFpBcRLwiHg==",
"version": "0.22.0",
"resolved": "https://registry.npmjs.org/@ladybugdb/core/-/core-0.22.0.tgz",
"integrity": "sha512-kEFtewqyRUk4rQNq2DA5xPgIyC2cOI8PhTixqz0sOhG6/BZ3hhoAP9RkYm0NkcAfCSH3SXs1varNGuccqPcapA==",
"hasInstallScript": true,
"license": "MIT",
"dependencies": {
@ -1770,17 +1776,17 @@
"node-addon-api": "^6.0.0"
},
"optionalDependencies": {
"@ladybugdb/core-darwin-arm64": "0.21.1",
"@ladybugdb/core-darwin-x64": "0.21.1",
"@ladybugdb/core-linux-arm64": "0.21.1",
"@ladybugdb/core-linux-x64": "0.21.1",
"@ladybugdb/core-win32-x64": "0.21.1"
"@ladybugdb/core-darwin-arm64": "0.22.0",
"@ladybugdb/core-darwin-x64": "0.22.0",
"@ladybugdb/core-linux-arm64": "0.22.0",
"@ladybugdb/core-linux-x64": "0.22.0",
"@ladybugdb/core-win32-x64": "0.22.0"
}
},
"node_modules/@ladybugdb/core-darwin-arm64": {
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-arm64/-/core-darwin-arm64-0.21.1.tgz",
"integrity": "sha512-TEFYNqBdbIojf1t29p3esgRhMDm56lD5eK91dwWFZJTVWAZoGXn+yLKs0NUQgj3lW2ZquuRTLZGglPhFEsDL1Q==",
"version": "0.22.0",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-arm64/-/core-darwin-arm64-0.22.0.tgz",
"integrity": "sha512-UE7UnM/Stb/wDyk/1Jl6BgZOl9KmyBr2EVfiASeLmRka09RKlSI6t5/cVu5j7v0qdJzvi/Csg0CP+lhWNNMurg==",
"cpu": [
"arm64"
],
@ -1791,9 +1797,9 @@
]
},
"node_modules/@ladybugdb/core-darwin-x64": {
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-x64/-/core-darwin-x64-0.21.1.tgz",
"integrity": "sha512-w9p3oKrqeMOeWpX3xdCc/hQJHfrZtpB9We+Ir+0qyls68dSQoeXXR1GZYzzTElOtxr4OM5USwYbVyxADx+CMZg==",
"version": "0.22.0",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-x64/-/core-darwin-x64-0.22.0.tgz",
"integrity": "sha512-VM4yiEVTNQel4Dz5cO9Rmc/NBiBWIsBxwMnD3MfSl9gZGGSoLTHa9JDD1RcDJoQ2tZvvXtQMjw5q6E7tnYYyAw==",
"cpu": [
"x64"
],
@ -1804,9 +1810,9 @@
]
},
"node_modules/@ladybugdb/core-linux-arm64": {
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-arm64/-/core-linux-arm64-0.21.1.tgz",
"integrity": "sha512-TodWmzOHxmmKvXXo9buBXGeyolxf/NqBUbo/LcR/tuMViKhGH8TBzIXi8DfVVwmsJ+CQCU065TvXgv2JoHAlZg==",
"version": "0.22.0",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-arm64/-/core-linux-arm64-0.22.0.tgz",
"integrity": "sha512-54K+vxXxQkpxnY6v6nBTPdSY4g9OEoKjXt2PxzRLnoNyZ1OMERxWiwaFLr4jAc5HHgpA3jHLIAvkaY2RSnDaWA==",
"cpu": [
"arm64"
],
@ -1817,9 +1823,9 @@
]
},
"node_modules/@ladybugdb/core-linux-x64": {
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-x64/-/core-linux-x64-0.21.1.tgz",
"integrity": "sha512-hCcLYv8ds0x4fkTaRkuc4f75KLdH9e0EV51ne6uBNdQSY7kyc0RgSoUG3utUGfFDMMkfgIJAeIxQY4ck9jQiXg==",
"version": "0.22.0",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-x64/-/core-linux-x64-0.22.0.tgz",
"integrity": "sha512-ZUbkNmRTjMb16XBPJSCkdNCW4up30jHpDzn9fn6qifg50XnkUQ3eje200EyrdIjd/LLYi9d/VG72mMRW7+cQTA==",
"cpu": [
"x64"
],
@ -1830,9 +1836,9 @@
]
},
"node_modules/@ladybugdb/core-win32-x64": {
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-win32-x64/-/core-win32-x64-0.21.1.tgz",
"integrity": "sha512-nBS1XSRJfpexdlhkezmEiRtkUt2qEDp4zBjIhH+oxgRdD7UsRz1Jyit8foJuZAmUsoQGukN5LO+YeyDU2WZTyA==",
"version": "0.22.0",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-win32-x64/-/core-win32-x64-0.22.0.tgz",
"integrity": "sha512-A7XW4cQYXQjfizF+yook55fSppdF07vUzwhi9d3ER1Z1CnkrzmECAF5DIwaDQ+jFAgwUCCEcJ7kQ9HrnYtZ6Zg==",
"cpu": [
"x64"
],
@ -4415,14 +4421,30 @@
"link": true
},
"node_modules/glob": {
"version": "13.0.6",
"resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz",
"integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==",
"version": "14.0.2",
"resolved": "https://registry.npmjs.org/glob/-/glob-14.0.2.tgz",
"integrity": "sha512-vfMgTR2djMHPUchsJMLpZlYQvtjVL+mHpEr5wPpoCbQs2vr/FBNK+3Gnl9Ara1DSs4Aeg4eG9HiADb5/rkY/ZA==",
"license": "BlueOak-1.0.0",
"dependencies": {
"minimatch": "^10.2.2",
"minimatch": "^11.0.0",
"minipass": "^7.1.3",
"path-scurry": "^2.0.2"
"path-scurry": "^3.0.0"
},
"engines": {
"node": "18 || 20 || >=22"
},
"funding": {
"url": "https://github.com/sponsors/isaacs"
}
},
"node_modules/glob/node_modules/minimatch": {
"version": "11.0.3",
"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-11.0.3.tgz",
"integrity": "sha512-iny/40PEGkNJQ5/Pv6z3nm6FbRAby32GeZRjCUJk2WnNDbgPSTcdI+DDvLqsgBdD4cD5sMtMheqPPnehCCa8Nw==",
"license": "BlueOak-1.0.0",
"dependencies": {
"@isaacs/nonrecursive-glob-match": "^1.0.3",
"brace-expansion": "^5.0.12"
},
"engines": {
"node": "18 || 20 || >=22"
@ -5490,6 +5512,7 @@
"version": "10.2.4",
"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz",
"integrity": "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==",
"dev": true,
"license": "BlueOak-1.0.0",
"dependencies": {
"brace-expansion": "^5.0.2"
@ -5845,9 +5868,9 @@
}
},
"node_modules/path-scurry": {
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
"integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==",
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-3.0.0.tgz",
"integrity": "sha512-1pTbQqH1wIwMi/eleQ5leFTTCkzFsPcgXNjwOA8YGGW/W4/kHT3dssE7Z6NH+zuqNLOzOB0uaD61yl7cAcVhgg==",
"license": "BlueOak-1.0.0",
"dependencies": {
"lru-cache": "^11.0.0",

View file

@ -81,7 +81,7 @@
"version": "node scripts/sync-plugin-manifests.mjs"
},
"dependencies": {
"@ladybugdb/core": "0.21.1",
"@ladybugdb/core": "0.22.0",
"@modelcontextprotocol/sdk": "^1.0.0",
"@scarf/scarf": "^1.4.0",
"busboy": "^1.6.0",
@ -92,7 +92,7 @@
"express": "^5.2.1",
"express-rate-limit": "^8.4.1",
"fast-xml-parser": "^5.11.1",
"glob": "^13.0.6",
"glob": "^14.0.2",
"graphology": "^0.26.0",
"graphology-indices": "^0.17.0",
"graphology-utils": "^2.3.0",

View file

@ -164,6 +164,7 @@ const PLATFORM_LOGIC = [
// N-API addon which has known platform-specific behavior (Windows
// file-lock lag after close, macOS N-API destructor segfaults)
const LBUG_NATIVE = [
'test/integration/dangling-owner-edges.test.ts',
'test/integration/impact-private-type-file-seed.test.ts',
'test/integration/impact-private-type-source.test.ts',
// Inline-handler findings must survive native persistence and cold explain
@ -208,12 +209,15 @@ const LBUG_NATIVE = [
'test/integration/lbug-orphan-sidecar-recovery.test.ts',
'test/integration/lbug-interrupted-checkpoint-recovery.test.ts',
'test/integration/lbug-checkpoint-accounting.test.ts',
'test/integration/lbug-rel-copy-page-padding.test.ts',
'test/integration/lbug-incremental-search.test.ts',
// Retained identities and reader metadata must agree on every native platform.
'test/integration/incremental-method-integrity.test.ts',
'test/integration/go-incremental-method-owners.test.ts',
'test/integration/query-symbol-integrity.test.ts',
'test/integration/mcp-index-generation.test.ts',
// A real refresh worker must preserve active readers or report native contention.
'test/integration/mcp-refresh-index-e2e.test.ts',
'test/integration/fts-repair-warm-session.test.ts',
'test/unit/lbug-pool-pinning.test.ts',
'test/unit/hybrid-search.test.ts',

View file

@ -0,0 +1,321 @@
/**
* Reproducible scaling probe for the per-file owner-edge guard.
*
* Run alone, after a build, from gitnexus/:
* node --expose-gc --import tsx scripts/owner-edge-guard-scaling.ts > /tmp/owner-edge-scaling.json
* --operations-only skips timings; --sizes=1024,2048,... --samples=11 --warmup=3 override defaults.
*
* Timings include guard lifecycle and appending preconstructed rows, excluding
* fixture creation, prefix copies, assertions, and explicit GC. Prefix-isolation
* timings call the guard directly on a fixed 16-member slice. Proxy counters run
* separately: they are deterministic regression checks, never timed thresholds.
*/
import assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
import { readFileSync } from 'node:fs';
import { arch, cpus, platform, release } from 'node:os';
import { performance } from 'node:perf_hooks';
import { parseArgs } from 'node:util';
import { SupportedLanguages } from 'gitnexus-shared';
import {
createOwnerEdgeGuard,
dropDanglingInFileOwnerEdges,
} from '../src/core/ingestion/workers/owner-edge-guard.js';
import type { ParseWorkerResult } from '../src/core/ingestion/workers/parse-worker.js';
const source = readFileSync(
new URL('../src/core/ingestion/workers/owner-edge-guard.ts', import.meta.url),
);
type Slice = Pick<ParseWorkerResult, 'nodes' | 'relationships'>;
type Rel = Slice['relationships'][number];
type Shape = 'member-free' | 'clean' | 'dangling' | 'predefined' | 'duplicate' | 'owner-last';
type FileFixture = Slice & { path: string; expected: Rel[] };
type Reads = { nodes: number; relationships: number; writes: number };
const { values } = parseArgs({
options: {
sizes: { type: 'string', default: '1024,2048,4096,8192,16384,32768,65536' },
samples: { type: 'string', default: '11' },
warmup: { type: 'string', default: '3' },
'operations-only': { type: 'boolean', default: false },
},
});
const sizes = values.sizes.split(',').map(Number);
const samples = Number(values.samples);
const warmup = Number(values.warmup);
assert(
sizes.length >= 2 &&
sizes.every((n, i) => Number.isSafeInteger(n) && n > 0 && (!i || n > sizes[i - 1])),
);
assert(Number.isSafeInteger(samples) && samples >= 3);
assert(Number.isSafeInteger(warmup) && warmup >= 1);
const edge = (type: Rel['type'], sourceId: string, targetId: string): Rel => ({
id: `${type}:${sourceId}->${targetId}`,
sourceId,
targetId,
type,
confidence: 1,
reason: '',
});
function fixture(shape: Shape, count: number, file: number): FileFixture {
// Fixed-width ids keep the string-length dimension constant across sizes.
const path = `src/file-${String(file).padStart(8, '0')}.ts`;
const owner = `Class:${path}:Owner`;
const result: FileFixture = { path, nodes: [], relationships: [], expected: [] };
const addNode = (id: string, label: string): void => {
result.nodes.push({
id,
label,
properties: {
name: id,
filePath: path,
startLine: 0,
endLine: 0,
language: SupportedLanguages.TypeScript,
isExported: false,
},
});
};
if (shape === 'clean') addNode(owner, 'Class');
for (let i = 0; i < count; i++) {
const target = `Method:${path}:member-${String(i).padStart(8, '0')}`;
const defined = edge('DEFINES', `File:${path}`, target);
const member = edge(i % 2 ? 'HAS_PROPERTY' : 'HAS_METHOD', owner, target);
addNode(target, 'Method');
if (shape === 'member-free' || shape === 'predefined') result.relationships.push(defined);
if (shape !== 'member-free') result.relationships.push(member);
if (shape === 'duplicate') result.relationships.push(edge('HAS_PROPERTY', owner, target));
result.expected.push(shape === 'clean' || shape === 'owner-last' ? member : defined);
}
if (shape === 'owner-last') addNode(owner, 'Class');
return result;
}
function files(shape: Shape, count: number, perFile: number): FileFixture[] {
const result: FileFixture[] = [];
for (let i = 0; i < count; i += perFile)
result.push(fixture(shape, Math.min(perFile, count - i), i / perFile));
return result;
}
function append(target: Slice, file: Slice): void {
for (const node of file.nodes) target.nodes.push(node);
for (const rel of file.relationships) target.relationships.push(rel);
}
function verify(result: Slice, expected: Rel[], nodeCount: number): void {
assert.equal(result.nodes.length, nodeCount);
assert.deepEqual(result.relationships, expected);
}
/** Count numeric array accesses only while the production guard runs. */
function operations(input: FileFixture[], prefix: Slice): Reads {
const raw: Slice = { nodes: prefix.nodes.slice(), relationships: prefix.relationships.slice() };
let nodeStart = raw.nodes.length;
let relStart = raw.relationships.length;
const reads: Reads = { nodes: 0, relationships: 0, writes: 0 };
const watched = <T>(array: T[], kind: 'nodes' | 'relationships'): T[] =>
new Proxy(array, {
get(target, property, receiver) {
if (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property)) {
assert(
Number(property) >= (kind === 'nodes' ? nodeStart : relStart),
`rescanned previous ${kind}`,
);
reads[kind]++;
}
return Reflect.get(target, property, receiver);
},
set(target, property, value, receiver) {
if (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property)) {
assert(
Number(property) >= (kind === 'nodes' ? nodeStart : relStart),
`rewrote previous ${kind}`,
);
reads.writes++;
}
return Reflect.set(target, property, value, receiver);
},
});
const guarded = {
nodes: watched(raw.nodes, 'nodes'),
relationships: watched(raw.relationships, 'relationships'),
};
const guard = createOwnerEdgeGuard(guarded);
for (const file of input) {
guard.open(file.path); // Settles the previous slice before the boundaries advance.
nodeStart = raw.nodes.length;
relStart = raw.relationships.length;
append(raw, file); // Fixture appends bypass the access counters.
}
guard.settle();
const settledReads = { ...reads };
guard.settle();
assert.deepEqual(reads, settledReads, 'settling twice rescans a file');
const n = input.reduce((sum, file) => sum + file.nodes.length, 0);
const e = input.reduce((sum, file) => sum + file.relationships.length, 0);
assert(reads.nodes <= n, 'more than one node pass');
assert(reads.relationships <= 3 * e, 'more than three relationship passes');
assert(reads.writes <= e, 'more than one compaction pass');
verify(
raw,
[...prefix.relationships, ...input.flatMap((file) => file.expected)],
prefix.nodes.length + n,
);
return reads;
}
function trial(input: FileFixture[], prefix: Slice, direct: boolean, expected: Rel[]): number {
const result: Slice = {
nodes: prefix.nodes.slice(),
relationships: prefix.relationships.slice(),
};
const nodeStart = result.nodes.length;
const relStart = result.relationships.length;
if (direct) append(result, input[0]);
globalThis.gc?.();
const start = performance.now();
if (direct) {
dropDanglingInFileOwnerEdges(result, input[0].path, nodeStart, relStart);
} else {
const guard = createOwnerEdgeGuard(result);
for (const file of input) {
guard.open(file.path);
append(result, file);
}
guard.settle();
}
const elapsed = performance.now() - start;
verify(
result,
expected,
prefix.nodes.length + input.reduce((sum, file) => sum + file.nodes.length, 0),
);
return elapsed;
}
const percentile = (values: number[], fraction: number): number => {
const sorted = [...values].sort((a, b) => a - b);
return sorted[Math.ceil(fraction * sorted.length) - 1];
};
function measure(shape: Shape, count: number, perFile: number, prefixCount = 0) {
const input = files(shape, count, perFile);
const prefix = prefixCount
? fixture('member-free', prefixCount, 99999999)
: { nodes: [], relationships: [] };
const nodes = input.reduce((sum, file) => sum + file.nodes.length, 0);
const relationships = input.reduce((sum, file) => sum + file.relationships.length, 0);
const counts = operations(input, prefix);
const direct = prefixCount > 0;
const samplesMs: number[] = [];
if (!values['operations-only']) {
for (let i = 0; i < warmup + samples; i++) {
const freshInput = files(shape, count, perFile);
const expected = [...prefix.relationships, ...freshInput.flatMap((file) => file.expected)];
const elapsed = trial(freshInput, prefix, direct, expected);
if (i >= warmup) samplesMs.push(elapsed);
}
}
const medianMs = samplesMs.length ? percentile(samplesMs, 0.5) : null;
return {
shape,
members: count,
files: input.length,
prefixRows: prefix.nodes.length + prefix.relationships.length,
nodes,
relationships,
indexedReads: counts,
samplesMs,
medianMs,
p95Ms: samplesMs.length ? percentile(samplesMs, 0.95) : null,
nsPerRow: medianMs === null ? null : (medianMs * 1e6) / (nodes + relationships),
};
}
function slope(points: { x: number; y: number }[]): number | null {
if (points.length < 2 || points.some(({ x, y }) => x <= 0 || y <= 0)) return null;
const xs = points.map(({ x }) => Math.log(x));
const ys = points.map(({ y }) => Math.log(y));
const meanX = xs.reduce((a, b) => a + b, 0) / xs.length;
const meanY = ys.reduce((a, b) => a + b, 0) / ys.length;
return (
xs.reduce((sum, x, i) => sum + (x - meanX) * (ys[i] - meanY), 0) /
xs.reduce((sum, x) => sum + (x - meanX) ** 2, 0)
);
}
const cases: ReturnType<typeof measure>[] = [];
const scaling: { shape: Shape; distribution: string; logLogSlope: number | null }[] = [];
const shapes: Shape[] = [
'member-free',
'clean',
'dangling',
'predefined',
'duplicate',
'owner-last',
];
// Alternate ascending/descending sizes to avoid tying every large case to late-run thermal drift.
for (const [shapeIndex, shape] of shapes.entries()) {
for (const distribution of ['one-file', 'many-files']) {
const rows = (shapeIndex % 2 ? [...sizes].reverse() : sizes).map((size) =>
measure(shape, size, distribution === 'one-file' ? size : 16),
);
cases.push(...rows);
scaling.push({
shape,
distribution,
logLogSlope: values['operations-only']
? null
: slope(
rows.flatMap((row) =>
row.medianMs === null ? [] : [{ x: row.nodes + row.relationships, y: row.medianMs }],
),
),
});
process.stderr.write(`Validated ${shape} / ${distribution}\n`);
}
}
const prefixIsolation = sizes.map((size) => measure('dangling', 16, 16, size));
process.stdout.write(
`${JSON.stringify(
{
schema: 'gitnexus.owner-edge-guard-scaling/v1',
recordedAt: new Date().toISOString(),
environment: {
node: process.version,
v8: process.versions.v8,
platform: platform(),
arch: arch(),
release: release(),
cpu: cpus()[0]?.model,
explicitGc: typeof globalThis.gc === 'function',
processMaxRssKiB: process.resourceUsage().maxRSS,
},
sourceSha256: createHash('sha256').update(source).digest('hex'),
config: { sizes, samples, warmup, operationsOnly: values['operations-only'] },
methodology: {
timed:
'guard lifecycle + append preconstructed rows; prefixIsolation times only the direct guard',
excluded:
'fresh fixture generation for every sample, prefix copies, assertions, explicit GC, Proxy instrumentation',
statistics:
'nearest-rank median/p95; least-squares slope of log(median ms) versus log(active rows)',
operations:
'at most one indexed node read, three indexed relationship reads, one relationship write per active row; no earlier-slice indexed accesses',
limits:
'Kernel benchmark, not end-to-end indexing throughput. Timings and slopes are descriptive, not asymptotic proof. maxRSS covers all fixtures and validation and is not guard peak memory. Set operations assume average constant-time hashing; string work scales with id lengths.',
memory:
'Live guard scratch is O(nodes + edges) of the largest active file; output accumulation and delayed garbage collection are excluded from that bound.',
},
cases,
scaling,
prefixIsolation,
},
null,
2,
)}\n`,
);

View file

@ -0,0 +1,264 @@
/**
* Generated, non-confidential #3527 probe. Keeps its indexes and raw responses.
* Usage: node scripts/repro-3527.mjs <built-gitnexus-package> <new-output-dir>
* Exit 1 means an integrity/coverage failure; exit 2 means the probe could not run.
* This does not claim to reproduce the original private macOS checkout.
*/
import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
import fs from 'node:fs';
import { createRequire } from 'node:module';
import path from 'node:path';
const [runtimeArg, outputArg] = process.argv.slice(2);
assert(runtimeArg && outputArg, 'Supply a built GitNexus package and a NEW output directory');
const runtime = fs.realpathSync(runtimeArg);
const output = path.resolve(outputArg);
fs.mkdirSync(output);
const primary = path.join(output, 'primary');
const repo = path.join(output, 'worktree');
fs.mkdirSync(primary);
const requireRuntime = createRequire(path.join(runtime, 'package.json'));
const lbug = requireRuntime('@ladybugdb/core');
const env = {
PATH: process.env.PATH,
HOME: process.env.HOME,
LANG: 'C.UTF-8',
TZ: 'UTC',
GIT_CONFIG_GLOBAL: '/dev/null',
GIT_CONFIG_NOSYSTEM: '1',
GIT_AUTHOR_NAME: 'fixture',
GIT_AUTHOR_EMAIL: 'fixture@example.com',
GIT_COMMITTER_NAME: 'fixture',
GIT_COMMITTER_EMAIL: 'fixture@example.com',
GITNEXUS_HOME: path.join(output, 'home'),
GITNEXUS_MEMORY: 'off',
NODE_OPTIONS: '--max-old-space-size=2048',
GITNEXUS_LBUG_BUFFER_POOL_SIZE: String(512 * 1024 ** 2),
GITNEXUS_WORKER_POOL_SIZE: '1',
GITNEXUS_PARSE_CHUNK_CONCURRENCY: '1',
GITNEXUS_LBUG_EXTENSION_INSTALL: 'load-only',
};
const expected = {};
const report = {
runtime,
node: process.version,
engine: lbug.VERSION,
platform: `${process.platform}-${process.arch}`,
expectedMethods: 4480,
expectedStructs: 4480,
queries: [],
native: [],
crossLanguageMethodPaths: 0,
nulStructNames: 0,
witnesses: [],
};
const save = (name, value) =>
fs.writeFileSync(path.join(output, name), JSON.stringify(value, null, 2) + '\n');
const git = (args, cwd = primary) => execFileSync('git', args, { cwd, env, stdio: 'pipe' });
function cli(args, name) {
const stderr = fs.openSync(path.join(output, name + '.stderr.txt'), 'w');
try {
const text = execFileSync(
process.execPath,
[path.join(runtime, 'dist/cli/index.js'), ...args],
{
cwd: repo,
env,
encoding: 'utf8',
stdio: ['ignore', 'pipe', stderr],
maxBuffer: 32 * 1024 ** 2,
timeout: 300_000,
},
);
fs.writeFileSync(path.join(output, name + '.txt'), text);
return text;
} finally {
fs.closeSync(stderr);
}
}
function source(kind, batch, edit = false) {
const python = kind === 'python';
const file = python
? `checks/test_integrity_batch_${batch}.py`
: `Sources/Features/Component${batch}/IntegritySentinels_${batch}.swift`;
const lines = python ? [`class IntegrityBatch${batch}:`] : [];
for (let i = 0; i < 64; i++) {
const name = python
? `test_mixed_integrity_${batch}_${i}`
: `MixedIntegritySentinel${batch}_${i}`;
const startLine = lines.length + 1;
const marker = `mixed integrity sentinel ${batch}_${i}${edit && i === 0 ? ' changed' : ''}`;
const block = python
? [` def ${name}(self):`, ` return "${marker}"`]
: [`struct ${name} {`, ` let marker = "${marker}"`, '}'];
const id = python
? `Method:${file}:IntegrityBatch${batch}.${name}#0`
: `Struct:${file}:${name}`;
expected[id] = { id, name, filePath: file, startLine, endLine: startLine + block.length - 1 };
lines.push(...block, '');
}
const root = fs.existsSync(repo) ? repo : primary;
fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
fs.writeFileSync(path.join(root, file), lines.join('\n'));
expected['File:' + file] = { id: 'File:' + file, name: path.basename(file), filePath: file };
}
function mismatches(rows) {
return rows.filter(
(row) =>
!expected[row.id] ||
Object.keys(expected[row.id]).some((k) => row[k] !== expected[row.id][k]),
);
}
async function nativeChecks() {
const entry = JSON.parse(fs.readFileSync(path.join(output, 'home/registry.json'))).find(
(entry) => fs.realpathSync(entry.path) === fs.realpathSync(repo),
);
assert(entry, 'The exact worktree must be registered');
const meta = JSON.parse(fs.readFileSync(path.join(entry.storagePath, 'gitnexus.json')));
const dbPath = meta.graphPath || path.join(entry.storagePath, 'lbug');
report.dbPath = dbPath;
report.lastCommit = meta.lastCommit;
assert.equal(meta.lastCommit, git(['rev-parse', 'HEAD'], repo).toString().trim());
const db = new lbug.Database(dbPath, 512 * 1024 ** 2, false, true);
const conn = new lbug.Connection(db);
const fields =
'n.id AS id,n.name AS name,n.filePath AS filePath,n.startLine+1 AS startLine,n.endLine+1 AS endLine';
async function read(query, params) {
const result = params
? await conn.execute(await conn.prepare(query), params)
: await conn.query(query);
try {
return await result.getAll();
} finally {
await result.close();
}
}
async function check(rows, ids, stage) {
const bad = mismatches(rows);
const found = new Set(rows.map((row) => row.id));
const missing = ids.filter((id) => !found.has(id));
const duplicates = rows.length - found.size;
report.crossLanguageMethodPaths += bad.filter(
(row) => row.id?.startsWith('Method:') && row.filePath?.includes('.swift'),
).length;
report.nulStructNames += bad.filter(
(row) => row.id?.startsWith('Struct:') && row.name?.includes('\0'),
).length;
report.native.push({
stage,
rows: rows.length,
bad: bad.length,
missing: missing.length,
duplicates,
});
if ((bad.length || missing.length || duplicates) && report.witnesses.length < 8) {
const uid = missing[0] || bad.find((row) => expected[row.id])?.id;
const primaryKey = uid
? await read(`MATCH(n:${uid.split(':')[0]} {id:$uid}) RETURN ${fields}`, { uid })
: [];
report.witnesses.push({
stage,
bad: bad.slice(0, 3),
missing: missing.slice(0, 3),
uid,
primaryKey,
});
}
}
try {
const methods = Object.keys(expected).filter((id) => id.startsWith('Method:'));
const structs = Object.keys(expected).filter((id) => id.startsWith('Struct:'));
for (const [table, ids] of [
['Method', methods],
['Struct', structs],
]) {
await check(await read(`MATCH(n:${table}) RETURN ${fields}`), ids, table + '-all');
}
const statement = await conn.prepare(
`MATCH(n) WHERE n.id IN $ids RETURN ${fields} ORDER BY startLine,id`,
);
for (let i = 0; i < 150; i++) {
const ids = [methods[(i * 29) % methods.length], structs[(i * 67) % structs.length]];
if (i % 3) ids.splice(i % 2, 1);
const result = await conn.execute(statement, { ids });
let rows;
try {
rows = await result.getAll();
} finally {
await result.close();
}
await check(rows, ids, 'mixed-' + i);
}
} finally {
await conn.close();
await db.close();
}
}
try {
for (let i = 0; i < 70; i++) for (const kind of ['python', 'swift']) source(kind, i);
fs.writeFileSync(path.join(primary, '.gitignore'), '.gitnexus/\n');
git(['init', '-b', 'main']);
git(['add', '.']);
git(['-c', 'commit.gpgsign=false', 'commit', '-m', 'mixed language fixture']);
git(['worktree', 'add', '-b', 'verification', repo]);
cli(['analyze', '--index-only', '.'], 'baseline-analyze');
for (let round = 0; round < 3; round++) {
source('python', round, true); // Leave every Swift file untouched.
git(['add', '.'], repo);
git(['-c', 'commit.gpgsign=false', 'commit', '-m', `incremental edit ${round}`], repo);
const name = `round-${round}-analyze`;
const analyze = cli(['analyze', '--index-only', '.'], name);
assert(
!/switching to a full DB write|escalated/i.test(
analyze + fs.readFileSync(path.join(output, name + '.stderr.txt')),
),
'Probe requires selective writeback',
);
cli(['status'], `round-${round}-status`);
const terms = [
'mixed integrity sentinel',
'test_mixed_integrity',
'MixedIntegritySentinel',
'integrity batch',
];
for (const [i, term] of terms.entries()) {
const text = cli(['query', term, '--repo', repo], `round-${round}-query-${i}`);
const result = JSON.parse(text.slice(text.indexOf('{')));
const rows = [...(result.process_symbols ?? []), ...(result.definitions ?? [])];
const relevant = rows.filter((row) => /^(Method|Struct|File):/.test(row.id));
report.queries.push({
round,
term,
error: result.error,
partial: result.partial,
rows: rows.length,
methods: rows.filter((r) => r.id?.startsWith('Method:')).length,
structs: rows.filter((r) => r.id?.startsWith('Struct:')).length,
bad: mismatches(relevant),
});
}
save('report.json', report);
}
save('expected.json', expected);
await nativeChecks();
report.passed =
report.queries.every((q) => !q.error && !q.partial && q.rows > 0 && !q.bad.length) &&
report.queries.some((q) => q.methods > 0) &&
report.queries.some((q) => q.structs > 0) &&
report.native.every((q) => !q.bad && !q.missing && !q.duplicates);
save('report.json', report);
console.log(
JSON.stringify({
engine: report.engine,
passed: report.passed,
report: path.join(output, 'report.json'),
}),
);
process.exitCode = report.passed ? 0 : 1;
} catch (error) {
report.probeError = String(error);
save('report.json', report);
console.error(error);
process.exitCode = 2;
}

View file

@ -87,6 +87,7 @@ Generates repository documentation from the knowledge graph using an LLM. HTTP p
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
| `--timeout <seconds>` | LLM request timeout in seconds (default: disabled) |
| `--retries <n>` | Max LLM retry attempts per request (default: 3) |
| `--max-completion-tokens <n>` | Max completion tokens per LLM request (default: 16384). `GITNEXUS_MAX_COMPLETION_TOKENS` overrides `maxCompletionTokens` in `~/.gitnexus/config.json`; the flag overrides both. |
| `--lang <lang>` | Output language for generated documentation (e.g. english, chinese, spanish, japanese) |
| `--gist` | Publish wiki as a public GitHub Gist |

View file

@ -114,6 +114,7 @@ const OPTION_DESCRIPTION_KEYS = {
'wiki|--concurrency <n>': 'help.option.wiki.concurrency',
'wiki|--timeout <seconds>': 'help.option.wiki.timeout',
'wiki|--retries <n>': 'help.option.wiki.retries',
'wiki|--max-completion-tokens <n>': 'help.option.wiki.maxCompletionTokens',
'wiki|--allow-insecure-connection <host>': 'help.option.wiki.allowInsecureConnection',
'wiki|--gist': 'help.option.wiki.gist',
'wiki|-v, --verbose': 'help.option.verbose',

View file

@ -361,6 +361,8 @@ export const en = {
'help.option.wiki.concurrency': 'Parallel LLM calls (default: 3)',
'help.option.wiki.timeout': 'LLM request timeout in seconds (default: disabled)',
'help.option.wiki.retries': 'Max LLM retry attempts per request (default: 3)',
'help.option.wiki.maxCompletionTokens':
'Max completion tokens for each LLM request (default: 16384)',
'help.option.wiki.allowInsecureConnection':
'Allow exact host(s) for http:// LLM base URLs (comma-separated; HTTPS is preferred)',
'help.option.wiki.gist': 'Publish wiki as a public GitHub Gist after generation',
@ -390,7 +392,7 @@ export const en = {
'help.option.impact.offset': 'Skip N symbols per depth level for pagination',
'help.option.impact.summaryOnly': 'Return counts and risk only, omit symbol list',
'help.option.impact.maxTokens':
'Fit the result into about N tokens by dropping the deepest symbols first (counts stay complete)',
'Fit compact JSON into about N tokens, dropping deepest symbols first; fails if the summary cannot fit',
'help.option.trace.fromUid': 'Source symbol UID (zero-ambiguity lookup)',
'help.option.trace.fromFile': 'Source file path to disambiguate common names',
'help.option.trace.toUid': 'Target symbol UID (zero-ambiguity lookup)',

View file

@ -329,6 +329,7 @@ export const zhCN = {
'help.option.wiki.concurrency': '并行 LLM 调用数(默认:3)',
'help.option.wiki.timeout': 'LLM 请求超时时间(秒,默认:禁用)',
'help.option.wiki.retries': '每个请求的最大 LLM 重试次数(默认:3)',
'help.option.wiki.maxCompletionTokens': '每次 LLM 请求的最大 completion token 数(默认:16384)',
'help.option.wiki.allowInsecureConnection':
'允许 http:// LLM base URL 使用的精确主机(逗号分隔;推荐使用 HTTPS)',
'help.option.wiki.gist': '生成后发布 Wiki 为公开 GitHub Gist',
@ -355,7 +356,7 @@ export const zhCN = {
'help.option.impact.offset': '每层深度跳过 N 个符号(分页用)',
'help.option.impact.summaryOnly': '仅返回计数和风险等级,省略符号列表',
'help.option.impact.maxTokens':
'将结果控制在约 N 个 token 内,优先舍弃最深层的符号(计数保持完整)',
'将紧凑 JSON 控制在约 N 个 token 内,优先舍弃最深层的符号;摘要无法容纳时返回错误',
'help.option.trace.fromUid': '源符号 UID(零歧义查找)',
'help.option.trace.fromFile': '源文件路径,用于消除常见名称歧义',
'help.option.trace.toUid': '目标符号 UID(零歧义查找)',

View file

@ -427,6 +427,10 @@ program
.option('--concurrency <n>', 'Parallel LLM calls (default: 3)', '3')
.option('--timeout <seconds>', 'LLM request timeout in seconds (default: disabled)')
.option('--retries <n>', 'Max LLM retry attempts per request (default: 3)')
.option(
'--max-completion-tokens <n>',
'Max completion tokens for each LLM request (default: 16384)',
)
.option(
'--allow-insecure-connection <host>',
'Allow exact host(s) for http:// LLM base URLs (comma-separated; HTTPS is preferred)',
@ -520,7 +524,7 @@ program
.option('--summary-only', 'Return counts and risk only, omit symbol list')
.option(
'--max-tokens <n>',
'Fit the result into about N tokens by dropping the deepest symbols first (counts stay complete)',
'Fit compact JSON into about N tokens, dropping deepest symbols first; fails if the summary cannot fit',
)
.action(createLbugLazyAction(() => import('./tool.js'), 'impactCommand'));

View file

@ -118,13 +118,23 @@ export const mcpCommand = async (options?: {
// stdout at module init, but transitive deps (pino, pino-pretty, the
// worker-thread transport) could in theory, and the import-closure
// regression test enforces the leaf invariant.
const [{ startMCPServer }, { LocalBackend }, { logger }, { createMcpRepositoryPolicy }] =
await Promise.all([
import('../mcp/server.js'),
import('../mcp/local/local-backend.js'),
import('../core/logger.js'),
import('../mcp/repository-policy.js'),
]);
const [
{ startMCPServer },
{ LocalBackend },
{ logger },
{ createMcpRepositoryPolicy },
{ resolveMcpRefreshLimits, resolveMcpRefreshMode },
] = await Promise.all([
import('../mcp/server.js'),
import('../mcp/local/local-backend.js'),
import('../core/logger.js'),
import('../mcp/repository-policy.js'),
import('../mcp/refresh-policy.js'),
]);
// Local servers only: `gitnexus serve` never reads these (#3524). A malformed
// value fails startup here, before any repository is opened.
const refreshIndex = resolveMcpRefreshMode();
if (refreshIndex) resolveMcpRefreshLimits();
// Missing-optional-grammar warnings are intentionally NOT emitted here.
// `gitnexus analyze` already warns at index time, filtered by the repo's
@ -174,6 +184,7 @@ export const mcpCommand = async (options?: {
host: options.host ?? '127.0.0.1',
authToken: resolveAuthToken(options.authToken, process.env),
repositoryPolicy,
refreshIndex,
});
} catch (err) {
logger.error(
@ -187,6 +198,6 @@ export const mcpCommand = async (options?: {
}
// Start MCP server (serves all repos, discovers new ones lazily)
await startMCPServer(backend, repositoryPolicy);
await startMCPServer(backend, repositoryPolicy, { refreshIndex });
void startMcpUpdateNotifier(logger).catch(() => {});
};

View file

@ -19,7 +19,12 @@ import { writeSync } from 'node:fs';
import { LocalBackend, VALID_NODE_LABELS } from '../mcp/local/local-backend.js';
import { cliErrorKey, cliWarnKey } from './cli-message.js';
import { formatDetectChangesResult } from './detect-changes-format.js';
import { shapeImpactForAgent, withImpactAgentDefaults } from '../mcp/impact-agent-output.js';
import {
ImpactBudgetExceededError,
shapeImpactForAgent,
withImpactAgentDefaults,
} from '../mcp/impact-agent-output.js';
import { resolveMcpMaxTokens } from '../mcp/output-budget.js';
let _backend: LocalBackend | null = null;
@ -270,11 +275,7 @@ export async function impactCommand(
// rather than on a silently-dropped flag. A non-numeric `--line` parses to
// NaN, which the backend rejects as a non-positive integer (loud, not silent).
const parsedLine = options?.line !== undefined ? parseInt(options.line, 10) : undefined;
const maxTokens = parseLimit(options?.maxTokens);
if (options?.maxTokens !== undefined && maxTokens === undefined) {
cliErrorKey('tool.usage.impact');
process.exit(1);
}
const maxTokens = resolveMcpMaxTokens('impact', { maxTokens: options?.maxTokens }, {});
const impactArgs = withImpactAgentDefaults({
target: target || undefined,
target_uid: options?.uid,
@ -294,7 +295,7 @@ export async function impactCommand(
offset: parsedOffset,
summaryOnly: options?.summaryOnly ?? undefined,
});
const result = shapeImpactForAgent(await backend.callTool('impact', impactArgs), maxTokens);
const result = await backend.callTool('impact', impactArgs);
// Client-side cap of the affected-list payload to --limit (parity with the
// other tool commands). The backend already paginates byDepth per level to
// the same limit, so byDepth needs no client-side re-slice.
@ -306,8 +307,15 @@ export async function impactCommand(
if (Array.isArray(result.affected_routes))
result.affected_routes = result.affected_routes.slice(0, parsedLimit);
}
output(result);
const shaped = shapeImpactForAgent(result, maxTokens);
// The budget is measured on compact JSON, even when stdout is a terminal.
output(shaped, maxTokens === undefined ? undefined : (data) => JSON.stringify(data));
} catch (err: unknown) {
if (err instanceof ImpactBudgetExceededError) {
output(err.toJSONText());
process.exitCode = 1;
return;
}
// Belt-and-suspenders: catch infrastructure failures (getBackend, callTool transport)
// The backend's impact() already returns structured errors for graph query failures
output({

View file

@ -47,6 +47,7 @@ export interface WikiCommandOptions {
retries?: string;
lang?: string;
allowInsecureConnection?: string;
maxCompletionTokens?: string;
}
function isLocalProvider(
@ -189,6 +190,7 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
let timeoutSeconds: number | undefined;
let retries: number | undefined;
let allowedInsecureHttpHosts: string[] | undefined;
let maxCompletionTokens: number | undefined;
try {
timeoutSeconds =
options?.timeout === undefined
@ -202,6 +204,12 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
options?.allowInsecureConnection === undefined
? undefined
: parseLLMAllowedInsecureHttpHosts(options.allowInsecureConnection);
maxCompletionTokens =
options?.maxCompletionTokens === undefined
? undefined
: parseIntegerOption(options.maxCompletionTokens, '--max-completion-tokens', {
minimum: 1,
});
} catch (error) {
console.log(` Error: ${(error as Error).message}\n`);
process.exitCode = 1;
@ -271,15 +279,23 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
options?.reasoningModel !== undefined
);
let llmConfig = await resolveLLMConfig({
model: options?.model,
baseUrl: options?.baseUrl,
apiKey: options?.apiKey,
provider: options?.provider,
apiVersion: options?.apiVersion,
isReasoningModel: options?.reasoningModel,
allowedInsecureHttpHosts,
});
let llmConfig;
try {
llmConfig = await resolveLLMConfig({
model: options?.model,
baseUrl: options?.baseUrl,
apiKey: options?.apiKey,
provider: options?.provider,
apiVersion: options?.apiVersion,
isReasoningModel: options?.reasoningModel,
allowedInsecureHttpHosts,
maxTokens: maxCompletionTokens,
});
} catch (error) {
console.log(` Error: ${(error as Error).message}\n`);
process.exitCode = 1;
return;
}
// Run interactive setup if no saved config and no CLI flags provided
// (even if env vars exist — let user explicitly choose their provider)
@ -687,7 +703,10 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
bar.stop();
const totalElapsed = ((Date.now() - t0) / 1000).toFixed(1);
console.log(`\n Wiki generated successfully (${totalElapsed}s)\n`);
const incomplete = !!continueResult.failedModules?.length;
console.log(
`\n ${incomplete ? 'Wiki generation incomplete' : 'Wiki generated successfully'} (${totalElapsed}s)\n`,
);
console.log(` Mode: ${continueResult.mode}`);
console.log(` Pages: ${continueResult.pagesGenerated}`);
console.log(` Output: ${wikiDir}`);
@ -698,6 +717,9 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
for (const mod of continueResult.failedModules) {
console.log(` - ${mod}`);
}
console.log(' Re-run to retry failed modules (pages will be regenerated).\n');
process.exitCode = 1;
return;
}
console.log('');
@ -714,7 +736,10 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
return;
}
console.log(`\n Wiki generated successfully (${elapsed}s)\n`);
const incomplete = !!result.failedModules?.length;
console.log(
`\n ${incomplete ? 'Wiki generation incomplete' : 'Wiki generated successfully'} (${elapsed}s)\n`,
);
console.log(` Mode: ${result.mode}`);
console.log(` Pages: ${result.pagesGenerated}`);
console.log(` Output: ${wikiDir}`);
@ -726,6 +751,9 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
console.log(` - ${mod}`);
}
console.log(' Re-run to retry failed modules (pages will be regenerated).');
console.log('');
process.exitCode = 1;
return;
}
console.log('');

View file

@ -15,7 +15,9 @@ export type AutoSyncAnalysisRunner = (
signal?: AbortSignal,
onCancellationRequested?: () => void,
concurrency?: number,
) => Promise<Pick<AnalyzeResult, 'stats'>>;
/** Worker progress until the run settles or cancellation begins. */
onProgress?: (percent: number, message: string) => void,
) => Promise<Pick<AnalyzeResult, 'stats' | 'graphWriteCollapsed'>>;
interface AnalysisWorker extends Pick<ChildProcess, 'send' | 'on'> {
stdout?: Pick<NodeJS.ReadableStream, 'resume'> | null;
@ -36,6 +38,8 @@ export class AutoSyncAnalysisError extends Error {
readonly code?: 'index-lock-timeout';
readonly retryable?: boolean;
readonly abandonedWorker: boolean;
/** Resolves on actual process exit when the request stopped waiting first. */
readonly workerExited?: Promise<void>;
constructor(
message: string,
@ -43,6 +47,7 @@ export class AutoSyncAnalysisError extends Error {
code?: 'index-lock-timeout';
retryable?: boolean;
abandonedWorker?: boolean;
workerExited?: Promise<void>;
} = {},
) {
super(message);
@ -50,6 +55,7 @@ export class AutoSyncAnalysisError extends Error {
this.code = options.code;
this.retryable = options.retryable;
this.abandonedWorker = options.abandonedWorker === true;
this.workerExited = options.workerExited;
}
}
@ -89,8 +95,8 @@ export function createAutoSyncAnalysisRunner(
overrides: Partial<AutoSyncAnalysisLaunchDeps> = {},
): AutoSyncAnalysisRunner {
const deps = { ...DEFAULT_DEPS, ...overrides };
return (repoPath, options, timeoutMs, signal, onCancellationRequested, concurrency) =>
new Promise<Pick<AnalyzeResult, 'stats'>>((resolve, reject) => {
return (repoPath, options, timeoutMs, signal, onCancellationRequested, concurrency, onProgress) =>
new Promise<Pick<AnalyzeResult, 'stats' | 'graphWriteCollapsed'>>((resolve, reject) => {
if (signal?.aborted) {
reject(new Error('Analysis cancelled.'));
return;
@ -135,7 +141,10 @@ export function createAutoSyncAnalysisRunner(
child.channel?.unref?.();
child.unref?.();
};
const settle = (error?: Error, result?: Pick<AnalyzeResult, 'stats'>) => {
const settle = (
error?: Error,
result?: Pick<AnalyzeResult, 'stats' | 'graphWriteCollapsed'>,
) => {
if (settled) return;
settled = true;
cleanup();
@ -163,12 +172,15 @@ export function createAutoSyncAnalysisRunner(
// child is deliberately left running rather than killed mid-write.
graceTimer = deps.setTimeoutFn(() => {
if (settled) return;
const workerExited = new Promise<void>((resolveExited) => {
child.on('exit', () => resolveExited());
});
releaseChild();
settle(
new AutoSyncAnalysisError(
`${error.message} The analyze worker did not exit within ${deps.cancelGraceMs}ms; ` +
'it was left running so its native work is not interrupted.',
{ abandonedWorker: true, retryable: true },
{ abandonedWorker: true, retryable: true, workerExited },
),
);
}, deps.cancelGraceMs);
@ -183,7 +195,19 @@ export function createAutoSyncAnalysisRunner(
child.on('message', (message: WorkerMessage) => {
// Once timeout/cancellation requested shutdown, its reason owns the
// result. A terminal IPC can already be queued behind cancellation.
if (message.type === 'progress' || terminalOutcome || terminationError) return;
if (terminalOutcome || terminationError) return;
if (message.type === 'progress') {
// The worker also sends its log lines as progress with percent -1;
// those are not progress. A listener's failure must not decide the
// run's outcome.
if (message.percent < 0) return;
try {
onProgress?.(message.percent, message.message);
} catch {
// ignored
}
return;
}
terminalOutcome = message;
deps.clearTimeoutFn(timeout);
});
@ -204,7 +228,9 @@ export function createAutoSyncAnalysisRunner(
return;
}
if (terminalOutcome?.type === 'complete') {
settle(undefined, { stats: terminalOutcome.result.stats });
const { stats, graphWriteCollapsed } = terminalOutcome.result;
// Only present on a collapsed write, so a healthy result keeps its shape.
settle(undefined, graphWriteCollapsed ? { stats, graphWriteCollapsed } : { stats });
return;
}
if (terminalOutcome?.type === 'error') {

View file

@ -10,7 +10,7 @@ import {
import fs from 'fs/promises';
import { readdir } from 'node:fs';
import path from 'path';
import { glob } from 'glob';
import { glob, globIterate } from 'glob';
import { createIgnoreFilter } from '../../config/ignore-service.js';
import { mapConcurrent } from '../../lib/utils.js';
@ -254,6 +254,33 @@ export const walkRepositoryPaths = async (
return deduplicatedEntries;
};
/**
* Count the paths `walkRepositoryPaths` would scan, with the same patterns and
* ignore rules, and stop as soon as the count passes `limit`. Nothing is
* stat-ed, so large files, non-regular entries and declaration siblings are
* not subtracted: the result is an upper bound on what analyze indexes. Used
* to refuse an expensive rebuild before it starts (#3524).
*/
export const countScanCandidates = async (
repoPath: string,
limit: number,
options: Pick<WalkRepositoryOptions, 'includeDotDirs'> = {},
): Promise<number> => {
await assertWalkRootIsDirectory(repoPath);
const ignoreFilter = await createIgnoreFilter(repoPath);
const includeDotDirs = normalizeIncludeDotDirs(options.includeDotDirs ?? getIncludeDotDirs());
let count = 0;
for await (const _ of globIterate(indexableGlobPatterns(includeDotDirs), {
cwd: repoPath,
nodir: true,
dot: false,
ignore: includeDotDirs.length > 0 ? dotDirectoryIgnoreFilter(ignoreFilter) : ignoreFilter,
})) {
if (++count > limit) break;
}
return count;
};
/**
* Phase 2: Read file contents for a specific set of relative paths.
* Returns a Map for O(1) lookup. Silently skips files that fail to read.

View file

@ -0,0 +1,109 @@
/**
* Per-file guard against member edges whose owner node was never emitted.
*
* Owner ids are minted from syntax (the binding an object literal is assigned
* to, the enclosing container), while node labels come from the query captures,
* so the two can disagree (#3747): `const X = z.object({ k: f(() => 0) }).refine(cb)`
* is emitted as `Function:<file>:X` but its key's owner is spelled
* `Const:<file>:X`, and a TS `declare module 'm' {}` owns its members under a
* `Trait` id no TS capture ever emits. LadybugDB's COPY rejects such an edge and
* the retry silently drops it.
*
* Kept free of worker side effects so it can be unit-tested directly.
*/
import { generateId } from '../../../lib/utils.js';
import type { ParseWorkerResult } from './parse-worker.js';
const isMemberEdge = (type: string): boolean => type === 'HAS_METHOD' || type === 'HAS_PROPERTY';
/**
* Remove `HAS_METHOD` / `HAS_PROPERTY` edges appended for `filePath` (from
* `relStart` on) whose owner id names a node in that same file that the file
* did not emit (from `nodeStart` on). The orphaned member is re-attached to its
* File with `DEFINES` unless it already has one.
*
* Owners in other files are left alone: they are resolved across the whole
* graph, not per file.
*/
export const dropDanglingInFileOwnerEdges = (
result: Pick<ParseWorkerResult, 'nodes' | 'relationships'>,
filePath: string,
nodeStart: number,
relStart: number,
): void => {
const rels = result.relationships;
const inFilePrefix = `:${filePath}:`;
let emitted: Set<string> | null = null;
let dangling: Set<number> | null = null;
for (let i = relStart; i < rels.length; i++) {
const rel = rels[i];
if (!isMemberEdge(rel.type)) continue;
const labelEnd = rel.sourceId.indexOf(':');
if (labelEnd < 0 || !rel.sourceId.startsWith(inFilePrefix, labelEnd)) continue;
if (emitted === null) {
emitted = new Set<string>();
for (let n = nodeStart; n < result.nodes.length; n++) emitted.add(result.nodes[n].id);
}
if (!emitted.has(rel.sourceId)) (dangling ??= new Set<number>()).add(i);
}
if (dangling === null || emitted === null) return;
const fileId = generateId('File', filePath);
const defined = new Set<string>();
for (let i = relStart; i < rels.length; i++) {
const rel = rels[i];
if (rel.type === 'DEFINES' && rel.sourceId === fileId) defined.add(rel.targetId);
}
let write = relStart;
for (let i = relStart; i < rels.length; i++) {
const rel = rels[i];
if (!dangling.has(i)) {
rels[write++] = rel;
continue;
}
if (defined.has(rel.targetId) || !emitted.has(rel.targetId)) continue;
defined.add(rel.targetId);
rels[write++] = {
id: generateId('DEFINES', `${fileId}->${rel.targetId}`),
sourceId: fileId,
targetId: rel.targetId,
type: 'DEFINES',
confidence: 1.0,
reason: '',
};
}
rels.length = write;
};
/** Tracks the file whose slice of a worker result is still being appended. */
export interface OwnerEdgeGuard {
/** Settle the previous file, then start tracking what `filePath` appends. */
open(filePath: string): void;
/** Settle the tracked file, if any. Safe to call more than once. */
settle(): void;
}
export const createOwnerEdgeGuard = (
result: Pick<ParseWorkerResult, 'nodes' | 'relationships'>,
): OwnerEdgeGuard => {
let current: { path: string; nodeStart: number; relStart: number } | null = null;
const settle = (): void => {
if (current === null) return;
const file = current;
current = null;
dropDanglingInFileOwnerEdges(result, file.path, file.nodeStart, file.relStart);
};
return {
open(filePath: string): void {
settle();
current = {
path: filePath,
nodeStart: result.nodes.length,
relStart: result.relationships.length,
};
},
settle,
};
};

View file

@ -138,6 +138,7 @@ import { buildTypeEnv } from '../type-env.js';
import type { ConstructorBinding } from '../type-env.js';
import { detectFrameworkFromAST } from '../framework-detection.js';
import { generateId } from '../../../lib/utils.js';
import { createOwnerEdgeGuard, type OwnerEdgeGuard } from './owner-edge-guard.js';
import { defaultExportNameCollides } from '../languages/typescript/cjs-export-assignment.js';
import {
extractVueScript,
@ -1595,6 +1596,23 @@ const processFileGroup = (
queryString: string,
result: ParseWorkerResult,
onFileProcessed?: () => void,
): void => {
const ownerEdgeGuard = createOwnerEdgeGuard(result);
try {
processFileGroupFiles(files, language, queryString, result, ownerEdgeGuard, onFileProcessed);
} finally {
// Also on a throw: processBatch keeps the partial result of a failed group.
ownerEdgeGuard.settle();
}
};
const processFileGroupFiles = (
files: ParseWorkerInput[],
language: SupportedLanguages,
queryString: string,
result: ParseWorkerResult,
ownerEdgeGuard: OwnerEdgeGuard,
onFileProcessed?: () => void,
): void => {
let query: Parser.Query;
try {
@ -1615,6 +1633,8 @@ const processFileGroup = (
}
for (const file of files) {
// Settles the previous file, so every `continue` below still gets checked.
ownerEdgeGuard.open(file.path);
// Skip files larger than the max tree-sitter buffer (32 MB)
if (getTreeSitterContentByteLength(file.content) > TREE_SITTER_MAX_BUFFER) continue;

View file

@ -1,3 +1,6 @@
import { getLanguageFromFilename } from 'gitnexus-shared';
import { SYMBOL_NODE_LABELS } from '../ingestion/utils/symbol-labels.js';
/** Shared integrity boundary for identities returned by graph and search queries. */
export const SYMBOL_IDENTITY_RECOVERY_SUGGESTION =
'Run gitnexus analyze --force from the affected repository root to rebuild the index.';
@ -41,6 +44,28 @@ export function assertIdentityFields(...values: unknown[]): void {
}
}
/** Reject mixed rows even when both the UID and the unrelated path are printable. */
export function assertSymbolFilePath(id: unknown, filePath: unknown): void {
// Older indexes may omit paths or use opaque IDs without a source-path component.
if (typeof id !== 'string' || typeof filePath !== 'string' || !filePath) return;
const separator = id.indexOf(':');
if (separator < 0) return;
const label = id.slice(0, separator);
const sourceLabels: ReadonlySet<string> = SYMBOL_NODE_LABELS;
if (label === 'File' || label === 'Folder') {
if (id !== `${label}:${filePath}`) throw new SymbolIdentityError();
} else if (sourceLabels.has(label) && id.indexOf(':', separator + 1) >= 0) {
// A node label does not define its ID format. Providers also emit semantic
// IDs (objc:class:..., spring-config:..., etc.) without a leading file path.
// Only compare paths when that leading component identifies a source file;
// opaque IDs and ambiguous colon-containing paths cannot be decoded here.
const leadingComponent = id.slice(separator + 1, id.indexOf(':', separator + 1));
if (!getLanguageFromFilename(leadingComponent)) return;
// Match against the supplied path rather than splitting it: filenames can contain colons.
if (!id.startsWith(`${label}:${filePath}:`)) throw new SymbolIdentityError();
}
}
export function assertQueryIdentity(
row: unknown,
idKey: string,

View file

@ -241,11 +241,13 @@ export const isReadOnlyShadowReplayError = (err: unknown): boolean => {
// SIGKILLing a writer mid-CHECKPOINT (homelab 2026-09-19, GitNexus image
// 1.6.10-20260917, built on 0.19.x). The 0.18.3 binary does NOT contain it
// (checked via `strings`), and 0.18.3 tolerates the same on-disk state, so on
// 0.18.x this classifier simply never fires. If the engine pin ever moves
// back to ^0.19, the read-path self-heal is already in place.
// 0.18.x this classifier simply never fires. In 0.22.0 the same refusal is
// reported as "checkpoint recovery is pending".
export const isReadOnlyCheckpointInProgressError = (err: unknown): boolean => {
const msg = err instanceof Error ? err.message : String(err);
return /cannot open database in read-only mode while checkpoint is in progress/i.test(msg);
return /cannot open database in read-only mode while checkpoint (?:is in progress|recovery is pending)/i.test(
msg,
);
};
/** Prefix of the interrupted-checkpoint wrap — must not rematch the native classifier. */

View file

@ -1556,6 +1556,8 @@ export async function runFullAnalysis(
else if (options.shareWith) await setShareOptOut(repoPath, false);
return result;
} finally {
// Readers opened after analyze must not inherit its smaller write budget.
setBufferPoolSizeHint(undefined);
await removeColdParseRebuildDir(parseRun.storagePath, true);
discardScopedEmbeddingSpills();
lock.release();

View file

@ -85,6 +85,8 @@ export interface WikiMeta {
lang: string;
moduleFiles: Record<string, string[]>;
moduleTree: ModuleTreeNode[];
/** Pages that must be retried even when fromCommit is still current. */
failedModules?: string[];
}
export interface ModuleTreeNode {
@ -260,6 +262,7 @@ export class WikiGenerator {
* Main entry point. Runs the full pipeline or incremental update.
*/
async run(): Promise<WikiRunResult> {
this.failedModules = [];
await fs.mkdir(this.wikiDir, { recursive: true });
const existingMeta = await this.loadWikiMeta();
@ -267,7 +270,12 @@ export class WikiGenerator {
const forceMode = this.options.force;
// Up-to-date check (skip if --force)
if (!forceMode && existingMeta && existingMeta.fromCommit === currentCommit) {
if (
!forceMode &&
existingMeta &&
existingMeta.fromCommit === currentCommit &&
!existingMeta.failedModules?.length
) {
const currentLang = this.effectiveLang();
const metaLang = existingMeta.lang ?? '';
if (currentLang !== metaLang) {
@ -284,6 +292,8 @@ export class WikiGenerator {
// Force mode: delete snapshot to force full re-grouping
if (forceMode) {
// A failure must not leave the previous wiki marked complete at this commit.
await fs.rm(path.join(this.wikiDir, 'meta.json'), { force: true });
try {
await fs.unlink(path.join(this.wikiDir, 'first_module_tree.json'));
} catch {}
@ -421,6 +431,11 @@ export class WikiGenerator {
// Process parent modules sequentially (they depend on child docs)
for (const node of parents) {
if (node.children?.some((child) => this.failedModules.includes(child.name))) {
this.failedModules.push(node.name);
reportProgress(`Failed: ${node.name}`);
continue;
}
const pagePath = path.join(this.wikiDir, `${node.slug}.md`);
if (await this.fileExists(pagePath)) {
reportProgress(node.name);
@ -452,6 +467,7 @@ export class WikiGenerator {
lang: this.effectiveLang(),
moduleFiles,
moduleTree,
failedModules: [...this.failedModules],
});
this.onProgress('done', 100, 'Wiki generation complete');
@ -1005,7 +1021,7 @@ export class WikiGenerator {
return { ...fullResult, mode: 'incremental' };
}
if (changedFiles.length === 0) {
if (changedFiles.length === 0 && !existingMeta.failedModules?.length) {
// No file changes but commit differs (e.g. merge commit)
await this.saveWikiMeta({
...existingMeta,
@ -1019,7 +1035,7 @@ export class WikiGenerator {
this.onProgress('incremental', 10, `${changedFiles.length} files changed`);
// Determine affected modules
const affectedModules = new Set<string>();
const affectedModules = new Set(existingMeta.failedModules ?? []);
const newFiles: string[] = [];
for (const fp of changedFiles) {
@ -1080,7 +1096,7 @@ export class WikiGenerator {
}
let incProcessed = 0;
pagesGenerated += await this.runParallel(affectedNodes, async (node) => {
const regenerateNode = async (node: ModuleTreeNode): Promise<number> => {
try {
if (node.children && node.children.length > 0) {
await this.generateParentPage(node);
@ -1100,7 +1116,18 @@ export class WikiGenerator {
incProcessed++;
return 0;
}
});
};
const leaves = affectedNodes.filter((node) => !node.children?.length);
const parents = affectedNodes.filter((node) => node.children?.length);
pagesGenerated += await this.runParallel(leaves, regenerateNode);
for (const node of parents) {
if (node.children?.some((child) => this.failedModules.includes(child.name))) {
this.failedModules.push(node.name);
continue;
}
pagesGenerated += await regenerateNode(node);
}
// Regenerate overview if any pages changed
if (pagesGenerated > 0) {
@ -1117,6 +1144,7 @@ export class WikiGenerator {
generatedAt: new Date().toISOString(),
model: this.llmConfig.model,
lang: this.effectiveLang(),
failedModules: [...this.failedModules],
});
this.onProgress('done', 100, 'Incremental update complete');

View file

@ -148,7 +148,11 @@ export async function resolveLLMConfig(overrides?: Partial<LLMConfig>): Promise<
? ''
: (reuseSavedHttpConfig ? savedConfig.model : undefined) ||
(savedProvider === 'minimax' ? MINIMAX_MODEL_IDS[0] : '')),
maxTokens: overrides?.maxTokens ?? 16_384,
maxTokens:
readOverrideMaxCompletionTokens(overrides?.maxTokens) ??
readEnvMaxCompletionTokens(process.env[LLM_MAX_COMPLETION_TOKENS_ENV]) ??
readConfiguredMaxCompletionTokens(savedConfig.maxCompletionTokens) ??
DEFAULT_MAX_COMPLETION_TOKENS,
temperature: overrides?.temperature ?? 0,
provider: savedProvider,
apiVersion:
@ -185,6 +189,37 @@ function isTimeoutLikeError(err: unknown): boolean {
}
export const LLM_ALLOW_INSECURE_CONNECTION_ENV = 'GITNEXUS_ALLOW_INSECURE_CONNECTION';
export const LLM_MAX_COMPLETION_TOKENS_ENV = 'GITNEXUS_MAX_COMPLETION_TOKENS';
export const DEFAULT_MAX_COMPLETION_TOKENS = 16_384;
function readOverrideMaxCompletionTokens(value: number | undefined): number | undefined {
if (value === undefined) return undefined;
if (!Number.isSafeInteger(value) || value < 1) {
throw new Error('--max-completion-tokens must be a positive integer');
}
return value;
}
function readEnvMaxCompletionTokens(value: string | undefined): number | undefined {
if (value === undefined || value.trim() === '') return undefined;
const trimmed = value.trim();
if (!/^[1-9]\d*$/.test(trimmed)) {
throw new Error(`${LLM_MAX_COMPLETION_TOKENS_ENV} must be a positive integer`);
}
const parsed = Number(trimmed);
if (!Number.isSafeInteger(parsed) || String(parsed) !== trimmed) {
throw new Error(`${LLM_MAX_COMPLETION_TOKENS_ENV} is too large`);
}
return parsed;
}
function readConfiguredMaxCompletionTokens(value: unknown): number | undefined {
if (value === undefined) return undefined;
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
throw new Error('maxCompletionTokens in ~/.gitnexus/config.json must be a positive integer');
}
return value;
}
function normalizeAllowedInsecureHttpHost(host: string): string {
const trimmed = host.trim().toLowerCase();
@ -450,12 +485,15 @@ export async function callLLM(
// Streaming path
if (useStream && response.body) {
return await readSSEStream(response.body, options!.onChunk!);
return await readSSEStream(response.body, options!.onChunk!, config.maxTokens);
}
// Non-streaming path
const json = (await response.json()) as any;
const choice = json.choices?.[0];
if (choice?.finish_reason === 'length') {
throw truncatedResponseError(config.maxTokens);
}
if (!choice?.message?.content) {
throw new Error('LLM returned empty response');
}
@ -467,18 +505,28 @@ export async function callLLM(
};
}
// A response cut off by the completion limit reads like a finished one, and a
// reasoning model can spend the whole limit before the answer starts.
function truncatedResponseError(maxTokens: number): Error {
return new Error(
`LLM response stopped at the completion token limit (${maxTokens}, finish_reason "length") and is incomplete.`,
);
}
/**
* Read an SSE stream from an OpenAI-compatible streaming response.
*/
async function readSSEStream(
body: ReadableStream<Uint8Array>,
onChunk: (charsReceived: number) => void,
maxTokens: number,
): Promise<LLMResponse> {
const decoder = new TextDecoder();
const reader = body.getReader();
let content = '';
let buffer = '';
let contentFilterTriggered = false;
let lengthLimitReached = false;
while (true) {
const { done, value } = await reader.read();
@ -503,6 +551,9 @@ async function readSSEStream(
contentFilterTriggered = true;
continue;
}
if (choice?.finish_reason === 'length') {
lengthLimitReached = true;
}
const delta = choice?.delta?.content;
if (delta) {
@ -521,6 +572,10 @@ async function readSSEStream(
);
}
if (lengthLimitReached) {
throw truncatedResponseError(maxTokens);
}
if (!content) {
throw new Error('LLM returned empty streaming response');
}

View file

@ -47,6 +47,8 @@ export interface McpHttpOptions {
authToken?: string;
/** Prevalidated repository policy shared by startup logging and transports. */
repositoryPolicy?: McpRepositoryPolicy;
/** Expose `refresh_index` (#3524); set only by the local `gitnexus mcp --http`. */
refreshIndex?: boolean;
}
interface MCPSession {
@ -229,6 +231,7 @@ export function createStreamableHttpHandler(
host?: string;
port?: number;
repositoryPolicy?: McpRepositoryPolicy;
refreshIndex?: boolean;
} = {},
): {
handler: (req: Request, res: Response) => Promise<void>;
@ -301,7 +304,10 @@ export function createStreamableHttpHandler(
});
const server = opts.createServer
? opts.createServer()
: createMCPServer(backend, { repositoryPolicy: await getRepositoryPolicy() });
: createMCPServer(backend, {
repositoryPolicy: await getRepositoryPolicy(),
refreshIndex: opts.refreshIndex,
});
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
@ -363,6 +369,7 @@ export function createSseHandlers(
host?: string;
port?: number;
repositoryPolicy?: McpRepositoryPolicy;
refreshIndex?: boolean;
} = {},
): {
sseHandler: (req: Request, res: Response) => Promise<void>;
@ -395,7 +402,10 @@ export function createSseHandlers(
// SSEServerTransport(endpoint, res, options): endpoint is the path clients POST to.
const transport = new SSEServerTransport(messagesPath, res, dnsRebinding);
const server = createMCPServer(backend, { repositoryPolicy: await getRepositoryPolicy() });
const server = createMCPServer(backend, {
repositoryPolicy: await getRepositoryPolicy(),
refreshIndex: opts.refreshIndex,
});
sseSessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() });
@ -535,7 +545,13 @@ export async function startMcpHttpServer(
});
// Streamable HTTP (modern MCP clients) at POST /mcp.
const streamable = createStreamableHttpHandler(backend, { host, port, repositoryPolicy });
const { refreshIndex } = options;
const streamable = createStreamableHttpHandler(backend, {
host,
port,
repositoryPolicy,
refreshIndex,
});
app.all('/mcp', auth, jsonBody, (req: Request, res: Response) => {
void streamable.handler(req, res).catch((err: unknown) => {
logger.error({ err }, 'MCP /mcp request failed');
@ -550,7 +566,12 @@ export async function startMcpHttpServer(
});
// Legacy SSE: GET /sse opens the stream; POST /messages receives JSON-RPC messages.
const sse = createSseHandlers(backend, '/messages', { host, port, repositoryPolicy });
const sse = createSseHandlers(backend, '/messages', {
host,
port,
repositoryPolicy,
refreshIndex,
});
app.get('/sse', auth, (req: Request, res: Response) => {
void sse.sseHandler(req, res).catch((err: unknown) => {
logger.error({ err }, 'MCP /sse failed');

View file

@ -1,3 +1,5 @@
import { MCP_TOKEN_ESTIMATE_BYTES } from './output-budget.js';
/**
* Agent-facing shaping of `impact` results.
*
@ -18,8 +20,28 @@ export const IMPACT_AGENT_DEFAULT_LIMIT = 30;
/** Processes listed per affected symbol; `processCount` carries the full count. */
export const IMPACT_ITEM_PROCESS_CAP = 3;
/** Bytes per estimated token, the same conservative estimate as output-budget.ts. */
const TOKEN_ESTIMATE_BYTES = 4;
/** A budget that cannot hold the summary must never look like a successful empty walk. */
export class ImpactBudgetExceededError extends Error {
constructor(readonly maxTokens: number) {
super('Impact result cannot fit maxTokens. Increase maxTokens or narrow the request.');
this.name = 'ImpactBudgetExceededError';
}
toJSONText(): string {
const budget = this.maxTokens * MCP_TOKEN_ESTIMATE_BYTES;
for (const payload of [
{ error: this.message },
{ error: 'Increase maxTokens' },
{ error: true },
]) {
const text = JSON.stringify(payload);
if (Buffer.byteLength(text, 'utf8') <= budget) return text;
}
// Even a one-token budget holds valid JSON. The transport's isError or
// CLI exit status still signals failure when an error object cannot fit.
return 'null';
}
}
/**
* The default per-depth page for agent calls. `GITNEXUS_IMPACT_DEFAULT_LIMIT=0`
@ -44,7 +66,11 @@ export function withImpactAgentDefaults<T extends Record<string, unknown> | unde
env: NodeJS.ProcessEnv = process.env,
): T {
if (!args) return args;
if (args.limit !== undefined || args.offset !== undefined || args.summaryOnly !== undefined) {
if (
args.limit !== undefined ||
(args.offset !== undefined && args.offset !== 0) ||
(args.summaryOnly !== undefined && args.summaryOnly !== false)
) {
return args;
}
if (typeof args.repo === 'string' && args.repo.startsWith('@')) return args;
@ -108,16 +134,20 @@ function keepFirst(byDepth: Record<string, unknown[]>, keep: number): Record<str
* deepest levels first, so the JSON stays valid and the direct dependants
* survive longest. Counts (`byDepthCounts`, `impactedCount`, `summary`) still
* describe the full result, and `pagination.trimmedForBudget` says what was
* cut. A result that cannot fit even without symbols is returned unchanged;
* the byte-level cap after serialization still applies to it.
* cut. If the summary alone cannot fit, fail explicitly instead of letting a
* byte-level cap turn a successful response into broken JSON.
*
* `reservedBytes` is text appended after serialization (next-step hints).
*/
export function fitImpactToTokenBudget<T>(result: T, maxTokens: number, reservedBytes = 0): T {
const input: unknown = result;
if (!isRecord(input) || !isRecord(input.byDepth)) return result;
const budget = maxTokens * TOKEN_ESTIMATE_BYTES - reservedBytes;
const budget = maxTokens * MCP_TOKEN_ESTIMATE_BYTES - reservedBytes;
if (byteLength(result) <= budget) return result;
// PDG's byDepth aliases interproceduralByDepth. Trimming only one would
// publish contradictory views of the same slice.
if (!isRecord(input) || !isRecord(input.byDepth) || input.mode === 'pdg') {
throw new ImpactBudgetExceededError(maxTokens);
}
const byDepth = input.byDepth as Record<string, unknown[]>;
const total = Object.values(byDepth).reduce(
@ -143,7 +173,7 @@ export function fitImpactToTokenBudget<T>(result: T, maxTokens: number, reserved
// Largest prefix that fits: one serialization per probe, log2(total) probes.
let low = 0;
let high = total;
if (byteLength(build(0)) > budget) return result;
if (byteLength(build(0)) > budget) throw new ImpactBudgetExceededError(maxTokens);
while (low < high) {
const mid = Math.ceil((low + high) / 2);
if (byteLength(build(mid)) <= budget) low = mid;
@ -158,7 +188,9 @@ export function shapeImpactForAgent<T>(
maxTokens: number | undefined,
reservedBytes = 0,
): T {
const compact = compactImpactItemProcesses(result);
const input: unknown = result;
const compact =
isRecord(input) && input.mode === 'pdg' ? result : compactImpactItemProcesses(result);
return maxTokens === undefined
? compact
: fitImpactToTokenBudget(compact, maxTokens, reservedBytes);

View file

@ -38,6 +38,7 @@ import {
SYMBOL_IDENTITY_RECOVERY_SUGGESTION,
SymbolIdentityError,
assertSymbolIdentity,
assertSymbolFilePath,
queryRowValue,
assertIdentityFields,
assertQueryIdentity,
@ -131,6 +132,7 @@ import {
isFullSourceAvailable,
} from '../../core/content-retention.js';
import { checkStalenessAsync, checkCwdMatch } from '../../core/git-staleness.js';
import { MCP_REFRESH_TOOL, resolveMcpRefreshLimits } from '../refresh-policy.js';
import {
stalenessPayload,
type IndexedRef,
@ -404,6 +406,8 @@ function assertResponseIdentities(value: unknown): void {
if (Array.isArray(value)) {
for (const item of value) assertResponseIdentities(item);
} else if (value !== null && typeof value === 'object') {
const row = value as Record<string, unknown>;
assertSymbolFilePath(row.id ?? row.uid, row.filePath);
for (const [key, field] of Object.entries(value)) {
if (key === 'seedBlocks' || key === 'reachableBlocks' || key === 'intraReachableBlocks') {
if (!Array.isArray(field)) throw new SymbolIdentityError();
@ -1213,6 +1217,18 @@ async function callableValueReferenceBoundaries(
};
}
/** Per-call extras the MCP server hands to {@link LocalBackend.callTool}. */
export interface McpToolCallContext {
/** `refresh_index` progress, as the analyze worker reports it (percent 0-100). */
onProgress?: (percent: number, message: string) => void;
}
/** An error's message as one sentence, so further sentences can follow it. */
function asSentence(err: unknown): string {
const message = (err instanceof Error ? err.message : String(err)).trim();
return /[.!?]$/u.test(message) ? message : `${message}.`;
}
interface RepoHandle {
id: string; // unique key = repo name (basename)
name: string;
@ -1572,7 +1588,9 @@ const isMissingRouteOptionalPropertyError = (error: unknown): boolean => {
* form; any guard failure returns `{ error }`.
*/
type ApiImpactResult =
ApiImpactRoute | { routes: ApiImpactRoute[]; total: number } | { error: string };
| ApiImpactRoute
| { routes: ApiImpactRoute[]; total: number }
| { error: string };
/**
* One repository entry as returned by {@link LocalBackend.listRepos} and in each
@ -3121,7 +3139,7 @@ export class LocalBackend {
return entry.value;
}
async callTool(method: string, params: any): Promise<any> {
async callTool(method: string, params: any, context: McpToolCallContext = {}): Promise<any> {
if (method === 'list_repos') {
// Paginated tool surface (#2119). `listRepos()` is unchanged for internal
// callers; the tool wraps it in { repositories, pagination } and forwards
@ -3172,7 +3190,12 @@ export class LocalBackend {
const repo = await this.selectToolRepository(
p.repo as string | undefined,
p.branch as string | undefined,
{ allowCwdDefault: method !== 'rename' || p.dry_run === undefined || p.dry_run === true },
{
allowCwdDefault:
method === MCP_REFRESH_TOOL
? false
: method !== 'rename' || p.dry_run === undefined || p.dry_run === true,
},
);
switch (method) {
@ -3220,11 +3243,159 @@ export class LocalBackend {
return this.withToolStaleness(repo, await this.readFile(repo, p));
case 'grep':
return this.withToolStaleness(repo, await this.grep(repo, p));
case MCP_REFRESH_TOOL:
return this.refreshIndex(repo, p, context);
default:
throw new Error(`Unknown tool: ${method}`);
}
}
/** Indexes with a `refresh_index` run in flight, keyed by storage slot (#3524). */
private readonly refreshesInFlight = new Set<string>();
/**
* `refresh_index` (#3524): rebuild one registered index through the same
* forked worker and options auto-sync uses, so nothing in the repository is
* written and the analysis runs outside this process. The worker takes the
* index lock and publishes the way `analyze` does (atomic swap on POSIX; see
* run-analyze). The server only dispatches here when the local operator
* enabled the tool; see refresh-policy.ts.
*/
private async refreshIndex(
repo: RepoHandle,
params: Record<string, unknown>,
context: McpToolCallContext,
): Promise<unknown> {
if (params.dry_run !== undefined && typeof params.dry_run !== 'boolean') {
return { error: 'Parameter "dry_run" must be a boolean.' };
}
const { maxFiles, timeoutMs } = resolveMcpRefreshLimits();
const [{ runAutoSyncAnalysis }, { embeddingsFromGitnexusRc }, { countScanCandidates }] =
await Promise.all([
import('../../core/auto-sync/analysis-worker-launch.js'),
import('../../core/gitnexus-rc-embeddings.js'),
import('../../core/ingestion/filesystem-walker.js'),
]);
let rcEmbeddings: Awaited<ReturnType<typeof embeddingsFromGitnexusRc>>;
// The working tree, not the last index, decides the rebuild's size: a stale
// index is exactly the one that may have fallen far behind it. Counting
// stops one past the limit, so a huge tree costs no more than a small one.
let treeFiles: number | undefined;
try {
rcEmbeddings = await embeddingsFromGitnexusRc(repo.repoPath);
if (maxFiles > 0) treeFiles = await countScanCandidates(repo.repoPath, maxFiles);
} catch (err) {
return { error: `Cannot refresh ${repo.name}: ${asSentence(err)}` };
}
const previous = await this.refreshSnapshot(repo);
const lastIndexedFiles = repo.stats?.files ?? null;
const refusal =
treeFiles !== undefined && treeFiles > maxFiles
? `${repo.name} has more than ${maxFiles} files in its working tree${
lastIndexedFiles === null ? '' : ` (${lastIndexedFiles} at its last index)`
}, over this server's refresh limit of ${maxFiles} (GITNEXUS_MCP_REFRESH_MAX_FILES). Run \`gitnexus analyze\` in the repository instead.`
: undefined;
const running = this.refreshesInFlight.has(repo.storagePath);
if (params.dry_run === true) {
return {
status: 'dry_run',
repo: repo.name,
...previous,
// Exact up to the limit; past it, only "more than maxFiles" is known.
estimatedFiles: treeFiles === undefined || refusal ? null : treeFiles,
lastIndexedFiles,
maxFiles,
// `.gitnexusrc` can ask for embeddings, which the file limit does not bound.
embeddings: rcEmbeddings.embeddings === true,
wouldRefresh: refusal === undefined && !running,
...(refusal ? { refusal } : {}),
...(running ? { inProgress: true } : {}),
};
}
if (running) {
return { error: `A refresh of ${repo.name} is already running; wait for it to finish.` };
}
if (refusal) return { error: refusal };
// No abort signal is passed: the worker never interrupts an analysis it has
// started (analyze-worker.ts), so a cancelled call would only free this slot
// while the rebuild runs on. Holding it keeps "already running" and
// `inProgress` true until the worker is done.
this.refreshesInFlight.add(repo.storagePath);
const startedAt = Date.now();
let analysis: Awaited<ReturnType<typeof runAutoSyncAnalysis>>;
let workerExited: Promise<void> | undefined;
try {
analysis = await runAutoSyncAnalysis(
repo.repoPath,
{
skipAgentsMd: true,
skipSkills: true,
preserveExistingPdg: true,
atomicIncremental: true,
...rcEmbeddings,
},
timeoutMs,
undefined,
undefined,
undefined,
context.onProgress,
);
} catch (err) {
const failure = err as {
abandonedWorker?: boolean;
workerExited?: Promise<void>;
} | null;
// The request can time out before its worker releases the index lock.
if (failure?.abandonedWorker) workerExited = failure.workerExited;
const leftRunning =
failure?.abandonedWorker === true
? ' Its worker keeps running until the analysis finishes; another refresh is refused until it exits.'
: '';
return {
error: `Refresh of ${repo.name} failed: ${asSentence(err)}${leftRunning} Run \`gitnexus analyze\` in the repository for the full log.`,
};
} finally {
const releaseSlot = () => this.refreshesInFlight.delete(repo.storagePath);
if (workerExited) void workerExited.then(releaseSlot);
else releaseSlot();
}
await this.refreshRepos();
// Same verdict as `gitnexus analyze` and `serve`: most edges are missing,
// so this is a failure, not a refresh.
if (analysis.graphWriteCollapsed) {
const { expected, persisted } = analysis.graphWriteCollapsed;
return {
error: `${repo.name} was indexed INCOMPLETELY: only ${persisted} of ${expected} expected relationships are readable, so queries will answer with missing edges. Run \`gitnexus analyze --force\` in the repository; if it recurs, check disk space and run \`gitnexus doctor\`.`,
};
}
const refreshed = this.resolveRepoFromCache(repo.repoPath) ?? repo;
return {
status: 'refreshed',
repo: refreshed.name,
previous,
...(await this.refreshSnapshot(refreshed)),
stats: refreshed.stats ?? {},
durationMs: Date.now() - startedAt,
};
}
private async refreshSnapshot(repo: RepoHandle) {
const info = await checkStalenessAsync(repo.repoPath, repo.lastCommit).catch(() => undefined);
return {
indexedAt: repo.indexedAt,
lastCommit: repo.lastCommit,
// `stalenessPayload` omits `current`; this result always states it, and a
// check that could not run is `unknown`, never `current`.
staleness:
info === undefined
? { status: 'unknown' }
: (stalenessPayload(info, { includeUnknown: true }) ?? { status: 'current' }),
};
}
// ─── Tool Implementations ────────────────────────────────────────
/** Check repository graph invariants that are suitable for CI gating. */
@ -9743,7 +9914,8 @@ export class LocalBackend {
'individual indexed repository instead.',
target: groupRejectTarget,
direction: (params.direction === 'downstream' ? 'downstream' : 'upstream') as
'upstream' | 'downstream',
| 'upstream'
| 'downstream',
});
return pdgErr;
}

View file

@ -0,0 +1,81 @@
/**
* Opt-in MCP index refresh (#3524).
*
* `refresh_index` is the one MCP tool that rebuilds an index. It is off unless
* the operator starting a LOCAL server (`gitnexus mcp`, stdio or `--http`) sets
* `GITNEXUS_MCP_ENABLE_REFRESH=1`. `gitnexus serve` never passes the flag to
* `createMCPServer`, so the web/Docker `/api/mcp` surface cannot expose it
* whatever its environment says. Read-only mode hides and rejects it through
* the `MCP_READ_ONLY_TOOLS` allowlist, which it is deliberately not part of.
*/
export const MCP_REFRESH_TOOL = 'refresh_index';
/**
* Repositories whose last index recorded more files than this are refused,
* because a full rebuild can run for minutes (#3524 measured 377 s for 10,987
* files). `0` removes the limit.
*/
export const MCP_REFRESH_DEFAULT_MAX_FILES = 5_000;
export const MCP_REFRESH_DEFAULT_TIMEOUT_MS = 10 * 60_000;
/** Node fires a longer `setTimeout` after 1 ms, so a larger value would cancel at once. */
const MAX_TIMER_MS = 2_147_483_647;
export function resolveMcpRefreshMode(env: NodeJS.ProcessEnv = process.env): boolean {
const value = env.GITNEXUS_MCP_ENABLE_REFRESH?.trim();
if (value === undefined || value === '' || value === '0') return false;
if (value === '1') return true;
throw new Error('GITNEXUS_MCP_ENABLE_REFRESH must be 0 or 1.');
}
function nonNegativeIntegerEnv(
env: NodeJS.ProcessEnv,
name: string,
fallback: number,
{ allowZero, max }: { allowZero: boolean; max: number },
): number {
const raw = env[name]?.trim();
if (raw === undefined || raw === '') return fallback;
const value = Number(raw);
if (!/^\d+$/u.test(raw) || value > max || (!allowZero && value === 0)) {
throw new Error(
`${name} must be ${allowZero ? 'a non-negative' : 'a positive'} integer no greater than ${max}; got "${raw}".`,
);
}
return value;
}
export interface McpRefreshLimits {
/** `0` means no limit. */
maxFiles: number;
timeoutMs: number;
}
export function resolveMcpRefreshLimits(env: NodeJS.ProcessEnv = process.env): McpRefreshLimits {
return {
maxFiles: nonNegativeIntegerEnv(
env,
'GITNEXUS_MCP_REFRESH_MAX_FILES',
MCP_REFRESH_DEFAULT_MAX_FILES,
{ allowZero: true, max: Number.MAX_SAFE_INTEGER },
),
timeoutMs: nonNegativeIntegerEnv(
env,
'GITNEXUS_MCP_REFRESH_TIMEOUT_MS',
MCP_REFRESH_DEFAULT_TIMEOUT_MS,
{ allowZero: false, max: MAX_TIMER_MS },
),
};
}
/**
* Dispatch half of the gate. The server lists the tool only when enabled; this
* keeps an unlisted tool from being called by name.
*/
export function assertMcpRefreshToolCall(toolName: string, refreshEnabled: boolean): void {
if (toolName === MCP_REFRESH_TOOL && !refreshEnabled) {
throw new Error(
`Tool "${MCP_REFRESH_TOOL}" is disabled. Start the local MCP server with GITNEXUS_MCP_ENABLE_REFRESH=1 to enable it, or run \`gitnexus analyze\` in the repository.`,
);
}
}

View file

@ -1,5 +1,5 @@
import path from 'node:path';
import type { LocalBackend, RepoListing } from './local/local-backend.js';
import type { LocalBackend, McpToolCallContext, RepoListing } from './local/local-backend.js';
import { parseListReposPagination } from './local/local-backend.js';
import { scrubGroupDescription } from './read-only-policy.js';
import { LIST_REPOS_DEFAULT_LIMIT, LIST_REPOS_MAX_LIMIT } from './tools.js';
@ -258,13 +258,14 @@ export class McpRepositoryPolicy {
backend: LocalBackend,
method: string,
params: Record<string, unknown> | undefined,
...context: [McpToolCallContext?]
): Promise<unknown> {
if (!this.configured) return backend.callTool(method, params);
if (!this.configured) return backend.callTool(method, params, ...context);
if (method === 'list_repos') return this.listReposPage(backend, params);
if (this.restricted && method.startsWith('group_')) {
throw new Error('Group tools are unavailable when an MCP repository allowlist is set.');
}
return backend.callTool(method, this.normalizeToolArgs(params));
return backend.callTool(method, this.normalizeToolArgs(params), ...context);
}
private async resolveRepo(
@ -366,8 +367,11 @@ export class McpRepositoryPolicy {
return new Proxy(backend, {
get(target, property, receiver) {
if (property === 'callTool') {
return (method: string, params: Record<string, unknown> | undefined) =>
policy.callTool(target, method, params);
return (
method: string,
params: Record<string, unknown> | undefined,
...context: [McpToolCallContext?]
) => policy.callTool(target, method, params, ...context);
}
if (property === 'listRepos') return () => policy.listAllowedRepos(target);
if (property === 'resolveRepo') {

View file

@ -22,10 +22,16 @@ import {
ListResourceTemplatesRequestSchema,
ListPromptsRequestSchema,
GetPromptRequestSchema,
type ServerNotification,
} from '@modelcontextprotocol/sdk/types.js';
import { GITNEXUS_TOOLS, REPO_SCOPED_TOOLS } from './tools.js';
import {
findToolDefinition,
GITNEXUS_TOOLS,
REFRESH_INDEX_TOOL,
REPO_SCOPED_TOOLS,
} from './tools.js';
import { installGlobalStdoutSentinel } from './stdio-context.js';
import type { LocalBackend } from './local/local-backend.js';
import type { LocalBackend, McpToolCallContext } from './local/local-backend.js';
import { getResourceDefinitions, getResourceTemplates, readResource } from './resources.js';
import {
assertMcpReadOnlyResource,
@ -36,18 +42,18 @@ import {
resolveMcpReadOnlyMode,
toolForReadOnlyMcp,
} from './read-only-policy.js';
import { assertMcpRefreshToolCall, MCP_REFRESH_TOOL } from './refresh-policy.js';
import {
createMcpRepositoryPolicy,
McpRepositoryPolicy,
mcpRepositoryPolicyConfigured,
} from './repository-policy.js';
import { applyMcpMaxTokens, resolveMcpMaxTokens, withoutMcpBudgetArg } from './output-budget.js';
import {
applyMcpMaxTokens,
MCP_TRUNCATION_MARKER,
resolveMcpMaxTokens,
withoutMcpBudgetArg,
} from './output-budget.js';
import { shapeImpactForAgent, withImpactAgentDefaults } from './impact-agent-output.js';
ImpactBudgetExceededError,
shapeImpactForAgent,
withImpactAgentDefaults,
} from './impact-agent-output.js';
import { assertKnownMcpToolArguments, schemaSourceToolName } from './tool-arguments.js';
import {
applyMcpResponseFilter,
@ -130,6 +136,12 @@ export function getNextStepHint(
case 'overview':
return `\n\n---\n**Next:** To drill into an area, READ gitnexus://repo/${repoPath}/cluster/{name}. To see execution flows, READ gitnexus://repo/${repoPath}/processes.`;
case 'refresh_index':
// Dry runs and refusals come back as plain results; only a rebuild changes what to do next.
return (toolResult as { status?: unknown } | null)?.status === 'refreshed'
? `\n\n---\n**Next:** Re-run the call that reported the stale index; it now reads the refreshed one.`
: '';
default:
return '';
}
@ -145,15 +157,46 @@ function formatMcpToolError(error: unknown): string {
return typeof code === 'string' ? `Error [${code}]: ${message}` : `Error: ${message}`;
}
/**
* Relay `refresh_index` worker progress as MCP progress notifications when the
* client asked for them. Values only move forward, as the protocol requires,
* and a failed send never fails the refresh.
*/
function refreshProgress(
progressToken: string | number | undefined,
extra: { sendNotification: (notification: ServerNotification) => Promise<void> },
): McpToolCallContext | undefined {
if (progressToken === undefined) return undefined;
let last = -1;
return {
onProgress: (percent, message) => {
const progress = Math.min(100, Math.max(last, percent));
if (progress === last) return;
last = progress;
void extra
.sendNotification({
method: 'notifications/progress',
params: { progressToken, progress, total: 100, message },
})
.catch(() => {});
},
};
}
/**
* Create a configured MCP Server with all handlers registered.
* Transport-agnostic — caller connects the desired transport.
*/
export function createMCPServer(
backend: LocalBackend,
options: { repositoryPolicy?: McpRepositoryPolicy } = {},
options: {
repositoryPolicy?: McpRepositoryPolicy;
/** Expose `refresh_index`; only the local `gitnexus mcp` command passes it (#3524). */
refreshIndex?: boolean;
} = {},
): Server {
const readOnly = resolveMcpReadOnlyMode();
const refreshEnabled = options.refreshIndex === true && !readOnly;
if (!options.repositoryPolicy && mcpRepositoryPolicyConfigured()) {
throw new Error('Configured MCP repository policy must be validated before server creation.');
}
@ -243,19 +286,21 @@ export function createMCPServer(
const { readOnlyRequiresRepo, mutatingRequiresRepo } =
await repositoryPolicy.toolSchemaRepoRequirements(backend);
return {
tools: GITNEXUS_TOOLS.filter(
(tool) =>
(!readOnly || MCP_READ_ONLY_TOOLS.has(tool.name)) &&
repositoryPolicy.toolAllowed(tool.name),
)
tools: (refreshEnabled ? [...GITNEXUS_TOOLS, REFRESH_INDEX_TOOL] : GITNEXUS_TOOLS)
.filter(
(tool) =>
(!readOnly || MCP_READ_ONLY_TOOLS.has(tool.name)) &&
repositoryPolicy.toolAllowed(tool.name),
)
.map((tool) => repositoryPolicy.toolForMcp(toolForReadOnlyMcp(tool, readOnly)))
.map((tool) => ({
name: tool.name,
description: tool.description,
inputSchema:
// Read-only `rename` is preview-only, so it follows the read-tool rule.
(tool.name === 'rename' && !readOnly ? mutatingRequiresRepo : readOnlyRequiresRepo) &&
REPO_SCOPED_TOOLS.has(tool.name)
((tool.name === 'rename' && !readOnly) || tool.name === MCP_REFRESH_TOOL
? mutatingRequiresRepo
: readOnlyRequiresRepo) && REPO_SCOPED_TOOLS.has(tool.name)
? {
...tool.inputSchema,
required: [...new Set([...tool.inputSchema.required, 'repo'])],
@ -267,15 +312,16 @@ export function createMCPServer(
});
// Handle tool calls — append next-step hints to guide agent workflow
server.setRequestHandler(CallToolRequestSchema, async (request) => {
server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
const { name, arguments: args } = request.params;
let maxTokens: number | undefined;
try {
const typedArgs = args as Record<string, unknown> | undefined;
assertMcpReadOnlyToolCall(name, typedArgs, readOnly);
assertMcpRefreshToolCall(name, refreshEnabled);
const schemaSource = schemaSourceToolName(name);
const advertisedTool = GITNEXUS_TOOLS.find((tool) => tool.name === schemaSource);
const advertisedTool = findToolDefinition(schemaSource);
if (advertisedTool) {
const listed = repositoryPolicy.toolForMcp(toolForReadOnlyMcp(advertisedTool, readOnly));
assertKnownMcpToolArguments(name, typedArgs, listed.inputSchema.properties);
@ -288,8 +334,16 @@ export function createMCPServer(
responseFilter,
);
const backendArgs = isImpact ? withImpactAgentDefaults(strippedArgs) : strippedArgs;
// Only a refresh with a progress token takes a context; every other call
// keeps its exact arguments.
const callContext =
name === MCP_REFRESH_TOOL
? refreshProgress(request.params._meta?.progressToken, extra)
: undefined;
const rawResult = applyMcpResponseFilter(
await scopedBackend.callTool(name, backendArgs),
await (callContext
? scopedBackend.callTool(name, backendArgs, callContext)
: scopedBackend.callTool(name, backendArgs)),
responseFilter,
);
const hint = getNextStepHint(
@ -301,11 +355,7 @@ export function createMCPServer(
// Trim whole impact records to the budget so the JSON stays valid; the
// byte cap below remains the backstop for everything else.
const result = isImpact
? shapeImpactForAgent(
rawResult,
maxTokens,
Buffer.byteLength(hint, 'utf8') + Buffer.byteLength(MCP_TRUNCATION_MARKER, 'utf8'),
)
? shapeImpactForAgent(rawResult, maxTokens, Buffer.byteLength(hint, 'utf8'))
: rawResult;
const resultText =
name === 'query' && result !== null && typeof result === 'object' && !Array.isArray(result)
@ -325,7 +375,10 @@ export function createMCPServer(
content: [
{
type: 'text',
text: applyMcpMaxTokens(formatMcpToolError(error), maxTokens),
text:
error instanceof ImpactBudgetExceededError
? error.toJSONText()
: applyMcpMaxTokens(formatMcpToolError(error), maxTokens),
},
],
isError: true,
@ -484,10 +537,14 @@ export function installParentShutdown(
export async function startMCPServer(
backend: LocalBackend,
repositoryPolicy?: McpRepositoryPolicy,
options: { refreshIndex?: boolean } = {},
): Promise<void> {
const parentPid = process.ppid;
const validatedRepositoryPolicy = repositoryPolicy ?? (await createMcpRepositoryPolicy(backend));
const server = createMCPServer(backend, { repositoryPolicy: validatedRepositoryPolicy });
const server = createMCPServer(backend, {
repositoryPolicy: validatedRepositoryPolicy,
refreshIndex: options.refreshIndex,
});
// Idempotent global sentinel install. cli/mcp.ts calls this first thing
// (before warnMissingOptionalGrammars / backend.init can emit to stdout);

View file

@ -9,7 +9,7 @@
* actually reads.
*/
import { GITNEXUS_TOOLS } from './tools.js';
import { findToolDefinition } from './tools.js';
/** Legacy MCP names that reuse another tool's advertised schema. */
export const LEGACY_TOOL_SCHEMA_SOURCE: Readonly<Record<string, string>> = {
@ -53,7 +53,7 @@ export function schemaSourceToolName(toolName: string): string {
export function advertisedToolPropertyNames(toolName: string): string[] | undefined {
const source = schemaSourceToolName(toolName);
const tool = GITNEXUS_TOOLS.find((entry) => entry.name === source);
const tool = findToolDefinition(source);
if (!tool) return undefined;
return Object.keys(tool.inputSchema.properties);
}
@ -100,8 +100,9 @@ function formatUnknownArgumentError(
* Reject top-level tool arguments that are neither advertised nor an
* unpublished handler alias. `advertisedProperties` should be the schema the
* caller actually saw (`tools/list` after read-only / repository-policy
* scrubbing). When it is omitted, the canonical `GITNEXUS_TOOLS` schema is
* used. Tools with no schema (legacy `overview`) are left unchecked.
* scrubbing). When it is omitted, the tool's canonical schema is used
* (`findToolDefinition`: `GITNEXUS_TOOLS`, plus the opt-in `refresh_index`).
* Tools with no schema (legacy `overview`) are left unchecked.
*/
export function assertKnownMcpToolArguments(
toolName: string,

View file

@ -62,6 +62,14 @@ const DESTRUCTIVE_TOOL_ANNOTATIONS: ToolAnnotations = {
openWorldHint: false,
};
/** Rebuilds GitNexus's own index; never touches the repository's files. */
const REFRESH_TOOL_ANNOTATIONS: ToolAnnotations = {
readOnlyHint: false,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
};
/**
* Pagination bounds for the `list_repos` tool. Exported so the backend
* validation (`local-backend.ts`) and the schema below stay a single source of
@ -693,7 +701,7 @@ ${HOT_READ_STALENESS_NOTE}`,
type: 'integer',
minimum: 1,
description:
'Maximum estimated tokens in the complete formatted MCP response. Explicit request overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.',
'Token budget including hints. Trims deepest symbols; preserves counts/risk. Errors if the summary cannot fit. Overrides GITNEXUS_MCP_DEFAULT_MAX_TOKENS.',
},
timeoutMs: {
type: 'number',
@ -1119,6 +1127,45 @@ Optional caseSensitive and literal match HTTP /api/grep (default: case-insensiti
},
];
/**
* `refresh_index` (#3524) lives outside GITNEXUS_TOOLS: it is opt-in, so it is
* neither part of the default catalog nor of its byte budget. The local server
* appends it only when refresh-policy.ts enables it.
*/
export const REFRESH_INDEX_TOOL: ToolDefinition = {
name: 'refresh_index',
description: `Rebuild a registered repository's index from its working tree, for agents that see a stale index but cannot run \`gitnexus analyze\`.
Index-only: never writes AGENTS.md, CLAUDE.md, skills, hooks, or any repository file. Incremental where possible; keeps embeddings and PDG mode. Waits for the rebuild, then returns indexedAt, lastCommit, stats, and staleness before and after; clients that send a progress token get progress notifications. One refresh per repository at a time.
WHEN TO USE: staleness.status is "behind" or "diverged". Call with dry_run:true first; repositories over the server's file limit are refused.`,
annotations: REFRESH_TOOL_ANNOTATIONS,
inputSchema: {
type: 'object',
properties: {
dry_run: {
type: 'boolean',
description:
'Report staleness, file count, embeddings, and whether a refresh would run (default: false).',
default: false,
},
repo: {
type: 'string',
description:
'Repository name or path. Omit only when one repo is indexed or an MCP default is configured; dry runs included.',
},
},
required: [],
},
};
/** Schema for a tool name, including opt-in tools outside the default catalog. */
export function findToolDefinition(name: string): ToolDefinition | undefined {
return name === REFRESH_INDEX_TOOL.name
? REFRESH_INDEX_TOOL
: GITNEXUS_TOOLS.find((tool) => tool.name === name);
}
/**
* Per-repo tools that accept an optional `branch` scope (#2106). Single source
* of truth: the schema property is injected here so it cannot drift from the
@ -1129,7 +1176,7 @@ Optional caseSensitive and literal match HTTP /api/grep (default: case-insensiti
* loop below skips `branch` for `CHECKOUT_SOURCE_TOOLS` — a pin would label
* checkout bytes with another commit.
*/
export const CHECKOUT_SOURCE_TOOLS = new Set(['read_file', 'grep', 'rename']);
export const CHECKOUT_SOURCE_TOOLS = new Set(['read_file', 'grep', 'rename', 'refresh_index']);
export const REPO_SCOPED_TOOLS = new Set([
'read_file',
@ -1148,9 +1195,10 @@ export const REPO_SCOPED_TOOLS = new Set([
'shape_check',
'api_impact',
'trace',
'refresh_index',
]);
for (const tool of GITNEXUS_TOOLS) {
for (const tool of [...GITNEXUS_TOOLS, REFRESH_INDEX_TOOL]) {
// Advertises a closed schema; tools/call still fail-closes on the scrubbed key list.
// The unpublished handler aliases in tool-arguments.ts stay off this schema on
// purpose (#2175), and closing it strands no caller: every alias has an

View file

@ -1848,6 +1848,8 @@ export interface CLIConfig {
apiVersion?: string;
/** Set true when the deployment is a reasoning model (o1, o3, o4-mini). Auto-detected for OpenAI; must be set for Azure deployments. */
isReasoningModel?: boolean;
/** Completion-token limit for wiki LLM requests. Flag and GITNEXUS_MAX_COMPLETION_TOKENS win over this. */
maxCompletionTokens?: number;
}
/**

View file

@ -0,0 +1,15 @@
# Recall audit sources
`audit.json` records manually reviewed positive pairs and distinct scenarios from
PR #3686. The runtime detector still decides whether retrieved candidates are duplicates.
`retired-type-env.ts` preserves 12 pure `stripNullable` callbacks removed from
`test/unit/type-env.test.ts` after the full detector run on PR #3743 confirmed their
duplicates in `test/unit/shared-type-extractors.test.ts`. The callbacks and suite titles
were copied from commit `bd9586e008c6a2dbcd2f15598a3a20c3f2f44f03`; only the import's
relative path changed. These cases have no hooks or mocks.
The `.ts` suffix keeps this source fixture out of Vitest's `*.test.ts` discovery.
`recall-audit.test.ts` explicitly parses it, keeping all 82 positive audit pairs
while the ordinary test suite executes each of these 12 scenarios once.
The seven other `stripNullable` cases remain in `type-env.test.ts`.

View file

@ -382,73 +382,73 @@
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > strips \"| null\": User | null \u2192 User",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > strips User | null \u2192 User",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > strips User | null \u2192 User",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > strips \"| undefined\": User | undefined \u2192 User",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > strips User | undefined \u2192 User",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > strips User | undefined \u2192 User",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > strips both \"| null | undefined\": User | null | undefined \u2192 User",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > strips User | null | undefined \u2192 User",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > strips User | null | undefined \u2192 User",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > strips nullable suffix: User? \u2192 User",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > strips User? \u2192 User",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > strips User? \u2192 User",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > returns undefined for genuine union: User | Repo",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > refuses genuine union User | Repo \u2192 undefined",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > refuses genuine union User | Repo \u2192 undefined",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > returns undefined for bare \"null\"",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > returns undefined for null alone",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > returns undefined for null alone",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > returns undefined for bare \"undefined\"",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > returns undefined for undefined alone",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > returns undefined for undefined alone",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > returns undefined for bare \"None\"",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > returns undefined for None alone",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > returns undefined for None alone",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > returns undefined for bare \"nil\"",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > returns undefined for nil alone",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > returns undefined for nil alone",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > returns undefined for bare \"void\"",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > returns undefined for void alone",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > returns undefined for void alone",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > returns undefined for empty string",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > returns undefined for empty string",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > returns undefined for empty string",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},
{
"a": "test/unit/shared-type-extractors.test.ts#stripNullable > returns the type name unchanged when no nullable markers: User \u2192 User",
"b": "test/unit/type-env.test.ts#buildTypeEnv > stripNullable > passes through User unchanged",
"b": "test/fixtures/scenario-map-recall/retired-type-env.ts#buildTypeEnv > stripNullable > passes through User unchanged",
"category": "pure-helper",
"basis": "Same production function, literal inputs and expected values; source callbacks are identical. No enclosing hooks change the input."
},

View file

@ -0,0 +1,56 @@
// Static input for recall-audit.test.ts; excluded from Vitest discovery by its .ts suffix.
// Preserves the 12 duplicate callbacks removed from type-env.test.ts (see README.md).
import { describe, expect, it } from 'vitest';
import { stripNullable } from '../../../src/core/ingestion/type-extractors/shared.js';
describe('buildTypeEnv', () => {
describe('stripNullable', () => {
it('strips User | null → User', () => {
expect(stripNullable('User | null')).toBe('User');
});
it('strips User | undefined → User', () => {
expect(stripNullable('User | undefined')).toBe('User');
});
it('strips User | null | undefined → User', () => {
expect(stripNullable('User | null | undefined')).toBe('User');
});
it('strips User? → User', () => {
expect(stripNullable('User?')).toBe('User');
});
it('refuses genuine union User | Repo → undefined', () => {
expect(stripNullable('User | Repo')).toBeUndefined();
});
it('returns undefined for null alone', () => {
expect(stripNullable('null')).toBeUndefined();
});
it('returns undefined for undefined alone', () => {
expect(stripNullable('undefined')).toBeUndefined();
});
it('returns undefined for None alone', () => {
expect(stripNullable('None')).toBeUndefined();
});
it('returns undefined for nil alone', () => {
expect(stripNullable('nil')).toBeUndefined();
});
it('returns undefined for void alone', () => {
expect(stripNullable('void')).toBeUndefined();
});
it('returns undefined for empty string', () => {
expect(stripNullable('')).toBeUndefined();
});
it('passes through User unchanged', () => {
expect(stripNullable('User')).toBe('User');
});
});
});

View file

@ -0,0 +1,163 @@
/**
* #3747: a member edge must never name an owner node the file did not emit.
* Both fixtures are the reporter's repro; before the fix each produced one
* HAS_METHOD edge that LadybugDB's COPY rejected with
* "Unable to find primary key value".
*/
import { describe, expect, it } from 'vitest';
import fs from 'node:fs/promises';
import path from 'node:path';
import { pathToFileURL } from 'node:url';
import {
closeLbug,
executeQuery,
initLbug,
loadGraphToLbug,
} from '../../src/core/lbug/lbug-adapter.js';
import { runPipelineFromRepo } from '../../src/core/ingestion/pipeline.js';
import { createTempDir } from '../helpers/test-db.js';
import { DIST_WORKER_URL, parseFilesWithWorkers } from '../helpers/worker-parse.js';
import { createWorkerPool } from '../../src/core/ingestion/workers/worker-pool.js';
import type {
ParseWorkerInput,
ParseWorkerResult,
} from '../../src/core/ingestion/workers/parse-worker.js';
import { findDanglingEdges } from './resolvers/helpers.js';
const CHAINED_CONST = `import { z } from 'zod';
const KEY = 'BRANCH';
const Branch = z.string();
const Context = z
.object({
REF: z.string(),
[KEY]: Branch,
REPO: z.string().refine((value) => value.split('/').every((p) => p !== '..')),
})
.refine((context) => context.REF === \`refs/heads/\${context[KEY]}\`, {
message: 'REF must be the branch head',
});
export function run(env) {
const context = Context.parse(env);
return context;
}
`;
const AMBIENT_MODULE = `declare module 'somelib' {
export function connect(opts: { user: string }): Promise<void>;
const lib: { connect: typeof connect };
export default lib;
}
`;
const OBJECT_LITERAL_CONTROL = `export const service = {
load() { return 1; },
save: () => 2,
};
`;
describe('#3747 member edges only name emitted owners', () => {
it('leaves no dangling member edge and keeps every member reachable from its file', async () => {
const { graph } = await parseFilesWithWorkers([
{ path: 'ctx.mjs', content: CHAINED_CONST },
{ path: 'types/lib.d.ts', content: AMBIENT_MODULE },
]);
expect(findDanglingEdges({ graph } as never, ['HAS_METHOD', 'HAS_PROPERTY'])).toEqual([]);
const definedFromFile = (file: string): string[] =>
graph.relationships
.filter((edge) => edge.type === 'DEFINES' && edge.sourceId === `File:${file}`)
.map((edge) => edge.targetId);
const repo = graph.nodes.find(
(n) => n.properties.filePath === 'ctx.mjs' && n.properties.name === 'REPO',
);
const connect = graph.nodes.find(
(n) => n.properties.filePath === 'types/lib.d.ts' && n.properties.name === 'connect',
);
expect(repo).toBeDefined();
expect(connect).toBeDefined();
expect(definedFromFile('ctx.mjs')).toContain(repo?.id);
expect(definedFromFile('types/lib.d.ts')).toContain(connect?.id);
});
it('keeps object-literal members owned by their emitted binding', async () => {
const { graph } = await parseFilesWithWorkers([
{ path: 'service.ts', content: OBJECT_LITERAL_CONTROL },
]);
const owner = graph.nodes.find(
(n) => n.properties.filePath === 'service.ts' && n.properties.name === 'service',
);
expect(owner).toBeDefined();
const members = graph.relationships
.filter((edge) => edge.type === 'HAS_METHOD' && edge.sourceId === owner?.id)
.map((edge) => graph.getNode(edge.targetId)?.properties.name)
.sort();
expect(members).toEqual(['load', 'save']);
});
it('persists every relationship through native COPY', async () => {
const temp = await createTempDir();
try {
await fs.mkdir(path.join(temp.dbPath, 'types'), { recursive: true });
await fs.writeFile(path.join(temp.dbPath, 'ctx.mjs'), CHAINED_CONST);
await fs.writeFile(path.join(temp.dbPath, 'types', 'lib.d.ts'), AMBIENT_MODULE);
const result = await runPipelineFromRepo(temp.dbPath, () => {}, { workerPoolSize: 1 });
expect(result.usedWorkerPool).toBe(true);
expect(findDanglingEdges(result)).toEqual([]);
await initLbug(path.join(temp.dbPath, 'lbug'), { skipFts: true });
await loadGraphToLbug(result.graph, temp.dbPath, path.join(temp.dbPath, 'storage'));
const [row] = await executeQuery('MATCH ()-[r:CodeRelation]->() RETURN count(r) AS edges');
expect(Number(row.edges)).toBe(result.graph.relationships.length);
} finally {
await closeLbug();
await temp.cleanup();
}
});
it('settles the partial file when a real parser provider throws after emitting members', async () => {
const temp = await createTempDir();
const bootstrap = path.join(temp.dbPath, 'throwing-provider.mjs');
const providersUrl = new URL('../languages/index.js', DIST_WORKER_URL).href;
// Inject the failure in the worker isolate, leaving the production loop and
// its finally intact. Removing that finally must make this regression fail.
await fs.writeFile(
bootstrap,
`
const { getProvider } = await import(${JSON.stringify(providersUrl)});
getProvider('javascript').extractToolDefinitions = () => {
throw new Error('owner-edge-guard provider fault');
};
await import(${JSON.stringify(DIST_WORKER_URL.href)});
`,
);
const pool = createWorkerPool(pathToFileURL(bootstrap), 1);
try {
const [result] = await pool.dispatch<ParseWorkerInput, ParseWorkerResult>([
{ path: 'ctx.mjs', content: CHAINED_CONST },
{ path: 'after.mjs', content: 'export function shouldNotParse() {}' },
]);
// The first file is counted before the provider throws; the remaining
// file is skipped, proving the injected failure reached processBatch.
expect(result.fileCount).toBe(1);
expect(result.nodes.some((node) => node.properties.name === 'shouldNotParse')).toBe(false);
const member = result.nodes.find((node) => node.properties.name === 'REPO');
expect(member).toBeDefined();
expect(result.relationships.filter((edge) => edge.targetId === member?.id)).toEqual([
{
id: `DEFINES:File:ctx.mjs->${member?.id}`,
sourceId: 'File:ctx.mjs',
targetId: member?.id,
type: 'DEFINES',
confidence: 1,
reason: '',
},
]);
} finally {
await pool.terminate();
await temp.cleanup();
}
});
});

View file

@ -11,6 +11,103 @@ import { getStoragePaths, registerRepo, saveMeta } from '../../src/storage/repo-
import { createTempDir } from '../helpers/test-db.js';
const REPO = 'query-integrity';
describe.each(['current', 'without staticGated'] as const)('native impact schema: %s', (schema) => {
let temp: Awaited<ReturnType<typeof createTempDir>>;
let backend: LocalBackend;
let lbugPath: string;
beforeAll(async () => {
temp = await createTempDir();
vi.stubEnv('GITNEXUS_HOME', path.join(temp.dbPath, 'home'));
vi.stubEnv('GITNEXUS_STORAGE_PATH', path.join(temp.dbPath, 'index'));
vi.stubEnv('GITNEXUS_SHARED_STORE', 'off');
const paths = getStoragePaths(temp.dbPath);
lbugPath = paths.lbugPath;
await adapter.initLbug(lbugPath);
try {
for (const name of ['target', 'caller', 'root']) {
await adapter.executeQuery(
`CREATE (:Function {id: 'Function:src/${name}.ts:${name}', name: '${name}', filePath: 'src/${name}.ts', startLine: 1, endLine: 3})`,
);
}
for (const [caller, callee, gated] of [
['caller', 'target', true],
['root', 'caller', false],
]) {
await adapter.executeQuery(
`MATCH (a:Function {name: '${caller}'}), (b:Function {name: '${callee}'}) CREATE (a)-[:CodeRelation {type: 'CALLS', confidence: 1.0, staticGated: ${gated}}]->(b)`,
);
}
if (schema === 'without staticGated') {
await adapter.executeQuery('ALTER TABLE CodeRelation DROP staticGated');
}
await adapter.flushWAL();
} finally {
await adapter.closeLbug();
}
const meta = {
repoPath: temp.dbPath,
storagePath: paths.storagePath,
lastCommit: 'legacy-fixture',
indexedAt: new Date().toISOString(),
scopeExtractionReceipt: 1 as const,
stats: { files: 3, nodes: 3, processes: 0, communities: 0 },
};
await saveMeta(paths.storagePath, meta);
await registerRepo(temp.dbPath, meta, { name: REPO });
backend = new LocalBackend();
expect(await backend.init()).toBe(true);
});
afterAll(async () => {
try {
await backend?.dispose();
} finally {
await adapter.closeLbug();
vi.unstubAllEnvs();
await temp?.cleanup();
}
});
it.each(['upstream', 'downstream'] as const)(
'walks two levels %s after a schema miss',
async (direction) => {
const result = await backend.callTool('impact', {
repo: REPO,
target: direction === 'upstream' ? 'target' : 'root',
direction,
maxDepth: 3,
});
if (schema === 'without staticGated') {
// The backend opens its pool lazily. Verify that a successful walk
// did not depend on adding the missing property to the database.
await expect(
executeParameterized(
lbugPath,
'MATCH ()-[r:CodeRelation]->() RETURN r.staticGated AS staticGated',
{},
),
).rejects.toThrow(/Cannot find property staticGated for r/);
}
expect(result).not.toHaveProperty('error');
expect(result).not.toHaveProperty('partial');
expect(result.impactedCount).toBe(2);
expect(result.byDepthCounts).toEqual({ 1: 1, 2: 1 });
expect(result.byDepth[1].map((item: any) => item.name)).toEqual(['caller']);
expect(result.byDepth[2].map((item: any) => item.name)).toEqual([
direction === 'upstream' ? 'root' : 'target',
]);
const gatedDepth = direction === 'upstream' ? 1 : 2;
if (schema === 'current') expect(result.byDepth[gatedDepth][0].staticGated).toBe(true);
else {
for (const depth of [1, 2])
expect(result.byDepth[depth][0]).not.toHaveProperty('staticGated');
}
},
);
});
const nodes = {
alpha: { id: 'Function:src/alpha.ts:runSweep', name: 'runSweep', filePath: 'src/alpha.ts' },
alphaCaller: {

View file

@ -566,3 +566,82 @@ withTestLbugDB('embedding-row-dml-vector-gate', (handle) => {
}, 120_000);
});
});
/**
* Delete-all-then-recopy of a table that spans more than one native vector.
*
* @ladybugdb/core 0.21.0 and 0.21.1 returned every row of such a table twice
* once the incremental writeback had DETACH DELETEd it and a COPY into an
* earlier table had run: `NodeGroup::scan` let a morsel that ended before the
* group's first live row wrap an unsigned subtraction and rescan to the end of
* the group (LadybugDB #1085, fixed in 0.21.2). No primary-key error fires, so
* the only symptom was `Graph identity reconciliation failed … duplicate ID`
* on repos with more than 2048 symbols of one label (Swift structs in the
* report that found it), and 2×-inflated counts for anything that scanned.
*
* The statement order below is the one `runFullAnalysisInner` issues: delete the
* write set's rows, then COPY File before the symbol tables.
*/
withTestLbugDB('delete-recopy-multi-vector-table', (handle) => {
describe('deleteNodesForFiles then loadGraphToLbug on a multi-vector table', () => {
// One native vector holds 2048 rows; 2049 is the smallest table that spans two.
const STRUCT_COUNT = 2049;
const STRUCTS_PER_FILE = 64;
const fileOf = (i: number): string => `Sources/S${Math.floor(i / STRUCTS_PER_FILE)}.swift`;
const buildStructGraph = () => {
const nodes: TestNodeInput[] = [];
const rels: TestRelInput[] = [];
const files = new Set<string>();
for (let i = 0; i < STRUCT_COUNT; i++) {
const fp = fileOf(i);
if (!files.has(fp)) {
files.add(fp);
nodes.push({ id: `File:${fp}`, label: 'File', name: path.basename(fp), filePath: fp });
}
const id = `Struct:${fp}:S${i}`;
nodes.push({
id,
label: 'Struct',
name: `S${i}`,
filePath: fp,
startLine: 1,
endLine: 3,
});
rels.push({ sourceId: `File:${fp}`, targetId: id, type: 'CONTAINS' });
}
return { graph: buildTestGraph(nodes, rels), filePaths: [...files] };
};
it('returns each struct and its edge exactly once after the rows were deleted and re-copied', async () => {
const { loadGraphToLbug, deleteNodesForFiles, executeQuery } =
await import('../../src/core/lbug/lbug-adapter.js');
const storagePath = path.dirname(handle.dbPath);
const structIds = async (): Promise<string[]> =>
((await executeQuery('MATCH (n:Struct) RETURN n.id AS id')) as Array<{ id: string }>).map(
(r) => String(r.id),
);
const containsEdges = async (): Promise<number> => {
const rows = (await executeQuery(
`MATCH (:File)-[r:CodeRelation]->(:Struct) WHERE r.type = 'CONTAINS' RETURN count(r) AS c`,
)) as Array<{ c: number | bigint }>;
return Number(rows[0]?.c ?? 0);
};
const { graph, filePaths } = buildStructGraph();
await loadGraphToLbug(graph, '/tmp/repo', storagePath);
expect(new Set(await structIds()).size).toBe(STRUCT_COUNT);
// Every file is in the write set, as when a Swift edit pulls in all importers.
await deleteNodesForFiles(filePaths);
expect(await structIds()).toEqual([]);
await loadGraphToLbug(graph, '/tmp/repo', storagePath);
const ids = await structIds();
expect(ids).toHaveLength(STRUCT_COUNT);
expect(new Set(ids).size).toBe(STRUCT_COUNT);
expect(await containsEdges()).toBe(STRUCT_COUNT);
}, 120_000);
});
});

View file

@ -202,7 +202,7 @@ describe('interrupted-checkpoint recovery (pooled read path self-heal)', () => {
await probe.close().catch(() => {});
}
})(),
).rejects.toThrow(/checkpoint is in progress/i);
).rejects.toThrow(/checkpoint (?:is in progress|recovery is pending)/i);
// The wiki path: pooled READ-ONLY open. Before the fix this refused with
// "Cannot open database in read-only mode while checkpoint is in

View file

@ -0,0 +1,73 @@
import fs from 'node:fs/promises';
import path from 'node:path';
import lbug from '@ladybugdb/core';
import { expect, it } from 'vitest';
import { createTempDir } from '../helpers/test-db.js';
// LadybugDB #1059/#1091: uncompressed relationship COPY allocated whole pages
// but wrote only the payload. On 0.21.1 this fixture leaves the file 3,936 bytes
// short; an immediate scan can still pass while the pages remain buffered.
it('pads uncheckpointed relationship COPY pages and preserves their rows', async () => {
const temp = await createTempDir();
const dbPath = path.join(temp.dbPath, 'lbug');
const db = new lbug.Database(dbPath, 64 * 1024 * 1024, false, false, 1024 ** 3, false);
const conn = new lbug.Connection(db);
const query = async (cypher: string): Promise<Array<Record<string, unknown>>> => {
const raw = await conn.query(cypher);
const rows: Array<Record<string, unknown>> = [];
for (const result of Array.isArray(raw) ? raw : [raw]) {
try {
rows.push(...(await result.getAll()));
} finally {
result.close();
}
}
return rows;
};
try {
await query('CALL force_checkpoint_on_close=false');
await query('CREATE NODE TABLE N(id INT64 PRIMARY KEY)');
await query('CREATE REL TABLE R(FROM N TO N, weight INT64)');
await query('UNWIND range(0, 999) AS i CREATE (:N {id: i})');
await query('CHECKPOINT');
const expected = Array.from({ length: 1000 }, (_, i) => ({
source: i,
target: (i + 1) % 1000,
weight: i,
}));
const csvPath = path.join(temp.dbPath, 'rels.csv');
await fs.writeFile(
csvPath,
expected.map(({ source, target, weight }) => `${source},${target},${weight}\n`).join(''),
);
const csvLiteral = csvPath.replace(/\\/g, '/').replace(/'/g, "\\'");
await query(`COPY R FROM '${csvLiteral}' (HEADER=false, PARALLEL=false)`);
// Check before a scan or checkpoint can conceal the short native flush.
expect((await fs.stat(dbPath)).size % 4096).toBe(0);
const scan = `MATCH (a:N)-[r:R]->(b:N)
RETURN a.id AS source, b.id AS target, r.weight AS weight ORDER BY weight`;
expect(await query(scan)).toEqual(expected);
await query(
'MATCH (a:N), (b:N) WHERE a.id = 0 AND b.id = 500 CREATE (a)-[:R {weight: 1000}]->(b)',
);
expected.push({ source: 0, target: 500, weight: 1000 });
expect(await query(scan)).toEqual(expected);
await query('CHECKPOINT');
expect((await fs.stat(dbPath)).size % 4096).toBe(0);
expect(await query(scan)).toEqual(expected);
} finally {
try {
await conn.close();
} finally {
try {
await db.close();
} finally {
await temp.cleanup();
}
}
}
}, 120_000);

View file

@ -0,0 +1,212 @@
/**
* #3524, end to end: a real analyze, a new commit that leaves the index behind,
* then `refresh_index` through LocalBackend with the real analyze worker. The
* refresh must bring the index to HEAD without touching anything git tracks or
* creating the agent files a plain `gitnexus analyze` writes. analyze hides
* its own storage, `.gitnexus/`, through `.git/info/exclude`, so the check also
* lists ignored paths and allows none outside that directory.
*/
import { execFileSync } from 'node:child_process';
import { existsSync } from 'node:fs';
import fs from 'node:fs/promises';
import path from 'node:path';
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
import { runFullAnalysis } from '../../src/core/run-analyze.js';
import { LocalBackend } from '../../src/mcp/local/local-backend.js';
import { commitAll, initGitRepo } from '../helpers/temp-git-repo.js';
import { createTempDir } from '../helpers/test-db.js';
const CLAUDE_MD = '# Team notes\n\nHand-written; no GitNexus block.\n';
function git(repo: string, ...args: string[]): string {
return execFileSync('git', args, { cwd: repo, encoding: 'utf-8' }).trim();
}
describe('refresh_index through a real analyze worker (#3524)', () => {
let temp: Awaited<ReturnType<typeof createTempDir>>;
let repo: string;
let backend: LocalBackend;
let indexedCommit: string;
let head: string;
beforeAll(async () => {
temp = await createTempDir();
const root = await fs.realpath(temp.dbPath);
const userHome = path.join(root, 'user-home');
await fs.mkdir(userHome);
vi.stubEnv('HOME', userHome);
vi.stubEnv('USERPROFILE', userHome);
vi.stubEnv('GITNEXUS_HOME', path.join(root, 'home'));
vi.stubEnv('GITNEXUS_STORAGE_PATH', undefined);
vi.stubEnv('GITNEXUS_STORAGE_ROOT', undefined);
vi.stubEnv('GITNEXUS_SHARED_STORE', 'off');
vi.stubEnv('GITNEXUS_ATOMIC_INCREMENTAL', undefined);
vi.stubEnv('GITNEXUS_ATOMIC_WINDOWS_SWAP', undefined);
vi.stubEnv('GITNEXUS_LBUG_EXTENSION_INSTALL', 'load-only');
vi.stubEnv('GITNEXUS_WAL_MANUAL_CHECKPOINT', '1');
vi.stubEnv('GITNEXUS_MCP_REFRESH_MAX_FILES', undefined);
vi.stubEnv('GITNEXUS_MCP_REFRESH_TIMEOUT_MS', undefined);
repo = path.join(root, 'repo');
await fs.mkdir(path.join(repo, 'src'), { recursive: true });
await fs.writeFile(
path.join(repo, 'src', 'orders.ts'),
'export function placeOrder(id: string) { return `order:${id}`; }\n',
);
await fs.writeFile(path.join(repo, 'CLAUDE.md'), CLAUDE_MD);
initGitRepo(repo);
git(repo, 'config', 'commit.gpgsign', 'false');
commitAll(repo, 'initial');
await runFullAnalysis(repo, { skipAgentsMd: true, skipSkills: true }, { onProgress: () => {} });
indexedCommit = git(repo, 'rev-parse', 'HEAD');
await fs.writeFile(
path.join(repo, 'src', 'invoices.ts'),
[
"import { placeOrder } from './orders';",
'export function issueInvoice(id: string) { return placeOrder(id); }',
'',
].join('\n'),
);
commitAll(repo, 'add invoices');
head = git(repo, 'rev-parse', 'HEAD');
backend = new LocalBackend();
await backend.init();
}, 180_000);
afterAll(async () => {
await backend?.dispose();
vi.unstubAllEnvs();
await temp?.cleanup();
});
it('reports the stale index on a dry run without rebuilding it', async () => {
const result = await backend.callTool('refresh_index', { repo, dry_run: true });
expect(result).toMatchObject({
status: 'dry_run',
wouldRefresh: true,
lastCommit: indexedCommit,
staleness: { status: 'behind', commitsBehind: 1 },
// Counted in the working tree, so the commit's new file is included;
// CLAUDE.md is indexed too.
estimatedFiles: 3,
lastIndexedFiles: 2,
});
const list = await backend.callTool('list_repos', {});
expect(list.repositories[0].lastCommit).toBe(indexedCommit);
});
it('refreshes with an open reader and concurrent query without touching source files', async () => {
const read = () =>
backend.callTool('cypher', {
repo,
statement: 'MATCH (n:Function) RETURN n.name AS name ORDER BY n.name',
});
const oldRows = '| name |\n| --- |\n| placeOrder |';
const newRows = '| name |\n| --- |\n| issueInvoice |\n| placeOrder |';
const before = await read();
expect(before).toMatchObject({
row_count: 1,
markdown: oldRows,
staleness: { status: 'behind', lastCommit: indexedCommit },
});
// The first query leaves the native pool open. Start another query from
// real worker progress, so it overlaps refresh without holding a query
// past its own deadline on slower CI hosts.
let concurrentRead: ReturnType<typeof read> | undefined;
let result = await backend.callTool(
'refresh_index',
{ repo },
{
onProgress: () => {
concurrentRead ??= read();
},
},
);
expect(concurrentRead).toBeDefined();
const during = await concurrentRead;
expect(during).not.toHaveProperty('error');
// Scheduling may let the query observe either generation, but never a
// partial inventory or old rows labelled with the new commit.
expect([
{ row_count: 1, markdown: oldRows, lastCommit: indexedCommit },
{ row_count: 2, markdown: newRows, lastCommit: head },
]).toContainEqual({
row_count: during.row_count,
markdown: during.markdown,
lastCommit: during.staleness.lastCommit,
});
// POSIX publishes a staged database while readers retain the old inode.
// Windows defaults to in-place writes, which may refuse the open reader;
// require an explicit lock error, an unchanged index, and a successful retry.
if (process.platform === 'win32' && result.error) {
expect(result.error).toMatch(
/could not set lock on file|database.*(?:locked|busy)|(?:locked|busy).*database/i,
);
const list = await backend.callTool('list_repos', {});
expect(list.repositories[0].lastCommit).toBe(indexedCommit);
await backend.dispose();
await backend.init();
result = await backend.callTool('refresh_index', { repo });
}
expect(result).toMatchObject({
status: 'refreshed',
previous: { lastCommit: indexedCommit, staleness: { status: 'behind' } },
lastCommit: head,
staleness: { status: 'current' },
stats: { files: 3 },
});
expect(git(repo, 'status', '--porcelain', '--untracked-files=all')).toBe('');
const ignored = git(repo, 'status', '--porcelain', '--ignored', '--untracked-files=all')
.split('\n')
.filter(Boolean);
expect(ignored.length).toBeGreaterThan(0);
expect(ignored.filter((line) => !line.startsWith('!! .gitnexus/'))).toEqual([]);
expect(await fs.readFile(path.join(repo, 'CLAUDE.md'), 'utf-8')).toBe(CLAUDE_MD);
expect(existsSync(path.join(repo, 'AGENTS.md'))).toBe(false);
expect(existsSync(path.join(repo, '.claude'))).toBe(false);
// The same backend serves the rebuilt index without a restart.
const found = await backend.callTool('context', { name: 'issueInvoice', repo });
expect(found).not.toHaveProperty('error');
expect(found.symbol).toMatchObject({ name: 'issueInvoice', filePath: 'src/invoices.ts' });
expect(found.staleness).toMatchObject({ status: 'current', lastCommit: head });
expect(await read()).toMatchObject({
row_count: 2,
markdown: newRows,
staleness: { status: 'current', lastCommit: head },
});
}, 180_000);
it('refuses once the working tree outgrows the limit, whatever the last index counted', async () => {
// The index at HEAD recorded 3 files, under the limit; the tree now holds 5.
for (const name of ['refunds', 'shipping']) {
await fs.writeFile(path.join(repo, 'src', `${name}.ts`), `export const ${name} = 1;\n`);
}
commitAll(repo, 'add refunds and shipping');
vi.stubEnv('GITNEXUS_MCP_REFRESH_MAX_FILES', '4');
try {
const dryRun = await backend.callTool('refresh_index', { repo, dry_run: true });
expect(dryRun).toMatchObject({
status: 'dry_run',
staleness: { status: 'behind' },
estimatedFiles: null,
lastIndexedFiles: 3,
maxFiles: 4,
wouldRefresh: false,
refusal: expect.stringMatching(/more than 4 files in its working tree/),
});
await expect(backend.callTool('refresh_index', { repo })).resolves.toEqual({
error: dryRun.refusal,
});
// No worker ran: the index still stops at the previous commit.
const list = await backend.callTool('list_repos', {});
expect(list.repositories[0].lastCommit).toBe(head);
} finally {
vi.stubEnv('GITNEXUS_MCP_REFRESH_MAX_FILES', undefined);
}
});
});

View file

@ -7,6 +7,7 @@ import { fileURLToPath } from 'url';
import type { GraphNode, RelationshipType } from 'gitnexus-shared';
import { runPipelineFromRepo } from '../../src/core/ingestion/pipeline.js';
import { runFullAnalysis } from '../../src/core/run-analyze.js';
import { getEffectiveBufferPoolSize } from '../../src/core/lbug/lbug-config.js';
import { LocalBackend } from '../../src/mcp/local/local-backend.js';
import { classifyObjectiveCFileContent } from '../../src/core/ingestion/languages/objective-c.js';
import type { PipelineResult } from '../../src/types/pipeline.js';
@ -213,6 +214,7 @@ async function analyzeObjectiveCRepo(
options: { force?: boolean } = {},
): Promise<string[]> {
const logs: string[] = [];
const readerBudget = getEffectiveBufferPoolSize();
await runFullAnalysis(
repoRoot,
{
@ -226,6 +228,7 @@ async function analyzeObjectiveCRepo(
onLog: (message) => logs.push(message),
},
);
expect(getEffectiveBufferPoolSize()).toBe(readerBudget);
return logs;
}

View file

@ -62,6 +62,14 @@ describe('query identity boundary through the real MCP server', () => {
await fs.mkdir(path.join(repo, 'src'), { recursive: true });
await fs.writeFile(path.join(repo, '.gitignore'), '.gitnexus/\n');
await fs.writeFile(path.join(repo, 'src/fixture.ts'), SOURCE);
await fs.writeFile(
path.join(repo, 'src/fixture.py'),
'class Fixture:\n def integrityNeedle(self):\n return 42\n',
);
await fs.writeFile(
path.join(repo, 'src/fixture.swift'),
'struct IntegrityNeedle {\n let value = 42\n}\n',
);
initGitRepo(repo);
execFileSync('git', ['config', 'commit.gpgsign', 'false'], { cwd: repo });
commitAll(repo, 'source-derived query fixture');
@ -148,7 +156,7 @@ describe('query identity boundary through the real MCP server', () => {
'bounds source previews in native queries without losing matches (%#)',
async (source) => {
const setSource = async () => {
for (const label of ['Function', 'File']) {
for (const label of ['Function', 'Class', 'Method', 'Struct', 'File']) {
await adapter.executePrepared(`MATCH (n:${label}) SET n.content = $source`, { source });
}
};
@ -188,6 +196,11 @@ describe('query identity boundary through the real MCP server', () => {
);
it.each([
[
'path inconsistent with the symbol UID',
'MATCH (n:Function {id: $uid}) SET n.filePath = $value',
'Sources/Unrelated.swift',
],
['NUL symbol name', 'MATCH (n:Function {id: $uid}) SET n.name = $value', 'invalid\0name'],
['NUL symbol path', 'MATCH (n:Function {id: $uid}) SET n.filePath = $value', 'invalid\0path'],
['NUL process label', 'MATCH (p:Process) SET p.label = $value', 'invalid\0process'],
@ -218,6 +231,35 @@ describe('query identity boundary through the real MCP server', () => {
expect(result).not.toHaveProperty('definitions');
});
it.each([
{
table: 'Method',
uid: 'Method:src/fixture.py:Fixture.integrityNeedle#0',
field: 'filePath',
value: 'src/fixture.swift',
},
{
table: 'Struct',
uid: 'Struct:src/fixture.swift:IntegrityNeedle',
field: 'name',
value: '\0\0\0\0',
},
])('rejects the injected #3527 $table/$field shape', async ({ table, uid, field, value }) => {
const result = await query(async () => {
// Prove the source-derived fixture contains the target before injecting the fault.
expect(
await adapter.executePrepared(`MATCH (n:${table} {id: $uid}) RETURN n.id AS id`, { uid }),
).toEqual([{ id: uid }]);
await adapter.executePrepared(`MATCH (n:${table} {id: $uid}) SET n.${field} = $value`, {
uid,
value,
});
});
expect(result.error).toContain('invalid symbol identity');
expect(result.recoverySuggestion).toBe(SYMBOL_IDENTITY_RECOVERY_SUGGESTION);
expect(result).not.toHaveProperty('definitions');
});
it('accepts legacy missing process entry points and empty optional labels', async () => {
const result = await query(async () => {
await adapter.executeQuery(

View file

@ -189,14 +189,6 @@ describe('COBOL parsing coverage (F17-F23)', () => {
// F23: PERFORM TIMES + THRU on digit-leading targets
// =====================================================================
describe('F23 — PERFORM TIMES and THRU', () => {
it('PERFORM 2000-PROCESS THRU 2100-CLEANUP resolves THRU target', () => {
const perfThruEdges = getRelationships(result, 'CALLS').filter(
(e) => e.rel.reason === 'cobol-perform-thru',
);
const thruTargets = perfThruEdges.map((e) => e.target);
expect(thruTargets).toContain('2100-CLEANUP');
});
it('PERFORM with VARYING does NOT create spurious CALLS edge', () => {
// PERFTIMS has PERFORM VARYING WS-COUNT FROM 1 BY 1...
// VARYING is in PERFORM_KEYWORD_SKIP, so it should be skipped.

View file

@ -937,18 +937,6 @@ describe('C# assignment chain propagation', () => {
expect(saveMethods.length).toBe(2);
});
it('resolves alias.Save() to User#Save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
// Positive: alias.Save() must resolve to User#Save
const userSave = calls.find(
(c) =>
c.target === 'Save' &&
c.source === 'ProcessEntities' &&
c.targetFilePath.includes('User.cs'),
);
expect(userSave).toBeDefined();
});
it('alias.Save() does NOT resolve to Repo#Save', () => {
const calls = getRelationships(result, 'CALLS');
// Negative: alias comes from User, so only one edge to User.cs
@ -961,18 +949,6 @@ describe('C# assignment chain propagation', () => {
expect(wrongCall.length).toBe(1);
});
it('resolves rAlias.Save() to Repo#Save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
// Positive: rAlias.Save() must resolve to Repo#Save
const repoSave = calls.find(
(c) =>
c.target === 'Save' &&
c.source === 'ProcessEntities' &&
c.targetFilePath.includes('Repo.cs'),
);
expect(repoSave).toBeDefined();
});
it('each alias resolves to its own class, not the other', () => {
const calls = getRelationships(result, 'CALLS');
const userSave = calls.find(

View file

@ -290,13 +290,6 @@ describe.skipIf(!dartAvailable)('Dart method enrichment', () => {
expect(speak!.properties.isAbstract).toBe(true);
});
it('marks breathe as NOT isAbstract', () => {
const methods = getNodesByLabelFull(result, 'Method');
const breathe = methods.find((n) => n.name === 'breathe');
expect(breathe).toBeDefined();
expect(breathe!.properties.isAbstract).toBe(false);
});
it('marks classify as isStatic', () => {
const methods = getNodesByLabelFull(result, 'Method');
const classify = methods.find((n) => n.name === 'classify');

View file

@ -980,18 +980,6 @@ describe('Go assignment chain propagation', () => {
expect(saveMethods.length).toBe(2);
});
it('resolves alias.Save() to User#Save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
// Positive: alias.Save() must resolve to User#Save
const userSave = calls.find(
(c) =>
c.target === 'Save' &&
c.source === 'processEntities' &&
c.targetFilePath.includes('user.go'),
);
expect(userSave).toBeDefined();
});
it('alias.Save() does NOT resolve to Repo#Save', () => {
const calls = getRelationships(result, 'CALLS');
// Negative: alias comes from User, so only one edge to user.go
@ -1004,18 +992,6 @@ describe('Go assignment chain propagation', () => {
expect(wrongCall.length).toBe(1);
});
it('resolves rAlias.Save() to Repo#Save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
// Positive: rAlias.Save() must resolve to Repo#Save
const repoSave = calls.find(
(c) =>
c.target === 'Save' &&
c.source === 'processEntities' &&
c.targetFilePath.includes('repo.go'),
);
expect(repoSave).toBeDefined();
});
it('each alias resolves to its own struct, not the other', () => {
const calls = getRelationships(result, 'CALLS');
const userSave = calls.find(
@ -1729,17 +1705,9 @@ describe('Go pointer-receiver field chains (#2766)', () => {
expect(calls()).toContain('RunLocal → DoWork');
});
it('keeps resolving a value receiver', () => {
expect(calls()).toContain('RunFromValueReceiver → DoWork');
});
// U8: the same-package field receiver that previously produced an ACCESSES
// edge to the method and no CALLS edge. Typing the base is what emits CALLS;
// the ACCESSES now correctly targets the PROPERTY being read instead.
it('emits CALLS for a same-package field receiver, not ACCESSES alone', () => {
expect(calls()).toContain('RunSamePackage → Work');
});
it('retargets the field ACCESSES to the property, not the method', () => {
// Unlabeled on purpose: the negative must reject `→ Work` under ANY target
// kind, which the kind-qualified rows below cannot express.

View file

@ -1058,18 +1058,6 @@ describe('Java assignment chain propagation', () => {
expect(saveMethods.length).toBe(2);
});
it('resolves alias.save() to User#save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
// Positive: alias.save() must resolve to User#save
const userSave = calls.find(
(c) =>
c.target === 'save' &&
c.source === 'processEntities' &&
c.targetFilePath.includes('User.java'),
);
expect(userSave).toBeDefined();
});
it('alias.save() does NOT resolve to Repo#save', () => {
const calls = getRelationships(result, 'CALLS');
// Negative: alias comes from User, so only one edge to User.java
@ -1082,18 +1070,6 @@ describe('Java assignment chain propagation', () => {
expect(wrongCall.length).toBe(1);
});
it('resolves rAlias.save() to Repo#save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
// Positive: rAlias.save() must resolve to Repo#save
const repoSave = calls.find(
(c) =>
c.target === 'save' &&
c.source === 'processEntities' &&
c.targetFilePath.includes('Repo.java'),
);
expect(repoSave).toBeDefined();
});
it('each alias resolves to its own class, not the other', () => {
const calls = getRelationships(result, 'CALLS');
const userSave = calls.find(
@ -1134,28 +1110,6 @@ describe('Java Optional<User> receiver resolution via wrapper unwrapping', () =>
expect(saveMethods.length).toBe(2);
});
it('resolves user.save() to User#save with Optional<User> in scope', () => {
const calls = getRelationships(result, 'CALLS');
const userSave = calls.find(
(c) =>
c.target === 'save' &&
c.source === 'processEntities' &&
c.targetFilePath?.includes('User.java'),
);
expect(userSave).toBeDefined();
});
it('resolves repo.save() to Repo#save alongside Optional usage', () => {
const calls = getRelationships(result, 'CALLS');
const repoSave = calls.find(
(c) =>
c.target === 'save' &&
c.source === 'processEntities' &&
c.targetFilePath?.includes('Repo.java'),
);
expect(repoSave).toBeDefined();
});
it('disambiguates user.save() and repo.save() to different files', () => {
const calls = getRelationships(result, 'CALLS');
const userSave = calls.find(

View file

@ -831,28 +831,6 @@ describe('Kotlin assignment chain propagation', () => {
expect(saveMethods.length).toBe(2);
});
it('resolves alias.save() to User#save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
const userSave = calls.find(
(c) =>
c.target === 'save' &&
c.source === 'processEntities' &&
c.targetFilePath.includes('User.kt'),
);
expect(userSave).toBeDefined();
});
it('resolves rAlias.save() to Repo#save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
const repoSave = calls.find(
(c) =>
c.target === 'save' &&
c.source === 'processEntities' &&
c.targetFilePath.includes('Repo.kt'),
);
expect(repoSave).toBeDefined();
});
it('alias.save() does NOT resolve to Repo#save', () => {
const calls = getRelationships(result, 'CALLS');
// There should be exactly one save() call targeting User.kt from processEntities
@ -1533,14 +1511,6 @@ describe('Write access tracking (Kotlin)', () => {
expect(scoreWrite!.source).toBe('updateUser');
});
it('emits ACCESSES write edge for compound assignment (+=)', () => {
const accesses = getRelationships(result, 'ACCESSES');
const writes = accesses.filter((e) => e.rel.reason === 'write');
const scoreWrite = writes.find((e) => e.target === 'score');
expect(scoreWrite).toBeDefined();
expect(scoreWrite!.source).toBe('updateUser');
});
it('write ACCESSES edges have confidence 1.0', () => {
const accesses = getRelationships(result, 'ACCESSES');
const writes = accesses.filter((e) => e.rel.reason === 'write');

View file

@ -52,12 +52,6 @@ describe('caller-derived parameter types (W2-2)', () => {
)
.map((e) => e.rel.targetId);
it('types a bare parameter from its single caller', () => {
const targets = preciseTargetsOf('readSpike', 'consumer.js');
expect(targets).toHaveLength(1);
expect(targets[0]).toContain('makeSpike.wickRatio');
});
it('does not reach the OTHER producer of the same field name', () => {
// `makeCandle.wickRatio` exists and is a candidate for any name-based join.
expect(preciseTargetsOf('readSpike', 'consumer.js')[0]).not.toContain('makeCandle');

View file

@ -1116,22 +1116,6 @@ describe('PHP assignment chain propagation', () => {
expect(saveMethods.length).toBe(2);
});
it('resolves alias->save() to User#save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
const userSave = calls.find(
(c) => c.target === 'save' && c.source === 'process' && c.targetFilePath.includes('User.php'),
);
expect(userSave).toBeDefined();
});
it('resolves rAlias->save() to Repo#save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
const repoSave = calls.find(
(c) => c.target === 'save' && c.source === 'process' && c.targetFilePath.includes('Repo.php'),
);
expect(repoSave).toBeDefined();
});
it('alias->save() does NOT resolve to Repo#save', () => {
const calls = getRelationships(result, 'CALLS');
// There should be exactly one save() call targeting User.php from process
@ -1509,14 +1493,6 @@ describe('Write access tracking (PHP)', () => {
expect(countWrite!.source).toBe('updateUser');
});
it('emits ACCESSES write edge for static property assignment', () => {
const accesses = getRelationships(result, 'ACCESSES');
const writes = accesses.filter((e) => e.rel.reason === 'write');
const countWrite = writes.find((e) => e.target === 'count');
expect(countWrite).toBeDefined();
expect(countWrite!.source).toBe('updateUser');
});
it('write ACCESSES edges have confidence 1.0', () => {
const accesses = getRelationships(result, 'ACCESSES');
const writes = accesses.filter((e) => e.rel.reason === 'write');

View file

@ -2882,15 +2882,6 @@ describe('Python assignment chain propagation', () => {
expect(saveFns.length).toBe(2);
});
it('resolves alias.save() to User#save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
// Positive: alias.save() must resolve to User#save
const userSave = calls.find(
(c) => c.target === 'save' && c.source === 'process' && c.targetFilePath.includes('user.py'),
);
expect(userSave).toBeDefined();
});
it('alias.save() does NOT resolve to Repo#save', () => {
const calls = getRelationships(result, 'CALLS');
// Negative: only one save call from process to User#save
@ -2900,15 +2891,6 @@ describe('Python assignment chain propagation', () => {
expect(wrongCall.length).toBe(1);
});
it('resolves r_alias.save() to Repo#save via assignment chain', () => {
const calls = getRelationships(result, 'CALLS');
// Positive: r_alias.save() must resolve to Repo#save
const repoSave = calls.find(
(c) => c.target === 'save' && c.source === 'process' && c.targetFilePath.includes('repo.py'),
);
expect(repoSave).toBeDefined();
});
it('each alias resolves to its own class, not the other', () => {
const calls = getRelationships(result, 'CALLS');
const userSave = calls.find(

View file

@ -1024,14 +1024,6 @@ describe('Write access tracking (Ruby)', () => {
expect(scoreWrite!.source).toBe('update_user');
});
it('emits ACCESSES write edge for compound assignment (operator_assignment)', () => {
const accesses = getRelationships(result, 'ACCESSES');
const writes = accesses.filter((e) => e.rel.reason === 'write');
const scoreWrite = writes.find((e) => e.target === 'score');
expect(scoreWrite).toBeDefined();
expect(scoreWrite!.source).toBe('update_user');
});
it('write ACCESSES edges have confidence 1.0', () => {
const accesses = getRelationships(result, 'ACCESSES');
const writes = accesses.filter((e) => e.rel.reason === 'write');

View file

@ -93,17 +93,6 @@ describe('TypeScript HOC-wrapped variable declarations', () => {
expect(targets).toContain('fmt');
});
it('useCallback: handleSubmit → doStuff (sibling const, separate caller)', () => {
// Two useCallback consts in the same file — each must be its own
// caller anchor (no leakage to the first sibling, the analogue of
// the multi-action-store regression in PR #1175).
const calls = getRelationships(result, 'CALLS').filter(
(c) => c.sourceFilePath === 'src/use-callback.ts' && c.target === 'doStuff',
);
const fromHandleSubmit = calls.filter((c) => c.source === 'handleSubmit');
expect(fromHandleSubmit.length, 'handleSubmit must call doStuff').toBeGreaterThan(0);
});
it('useMemo: computed → doStuff (returns-a-value variant)', () => {
// `const computed = useMemo(() => { return doStuff(42); }, [])`.
// The arrow's body has a `return` statement — irrelevant to call

View file

@ -422,10 +422,6 @@ describe.skipIf(!zigAvailable)('Zig idioms (zig-idioms fixture)', () => {
]);
});
it('applies the callable gate through a HUB too', () => {
expect(valueRefs).not.toContain('JsApi → DEFAULT_NS');
});
it('applies the callable gate to a MODULE owner too', () => {
// `dom_utils.DEFAULT_NS` is a module-scope constant. Widening the owner
// channel must not widen what counts as a registration, or every

View file

@ -39,6 +39,42 @@ describe('auto-sync analysis worker', () => {
expect(child.stderr.resume).toHaveBeenCalled();
});
it('passes a collapsed graph write through with the stats', async () => {
const child = createChild();
const run = createAutoSyncAnalysisRunner({ forkWorker: vi.fn(() => child as any) });
const result = run('/tmp/repo', {}, 50);
const graphWriteCollapsed = { expected: 930, persisted: 12 };
child.emit('message', {
type: 'complete',
result: { stats: { files: 3 }, graphWriteCollapsed },
});
child.emit('exit', 0, null);
await expect(result).resolves.toEqual({ stats: { files: 3 }, graphWriteCollapsed });
});
it('reports progress until the terminal message, skipping worker log lines; a throwing listener changes nothing', async () => {
const child = createChild();
const run = createAutoSyncAnalysisRunner({ forkWorker: vi.fn(() => child as any) });
const onProgress = vi.fn().mockImplementationOnce(() => {
throw new Error('listener failed');
});
const result = run('/tmp/repo', {}, 50, undefined, undefined, undefined, onProgress);
child.emit('message', { type: 'progress', phase: 'parsing', percent: 20, message: 'Parsing' });
// A worker log line, not progress.
child.emit('message', { type: 'progress', phase: 'log', percent: -1, message: 'warn: x' });
child.emit('message', { type: 'progress', phase: 'graph', percent: 60, message: 'Graph' });
child.emit('message', { type: 'complete', result: { stats: { files: 3 } } });
child.emit('message', { type: 'progress', phase: 'late', percent: 99, message: 'Late' });
child.emit('exit', 0, null);
await expect(result).resolves.toEqual({ stats: { files: 3 } });
expect(onProgress.mock.calls).toEqual([
[20, 'Parsing'],
[60, 'Graph'],
]);
});
it('rejects on a worker error even when no exit event follows', async () => {
const child = createChild();
const run = createAutoSyncAnalysisRunner({ forkWorker: vi.fn(() => child as any) });
@ -214,7 +250,7 @@ describe('auto-sync analysis worker', () => {
await expect(solo).resolves.toEqual({ stats: { files: 1 } });
});
it('stops waiting for a worker that never exits after cancellation', async () => {
it.each([0, 1])('tracks an abandoned worker until exit (%s)', async (exitCode) => {
const child = Object.assign(createChild(), {
unref: vi.fn(),
channel: { unref: vi.fn() },
@ -233,7 +269,7 @@ describe('auto-sync analysis worker', () => {
timers[0]!();
expect(child.send).toHaveBeenLastCalledWith({ type: 'cancel' });
// No 'exit' ever arrives — the worker is wedged past its safe point.
// No 'exit' arrives during the grace period.
timers[1]!();
await expect(result).rejects.toThrow('did not exit within');
@ -246,6 +282,18 @@ describe('auto-sync analysis worker', () => {
expect(child.channel.unref).toHaveBeenCalled();
expect(child.unref).toHaveBeenCalled();
expect(child.send).toHaveBeenCalledTimes(2);
const failure = (await result.catch((error) => error)) as AutoSyncAnalysisError;
expect(failure.workerExited).toBeInstanceOf(Promise);
const exited = vi.fn();
void failure.workerExited?.then(exited);
// A late completion message is not proof that the process has exited.
child.emit('message', { type: 'complete', result: { stats: { files: 1 } } });
await Promise.resolve();
expect(exited).not.toHaveBeenCalled();
child.emit('exit', exitCode, null);
await failure.workerExited;
expect(exited).toHaveBeenCalledOnce();
});
it('uses the same cancellation request for an aborted watch run', async () => {

View file

@ -0,0 +1,67 @@
import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import {
countScanCandidates,
walkRepositoryPaths,
} from '../../src/core/ingestion/filesystem-walker.js';
// #3524: refresh_index admits a rebuild from this count of the working tree,
// so it must see what analyze's scan sees, and stop once it passes the limit.
let root: string;
async function write(relativePath: string, content = 'export const x = 1;\n'): Promise<void> {
const file = path.join(root, relativePath);
await fs.mkdir(path.dirname(file), { recursive: true });
await fs.writeFile(file, content);
}
beforeEach(async () => {
vi.stubEnv('GITNEXUS_INCLUDE_DOT_DIRS', undefined);
root = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-scan-count-'));
await write('src/a.ts');
await write('src/b.ts');
await write('README.md', '# readme\n');
await write('.gitignore', 'scratch/\n');
await write('scratch/out.ts');
await write('node_modules/dep/index.js');
await write('.hidden/c.ts');
});
afterEach(async () => {
vi.unstubAllEnvs();
await fs.rm(root, { recursive: true, force: true });
});
describe('countScanCandidates', () => {
it('counts the paths the scan walks, with its ignore rules', async () => {
const scanned = await walkRepositoryPaths(root, undefined, { quiet: true });
expect(scanned.map((file) => file.path).sort()).toEqual(['README.md', 'src/a.ts', 'src/b.ts']);
await expect(countScanCandidates(root, 100)).resolves.toBe(scanned.length);
});
it('stops once the count passes the limit', async () => {
await expect(countScanCandidates(root, 1)).resolves.toBe(2);
await expect(countScanCandidates(root, 3)).resolves.toBe(3);
});
it('counts files the scan later drops for their size', async () => {
await write('src/big.ts', 'x'.repeat(64));
const scanned = await walkRepositoryPaths(root, undefined, {
quiet: true,
maxFileSizeBytes: 32,
});
expect(scanned.map((file) => file.path)).not.toContain('src/big.ts');
await expect(countScanCandidates(root, 100)).resolves.toBe(scanned.length + 1);
});
it('rejects a path that is not a directory, like the scan', async () => {
await expect(countScanCandidates(path.join(root, 'missing'), 10)).rejects.toThrow(
/walkRepositoryPaths: path does not exist/,
);
});
});

View file

@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
import {
compactImpactItemProcesses,
fitImpactToTokenBudget,
ImpactBudgetExceededError,
IMPACT_AGENT_DEFAULT_LIMIT,
impactAgentDefaultLimit,
shapeImpactForAgent,
@ -29,6 +30,16 @@ const result = (byDepth: Record<string, unknown[]>) => ({
});
describe('impact agent defaults', () => {
it.each([{ offset: 0 }, { summaryOnly: false }, { offset: 0, summaryOnly: false }])(
'pages requests with materialized schema defaults: %j',
(defaults) => {
expect(withImpactAgentDefaults({ target: 't', ...defaults }, {})).toEqual({
target: 't',
...defaults,
limit: 30,
});
},
);
it('adds the default page only when the caller chose no pagination', () => {
expect(withImpactAgentDefaults({ target: 't' }, {})).toEqual({
target: 't',
@ -106,12 +117,38 @@ describe('fitImpactToTokenBudget', () => {
});
});
it('keeps a result that already fits, and one that cannot fit without symbols', () => {
it('keeps a result that already fits and rejects a budget smaller than its summary', () => {
const small = result({ '1': [symbol('a')] });
expect(fitImpactToTokenBudget(small, 10_000)).toBe(small);
expect(fitImpactToTokenBudget(small, 1)).toBe(small);
expect(() => fitImpactToTokenBudget(small, 1)).toThrow(ImpactBudgetExceededError);
});
it.each([
{ ...result({ '1': [symbol('a')] }), affected_processes: [{ name: 'x'.repeat(10_000) }] },
{ impactedCount: 1, affected_modules: [{ name: 'x'.repeat(10_000) }] },
{ status: 'ambiguous', candidates: [{ name: 'x'.repeat(10_000) }] },
{ group: 'services', local: { payload: 'x'.repeat(10_000) } },
])('fails explicitly when non-symbol fields cannot fit', (input) => {
expect(() => fitImpactToTokenBudget(input, 100)).toThrow(ImpactBudgetExceededError);
});
it('does not trim one of the two PDG views independently', () => {
const byDepth = { '1': Array.from({ length: 50 }, (_, i) => symbol(`s${i}`, 5)) };
const pdg = { ...result(byDepth), mode: 'pdg', interproceduralByDepth: byDepth };
expect(shapeImpactForAgent(pdg, undefined)).toBe(pdg);
expect(() => shapeImpactForAgent(pdg, 200)).toThrow(ImpactBudgetExceededError);
});
it.each([1, 3, 4, 8, 20, 100])(
'keeps even a tiny budget error valid JSON (%i tokens)',
(budget) => {
const text = new ImpactBudgetExceededError(budget).toJSONText();
expect(() => JSON.parse(text)).not.toThrow();
expect(Buffer.byteLength(text)).toBeLessThanOrEqual(budget * 4);
if (budget >= 4) expect(JSON.parse(text)).toHaveProperty('error');
},
);
it('reserves room for text appended after serialization', () => {
const full = result({ '1': Array.from({ length: 30 }, (_, i) => symbol(`s${i}`)) });
const withoutReserve = fitImpactToTokenBudget(full, 500) as any;

View file

@ -278,6 +278,9 @@ describe('incremental graph identity before publication', () => {
await repo.cleanup();
}
},
120_000,
// Windows takes the in-place recovery path for every row: five analysis
// calls including repair refusal, full recovery, and the final no-op.
// Allow slow native checkpoints to finish before the test runner times out.
process.platform === 'win32' ? 240_000 : 120_000,
);
});

View file

@ -0,0 +1,320 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
// #3524: LocalBackend's refresh_index around a stubbed analyze worker. The real
// worker, registry, and git are covered by test/integration/mcp-refresh-index-e2e.
const mocks = vi.hoisted(() => ({
listRegisteredRepos: vi.fn(),
runAutoSyncAnalysis: vi.fn(),
checkStalenessAsync: vi.fn(),
embeddingsFromGitnexusRc: vi.fn(),
countScanCandidates: vi.fn(),
}));
vi.mock('../../src/storage/repo-manager.js', async (importOriginal) => {
const actual = await importOriginal<typeof import('../../src/storage/repo-manager.js')>();
return { ...actual, listRegisteredRepos: mocks.listRegisteredRepos };
});
vi.mock('../../src/core/auto-sync/analysis-worker-launch.js', async (importOriginal) => {
const actual =
await importOriginal<typeof import('../../src/core/auto-sync/analysis-worker-launch.js')>();
return { ...actual, runAutoSyncAnalysis: mocks.runAutoSyncAnalysis };
});
vi.mock('../../src/core/git-staleness.js', async (importOriginal) => {
const actual = await importOriginal<typeof import('../../src/core/git-staleness.js')>();
return { ...actual, checkStalenessAsync: mocks.checkStalenessAsync };
});
vi.mock('../../src/core/ingestion/filesystem-walker.js', async (importOriginal) => {
const actual =
await importOriginal<typeof import('../../src/core/ingestion/filesystem-walker.js')>();
return { ...actual, countScanCandidates: mocks.countScanCandidates };
});
vi.mock('../../src/core/gitnexus-rc-embeddings.js', () => ({
embeddingsFromGitnexusRc: mocks.embeddingsFromGitnexusRc,
}));
import path from 'node:path';
import { LocalBackend } from '../../src/mcp/local/local-backend.js';
const REPO = path.resolve('/work/shop');
function entry(overrides: Record<string, unknown> = {}) {
return {
name: 'shop',
path: REPO,
storagePath: `${REPO}/.gitnexus`,
indexedAt: '2026-10-01T00:00:00.000Z',
lastCommit: 'old',
stats: { files: 40, nodes: 300, edges: 900 },
...overrides,
};
}
const BEHIND = { isStale: true, commitsBehind: 3, status: 'behind', hint: 'behind' };
const CURRENT = { isStale: false, commitsBehind: 0, status: 'current' };
describe('LocalBackend refresh_index (#3524)', () => {
let backend: LocalBackend;
beforeEach(async () => {
vi.clearAllMocks();
vi.unstubAllEnvs();
// The assertions use the defaults, so an inherited setting must not leak in.
vi.stubEnv('GITNEXUS_MCP_REFRESH_MAX_FILES', undefined);
vi.stubEnv('GITNEXUS_MCP_REFRESH_TIMEOUT_MS', undefined);
mocks.listRegisteredRepos.mockResolvedValue([entry()]);
mocks.embeddingsFromGitnexusRc.mockResolvedValue({});
// The working tree has one file more than the last index recorded.
mocks.countScanCandidates.mockResolvedValue(41);
mocks.checkStalenessAsync.mockImplementation(async (_path: string, commit: string) =>
commit === 'new' ? CURRENT : BEHIND,
);
mocks.runAutoSyncAnalysis.mockImplementation(async () => {
mocks.listRegisteredRepos.mockResolvedValue([
entry({
lastCommit: 'new',
indexedAt: '2026-10-29T00:00:00.000Z',
stats: { files: 41, nodes: 310, edges: 930 },
}),
]);
return { stats: { files: 41 } };
});
backend = new LocalBackend();
await backend.init();
});
it('describes a dry run without starting the worker', async () => {
const result = await backend.callTool('refresh_index', { repo: 'shop', dry_run: true });
expect(result).toEqual({
status: 'dry_run',
repo: 'shop',
indexedAt: '2026-10-01T00:00:00.000Z',
lastCommit: 'old',
staleness: expect.objectContaining({ status: 'behind', commitsBehind: 3 }),
estimatedFiles: 41,
lastIndexedFiles: 40,
maxFiles: 5_000,
embeddings: false,
wouldRefresh: true,
});
expect(mocks.runAutoSyncAnalysis).not.toHaveBeenCalled();
});
it('reports and forwards embeddings that .gitnexusrc asks for', async () => {
mocks.embeddingsFromGitnexusRc.mockResolvedValue({ embeddings: true, embeddingsNodeLimit: 9 });
const dryRun = await backend.callTool('refresh_index', { repo: 'shop', dry_run: true });
expect(dryRun).toMatchObject({ embeddings: true, wouldRefresh: true });
await backend.callTool('refresh_index', { repo: 'shop' });
expect(mocks.runAutoSyncAnalysis.mock.calls[0][1]).toMatchObject({
embeddings: true,
embeddingsNodeLimit: 9,
});
});
it('refuses to start when .gitnexusrc cannot be read', async () => {
mocks.embeddingsFromGitnexusRc.mockRejectedValue(new Error('.gitnexusrc: invalid JSON'));
for (const dry_run of [true, false]) {
await expect(backend.callTool('refresh_index', { repo: 'shop', dry_run })).resolves.toEqual({
error: 'Cannot refresh shop: .gitnexusrc: invalid JSON.',
});
}
expect(mocks.runAutoSyncAnalysis).not.toHaveBeenCalled();
});
it('rebuilds index-only through the worker and reports before and after', async () => {
const onProgress = vi.fn();
const result = await backend.callTool('refresh_index', { repo: 'shop' }, { onProgress });
expect(mocks.runAutoSyncAnalysis).toHaveBeenCalledTimes(1);
const [repoPath, options, timeoutMs, runSignal, , , progress] =
mocks.runAutoSyncAnalysis.mock.calls[0];
expect(repoPath).toBe(REPO);
expect(options).toEqual({
skipAgentsMd: true,
skipSkills: true,
preserveExistingPdg: true,
atomicIncremental: true,
});
expect(timeoutMs).toBe(600_000);
// The worker never interrupts a started analysis, so no abort signal is passed.
expect(runSignal).toBeUndefined();
expect(progress).toBe(onProgress);
expect(result).toEqual({
status: 'refreshed',
repo: 'shop',
previous: {
indexedAt: '2026-10-01T00:00:00.000Z',
lastCommit: 'old',
staleness: expect.objectContaining({ status: 'behind' }),
},
indexedAt: '2026-10-29T00:00:00.000Z',
lastCommit: 'new',
staleness: { status: 'current' },
stats: { files: 41, nodes: 310, edges: 930 },
durationMs: expect.any(Number),
});
});
it('counts the working tree against the limit, not the last index', async () => {
// The last index recorded 40 files; the tree has since grown past the limit.
mocks.countScanCandidates.mockResolvedValue(5_001);
const dryRun = await backend.callTool('refresh_index', { repo: 'shop', dry_run: true });
expect(dryRun).toMatchObject({
estimatedFiles: null,
lastIndexedFiles: 40,
maxFiles: 5_000,
wouldRefresh: false,
refusal:
'shop has more than 5000 files in its working tree (40 at its last index), over ' +
"this server's refresh limit of 5000 (GITNEXUS_MCP_REFRESH_MAX_FILES). " +
'Run `gitnexus analyze` in the repository instead.',
});
await expect(backend.callTool('refresh_index', { repo: 'shop' })).resolves.toEqual({
error: dryRun.refusal,
});
expect(mocks.runAutoSyncAnalysis).not.toHaveBeenCalled();
// Enumeration stops one past the limit.
expect(mocks.countScanCandidates).toHaveBeenCalledWith(REPO, 5_000);
});
it('admits an index with no recorded count, and skips the count with no limit', async () => {
mocks.listRegisteredRepos.mockResolvedValue([entry({ stats: undefined })]);
await backend.init();
await expect(
backend.callTool('refresh_index', { repo: REPO, dry_run: true }),
).resolves.toMatchObject({ estimatedFiles: 41, lastIndexedFiles: null, wouldRefresh: true });
vi.stubEnv('GITNEXUS_MCP_REFRESH_MAX_FILES', '0');
mocks.countScanCandidates.mockClear();
await expect(
backend.callTool('refresh_index', { repo: REPO, dry_run: true }),
).resolves.toMatchObject({ estimatedFiles: null, maxFiles: 0, wouldRefresh: true });
await expect(backend.callTool('refresh_index', { repo: REPO })).resolves.toMatchObject({
status: 'refreshed',
});
expect(mocks.countScanCandidates).not.toHaveBeenCalled();
});
it('refuses to start when the working tree cannot be read', async () => {
mocks.countScanCandidates.mockRejectedValue(
new Error(`walkRepositoryPaths: path does not exist: ${REPO}`),
);
for (const dry_run of [true, false]) {
await expect(backend.callTool('refresh_index', { repo: 'shop', dry_run })).resolves.toEqual({
error: `Cannot refresh shop: walkRepositoryPaths: path does not exist: ${REPO}.`,
});
}
expect(mocks.runAutoSyncAnalysis).not.toHaveBeenCalled();
});
it('runs one refresh per repository at a time', async () => {
let finish!: () => void;
mocks.runAutoSyncAnalysis.mockImplementationOnce(
() => new Promise((resolve) => (finish = () => resolve({ stats: {} }))),
);
const first = backend.callTool('refresh_index', { repo: 'shop' });
await vi.waitFor(() => expect(mocks.runAutoSyncAnalysis).toHaveBeenCalled());
const second = await backend.callTool('refresh_index', { repo: 'shop' });
expect(second.error).toMatch(/already running/);
await expect(
backend.callTool('refresh_index', { repo: 'shop', dry_run: true }),
).resolves.toMatchObject({ wouldRefresh: false, inProgress: true });
finish();
await expect(first).resolves.toMatchObject({ status: 'refreshed' });
// The slot is released, including after a failure.
mocks.runAutoSyncAnalysis.mockRejectedValueOnce(new Error('Analysis timed out after 5ms.'));
const failed = await backend.callTool('refresh_index', { repo: 'shop' });
expect(failed.error).toMatch(/Refresh of shop failed: Analysis timed out after 5ms\./);
await expect(backend.callTool('refresh_index', { repo: 'shop' })).resolves.toMatchObject({
status: 'refreshed',
});
});
it('reports a collapsed graph write as a failure, like analyze and serve', async () => {
mocks.runAutoSyncAnalysis.mockImplementationOnce(async () => {
mocks.listRegisteredRepos.mockResolvedValue([entry({ lastCommit: 'new' })]);
return { stats: { files: 41 }, graphWriteCollapsed: { expected: 930, persisted: 12 } };
});
const result = await backend.callTool('refresh_index', { repo: 'shop' });
expect(result).toEqual({
error: expect.stringMatching(
/^shop was indexed INCOMPLETELY: only 12 of 930 expected relationships are readable.*`gitnexus analyze --force`/,
),
});
// The registry is still re-read, so later tools see what is on disk.
const list = await backend.callTool('list_repos', {});
expect(list.repositories[0].lastCommit).toBe('new');
});
it('keeps a timed-out refresh busy until its abandoned worker exits', async () => {
let finishWorker!: () => void;
const workerExited = new Promise<void>((resolve) => {
finishWorker = resolve;
});
mocks.runAutoSyncAnalysis.mockRejectedValueOnce(
Object.assign(new Error('Analysis timed out after 5ms. The analyze worker did not exit'), {
abandonedWorker: true,
workerExited,
}),
);
const result = await backend.callTool('refresh_index', { repo: 'shop' });
expect(result.error).toContain('Its worker keeps running until the analysis finishes');
await expect(backend.callTool('refresh_index', { repo: 'shop' })).resolves.toMatchObject({
error: expect.stringContaining('already running'),
});
await expect(
backend.callTool('refresh_index', { repo: 'shop', dry_run: true }),
).resolves.toMatchObject({ wouldRefresh: false, inProgress: true });
expect(mocks.runAutoSyncAnalysis).toHaveBeenCalledTimes(1);
finishWorker();
await workerExited;
await expect(backend.callTool('refresh_index', { repo: 'shop' })).resolves.toMatchObject({
status: 'refreshed',
});
expect(mocks.runAutoSyncAnalysis).toHaveBeenCalledTimes(2);
expect(result.error).toBe(
'Refresh of shop failed: Analysis timed out after 5ms. The analyze worker did not exit. ' +
'Its worker keeps running until the analysis finishes; another refresh is refused until it exits. ' +
'Run `gitnexus analyze` in the repository for the full log.',
);
});
it('reports unknown staleness when the check itself fails', async () => {
mocks.checkStalenessAsync.mockRejectedValue(new Error('git missing'));
const result = await backend.callTool('refresh_index', { repo: 'shop', dry_run: true });
expect(result.staleness).toEqual({ status: 'unknown' });
});
it('needs an explicit repo once several are indexed, dry runs included', async () => {
mocks.listRegisteredRepos.mockResolvedValue([
entry(),
entry({
name: 'blog',
path: path.resolve('/work/blog'),
storagePath: `${path.resolve('/work/blog')}/.gitnexus`,
}),
]);
vi.spyOn(process, 'cwd').mockReturnValue(REPO);
// The cwd would pick `shop` for a read tool; refresh_index does not use it.
await expect(
backend.selectToolRepository(undefined, undefined, { allowCwdDefault: true }),
).resolves.toMatchObject({ name: 'shop' });
for (const dry_run of [true, false]) {
await expect(backend.callTool('refresh_index', { dry_run })).rejects.toThrow(
/multiple repositories/i,
);
}
expect(mocks.runAutoSyncAnalysis).not.toHaveBeenCalled();
});
it('rejects a non-boolean dry_run', async () => {
const result = await backend.callTool('refresh_index', { repo: 'shop', dry_run: 'true' });
expect(result).toEqual({ error: 'Parameter "dry_run" must be a boolean.' });
expect(mocks.runAutoSyncAnalysis).not.toHaveBeenCalled();
});
});

View file

@ -0,0 +1,380 @@
import type http from 'node:http';
import net, { type AddressInfo } from 'node:net';
import express from 'express';
import { afterEach, describe, expect, it, vi } from 'vitest';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
import { createMCPServer } from '../../src/mcp/server.js';
import { startMcpHttpServer } from '../../src/mcp/http-transport.js';
import type { LocalBackend } from '../../src/mcp/local/local-backend.js';
import { createMcpRepositoryPolicy } from '../../src/mcp/repository-policy.js';
import { mountMCPEndpoints } from '../../src/server/mcp-http.js';
import {
MCP_REFRESH_DEFAULT_MAX_FILES,
MCP_REFRESH_DEFAULT_TIMEOUT_MS,
resolveMcpRefreshLimits,
resolveMcpRefreshMode,
} from '../../src/mcp/refresh-policy.js';
const REPOS = [
{ name: 'Alpha', path: '/repos/alpha', indexedAt: '2026-01-01', lastCommit: 'a'.repeat(40) },
{ name: 'Beta', path: '/repos/beta', indexedAt: '2026-01-02', lastCommit: 'b'.repeat(40) },
];
function createMockBackend() {
return {
callTool: vi.fn().mockResolvedValue({ status: 'refreshed' }),
listRepos: vi.fn().mockResolvedValue(REPOS.map((repo) => ({ ...repo }))),
countRepos: vi.fn().mockResolvedValue(REPOS.length),
cachedRepoCount: vi.fn().mockReturnValue(REPOS.length),
resolveRepo: vi
.fn()
.mockResolvedValue({ name: 'test', repoPath: '/tmp/test', lastCommit: 'abc' }),
getContext: vi.fn().mockReturnValue(null),
disconnect: vi.fn().mockResolvedValue(undefined),
};
}
async function connect(
options: Parameters<typeof createMCPServer>[1] = {},
backend = createMockBackend(),
) {
const server = createMCPServer(backend as unknown as LocalBackend, options);
const client = new Client({ name: 'refresh-test-client', version: '0.0.0' });
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
return {
backend,
client,
serverTransport,
close: async () => {
await client.close();
await server.close();
},
};
}
afterEach(() => {
vi.unstubAllEnvs();
});
describe('refresh_index MCP gate (#3524)', () => {
it('is absent and rejected by default, even when the environment asks for it', async () => {
// `gitnexus serve` creates its MCP servers without the option, so its
// environment alone must not be able to expose the tool.
vi.stubEnv('GITNEXUS_MCP_ENABLE_REFRESH', '1');
const session = await connect();
try {
const { tools } = await session.client.listTools();
expect(tools.map((tool) => tool.name)).not.toContain('refresh_index');
const response = await session.client.callTool({
name: 'refresh_index',
arguments: { repo: 'test' },
});
expect(response.isError).toBe(true);
expect(JSON.stringify(response.content)).toContain('GITNEXUS_MCP_ENABLE_REFRESH=1');
expect(session.backend.callTool).not.toHaveBeenCalled();
} finally {
await session.close();
}
});
it('is listed as a non-destructive write when the local server enables it', async () => {
const session = await connect({ refreshIndex: true });
try {
const { tools } = await session.client.listTools();
const refresh = tools.find((tool) => tool.name === 'refresh_index');
expect(refresh?.annotations).toEqual({
readOnlyHint: false,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
});
expect(Object.keys(refresh?.inputSchema.properties ?? {}).sort()).toEqual([
'dry_run',
'repo',
]);
session.backend.callTool.mockResolvedValueOnce({ status: 'dry_run', wouldRefresh: true });
const response = await session.client.callTool({
name: 'refresh_index',
arguments: { repo: 'test', dry_run: true },
});
expect(response.isError).not.toBe(true);
// A dry run changes nothing, so it gets no next step.
expect(JSON.stringify(response.content)).not.toContain('**Next:**');
// No progress token, so nothing beyond the arguments reaches the backend.
expect(session.backend.callTool).toHaveBeenCalledWith('refresh_index', {
repo: 'test',
dry_run: true,
});
} finally {
await session.close();
}
});
it('rejects a branch pin before dispatch', async () => {
const session = await connect({ refreshIndex: true });
try {
const response = await session.client.callTool({
name: 'refresh_index',
arguments: { repo: 'test', branch: 'main' },
});
expect(response.isError).toBe(true);
expect(session.backend.callTool).not.toHaveBeenCalled();
} finally {
await session.close();
}
});
it('stays hidden and rejected in read-only mode even when enabled', async () => {
vi.stubEnv('GITNEXUS_MCP_READ_ONLY', '1');
const session = await connect({ refreshIndex: true });
try {
const { tools } = await session.client.listTools();
expect(tools.map((tool) => tool.name)).not.toContain('refresh_index');
const response = await session.client.callTool({
name: 'refresh_index',
arguments: { repo: 'test', dry_run: true },
});
expect(response.isError).toBe(true);
expect(JSON.stringify(response.content)).toContain('read-only mode');
expect(session.backend.callTool).not.toHaveBeenCalled();
} finally {
await session.close();
}
});
it('forwards strictly increasing progress and clamps it to the advertised total', async () => {
const backend = createMockBackend();
backend.callTool.mockImplementation(
async (
_method: string,
_args: unknown,
context?: { onProgress?: (progress: number, message: string) => Promise<void> },
) => {
await context?.onProgress?.(0, 'starting');
await context?.onProgress?.(10, 'parsing');
await context?.onProgress?.(10, 'repeated');
await context?.onProgress?.(5, 'decreasing');
await context?.onProgress?.(90, 'communities');
await context?.onProgress?.(105, 'complete');
await context?.onProgress?.(100, 'repeated completion');
await context?.onProgress?.(150, 'above total again');
return { status: 'refreshed' };
},
);
const session = await connect({ refreshIndex: true }, backend);
try {
const updates: Array<{ progress: number; total?: number; message?: string }> = [];
const response = await session.client.callTool(
{ name: 'refresh_index', arguments: { repo: 'test' } },
undefined,
{ onprogress: (update) => updates.push(update), resetTimeoutOnProgress: true },
);
expect(response.isError).not.toBe(true);
expect(JSON.stringify(response.content)).toContain('it now reads the refreshed one');
expect(updates).toEqual([
{ progress: 0, total: 100, message: 'starting' },
{ progress: 10, total: 100, message: 'parsing' },
{ progress: 90, total: 100, message: 'communities' },
{ progress: 100, total: 100, message: 'complete' },
]);
} finally {
await session.close();
}
});
it('finishes the refresh and sends later progress when a notification send rejects', async () => {
const backend = createMockBackend();
backend.callTool.mockImplementation(
async (
_method: string,
_args: unknown,
context?: { onProgress?: (progress: number, message: string) => Promise<void> },
) => {
await context?.onProgress?.(10, 'parsing');
await context?.onProgress?.(90, 'communities');
return { status: 'refreshed' };
},
);
const session = await connect({ refreshIndex: true }, backend);
const send = session.serverTransport.send.bind(session.serverTransport);
const rejected = vi.fn();
const unhandled = vi.fn();
process.on('unhandledRejection', unhandled);
const spy = vi
.spyOn(session.serverTransport, 'send')
.mockImplementation(async (message, options) => {
if (
'method' in message &&
message.method === 'notifications/progress' &&
message.params?.progress === 10
) {
rejected();
throw new Error('notification transport unavailable');
}
await send(message, options);
});
try {
const updates: Array<{ progress: number; total?: number; message?: string }> = [];
const response = await session.client.callTool(
{ name: 'refresh_index', arguments: { repo: 'test' } },
undefined,
{ onprogress: (update) => updates.push(update) },
);
expect(rejected).toHaveBeenCalledOnce();
expect(response.isError).not.toBe(true);
expect(JSON.stringify(response.content)).toContain('refreshed');
expect(updates).toEqual([{ progress: 90, total: 100, message: 'communities' }]);
// The suite tolerates native teardown errors globally, so assert this
// rejection explicitly after Node has had a turn to report it.
await new Promise<void>((resolve) => setImmediate(resolve));
expect(unhandled).not.toHaveBeenCalled();
} finally {
process.off('unhandledRejection', unhandled);
spy.mockRestore();
await session.close();
}
});
});
describe('refresh_index repository policy (#3524)', () => {
it('keeps a refresh inside the MCP repository allowlist', async () => {
const backend = createMockBackend();
const repositoryPolicy = await createMcpRepositoryPolicy(backend as unknown as LocalBackend, {
GITNEXUS_MCP_ALLOWED_REPOS: 'Alpha',
});
const session = await connect({ refreshIndex: true, repositoryPolicy }, backend);
try {
const denied = await session.client.callTool({
name: 'refresh_index',
arguments: { repo: '/repos/beta' },
});
expect(denied.isError).toBe(true);
expect(backend.callTool).not.toHaveBeenCalled();
await session.client.callTool({ name: 'refresh_index', arguments: {} });
expect(backend.callTool).toHaveBeenCalledWith('refresh_index', { repo: '/repos/alpha' });
} finally {
await session.close();
}
});
});
describe('refresh_index over HTTP (#3524)', () => {
const servers: http.Server[] = [];
afterEach(async () => {
for (const server of servers.splice(0)) {
await new Promise<void>((resolve) => server.close(() => resolve()));
}
});
// The DNS-rebinding guard allows the configured port, so port 0 cannot be used here.
async function freePort(): Promise<number> {
const probe = net.createServer();
await new Promise<void>((resolve) => probe.listen(0, '127.0.0.1', resolve));
const { port } = probe.address() as AddressInfo;
await new Promise<void>((resolve) => probe.close(() => resolve()));
return port;
}
async function toolNames(transport: StreamableHTTPClientTransport | SSEClientTransport) {
const client = new Client({ name: 'refresh-http-client', version: '0.0.0' });
await client.connect(transport);
try {
return (await client.listTools()).tools.map((tool) => tool.name);
} finally {
await client.close();
}
}
it.each([
[true, true],
[undefined, false],
])('gitnexus mcp --http with refreshIndex=%s lists it: %s', async (refreshIndex, listed) => {
const port = await freePort();
const server = await startMcpHttpServer(createMockBackend() as unknown as LocalBackend, {
port,
host: '127.0.0.1',
refreshIndex,
});
servers.push(server);
const base = `http://127.0.0.1:${port}`;
for (const transport of [
new StreamableHTTPClientTransport(new URL(`${base}/mcp`)),
new SSEClientTransport(new URL(`${base}/sse`)),
]) {
expect((await toolNames(transport)).includes('refresh_index')).toBe(listed);
}
});
it('is never listed on the serve /api/mcp surface, even with the variable set', async () => {
vi.stubEnv('GITNEXUS_MCP_ENABLE_REFRESH', '1');
const app = express();
app.use(express.json());
const cleanup = await mountMCPEndpoints(app, createMockBackend() as unknown as LocalBackend);
const server = await new Promise<http.Server>((resolve) => {
const listening = app.listen(0, '127.0.0.1', () => resolve(listening));
});
servers.push(server);
try {
const port = (server.address() as AddressInfo).port;
const names = await toolNames(
new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${port}/api/mcp`)),
);
expect(names).toContain('list_repos');
expect(names).not.toContain('refresh_index');
} finally {
await cleanup();
}
});
});
describe('refresh policy environment', () => {
it.each([
[undefined, false],
['', false],
['0', false],
['1', true],
])('reads GITNEXUS_MCP_ENABLE_REFRESH=%s as %s', (value, expected) => {
expect(resolveMcpRefreshMode({ GITNEXUS_MCP_ENABLE_REFRESH: value })).toBe(expected);
});
it.each(['true', 'yes', '2'])('fails startup for malformed enable value %s', (value) => {
expect(() => resolveMcpRefreshMode({ GITNEXUS_MCP_ENABLE_REFRESH: value })).toThrow(
/GITNEXUS_MCP_ENABLE_REFRESH must be 0 or 1/,
);
});
it('defaults the size and time limits, and accepts 0 files as no limit', () => {
expect(resolveMcpRefreshLimits({})).toEqual({
maxFiles: MCP_REFRESH_DEFAULT_MAX_FILES,
timeoutMs: MCP_REFRESH_DEFAULT_TIMEOUT_MS,
});
expect(
resolveMcpRefreshLimits({
GITNEXUS_MCP_REFRESH_MAX_FILES: '0',
GITNEXUS_MCP_REFRESH_TIMEOUT_MS: '30000',
}),
).toEqual({ maxFiles: 0, timeoutMs: 30_000 });
expect(
resolveMcpRefreshLimits({ GITNEXUS_MCP_REFRESH_TIMEOUT_MS: '2147483647' }).timeoutMs,
).toBe(2_147_483_647);
});
it.each([
['GITNEXUS_MCP_REFRESH_MAX_FILES', '-1'],
['GITNEXUS_MCP_REFRESH_MAX_FILES', '1e3'],
['GITNEXUS_MCP_REFRESH_TIMEOUT_MS', '0'],
['GITNEXUS_MCP_REFRESH_TIMEOUT_MS', 'ten'],
// Node would fire a longer timer after 1 ms and cancel every refresh.
['GITNEXUS_MCP_REFRESH_TIMEOUT_MS', '2147483648'],
])('rejects %s=%s', (name, value) => {
expect(() => resolveMcpRefreshLimits({ [name]: value })).toThrow(new RegExp(name));
});
});

View file

@ -0,0 +1,97 @@
import { describe, expect, it } from 'vitest';
import { SupportedLanguages } from 'gitnexus-shared';
import { createOwnerEdgeGuard } from '../../src/core/ingestion/workers/owner-edge-guard.js';
import type { ParseWorkerResult } from '../../src/core/ingestion/workers/parse-worker.js';
type Slice = Pick<ParseWorkerResult, 'nodes' | 'relationships'>;
type Rel = Slice['relationships'][number];
const memberNode = (path: string, member: number): Slice['nodes'][number] => ({
id: `Method:${path}:m${member}`,
label: 'Method',
properties: {
name: `m${member}`,
filePath: path,
startLine: 0,
endLine: 0,
language: SupportedLanguages.TypeScript,
isExported: false,
},
});
const memberEdge = (type: Rel['type'], sourceId: string, targetId: string): Rel => ({
id: `${type}:${sourceId}->${targetId}`,
sourceId,
targetId,
type,
confidence: 1,
reason: '',
});
describe('owner-edge guard scaling', () => {
it.each([8, 32, 128])('processes %i files without rescanning completed files', (fileCount) => {
const prefixNode = memberNode('previous.ts', 0);
const prefixEdge = memberEdge('DEFINES', 'File:previous.ts', prefixNode.id);
const raw: Slice = { nodes: [prefixNode], relationships: [prefixEdge] };
let nodeStart = 1;
let relStart = 1;
let nodeReads = 0;
let relReads = 0;
let relWrites = 0;
const guarded: Slice = {
nodes: new Proxy(raw.nodes, {
get(target, property, receiver) {
if (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property)) {
expect(Number(property)).toBeGreaterThanOrEqual(nodeStart);
nodeReads++;
}
return Reflect.get(target, property, receiver);
},
}),
relationships: new Proxy(raw.relationships, {
get(target, property, receiver) {
if (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property)) {
expect(Number(property)).toBeGreaterThanOrEqual(relStart);
relReads++;
}
return Reflect.get(target, property, receiver);
},
set(target, property, value, receiver) {
if (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property)) {
expect(Number(property)).toBeGreaterThanOrEqual(relStart);
relWrites++;
}
return Reflect.set(target, property, value, receiver);
},
}),
};
const guard = createOwnerEdgeGuard(guarded);
for (let file = 0; file < fileCount; file++) {
const path = `file-${file}.ts`;
guard.open(path);
nodeStart = raw.nodes.length;
relStart = raw.relationships.length;
for (let member = 0; member < 8; member++) {
const node = memberNode(path, member);
raw.nodes.push(node);
if (member % 2 === 0)
raw.relationships.push(memberEdge('DEFINES', `File:${path}`, node.id));
raw.relationships.push(memberEdge('HAS_METHOD', `Class:${path}:Missing`, node.id));
raw.relationships.push(memberEdge('HAS_PROPERTY', `Class:${path}:Missing`, node.id));
}
}
guard.settle();
// Bound work by current-file input, including duplicate and already-defined members.
expect(nodeReads).toBeGreaterThan(0);
expect(nodeReads).toBeLessThanOrEqual(fileCount * 8);
expect(relReads).toBeGreaterThan(0);
expect(relReads).toBeLessThanOrEqual(fileCount * 20 * 3);
expect(relWrites).toBeLessThanOrEqual(fileCount * 20);
expect(raw.relationships).toHaveLength(1 + fileCount * 8);
expect(raw.relationships[0]).toBe(prefixEdge);
expect(raw.relationships.every((rel) => rel.type === 'DEFINES')).toBe(true);
expect(new Set(raw.relationships.map((rel) => rel.targetId)).size).toBe(
raw.relationships.length,
);
});
});

View file

@ -0,0 +1,148 @@
import { describe, expect, it } from 'vitest';
import {
createOwnerEdgeGuard,
dropDanglingInFileOwnerEdges,
} from '../../src/core/ingestion/workers/owner-edge-guard.js';
import type { ParseWorkerResult } from '../../src/core/ingestion/workers/parse-worker.js';
type Slice = Pick<ParseWorkerResult, 'nodes' | 'relationships'>;
type Rel = Slice['relationships'][number];
const node = (id: string): Slice['nodes'][number] =>
({ id, label: id.slice(0, id.indexOf(':')), properties: {} }) as Slice['nodes'][number];
const rel = (type: Rel['type'], sourceId: string, targetId: string): Rel => ({
id: `${type}:${sourceId}->${targetId}`,
sourceId,
targetId,
type,
confidence: 1,
reason: '',
});
const summarize = (slice: Slice): string[] =>
slice.relationships.map((r) => `${r.type} ${r.sourceId} -> ${r.targetId}`);
describe('dropDanglingInFileOwnerEdges', () => {
it('re-attaches a member whose in-file owner was never emitted to its File', () => {
const slice: Slice = {
nodes: [node('Function:types/lib.d.ts:m.connect')],
relationships: [
rel('HAS_METHOD', "Trait:types/lib.d.ts:'m'", 'Function:types/lib.d.ts:m.connect'),
],
};
dropDanglingInFileOwnerEdges(slice, 'types/lib.d.ts', 0, 0);
expect(summarize(slice)).toEqual([
'DEFINES File:types/lib.d.ts -> Function:types/lib.d.ts:m.connect',
]);
});
it('drops the edge without duplicating an existing DEFINES', () => {
const slice: Slice = {
nodes: [node('Function:a.mjs:Context'), node('Function:a.mjs:Context.REPO')],
relationships: [
rel('DEFINES', 'File:a.mjs', 'Function:a.mjs:Context.REPO'),
rel('HAS_METHOD', 'Const:a.mjs:Context', 'Function:a.mjs:Context.REPO'),
rel('HAS_PROPERTY', 'Const:a.mjs:Context', 'Property:a.mjs:Context.REF'),
],
};
slice.nodes.push(node('Property:a.mjs:Context.REF'));
dropDanglingInFileOwnerEdges(slice, 'a.mjs', 0, 0);
expect(summarize(slice)).toEqual([
'DEFINES File:a.mjs -> Function:a.mjs:Context.REPO',
'DEFINES File:a.mjs -> Property:a.mjs:Context.REF',
]);
});
it('keeps edges whose owner the file emitted, owners in other files, and non-member edges', () => {
const slice: Slice = {
nodes: [node('Const:a.ts:svc'), node('Method:a.ts:load'), node('Method:a.ts:Server.run')],
relationships: [
rel('HAS_METHOD', 'Const:a.ts:svc', 'Method:a.ts:load'),
rel('HAS_METHOD', 'Struct:b.ts:Server', 'Method:a.ts:Server.run'),
rel('DECLARES', 'Const:a.ts:gone', 'Method:a.ts:load'),
],
};
const before = summarize(slice);
dropDanglingInFileOwnerEdges(slice, 'a.ts', 0, 0);
expect(summarize(slice)).toEqual(before);
});
it('does not treat a path that merely shares a prefix as the same file', () => {
const slice: Slice = {
nodes: [node('Method:a.ts:run')],
relationships: [rel('HAS_METHOD', 'Class:a.ts.bak:Foo', 'Method:a.ts:run')],
};
const before = summarize(slice);
dropDanglingInFileOwnerEdges(slice, 'a.ts', 0, 0);
expect(summarize(slice)).toEqual(before);
});
it('only inspects the current file slice', () => {
const slice: Slice = {
nodes: [node('Method:prev.ts:m'), node('Method:cur.ts:m')],
relationships: [
rel('HAS_METHOD', 'Const:cur.ts:Owner', 'Method:prev.ts:m'),
rel('HAS_METHOD', 'Const:cur.ts:Owner', 'Method:cur.ts:m'),
],
};
dropDanglingInFileOwnerEdges(slice, 'cur.ts', 1, 1);
expect(summarize(slice)).toEqual([
'HAS_METHOD Const:cur.ts:Owner -> Method:prev.ts:m',
'DEFINES File:cur.ts -> Method:cur.ts:m',
]);
});
it('treats an owner emitted earlier in the same file as present', () => {
const slice: Slice = {
nodes: [node('Class:cur.ts:Foo'), node('Method:cur.ts:Foo.m')],
relationships: [rel('HAS_METHOD', 'Class:cur.ts:Foo', 'Method:cur.ts:Foo.m')],
};
dropDanglingInFileOwnerEdges(slice, 'cur.ts', 0, 0);
expect(summarize(slice)).toEqual(['HAS_METHOD Class:cur.ts:Foo -> Method:cur.ts:Foo.m']);
});
});
describe('createOwnerEdgeGuard', () => {
it('settles the previous file when the next one opens', () => {
const slice: Slice = { nodes: [], relationships: [] };
const guard = createOwnerEdgeGuard(slice);
guard.open('a.ts');
slice.nodes.push(node('Method:a.ts:m'));
slice.relationships.push(rel('HAS_METHOD', 'Const:a.ts:Gone', 'Method:a.ts:m'));
guard.open('b.ts');
expect(summarize(slice)).toEqual(['DEFINES File:a.ts -> Method:a.ts:m']);
});
it('settles a file whose processing threw', () => {
const slice: Slice = { nodes: [], relationships: [] };
const guard = createOwnerEdgeGuard(slice);
expect(() => {
try {
guard.open('a.ts');
slice.nodes.push(node('Function:a.ts:X.k'));
slice.relationships.push(rel('HAS_METHOD', 'Const:a.ts:X', 'Function:a.ts:X.k'));
throw new Error('extractor failed after member edges were appended');
} finally {
guard.settle();
}
}).toThrow('extractor failed');
expect(summarize(slice)).toEqual(['DEFINES File:a.ts -> Function:a.ts:X.k']);
});
it('settles each file once', () => {
const slice: Slice = { nodes: [], relationships: [] };
const guard = createOwnerEdgeGuard(slice);
guard.open('a.ts');
slice.nodes.push(node('Method:a.ts:m'));
slice.relationships.push(rel('HAS_METHOD', 'Const:a.ts:Gone', 'Method:a.ts:m'));
guard.settle();
slice.relationships.push(rel('HAS_METHOD', 'Const:a.ts:Late', 'Method:a.ts:m'));
guard.settle();
expect(summarize(slice)).toEqual([
'DEFINES File:a.ts -> Method:a.ts:m',
'HAS_METHOD Const:a.ts:Late -> Method:a.ts:m',
]);
});
});

View file

@ -403,6 +403,56 @@ describe('getNextStepHint rename', () => {
});
describe('MCP output budgets', () => {
it('applies the default impact page with client-supplied schema defaults', async () => {
const backend = createMockBackend();
const args = { target: 'auth', direction: 'upstream', offset: 0, summaryOnly: false };
const response = await callToolThroughServer(backend, 'impact', args);
expect(response.isError).toBe(false);
expect(backend.callTool).toHaveBeenCalledWith('impact', { ...args, limit: 30 });
});
it.each([1, 4, 20, 100, 800])(
'returns a bounded JSON error when impact metadata exceeds %i tokens',
async (maxTokens) => {
const backend = createMockBackend({
callTool: vi.fn().mockResolvedValue({
impactedCount: 1,
risk: 'HIGH',
byDepthCounts: { 1: 1 },
byDepth: { 1: [{ id: 'caller' }] },
affected_processes: [{ name: '😀'.repeat(3000) }],
}),
});
const { text, isError } = await callToolThroughServer(backend, 'impact', {
target: 'auth',
direction: 'upstream',
maxTokens,
});
expect(isError).toBe(true);
expect(Buffer.byteLength(text)).toBeLessThanOrEqual(maxTokens * 4);
expect(() => JSON.parse(text)).not.toThrow();
expect(text).not.toContain(MCP_TRUNCATION_MARKER);
if (maxTokens >= 4) expect(JSON.parse(text)).toHaveProperty('error');
},
);
it.each([
{ impactedCount: 2, affected_modules: [{ name: 'x'.repeat(10_000) }] },
{ status: 'ambiguous', candidates: [{ name: 'x'.repeat(10_000) }] },
{ mode: 'pdg', byDepth: {}, affectedStatements: [{ code: 'x'.repeat(10_000) }] },
{ group: 'services', local: { payload: 'x'.repeat(10_000) } },
])('bounds impact responses without a trimmable symbol list', async (result) => {
const backend = createMockBackend({ callTool: vi.fn().mockResolvedValue(result) });
const response = await callToolThroughServer(backend, 'impact', {
target: 'auth',
direction: 'upstream',
maxTokens: 100,
});
expect(response.isError).toBe(true);
expect(JSON.parse(response.text).error).toContain('Increase maxTokens');
expect(Buffer.byteLength(response.text)).toBeLessThanOrEqual(400);
});
it('serializes query previews and diagnostics as one JSON document', async () => {
const result = {
processes: [{ id: 'process-1', symbol_count: 2 }],

View file

@ -33,6 +33,10 @@ import {
} from '../../src/core/lbug/sidecar-recovery.js';
const logger = () => ({ warn: vi.fn(), info: vi.fn(), debug: vi.fn() });
const CHECKPOINT_RECOVERY_PENDING =
'Runtime exception: Cannot open database in read-only mode while checkpoint recovery is pending. ' +
'If another process is checkpointing, retry after it finishes; otherwise reopen in read-write mode ' +
'to complete recovery before reopening read-only.';
describe('LadybugDB sidecar recovery', () => {
let dir: string;
@ -255,6 +259,13 @@ describe('LadybugDB sidecar recovery', () => {
expect(isReadOnlyCheckpointInProgressError(new Error(CANONICAL))).toBe(true);
});
it('matches the 0.22 checkpoint-recovery refusal', () => {
expect(isReadOnlyCheckpointInProgressError(new Error(CHECKPOINT_RECOVERY_PENDING))).toBe(
true,
);
expect(isReadOnlyCheckpointInProgressError(CHECKPOINT_RECOVERY_PENDING)).toBe(true);
});
it('matches prefix-wrapped and case-variant forms', () => {
expect(
isReadOnlyCheckpointInProgressError(
@ -328,16 +339,19 @@ describe('LadybugDB sidecar recovery', () => {
const SHADOW =
"Runtime exception: Couldn't replay shadow pages under read-only mode. Please re-open the database with read-write mode to replay shadow pages.";
it('wraps checkpoint refusal without rematching the native classifier', () => {
const wrapped = readOnlyRecoveryFailureMessage(dbPath, new Error(CANONICAL));
expect(wrapped.startsWith(INTERRUPTED_CHECKPOINT_RECOVERY_PREFIX)).toBe(true);
expect(wrapped).toMatch(/gitnexus analyze/);
expect(wrapped).not.toMatch(/sidecar is missing/i);
expect(wrapped).not.toMatch(/--force/);
expect(wrapped).not.toContain(CANONICAL);
expect(isReadOnlyCheckpointInProgressError(new Error(wrapped))).toBe(false);
expect(isReadOnlyRecoveryFailure(new Error(wrapped))).toBe(true);
});
it.each([CANONICAL, CHECKPOINT_RECOVERY_PENDING])(
'wraps checkpoint refusal without rematching the native classifier (%#)',
(refusal) => {
const wrapped = readOnlyRecoveryFailureMessage(dbPath, new Error(refusal));
expect(wrapped.startsWith(INTERRUPTED_CHECKPOINT_RECOVERY_PREFIX)).toBe(true);
expect(wrapped).toMatch(/gitnexus analyze/);
expect(wrapped).not.toMatch(/sidecar is missing/i);
expect(wrapped).not.toMatch(/--force/);
expect(wrapped).not.toContain(refusal);
expect(isReadOnlyCheckpointInProgressError(new Error(wrapped))).toBe(false);
expect(isReadOnlyRecoveryFailure(new Error(wrapped))).toBe(true);
},
);
it('wraps shadow-replay refusal without rematching the native classifier', () => {
const wrapped = readOnlyRecoveryFailureMessage(dbPath, new Error(SHADOW));

View file

@ -165,8 +165,10 @@ describe('--skip-git CLI flag', () => {
env,
},
);
expect(keepContext).toContain('"status": "found"');
expect(keepContext).toContain('"filePath": "src/keep.ts"');
expect(JSON.parse(keepContext)).toMatchObject({
status: 'found',
symbol: { filePath: 'src/keep.ts' },
});
// Since #2470 a backend error payload also exits non-zero, so capture
// the payload from the exec failure instead of expecting exit 0.
@ -187,7 +189,7 @@ describe('--skip-git CLI flag', () => {
leakedContext = String(execErr.stdout ?? '');
}
expect(leakedStatus).toBe(1);
expect(leakedContext).toContain(`"error": "Symbol 'leaked' not found"`);
expect(JSON.parse(leakedContext).error).toBe("Symbol 'leaked' not found");
} finally {
fs.rmSync(tmpDir, { recursive: true, force: true });
fs.rmSync(gitnexusHome, { recursive: true, force: true });

View file

@ -0,0 +1,44 @@
import { describe, expect, it } from 'vitest';
import {
assertSymbolFilePath,
SymbolIdentityError,
} from '../../src/core/lbug/query-result-integrity.js';
describe('source UID/path consistency (#3527)', () => {
it.each([
['Method:checks/test_batch.py:Batch.test_run#0', 'Sources/Unrelated.swift'],
['Struct:Sources/Widget.swift:Widget', 'Sources/Other.swift'],
['File:src/actual.ts', 'src/unrelated.ts'],
['Folder:src/actual', 'src/unrelated'],
['Function:src/actual.ts:run', 'src/actual'],
])('rejects a printable mixed tuple: %s', (id, filePath) => {
expect(() => assertSymbolFilePath(id, filePath)).toThrow(SymbolIdentityError);
});
it.each([
['Method:checks/test_batch.py:Batch.test_run#0', 'checks/test_batch.py'],
['Struct:Sources/Widget.swift:Widget', 'Sources/Widget.swift'],
['File:src/part:one.ts', 'src/part:one.ts'],
['Folder:src/part:one', 'src/part:one'],
['Function:src/part:one.ts:run', 'src/part:one.ts'],
['Method:src/a.cpp:Owner::run#0', 'src/a.cpp'],
['Function:src/space .ts:run', 'src/space .ts'],
['func:alpha ', 'src/legacy.ts'],
['Function:legacy', 'src/legacy.ts'],
['Function:legacy:run', 'src/legacy.ts'],
['Class:vendor.v2:Widget', 'src/Widget.ts'],
['Class:objc:class:Widget', 'Sources/Widget.h'],
['Method:objc:method:Widget:-:load:', 'Sources/Widget.m'],
['Function:objc:function:helper', 'Sources/Widget.m'],
['Property:spring-config:application.properties:payment.timeout', 'application.properties'],
['CodeElement:spring-bean:Method:src/Config.java:Config.bean#0', 'src/Config.java'],
['CodeElement:spring-aop:Class:src/Service.java:Service:transactional', 'src/Service.java'],
['Route:GET:/api/items', 'src/routes.ts'],
['Tool:server:search', 'src/tools.ts'],
['Method:checks/test_batch.py:Batch.test_run#0', undefined],
['Method:checks/test_batch.py:Batch.test_run#0', null],
['Method:checks/test_batch.py:Batch.test_run#0', ''],
])('preserves valid paths and legacy/synthetic identities: %s / %j', (id, filePath) => {
expect(() => assertSymbolFilePath(id, filePath)).not.toThrow();
});
});

View file

@ -18,6 +18,58 @@ vi.mock('node:fs', () => ({
}));
describe('direct CLI tool commands', () => {
it.each(['0', '1.5', '10tokens'])('rejects invalid impact budgets: %s', async (maxTokens) => {
const exit = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
try {
const { impactCommand } = await import('../../src/cli/tool.js');
await impactCommand('auth', { maxTokens });
expect(callToolMock).not.toHaveBeenCalled();
expect(JSON.parse(writeSyncMock.mock.calls[0][1]).error).toContain('positive integer');
expect(exit).toHaveBeenCalledWith(1);
} finally {
exit.mockRestore();
}
});
it('returns a JSON budget error and fails when impact metadata cannot fit', async () => {
callToolMock.mockResolvedValue({
impactedCount: 1,
byDepth: { 1: [{ id: 'caller' }] },
affected_processes: [{ name: 'x'.repeat(10_000) }],
});
const { impactCommand } = await import('../../src/cli/tool.js');
await impactCommand('auth', { maxTokens: '100' });
const text = writeSyncMock.mock.calls[0][1];
expect(JSON.parse(text).error).toContain('Increase maxTokens');
expect(Buffer.byteLength(text)).toBeLessThanOrEqual(400);
expect(process.exitCode).toBe(1);
});
it('budgets compact output even on a terminal', async () => {
const tty = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
Object.defineProperty(process.stdout, 'isTTY', { configurable: true, value: true });
try {
callToolMock.mockResolvedValue({
byDepth: {
1: Array.from({ length: 20 }, (_, i) => ({
id: `caller${i}`,
name: `caller${i}`,
filePath: `src/${i}.ts`,
})),
},
});
const { impactCommand } = await import('../../src/cli/tool.js');
await impactCommand('auth', { maxTokens: '150' });
const text = writeSyncMock.mock.calls[0][1];
expect(Buffer.byteLength(text.trim())).toBeLessThanOrEqual(600);
expect(JSON.parse(text).pagination.trimmedForBudget.maxTokens).toBe(150);
expect(process.exitCode).toBeUndefined();
} finally {
if (tty) Object.defineProperty(process.stdout, 'isTTY', tty);
else delete process.stdout.isTTY;
}
});
beforeEach(() => {
vi.unstubAllEnvs();
vi.stubEnv('GITNEXUS_LANG', 'en');

View file

@ -3224,38 +3224,6 @@ svc = App::Models::Service.new
});
describe('stripNullable', () => {
it('strips User | null → User', () => {
expect(stripNullable('User | null')).toBe('User');
});
it('strips User | undefined → User', () => {
expect(stripNullable('User | undefined')).toBe('User');
});
it('strips User | null | undefined → User', () => {
expect(stripNullable('User | null | undefined')).toBe('User');
});
it('strips User? → User', () => {
expect(stripNullable('User?')).toBe('User');
});
it('passes through User unchanged', () => {
expect(stripNullable('User')).toBe('User');
});
it('refuses genuine union User | Repo → undefined', () => {
expect(stripNullable('User | Repo')).toBeUndefined();
});
it('returns undefined for null alone', () => {
expect(stripNullable('null')).toBeUndefined();
});
it('returns undefined for empty string', () => {
expect(stripNullable('')).toBeUndefined();
});
it('strips User | void → User', () => {
expect(stripNullable('User | void')).toBe('User');
});
@ -3272,22 +3240,6 @@ svc = App::Models::Service.new
expect(stripNullable('User | void | nil')).toBe('User');
});
it('returns undefined for None alone', () => {
expect(stripNullable('None')).toBeUndefined();
});
it('returns undefined for nil alone', () => {
expect(stripNullable('nil')).toBeUndefined();
});
it('returns undefined for void alone', () => {
expect(stripNullable('void')).toBeUndefined();
});
it('returns undefined for undefined alone', () => {
expect(stripNullable('undefined')).toBeUndefined();
});
it('strips nullable suffix with spaces: User ? → User', () => {
expect(stripNullable(' User? ')).toBe('User');
});

Some files were not shown because too many files have changed in this diff Show more