Merge branch 'main' into codex/quoted-shell-pattern-24a41916

This commit is contained in:
Gergő Magyar 2026-08-29 09:59:32 +01:00 • committed by GitHub
commit 3f82e46ca6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
260 changed files with 31506 additions and 3211 deletions

View file

@ -6,7 +6,7 @@
"plugins": [
{
"name": "gitnexus",
"version": "1.6.9",
"version": "1.6.10",
"source": {
"source": "local",
"path": "./gitnexus-claude-plugin"

View file

@ -11,7 +11,7 @@
"plugins": [
{
"name": "gitnexus",
"version": "1.6.9",
"version": "1.6.10",
"source": "./gitnexus-claude-plugin",
"description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase."
}

View file

@ -55,15 +55,19 @@ Deletes the `.gitnexus/` directory and unregisters the repo from the global regi
node .gitnexus/run.cjs wiki
```
Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
Generates repository documentation from the knowledge graph using an LLM. HTTP providers require an API key (saved to `~/.gitnexus/config.json` on first use). Local CLI providers (`--provider cursor|claude|codex|opencode|grok`) use your existing CLI login.
| Flag | Effect |
| ------------------- | ----------------------------------------- |
| `--force` | Force full regeneration |
| `--force` | Force full regeneration, also required to re-generate an existing wiki in a different language |
| `--provider <name>` | LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax). Local CLIs (`cursor`, `claude`, `codex`, `opencode`, `grok`) use your existing CLI login and skip `--api-key`. |
| `--model <model>` | LLM model (default: MiniMax-M3) |
| `--base-url <url>` | LLM API base URL |
| `--api-key <key>` | LLM API key |
| `--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) |
| `--lang <lang>` | Output language for generated documentation (e.g. english, chinese, spanish, japanese) |
| `--gist` | Publish wiki as a public GitHub Gist |
### list — Show all indexed repos

View file

@ -13,9 +13,28 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
- "This endpoint returns 500"
- Investigating bugs, errors, or unexpected behavior
## Bind the repository first
A root cause traced in the wrong repository is a wrong root cause.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask. This matters most for `cypher`, whose
statement carries no in-band hint of which database it ran against.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
A stale index describes the code from before your bug, so refresh before
trusting a trace, and state the repository and index freshness with the
diagnosis.
## Workflow
```
0. list_repos {} → Bind repo
1. query({search_query: "<error or symptom>"}) → Find related execution flows
2. context({name: "<suspect>"}) → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
@ -27,6 +46,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
@ -34,6 +54,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
- [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
- [ ] State the repository and index freshness with the diagnosis
```
## Debugging Patterns
@ -44,7 +65,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
| Wrong return value | `context` on the function → trace callees for data flow |
| Intermittent failure | `context` → look for external calls, async deps |
| Performance issue | `context` → find symbols with many callers (hot paths) |
| Recent regression | `detect_changes` to see what your changes affect |
| Recent regression | `detect_changes` to see what your changes affect — pass `worktree` for a linked worktree |
| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
## Tools
@ -52,7 +73,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
**query** — find code related to error:
```
query({search_query: "payment validation error"})
query({search_query: "payment validation error", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException
```
@ -60,13 +81,15 @@ query({search_query: "payment validation error"})
**context** — full context for a suspect:
```
context({name: "validatePayment"})
context({name: "validatePayment", repo: "my-app"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)
```
**cypher** — custom call chain traces:
**cypher** — custom call chain traces. Pass `repo` alongside the statement; the
Cypher text itself names no repository, so the result is unattributable without
it:
```cypher
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
@ -76,7 +99,7 @@ RETURN [n IN nodes(path) | n.name] AS chain
**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
```
trace({ from: "processCheckout", to: "fetchRates" })
trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
@ -87,15 +110,22 @@ When no path exists, `trace` reports the furthest reachable node — exactly whe
## Example: "Payment endpoint returns 500 intermittently"
```
1. query({search_query: "payment error handling"})
0. list_repos {}
→ total: 2 (my-app, billing-api) — bind my-app explicitly on every call
1. query({search_query: "payment error handling", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError
2. context({name: "validatePayment"})
2. context({name: "validatePayment", repo: "my-app"})
→ Outgoing calls: verifyCard, fetchRates (external API!)
3. READ gitnexus://repo/my-app/process/CheckoutFlow
→ Step 3: validatePayment → calls fetchRates (external)
4. Root cause: fetchRates calls external API without proper timeout
Repository: my-app Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -13,10 +13,22 @@ description: "Use when the user asks how code works, wants to understand archite
- "Where is the database logic?"
- Understanding code you haven't seen before
## Bind the repository first
Step 1 discovers what is indexed; every call after it must say which of those
it means. With one indexed repository, use the examples below as written. With
more than one, pass `repo` on every call: an omitted `repo` normally errors,
but under an MCP policy with a configured default it resolves to that default
silently. If you cannot tell which repository is meant, stop and ask. Report
the bound repository and index freshness alongside your explanation.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
## Workflow
```
1. READ gitnexus://repos → Discover indexed repos
1. list_repos {} or READ gitnexus://repos → Discover indexed repos
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
3. query({search_query: "<what you want to understand>"}) → Find related execution flows
4. context({name: "<symbol>"}) → Deep dive on specific symbol
@ -28,12 +40,14 @@ description: "Use when the user asks how code works, wants to understand archite
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] READ gitnexus://repo/{name}/context
- [ ] query for the concept you want to understand
- [ ] Review returned processes (execution flows)
- [ ] context on key symbols for callers/callees
- [ ] READ process resource for full execution traces
- [ ] Read source files for implementation details
- [ ] State the repository and index freshness with the explanation
```
## Resources
@ -50,7 +64,7 @@ description: "Use when the user asks how code works, wants to understand archite
**query** — find execution flows related to a concept:
```
query({search_query: "payment processing"})
query({search_query: "payment processing", repo: "my-app"})
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Symbols grouped by flow with file locations
```
@ -58,16 +72,20 @@ query({search_query: "payment processing"})
**context** — 360-degree view of a symbol:
```
context({name: "validateUser"})
context({name: "validateUser", repo: "my-app"})
→ Incoming calls: loginHandler, apiMiddleware
→ Outgoing calls: checkToken, getUserById
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
```
`repo` is required once more than one repository is indexed, and may be omitted
with a single one.
## Example: "How does payment processing work?"
```
1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
1. list_repos {} → total: 1 (my-app) — bind it
READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
2. query({search_query: "payment processing"})
→ CheckoutFlow: processPayment → validateCard → chargeStripe
→ RefundFlow: initiateRefund → calculateRefund → processRefund
@ -75,4 +93,8 @@ context({name: "validateUser"})
→ Incoming: checkoutHandler, webhookHandler
→ Outgoing: validateCard, chargeStripe, saveTransaction
4. Read src/payments/processor.ts for implementation details
5. Answer, noting: Repository my-app, index current
```
Had step 1 returned two repositories, every call above would carry
`repo: "my-app"`.

View file

@ -14,13 +14,42 @@ description: "Use when the user wants to know what will break if they change som
- Before making non-trivial code changes
- Before committing — to understand what your changes affect
## Bind the repository first
Impact analysis is the gate that authorizes an edit, so it must answer for the
repository you are about to edit.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask — every result below an ambiguous
identity inherits the ambiguity. `list_repos` is paginated, so page with
`offset: pagination.nextOffset` until `hasMore` is false before concluding a
repository is absent.
`detect_changes` takes `worktree` when your changes are in a linked worktree
the MCP server was not launched from. The server auto-detects a worktree only
when it was launched from inside one; otherwise `git diff` runs in the wrong
checkout and reports zero changed symbols — a false clean check that carries
none of the degradation flags described below. In the CLI fallbacks, `--repo .`
means the current checkout; pass the intended repository path instead when you
are not standing in it.
State the bound identity with your risk report:
```
Repository: <name> (<path>) Worktree: <path> Index: <commit>, <n> behind HEAD
```
## Workflow
```
0. list_repos {} → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) or `node .gitnexus/run.cjs impact "X" --direction upstream --repo .`
2. READ gitnexus://repo/{name}/processes → Check affected execution flows
3. detect_changes({scope: "all"}) or `node .gitnexus/run.cjs detect-changes --scope all --repo .`
4. Assess risk and report to user
4. Assess risk and report to user, echoing repo/worktree/index identity
```
> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@ -29,12 +58,14 @@ description: "Use when the user wants to know what will break if they change som
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] impact({target, direction: "upstream"}) or CLI fallback to find dependents
- [ ] Review d=1 items first (these WILL BREAK)
- [ ] Check high-confidence (>0.8) dependencies
- [ ] READ processes to check affected execution flows
- [ ] detect_changes({scope: "all"}) or CLI fallback for pre-commit check
- [ ] Assess risk level and report to user
- [ ] Confirm the checkout you edited is the checkout that was diffed
- [ ] Assess risk level and report, stating repo/worktree/index identity
```
## Understanding Output
@ -69,6 +100,7 @@ treating the symbol as safe to change or delete.
```
impact({
target: "validateUser",
repo: "my-app", // required once >1 repository is indexed
direction: "upstream",
minConfidence: 0.8,
maxDepth: 3
@ -92,15 +124,26 @@ detect_changes({scope: "all"})
→ Risk: MEDIUM
```
Add `repo` once more than one repository is indexed, and `worktree: "<abs
path>"` when your changes are in a linked worktree the server was not launched
from.
`partial: true` (a graph query failed) or `truncated: true` (the changed-symbol
listing was capped) means the result is short of the truth, and reads like
`UNKNOWN` above: a zero there means unseen, not unaffected. Re-run it rather
than tick the pre-commit check.
A wrong-worktree zero carries neither flag and is shape-identical to a genuine
clean result, so confirm the checkout you edited is the one that was diffed
before treating an empty change set as a passed check.
## Example: "What breaks if I change validateUser?"
```
1. impact({target: "validateUser", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
0. list_repos {}
→ total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
1. impact({target: "validateUser", repo: "my-app", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
→ d=1: loginHandler, apiMiddleware (WILL BREAK)
→ d=2: authRouter, sessionManager (LIKELY AFFECTED)
@ -108,4 +151,8 @@ than tick the pre-commit check.
→ LoginFlow and TokenRefresh touch validateUser
3. Risk: 2 direct callers, 2 processes = MEDIUM
Repository: my-app (/abs/path/my-app) Worktree: same Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -13,9 +13,32 @@ description: "Use when the user wants to rename, extract, split, move, or restru
- "Move this to a new file"
- Any task involving renaming, extracting, splitting, or restructuring code
## Bind the repository first
Refactoring writes to disk. `rename` with `dry_run: false` edits files in
whichever repository was resolved, so binding identity here is a safety gate,
not bookkeeping.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask. Never run `rename` with
`dry_run: false` until the preview in the same bound repository has been
reviewed — its returned `file_path` values show which checkout is about to be
written, so read them as a confirmation of identity.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
`detect_changes` takes `worktree` when you are editing a linked worktree the
MCP server was not launched from; otherwise `git diff` runs in the wrong
checkout and reports nothing changed, which reads as a verified refactor.
## Workflow
```
0. list_repos {} → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) → Map all dependents
2. query({search_query: "X"}) → Find execution flows involving X
3. context({name: "X"}) → See all incoming/outgoing refs
@ -29,7 +52,9 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Rename Symbol
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
- [ ] Confirm the previewed file paths are in the bound repository/worktree
- [ ] Review graph edits (high confidence) and text_search edits (review carefully)
- [ ] If satisfied: rename({..., dry_run: false}) — apply edits
- [ ] detect_changes() — verify only expected files changed
@ -39,6 +64,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Extract Module
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] context({name: target}) — see all incoming/outgoing refs
- [ ] impact({target, direction: "upstream"}) — find all external callers
- [ ] Define new module interface
@ -50,6 +76,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Split Function/Service
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] context({name: target}) — understand all callees
- [ ] Group callees by responsibility
- [ ] impact({target, direction: "upstream"}) — map callers to update
@ -64,7 +91,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
**rename** — automated multi-file rename:
```
rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
→ 12 edits across 8 files
→ 10 graph edits (high confidence), 2 text_search edits (review)
→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
@ -73,7 +100,7 @@ rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true
**impact** — map all dependents first:
```
impact({target: "validateUser", direction: "upstream"})
impact({target: "validateUser", repo: "my-app", direction: "upstream"})
→ d=1: loginHandler, apiMiddleware, testUtils
→ Affected Processes: LoginFlow, TokenRefresh
```
@ -92,6 +119,9 @@ listing was capped) means the result is short of the truth: a short or empty
list is not proof that only the expected files changed. Re-run it rather than
treat the refactor as verified.
A wrong-worktree zero carries neither flag and is indistinguishable from a
clean verification, so confirm the diffed checkout is the one you edited.
**cypher** — custom reference queries:
```cypher
@ -107,20 +137,28 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
| Cross-area refs | Use detect_changes after to verify scope |
| String/dynamic refs | query to find them |
| External/public API | Version and deprecate properly |
| Same name in another indexed repo | Bind `repo`; verify previewed paths before applying |
## Example: Rename `validateUser` to `authenticateUser`
```
1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
0. list_repos {}
→ total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
1. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
→ 12 edits: 10 graph (safe), 2 text_search (review)
→ Files: validator.ts, login.ts, middleware.ts, config.json...
2. Review text_search edits (config.json: dynamic reference!)
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: false})
→ Applied 12 edits across 8 files
4. detect_changes({scope: "all"})
4. detect_changes({scope: "all", repo: "my-app"})
→ Affected: LoginFlow, TokenRefresh
→ Risk: MEDIUM — run tests for these flows
Repository: my-app (/abs/path/my-app) Worktree: same Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

12
.gitattributes vendored
View file

@ -15,3 +15,15 @@
*.so binary
*.dll binary
*.dylib binary
# TypeScript sources are always text for diff purposes. Git's binary
# heuristic fires when EITHER blob in a pair carries a NUL, so a source
# file that carried one on a base commit still renders as "Binary files
# differ" — with no hunks and no inline comments — long after the byte
# itself is gone from the working tree. A head-side guard cannot see
# that, by construction. This does not mark the files binary or change
# how they are stored; it only stops the heuristic from hiding a diff.
*.ts diff
*.tsx diff
*.mts diff
*.cts diff

View file

@ -567,7 +567,7 @@ jobs:
NODE
- name: Attest build provenance (SLSA)
uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
with:
subject-path: 'gitnexus/vendor/tree-sitter-*/prebuilds/**/*.node'

View file

@ -616,8 +616,8 @@ jobs:
# where the measured overshoot is at most 6.3%. The estimator was fixed
# rather than the budget widened; distributions in _arms_note.
# The Kotlin arm here is a second corpus, not a replacement for the
# kotlin-import-target bench below, which carries tie-break probes (both
# file-set iteration orders, the four-tier cascade) this one does not.
# kotlin-import-target bench below, which carries declared-package
# correctness probes this shared corpus does not.
# It sits with the other resolver-index guards rather than at the end of
# the job: parking a new gate last is not safety, it is the slot least
# likely to execute (#2895 measured the last two guards running zero
@ -629,15 +629,13 @@ jobs:
run: node --expose-gc --import tsx bench/import-target/measure.mjs --check
working-directory: gitnexus
- name: Kotlin import-resolution identity + scaling guards
- name: Kotlin declared-package import correctness + scaling guards
if: ${{ !cancelled() }}
# Build-free: asserts resolveKotlinImportTarget resolves an unchanged
# file set (fingerprint, in both file-set iteration orders — every
# tie-break in that resolver is expressed only through iteration order)
# and that per-import cost stays independent of workspace size. The
# pre-index implementation scores 3.737 on this corpus against 0.99 for
# the index, so the gate separates them by a wide margin. Rationale and
# history: see the header of bench/kotlin-import-target/measure.mjs.
# Build-free: fingerprints declared-package evidence, external decoy
# rejection, top-level/member/wildcard imports, overload sets and root
# packages, then guards one package-index build per workspace against
# file-count and path-depth scaling. Rationale and history: see the
# header of bench/kotlin-import-target/measure.mjs.
run: node --import tsx bench/kotlin-import-target/measure.mjs --check
working-directory: gitnexus

View file

@ -48,7 +48,7 @@ jobs:
persist-credentials: false
- name: Initialize CodeQL
uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
with:
languages: ${{ matrix.language }}
queries: security-and-quality
@ -73,6 +73,6 @@ jobs:
- '**/test/**/fixtures/**'
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
with:
category: '/language:${{ matrix.language }}'

View file

@ -141,7 +141,7 @@ jobs:
uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
- name: Install Cosign
uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
@ -256,7 +256,7 @@ jobs:
# pulling from either GHCR or Docker Hub see the same provenance.
- name: Generate build provenance attestation (GHCR)
if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
with:
subject-name: ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
subject-digest: ${{ steps.build.outputs.digest }}
@ -264,7 +264,7 @@ jobs:
- name: Generate build provenance attestation (Docker Hub)
if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
with:
subject-name: docker.io/akonlabs/${{ matrix.image.slug }}
subject-digest: ${{ steps.build.outputs.digest }}

View file

@ -53,6 +53,6 @@ jobs:
retention-days: 5
- name: Upload to Security tab
uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
with:
sarif_file: results.sarif

View file

@ -50,7 +50,7 @@ jobs:
persist-credentials: false
- name: Setup Buildx
uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
- name: Build image (load locally for scan)
uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
@ -76,7 +76,7 @@ jobs:
exit-code: '0'
- name: Upload to Security tab
uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
with:
sarif_file: trivy-${{ matrix.image.name }}.sarif
category: trivy-${{ matrix.image.name }}

View file

@ -76,7 +76,7 @@ jobs:
continue-on-error: true
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3 # v4.37.6
uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
with:
sarif_file: zizmor.sarif
category: zizmor

View file

@ -174,7 +174,7 @@ converging on the routes phase's `(method, url)` registry:
| Filesystem convention | path → URL, no parsing | Next.js `app/`, Expo, PHP |
| Single-file framework route | `isRouteFile` + worker extraction | Laravel `routes/*.php` |
| Cross-file framework route | `discoverRootRouteFiles` + `extractRoutes` | Django `urlpatterns` |
| AST-level route in a normal file | `extractDecoratorRoutes` | Spring, FastAPI, NestJS, **JS/TS dispatch guards and static data route tables** |
| AST-level route in a normal file | `extractDecoratorRoutes` | Spring, FastAPI, NestJS (`@Controller` + `@Get`/`@Post`/…; URLs are controller-relative — `setGlobalPrefix` and URI versioning live in the bootstrap file and are not applied), **JS/TS dispatch guards and static data route tables** |
The last row is the one whose name undersells it. A route is DECLARED by a
decorator, but it can also be **inferred** from a raw `node:http` server's own
@ -403,6 +403,7 @@ Each language implements `LanguageProvider` (`language-provider.ts`). Key fields
| `typeConfig` | Type annotation extraction rules |
| `mroStrategy` | `first-wins` / `c3` / `none` |
| `descriptionExtractor` | Optional hook returning a symbol's doc-comment text as its `description`; feeds the embedding metadata header so doc-only terms are semantically searchable (issue #2270). Most languages register `createLeadingDocDescriptionExtractor` (shared, language-neutral; per-language comment/wrapper config passed at the call site) |
| `definitionPropertiesExtractor` | Optional language-owned hook for structured, clone-safe definition metadata. Shared ingestion persists these properties opaquely; the owning provider supplies the extraction semantics. |
16 providers in `languages/index.ts` via `satisfies Record<SupportedLanguages, LanguageProvider>` — missing a language is a compile error.

View file

@ -52,6 +52,12 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
- **Do:** Re-run plain `npx gitnexus analyze` — no `--embeddings` flag needed. A retained `embeddingCheckpoint` in the index metadata forces embedding generation for exactly the pending nodes regardless of flags, and clears once they succeed. `--drop-embeddings` abandons the pending nodes instead of retrying them; `--force` also discards the checkpoint (with a warning) and rebuilds without resuming it.
- **Why:** A long analyze run against a flaky HTTP embedding endpoint tolerates bounded sub-batch failures instead of aborting the whole run: it deletes the affected nodes' embedding rows (so they hold zero rows, never a partial set) and records those nodes as pending in `embeddingCheckpoint`. `stats.embeddings` stays an honest, non-zero count of everything that did succeed, so this state never trips the "Embeddings vanished" Sign above — `embedding-checkpoint-pending` is the only reliable signal.
### Scope extraction is incomplete
- **Trigger:** `npx gitnexus status` reports `incompleteReasons: ["scope-extraction-failed"]` when files were omitted, or `incompleteReasons: ["scope-extraction-unverified"]` when the index predates the completeness receipt or its metadata is unreadable. `impact`/`context` reports the same uncertainty as `epistemic: "lower-bound"`; confirmed omissions set `causes.scopeExtractionFiles > 0`.
- **Do:** Re-run `npx gitnexus analyze` (`--force` for a full graph rebuild). If the reason persists, inspect the scope-extraction warnings and treat impact counts as floors until the affected source is supported or corrected.
- **Why:** Parsing continued, but scope captures for the reported file count could not be produced even after the main-thread fallback. Calls, inheritance, imports, or accesses originating there may therefore be absent from the graph.
### Analyze reports INCOMPLETE with a collapsed graph write
- **Trigger:** `npx gitnexus status` reports `incompleteReasons: ["graph-write-collapsed"]`; the analyze summary printed `Repository indexed INCOMPLETELY` naming an expected and a persisted relationship count, and the CLI exited non-zero.

View file

@ -767,6 +767,7 @@ gitnexus wiki
# Use a custom model or provider (default model: minimax/minimax-m2.5)
gitnexus wiki --model gpt-4o
gitnexus wiki --base-url https://api.anthropic.com/v1
gitnexus wiki --provider grok # local Grok Build CLI (uses `grok login`, no API key)
# Force full regeneration
gitnexus wiki --force

View file

@ -46,6 +46,17 @@ npx gitnexus status
npx gitnexus list
```
**Scope extraction incomplete:** `npx gitnexus status` reports
`incompleteReasons: ["scope-extraction-failed"]` when one or more files still
lack scope captures after the worker and fallback passes. `impact` and `context`
then report a lower bound with `causes.scopeExtractionFiles` set to the affected
file count. Re-run `npx gitnexus analyze --force`; if the reason remains, inspect
the scope-extraction warnings for the unsupported or malformed source file.
Every pre-existing index remains unverified until it is analyzed once by a
version that writes the completeness receipt. An older index or unreadable completeness record reports
`incompleteReasons: ["scope-extraction-unverified"]`; re-analyze it before treating
empty impact results as exact.
---
## Embeddings

View file

@ -28,8 +28,10 @@ from .proposer_sandbox import (
SandboxError,
)
PINNED_GITNEXUS_VERSION = "1.6.9"
HARNESS_ROOT = Path(__file__).resolve().parents[2]
# The mounted runtime is built from this checkout, so the pin tracks the harness'
# own package version. A hardcoded copy only drifts on release day (#3064).
PINNED_GITNEXUS_VERSION = json.loads((HARNESS_ROOT / "gitnexus" / "package.json").read_text())["version"]
CE_ARMS = frozenset({"ce_workflow", "ce_workflow_direct", "ce_review"})
SANDBOX_CE_PLUGIN = "/opt/compound-engineering-plugin"

View file

@ -1,7 +1,7 @@
{
"name": "gitnexus",
"description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.",
"version": "1.6.9",
"version": "1.6.10",
"author": {
"name": "GitNexus"
},

View file

@ -1,7 +1,7 @@
{
"name": "gitnexus",
"description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.",
"version": "1.6.9",
"version": "1.6.10",
"skills": "./skills",
"mcpServers": "./.mcp.json",
"hooks": "./hooks/hooks.json",

View file

@ -19,14 +19,14 @@ node .gitnexus/run.cjs analyze
Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
| Flag | Effect |
|------|--------|
| `--force` | Force full re-index even if up to date |
| Flag | Effect |
| -------------- | ---------------------------------------------------------------- |
| `--force` | Force full re-index even if up to date |
| `--embeddings` | Enable embedding generation for semantic search (off by default) |
| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
| `--pdg` | Build the program-dependence layers used by `explain` and `pdg_query` (taint, CDG, and REACHING_DEF). |
**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
### status — Check index freshness
@ -44,10 +44,10 @@ node .gitnexus/run.cjs clean
Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
| Flag | Effect |
|------|--------|
| `--force` | Skip confirmation prompt |
| `--all` | Clean all indexed repos, not just the current one |
| Flag | Effect |
| --------- | ------------------------------------------------- |
| `--force` | Skip confirmation prompt |
| `--all` | Clean all indexed repos, not just the current one |
### wiki — Generate documentation from the graph
@ -55,19 +55,21 @@ Deletes the `.gitnexus/` directory and unregisters the repo from the global regi
node .gitnexus/run.cjs wiki
```
Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
Generates repository documentation from the knowledge graph using an LLM. HTTP providers require an API key (saved to `~/.gitnexus/config.json` on first use). Local CLI providers (`--provider cursor|claude|codex|opencode|grok`) use your existing CLI login.
| Flag | Effect |
|------|--------|
| `--force` | Force full regeneration, also required to re-gerenate an existing wiki in a different language |
| `--model <model>` | LLM model (default: MiniMax-M3) |
| `--base-url <url>` | LLM API base URL |
| `--api-key <key>` | LLM API key |
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
| `--gist` | Publish wiki as a public GitHub Gist |
| Flag | Effect |
| ------------------- | ----------------------------------------- |
| `--force` | Force full regeneration, also required to re-generate an existing wiki in a different language |
| `--provider <name>` | LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax). Local CLIs (`cursor`, `claude`, `codex`, `opencode`, `grok`) use your existing CLI login and skip `--api-key`. |
| `--model <model>` | LLM model (default: MiniMax-M3) |
| `--base-url <url>` | LLM API base URL |
| `--api-key <key>` | LLM API key |
| `--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) |
| `--lang <lang>` | Output language for generated documentation (e.g. english, chinese, spanish, japanese)|
| `--retries <n>` | Max LLM retry attempts per request (default: 3) |
| `--lang <lang>` | Output language for generated documentation (e.g. english, chinese, spanish, japanese) |
| `--gist` | Publish wiki as a public GitHub Gist |
### list — Show all indexed repos
```bash

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -13,9 +13,28 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
- "This endpoint returns 500"
- Investigating bugs, errors, or unexpected behavior
## Bind the repository first
A root cause traced in the wrong repository is a wrong root cause.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask. This matters most for `cypher`, whose
statement carries no in-band hint of which database it ran against.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
A stale index describes the code from before your bug, so refresh before
trusting a trace, and state the repository and index freshness with the
diagnosis.
## Workflow
```
0. list_repos {} → Bind repo
1. query({search_query: "<error or symptom>"}) → Find related execution flows
2. context({name: "<suspect>"}) → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
@ -27,6 +46,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
@ -34,6 +54,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
- [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
- [ ] State the repository and index freshness with the diagnosis
```
## Debugging Patterns
@ -44,7 +65,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
| Wrong return value | `context` on the function → trace callees for data flow |
| Intermittent failure | `context` → look for external calls, async deps |
| Performance issue | `context` → find symbols with many callers (hot paths) |
| Recent regression | `detect_changes` to see what your changes affect |
| Recent regression | `detect_changes` to see what your changes affect — pass `worktree` for a linked worktree |
| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
## Tools
@ -52,7 +73,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
**query** — find code related to error:
```
query({search_query: "payment validation error"})
query({search_query: "payment validation error", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException
```
@ -60,13 +81,15 @@ query({search_query: "payment validation error"})
**context** — full context for a suspect:
```
context({name: "validatePayment"})
context({name: "validatePayment", repo: "my-app"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)
```
**cypher** — custom call chain traces:
**cypher** — custom call chain traces. Pass `repo` alongside the statement; the
Cypher text itself names no repository, so the result is unattributable without
it:
```cypher
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
@ -76,7 +99,7 @@ RETURN [n IN nodes(path) | n.name] AS chain
**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
```
trace({ from: "processCheckout", to: "fetchRates" })
trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
@ -87,15 +110,22 @@ When no path exists, `trace` reports the furthest reachable node — exactly whe
## Example: "Payment endpoint returns 500 intermittently"
```
1. query({search_query: "payment error handling"})
0. list_repos {}
→ total: 2 (my-app, billing-api) — bind my-app explicitly on every call
1. query({search_query: "payment error handling", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError
2. context({name: "validatePayment"})
2. context({name: "validatePayment", repo: "my-app"})
→ Outgoing calls: verifyCard, fetchRates (external API!)
3. READ gitnexus://repo/my-app/process/CheckoutFlow
→ Step 3: validatePayment → calls fetchRates (external)
4. Root cause: fetchRates calls external API without proper timeout
Repository: my-app Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -13,10 +13,22 @@ description: "Use when the user asks how code works, wants to understand archite
- "Where is the database logic?"
- Understanding code you haven't seen before
## Bind the repository first
Step 1 discovers what is indexed; every call after it must say which of those
it means. With one indexed repository, use the examples below as written. With
more than one, pass `repo` on every call: an omitted `repo` normally errors,
but under an MCP policy with a configured default it resolves to that default
silently. If you cannot tell which repository is meant, stop and ask. Report
the bound repository and index freshness alongside your explanation.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
## Workflow
```
1. READ gitnexus://repos → Discover indexed repos
1. list_repos {} or READ gitnexus://repos → Discover indexed repos
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
3. query({search_query: "<what you want to understand>"}) → Find related execution flows
4. context({name: "<symbol>"}) → Deep dive on specific symbol
@ -28,12 +40,14 @@ description: "Use when the user asks how code works, wants to understand archite
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] READ gitnexus://repo/{name}/context
- [ ] query for the concept you want to understand
- [ ] Review returned processes (execution flows)
- [ ] context on key symbols for callers/callees
- [ ] READ process resource for full execution traces
- [ ] Read source files for implementation details
- [ ] State the repository and index freshness with the explanation
```
## Resources
@ -50,7 +64,7 @@ description: "Use when the user asks how code works, wants to understand archite
**query** — find execution flows related to a concept:
```
query({search_query: "payment processing"})
query({search_query: "payment processing", repo: "my-app"})
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Symbols grouped by flow with file locations
```
@ -58,16 +72,20 @@ query({search_query: "payment processing"})
**context** — 360-degree view of a symbol:
```
context({name: "validateUser"})
context({name: "validateUser", repo: "my-app"})
→ Incoming calls: loginHandler, apiMiddleware
→ Outgoing calls: checkToken, getUserById
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
```
`repo` is required once more than one repository is indexed, and may be omitted
with a single one.
## Example: "How does payment processing work?"
```
1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
1. list_repos {} → total: 1 (my-app) — bind it
READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
2. query({search_query: "payment processing"})
→ CheckoutFlow: processPayment → validateCard → chargeStripe
→ RefundFlow: initiateRefund → calculateRefund → processRefund
@ -75,4 +93,8 @@ context({name: "validateUser"})
→ Incoming: checkoutHandler, webhookHandler
→ Outgoing: validateCard, chargeStripe, saveTransaction
4. Read src/payments/processor.ts for implementation details
5. Answer, noting: Repository my-app, index current
```
Had step 1 returned two repositories, every call above would carry
`repo: "my-app"`.

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -14,13 +14,42 @@ description: "Use when the user wants to know what will break if they change som
- Before making non-trivial code changes
- Before committing — to understand what your changes affect
## Bind the repository first
Impact analysis is the gate that authorizes an edit, so it must answer for the
repository you are about to edit.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask — every result below an ambiguous
identity inherits the ambiguity. `list_repos` is paginated, so page with
`offset: pagination.nextOffset` until `hasMore` is false before concluding a
repository is absent.
`detect_changes` takes `worktree` when your changes are in a linked worktree
the MCP server was not launched from. The server auto-detects a worktree only
when it was launched from inside one; otherwise `git diff` runs in the wrong
checkout and reports zero changed symbols — a false clean check that carries
none of the degradation flags described below. In the CLI fallbacks, `--repo .`
means the current checkout; pass the intended repository path instead when you
are not standing in it.
State the bound identity with your risk report:
```
Repository: <name> (<path>) Worktree: <path> Index: <commit>, <n> behind HEAD
```
## Workflow
```
0. list_repos {} → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) or `node .gitnexus/run.cjs impact "X" --direction upstream --repo .`
2. READ gitnexus://repo/{name}/processes → Check affected execution flows
3. detect_changes({scope: "all"}) or `node .gitnexus/run.cjs detect-changes --scope all --repo .`
4. Assess risk and report to user
4. Assess risk and report to user, echoing repo/worktree/index identity
```
> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@ -29,12 +58,14 @@ description: "Use when the user wants to know what will break if they change som
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] impact({target, direction: "upstream"}) or CLI fallback to find dependents
- [ ] Review d=1 items first (these WILL BREAK)
- [ ] Check high-confidence (>0.8) dependencies
- [ ] READ processes to check affected execution flows
- [ ] detect_changes({scope: "all"}) or CLI fallback for pre-commit check
- [ ] Assess risk level and report to user
- [ ] Confirm the checkout you edited is the checkout that was diffed
- [ ] Assess risk level and report, stating repo/worktree/index identity
```
## Understanding Output
@ -69,6 +100,7 @@ treating the symbol as safe to change or delete.
```
impact({
target: "validateUser",
repo: "my-app", // required once >1 repository is indexed
direction: "upstream",
minConfidence: 0.8,
maxDepth: 3
@ -92,15 +124,26 @@ detect_changes({scope: "all"})
→ Risk: MEDIUM
```
Add `repo` once more than one repository is indexed, and `worktree: "<abs
path>"` when your changes are in a linked worktree the server was not launched
from.
`partial: true` (a graph query failed) or `truncated: true` (the changed-symbol
listing was capped) means the result is short of the truth, and reads like
`UNKNOWN` above: a zero there means unseen, not unaffected. Re-run it rather
than tick the pre-commit check.
A wrong-worktree zero carries neither flag and is shape-identical to a genuine
clean result, so confirm the checkout you edited is the one that was diffed
before treating an empty change set as a passed check.
## Example: "What breaks if I change validateUser?"
```
1. impact({target: "validateUser", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
0. list_repos {}
→ total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
1. impact({target: "validateUser", repo: "my-app", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
→ d=1: loginHandler, apiMiddleware (WILL BREAK)
→ d=2: authRouter, sessionManager (LIKELY AFFECTED)
@ -108,4 +151,8 @@ than tick the pre-commit check.
→ LoginFlow and TokenRefresh touch validateUser
3. Risk: 2 direct callers, 2 processes = MEDIUM
Repository: my-app (/abs/path/my-app) Worktree: same Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -13,9 +13,32 @@ description: "Use when the user wants to rename, extract, split, move, or restru
- "Move this to a new file"
- Any task involving renaming, extracting, splitting, or restructuring code
## Bind the repository first
Refactoring writes to disk. `rename` with `dry_run: false` edits files in
whichever repository was resolved, so binding identity here is a safety gate,
not bookkeeping.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask. Never run `rename` with
`dry_run: false` until the preview in the same bound repository has been
reviewed — its returned `file_path` values show which checkout is about to be
written, so read them as a confirmation of identity.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
`detect_changes` takes `worktree` when you are editing a linked worktree the
MCP server was not launched from; otherwise `git diff` runs in the wrong
checkout and reports nothing changed, which reads as a verified refactor.
## Workflow
```
0. list_repos {} → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) → Map all dependents
2. query({search_query: "X"}) → Find execution flows involving X
3. context({name: "X"}) → See all incoming/outgoing refs
@ -29,7 +52,9 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Rename Symbol
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
- [ ] Confirm the previewed file paths are in the bound repository/worktree
- [ ] Review graph edits (high confidence) and text_search edits (review carefully)
- [ ] If satisfied: rename({..., dry_run: false}) — apply edits
- [ ] detect_changes() — verify only expected files changed
@ -39,6 +64,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Extract Module
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] context({name: target}) — see all incoming/outgoing refs
- [ ] impact({target, direction: "upstream"}) — find all external callers
- [ ] Define new module interface
@ -50,6 +76,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Split Function/Service
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] context({name: target}) — understand all callees
- [ ] Group callees by responsibility
- [ ] impact({target, direction: "upstream"}) — map callers to update
@ -64,7 +91,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
**rename** — automated multi-file rename:
```
rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
→ 12 edits across 8 files
→ 10 graph edits (high confidence), 2 text_search edits (review)
→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
@ -73,7 +100,7 @@ rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true
**impact** — map all dependents first:
```
impact({target: "validateUser", direction: "upstream"})
impact({target: "validateUser", repo: "my-app", direction: "upstream"})
→ d=1: loginHandler, apiMiddleware, testUtils
→ Affected Processes: LoginFlow, TokenRefresh
```
@ -92,6 +119,9 @@ listing was capped) means the result is short of the truth: a short or empty
list is not proof that only the expected files changed. Re-run it rather than
treat the refactor as verified.
A wrong-worktree zero carries neither flag and is indistinguishable from a
clean verification, so confirm the diffed checkout is the one you edited.
**cypher** — custom reference queries:
```cypher
@ -107,20 +137,28 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
| Cross-area refs | Use detect_changes after to verify scope |
| String/dynamic refs | query to find them |
| External/public API | Version and deprecate properly |
| Same name in another indexed repo | Bind `repo`; verify previewed paths before applying |
## Example: Rename `validateUser` to `authenticateUser`
```
1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
0. list_repos {}
→ total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
1. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
→ 12 edits: 10 graph (safe), 2 text_search (review)
→ Files: validator.ts, login.ts, middleware.ts, config.json...
2. Review text_search edits (config.json: dynamic reference!)
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: false})
→ Applied 12 edits across 8 files
4. detect_changes({scope: "all"})
4. detect_changes({scope: "all", repo: "my-app"})
→ Affected: LoginFlow, TokenRefresh
→ Risk: MEDIUM — run tests for these flows
Repository: my-app (/abs/path/my-app) Worktree: same Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -2,7 +2,7 @@
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@1.6.9", "mcp"]
"args": ["-y", "gitnexus@1.6.10", "mcp"]
}
}
}

View file

@ -1,20 +1,40 @@
---
name: gitnexus-debugging
description: Trace bugs through call chains using knowledge graph
description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
---
# Debugging with GitNexus
## When to Use
- "Why is this function failing?"
- "Trace where this error comes from"
- "Who calls this method?"
- "This endpoint returns 500"
- Investigating bugs, errors, or unexpected behavior
## Bind the repository first
A root cause traced in the wrong repository is a wrong root cause.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask. This matters most for `cypher`, whose
statement carries no in-band hint of which database it ran against.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
A stale index describes the code from before your bug, so refresh before
trusting a trace, and state the repository and index freshness with the
diagnosis.
## Workflow
```
0. list_repos {} → Bind repo
1. query({search_query: "<error or symptom>"}) → Find related execution flows
2. context({name: "<suspect>"}) → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
@ -26,6 +46,7 @@ description: Trace bugs through call chains using knowledge graph
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
@ -33,45 +54,52 @@ description: Trace bugs through call chains using knowledge graph
- [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
- [ ] State the repository and index freshness with the diagnosis
```
## Debugging Patterns
| Symptom | GitNexus Approach |
|---------|-------------------|
| Error message | `query` for error text → `context` on throw sites |
| Wrong return value | `context` on the function → trace callees for data flow |
| Intermittent failure | `context` → look for external calls, async deps |
| Performance issue | `context` → find symbols with many callers (hot paths) |
| Recent regression | `detect_changes` to see what your changes affect |
| Symptom | GitNexus Approach |
| -------------------- | ---------------------------------------------------------- |
| Error message | `query` for error text → `context` on throw sites |
| Wrong return value | `context` on the function → trace callees for data flow |
| Intermittent failure | `context` → look for external calls, async deps |
| Performance issue | `context` → find symbols with many callers (hot paths) |
| Recent regression | `detect_changes` to see what your changes affect — pass `worktree` for a linked worktree |
| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
## Tools
**query** — find code related to error:
```
query({search_query: "payment validation error"})
query({search_query: "payment validation error", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException
```
**context** — full context for a suspect:
```
context({name: "validatePayment"})
context({name: "validatePayment", repo: "my-app"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)
```
**cypher** — custom call chain traces:
**cypher** — custom call chain traces. Pass `repo` alongside the statement; the
Cypher text itself names no repository, so the result is unattributable without
it:
```cypher
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chain
```
**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
```
trace({ from: "processCheckout", to: "fetchRates" })
trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
@ -82,15 +110,22 @@ When no path exists, `trace` reports the furthest reachable node — exactly whe
## Example: "Payment endpoint returns 500 intermittently"
```
1. query({search_query: "payment error handling"})
0. list_repos {}
→ total: 2 (my-app, billing-api) — bind my-app explicitly on every call
1. query({search_query: "payment error handling", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError
2. context({name: "validatePayment"})
2. context({name: "validatePayment", repo: "my-app"})
→ Outgoing calls: verifyCard, fetchRates (external API!)
3. READ gitnexus://repo/my-app/process/CheckoutFlow
→ Step 3: validatePayment → calls fetchRates (external)
4. Root cause: fetchRates calls external API without proper timeout
Repository: my-app Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -1,21 +1,34 @@
---
name: gitnexus-exploring
description: Navigate unfamiliar code using GitNexus knowledge graph
description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
---
# Exploring Codebases with GitNexus
## When to Use
- "How does authentication work?"
- "What's the project structure?"
- "Show me the main components"
- "Where is the database logic?"
- Understanding code you haven't seen before
## Bind the repository first
Step 1 discovers what is indexed; every call after it must say which of those
it means. With one indexed repository, use the examples below as written. With
more than one, pass `repo` on every call: an omitted `repo` normally errors,
but under an MCP policy with a configured default it resolves to that default
silently. If you cannot tell which repository is meant, stop and ask. Report
the bound repository and index freshness alongside your explanation.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
## Workflow
```
1. READ gitnexus://repos → Discover indexed repos
1. list_repos {} or READ gitnexus://repos → Discover indexed repos
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
3. query({search_query: "<what you want to understand>"}) → Find related execution flows
4. context({name: "<symbol>"}) → Deep dive on specific symbol
@ -27,44 +40,52 @@ description: Navigate unfamiliar code using GitNexus knowledge graph
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] READ gitnexus://repo/{name}/context
- [ ] query for the concept you want to understand
- [ ] Review returned processes (execution flows)
- [ ] context on key symbols for callers/callees
- [ ] READ process resource for full execution traces
- [ ] Read source files for implementation details
- [ ] State the repository and index freshness with the explanation
```
## Resources
| Resource | What you get |
|----------|-------------|
| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
| Resource | What you get |
| --------------------------------------- | ------------------------------------------------------- |
| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
## Tools
**query** — find execution flows related to a concept:
```
query({search_query: "payment processing"})
query({search_query: "payment processing", repo: "my-app"})
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Symbols grouped by flow with file locations
```
**context** — 360-degree view of a symbol:
```
context({name: "validateUser"})
context({name: "validateUser", repo: "my-app"})
→ Incoming calls: loginHandler, apiMiddleware
→ Outgoing calls: checkToken, getUserById
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
```
`repo` is required once more than one repository is indexed, and may be omitted
with a single one.
## Example: "How does payment processing work?"
```
1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
1. list_repos {} → total: 1 (my-app) — bind it
READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
2. query({search_query: "payment processing"})
→ CheckoutFlow: processPayment → validateCard → chargeStripe
→ RefundFlow: initiateRefund → calculateRefund → processRefund
@ -72,4 +93,8 @@ context({name: "validateUser"})
→ Incoming: checkoutHandler, webhookHandler
→ Outgoing: validateCard, chargeStripe, saveTransaction
4. Read src/payments/processor.ts for implementation details
5. Answer, noting: Repository my-app, index current
```
Had step 1 returned two repositories, every call above would carry
`repo: "my-app"`.

View file

@ -1,11 +1,12 @@
---
name: gitnexus-impact-analysis
description: Analyze blast radius before making code changes
description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
---
# Impact Analysis with GitNexus
## When to Use
- "Is it safe to change this function?"
- "What will break if I modify X?"
- "Show me the blast radius"
@ -13,13 +14,42 @@ description: Analyze blast radius before making code changes
- Before making non-trivial code changes
- Before committing — to understand what your changes affect
## Bind the repository first
Impact analysis is the gate that authorizes an edit, so it must answer for the
repository you are about to edit.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask — every result below an ambiguous
identity inherits the ambiguity. `list_repos` is paginated, so page with
`offset: pagination.nextOffset` until `hasMore` is false before concluding a
repository is absent.
`detect_changes` takes `worktree` when your changes are in a linked worktree
the MCP server was not launched from. The server auto-detects a worktree only
when it was launched from inside one; otherwise `git diff` runs in the wrong
checkout and reports zero changed symbols — a false clean check that carries
none of the degradation flags described below. In the CLI fallbacks, `--repo .`
means the current checkout; pass the intended repository path instead when you
are not standing in it.
State the bound identity with your risk report:
```
Repository: <name> (<path>) Worktree: <path> Index: <commit>, <n> behind HEAD
```
## Workflow
```
0. list_repos {} → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) or `node .gitnexus/run.cjs impact "X" --direction upstream --repo .`
2. READ gitnexus://repo/{name}/processes → Check affected execution flows
3. detect_changes({scope: "all"}) or `node .gitnexus/run.cjs detect-changes --scope all --repo .`
4. Assess risk and report to user
4. Assess risk and report to user, echoing repo/worktree/index identity
```
> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@ -28,31 +58,31 @@ description: Analyze blast radius before making code changes
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] impact({target, direction: "upstream"}) or CLI fallback to find dependents
- [ ] Review d=1 items first (these WILL BREAK)
- [ ] Check high-confidence (>0.8) dependencies
- [ ] READ processes to check affected execution flows
- [ ] detect_changes({scope: "all"}) or CLI fallback for pre-commit check
- [ ] Assess risk level and report to user
- [ ] Confirm the checkout you edited is the checkout that was diffed
- [ ] Assess risk level and report, stating repo/worktree/index identity
```
> `partial: true` (a graph query failed) or `truncated: true` (the changed-symbol listing was capped) means the result is short of the truth: a zero there means unseen, not unaffected. Re-run it rather than tick the pre-commit check.
## Understanding Output
| Depth | Risk Level | Meaning |
|-------|-----------|---------|
| d=1 | **WILL BREAK** | Direct callers/importers |
| d=2 | LIKELY AFFECTED | Indirect dependencies |
| d=3 | MAY NEED TESTING | Transitive effects |
| Depth | Risk Level | Meaning |
| ----- | ---------------- | ------------------------ |
| d=1 | **WILL BREAK** | Direct callers/importers |
| d=2 | LIKELY AFFECTED | Indirect dependencies |
| d=3 | MAY NEED TESTING | Transitive effects |
## Risk Assessment
| Affected | Risk |
|----------|------|
| <5 symbols, few processes | LOW |
| 5-15 symbols, 2-5 processes | MEDIUM |
| >15 symbols or many processes | HIGH |
| Affected | Risk |
| ------------------------------ | -------- |
| <5 symbols, few processes | LOW |
| 5-15 symbols, 2-5 processes | MEDIUM |
| >15 symbols or many processes | HIGH |
| Critical path (auth, payments) | CRITICAL |
| **Zero callers found** | **UNKNOWN** |
@ -66,9 +96,11 @@ treating the symbol as safe to change or delete.
## Tools
**impact** — the primary tool for symbol blast radius. If MCP is unavailable, use `node .gitnexus/run.cjs impact <symbol> --direction upstream --repo .` instead:
```
impact({
target: "validateUser",
repo: "my-app", // required once >1 repository is indexed
direction: "upstream",
minConfidence: 0.8,
maxDepth: 3
@ -83,6 +115,7 @@ impact({
```
**detect_changes** — git-diff based impact analysis. If MCP is unavailable, use `node .gitnexus/run.cjs detect-changes --scope all --repo .` instead:
```
detect_changes({scope: "all"})
@ -91,10 +124,26 @@ detect_changes({scope: "all"})
→ Risk: MEDIUM
```
Add `repo` once more than one repository is indexed, and `worktree: "<abs
path>"` when your changes are in a linked worktree the server was not launched
from.
`partial: true` (a graph query failed) or `truncated: true` (the changed-symbol
listing was capped) means the result is short of the truth, and reads like
`UNKNOWN` above: a zero there means unseen, not unaffected. Re-run it rather
than tick the pre-commit check.
A wrong-worktree zero carries neither flag and is shape-identical to a genuine
clean result, so confirm the checkout you edited is the one that was diffed
before treating an empty change set as a passed check.
## Example: "What breaks if I change validateUser?"
```
1. impact({target: "validateUser", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
0. list_repos {}
→ total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
1. impact({target: "validateUser", repo: "my-app", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
→ d=1: loginHandler, apiMiddleware (WILL BREAK)
→ d=2: authRouter, sessionManager (LIKELY AFFECTED)
@ -102,4 +151,8 @@ detect_changes({scope: "all"})
→ LoginFlow and TokenRefresh touch validateUser
3. Risk: 2 direct callers, 2 processes = MEDIUM
Repository: my-app (/abs/path/my-app) Worktree: same Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -1,20 +1,44 @@
---
name: gitnexus-refactoring
description: Plan safe refactors using blast radius and dependency mapping
description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
---
# Refactoring with GitNexus
## When to Use
- "Rename this function safely"
- "Extract this into a module"
- "Split this service"
- "Move this to a new file"
- Any task involving renaming, extracting, splitting, or restructuring code
## Bind the repository first
Refactoring writes to disk. `rename` with `dry_run: false` edits files in
whichever repository was resolved, so binding identity here is a safety gate,
not bookkeeping.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask. Never run `rename` with
`dry_run: false` until the preview in the same bound repository has been
reviewed — its returned `file_path` values show which checkout is about to be
written, so read them as a confirmation of identity.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
`detect_changes` takes `worktree` when you are editing a linked worktree the
MCP server was not launched from; otherwise `git diff` runs in the wrong
checkout and reports nothing changed, which reads as a verified refactor.
## Workflow
```
0. list_repos {} → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) → Map all dependents
2. query({search_query: "X"}) → Find execution flows involving X
3. context({name: "X"}) → See all incoming/outgoing refs
@ -23,13 +47,14 @@ description: Plan safe refactors using blast radius and dependency mapping
> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
> Every `detect_changes()` below: `partial: true` (a graph query failed) or `truncated: true` (the changed-symbol listing was capped) means the result is short of the truth — a short or empty list is not proof that only the expected files changed. Re-run it rather than treat the refactor as verified.
## Checklists
### Rename Symbol
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
- [ ] Confirm the previewed file paths are in the bound repository/worktree
- [ ] Review graph edits (high confidence) and text_search edits (review carefully)
- [ ] If satisfied: rename({..., dry_run: false}) — apply edits
- [ ] detect_changes() — verify only expected files changed
@ -37,7 +62,9 @@ description: Plan safe refactors using blast radius and dependency mapping
```
### Extract Module
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] context({name: target}) — see all incoming/outgoing refs
- [ ] impact({target, direction: "upstream"}) — find all external callers
- [ ] Define new module interface
@ -47,7 +74,9 @@ description: Plan safe refactors using blast radius and dependency mapping
```
### Split Function/Service
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] context({name: target}) — understand all callees
- [ ] Group callees by responsibility
- [ ] impact({target, direction: "upstream"}) — map callers to update
@ -60,21 +89,24 @@ description: Plan safe refactors using blast radius and dependency mapping
## Tools
**rename** — automated multi-file rename:
```
rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
→ 12 edits across 8 files
→ 10 graph edits (high confidence), 2 text_search edits (review)
→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
```
**impact** — map all dependents first:
```
impact({target: "validateUser", direction: "upstream"})
impact({target: "validateUser", repo: "my-app", direction: "upstream"})
→ d=1: loginHandler, apiMiddleware, testUtils
→ Affected Processes: LoginFlow, TokenRefresh
```
**detect_changes** — verify your changes after refactoring:
```
detect_changes({scope: "all"})
→ Changed: 8 files, 12 symbols
@ -82,7 +114,16 @@ detect_changes({scope: "all"})
→ Risk: MEDIUM
```
`partial: true` (a graph query failed) or `truncated: true` (the changed-symbol
listing was capped) means the result is short of the truth: a short or empty
list is not proof that only the expected files changed. Re-run it rather than
treat the refactor as verified.
A wrong-worktree zero carries neither flag and is indistinguishable from a
clean verification, so confirm the diffed checkout is the one you edited.
**cypher** — custom reference queries:
```cypher
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
RETURN caller.name, caller.filePath ORDER BY caller.filePath
@ -90,26 +131,34 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
## Risk Rules
| Risk Factor | Mitigation |
|-------------|------------|
| Many callers (>5) | Use rename for automated updates |
| Cross-area refs | Use detect_changes after to verify scope |
| String/dynamic refs | query to find them |
| External/public API | Version and deprecate properly |
| Risk Factor | Mitigation |
| ------------------- | ----------------------------------------- |
| Many callers (>5) | Use rename for automated updates |
| Cross-area refs | Use detect_changes after to verify scope |
| String/dynamic refs | query to find them |
| External/public API | Version and deprecate properly |
| Same name in another indexed repo | Bind `repo`; verify previewed paths before applying |
## Example: Rename `validateUser` to `authenticateUser`
```
1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
0. list_repos {}
→ total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
1. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
→ 12 edits: 10 graph (safe), 2 text_search (review)
→ Files: validator.ts, login.ts, middleware.ts, config.json...
2. Review text_search edits (config.json: dynamic reference!)
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: false})
→ Applied 12 edits across 8 files
4. detect_changes({scope: "all"})
4. detect_changes({scope: "all", repo: "my-app"})
→ Affected: LoginFlow, TokenRefresh
→ Risk: MEDIUM — run tests for these flows
Repository: my-app (/abs/path/my-app) Worktree: same Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -8,15 +8,15 @@
"name": "gitnexus-web",
"version": "0.0.0",
"dependencies": {
"@langchain/anthropic": "^1.5.1",
"@langchain/core": "^1.2.3",
"@langchain/anthropic": "^1.5.8",
"@langchain/core": "^1.2.8",
"@langchain/google-genai": "^2.2.0",
"@langchain/langgraph": "^1.4.9",
"@langchain/ollama": "^1.3.0",
"@langchain/openai": "^1.5.3",
"@sigma/edge-curve": "^3.1.0",
"@tailwindcss/vite": "^4.3.3",
"axios": "^1.18.1",
"axios": "^1.19.0",
"d3": "^7.9.0",
"dompurify": "^3.4.13",
"gitnexus-shared": "file:../gitnexus-shared",
@ -30,34 +30,34 @@
"i18next-browser-languagedetector": "^8.2.1",
"langchain": "^1.5.4",
"lru-cache": "^11.5.2",
"lucide-react": "^1.28.0",
"lucide-react": "^1.31.0",
"mermaid": "^11.16.1",
"mnemonist": "^0.40.4",
"pandemonium": "^2.4.0",
"react": "^19.2.5",
"react-dom": "^19.2.8",
"react-i18next": "^17.0.11",
"react-i18next": "^17.0.12",
"react-markdown": "^10.1.0",
"react-syntax-highlighter": "^16.1.1",
"react-zoom-pan-pinch": "^4.0.3",
"remark-gfm": "^4.0.1",
"sigma": "^3.0.3",
"tailwindcss": "^4.3.3",
"uuid": "^14.0.1",
"uuid": "^14.0.2",
"zod": "^4.4.3"
},
"devDependencies": {
"@babel/types": "^8.0.4",
"@playwright/test": "^1.62.0",
"@testing-library/jest-dom": "^6.9.1",
"@testing-library/jest-dom": "^7.0.0",
"@testing-library/react": "^16.3.2",
"@testing-library/user-event": "^14.6.1",
"@testing-library/user-event": "^14.6.6",
"@types/dompurify": "^3.2.0",
"@types/node": "^26.0.1",
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.4",
"@types/react-syntax-highlighter": "^15.5.13",
"@vercel/node": "^5.8.23",
"@vercel/node": "^5.10.1",
"@vitejs/plugin-react": "^6.0.5",
"@vitest/coverage-v8": "^4.1.9",
"jsdom": "^29.1.1",
@ -74,7 +74,7 @@
"../gitnexus-shared": {
"version": "1.0.0",
"devDependencies": {
"typescript": "^6.0.3"
"typescript": "^7.0.2"
}
},
"node_modules/@adobe/css-tools": {
@ -98,9 +98,9 @@
}
},
"node_modules/@anthropic-ai/sdk": {
"version": "0.103.0",
"resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.103.0.tgz",
"integrity": "sha512-1uG7RNgoHTUxzOXqSCODKt0UTVlxWiHk/2Tt2/uQJiPW7XzBeKVuJyd3Aw6T3LPyvZV/jDTnPLX7SaM70WLLjA==",
"version": "0.115.0",
"resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.115.0.tgz",
"integrity": "sha512-BJrFIVyjNuU8lfDyIJTvlRYzgQg+zEl78BxE7fq8esULsGz9IRQvGtW5spq3tydmtjQb/GFdooKGdGsetpx+lQ==",
"license": "MIT",
"dependencies": {
"json-schema-to-ts": "^3.1.1",
@ -246,9 +246,9 @@
}
},
"node_modules/@babel/runtime": {
"version": "7.29.2",
"resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.2.tgz",
"integrity": "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==",
"version": "7.29.7",
"resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz",
"integrity": "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==",
"license": "MIT",
"engines": {
"node": ">=6.9.0"
@ -1123,25 +1123,25 @@
}
},
"node_modules/@langchain/anthropic": {
"version": "1.5.1",
"resolved": "https://registry.npmjs.org/@langchain/anthropic/-/anthropic-1.5.1.tgz",
"integrity": "sha512-j92zCCd5BFH3rHMRzc2wBmSKDoVpinof1oh8aFiAz9TWbSOc4tGU4n6bqwy/wP0GH1uO96zZHLGCHBMPgrxTNw==",
"version": "1.5.8",
"resolved": "https://registry.npmjs.org/@langchain/anthropic/-/anthropic-1.5.8.tgz",
"integrity": "sha512-KZWgIf+04M9XZHhgH1rVJkqw/C26DM4a4jKk4Qc4HaSbRawN2Dw5nDffna+IoaU/50ohTdyB3HOz9g8XFQYF2A==",
"license": "MIT",
"dependencies": {
"@anthropic-ai/sdk": "^0.103.0",
"@anthropic-ai/sdk": "^0.115.0",
"zod": "^3.25.76 || ^4"
},
"engines": {
"node": ">=20"
},
"peerDependencies": {
"@langchain/core": "^1.2.1"
"@langchain/core": "^1.2.9"
}
},
"node_modules/@langchain/core": {
"version": "1.2.3",
"resolved": "https://registry.npmjs.org/@langchain/core/-/core-1.2.3.tgz",
"integrity": "sha512-F+L5SsciykwDl7eDxacnhDTcWe1IF6jetzfkvI5PPfq6ogWHO7xcjU90SGh/3lqbbS0tgun+qF01KIqxawrCsA==",
"version": "1.2.9",
"resolved": "https://registry.npmjs.org/@langchain/core/-/core-1.2.9.tgz",
"integrity": "sha512-conzSEj9Zu1AyXJLXsSbgrtxtxinmI1yGqQ5CIJZSoV5rvv+yvQE/vgBnoySpBQ/bl3YPgj2FL/gbDjWykLSfg==",
"license": "MIT",
"dependencies": {
"@cfworker/json-schema": "^4.0.2",
@ -2091,9 +2091,9 @@
}
},
"node_modules/@testing-library/jest-dom": {
"version": "6.9.1",
"resolved": "https://registry.npmjs.org/@testing-library/jest-dom/-/jest-dom-6.9.1.tgz",
"integrity": "sha512-zIcONa+hVtVSSep9UT3jZ5rizo2BsxgyDYU7WFD5eICBE7no3881HGeb/QkGfsJs6JTkY1aQhT7rIPC7e+0nnA==",
"version": "7.0.0",
"resolved": "https://registry.npmjs.org/@testing-library/jest-dom/-/jest-dom-7.0.0.tgz",
"integrity": "sha512-HKAH9C6mBo5yBG6yRO5i43L2iisencAo5z+o5P/saHUoY+miC5ivXRxHBJcFyB5ypPNxHJdK3BoF/3O4DIptMg==",
"dev": true,
"license": "MIT",
"dependencies": {
@ -2105,9 +2105,12 @@
"redent": "^3.0.0"
},
"engines": {
"node": ">=14",
"node": ">=22",
"npm": ">=6",
"yarn": ">=1"
},
"peerDependencies": {
"@testing-library/dom": ">=10 <11"
}
},
"node_modules/@testing-library/jest-dom/node_modules/dom-accessibility-api": {
@ -2146,9 +2149,9 @@
}
},
"node_modules/@testing-library/user-event": {
"version": "14.6.1",
"resolved": "https://registry.npmjs.org/@testing-library/user-event/-/user-event-14.6.1.tgz",
"integrity": "sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw==",
"version": "14.6.6",
"resolved": "https://registry.npmjs.org/@testing-library/user-event/-/user-event-14.6.6.tgz",
"integrity": "sha512-Jbs9FpkkIDw8FgSc6kOVsOv8JuuqGAL7J4X1oot77JxAoDlkNn2GRkd0aYRVuQ+pVQAiHWVkE4rX/dkF5fBiCw==",
"dev": true,
"license": "MIT",
"engines": {
@ -2638,13 +2641,13 @@
}
},
"node_modules/@vercel/build-utils": {
"version": "13.32.3",
"resolved": "https://registry.npmjs.org/@vercel/build-utils/-/build-utils-13.32.3.tgz",
"integrity": "sha512-rYk9EKq8ThkBC1vz38jZ8DmmxtKBjN6EfEOEz1ORL74PLVvET/l++R0tNmPrPg3eP+GI852KdArDmJRNCY6EOw==",
"version": "14.1.1",
"resolved": "https://registry.npmjs.org/@vercel/build-utils/-/build-utils-14.1.1.tgz",
"integrity": "sha512-kW9CeW0aokEBvX1rSgNyOKg90VyIQOmT0wBl7KXneM3Qs1+x4Puakqp97BdIgttWEtmN96UvdhQVG2bCA5JsPA==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
"@vercel/python-analysis": "0.11.1",
"@vercel/python-analysis": "0.13.2",
"cjs-module-lexer": "1.2.3",
"es-module-lexer": "1.5.0"
}
@ -2657,9 +2660,9 @@
"license": "MIT"
},
"node_modules/@vercel/error-utils": {
"version": "2.2.0",
"resolved": "https://registry.npmjs.org/@vercel/error-utils/-/error-utils-2.2.0.tgz",
"integrity": "sha512-WFWiRxfPzoYWYifaj4thSKvAaZZwUOqD4k5GINRIgZgCiS2E3iAJbWbIsIZmkQdTecWFHcWGA6q48CjisgpOBA==",
"version": "2.2.1",
"resolved": "https://registry.npmjs.org/@vercel/error-utils/-/error-utils-2.2.1.tgz",
"integrity": "sha512-9DhP8jP7raLML4hGsBemxX5fXuQnu5xxMV+HjGygGbzEmVK/+KyJ3QP2Cw7PdF0uXdb9N0Qa4c3tRGH34ZX6vw==",
"dev": true,
"license": "Apache-2.0"
},
@ -2691,9 +2694,9 @@
}
},
"node_modules/@vercel/node": {
"version": "5.8.23",
"resolved": "https://registry.npmjs.org/@vercel/node/-/node-5.8.23.tgz",
"integrity": "sha512-wigp1yONlJwFtPuyCrp6KI1umG78VhhEspNBXe2i9UOaxjjqLAR3DKiRQ/ivjvnDzV0SN7fuLxwLj+JcG0iwcQ==",
"version": "5.10.1",
"resolved": "https://registry.npmjs.org/@vercel/node/-/node-5.10.1.tgz",
"integrity": "sha512-muj+t8sZ2XHQDkWcHxkql2rbvr/HhZOqYdZBG7pw8F5RLasL3o0gjHLXJKwHAEHp2I3fd3AgbMud2oz+hzeV0g==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
@ -2701,10 +2704,10 @@
"@edge-runtime/primitives": "4.1.0",
"@edge-runtime/vm": "3.2.0",
"@types/node": "20.11.0",
"@vercel/build-utils": "13.32.3",
"@vercel/error-utils": "2.2.0",
"@vercel/build-utils": "14.1.1",
"@vercel/error-utils": "2.2.1",
"@vercel/nft": "1.10.0",
"@vercel/static-config": "3.4.0",
"@vercel/static-config": "3.4.1",
"async-listen": "3.0.0",
"cjs-module-lexer": "1.2.3",
"edge-runtime": "2.5.9",
@ -2739,9 +2742,9 @@
"license": "MIT"
},
"node_modules/@vercel/python-analysis": {
"version": "0.11.1",
"resolved": "https://registry.npmjs.org/@vercel/python-analysis/-/python-analysis-0.11.1.tgz",
"integrity": "sha512-EPPLuXJQhIDUx08H9nG76AR2HSgBquwe3OAX5s2w20M923iaWeGGVkhX/4yZ89CJfXEZgE1Aj/mX7lVHOVIcYA==",
"version": "0.13.2",
"resolved": "https://registry.npmjs.org/@vercel/python-analysis/-/python-analysis-0.13.2.tgz",
"integrity": "sha512-IEr5K2gvX143NBoQc1W4BWrdDWjZwxnIT6UrL5Y1dnyH7Cqc4AV00FIAddB1YpnIZBJwT4ZhE8QbgqBeO6C9Zw==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
@ -2765,9 +2768,9 @@
}
},
"node_modules/@vercel/static-config": {
"version": "3.4.0",
"resolved": "https://registry.npmjs.org/@vercel/static-config/-/static-config-3.4.0.tgz",
"integrity": "sha512-wCq90CMUB//ggnFh77NQO1xaLFsS4LigQIqKrH6ohnr9Br/KI1FhlErx62WfCOuueWaW+LVsbLOqNXIUjK8t6A==",
"version": "3.4.1",
"resolved": "https://registry.npmjs.org/@vercel/static-config/-/static-config-3.4.1.tgz",
"integrity": "sha512-kJKTyOg25JDRgDkHEkc+vWlvURxmSQkVKyRPO4EEGD/8HpJT+4u9Z/VGxwnCZ6zZBxYPpma283qBsHwY0gXjfw==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
@ -3131,13 +3134,13 @@
"license": "MIT"
},
"node_modules/axios": {
"version": "1.18.1",
"resolved": "https://registry.npmjs.org/axios/-/axios-1.18.1.tgz",
"integrity": "sha512-3nTvFlvpn9Zu/RkHUqtc7/+al4UpRW5az71ap5zccp6e8RAYEzhMTecX8Dz1wWDYrPpUoB1HAQEGEAEvUr7S9g==",
"version": "1.19.0",
"resolved": "https://registry.npmjs.org/axios/-/axios-1.19.0.tgz",
"integrity": "sha512-ht/iuYZXEjFxLH/Hkezgd7m6JKlHHXEUSneaDz8uZe1Gj5QZtCnpyDsckvAiEnT89OEbCLmnte4R4sn7P0EKFw==",
"license": "MIT",
"dependencies": {
"follow-redirects": "^1.16.0",
"form-data": "^4.0.5",
"form-data": "^4.0.6",
"https-proxy-agent": "^5.0.1",
"proxy-from-env": "^2.1.0"
}
@ -5715,9 +5718,9 @@
}
},
"node_modules/lucide-react": {
"version": "1.28.0",
"resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.28.0.tgz",
"integrity": "sha512-fARAFJULsGuDDydjp6+6blekG/sBIM29TerzLjc9bQUKAcEfrSc4ZQKb25KRz4OMKd87cZTb5dgq0w/T6KufVg==",
"version": "1.31.0",
"resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.31.0.tgz",
"integrity": "sha512-G8u2eEtoHUnUa9f8lbvqDhCiORMnYLdUEo06EEG9MQvHQrInKcX3Pa2TH39MM5qyzRcWETxB0+aOwAPI1g1kEg==",
"license": "ISC",
"peerDependencies": {
"react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
@ -7414,12 +7417,12 @@
}
},
"node_modules/react-i18next": {
"version": "17.0.11",
"resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-17.0.11.tgz",
"integrity": "sha512-cDtkXgxjuFTWUH6V+aQn1Ve5vDiUztCNPWW5GtSHDccsgRXO1nE6QFWCEmc1KAutrb3OUv87wFShJL5RhUwPXg==",
"version": "17.0.12",
"resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-17.0.12.tgz",
"integrity": "sha512-lFWPEGkxQ6RhusdUkysFBD58VHfSSzvHBzqMgN0SvfVpdQGfwtNkStTqdy08/sJd7s807qqutgx93fRpD0DJ3Q==",
"license": "MIT",
"dependencies": {
"@babel/runtime": "^7.29.2",
"@babel/runtime": "^7.29.7",
"html-parse-stringify": "^4.0.1",
"use-sync-external-store": "^1.6.0"
},
@ -8313,9 +8316,9 @@
}
},
"node_modules/uuid": {
"version": "14.0.1",
"resolved": "https://registry.npmjs.org/uuid/-/uuid-14.0.1.tgz",
"integrity": "sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew==",
"version": "14.0.2",
"resolved": "https://registry.npmjs.org/uuid/-/uuid-14.0.2.tgz",
"integrity": "sha512-xZe/16rV4aa+HGSOCiY2YeLT1OybRLrrkL/Rqaq7p7GMVXjFh+6wN4oMYgjFmnSnhY8t6Xpdl2l9qmnHYuMHwQ==",
"funding": [
"https://github.com/sponsors/broofa",
"https://github.com/sponsors/ctavan"

View file

@ -18,15 +18,15 @@
"test:e2e:report": "playwright show-report"
},
"dependencies": {
"@langchain/anthropic": "^1.5.1",
"@langchain/core": "^1.2.3",
"@langchain/anthropic": "^1.5.8",
"@langchain/core": "^1.2.8",
"@langchain/google-genai": "^2.2.0",
"@langchain/langgraph": "^1.4.9",
"@langchain/ollama": "^1.3.0",
"@langchain/openai": "^1.5.3",
"@sigma/edge-curve": "^3.1.0",
"@tailwindcss/vite": "^4.3.3",
"axios": "^1.18.1",
"axios": "^1.19.0",
"d3": "^7.9.0",
"dompurify": "^3.4.13",
"gitnexus-shared": "file:../gitnexus-shared",
@ -40,34 +40,34 @@
"i18next-browser-languagedetector": "^8.2.1",
"langchain": "^1.5.4",
"lru-cache": "^11.5.2",
"lucide-react": "^1.28.0",
"lucide-react": "^1.31.0",
"mermaid": "^11.16.1",
"mnemonist": "^0.40.4",
"pandemonium": "^2.4.0",
"react": "^19.2.5",
"react-dom": "^19.2.8",
"react-i18next": "^17.0.11",
"react-i18next": "^17.0.12",
"react-markdown": "^10.1.0",
"react-syntax-highlighter": "^16.1.1",
"react-zoom-pan-pinch": "^4.0.3",
"remark-gfm": "^4.0.1",
"sigma": "^3.0.3",
"tailwindcss": "^4.3.3",
"uuid": "^14.0.1",
"uuid": "^14.0.2",
"zod": "^4.4.3"
},
"devDependencies": {
"@babel/types": "^8.0.4",
"@playwright/test": "^1.62.0",
"@testing-library/jest-dom": "^6.9.1",
"@testing-library/jest-dom": "^7.0.0",
"@testing-library/react": "^16.3.2",
"@testing-library/user-event": "^14.6.1",
"@testing-library/user-event": "^14.6.6",
"@types/dompurify": "^3.2.0",
"@types/node": "^26.0.1",
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.4",
"@types/react-syntax-highlighter": "^15.5.13",
"@vercel/node": "^5.8.23",
"@vercel/node": "^5.10.1",
"@vitejs/plugin-react": "^6.0.5",
"@vitest/coverage-v8": "^4.1.9",
"jsdom": "^29.1.1",

View file

@ -31,6 +31,22 @@ describe('filterRepoFiles', () => {
expect(r.droppedCount).toBe(4);
});
it('excludes emitted _next output, including the Capacitor/Cordova copy', () => {
// `.next` was listed but `_next` was not, so a mobile-wrapped Next.js app
// uploaded its whole minified bundle against the server's caps for files
// the analyzer then discards anyway (#3007).
const input = [
f('repo/android/app/src/main/assets/public/_next/static/chunks/main.js'),
f('repo/ios/App/App/public/_next/static/chunks/framework.js'),
f('repo/_next/static/chunks/x.js'),
f('repo/src/index.ts'),
f('repo/src/_nextgen/index.ts'),
];
const r = filterRepoFiles(input);
expect(r.manifest).toEqual(['repo/src/index.ts', 'repo/src/_nextgen/index.ts']);
expect(r.droppedCount).toBe(3);
});
it('drops files over the per-file size cap', () => {
const input = [f('repo/big.bin', MAX_FILE_BYTES + 1), f('repo/small.ts', 10)];
const r = filterRepoFiles(input);

View file

@ -22,6 +22,17 @@ export const EXCLUDED_DIRS = new Set([
'build',
'out',
'.next',
// `.next` is the build CACHE, `_next` the EMITTED output — different
// directories. A Capacitor/Cordova shell leaves the emitted bundle at
// `<platform>/app/src/main/assets/public/_next/`, so without this the whole
// minified tree is uploaded against the server's file/byte caps only to be
// discarded by the analyzer's own ignore list (#3007).
//
// This pre-filter reads no repository ignore rules, so unlike the CLI walker
// a `.gitnexusignore` negation cannot recover anything dropped here. Names
// added below must therefore stay a subset of the analyzer's own list; see
// `gitnexus/test/unit/upload-filter-ignore-drift.test.ts`.
'_next',
'.nuxt',
'.cache',
'coverage',

View file

@ -4,6 +4,97 @@ All notable changes to GitNexus will be documented in this file.
## [Unreleased]
## [1.6.10] - 2026-08-27
### Added
- **Spring framework modeling expanded end to end** — AOP transactions, caching and security (#2783), `@Bean` factories and `@Resource` injection (#2740), profiles/conditions/auto-configuration (#2678), constructor and standard injection (#2632), bean candidate inventory (#2494), configuration-property consumers, and non-HTTP handler entry points (#2891)
- **Receiver chains typed from AST structure across all 14 languages**, with an explicit epistemic lower bound on what the graph can claim (#2708, #2744, #2747)
- **Java enum constant bodies modeled as first-class instances**, with JLS 13.1 anonymous-class naming (#2558)
- **More route surfaces indexed** — Java constant-based route paths such as `@PostMapping(ApiPathConstants.X)` (#2980) and JavaScript data route tables (#2972)
- **MCP server hardening** — repository allowlist, fail-closed read-only mode, deterministic output budgets, and normalized `impact`/`context` aliases
- **`bunx` lane so bun-only machines can run GitNexus** (#2765)
- **Codex support** — hooks, plugin marketplace and setup (#2328, #2369) — plus CodeBuddy and Qoder coding-agent integrations (#2368)
- **Skills mirrored to `.agents/skills/`** when an `.agents/` directory exists
- **One-click Render deploy** (#2804)
- **`serve` origin/proxy configuration is validated and port-scoped** (#2820)
- **Expanded TypeScript/JavaScript taint sink model** (#2490)
- **Wiki generation accepts explicit HTTP LLM hosts** (#2491)
- **Embedding request-body dimensions configurable** via `GITNEXUS_EMBEDDING_REQUEST_DIMS` (#2574)
- **Refreshed MiniMax model and endpoint configuration** (#2780)
- **`MAX_CALLABLE_VALUE_TARGETS` and `MAX_PROPERTY_DISPATCH_FANOUT` configurable via env** (#2725, #2726)
- **Opt-in `analyze --self-commit`** for AGENTS.md/CLAUDE.md churn (#2640)
- **Buffer pool sized to the graph before the database opens**, with an adaptive size hint
- **CI review agent runs as a coordinated reviewer swarm** on Sonnet 5 with structured, linked reviews (#2570, #2572), alongside the GitNexus Engineering Tool Kit skills (#2566) and an online skill-evolution loop (#2571)
- **Icebug community-engine prototype behind a gate** (#2376)
### Fixed
- **`group sync` stops claiming matching it never did** — the advertised BM25/embedding cascade was config, help text and MCP schema with no matcher behind it; the unread `matching.bm25_threshold`, `matching.embedding_threshold`, `detect.embedding_fallback` and `--skip-embeddings` surfaces are removed (#3020)
- **Emitted Next.js build output is ignored during ingestion**, and the inert `public/build` entry is deleted (#3018)
- **NestJS decorator routes are indexed** so `api_impact` and `route_map` stop reporting live endpoints as non-existent (#3017)
- **Import resolution gated by real module configuration** instead of path-suffix guessing — TypeScript config (#2953, #2956), Java and Kotlin declared packages (#2955, #2990), Go module paths (#2984), PHP Composer autoload maps (#2987), Python `__init__.py` re-exports (#2864) and unaliased dotted namespace imports (#2826, #2828), and JavaScript module extensions (#3034)
- **Interface dispatch is generic-instantiation aware** (#2912, #2939), fans out from Case 3b receivers (#2832, #2842) and from C# record interface calls (#2904), and resolves through generic-typed field receivers in every language (#2833, #2855)
- **Go method sets modeled exactly** so interface satisfaction is decidable (#2813, #2829), out-of-repo package qualifiers resolve, and an undecided interface check is no longer reported as a decided negative (#2873, #2921)
- **Go pointer-receiver calls resolve**, reporting the program boundary instead of hedging (#2766, #2782)
- **Java record support** — graph nodes for `record_declaration`, component accessors, enum and record interface heritage (#2564, #2916, #2935, #2936), plus `E.CONST.method()` enum-constant receiver dispatch (#2561) and JLS binary-name identities for local classes, enums, records and interfaces (#2562, #2653)
- **Rust module-qualified calls resolve against the module tree** (#2730, #2741), items are qualified by their enclosing `mod` chain (#2742, #2745), duplicate type names stay ambiguous in range binding (#2514, #2652), and `Box<dyn Trait>` names normalize
- **Closure bindings are call sources in every language**, and function-local values carry their own identity (#2693, #2695, #2699, #2718)
- **A named receiver's member never resolves lexically** (#2714), platform builtins stop resolving to unrelated same-file symbols (#2549), and inline constructor receivers are typed in every spelling (#2708, #2737)
- **Python calls resolve through constructor-injected fields** (#2628) and module-imported classes (#2770)
- **Package directories that repeat higher in the path resolve correctly** (#2881, #2929)
- **`check` stops reporting erased and deferred imports as initialization cycles** (#2934)
- **`detect_changes` no longer scales its query with the diff's hunk count** (#2915, #2930), and CR-only line-ending diffs are ignored (#2839)
- **`group` stops reporting what could not be measured as a measurement of zero** (#3012), resolves HTTP consumers through configured clients and constant route tables (#3008), and preserves manifest-only impact crossings (#2784)
- **`impact` and `context` are reproducible** — deterministic ordering on every capped query (#2787, #2796) — and Convex caller results are marked incomplete rather than empty (#3044)
- **Object handler identity is preserved** during ingestion (#3046), nested source directories are discovered (#3043), and parse-node insertion is canonicalized
- **Large-repo analyze OOM and the false worker-timeout cascade are fixed** (#2649, #2679)
- **Single-writer lock on the index write path** (#2658, #2677), atomic index swap with read-pool staleness invalidation (#2614), and reliable large incremental writeback commits (#2409, #2425)
- **Remote URLs are stripped of credentials before they are persisted** (#2914, #2928), and every registry write gets its own tmp path (#2888, #2920)
- **Schema version derived from a DDL fingerprint** instead of a hand-incremented constant (#2798, #2808), and the scope-resolution relation cross product is fully declared (#2792, #2793)
- **FTS reliability** — binary payloads stay out of the description column and an unbuildable index is confined to its own table (#2919), FTS-indexed DML is gated before the incremental writeback (#2841, #2854), analyze degrades instead of aborting on index-build failure (#2548), real LOAD errors surface and broken extension files self-heal (#2374, #2375), and Windows missing-dependency load failures are diagnosed (#2383)
- **`VECTOR` is loaded only when needed** (#3045) and before the incremental writeback touches embedding rows (#2623, #2624)
- **Buffer pool bounded instead of taking the native 80%-of-RAM default** (#2560), scaled by the OS page-size granule ratio (#2631, #2636), with a COPY-safe floor and actionable diagnostics for non-4K page sizes (#2424)
- **`Napi::Error` SIGABRT on analyze eliminated** — C++ type lookups are indexed and workers terminate only at JS-safe points (#2432, #2436)
- **Native-load failures fail closed**, including truncated-binary SIGBUS (#2441, #2651), and glibc-too-old loads are no longer misdiagnosed (#2672, #2689)
- **Index staleness reporting fixed** — no false-stale status after analyze, with inline staleness in `query`/`context`/`impact`/`cypher` (#2655, #2668, #2683)
- **Windows path handling** — the `\\?\` long-path prefix no longer breaks repo path matching (#2667, #2700), `parts` negation is honored (#2720), and missing-shadow errors let `serve` repo-switch recover (#2382, #2387)
- **Embeddings survive partial failures** — unparseable 200 responses are retried (#2790, #2795), batch inserts are retry-safe (#2453), HTTP generation is resumable, resume checkpoints bind to their provider, and proxy-blocked installs self-heal (#2370, #2372)
- **Custom HTTP embedding endpoint failures are reported as themselves**, not as Hugging Face download errors (#2385, #2386)
- **Exact symbol content with 0-based line storage and 1-based MCP display** (#2377, #2379, #2380)
- **`rename` reports every edit that apply writes** and reconciles its report on partial failure (#2605)
- **Global registry transactions serialized across processes** (#2716)
- **Swift indented conditional directives are preprocessed** so class bodies survive parsing (#2771), and Swift member-containment pairs are declared in the `CONTAINS` DDL (#2769)
- **JavaScript `exports.foo = function () {}` CommonJS exports are indexed** (#2723, #2729), and `const X = () => {}` is no longer double-indexed as a Function plus an edgeless Const twin (#2687, #2691)
- **JVM sibling injection is proximity-bounded** (#2732), and C#/Kotlin free calls are gated by instance ownership (#2563, #2654)
- **Dart extension type symbols are extracted** (#2539), and declarations recover after embedded NUL bytes (#2430)
- **CLI and hooks fail loudly on backend error payloads**, with an MCP query hint when the server owns the DB lock (#2396, #2397)
- **Committed agent guides stop churning**, with an `--index-only` nudge (#2907, #2927), and `gitnexus-plan` artifacts publish on macOS without an interpreter (#2905, #2922)
- **The 300-flows cap is removed for large repositories** (#2198)
### Changed
- **BREAKING: Node `^22.18.0 || >=24.11.0` is now the supported floor**; the `@types/uuid` stub is dropped
- **BREAKING: the non-functional `group` matching knobs are gone** — `matching.bm25_threshold`, `matching.embedding_threshold`, `detect.embedding_fallback` in `group.yaml`, the `gitnexus group sync --skip-embeddings` flag, and the MCP `group_sync` `skipEmbeddings` argument (#3020)
- **Structural relationships are held out of the JS heap by default** during analyze (#2680, #2685)
- **Global ignore support** — `core.excludesFile`, `.git/info/exclude`, and a user-level global ignore file are honored (#2606)
- **Plugin manifests sync on every version bump** (#2445), and planning output under `docs/plans` is no longer tracked
### Performance
- **Import resolution indexed instead of scanned** — every scanning resolver with a consolidated memo (#2911), a per-run workspace index for Go/C#/Dart/Ruby (#2898), and Kotlin import resolution (#2872)
- **MCP server startup drops the analyze-only language-provider closure** (#2802, #2806)
- **C++ qualified namespace members indexed once per pipeline run** (#2788, #2794)
- **Vendored Leiden O(communities × N) copy removed**, with Icebug wired to its real API (#2337, #2692)
- **`core.excludesFile` / `info/exclude` resolution memoized** (#2606)
### Chore / Dependencies
- **`@ladybugdb/core` bumped to ^0.18.3** for the rel-property IN-predicate fix (#2508, #2634)
- **Security overrides** — `sharp` >=0.35.0 for libvips vulnerabilities (#2993) and `adm-zip` >=0.6.0 for a memory-allocation vulnerability (#2992)
- **~130 dependency bumps** across the CLI, web app and GitHub Actions, including `@modelcontextprotocol/sdk`, LangChain, Vite, Vitest, TypeScript, React and the Docker/CodeQL action suite
- **CI hardening** — Windows shard watchdog widened with exit diagnostics (#2449), platform-sensitive matrix sharded to fix the Windows cross-platform timeout (#2394), and CI Report no longer dies silently when the tests job fails (#2728)
## [1.6.9] - 2026-07-04
### Added

View file

@ -256,6 +256,7 @@ gitnexus clean # Delete index for current repo
gitnexus clean --all --force # Delete all indexes
gitnexus wiki [path] # Generate LLM-powered docs from knowledge graph
gitnexus wiki --model <model> # Wiki with custom LLM model (default: minimax/minimax-m2.5)
gitnexus wiki --provider grok # Local Grok Build CLI (uses `grok login`, no API key)
gitnexus wiki --base-url http://llama-box.local:8080/v1 --allow-insecure-connection llama-box.local
# Allow an exact LAN/self-hosted HTTP LLM host; env: GITNEXUS_ALLOW_INSECURE_CONNECTION
gitnexus doctor # Show runtime platform capabilities and embedding configuration
@ -281,6 +282,21 @@ gitnexus group status <name> # Check staleness of repos in a group
gitnexus group impact <name> --target <symbol> --repo <groupPath> # Cross-repo blast radius
```
GraphQL contract matching is opt-in in the group's `group.yaml`:
```yaml
detect:
graphql: true
```
The initial exact-only slice matches methods and properties on top-level NestJS `@Resolver`
classes using imported `@Query`, `@Mutation`, and `@Subscription` decorators. Named
`.graphql`/`.gql` operations are anchored by generated `<OperationName>Document` declarations;
object, static `gql` template, and `TypedDocumentString` initializers must prove the operation name
and root fields. Dynamic decorator names, anonymous operations, and ambiguous or missing graph
anchors are deliberately omitted. Add common infrastructure fields such as `/health` to
`matching.exclude_links_paths` to keep those GraphQL contracts visible without cross-linking them.
> **`gitnexus uninstall`** reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove.
## Remote Embeddings

View file

@ -58,9 +58,6 @@ packages: {}
detect:
http: true
matching:
bm25_threshold: 0.7
embedding_threshold: 0.65
max_candidates_per_step: 3
`;
}

View file

@ -1,7 +1,8 @@
{
"fingerprint": "4ee15e742a9839671a900df4f57c1c91196c64256c8cab2ac445bec605a092d5",
"fingerprint": "c4d799c5336d616955b3530ba051b7dca300d1a0e412a66741cf2f27e04c533e",
"scaling_budget": 1.8,
"max_ms_large": 1000,
"_rebaselined_2856_property_is_detail": "Third and last of the bench guards this branch left red. The Property node table gained an `isDetail` BOOLEAN column (see PROPERTY_SCHEMA in src/core/lbug/schema.ts), so `streamAllCSVsToDisk` writes one more header field and one more cell per Property row — csv-generator.ts `propertyHeader` and the `node.label === 'Property'` tail. Verified to be header-only drift rather than a change in what is emitted: dumping every CSV this bench produces on `origin/main` and on this branch and diffing per-file (filename, byte length, sha256) shows the file SET is identical at 35 CSVs on both sides, 34 of the 35 are byte-identical, and the sole difference is `property.csv` growing 68 -> 77 bytes, `id,name,filePath,startLine,endLine,content,description,declaredType` -> `...,declaredType,isDetail`. The synthetic graph has no Property nodes, so no ROW moved at all. That is the check that matters here: a row routed to the wrong pair file, or a within-file reordering, is what this fingerprint exists to catch, and neither happened. Prior 69e9182ae205183ade24c3d8ad5d7292aea677144b1cbe443dd631bc25b0cafe -> 4ee15e742a9839671a900df4f57c1c91196c64256c8cab2ac445bec605a092d5. Both timing gates passed unchanged while this was red (scaling_ratio 0.783 vs budget 1.8, elapsed_ms_large 229ms vs the 1000ms backstop), so no throughput claim is being rebaselined away.",
"_rebaselined_3040_convex_endpoint_factory": "Const and Function gained a trailing convexEndpointFactory column. A deterministic 2,400-entity emit produced the same 35 CSV files and fingerprint c4d799c5336d616955b3530ba051b7dca300d1a0e412a66741cf2f27e04c533e. Removing the new Const and Function header fields plus the new trailing empty Function cell from each of 4,800 Function rows restored the exact prior fingerprint 4ee15e742a9839671a900df4f57c1c91196c64256c8cab2ac445bec605a092d5. No file or row moved or reordered. The measured scaling ratio remained 0.826 against the 1.8 budget and elapsed_ms_large was 307.75ms against the 1000ms backstop.",
"_note": "fingerprint = sha256 over per-file digests (filename + sha256(file bytes)), entry list sorted — binds each emitted line to its file so a row routed to the WRONG pair file changes the hash, AND catches within-file row reordering (file bytes hashed as-written). Byte-identity gate for #2203 U2/U3. NOTE: a future change that legitimately reorders emit (without changing the node/edge SET) will trip --check; regenerate then, and record WHY in a `_rebaselined_<reason>` key alongside — bench/scope-capture/baselines.json sets that convention and it is what makes a regenerated hash reviewable. scaling_budget bounds (t_large/t_small)/(LARGE/SMALL): observed ~0.95-1.05 (linear); 1.8 tolerates disk-I/O timing noise on CI while still catching an O(n^2) re-regression (~4x). max_ms_large=1000ms is a coarse absolute backstop (observed ~200ms) that catches a gross uniform slowdown the ratio gate misses; generous so CI host noise won't flake it. Regenerate via `node --import tsx bench/emit-persistence/measure.mjs`."
}

File diff suppressed because one or more lines are too long

View file

@ -24,9 +24,9 @@
* those two need that no other language does.
*
* Kotlin also has `bench/kotlin-import-target/`, and this does not replace it:
* that bench fingerprints both file-set iteration orders and probes the
* four-tier cascade shape by shape, which this corpus does not. What Kotlin
* gains here is a second corpus and the arms below that its own bench predates.
* that bench probes declared-package correctness cases shape by shape. What
* Kotlin gains here is a second corpus plus shared timing, context and heap
* arms.
*
* Each of the first nine resolvers answered its lookups with a full
* `allFilePaths` scan per import before its fix, so import resolution cost
@ -129,10 +129,10 @@
* - `depth_ratio` `t_deep/t_small` at a FIXED file count with ~6x the path
* components. `scaling_ratio` divides the file count out, so it is
* scale-invariant and structurally cannot see a cost that grows with path
* DEPTH instead — and `buildSuffixIndex` (C#, Ruby, PHP, Java) and Kotlin's
* `suffixByStem` each emit one entry per component. Go, Dart and COBOL,
* whose indexes are depth-free (COBOL's are keyed on the basename and
* nothing else), sit at ~0.9-1.0; the others sit legitimately above 1.0,
* DEPTH instead — and `buildSuffixIndex` (C#, Ruby, PHP, Java) emits one
* entry per component. Go, Dart, Kotlin and COBOL have depth-free indexes
* (COBOL's are keyed on the basename and nothing else), so they sit near
* 1.0; the suffix-indexed resolvers sit legitimately above 1.0,
* which is why the budget is per language. Python is the extreme and the
* reason the spread is worth a per-language number at all: its index is
* depth-free, but `hasRepoCandidate` and `resolveAbsoluteFromFiles` rebuild
@ -355,13 +355,13 @@
* measures 197.0 µs -> 9976.2 µs per import (50.6x) with every test still
* green, and nothing here could see it.
*
* `resolveOne` now makes the production call. Only TWO of the seventeen arms
* can observe it — PHP and Python are the only registered hooks that declare a
* fifth parameter — and that is ASSERTED rather than asserted-in-a-comment: the
* `resolveOne` now makes the production call. Four of the seventeen arms can
* observe it — PHP, Java, Kotlin and Python declare a fifth parameter — and
* that is ASSERTED rather than asserted-in-a-comment: the
* inventory arm at the foot of the file reads
* `SCOPE_RESOLVERS.get(language).resolveImportTarget.length` and reconciles it
* against `CONTEXT_LANGS` in both directions, so a language that grows a
* context leg cannot ship with the leg unmeasured. The other fourteen are handed
* context leg cannot ship with the leg unmeasured. The other thirteen are handed
* nothing and build no `ParsedFile[]` at all, so their numbers are unmoved.
*
* `newPass` mints the `ParsedFile[]` FIRST and derives the path set from it
@ -386,8 +386,8 @@
* equal what baselines.json records. Dropping the fifth argument, dropping
* `importedSymbolKind`, or reverting Python to `namespace` collapses the two
* onto one value and fails. PHP and Python still agree with their fallback on
* the main corpus; Java deliberately has no context-free fallback, so its
* fingerprints move to the declared-package answers recorded here.
* the main corpus; Java and Kotlin deliberately have no context-free fallback,
* so their fingerprints pin the declared-package answers recorded here.
*
* WHAT IS STILL NOT MEASURED, narrowed rather than deleted:
*
@ -399,12 +399,9 @@
* per parsed file, O(files) with no depth term, and the count gate in
* import-target-index-reuse.contract.test.ts is what holds it to one build
* per pass;
* - PHP's leg is measured with NO composer.json — `resolutionConfig` is
* undefined here, as it always has been — so `namespaceDirectories` only
* ever returns the directory of an already-resolved file and the PSR-4
* mapping branch stays unreached, exactly as `csharp` cannot reach the
* csproj leg. Closing that is a second PHP arm on the `csharp_csproj`
* precedent, not a parameter;
* - PHP runs with the Composer PSR-4 configuration every production project
* supplies. Configured hits and unmatched dependency misses share one
* workload, so the Composer gate cannot become an unmeasured fast path;
* - the `const` tail of PHP's leg (`candidateFiles.length === 1`) is a
* different ANSWER, not a different cost: `function` runs the identical
* candidate gather and `localDefs` filter and diverges only in the last two
@ -424,9 +421,9 @@
* a measured number rather than the "seconds are free here" the paragraph below
* would have let it be. Timed per language with the phase instrumented, twice:
* the heap phase goes 2.06 s -> 3.43 s (1.377 s and 1.370 s added over the two
* runs). The nine are kotlin 0.57 s — it retains the largest index of the nine
* and builds all three of its maps eagerly — then vue 0.18, typescript 0.17,
* cpp 0.09, swift 0.08, dart 0.08, go 0.07, cobol 0.07, rust 0.06. End to end
* runs). Those figures predate #2960: Kotlin now retains a compact
* declared-package/module-binding index rather than three path-suffix maps.
* End to end
* that is report mode 33.76 s -> 34.93 s (min of three runs each, +1.17 s,
* consistent with the phase measurement inside run-to-run noise). `--check` was
* 41.60 s before and reads 41.48-43.56 s after, i.e. the whole-run difference
@ -460,7 +457,7 @@ import { resolveGoImportTarget } from '../../src/core/ingestion/languages/go/imp
import { resolveDartImportTarget } from '../../src/core/ingestion/languages/dart/import-target.ts';
import { resolveRubyImportTarget } from '../../src/core/ingestion/languages/ruby/import-target.ts';
import { resolveCsharpImportTarget } from '../../src/core/ingestion/languages/csharp/import-target.ts';
import { resolveKotlinImportTarget } from '../../src/core/ingestion/languages/kotlin/import-target.ts';
import { kotlinScopeResolver } from '../../src/core/ingestion/languages/kotlin/scope-resolver.ts';
import { resolvePhpImportTargetInternal } from '../../src/core/ingestion/languages/php/import-target.ts';
import { javaScopeResolver } from '../../src/core/ingestion/languages/java/scope-resolver.ts';
import { cobolScopeResolver } from '../../src/core/ingestion/languages/cobol/scope-resolver.ts';
@ -550,13 +547,10 @@ const HEAP_LARGE = 32000;
const HEAP_PAD = 8;
/** The languages whose retained per-pass index carries a BUDGET — a ceiling, a
* floor derived from `heap_reading_bytes`, and the linear-growth ratio arm.
* All eight are measured the same way as the other nine (`retainedPassBytes`,
* one real import through the real resolver); what this list decides is which
* GATE a reading gets, not whether it is taken. The first five reach the shared
* `WorkspaceFileIndex` and retained NOTHING at BASE; `csharp_csproj` is the
* same corpus through the same index under the csproj context, and it is here
* rather than excluded as a duplicate because after #2903 its READ PATTERN,
* not its corpus, decides the number.
* All arms are measured through `retainedPassBytes`, one real import through
* the real resolver; this list decides which GATE a reading gets, not whether
* it is taken. The configured C# arm stays here because its read pattern
* reaches retained structures that the unconfigured arm cannot observe.
*
* The remaining three are `HEAP_BOUNDED`, DERIVED from this list rather than
* written beside it, and they carry an upper bound and NO floor. That asymmetry
@ -565,7 +559,7 @@ const HEAP_PAD = 8;
* would gate the noise. rust reads 16 B at both scales; swift's ratio is 0.888
* and cobol's 1.082, both outside the linearity every budgeted arm shows, so a
* floor and a ratio arm would be measuring the measurement. See the MEMORY
* section of the header for what re-measuring all seventeen found. */
* section of the header for what re-measuring the full inventory found. */
const HEAP_BUDGETED = [
'csharp',
'csharp_csproj',
@ -578,20 +572,8 @@ const HEAP_BUDGETED = [
// per-pass structure and each grows LINEARLY with the file count (ratio
// 0.996-1.004 against a 1.25 budget over 8000 -> 32000 files), so each can
// carry the full ceiling + floor + ratio set rather than a bound alone.
// kotlin's 40.82 MiB is larger than ruby's and java's, both of which were
// budgeted from the start, and it had no stated exclusion reason at all.
//
// Its ceiling is also the one TIGHT ceiling in this file — 1.0747x its
// reading where every other is 1.5x — because it is the only one gating a
// size REDUCTION being preserved rather than a footprint not growing.
// #2881 compacts `dirChildren`'s buckets, and deleting that `slice()` is
// invisible to every other instrument in the repository: output-identical,
// so no fingerprint moves; capacity has no reflective surface, so no unit
// assertion moves; and both heap scales grow together, so `heap_ratio_budget`
// divides it out. It shows up here and nowhere else, at +12.57%. See
// `_heap_compaction_gate` in baselines.json for the measurement, the
// arithmetic behind the 5.4 MB, and how to tell a lost compaction from a
// runner's heapUsed accounting moving under the whole file.
// Kotlin now retains its declared-package/module-binding index. Its measured
// 32000-file reading and standard 1.5x ceiling are recorded in baselines.json.
'kotlin',
'dart',
'go',
@ -613,17 +595,17 @@ const HEAP_BUDGETED = [
/**
* The arms handed the fifth `context` argument — `{ parsedFiles, parsedImport }`
* — because their registered hook DECLARES it. Three of seventeen, and the
* — because their registered hook DECLARES it. Four of seventeen arms, and the
* inventory arm at the foot of this file reconciles that claim against
* `SCOPE_RESOLVERS` in both directions rather than trusting this line.
*
* These are also the only arms for which `newPass` builds a `ParsedFile[]` at
* all. Building one for the other fourteen would cost their timed loop an
* all. Building one for the other thirteen would cost their timed loop an
* O(files) allocation per pass that no resolver of theirs can even observe —
* their hooks declare three or four parameters — so their numbers stay exactly
* where they were.
*/
const CONTEXT_LANGS = ['php', 'java', 'python'];
const CONTEXT_LANGS = ['php', 'java', 'kotlin', 'python'];
/**
* Needs `node --expose-gc` to force collection for a clean delta; without it
@ -726,6 +708,15 @@ const joinBase = (baseUrl, rest) => (baseUrl === '' ? rest : `${baseUrl}/${rest}
*/
const tsBaseUrlFor = (pad) =>
pad === 0 ? '' : Array.from({ length: pad }, (_, n) => `d${n}`).join('/');
const phpComposerConfigFor = (pad) => ({
psr4: new Map([['App', joinBase(tsBaseUrlFor(pad), 'src/App')]]),
authoritativePsr4: new Set(['App']),
});
const renderPhpComposerConfig = (config) =>
[...config.psr4]
.map(([namespace, directory]) => `${namespace || '<root>'}=${directory || '<root>'}`)
.sort()
.join(';');
/** Keyed by LAYOUT name, so there is no `csharp_csproj` row: `buildFiles`
* aliases that arm to `csharp` before this table is read. */
const EXTENSION = {
@ -931,7 +922,7 @@ function collideDir(lang, d, i) {
`mod${d}/src/main/kotlin/com/example/models/inner/com/example/models`
: `mod${d}/src/main/kotlin/com/example/models`;
}
if (lang === 'php') return `svc${d}/src/Models`;
if (lang === 'php') return `src/App/Svc${d}/Models`;
if (lang === 'java') {
return d % 7 === 0
? `svc${d}/src/main/java/com/example/model/inner/model`
@ -965,11 +956,10 @@ function collideDir(lang, d, i) {
* a handful of buckets.
*
* `pad` prepends that many extra directory components to every path. Every
* language's in-repo target resolves through a path SUFFIX (Go's module leg
* against the package dir, C#'s progressive strip, Dart's `lib/<rel>`, Ruby's
* suffix match, Kotlin's `suffixByStem`), so the padding changes path depth
* without changing what resolves — which is what makes the `deep` arm a clean
* depth measurement rather than a different corpus.
* path-based resolver keeps the same answer under that padding. Kotlin's
* package facts are also unchanged by it. The padding therefore changes path
* depth without changing what resolves, making `deep` a clean depth
* measurement rather than a different corpus.
*
* Split out from `buildRepo` so the heap arm can build 32k paths without also
* minting 256k import tuples it would never resolve.
@ -1048,6 +1038,12 @@ function buildFiles(lang, fileCount, pad, shape) {
: ext;
files.push(`${prefix}${dir}/${stem}${suffix}`);
}
// One real suffix decoy makes the PHP external gate observable: with the
// gate, Vendor0 stays unresolved; without it, suffix fallback resolves this
// path and the exact fingerprint/external-probe result changes.
if (layout === 'php' && files.length > 0) {
files[files.length - 1] = `${prefix}legacy/Vendor0/Ghost/Missing.php`;
}
return files;
}
@ -1097,6 +1093,35 @@ const javaProbeFile = (filePath, packageName) => ({
},
});
const kotlinProbeFile = (filePath, packageName, exportName) => {
const base = probeFile(filePath, [['Class', `${packageName}.${exportName}`]]);
const def = base.localDefs[0];
const moduleScope = `module:${filePath}`;
return {
...base,
moduleScope,
scopes: [
{
id: moduleScope,
parent: null,
kind: 'Module',
range: { startLine: 1, startCol: 0, endLine: 1, endCol: 1 },
filePath,
bindings: new Map([[exportName, [{ def, origin: 'local' }]]]),
ownedDefs: [def],
imports: [],
typeBindings: new Map(),
},
],
captureSideChannel: {
kind: 'kotlin',
companionScopes: [],
packageFact: { status: 'known', packageName },
classAnnotations: [],
},
};
};
function javaBenchmarkPackage(filePath) {
const uniquePackage = /\/com\/example\/(pkg\d+)(?:\/|$)/.exec(`/${filePath}`)?.[1];
if (uniquePackage !== undefined) return `com.example.${uniquePackage}`;
@ -1106,6 +1131,13 @@ function javaBenchmarkPackage(filePath) {
: '';
}
function kotlinBenchmarkPackage(filePath) {
const rootedPath = '/' + filePath;
const uniquePackage = /\/com\/example\/(pkg\d+)(?:\/|$)/.exec(rootedPath)?.[1];
if (uniquePackage !== undefined) return `com.example.${uniquePackage}`;
return /\/com\/example\/models(?:\/|$)/.test(rootedPath) ? 'com.example.models' : '';
}
/**
* The `ParsedFile[]` the orchestrator threads beside the path set, for the three
* languages whose hook declares a `context` — see `CONTEXT_LANGS`.
@ -1122,9 +1154,8 @@ function javaBenchmarkPackage(filePath) {
* The owner segment is the file's own directory name (`Ns7`, `Models`, `pkg7`),
* which is stable across the `small`, `deep` and `collide` arms — so the `deep`
* arm differs from `small` in path DEPTH alone, exactly as it does for the path
* set. That matters here: `directoryAliases` emits one entry per path segment,
* so `filesByDirectory` is O(files × depth) and the depth arm is the only one
* that can see it.
* set. `filesByDirectory` is exact and linear in the file count; the shared
* suffix index remains the path-depth-sensitive structure this arm measures.
*/
function buildParsedFiles(lang, files) {
const parsedFiles = [];
@ -1133,6 +1164,12 @@ function buildParsedFiles(lang, files) {
parsedFiles.push(javaProbeFile(filePath, javaBenchmarkPackage(filePath)));
continue;
}
if (lang === 'kotlin') {
const slash = filePath.lastIndexOf('/');
const stem = filePath.slice(slash + 1, filePath.lastIndexOf('.'));
parsedFiles.push(kotlinProbeFile(filePath, kotlinBenchmarkPackage(filePath), stem));
continue;
}
const slash = filePath.lastIndexOf('/');
const stem = filePath.slice(slash + 1, filePath.lastIndexOf('.'));
const parent = slash < 0 ? '' : filePath.slice(0, slash);
@ -1218,21 +1255,18 @@ function uniqueTarget(lang, { local, r, d, j, dirs }) {
: `com.ghost${(r >>> 4) % 97}.deep.Missing`;
}
if (lang === 'php') {
// Backslash-separated, the way a `use` statement is actually written; the
// resolver normalizes them. No composer.json is threaded (the adapter's
// `resolutionConfig` is left undefined), so every one of these lands on
// `suffixResolve` — the leg that ran one `findIndex` over every file per
// path part per extension, ~50 of them, and measured 96.40 ms per import at
// 20k files before #2901.
return local
? `App\\Ns${d}\\File${j}`
: (r >>> 3) % 2 === 0
? [
'Psr\\Log\\LoggerInterface',
'Symfony\\Component\\Console\\Command',
'Doctrine\\ORM\\EntityManager',
][(r >>> 4) % 3]
: `Vendor${(r >>> 4) % 97}\\Ghost\\Missing`;
if (local) {
const namespace = d % 7 === 0 ? `Ns${d}\\Sub\\Ns${d}` : `Ns${d}`;
const leadingSeparator = (r >>> 3) % 4 === 0 ? '\\' : '';
return `${leadingSeparator}App\\${namespace}\\File${j}`;
}
return (r >>> 3) % 2 === 0
? [
'Psr\\Log\\LoggerInterface',
'Symfony\\Component\\Console\\Command',
'Doctrine\\ORM\\EntityManager',
][(r >>> 4) % 3]
: `Vendor${(r >>> 4) % 97}\\Ghost\\Missing`;
}
if (lang === 'java') {
// Java has NO in-repo-namespace gate (#2910 is filed for it), so a JDK
@ -1409,15 +1443,8 @@ function collideTarget(lang, { local, r, d, j, dirs }) {
`package:ext${(r >>> 4) % 97}/other/mod${(r >>> 4) % 8}.dart`;
}
if (lang === 'kotlin') {
// Same wildcard share as the unique arm. This used to send the `d % 7`
// nested slice to `com.example.vendor${d}`, a package that exists nowhere,
// to mirror the unique arm's nested slice — which missed, because
// `dirChildren` required the parent to be the FIRST occurrence of its own
// name and `…/com/example/pkg${d}/inner/pkg${d}` therefore did not belong to
// `pkg${d}`. #2881 removed that rule, so the unique arm's nested wildcards
// resolve and the mirror has to as well, or this arm stops resolving as
// many imports as `small` — which is the invariant that makes the two
// timings comparable, and it is asserted below.
// Same wildcard share and declared-package workload as the unique arm.
// Directory collisions must not affect semantic package resolution.
return local
? (r >>> 3) % 3 === 0
? `com.example.models.*`
@ -1429,21 +1456,17 @@ function collideTarget(lang, { local, r, d, j, dirs }) {
: `com.ghost${(r >>> 4) % 97}.deep.Missing`;
}
if (lang === 'php') {
// `Models\Mod{n}` is carried by every service, so the segment-suffix key it
// resolves through holds one entry no matter how many files exist: PHP
// answers from keyed maps and is collision-IMMUNE, which is what this arm
// asserts. The local spelling still always resolves, as it does on the
// unique layout — PHP's cascade strips leading segments, so even the
// nested-same-name slice is reachable by a shorter suffix.
return local
? `App\\Models\\Mod${Math.floor(j / dirs)}`
: (r >>> 3) % 2 === 0
? [
'Psr\\Log\\LoggerInterface',
'Symfony\\Component\\Console\\Command',
'Doctrine\\ORM\\EntityManager',
][(r >>> 4) % 3]
: `Vendor${(r >>> 4) % 97}\\Ghost\\Missing`;
if (local) {
const leadingSeparator = (r >>> 3) % 4 === 0 ? '\\' : '';
return `${leadingSeparator}App\\Svc${j % dirs}\\Models\\Mod${Math.floor(j / dirs)}`;
}
return (r >>> 3) % 2 === 0
? [
'Psr\\Log\\LoggerInterface',
'Symfony\\Component\\Console\\Command',
'Doctrine\\ORM\\EntityManager',
][(r >>> 4) % 3]
: `Vendor${(r >>> 4) % 97}\\Ghost\\Missing`;
}
if (lang === 'java') {
// Every file declares the same package despite living under different
@ -1585,6 +1608,9 @@ function buildRepo(lang, fileCount, pad = 0, shape = 'unique') {
imports.push([from, mintTarget(lang, { local, r, d, j, dirs })]);
}
}
if (lang === 'php' && imports.length > 0) {
imports[0] = [files[0], 'Vendor0\\Ghost\\Missing'];
}
return { files, imports };
}
@ -1645,7 +1671,7 @@ function newPass(lang, files, pad = 0) {
restoreBenchmarkSideChannels(lang, parsedFiles);
return {
allFilePaths: new Set(parsedFiles.map((f) => f.filePath)),
config: undefined,
config: lang === 'php' ? phpComposerConfigFor(pad) : undefined,
parsedFiles,
};
}
@ -1666,9 +1692,11 @@ const contextFor = (pass, parsedImport) =>
: { parsedFiles: pass.parsedFiles, parsedImport, filesSkipped: 0 };
function restoreBenchmarkSideChannels(lang, parsedFiles) {
if (lang !== 'java') return;
javaScopeResolver.loadResolutionConfig?.('');
for (const parsed of parsedFiles) javaScopeResolver.applyCaptureSideChannel?.(parsed);
const resolver =
lang === 'java' ? javaScopeResolver : lang === 'kotlin' ? kotlinScopeResolver : undefined;
if (resolver === undefined) return;
resolver.loadResolutionConfig?.('');
for (const parsed of parsedFiles) resolver.applyCaptureSideChannel?.(parsed);
}
/** The timed loop. One `newPass` per pass, so every pass pays exactly one index
@ -1689,9 +1717,18 @@ function resolveOne(lang, from, target, pass) {
if (lang === 'dart') return resolveDartImportTarget(target, from, allFilePaths);
if (lang === 'ruby') return resolveRubyImportTarget(target, from, allFilePaths);
if (lang === 'kotlin') {
return resolveKotlinImportTarget(
{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: target },
{ fromFile: from, allFilePaths },
const parsedImport = {
kind: 'named',
localName: 'X',
importedName: 'X',
targetRaw: target,
};
return kotlinScopeResolver.resolveImportTarget(
target,
from,
allFilePaths,
pass.config,
contextFor(pass, parsedImport),
);
}
// `pass.config` is undefined for PHP, so no composer.json: the PSR-4 mapping
@ -2006,7 +2043,9 @@ const HEAP_PROBE_TARGET = {
// (`getFilesInDir`) before answering null — the three-map read pattern.
csharp_csproj: 'App.Missing0',
ruby: 'gem0/missing/thing',
php: 'Vendor0\\Ghost\\Missing',
// A mapped-but-missing class forces the Composer mapping and suffix-index
// read paths. The separate external probe below keeps the fast gate visible.
php: 'App\\HeapGhost0\\AbsentHeapProbe',
java: 'com.google.common.vendor0.Missing',
javascript: 'vendor0/lib/missing',
python: 'vendor0.deep.missing',
@ -2020,7 +2059,7 @@ const HEAP_PROBE_TARGET = {
// package-directory lookup and forces `PackageDirIndex`;
// - `dart` is an external package, so BOTH candidate paths miss and both
// walk the basename bucket to completion;
// - `kotlin` misses in `suffixByStem`, the map its four-tier cascade builds;
// - `kotlin` misses after building its declared-package/module-binding index;
// - `cobol` misses in both tier maps, `swift` in `byModule`, and `rust`
// probes candidate paths and builds nothing — that last is the reading
// the exclusion rests on;
@ -2074,11 +2113,24 @@ function measureHeap(lang) {
GC();
GC();
const probe = HEAP_PROBE_TARGET[lang];
const read = (files) => retainedPassBytes(lang, files, probe);
const read = (files) => retainedPassBytes(lang, files, probe, lang === 'php' ? HEAP_PAD : 0);
const small = flatten(buildFiles(lang, HEAP_SMALL, HEAP_PAD, 'unique'));
const bytesSmall = read(small);
const large = flatten(buildFiles(lang, HEAP_LARGE, HEAP_PAD, 'unique'));
const bytesLarge = read(large);
const phpGateShape =
lang === 'php'
? (() => {
const externalProbe = 'Vendor0\\Ghost\\Missing';
const config = phpComposerConfigFor(HEAP_PAD);
const pass = newPass(lang, large, HEAP_PAD);
return {
resolution_config: renderPhpComposerConfig(config),
external_probe: externalProbe,
external_result: renderResolved(resolveOne(lang, large[0], externalProbe, pass)),
};
})()
: {};
return {
files_small: HEAP_SMALL,
files_large: HEAP_LARGE,
@ -2088,6 +2140,7 @@ function measureHeap(lang) {
bytes_large: bytesLarge,
mib_large: Number((bytesLarge / 1024 / 1024).toFixed(2)),
ratio: Number((bytesLarge / bytesSmall / (HEAP_LARGE / HEAP_SMALL)).toFixed(3)),
...phpGateShape,
};
}
@ -2097,12 +2150,13 @@ function measureHeap(lang) {
* five-argument call and the three-argument one this harness used to make.
*
* That difference is the whole arm. PHP and Python need it because their main
* corpus answers agree with the fallback. Java's main fingerprint also catches
* a dropped context, but this tiny positive probe isolates the adapter contract
* from aggregate corpus changes. Timing cannot prove any of these; a dropped
* context makes the arms faster, and nothing here has a lower bound on ms.
* corpus answers agree with the fallback. Java and Kotlin deliberately return
* null without declared-package context; this tiny positive probe isolates the
* adapter contract from aggregate corpus changes. Timing cannot prove any of
* these; a dropped context makes the arms faster, and nothing here has a lower
* bound on ms.
*
* Both are resolved THROUGH `resolveOne`, not through the resolvers directly,
* All probes are resolved THROUGH `resolveOne`, not through the resolvers directly,
* because what is under test is this file's threading rather than the
* resolvers' behaviour. The control differs in exactly one thing:
* `pass.parsedFiles` is undefined, which `contextFor` turns into no fifth
@ -2137,6 +2191,15 @@ const CONTEXT_PROBE = {
javaProbeFile('weird/path/User.java', 'com.example.model'),
],
},
/** A Kotlin export resolves from its package fact and module binding only. */
kotlin: {
from: 'app/Main.kt',
target: 'com.example.model.User',
parsedFiles: [
kotlinProbeFile('app/Main.kt', 'app', 'main'),
kotlinProbeFile('weird/path/UserSource.kt', 'com.example.model', 'User'),
],
},
/**
* `from pkg import X`, with `pkg/__init__.py` exporting `X` AND a same-named
* submodule `pkg/X.py` beside it — the precedence CPython documents and the
@ -2170,10 +2233,11 @@ const CONTEXT_PROBE = {
function measureContext(lang) {
const { from, target, parsedFiles } = CONTEXT_PROBE[lang];
const allFilePaths = new Set(parsedFiles.map((f) => f.filePath));
const config = lang === 'php' ? phpComposerConfigFor(0) : undefined;
const answer = (files) => {
restoreBenchmarkSideChannels(lang, files ?? []);
return renderResolved(
resolveOne(lang, from, target, { allFilePaths, config: undefined, parsedFiles: files }),
resolveOne(lang, from, target, { allFilePaths, config, parsedFiles: files }),
);
};
return {
@ -2206,11 +2270,11 @@ if (CHECK && GC === null) {
/**
* Every arm, and the registered language each one exercises.
*
* This used to be a hand-written list of seventeen strings under a comment
* This used to be a hand-written list of language strings under a comment
* claiming it was "every language in `SCOPE_RESOLVERS`" — a claim nothing in
* the file could check, because the file never imported the registry. Adding a
* resolver to `pipeline/registry.ts` is two lines, neither of which is this
* one, so a seventeenth registered language would have shipped ungated and
* one, so a newly registered language would have shipped ungated and
* printed PASS. That is not a hypothetical failure mode: JavaScript reached
* `suffixResolve` with no index at all and measured 25 972 µs per import at
* 8000 files (PR #2911) for exactly as long as nothing gated it.
@ -2222,10 +2286,9 @@ if (CHECK && GC === null) {
* uses ten files away, and the same "one row per language" table
* `bench/cfg/measure.mjs` keeps.
*
* The mapping is many-to-one on purpose: `csharp` and `csharp_csproj` are two
* arms over one registered resolver, differing only in whether `csharpConfigs`
* is supplied, because the no-csproj arm returns before it can reach the leg
* #2902 indexed.
* The mapping is many-to-one only for C#: the configured arm reaches the
* csproj branch that the default arm cannot observe. PHP's sole arm carries
* its production Composer configuration directly.
*/
const LANG_REGISTRY = {
go: SupportedLanguages.Go,
@ -2311,8 +2374,9 @@ for (const lang of LANGS) {
scaling_ratio: Number((scales.large.ms / scales.small.ms / (LARGE / SMALL)).toFixed(3)),
// `scaling_ratio` divides the file count out, so it is scale-invariant and
// structurally cannot see a cost that grows with path DEPTH instead — and
// `buildSuffixIndex` (C#, Ruby, PHP, Java, and the whole ts family) and
// Kotlin's `suffixByStem` all emit one entry per '/' in a path, and
// `buildSuffixIndex` (C#, Ruby, PHP, Java, and the whole ts family) emits
// one entry per '/' in a path, while Kotlin's declared-package index is
// depth-free, and
// Python's ancestor walk rebuilds one prefix per component PER IMPORT.
// Same file count, ~6x the components.
depth_ratio: Number((scales.deep.ms / scales.small.ms).toFixed(3)),
@ -2413,7 +2477,7 @@ const SCALE_SHAPE = {
'one of them alone moves nothing in the others.',
};
/** The same, for the heap arm — the four inputs that decide what it measures.
* Asserted for all seventeen, budgeted tier and bounded tier alike, and it is
* Asserted for all seventeen arms, budgeted tier and bounded tier alike, and it is
* the bounded tier that needs it most: a bound is a single comparison, so a
* probe swapped for one that reaches less is a bound over a smaller workload
* and there is no floor beside it to notice.
@ -2430,6 +2494,13 @@ const HEAP_SHAPE = {
'ceiling, floor, bound and ratio passing over an arm that changed workload. Deterministic: ' +
'a re-run will not change it.',
};
const PHP_HEAP_SHAPE = {
fields: [...HEAP_SHAPE.fields, 'resolution_config', 'external_probe', 'external_result'],
why:
HEAP_SHAPE.why +
' PHP also pins the Composer mapping and a suffix-matchable external decoy so the mapped ' +
'index path and the external fast gate remain separate observable arms.',
};
/** The same, for the `context` arm. All three fields are exact strings, not
* bounds: this arm has no measurement noise at all — it resolves one import
* two ways over a three-file corpus — so anything less than equality would be
@ -2452,7 +2523,7 @@ const CONTEXT_SHAPE = {
* a fifth parameter. */
const armShapes = (lang) => [
...SCALES.map((scale) => [scale, SCALE_SHAPE]),
['heap', HEAP_SHAPE],
['heap', lang === 'php' ? PHP_HEAP_SHAPE : HEAP_SHAPE],
...(CONTEXT_LANGS.includes(lang) ? [['context', CONTEXT_SHAPE]] : []),
];
@ -2886,8 +2957,8 @@ expectNoOrphanKeys(
// against a claim in a comment. `run.ts` passes the fifth argument to every
// provider; which ones can OBSERVE it is decided by how many parameters each
// hook declares, and that is a number the registry can be asked for. Today
// exactly three answer 5 (php, java, python) and the other fourteen answer 3 or 4 —
// which is why fourteen arms could ignore this whole question and their numbers
// exactly four answer 5 (php, java, kotlin, python) and the other thirteen answer 3 or 4 —
// which is why thirteen arms can ignore this whole question and their numbers
// did not move when it was fixed.
//
// `Function.length` stops at the first defaulted or rest parameter, so a hook

View file

@ -1,15 +1,9 @@
{
"_comment": "Baselines for bench/kotlin-import-target/measure.mjs --check. `fingerprint` is a sha256 over every `fileSet | fromFile | targetRaw -> result` record the correctness corpus resolves, in BOTH file-set iteration orders; it is a CORRECTNESS gate, so drift means Kotlin import resolution started returning a different file set and IMPORTS/CALLS edges moved in every Kotlin repository. Explain it, never re-baseline to make CI green. `cases` and `non_null` are asserted beside it because a shrunken or hollowed corpus produces a perfectly valid fingerprint over a smaller surface — all three are one re-baseline, never separate ones. `scaling_budget`, `depth_budget` and `small_ms_ceiling` are timing gates and carry deliberate headroom for shared CI runners.",
"_provenance": "RE-BASELINED ONCE, DELIBERATELY, IN #2881. The previous value ebf1790bf1d42dad483a51f2cbdeb2351e493b9e8236e4eedeef592dd81e2c5c (13256 non-null) was the PRE-INDEX implementation's, and the index that replaced it in #2872 reproduced it byte for byte — that is what made #2872 a performance change. #2881 changes resolution on purpose: `getKotlinFileIndex` no longer requires the parent directory to be the FIRST occurrence of that name in the path, so a file whose package directory name repeats higher in its own path is now a child of that package (`data/src/main/kotlin/com/example/data/Repo.kt` IS a child of `data`, and `import data.helper` resolves instead of returning null). The drift was not read off the new code and accepted; the corpus was dumped from both implementations and diffed record by record. That census was RE-RUN with a shape classifier after review found its taxonomy — 54 NULL -> resolved, 149 reselections, 32 wider fan-outs — was entirely SHAPE-PRESERVING and so had no bucket for a class this change introduces. Both ends of the re-run are validated against numbers this file already publishes, so the census is provably over the surface they describe: driven over this bench's own corpus, the BASE resolver reproduces ebf1790bf1… at 13256 non_null and the HEAD resolver reproduces d91110bee3… at 13310, across 20106 records of which 19968 are distinct. 235 distinct records moved, classified by SHAPE rather than by null-ness: null -> string 38 and null -> array 16, which together are the first census's '54 NULL -> resolved' and exactly the +54 in non_null; string -> string (a different member of a now-wider bucket) 149; array -> array (the fan-out grew) 32; string -> array 0; and ZERO of every other transition — nothing went string -> null, array -> null or array -> string, and no array shrank or reordered. So the old three buckets reappear inside the shape taxonomy exactly, and its two structural claims hold when checked directly instead of inferred: all 32 growths are order-preserving SUPERSETS of the base answer, no record lost a member, and in all 149 reselections the new answer's parent directory is named by a segment of the import and carries the same directory NAME the base answer's parent did. WHAT THE OLD TAXONOMY HAD NO BUCKET FOR is `string -> array`, and it is the one class here that is not shape-preserving: it is a RESOLVED -> UNRESOLVED transition. Tier 3 (`findKotlinPackageFiles`) runs before tier 4 (`findByProgressivePrefixStrip`), so a bucket the removed guards left empty returned null and let tier 4 answer with a single BOUND file; a now-populated bucket stops tier 4 running at all and hands back a fan-out array that need not contain the imported name at all. Two files reproduce it, in both iteration orders: ['data/src/main/kotlin/com/example/data/Repo.kt', 'common/helper.kt'] with `import data.helper` answers 'common/helper.kt' at base and ['data/src/main/kotlin/com/example/data/Repo.kt'] at head. ITS COUNT OVER THIS CORPUS IS 0, AND THAT IS A FACT ABOUT THE CORPUS RATHER THAN ABOUT THE CLASS. This file's own fuzz generator, run at ten times the repositories (4000, ~198600 distinct records), hits the class 12, 4, 10 and 10 times over four seeds — ~5e-5 per record, an expectation of about ONE over the 19968 records here — so 0 is this corpus being an order of magnitude too small to reach it, not the shape being unreachable. The consequence is worth stating plainly: the fingerprint below is blind to a resolved -> unresolved class this change introduces, by corpus SIZE and not by construction, and no arm in this bench gates it today. Adding a hand-written case for it is a deliberate fingerprint move and a fourth re-baseline of this file; it is worth doing and it is not this change. The corpus itself is untouched, which is why `cases` is unchanged at 20106 — the fingerprint is over the same surface as the value it replaces.",
"_gate_controls": "The gate is only worth its baseline if a plausible regression moves it, so each arm was checked against the mutation it exists to catch, with the resolver otherwise untouched. All values below are against the CURRENT baseline (#2881, guards removed + per-directory key memo + bucket compaction). Caught: skipping the dirChildren component walk above depth 8 (fingerprint 41bb550b76d4…, non_null 13310 -> 12800); capping a dirChildren bucket at 17 entries (a7681945b752…, non_null UNCHANGED — the fingerprint is the only arm that sees it, and note the compaction pass now rewrites those same buckets, so this control was re-run after it); capping suffixByStem key depth at 7 (d24b8a2bd822…, non_null unchanged); and a HALF fix that drops only the `startsWith` guard while keeping the `indexOf` first-occurrence check (836977b83bf0…, non_null 13310 -> 13282), which leaves every mid-path repeat such as `top/data/mid/data/Repo.kt` broken and is the mutation #2881 itself makes plausible. Added with the memo: keying `dirKeys` on the directory's LAST SEGMENT instead of its full path (36a4e9dad313…, non_null 13310 -> 13305) — the memo's whole safety argument is that its key determines the key SET a directory contributes, so a coarser key silently hands one directory another's bucket list, and that is the one way this optimization can move an answer. Also caught, with the RESOLVER untouched and only the corpus edited: dropping the competing file from the exact-beats-earlier-suffix case and emptying the repeated-directory case (44df5093ee…). All of these passed silently before this corpus carried deep paths, packages above 16 files, queries against suffix keys deeper than 7, and the file set inside the hashed record. Re-check them after any corpus edit — a corpus that stops spanning an axis takes the gate with it. NOTE what no fingerprint control here can catch: the memo and the compaction are both invisible to this bench by design (identical output), so no arm in this file gates either one, and the honest version of where they ARE gated is narrower than a claim about comparing the three maps would suggest. The memo's gate is test/unit/scope-resolution/kotlin/kotlin-index-internals.test.ts, which drives the resolver's OBSERVABLE SURFACE rather than the built index — the index is module-private — and reconstructs what it needs from the tiers. It pins: bucket CONTENTS and ORDER, read back from the fan-out tier, which hands out the bucket array itself; that the first-child tier reads position 0 of that SAME array; bucket IDENTITY across two calls on one Set, which is what proves the memo's hit path ran at all, since only a second file in the same directory reaches it; the frozen state of the array actually handed out, on the multi-child path, on the `length === 1` skip path, and once per key of a multi-key directory; that the memo keys on the NORMALIZED directory while storing the raw path; and the one mutation that can move an answer — keying `dirKeys` on the directory's last segment instead of the whole `dir` — which fails three of its arms. KEY INSERTION ORDER is unasserted there BY DESIGN and not by omission: `dirChildren` is only ever read by `.get(key)`, so key order has no consumer, and that file says so. The COMPACTION is unasserted there too and cannot be asserted there at all — a JS array's backing-store capacity has no reflective surface, so deleting `bucket.slice()` and freezing the grown bucket in place leaves every arm in that file green, `Object.isFrozen` included. Its only instrument is the retained-heap arm in bench/import-target, whose kotlin ceiling was tightened to 1.0747x its recorded reading precisely so that the +12.57% the slice reclaims fails `--check`; see `_heap_compaction_gate` in bench/import-target/baselines.json for the measurement and for how to tell that failure apart from a runner's heapUsed accounting moving under the whole file.",
"fingerprint": "d91110bee389891c313811c5b4bae61d909561156e1458d38d487be969f0059c",
"cases": 20106,
"non_null": 13310,
"_comment": "Declared-package Kotlin import benchmark. The fingerprint pins external-decoy rejection, path/package disagreement, top-level declarations and overload sets, member and wildcard imports, root packages, malformed package facts, and imported-binding exclusion. Timing budgets guard one parsed-workspace index build per pass.",
"fingerprint": "76ee74bf860c54ef6dc0850f6bec2d0f7267ba3010f552ee89b84dfdbbecd0e2",
"cases": 24,
"non_null": 16,
"scaling_budget": 1.6,
"depth_budget": 2.0,
"small_ms_ceiling": 40,
"_scaling_note": "(t_large/t_small)/(1600/400). ~1.0 is linear. OBSERVED BAND: 0.99-1.04 on a 12-core dev box, small arm ~6 ms. Read that band as a floor, not a spec — independent runs on other hardware during review came out 0.954-1.014, 0.965-1.036 and ~0.95-1.08, so a 1.2 reading is noise and should be re-run, not investigated. IMPORTS_PER_FILE is sized so the small arm lands in the ms rather than the ~2 ms a first revision measured, where timer granularity and JIT warm-up, not scaling, set the number; bench/cpp-qualified-ns documents the same artifact. TRIAGE: every timing arm here is a TIMING signal — RE-RUN IT on an idle machine before investigating; runner contention dominates. The fingerprint arm is the opposite: deterministic, a re-run never changes it, and it must never be wished away. FLOOR CHECK: the pre-index implementation — i.e. exactly the regression this gate exists to catch — measures ratio 3.737 on this corpus (2207.8 ms small, 33003.5 ms large, one cold run) against ~1.0 for the index. Independent review runs measured its floor at 3.905-4.297. Treat the absolute times as an order of magnitude only: the floor arm is one cold run because best-of-seven against a quadratic implementation costs minutes, while the index arm is best-of-seven after two warmups.",
"_depth_note": "deep_ms/shallow_ms at a FIXED file count, paths 24 components against 8. scaling_ratio divides the file count out, so it is scale-invariant and structurally cannot see a cost that grows with path depth instead — and the two loops the index is built from are depth loops (one suffixByStem entry per '/' in a stem, one dirChildren pass per component of dir). OBSERVED BAND, five runs each on one box: 1.44-1.51 before #2881; 1.27-1.40 after its guard removal, which deleted two string comparisons per component of every dir; 1.20-1.26 after the same issue's per-directory key memo, which turns that whole component walk from once-per-FILE into once-per-DIRECTORY. Both movements are per-depth work, which is why this arm sees them and the file-count arm does not. The BUDGET moved with the band both times — 2.4 -> 2.2 -> 2.0 — holding the ~1.6x headroom over the band's top that 2.4 expressed against the original; left at 2.4 it would quietly have become 1.9x, which is how a gate goes slack without anyone deciding to loosen it. Note what this budget is NOT for: a revert of #2881 scores ~1.5 and passes at any of those numbers, and that is correct — reverting it restores a resolution bug, which is the FINGERPRINT's job to catch, not a timing arm's. It sits above 1.0 legitimately: 3x the depth is 3x the suffix keys per file, so the build genuinely does more work; what the budget forbids is that growing faster than the depth ratio itself.",
"_ceiling_note": "small_ms_ceiling is an ABSOLUTE bound, because scaling_ratio is a ratio and a constant-factor regression that grows both arms equally passes it. Measured during review: a full workspace scan reintroduced on 1-in-16 imports is caught by the ratio (1.814), but at 1-in-32 it passes at 1.490 while running 2.8x slower in absolute terms. 40 ms against an observed 5.9-6.1 ms leaves ~6x of headroom for a loaded shared runner while still catching that shape.",
"_blind_spot": "WHAT THIS BENCH CANNOT SEE, measured rather than guessed. Its scaling corpus gives every module a UNIQUE package leaf (`com/example/mod{N}`), so a `dirChildren` query matches exactly one directory. That makes it blind to any cost that grows with the number of DIRECTORIES sharing a queried segment — the shape a real Kotlin monorepo has, where 200 modules each hold `data`, `ui` and `domain`. Established by building the reuse this file's memo argues against: swapping `dirChildren` for the shared `import-resolvers/package-dir-index.ts` (with its first-occurrence rule off) is OUTPUT-IDENTICAL — same fingerprint, same cases, same non_null, 0 divergences over 107948 answers — and on THIS corpus it costs only 1.37x-1.50x and passes every arm here. On a repeated-leaf corpus the same swap measures 13.5x per first-child query, 409x per fan-out, and 8114x on `import data.*` at 200 matching directories (it merges and SORTS every candidate, per import), for 3.1x-5.7x end to end and a bench-style scaling_ratio of 3.465 against this file's 1.6 budget — i.e. back to the pre-index quadratic floor of 3.737. A change that regresses this resolver to the very shape the bench exists to catch would go GREEN here. The trade it buys is real and also measured: 26.2% less retained memory, 12.18 MiB at 32000 files. If that memory is ever wanted, the shape to build is per-suffix keys -> DIRECTORY lists plus files-per-directory (8.29 MiB against 15.87 measured, single-directory query still one hash lookup) — and the repeated-leaf arm to measure it against already exists one directory over: bench/import-target's kotlin `collide` layout puts `com/example/models` under 200 modules at the 1600-file scale, with `collide_scaling_budget` 1.8 against a measured 1.081. The swap scores 3.465 there. So the gate for this decision is that arm, not a new one here; what this file lacks is only a repeated-leaf arm of its own, which would be duplicated coverage."
"depth_budget": 1.5,
"small_ms_ceiling": 40
}

View file

@ -1,537 +1,239 @@
/**
* Build-free identity + scaling bench for `resolveKotlinImportTarget`, the
* Kotlin import resolver.
* Declared-package correctness and scaling gate for Kotlin import resolution.
*
* Before this bench's companion change the resolver walked the ENTIRE
* `allFilePaths` Set on every import. Its four tiers — exact/suffix,
* directory child, package fan-out, progressive prefix strip — each ran
* `for (const raw of allFilePaths)` with a `replace(/\\/g, '/')` and several
* string comparisons per entry, and they are tried in cascade, so one
* unresolved import cost two to four full passes. Resolution was therefore
* O(imports x files). Once a repository reaches tens of thousands of Kotlin
* files that is on the order of 10^10 string operations on one thread:
* `analyze` sits at exactly 1.00 core with a flat heap and emits nothing for
* hours, because every allocation is a short-lived string and nothing
* accumulates to hint at progress.
*
* This is the same shape #1918 fixed for Python and #2788 for C++, and it
* returns the same way: someone adds a tier, reaches for `allFilePaths`, and
* writes a loop. Neither existing gate can catch it here —
* `bench/python-scope/import-target-fingerprint.mjs` drives the Python
* resolver only, and `bench/scope-capture/measure.mjs` fingerprints
* `emit<Lang>ScopeCaptures`, a different function that never calls import
* resolution. Hence this bench, in an always-on CI step.
*
* TWO ARMS, and they fail for opposite reasons:
*
* - `fingerprint` — a sha256 over every `fromFile | targetRaw -> result`
* triple the correctness corpus resolves (an exhaustive branch matrix plus
* a deterministic fuzz). This is a CORRECTNESS gate. Drift means Kotlin
* imports started resolving a DIFFERENT file set, i.e. CALLS/IMPORTS edges
* moved in every Kotlin repository. It is deterministic: a re-run never
* changes it, and it must never be re-baselined to make CI green. This
* value is the one the pre-index implementation produced — see
* `_provenance` in baselines.json.
*
* - `scaling_ratio` — `(t_large/t_small)/(LARGE/SMALL)` over a synthetic
* Kotlin monorepo at two scales, timing the index build TOGETHER with
* resolving every import. ~1.0 is linear; a reintroduced per-import scan
* measures ~4 at this scale gap. This is a TIMING gate: re-run it on an
* idle machine before investigating.
*
* A ratio cannot see a constant factor and a file-count ratio cannot see a
* depth cost, so `--check` also asserts a DEPTH ratio (file count fixed, paths
* ~3x deeper) and an absolute ceiling on the small arm. A full workspace scan
* reintroduced on 1-in-32 imports scores 1.490 — inside the scaling budget —
* while running 2.8x slower; the ceiling is what catches that shape.
*
* One honest limit: at a very small import count the index loses. Building it
* is one workspace pass, so a single import into a 100k-file workspace costs
* ~0.8 s against ~0 for a scan that returns on its first hit. It inverts at
* roughly 15 imports, and in the polyglot case that motivates the worry —
* 100k files, 5% Kotlin, a couple of imports — the index already wins, because
* the build skips non-`.kt` entries as cheaply as the scan did.
*
* Five properties of the corpora are load-bearing and must not be
* "simplified" away:
*
* 1. **The correctness corpus fuzzes each file set in BOTH iteration
* orders.** Every tie-break in this resolver is expressed only through
* Set-iteration order — "first suffix match wins", and the two stem maps
* keeping the FIRST path inserted per key. A single-order corpus scores an
* implementation that keeps the LAST match identically.
* 2. **The correctness corpus contains repeated directory names at BOTH the
* leading and the mid-path position** (`data/src/main/kotlin/com/example/
* data/Repo.kt` and `top/data/mid/data/Repo.kt`). Until #2881 the resolver
* required a file's package directory to be the FIRST occurrence of that
* name in its own path, so neither file was a child of `data`; both are
* now, and that is what the fingerprint pins. Two positions, not one,
* because the old rule was two guards and a half fix that drops only the
* leading-position one still leaves the mid-path shape broken — see
* `_gate_controls` in baselines.json. Without these shapes the fingerprint
* cannot tell the current rule from either predecessor.
* 3. **~40% of the scaling corpus's imports are unresolvable.** The old cost
* was worst when nothing matched, because only then did all four tiers
* run. A corpus where every import hits tier 1 exits after one pass and
* scores a per-import scan far closer to linear.
* 4. **The hashed record includes the FILE SET, not just the query and the
* result.** Otherwise a corpus edit that swaps the workspace under a case
* while leaving its result string alone is invisible: dropping the
* competing file from the "exact beats an earlier suffix" case, or
* emptying the repeated-directory negative case, each leaves `cases`,
* `non_null` and the fingerprint byte-identical and the gate green.
* 5. **Path depth and package size are spanned, not pinned.** Both loops this
* change added are driven by depth — one `suffixByStem` entry per '/' in a
* stem, one `dirChildren` pass per component of `dir` — and the fan-out
* tier returns a bucket whose length is the package size. While the corpus
* capped depth at 8 components and packages at 16 files, three plausible
* follow-up guards (cap suffix depth at 7, skip the `dirChildren` suffix
* loop above depth 8, cap a bucket at 17) all passed `--check` with a
* byte-identical fingerprint — while on a standard Gradle layout the depth
* skip resolved EVERY package import to null and the bucket cap truncated
* fan-out by 58%. Import ARITY, by contrast, was never blind: a tier-4 cap
* at 4 dotted segments already failed the gate, because the branch matrix
* carries 6- and 8-segment cases.
* The production resolver indexes the parsed workspace once per pass. This
* benchmark pins the semantic cases path matching cannot express and verifies
* that work remains linear as files and imports grow together.
*
* Run:
* node --import tsx bench/kotlin-import-target/measure.mjs # report
* node --import tsx bench/kotlin-import-target/measure.mjs --check # CI gate
* node --import tsx bench/kotlin-import-target/measure.mjs
* node --import tsx bench/kotlin-import-target/measure.mjs --check
*/
import crypto from 'node:crypto';
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { resolveKotlinImportTarget } from '../../src/core/ingestion/languages/kotlin/import-target.ts';
import { kotlinScopeResolver } from '../../src/core/ingestion/languages/kotlin/scope-resolver.ts';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const BASELINE_PATH = path.resolve(__dirname, 'baselines.json');
const baseline = JSON.parse(fs.readFileSync(path.join(__dirname, 'baselines.json'), 'utf8'));
const CHECK = process.argv.includes('--check');
const SMALL = 400;
const LARGE = 1600;
/** Imports per file. Keeps the import count proportional to the file count, so
* a per-import workspace scan shows up as a quadratic ratio rather than being
* amortized away by a fixed import budget. Sized so the SMALL arm measures in
* the tens of ms: at ~2 ms timer granularity and JIT warm-up, not scaling, set
* the ratio — the same artifact bench/cpp-qualified-ns documents. */
const IMPORTS_PER_FILE = 32;
/** Depth arm: same file count either side, ~3x the path depth on one side. */
const DEPTH_FILES = 800;
const DEPTH_PAD = 16;
const IMPORTS_PER_FILE = 4;
const WARMUP = 2;
const REPS = 7;
// ---------------------------------------------------------------------------
// Correctness arm
// ---------------------------------------------------------------------------
function parsedFile(filePath, packageName, exports, imported = []) {
const moduleScope = `module:${filePath}`;
const localDefs = exports.map((name, i) => ({
nodeId: `Declaration:${filePath}:${i}`,
filePath,
type: i === 0 ? 'Class' : 'Function',
qualifiedName: name,
}));
const bindings = new Map(localDefs.map((def) => [def.qualifiedName, [{ def, origin: 'local' }]]));
for (const name of imported) {
bindings.set(name, [
{
def: {
nodeId: `Declaration:dependency.kt:${name}`,
filePath: 'dependency.kt',
type: 'Class',
qualifiedName: name,
},
origin: 'import',
},
]);
}
return {
filePath,
moduleScope,
scopes: [
{
id: moduleScope,
parent: null,
kind: 'Module',
range: { startLine: 1, startCol: 0, endLine: 1, endCol: 1 },
filePath,
bindings,
ownedDefs: localDefs,
imports: [],
typeBindings: new Map(),
},
],
parsedImports: [],
localDefs,
referenceSites: [],
captureSideChannel: {
kind: 'kotlin',
companionScopes: [],
packageFact: packageName === null ? { status: 'unknown' } : { status: 'known', packageName },
classAnnotations: [],
},
};
}
const lines = [];
let nonNull = 0;
function prepare(parsedFiles) {
kotlinScopeResolver.loadResolutionConfig?.('');
for (const parsed of parsedFiles) kotlinScopeResolver.applyCaptureSideChannel?.(parsed);
return {
parsedFiles,
allFilePaths: new Set(parsedFiles.map((file) => file.filePath)),
};
}
function resolve(files, targetRaw, fromFile) {
return resolveKotlinImportTarget(
{ kind: 'named', localName: 'X', importedName: 'X', targetRaw },
{ fromFile, allFilePaths: new Set(files) },
function resolve(targetRaw, pass) {
return kotlinScopeResolver.resolveImportTarget(
targetRaw,
pass.parsedFiles[0]?.filePath ?? 'app/Main.kt',
pass.allFilePaths,
undefined,
{
parsedFiles: pass.parsedFiles,
parsedImport: { kind: 'named', localName: 'X', importedName: 'X', targetRaw },
filesSkipped: 0,
},
);
}
/** Record one case in BOTH file-set iteration orders — see header property 1. */
function record(files, targetRaw, fromFile = 'App.kt') {
for (const [order, list] of [
['fwd', files],
['rev', [...files].reverse()],
]) {
const r = resolve(list, targetRaw, fromFile);
if (r !== null) nonNull++;
const rendered = r === null ? 'NULL' : Array.isArray(r) ? `[${r.join(',')}]` : r;
// The FILE SET is part of the hashed record, not just the query and the
// result — see header property 4.
lines.push(`${order}\t${list.join('|')}\t${fromFile}\t${targetRaw}\t${rendered}`);
function render(answer) {
if (answer === null) return 'null';
return typeof answer === 'string' ? answer : JSON.stringify(answer);
}
const correctness = [
[
[
parsedFile('app/Main.kt', 'app', ['main']),
parsedFile('src/main/kotlin/vendor/Assert.kt', 'vendor', ['Assert']),
],
['org.junit.Assert', 'vendor.Assert'],
],
[
[
parsedFile('flat/UserSource.kt', 'com.example.model', ['User', 'loadUser']),
parsedFile('other/Order.kt', 'com.example.model', ['Order']),
parsedFile('odd/ToolsFile.kt', 'com.example', ['Tools']),
],
[
'com.example.model.User',
'com.example.model.loadUser',
'com.example.model.*',
'com.example.Tools.format',
'com.example.Tools.*',
'com.example.model.Missing',
],
],
[
[
parsedFile('one.kt', 'dup', ['parse']),
parsedFile('two.kt', 'dup', ['parse']),
parsedFile('Root.kt', '', ['Root']),
parsedFile('Broken.kt', null, ['Broken']),
parsedFile('app.kt', 'app', ['main'], ['External']),
],
['dup.parse', 'Root', 'broken.Broken', 'app.External'],
],
];
const records = [];
let nonNull = 0;
for (const [files, targets] of correctness) {
for (const ordered of [files, [...files].reverse()]) {
const pass = prepare(ordered);
for (const target of targets) {
const answer = render(resolve(target, pass));
if (answer !== 'null') nonNull++;
records.push(`${ordered.map((file) => file.filePath).join(',')}|${target}->${answer}`);
}
}
}
const fingerprint = crypto.createHash('sha256').update(records.sort().join('\n')).digest('hex');
// ---- 1. Exhaustive branch matrix ------------------------------------------
// Tier 1, exact.
record(['util/User.kt', 'util/Repo.kt'], 'util.User');
// Tier 1, suffix (import is not workspace-rooted).
record(['src/main/kotlin/util/User.kt'], 'util.User');
// Exact anywhere beats a suffix found earlier.
record(['deep/util/User.kt', 'util/User.kt'], 'util.User');
// No exact match: first suffix in iteration order wins.
record(['a/util/User.kt', 'b/util/User.kt'], 'util.User');
// .kt / .kts sharing a stem.
record(['dup/Thing.kt', 'dup/Thing.kts'], 'dup.Thing');
// Multi-segment suffix query.
record(['src/main/com/example/User.kt'], 'com.example.User');
record(['a/b/com/example/User.kt', 'com/example/User.kt'], 'com.example.User');
// Tier 2: stripped path matches a file (class-or-object holding the member).
record(['util/OneArg.kt'], 'util.OneArg.writeAudit');
record(['src/main/kotlin/util/OneArg.kt'], 'util.OneArg.writeAudit');
// Tier 3: package fan-out to every direct child, in order.
record(['models/User.kt', 'models/Repo.kt', 'models/sub/Deep.kt'], 'models.getRepo');
record(['models/User.kt', 'models/sub/Deep.kt', 'models/Repo.kt'], 'models.getRepo');
// Fan-out where the package directory is reached by suffix, not at the root.
record(['app/src/main/kotlin/models/User.kt', 'app/src/main/kotlin/models/Repo.kt'], 'models.get');
// Tier 4: progressive prefix strip, one and several skip levels.
record(['x/y/z/Deep.kt'], 'com.example.z.Deep');
record(['z/Deep.kt'], 'a.b.c.d.z.Deep');
record(['q/Deep.kt'], 'a.b.c.d.e.f.q.Deep');
// Tier 4 reaching the fan-out tier after stripping.
record(['pkg/A.kt', 'pkg/B.kt'], 'com.example.pkg.someFunction');
// Backslash normalization.
record(['win\\pkg\\A.kt'], 'win.pkg.A');
record(['win\\pkg\\A.kt', 'win\\pkg\\B.kt'], 'win.pkg.someFunction');
// Non-Kotlin files never resolve.
record(['pkg/A.java', 'pkg/A.md', 'pkg/A.kt.txt'], 'pkg.A');
// Kotlin file alongside non-Kotlin noise of the same stem.
record(['pkg/A.java', 'pkg/A.kt'], 'pkg.A');
// Header property 2: repeated directory name — a child of the repeated package
// since #2881, at the leading position here and mid-path below.
record(['data/src/main/kotlin/com/example/data/Repo.kt'], 'data.something');
record(['data/src/main/kotlin/com/example/data/Repo.kt'], 'data.Repo');
record(['a/c/b/c/File.kt'], 'c.X');
record(['c/b/c/File.kt'], 'c.X');
// Doubly nested same-name directory, both below the root.
record(['top/data/mid/data/Repo.kt'], 'data.something');
// A path starting with the directory name is not its child unless direct.
record(['data/sub/Repo.kt'], 'data.something');
record(['data/Repo.kt'], 'data.something');
// Repo-root file has no package directory.
record(['Root.kt'], 'Root');
record(['Root.kt', 'pkg/Root.kt'], 'Root');
// Wildcard: `.*` is stripped and lands on the single-file tier, not fan-out.
record(['models/User.kt', 'models/Repo.kt'], 'models.*');
record(['models/Repo.kt', 'models/User.kt'], 'models.*');
record(['util/User.kt'], 'util.User.*');
// Unknown target.
record(['pkg/A.kt'], 'nowhere.Thing');
// Single-segment target with no directory anywhere.
record(['pkg/A.kt'], 'A');
// Empty-ish and degenerate targets.
record(['pkg/A.kt'], '*');
record(['pkg/A.kt'], 'pkg.');
// fromFile variation must not change the outcome (this resolver ignores it) —
// pinned so a future change that starts consulting it is visible here.
record(['util/User.kt'], 'util.User', 'deep/nested/Caller.kt');
// ---- 1b. Depth and package size, the two axes the loops scale on ----------
//
// Header property 5. The index writes one `suffixByStem` entry per '/' in a
// stem and walks `dir` once per component, so DEPTH is what those two loops
// cost, and `dirChildren` bucket length is what the fan-out tier returns. A
// corpus that pins either as a constant cannot see a guard on it: capping
// suffix-key depth at 7, skipping the `dirChildren` suffix loop above depth 8,
// or capping a bucket at 17 entries all left the fingerprint, `cases` and
// `non_null` byte-identical before these cases existed — while, on a standard
// Gradle layout, the depth skip resolved EVERY package import to null and the
// bucket cap silently truncated fan-out by 58%.
const DEEP = 'core/data/src/main/kotlin/com/example/core/data/repository';
// 11 components — ordinary for Android/Gradle source, which runs 9-12.
record([`${DEEP}/UserRepository.kt`], 'com.example.core.data.repository.UserRepository');
record([`${DEEP}/UserRepository.kt`], 'repository.UserRepository');
record([`${DEEP}/UserRepository.kt`], 'core.data.repository.UserRepository');
record([`${DEEP}/UserRepository.kt`, `${DEEP}/PostRepository.kt`], 'repository.findAll');
record([`${DEEP}/UserRepository.kt`, `${DEEP}/PostRepository.kt`], 'core.data.repository.findAll');
// Deeper still, and with the repeated-name shape at depth.
const DEEPER = 'feature/home/src/main/kotlin/com/example/feature/home/data/local/dao';
record([`${DEEPER}/UserDao.kt`], 'dao.UserDao');
record([`${DEEPER}/UserDao.kt`, `${DEEPER}/PostDao.kt`], 'dao.insertAll');
record([`${DEEPER}/UserDao.kt`], 'home.data.local.dao.UserDao');
// Suffix keys deeper than 7 components. Depth in the FILE is not enough on its
// own: a cap on how many component-suffixes a stem contributes stays invisible
// unless something QUERIES one of the deep keys, and every Gradle-shaped import
// above is 6 segments or fewer. These reach the top of the stem.
record(
[`${DEEP}/UserRepository.kt`],
'src.main.kotlin.com.example.core.data.repository.UserRepository',
);
record(
[`${DEEP}/UserRepository.kt`],
'data.src.main.kotlin.com.example.core.data.repository.UserRepository',
);
record([`${DEEPER}/UserDao.kt`], 'src.main.kotlin.com.example.feature.home.data.local.dao.UserDao');
record(
[`${DEEPER}/UserDao.kt`],
'home.src.main.kotlin.com.example.feature.home.data.local.dao.UserDao',
);
record(
[`${DEEP}/UserRepository.kt`, `${DEEP}/PostRepository.kt`],
'src.main.kotlin.com.example.core.data.repository.findAll',
);
// A package larger than any plausible bucket cap. 40 files in one package is
// ordinary; a silent sibling cap is exactly what #2732 shipped on the JVM side.
const BIG_PACKAGE = Array.from({ length: 40 }, (_, i) => `${DEEP}/Item${i}.kt`);
record(BIG_PACKAGE, 'repository.someTopLevelFun');
record(BIG_PACKAGE, 'com.example.core.data.repository.someTopLevelFun');
record([...BIG_PACKAGE, `${DEEP}/sub/Nested.kt`], 'repository.someTopLevelFun');
// ---- 2. Deterministic fuzz -------------------------------------------------
/** xorshift32 — seeded, so the corpus is identical on every machine. */
let seed = 0x9e3779b9;
function rnd() {
seed ^= seed << 13;
seed ^= seed >>> 17;
seed ^= seed << 5;
seed >>>= 0;
return seed / 0x100000000;
}
function pick(arr) {
return arr[Math.floor(rnd() * arr.length)];
}
const DIRS = [
'',
'app',
'core',
'data',
'feature/home',
'lib/data',
'src/main/kotlin',
'src/main/kotlin/com/example',
'module/src/main/kotlin/com/example/data',
'data/src/main/kotlin/com/example/data',
'top/data/mid/data',
'win\\pkg',
// Depth beyond the Gradle norm, so the fuzz spans the axis too rather than
// leaving it to the hand-written cases above.
'core/data/src/main/kotlin/com/example/core/data/repository',
'feature/home/src/main/kotlin/com/example/feature/home/data/local/dao',
'a/b/c/d/e/f/g/h/i/j/k/l',
];
// Segment alphabet overlaps the DIRS entries on purpose: a random dotted target
// only exercises a deep suffix key if its segments can actually align with a
// deep path.
const SEGS = [
'User',
'Repo',
'Util',
'Service',
'Model',
'data',
'core',
'api',
'store',
'sub',
'src',
'main',
'kotlin',
'com',
'example',
'repository',
'dao',
];
const EXTS = ['.kt', '.kt', '.kt', '.kts', '.java', '.md'];
function randPath() {
const dir = pick(DIRS);
const base = pick(SEGS);
const file = `${base}${pick(EXTS)}`;
if (dir === '') return file;
return dir.includes('\\') ? `${dir}\\${file}` : `${dir}/${file}`;
}
function randDotted() {
// Up to 9 segments, not 4: import arity is the one axis the branch matrix
// already spanned, but the fuzz should cover it too now that the corpus
// carries paths deep enough for a long target to align with one.
const n = 1 + Math.floor(rnd() * 9);
const parts = [];
for (let i = 0; i < n; i++) parts.push(pick(SEGS));
return rnd() < 0.12 ? `${parts.join('.')}.*` : parts.join('.');
}
// File counts run to 45, not 16: a package that never exceeds 16 direct
// children cannot distinguish an uncapped `dirChildren` bucket from one capped
// at 17 (header property 5).
for (let repo = 0; repo < 400; repo++) {
const fileCount = 3 + Math.floor(rnd() * 43);
const files = [];
for (let i = 0; i < fileCount; i++) files.push(randPath());
const fromFile = randPath();
for (let imp = 0; imp < 25; imp++) record(files, randDotted(), fromFile);
}
const correctnessFingerprint = crypto
.createHash('sha256')
.update([...lines].sort().join('\n'))
.digest('hex');
// ---------------------------------------------------------------------------
// Scaling arm
// ---------------------------------------------------------------------------
/** A synthetic Kotlin monorepo: Gradle-module roots over a shared package
* namespace, at the path depth real Kotlin source has (the index stores one
* suffix entry per '/' in a stem and walks `dir` once per component, so depth
* is a cost driver and a flat corpus would understate the build).
*
* `padDepth` inserts filler segments so the depth arm below can hold the file
* count fixed and vary only depth — the scaling ratio is scale-invariant in
* FILE COUNT and would otherwise never see a depth-driven cost regression. */
function buildCorpus(fileCount, padDepth = 0) {
const pad = Array.from({ length: padDepth }, (_, d) => `p${d}`).join('/');
const pad = Array.from({ length: padDepth }, (_, i) => `deep${i}`).join('/');
const files = [];
const packages = Math.max(1, Math.floor(fileCount / 8));
for (let i = 0; i < fileCount; i++) {
const mod = i % 16;
const root = pad === '' ? `lib${mod}` : `lib${mod}/${pad}`;
files.push(`${root}/src/main/kotlin/com/example/mod${mod}/Class${i}.kt`);
const pkg = i % packages;
const prefix = pad === '' ? `mod${pkg}` : `mod${pkg}/${pad}`;
files.push(
parsedFile(
`${prefix}/src/main/kotlin/com/example/pkg${pkg}/Source${i}.kt`,
`com.example.pkg${pkg}`,
[`File${i}`, `topLevel${i}`],
),
);
}
return files;
}
/** Import targets for the corpus, ~40% of them unresolvable — see header
* property 3: only a miss drives all four tiers, which is where the
* per-import scan was worst. */
function buildImports(fileCount) {
const imports = [];
for (let i = 0; i < fileCount * IMPORTS_PER_FILE; i++) {
const kind = i % 5;
const mod = i % 16;
if (kind === 0)
imports.push(`com.example.mod${mod}.Class${i % fileCount}`); // tier 1 hit
else if (kind === 1)
imports.push(`com.example.mod${mod}.someFunction`); // fan-out
else if (kind === 2)
imports.push(`mod${mod}.Class${i % fileCount}`); // suffix
else imports.push(`org.absent.pkg${mod}.Missing${i}`); // full cascade, no hit
}
return imports;
}
function fastest(values) {
return Math.min(...values);
}
/**
* Time one full pass: the index build PLUS resolving every import. The build is
* the work the per-import scan was traded for, so hiding it would let an index
* that is itself quadratic pass. Each pass gets its own Set object, because the
* index is memoized on Set identity and a shared Set would build once and make
* every later pass free. The Sets are constructed OUTSIDE the timer so their
* own O(files) cost never lands in the measurement.
*/
function timeResolution(files, imports) {
const sets = [];
for (let i = 0; i < WARMUP + REPS; i++) sets.push(new Set(files));
const fromFile = files[0];
for (let w = 0; w < WARMUP; w++) {
for (const t of imports) {
resolveKotlinImportTarget(
{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: t },
{ fromFile, allFilePaths: sets[w] },
);
const packages = Math.max(1, Math.floor(fileCount / 8));
return Array.from({ length: fileCount * IMPORTS_PER_FILE }, (_, i) => {
const file = i % fileCount;
const pkg = file % packages;
switch (i % 4) {
case 0:
return `com.example.pkg${pkg}.File${file}`;
case 1:
return `com.example.pkg${pkg}.topLevel${file}`;
case 2:
return `com.example.pkg${pkg}.*`;
default:
return `org.external.pkg${pkg}.Missing${i}`;
}
}
const samples = [];
for (let r = 0; r < REPS; r++) {
const set = sets[WARMUP + r];
const t0 = performance.now();
for (const t of imports) {
resolveKotlinImportTarget(
{ kind: 'named', localName: 'X', importedName: 'X', targetRaw: t },
{ fromFile, allFilePaths: set },
);
}
samples.push(performance.now() - t0);
}
return fastest(samples);
});
}
const scales = {};
for (const [name, fileCount] of [
['small', SMALL],
['large', LARGE],
]) {
const files = buildCorpus(fileCount);
function timeResolution(fileCount, padDepth = 0) {
const workspaces = Array.from({ length: WARMUP + REPS }, () => buildCorpus(fileCount, padDepth));
const imports = buildImports(fileCount);
scales[name] = {
files: fileCount,
imports: imports.length,
ms: Number(timeResolution(files, imports).toFixed(3)),
};
const samples = [];
for (let run = 0; run < workspaces.length; run++) {
const pass = prepare(workspaces[run]);
const start = performance.now();
let sink = 0;
for (const target of imports) if (resolve(target, pass) !== null) sink++;
const elapsed = performance.now() - start;
if (sink === 0) throw new Error('benchmark workload resolved nothing');
if (run >= WARMUP) samples.push(elapsed);
}
return Math.min(...samples);
}
const scalingRatio = scales.large.ms / scales.small.ms / (LARGE / SMALL);
// Depth arm: file count fixed, depth roughly tripled. `scaling_ratio` divides
// out the file count, so it is scale-INVARIANT and structurally cannot see a
// cost that grows with path depth instead — and both loops this PR added are
// depth loops. Same corpus size, same imports, only the paths get longer.
const depthFiles = buildCorpus(DEPTH_FILES, 0);
const depthFilesPadded = buildCorpus(DEPTH_FILES, DEPTH_PAD);
const depthImports = buildImports(DEPTH_FILES);
const shallowMs = timeResolution(depthFiles, depthImports);
const deepMs = timeResolution(depthFilesPadded, depthImports);
const depthRatio = deepMs / shallowMs;
const smallMs = timeResolution(SMALL);
const largeMs = timeResolution(LARGE);
const deepMs = timeResolution(SMALL, 16);
const report = {
small: scales.small,
large: scales.large,
scaling_ratio: Number(scalingRatio.toFixed(3)),
depth: {
files: DEPTH_FILES,
shallow_components: 8,
deep_components: 8 + DEPTH_PAD,
shallow_ms: Number(shallowMs.toFixed(3)),
deep_ms: Number(deepMs.toFixed(3)),
},
depth_ratio: Number(depthRatio.toFixed(3)),
cases: lines.length,
fingerprint,
cases: records.length,
non_null: nonNull,
fingerprint: correctnessFingerprint,
small: { files: SMALL, imports: SMALL * IMPORTS_PER_FILE, ms: Number(smallMs.toFixed(3)) },
large: { files: LARGE, imports: LARGE * IMPORTS_PER_FILE, ms: Number(largeMs.toFixed(3)) },
scaling_ratio: Number((largeMs / smallMs / (LARGE / SMALL)).toFixed(3)),
depth_ratio: Number((deepMs / smallMs).toFixed(3)),
};
if (!process.argv.includes('--check')) {
console.log(JSON.stringify(report, null, 2));
process.exit(0);
}
console.log(JSON.stringify(report, null, 2));
if (!CHECK) process.exit(0);
const baseline = JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf-8'));
const failures = [];
if (report.fingerprint !== baseline.fingerprint) {
failures.push(
`fingerprint drift: ${report.fingerprint} != ${baseline.fingerprint} — Kotlin import ` +
`resolution returned a DIFFERENT file set. That is a behaviour change, not a perf one: ` +
`IMPORTS/CALLS edges move in every Kotlin repository. Explain it, never re-baseline to ` +
`make CI green.`,
);
}
for (const field of ['cases', 'non_null']) {
if (report[field] !== baseline[field]) {
failures.push(
`${field} ${report[field]} != ${baseline[field]} — the corpus itself changed, so the ` +
`fingerprint above is computed over a different surface and proves nothing about the ` +
`resolver. Re-baseline every corpus field together, deliberately.`,
);
}
for (const key of ['fingerprint', 'cases', 'non_null']) {
if (report[key] !== baseline[key]) failures.push(`${key}: ${report[key]} != ${baseline[key]}`);
}
if (report.scaling_ratio > baseline.scaling_budget) {
failures.push(
`scaling ${report.scaling_ratio} > budget ${baseline.scaling_budget} — per-import cost grows ` +
`with workspace size again, i.e. a tier went back to walking allFilePaths. Timing arm: ` +
`re-run on an idle machine before investigating (see _scaling_note in baselines.json); the ` +
`fingerprint arm is deterministic and never warrants a re-run.`,
);
failures.push(`scaling_ratio ${report.scaling_ratio} > ${baseline.scaling_budget}`);
}
if (report.depth_ratio > baseline.depth_budget) {
failures.push(
`depth ratio ${report.depth_ratio} > budget ${baseline.depth_budget} — cost now grows with ` +
`PATH DEPTH at a fixed file count. scaling_ratio divides the file count out and cannot ` +
`see this. Timing arm: re-run on an idle machine first.`,
);
failures.push(`depth_ratio ${report.depth_ratio} > ${baseline.depth_budget}`);
}
if (report.small.ms > baseline.small_ms_ceiling) {
failures.push(
`small arm ${report.small.ms} ms > ceiling ${baseline.small_ms_ceiling} ms — scaling_ratio is ` +
`a RATIO, so a constant-factor regression that grows both arms equally passes it (a full ` +
`scan reintroduced on 1-in-32 imports measured 1.490, inside the budget, while running ` +
`2.8x slower). This ceiling is what catches that. Timing arm: re-run on an idle machine.`,
);
failures.push(`small.ms ${report.small.ms} > ${baseline.small_ms_ceiling}`);
}
console.log(JSON.stringify(report, null, 2));
if (failures.length > 0) {
console.error(`[kotlin-import-target --check] FAIL\n - ${failures.join('\n - ')}`);
process.exit(1);

View file

@ -209,7 +209,7 @@
"_rebaselined_blind_spots_2856": "#2856 blind-spots series: the JS/TS SCOPE queries gained capture rules, so fingerprint drift is expected and additive. Verified before re-baselining by diffing the capture-name sets in both scope queries against origin/main: TypeScript gained exactly @reference.read.identifier (A2 bare-identifier reads in value positions) and @reference.type (R2-2 type references, so a declared contract stops reporting incoming:{}); JavaScript gained exactly @reference.read.identifier, @reference.read.destructured (R2-1c) and @reference.write.property-key (R2-1b record-construction writes). NOTHING was removed on either side \u2014 the delta is a pure superset, which is the check that no existing capture moved. capture_groups_small/large are unchanged (4503/14403) because those measure the SYNTHETIC scaling source, which this branch does not touch; only the fixture-corpus count moves. capture_groups_fp 2097 -> 2338 and fixture_count 146 -> 151 from 21 new lang-resolution fixtures. Scaling stayed linear and inside budget: typescript 1.116 < 1.5, javascript 1.010 < 1.5. Prior typescript ed92588e0fc7b28b3a0174339ac378b4dd85965fe007db1208dea97a65ce0571 -> f66a3e6f1e096431e7046505129a627deaa00ca0de5bc846b080591b397248f7; prior javascript 806f70ad3cce5fc849f6d06a08ace8a95f92a1ea84a2418fddabb1eef5846594 -> 2026993b81b873839dd2ef8797d9c14d9c48516b2b57b05ac17d8d43f2f4eba3."
},
"kotlin": {
"fingerprint": "a184f8ff0ae40d246db855b63f7ff26bda3afac03e5f4c76e4593c7e2cefce54",
"fingerprint": "f98e7e936afbce0e99588285cfc603bf945fd58c5de45271860509a5d90eb832",
"scaling_budget": 1.5,
"_rebaselined_callable_flow_2522_review": "PR #2522 review hardening: callable operands retain expression/qualified identity and formals retain signature metadata. Prior bddba25d5a88152bbbee8d70e82c944b5302accb4b625df782adb1d4f7a7ac12 -> e856951c2a779163d555dadc8e1bf59304a86caed78ac1f450d9caa2b50f63d1; scaling 1.090 < 1.5.",
"_rebaselined_callable_flow_2522_followup": "PR #2522 follow-up: Kotlin callable-reference flow facts with invocation-result suppression. Prior 4900431791f2b9280009deb2b82659c26ead8aa6fb8731190a7c505dec5a9041 -> bddba25d5a88152bbbee8d70e82c944b5302accb4b625df782adb1d4f7a7ac12; scaling 0.880 < 1.5.",
@ -222,9 +222,10 @@
"_rebaselined_receiver_chain_2747": "#2747 receiver-chain rollout: call matches whose receiver is itself an expression now carry `@reference.receiver-chain`, a compact encoding of the receiver's structure, so resolution types it by folding instead of re-parsing receiver source text. Capture GROUP counts are unchanged \u2014 the tag is added to existing call matches, never a new match \u2014 so this is digest drift only. Prior 9f159f8810d342ef1c821f466efd6920dad9a190f06000056e6cd2815861b195 -> d3c4d2fa0d82d248a2299cfc888b067187ad1faf2c87a97f93c6ed835eefc3f1.",
"_rebaselined_2766_receiver_chain_wire_v2": "#2766: receiver-chain wire format v1 -> v2 (name-free `await` / `index` step kinds). The VERSION prefix is part of every emitted `@reference.receiver-chain` capture, so every chain-minting language's capture text changed. WIRE-FORMAT CHANGE, NOT A CAPTURE-SET CHANGE: the same chains are minted for the same sites, spelled `2|\u2026` instead of `1|\u2026`. Exactly the 12 chain-minting languages drifted; c, cobol and dart did not, which is the check that this is the prefix and not a capture regression. Accompanied by SCHEMA_BUMP 34 -> 37 and INCREMENTAL_SCHEMA_VERSION 28 -> 31 so a stale index is rejected rather than replaying chains a v2 decoder refuses. Prior d3c4d2fa0d82d248a2299cfc888b067187ad1faf2c87a97f93c6ed835eefc3f1 -> c1f0cc9058ab11b7cd6fc8b440deb6db2b2f530f2eb21178923e68a3d0796c4b.",
"_rebaselined_2766_await_subscript_emission": "#2766: extractMixedChain now walks THROUGH await and subscript nodes and peels transparent wrappers at loop entry, so sites whose receiver is `repos[0]` or `(await f())` mint a receiver chain where they previously minted none. EMISSION CHANGE: more sites carry `@reference.receiver-chain`; no existing chain changed shape. Only go and kotlin drifted of 15 \u2014 the two whose fixture corpora contain such receivers. Prior c1f0cc9058ab11b7cd6fc8b440deb6db2b2f530f2eb21178923e68a3d0796c4b -> efd5dbf80ffcd3bab2834d1010f6fe2b239dcc5d58229938dea9cff8d0f380f2.",
"_rebaselined_2960_declared_package_fixture": "#2960 adds four Kotlin declared-package import-resolution fixture files. This is fixture-corpus growth only: fixture_count 137 -> 141 and capture_groups_fp 2334 -> 2367; the synthetic capture counts remain 4753/15203, no Kotlin scope-capture query or implementation changed, and package resolution runs after capture. Other language fingerprints matched their baselines in the same CI run. Prior a184f8ff0ae40d246db855b63f7ff26bda3afac03e5f4c76e4593c7e2cefce54 -> f98e7e936afbce0e99588285cfc603bf945fd58c5de45271860509a5d90eb832.",
"capture_groups_small": 4753,
"capture_groups_large": 15203,
"capture_groups_fp": 2334,
"fixture_count": 137
"capture_groups_fp": 2367,
"fixture_count": 141
}
}

File diff suppressed because it is too large Load diff

View file

@ -1,6 +1,6 @@
{
"name": "gitnexus",
"version": "1.6.9",
"version": "1.6.10",
"description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
"author": "Abhigyan Patwari",
"license": "PolyForm-Noncommercial-1.0.0",
@ -69,6 +69,7 @@
"graphology": "^0.26.0",
"graphology-indices": "^0.17.0",
"graphology-utils": "^2.3.0",
"graphql": "^16.14.2",
"ignore": "^7.0.5",
"js-yaml": "^5.0.0",
"jsonc-parser": "^3.3.1",
@ -120,6 +121,8 @@
"vitest": "^4.0.18"
},
"overrides": {
"adm-zip": ">=0.6.0",
"sharp": ">=0.35.0",
"@huggingface/transformers": {
"onnxruntime-node": "$onnxruntime-node"
}

View file

@ -65,6 +65,16 @@ export const WINDOWS_WEIGHTS_SEC: Readonly<Record<string, number>> = {
'test/integration/antigravity-hook-e2e.test.ts': 7,
'test/unit/index-lock.test.ts': 5,
'test/unit/setup.test.ts': 5,
// ESTIMATE, not a measurement. This file asserts almost nothing; it READS —
// one 4893-file pass over every tracked text file, plus an 830-file pass over
// `src/`. Measured at 2.3 s and 0.3 s per pass on a virtualised and a local
// Linux filesystem respectively, so the cost is entirely per-file open
// latency, which is the term Windows inflates most (NTFS plus Defender on
// every read). Scaled from the slower Linux figure to keep the split
// conservative rather than let the 8 s PER_FILE_OVERHEAD floor under-charge
// a file that touches more paths than anything else here. Replace with a real
// figure after the first green Windows matrix run.
'test/unit/source-control-bytes.test.ts': 15,
};
/**

View file

@ -90,6 +90,7 @@ const PLATFORM_LOGIC = [
'test/unit/ignore-service.test.ts',
'test/unit/group/bridge-db.test.ts',
'test/unit/group/bridge-db-edge.test.ts',
'test/unit/group/fs-utils.test.ts',
'test/unit/onnxruntime-node-resolver.test.ts',
// Windows cmd.exe arg-quoting + compose-and-spawn for the npm install (#2372):
// the quoting rules and win32 single-string spawn shape are OS-sensitive, so
@ -140,6 +141,7 @@ const LBUG_NATIVE = [
// opens them through the pool adapter (native addon + bridge file locking).
// Windows is skipped in-file (describeReopen) due to the bridge reopen lock.
'test/integration/group/cross-trace-e2e.test.ts',
'test/integration/group/graphql-resolve-symbol.test.ts',
'test/integration/local-backend.test.ts',
'test/integration/local-backend-calltool.test.ts',
'test/integration/search-core.test.ts',
@ -208,6 +210,18 @@ const SPAWN_CLI = [
// exposed a file-backend double-admit race here (#2658 review); the reclaim is
// now judgment-verified so a live holder is never displaced.
'test/integration/analyze-index-lock-concurrency.test.ts',
// The per-group sync lock (R9), same class of guarantee one level up: real
// child processes contend for one group's lock while this process runs a real
// `syncGroup`, and the CLI case spawns the real command. Everything that
// varies here is platform-owned — which backend `selectBackend()` picks
// (Windows named pipe / Linux abstract socket / macOS file lock), kernel
// auto-release on SIGKILL vs. the file backend's pid-liveness reclaim, and
// `mkdir` over an occupied path. The fail-closed cases pin
// GITNEXUS_INDEX_LOCK_BACKEND=file so the filesystem branch is exercised on
// every OS rather than only where it is the default; no case is skipped on
// any platform, because a skipped case turns "a sync that cannot be protected
// does not run" into a claim that holds on Ubuntu only.
'test/integration/group/group-sync-lock-concurrency.test.ts',
// The three `dist/` module-load closure guards, all built on the shared
// child-process probe in `test/helpers/module-load-probe.ts`. That probe IS
// the platform-varying part: it spawns `process.execPath` in array form,
@ -261,6 +275,28 @@ const FILESYSTEM = [
'test/integration/filesystem-walker.test.ts',
'test/integration/markdown-processor-crlf.test.ts',
'test/integration/ignore-and-skip-e2e.test.ts',
// Pins that the bridge pairing verdict is measured before the database is
// opened. The property it protects is about mtime behavior across OS and
// filesystem, and the alternative — really opening the bridge — cannot run on
// Windows at all (in-process write→read reopen of the same bridge.lbug is a
// documented limitation). Running it on every platform is the whole point:
// Windows is where an unverified assumption about mtime would hurt most.
'test/unit/group/bridge-pairing-precedes-open.test.ts',
// The raw-control-byte guard reads every tracked text file `git ls-files`
// reports — 4893 of them — and decides membership from the git path, which is
// always `/`-separated no matter what the host separator is. Both halves of
// that are platform-varying: the collector basename-matches with
// `path.posix.basename` against `git ls-files -z` output while the reads go
// through `path.join`, so on Windows the same string is consumed under two
// separator conventions in one pass, and only a real windows-latest run
// proves they agree. It is also the file-count-heaviest read loop in the
// suite, so it is where a per-file filesystem cost (NTFS + Defender, or
// macOS's slower stat path) would show up first. No case is skipped on any
// platform: a guard that only holds on Ubuntu is not a guard on the file
// whose NUL it exists to catch. Budget: the heaviest single case is one
// 4893-file pass — 2.3 s on a slow virtualised filesystem, 0.34 s on a local
// disk — against a 30 s testTimeout.
'test/unit/source-control-bytes.test.ts',
];
const ALL_CROSS_PLATFORM = [

View file

@ -55,15 +55,19 @@ Deletes the `.gitnexus/` directory and unregisters the repo from the global regi
node .gitnexus/run.cjs wiki
```
Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
Generates repository documentation from the knowledge graph using an LLM. HTTP providers require an API key (saved to `~/.gitnexus/config.json` on first use). Local CLI providers (`--provider cursor|claude|codex|opencode|grok`) use your existing CLI login.
| Flag | Effect |
| ------------------- | ----------------------------------------- |
| `--force` | Force full regeneration |
| `--force` | Force full regeneration, also required to re-generate an existing wiki in a different language |
| `--provider <name>` | LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax). Local CLIs (`cursor`, `claude`, `codex`, `opencode`, `grok`) use your existing CLI login and skip `--api-key`. |
| `--model <model>` | LLM model (default: MiniMax-M3) |
| `--base-url <url>` | LLM API base URL |
| `--api-key <key>` | LLM API key |
| `--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) |
| `--lang <lang>` | Output language for generated documentation (e.g. english, chinese, spanish, japanese) |
| `--gist` | Publish wiki as a public GitHub Gist |
### list — Show all indexed repos

View file

@ -13,9 +13,28 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
- "This endpoint returns 500"
- Investigating bugs, errors, or unexpected behavior
## Bind the repository first
A root cause traced in the wrong repository is a wrong root cause.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask. This matters most for `cypher`, whose
statement carries no in-band hint of which database it ran against.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
A stale index describes the code from before your bug, so refresh before
trusting a trace, and state the repository and index freshness with the
diagnosis.
## Workflow
```
0. list_repos {} → Bind repo
1. query({search_query: "<error or symptom>"}) → Find related execution flows
2. context({name: "<suspect>"}) → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
@ -27,6 +46,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
@ -34,6 +54,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
- [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
- [ ] State the repository and index freshness with the diagnosis
```
## Debugging Patterns
@ -44,7 +65,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
| Wrong return value | `context` on the function → trace callees for data flow |
| Intermittent failure | `context` → look for external calls, async deps |
| Performance issue | `context` → find symbols with many callers (hot paths) |
| Recent regression | `detect_changes` to see what your changes affect |
| Recent regression | `detect_changes` to see what your changes affect — pass `worktree` for a linked worktree |
| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
## Tools
@ -52,7 +73,7 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
**query** — find code related to error:
```
query({search_query: "payment validation error"})
query({search_query: "payment validation error", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException
```
@ -60,13 +81,15 @@ query({search_query: "payment validation error"})
**context** — full context for a suspect:
```
context({name: "validatePayment"})
context({name: "validatePayment", repo: "my-app"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)
```
**cypher** — custom call chain traces:
**cypher** — custom call chain traces. Pass `repo` alongside the statement; the
Cypher text itself names no repository, so the result is unattributable without
it:
```cypher
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
@ -76,7 +99,7 @@ RETURN [n IN nodes(path) | n.name] AS chain
**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
```
trace({ from: "processCheckout", to: "fetchRates" })
trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
@ -87,15 +110,22 @@ When no path exists, `trace` reports the furthest reachable node — exactly whe
## Example: "Payment endpoint returns 500 intermittently"
```
1. query({search_query: "payment error handling"})
0. list_repos {}
→ total: 2 (my-app, billing-api) — bind my-app explicitly on every call
1. query({search_query: "payment error handling", repo: "my-app"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError
2. context({name: "validatePayment"})
2. context({name: "validatePayment", repo: "my-app"})
→ Outgoing calls: verifyCard, fetchRates (external API!)
3. READ gitnexus://repo/my-app/process/CheckoutFlow
→ Step 3: validatePayment → calls fetchRates (external)
4. Root cause: fetchRates calls external API without proper timeout
Repository: my-app Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -13,10 +13,22 @@ description: "Use when the user asks how code works, wants to understand archite
- "Where is the database logic?"
- Understanding code you haven't seen before
## Bind the repository first
Step 1 discovers what is indexed; every call after it must say which of those
it means. With one indexed repository, use the examples below as written. With
more than one, pass `repo` on every call: an omitted `repo` normally errors,
but under an MCP policy with a configured default it resolves to that default
silently. If you cannot tell which repository is meant, stop and ask. Report
the bound repository and index freshness alongside your explanation.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
## Workflow
```
1. READ gitnexus://repos → Discover indexed repos
1. list_repos {} or READ gitnexus://repos → Discover indexed repos
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
3. query({search_query: "<what you want to understand>"}) → Find related execution flows
4. context({name: "<symbol>"}) → Deep dive on specific symbol
@ -28,12 +40,14 @@ description: "Use when the user asks how code works, wants to understand archite
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] READ gitnexus://repo/{name}/context
- [ ] query for the concept you want to understand
- [ ] Review returned processes (execution flows)
- [ ] context on key symbols for callers/callees
- [ ] READ process resource for full execution traces
- [ ] Read source files for implementation details
- [ ] State the repository and index freshness with the explanation
```
## Resources
@ -50,7 +64,7 @@ description: "Use when the user asks how code works, wants to understand archite
**query** — find execution flows related to a concept:
```
query({search_query: "payment processing"})
query({search_query: "payment processing", repo: "my-app"})
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Symbols grouped by flow with file locations
```
@ -58,16 +72,20 @@ query({search_query: "payment processing"})
**context** — 360-degree view of a symbol:
```
context({name: "validateUser"})
context({name: "validateUser", repo: "my-app"})
→ Incoming calls: loginHandler, apiMiddleware
→ Outgoing calls: checkToken, getUserById
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
```
`repo` is required once more than one repository is indexed, and may be omitted
with a single one.
## Example: "How does payment processing work?"
```
1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
1. list_repos {} → total: 1 (my-app) — bind it
READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
2. query({search_query: "payment processing"})
→ CheckoutFlow: processPayment → validateCard → chargeStripe
→ RefundFlow: initiateRefund → calculateRefund → processRefund
@ -75,4 +93,8 @@ context({name: "validateUser"})
→ Incoming: checkoutHandler, webhookHandler
→ Outgoing: validateCard, chargeStripe, saveTransaction
4. Read src/payments/processor.ts for implementation details
5. Answer, noting: Repository my-app, index current
```
Had step 1 returned two repositories, every call above would carry
`repo: "my-app"`.

View file

@ -14,13 +14,42 @@ description: "Use when the user wants to know what will break if they change som
- Before making non-trivial code changes
- Before committing — to understand what your changes affect
## Bind the repository first
Impact analysis is the gate that authorizes an edit, so it must answer for the
repository you are about to edit.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask — every result below an ambiguous
identity inherits the ambiguity. `list_repos` is paginated, so page with
`offset: pagination.nextOffset` until `hasMore` is false before concluding a
repository is absent.
`detect_changes` takes `worktree` when your changes are in a linked worktree
the MCP server was not launched from. The server auto-detects a worktree only
when it was launched from inside one; otherwise `git diff` runs in the wrong
checkout and reports zero changed symbols — a false clean check that carries
none of the degradation flags described below. In the CLI fallbacks, `--repo .`
means the current checkout; pass the intended repository path instead when you
are not standing in it.
State the bound identity with your risk report:
```
Repository: <name> (<path>) Worktree: <path> Index: <commit>, <n> behind HEAD
```
## Workflow
```
0. list_repos {} → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) or `node .gitnexus/run.cjs impact "X" --direction upstream --repo .`
2. READ gitnexus://repo/{name}/processes → Check affected execution flows
3. detect_changes({scope: "all"}) or `node .gitnexus/run.cjs detect-changes --scope all --repo .`
4. Assess risk and report to user
4. Assess risk and report to user, echoing repo/worktree/index identity
```
> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@ -29,12 +58,14 @@ description: "Use when the user wants to know what will break if they change som
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] impact({target, direction: "upstream"}) or CLI fallback to find dependents
- [ ] Review d=1 items first (these WILL BREAK)
- [ ] Check high-confidence (>0.8) dependencies
- [ ] READ processes to check affected execution flows
- [ ] detect_changes({scope: "all"}) or CLI fallback for pre-commit check
- [ ] Assess risk level and report to user
- [ ] Confirm the checkout you edited is the checkout that was diffed
- [ ] Assess risk level and report, stating repo/worktree/index identity
```
## Understanding Output
@ -69,6 +100,7 @@ treating the symbol as safe to change or delete.
```
impact({
target: "validateUser",
repo: "my-app", // required once >1 repository is indexed
direction: "upstream",
minConfidence: 0.8,
maxDepth: 3
@ -92,15 +124,26 @@ detect_changes({scope: "all"})
→ Risk: MEDIUM
```
Add `repo` once more than one repository is indexed, and `worktree: "<abs
path>"` when your changes are in a linked worktree the server was not launched
from.
`partial: true` (a graph query failed) or `truncated: true` (the changed-symbol
listing was capped) means the result is short of the truth, and reads like
`UNKNOWN` above: a zero there means unseen, not unaffected. Re-run it rather
than tick the pre-commit check.
A wrong-worktree zero carries neither flag and is shape-identical to a genuine
clean result, so confirm the checkout you edited is the one that was diffed
before treating an empty change set as a passed check.
## Example: "What breaks if I change validateUser?"
```
1. impact({target: "validateUser", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
0. list_repos {}
→ total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
1. impact({target: "validateUser", repo: "my-app", direction: "upstream"}) or `node .gitnexus/run.cjs impact "validateUser" --direction upstream --repo .`
→ d=1: loginHandler, apiMiddleware (WILL BREAK)
→ d=2: authRouter, sessionManager (LIKELY AFFECTED)
@ -108,4 +151,8 @@ than tick the pre-commit check.
→ LoginFlow and TokenRefresh touch validateUser
3. Risk: 2 direct callers, 2 processes = MEDIUM
Repository: my-app (/abs/path/my-app) Worktree: same Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -13,9 +13,32 @@ description: "Use when the user wants to rename, extract, split, move, or restru
- "Move this to a new file"
- Any task involving renaming, extracting, splitting, or restructuring code
## Bind the repository first
Refactoring writes to disk. `rename` with `dry_run: false` edits files in
whichever repository was resolved, so binding identity here is a safety gate,
not bookkeeping.
Call `list_repos {}` before the first tool call. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
which repository is meant, stop and ask. Never run `rename` with
`dry_run: false` until the preview in the same bound repository has been
reviewed — its returned `file_path` values show which checkout is about to be
written, so read them as a confirmation of identity.
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
`hasMore` is false before concluding a repository is absent.
`detect_changes` takes `worktree` when you are editing a linked worktree the
MCP server was not launched from; otherwise `git diff` runs in the wrong
checkout and reports nothing changed, which reads as a verified refactor.
## Workflow
```
0. list_repos {} → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"}) → Map all dependents
2. query({search_query: "X"}) → Find execution flows involving X
3. context({name: "X"}) → See all incoming/outgoing refs
@ -29,7 +52,9 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Rename Symbol
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
- [ ] Confirm the previewed file paths are in the bound repository/worktree
- [ ] Review graph edits (high confidence) and text_search edits (review carefully)
- [ ] If satisfied: rename({..., dry_run: false}) — apply edits
- [ ] detect_changes() — verify only expected files changed
@ -39,6 +64,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Extract Module
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] context({name: target}) — see all incoming/outgoing refs
- [ ] impact({target, direction: "upstream"}) — find all external callers
- [ ] Define new module interface
@ -50,6 +76,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
### Split Function/Service
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] context({name: target}) — understand all callees
- [ ] Group callees by responsibility
- [ ] impact({target, direction: "upstream"}) — map callers to update
@ -64,7 +91,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
**rename** — automated multi-file rename:
```
rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
→ 12 edits across 8 files
→ 10 graph edits (high confidence), 2 text_search edits (review)
→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
@ -73,7 +100,7 @@ rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true
**impact** — map all dependents first:
```
impact({target: "validateUser", direction: "upstream"})
impact({target: "validateUser", repo: "my-app", direction: "upstream"})
→ d=1: loginHandler, apiMiddleware, testUtils
→ Affected Processes: LoginFlow, TokenRefresh
```
@ -92,6 +119,9 @@ listing was capped) means the result is short of the truth: a short or empty
list is not proof that only the expected files changed. Re-run it rather than
treat the refactor as verified.
A wrong-worktree zero carries neither flag and is indistinguishable from a
clean verification, so confirm the diffed checkout is the one you edited.
**cypher** — custom reference queries:
```cypher
@ -107,20 +137,28 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
| Cross-area refs | Use detect_changes after to verify scope |
| String/dynamic refs | query to find them |
| External/public API | Version and deprecate properly |
| Same name in another indexed repo | Bind `repo`; verify previewed paths before applying |
## Example: Rename `validateUser` to `authenticateUser`
```
1. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
0. list_repos {}
→ total: 2 (my-app, billing-api) — both define validateUser, so bind explicitly
1. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true})
→ 12 edits: 10 graph (safe), 2 text_search (review)
→ Files: validator.ts, login.ts, middleware.ts, config.json...
2. Review text_search edits (config.json: dynamic reference!)
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: false})
→ Applied 12 edits across 8 files
4. detect_changes({scope: "all"})
4. detect_changes({scope: "all", repo: "my-app"})
→ Affected: LoginFlow, TokenRefresh
→ Risk: MEDIUM — run tests for these flows
Repository: my-app (/abs/path/my-app) Worktree: same Index: current
```
With a single indexed repository, step 0 returns `total: 1` and the `repo`
argument drops out of every call above.

View file

@ -1,6 +1,8 @@
// gitnexus/src/cli/group.ts
import { createRequire } from 'node:module';
import type { Command } from 'commander';
import type { RegistryWriteOutcome } from '../core/group/sync.js';
import type { MatchType } from '../core/group/types.js';
import { logger } from '../core/logger.js';
const _require = createRequire(import.meta.url);
@ -120,16 +122,43 @@ export function registerGroupCommands(program: Command): void {
indexStale: boolean;
contractsStale: boolean;
missing: boolean;
/**
* Optional here on purpose: a payload produced before the split
* carries no such key, and an absent one must degrade to the
* label this command has always printed rather than to the new
* one — an unrecorded cause is not evidence of a cause.
*/
unresolvable?: boolean;
unresolvableReason?: string;
commitsBehind?: number;
}
>;
missingRepos?: string[];
unreadableRepos?: string[];
suppressedMatchStages?: string[];
};
console.log(' Repo index / contracts staleness:');
for (const [repoPath, row] of Object.entries(st.repos || {})) {
if (row.missing) {
console.log(` ${repoPath.padEnd(25)} MISSING (not in registry or unreadable)`);
// Two different facts with two different remedies: a repo the
// registry never heard of is fixed by indexing it, while an entry
// the resolver choked on is fixed by repairing the registry.
// Printing "no entry in the registry" for the second one states a
// cause that was never measured, and points at the wrong repair.
if (row.unresolvable) {
// The reason can be multi-line — an ambiguous registry names
// every colliding clone. Fold it onto this row's line rather
// than truncating it: those paths are what the operator acts on,
// and a table row that swallows half its own explanation is the
// failure this label exists to stop.
const why = (row.unresolvableReason ?? 'the registry entry could not be resolved')
.replace(/\s+/g, ' ')
.trim();
console.log(` ${repoPath.padEnd(25)} UNRESOLVABLE (${why})`);
continue;
}
console.log(` ${repoPath.padEnd(25)} MISSING (no entry in the registry)`);
continue;
}
const idx = row.indexStale
@ -138,9 +167,41 @@ export function registerGroupCommands(program: Command): void {
const ctr = row.contractsStale ? ' CONTRACTS_STALE' : '';
console.log(` ${repoPath.padEnd(25)} ${idx}${ctr}`);
}
// `undefined` and `[]` are different answers here: a registry written
// before this was tracked has no opinion, while an empty array is a
// measurement. Printing nothing for both would let an unmeasured sync
// read as evidence that every index opened cleanly.
//
// `undefined` covers two ways of not knowing — the field is absent, or
// it held something that was not a list of repo paths and `getStatus`
// declined to guess. Naming only the first would make a corrupt
// registry read as a merely old one, which is the same shape of wrong
// answer this command exists to stop giving.
const unreadable = st.unreadableRepos;
if (unreadable === undefined) {
console.log(
`\n Last sync unreadable repos: not recorded` +
`\n (the registry predates this field, or its value could not be read)` +
`\n Re-run \`gitnexus group sync\` to record it.`,
);
} else if (unreadable.length > 0) {
console.log(`\n Last sync unreadable repos: ${unreadable.join(', ')}`);
}
if ((st.missingRepos || []).length > 0) {
console.log(`\n Last sync missing repos: ${st.missingRepos!.join(', ')}`);
}
// Only the populated case prints. Absent means a registry that predates
// the field, and empty is the ordinary clean sync — neither is worth a
// line, whereas a narrowed registry changes how every later answer
// should be read.
const skippedStages = st.suppressedMatchStages ?? [];
if (skippedStages.length > 0) {
console.log(
`\n Last sync skipped matching stages: ${skippedStages.join(', ')}` +
`\n Cross-links those stages would have found are absent by request.` +
`\n Re-run \`gitnexus group sync\` without --exact-only for the complete set.`,
);
}
} finally {
await backend.dispose().catch(() => {});
}
@ -149,39 +210,131 @@ export function registerGroupCommands(program: Command): void {
group
.command('sync <name>')
.description('Sync Contract Registry — extract contracts and build cross-links')
.option('--skip-embeddings', 'Exact + BM25 only (no embedding fallback)')
.option('--exact-only', 'Exact match only')
.option('--allow-stale', 'Skip stale index warnings')
.option('--verbose', 'Show each cross-link detail')
.option(
'--exact-only',
'Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)',
)
.option('--verbose', 'Show additional sync diagnostics')
.option('--json', 'JSON output')
.action(async (name: string, opts: Record<string, boolean | undefined>) => {
const { getGroupDir, getDefaultGitnexusDir } = await import('../core/group/storage.js');
const { loadGroupConfig } = await import('../core/group/config-parser.js');
const { syncGroup } = await import('../core/group/sync.js');
const { GroupSyncLockError } = await import('../core/group/group-lock.js');
const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
const config = await loadGroupConfig(groupDir);
console.log(`Syncing group "${name}" (${Object.keys(config.repos).length} repos)...\n`);
const result = await syncGroup(config, {
groupDir,
allowStale: Boolean(opts.allowStale),
verbose: Boolean(opts.verbose),
skipEmbeddings: Boolean(opts.skipEmbeddings),
exactOnly: Boolean(opts.exactOnly),
});
let result: Awaited<ReturnType<typeof syncGroup>>;
try {
result = await syncGroup(config, {
groupDir,
verbose: Boolean(opts.verbose),
exactOnly: Boolean(opts.exactOnly),
});
} catch (err) {
// A sync that could not take the group's lock did NOT run and wrote
// nothing (R9 fails closed). That is an operator-actionable outcome, not
// a crash, so report it as a failed command rather than letting it
// surface as an unhandled rejection with a stack trace — commander's
// async actions have no error handler, so an uncaught throw here would
// print exactly that.
if (!(err instanceof GroupSyncLockError)) throw err;
logger.error(`⚠️ Did not sync group "${name}": ${err.message}`);
process.exitCode = 1;
return;
}
if (opts.json) {
console.log(JSON.stringify(result, null, 2));
} else {
console.log(`\nMatching cascade:`);
const exactLinks = result.crossLinks.filter((l) => l.matchType === 'exact');
console.log(` exact: ${exactLinks.length} cross-links (confidence 1.0)`);
console.log(` unmatched: ${result.unmatched.length} contracts`);
console.log(
`\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`,
);
// Repos we could not read are the most likely explanation for a small
// or empty contract count, so they are reported before the counts —
// otherwise a run that read nothing looks exactly like a clean run.
if (result.unreadableRepos.length > 0) {
// No "re-run with GITNEXUS_LOG_LEVEL=warn" hint: the default level is
// `info`, and pino emits `warn` (40) at `info` (30), so the reason was
// already printed by this same run — raising the level to `warn` would
// only suppress the surrounding `info` output.
console.log(
`\n ⚠️ Could not extract contracts from: ${result.unreadableRepos.join(', ')}` +
`\n None of their contracts are included in this sync (the warning above says why),` +
`\n or check \`gitnexus doctor\` in the affected repo.`,
);
}
if (result.missingRepos.length > 0) {
console.log(
`\n ⚠️ Not found in the registry: ${result.missingRepos.join(', ')}` +
`\n Index them with \`gitnexus analyze\`, or remove them from group.yaml.`,
);
}
// Every stage that produced a link, not just `exact`. This used to print
// `Matching cascade:` and then count `exact` alone, while the `Wrote
// contracts.json (…)` line below reports `result.crossLinks.length` —
// which also includes `manifest` and `wildcard` links. For any group with
// those, the two numbers disagreed with nothing on screen explaining why.
// Summing the stages here makes them reconcile by construction.
console.log(`\nMatching:`);
// Exhaustive by construction, same idiom as OUTCOME_LINE below: adding a
// MatchType fails the build here instead of silently going uncounted and
// reopening the very mismatch this replaced. Every stage prints even at
// zero — a stage that is absent reads as "did not apply", not "found none".
const STAGE_COUNTS: Record<MatchType, number> = {
exact: 0,
manifest: 0,
wildcard: 0,
};
for (const link of result.crossLinks) STAGE_COUNTS[link.matchType] += 1;
// A stage the sync was told to skip is reported as skipped, not as a
// zero count. The two are different facts — "ran, matched nothing" and
// "never ran" — and printing both as `0` is the same conflation this
// block replaced. Driven by what the sync did (`suppressedMatchStages`)
// rather than by what the caller asked for, so it stays correct on the
// outcomes where the run ended without writing a registry.
for (const stage of Object.keys(STAGE_COUNTS) as MatchType[]) {
const count = STAGE_COUNTS[stage];
const label = `${stage}:`.padEnd(10);
if (result.suppressedMatchStages.includes(stage)) {
console.log(` ${label} skipped (--exact-only)`);
continue;
}
const confidence = stage === 'exact' ? ' (confidence 1.0)' : '';
console.log(` ${label} ${count} cross-links${confidence}`);
}
console.log(` ${'unmatched:'.padEnd(10)} ${result.unmatched.length} contracts`);
// Driven by what actually happened to the file. This line used to be
// unconditional, so a run that deliberately preserved the previous
// registry still announced `Wrote contracts.json (0 contracts, 0
// cross-links)` — a confident false statement about persisted state, on
// the exact path this command exists to make legible.
// Exhaustive by construction: a `Record` keyed on the union means a
// new outcome fails the build here instead of printing nothing, which
// is what previously pushed a distinct state into `preserved` and made
// this summary false on one of the two branches it then covered.
const OUTCOME_LINE: Record<RegistryWriteOutcome, string | null> = {
written:
`\nWrote contracts.json (${result.contracts.length} contracts, ` +
`${result.crossLinks.length} cross-links)`,
preserved:
`\nKept the previous contracts.json — no repo in this group could be read.` +
`\n Its contracts and cross-links are unchanged; only the unreadable/missing` +
`\n repo lists were refreshed to describe THIS run. Fix the repos above and re-run.`,
superseded:
`\nDid NOT touch contracts.json — no repo in this group could be read, and another` +
`\n sync replaced the file while this one waited for the group lock. That sync's` +
`\n result stands and this run's repo lists were NOT recorded: they describe a` +
`\n group state older than what is on disk. Fix the repos above and re-run.`,
'no-prior-registry':
`\nDid NOT write contracts.json — no repo in this group could be read,` +
`\n and there is no previous contracts.json to fall back on. Fix the repos` +
`\n above and re-run.`,
// Nothing to say: the caller asked for no write.
'not-attempted': null,
};
const line = OUTCOME_LINE[result.registryOutcome];
if (line) console.log(line);
}
});
@ -281,11 +434,28 @@ export function registerGroupCommands(program: Command): void {
// repos — reporting it as crossings understates a fan-out cap the
// same way #2787's totals did.
const dropped = (raw as { truncatedRepos?: string[] })?.truncatedRepos ?? [];
console.log(
dropped.length > 0
? ` risk is a LOWER BOUND — fan-out stopped early; crossings to ${dropped.length} repo(s) not traversed: ${dropped.join(', ')}`
: ' risk is a LOWER BOUND — the local impact walk did not complete (every bridge crossing was traversed)',
);
const reason = (raw as { truncationReason?: string })?.truncationReason;
// Keyed on the REASON, not on which incidental fact happens to be
// non-empty. `truncatedRepos` is populated for a structural gap too
// — the bridge's incomplete repos are unioned into it even when ZERO
// crossings were attempted — so branching on its length first
// reported "fan-out stopped early" for a run where nothing stopped
// early, and omitted the only remedy that works. Same false-cause
// shape the contract listing was just re-gated for, one command over.
const floorReason = (): string => {
if (reason === 'suppressed-stage') {
return 'the last sync skipped a matching stage (--exact-only); re-run `gitnexus group sync` without it for the complete graph';
}
if (reason === 'incomplete-sync') {
return dropped.length > 0
? `the last sync could not account for ${dropped.join(', ')}; their contracts are absent from every query against this bridge — re-run \`gitnexus group sync\``
: 'the last sync could not say which repos it read — re-run `gitnexus group sync`';
}
return dropped.length > 0
? `fan-out stopped early; crossings to ${dropped.length} repo(s) not traversed: ${dropped.join(', ')}`
: 'the local impact walk did not complete (every bridge crossing was traversed)';
};
console.log(` risk is a LOWER BOUND — ${floorReason()}`);
}
}
} finally {
@ -370,7 +540,15 @@ export function registerGroupCommands(program: Command): void {
return;
}
const { contracts, crossLinks } = raw as {
const {
contracts,
crossLinks,
truncated,
unreadableRepos,
missingRepos,
suppressedMatchStages,
truncationReason,
} = raw as {
contracts: Array<{
role: string;
contractId: string;
@ -384,10 +562,21 @@ export function registerGroupCommands(program: Command): void {
confidence: number;
contractId: string;
}>;
truncated?: boolean;
suppressedMatchStages?: string[];
truncationReason?: string;
unreadableRepos?: string[];
missingRepos?: string[];
};
if (opts.json) {
console.log(JSON.stringify({ contracts, crossLinks }, null, 2));
// The whole payload, not a re-serialized subset. Destructuring the two
// fields this command happens to print and rebuilding an object from
// them dropped everything else the service returned — which is how the
// completeness fields were invisible here while the MCP tool carried
// them. Printing `raw` means a field added to the service reaches
// `--json` without a matching edit in this file.
console.log(JSON.stringify(raw, null, 2));
} else {
console.log(`Contracts (${contracts.length}):`);
for (const c of contracts) {
@ -399,6 +588,39 @@ export function registerGroupCommands(program: Command): void {
` ${l.from.repo} -> ${l.to.repo} [${l.matchType}, conf=${l.confidence}] ${l.contractId}`,
);
}
// Separate from `truncated` below, and deliberately so: that one means
// the sync could not read something and the remedy is to fix the repo.
// This one means the sync was ASKED to skip a stage, and the remedy is
// to re-run without the flag. A listing narrowed on purpose is still
// narrowed, and without this the human view showed nothing at all.
if (suppressedMatchStages && suppressedMatchStages.length > 0) {
console.log(
`\n⚠️ This listing is a lower bound: the last sync skipped ${suppressedMatchStages.join(', ')} matching` +
`\n (--exact-only), so cross-links that stage would have found are absent.` +
`\n Re-run \`gitnexus group sync\` without --exact-only for the complete set.`,
);
}
// Gated on the REASON, not just the flag. A suppressed stage sets
// `truncated` with both repo lists empty, which sent this block down
// its else-branch and printed "the last sync did not record which
// repos it could read" — a false statement, with the wrong remedy,
// about a sync that recorded them fine. The suppressed-stage warning
// above already said the true thing. When a repo gap co-occurs the
// reason is 'incomplete-sync' (the repo side takes precedence in
// `crossRepoCompleteness`), so this block still runs for it.
if (truncated && truncationReason !== 'suppressed-stage') {
// Counts above are a floor, not a census. Name the repos when the
// registry recorded them, and say so plainly when it did not — a
// listing that cannot say what it is missing is still incomplete.
const absent = [...(unreadableRepos ?? []), ...(missingRepos ?? [])];
console.log(
absent.length > 0
? `\n⚠️ This listing is incomplete: the last sync could not account for ${absent.join(', ')}.` +
`\n Contracts from those repos are absent, so the counts above are a lower bound.`
: `\n⚠️ This listing is incomplete: the last sync did not record which repos it could` +
`\n read, so the counts above are a lower bound. Re-run group sync.`,
);
}
}
} finally {
await backend.dispose().catch(() => {});

View file

@ -155,9 +155,7 @@ const OPTION_DESCRIPTION_KEYS = {
'embeddings install|--cuda': 'help.option.embeddings.install.cuda',
'embeddings install|--force': 'help.option.embeddings.install.force',
'group create|--force': 'help.option.group.create.force',
'group sync|--skip-embeddings': 'help.option.group.sync.skipEmbeddings',
'group sync|--exact-only': 'help.option.group.sync.exactOnly',
'group sync|--allow-stale': 'help.option.group.sync.allowStale',
'group sync|--verbose': 'help.option.group.sync.verbose',
'group sync|--json': 'help.option.json',
'group impact|--target <symbol>': 'help.option.group.impact.target',

View file

@ -234,7 +234,7 @@ export const en = {
'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)',
'help.option.wiki.force': 'Force full regeneration even if up to date',
'help.option.wiki.provider':
'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)',
'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)',
'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)',
'help.option.wiki.baseUrl':
'LLM API base URL. Azure v1: https://{resource}.openai.azure.com/openai/v1',
@ -293,10 +293,9 @@ export const en = {
'help.option.embeddings.install.force':
'Install into the runtime prefix even when the stack already resolves',
'help.option.group.create.force': 'Overwrite existing group',
'help.option.group.sync.skipEmbeddings': 'Exact + BM25 only (no embedding fallback)',
'help.option.group.sync.exactOnly': 'Exact match only',
'help.option.group.sync.allowStale': 'Skip stale index warnings',
'help.option.group.sync.verbose': 'Show each cross-link detail',
'help.option.group.sync.exactOnly':
'Skip wildcard service matching; cross-link on exact contract-id match only (manifest links still apply)',
'help.option.group.sync.verbose': 'Show additional sync diagnostics',
'help.option.status.json': 'Emit machine-readable index and analyzer provenance',
'help.option.json': 'JSON output',
'help.option.group.impact.target': 'Symbol or file name to analyze',

View file

@ -220,7 +220,7 @@ export const zhCN = {
'清理已暂存的 LadybugDB 恢复 sidecar(missing-shadow WAL 隔离文件与 dirty-recovery 暂存文件)',
'help.option.wiki.force': '即使已是最新也强制完整重新生成',
'help.option.wiki.provider':
'LLM 提供商:minimax、openai、openrouter、azure、custom、cursor、claude、codex 或 opencode(默认:minimax)',
'LLM 提供商:minimax、openai、openrouter、azure、custom、cursor、claude、codex、opencode 或 grok(默认:minimax)',
'help.option.wiki.model': 'LLM 模型或 deployment 名称(默认:MiniMax-M3)',
'help.option.wiki.baseUrl':
'LLM API base URL。Azure v1:https://{resource}.openai.azure.com/openai/v1',
@ -273,10 +273,9 @@ export const zhCN = {
'同时下载 CUDA GPU 二进制文件(运行 onnxruntime-node 的 NuGet postinstall;代理后请设置 GLOBAL_AGENT_HTTPS_PROXY)',
'help.option.embeddings.install.force': '即使嵌入组件已可解析,也强制安装到运行时目录',
'help.option.group.create.force': '覆盖现有仓库组',
'help.option.group.sync.skipEmbeddings': '仅使用 exact + BM25(不使用嵌入回退)',
'help.option.group.sync.exactOnly': '仅精确匹配',
'help.option.group.sync.allowStale': '跳过过期索引警告',
'help.option.group.sync.verbose': '显示每条跨仓库链接详情',
'help.option.group.sync.exactOnly':
'跳过通配符服务匹配,仅按契约 ID 精确匹配建立跨仓链接(清单声明的链接仍然生效)',
'help.option.group.sync.verbose': '显示额外的同步诊断信息',
'help.option.status.json': '输出机器可读的索引和分析器来源信息',
'help.option.json': 'JSON 输出',
'help.option.group.impact.target': '要分析的符号或文件名',

View file

@ -303,7 +303,7 @@ program
.option('-f, --force', 'Force full regeneration even if up to date')
.option(
'--provider <provider>',
'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: minimax)',
'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)',
)
.option('--model <model>', 'LLM model or deployment name (default: MiniMax-M3)')
.option(

View file

@ -25,6 +25,7 @@ import {
type LLMProvider,
} from '../core/wiki/llm-client.js';
import { detectCursorCLI } from '../core/wiki/cursor-client.js';
import { detectGrokCLI } from '../core/wiki/grok-client.js';
import { detectLocalCLI } from '../core/wiki/local-cli-client.js';
import { logger } from '../core/logger.js';
@ -65,20 +66,22 @@ function parsePositiveIntegerOption(
function isLocalProvider(
provider: LLMProvider | undefined,
): provider is 'cursor' | 'claude' | 'codex' | 'opencode' {
): provider is 'cursor' | 'claude' | 'codex' | 'opencode' | 'grok' {
return (
provider === 'cursor' ||
provider === 'claude' ||
provider === 'codex' ||
provider === 'opencode'
provider === 'opencode' ||
provider === 'grok'
);
}
function localModelConfigKey(provider: 'cursor' | 'claude' | 'codex' | 'opencode') {
function localModelConfigKey(provider: 'cursor' | 'claude' | 'codex' | 'opencode' | 'grok') {
if (provider === 'cursor') return 'cursorModel';
if (provider === 'claude') return 'claudeModel';
if (provider === 'codex') return 'codexModel';
if (provider === 'opencode') return 'opencodeModel';
if (provider === 'grok') return 'grokModel';
throw new Error(`Unsupported local provider: ${provider satisfies never}`);
}
@ -287,7 +290,9 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
if (!llmConfig.apiKey && !isLocalProvider(llmConfig.provider)) {
console.log(' Error: No LLM API key found.');
console.log(' Set MINIMAX_API_KEY, GITNEXUS_API_KEY, or OPENAI_API_KEY,');
console.log(' or pass --api-key <key>, or use --provider cursor|claude|codex|opencode.\n');
console.log(
' or pass --api-key <key>, or use --provider cursor|claude|codex|opencode|grok.\n',
);
process.exitCode = 1;
return;
}
@ -301,9 +306,10 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
const hasClaude = detectLocalCLI('claude');
const hasCodex = detectLocalCLI('codex');
const hasOpenCode = detectLocalCLI('opencode');
const hasGrok = detectGrokCLI();
const localChoices: Array<{
choice: string;
provider: 'cursor' | 'claude' | 'codex' | 'opencode';
provider: 'cursor' | 'claude' | 'codex' | 'opencode' | 'grok';
}> = [];
// Provider selection
@ -346,6 +352,14 @@ const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions)
});
console.log(` [${choice}] OpenCode CLI (local, uses your OpenCode login/config)`);
}
if (hasGrok) {
const choice = String(nextChoice++);
localChoices.push({
choice,
provider: 'grok',
});
console.log(` [${choice}] Grok CLI (local, uses your Grok Build login)`);
}
console.log('');
const maxChoice = String(nextChoice - 1);

View file

@ -1,4 +1,5 @@
import ignore, { type Ignore } from 'ignore';
import { existsSync } from 'fs';
import fs from 'fs/promises';
import nodePath from 'path';
import type { Path } from 'path-scurry';
@ -31,12 +32,15 @@ const DEFAULT_IGNORE_LIST = new Set([
// 'packages' removed - commonly used for monorepo source code (lerna, pnpm, yarn workspaces)
'venv',
'.venv',
'env',
'.env',
// Bare `env/` can be application source or a Python virtual environment.
// Path-aware rules below prune it at the root and wherever pyvenv.cfg marks
// a virtual environment, while preserving ordinary nested source folders.
'__pycache__',
'.pytest_cache',
'.mypy_cache',
'site-packages',
'dist-packages',
'.tox',
'eggs',
'.eggs',
@ -54,13 +58,33 @@ const DEFAULT_IGNORE_LIST = new Set([
'obj',
'target', // Java/Rust
'.next',
// `.next` is Next.js's build CACHE; `_next` is the EMITTED output, and the two
// are different directories. A Capacitor/Cordova shell copies the emitted
// bundle to `<platform>/app/src/main/assets/public/_next/static/…`, where none
// of the path segments hit this list — so a mobile-wrapped Next.js app had its
// shipped bundle indexed as source, and every Route node it produced pointed at
// a webpack chunk rather than code anyone wrote (#3007).
//
// The name is deliberately unanchored. No `<web-root>/_next` form matches a
// root-level `_next/static/…`, which is the shape the reported repo has, so
// anchoring it would miss the case it was added for. The accepted cost is a
// hand-written directory literally named `_next`; recover one with a bare
// `!_next/` line in `.gitnexusignore`.
'_next',
'.nuxt',
'.output',
'.vercel',
'.netlify',
'.serverless',
'_build',
'public/build',
// `'public/build'` used to sit here. This set is tested one path SEGMENT at a
// time, and `isHardcodedIgnoredDirectory(name)` takes a bare directory name,
// so a slash-containing member could never match either — it was inert. Its
// paths were never unignored though: bare `'build'` above already prunes
// `public/build/**`, so removing the entry changes no behavior (#3007).
// `test/unit/ignore-build-output.test.ts` keeps the next slash-bearing entry
// in this set — or in IGNORED_FILES, ROOT_ARTIFACT_DIRECTORIES or
// IGNORED_EXTENSIONS — from dying the same way.
'.parcel-cache',
'.turbo',
'.svelte-kit',
@ -86,11 +110,11 @@ const DEFAULT_IGNORE_LIST = new Set([
// Generated/Compiled
'.generated',
'generated',
'auto-generated',
// Bare `generated/` can contain tracked source-of-truth code. Build output
// remains covered by .gitignore/.gitnexusignore and the unambiguous names.
'monaco-workers', // Monaco editor web-worker bundles generated for browser runtime
'.terraform',
'.serverless',
// Documentation (optional - might want to keep)
// 'docs',
@ -106,6 +130,14 @@ const DEFAULT_IGNORE_LIST = new Set([
'__snapshots__',
]);
// Ambiguous names that conventionally denote generated artifacts only at the
// repository root. Nested directories with these names are frequently source
// modules (for example apps/web/src/env or packages/api/generated).
const ROOT_ARTIFACT_DIRECTORIES = new Set(['env', 'generated']);
const isRootArtifactDirectory = (relativePath: string, name: string): boolean =>
!relativePath.includes('/') && ROOT_ARTIFACT_DIRECTORIES.has(name);
const IGNORED_EXTENSIONS = new Set([
// Images
'.png',
@ -290,6 +322,10 @@ export const shouldIgnorePath = (filePath: string): boolean => {
const fileName = parts[parts.length - 1];
const fileNameLower = fileName.toLowerCase();
if (parts.length > 0 && isRootArtifactDirectory(parts[0], parts[0])) {
return true;
}
// Laravel compiles Blade templates into generated PHP cache files under
// storage/framework/views. Source templates live in resources/views and are
// handled separately; compiled cache should not become source-of-truth. Keep
@ -329,10 +365,8 @@ export const shouldIgnorePath = (filePath: string): boolean => {
if (
fileNameLower.includes('.bundle.') ||
fileNameLower.includes('.chunk.') ||
fileNameLower.includes('.generated.') ||
fileNameLower.endsWith('.d.ts')
fileNameLower.includes('.generated.')
) {
// TypeScript declaration files
return true;
}
@ -344,6 +378,20 @@ export const isHardcodedIgnoredDirectory = (name: string): boolean => {
return DEFAULT_IGNORE_LIST.has(name);
};
/** Apply directory ignore rules that depend on repository-relative depth. */
export const isHardcodedIgnoredDirectoryAtPath = (
repoRoot: string,
directoryPath: string,
): boolean => {
const name = nodePath.basename(directoryPath);
if (isHardcodedIgnoredDirectory(name)) return true;
const relative = nodePath.relative(repoRoot, directoryPath).replace(/\\/g, '/');
if (isRootArtifactDirectory(relative, name)) return true;
return name === 'env' && existsSync(nodePath.join(directoryPath, 'pyvenv.cfg'));
};
/**
* Load .gitignore and .gitnexusignore rules from the repo root.
* Returns an `ignore` instance with all patterns, or null if no files found.
@ -496,8 +544,10 @@ export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptio
// last-match-wins: `!__tests__/` + `__tests__/generated/` still
// blocks descent into `__tests__/generated/`.
if (ig && rel && hasExplicitUnignore(ig, rel) && !ig.ignores(rel + '/')) return false;
// Hardcoded list: block descent into well-known noise directories.
if (DEFAULT_IGNORE_LIST.has(p.name)) return true;
// Hardcoded and path-aware rules prune whole trees before glob walks them.
if (rel && isHardcodedIgnoredDirectoryAtPath(repoPath, nodePath.join(repoPath, rel))) {
return true;
}
// Check against .gitignore / .gitnexusignore patterns.
// Since childrenIgnored is only called for directories, always test with
// a trailing slash. This ensures directory-only negation patterns (e.g.

View file

@ -16,10 +16,12 @@ flowchart TD
D --> E1[TopicExtractor]
D --> E2[HttpRouteExtractor]
D --> E3[GrpcExtractor]
D --> E4[GraphqlExtractor]
E1 --> F[ExtractedContract array<br/>per repo]
E2 --> F
E3 --> F
E4 --> F
B --> M[ManifestExtractor]
M --> G[Manifest contracts<br/>+ cross-links]
@ -59,14 +61,27 @@ flowchart TD
**Strategy A** (graph-assisted) uses Cypher over edges already produced
by the main ingestion pipeline:
- HTTP: `HANDLES_ROUTE` / `FETCHES` edges from `(File)-[]->(Route)`
- topic: none (pipeline doesn't yet produce topic nodes — Strategy B only)
- gRPC: none (Strategy B + proto map only)
**Strategy B** (source-scan) is 100% tree-sitter based after this PR.
**Strategy B** (source-scan) uses tree-sitter for language source and the
official GraphQL parser for `.graphql` / `.gql` operation documents.
Each `*-patterns/<lang>.ts` plugin owns its grammar + S-expression
queries; the top-level orchestrator imports neither.
GraphQL detection is opt-in with `detect.graphql: true`. The initial slice
recognizes imported NestJS `Query`, `Mutation`, and `Subscription` decorators on
top-level imported `Resolver` classes, plus named operation documents. Generated
object documents, static `gql` templates, and `TypedDocumentString` values are
verified against the operation and its resolved root fragments. Providers and
consumers must resolve to one exact, real graph symbol; anonymous operations,
dynamic decorator names, ambiguous generated symbols, malformed documents,
symlink escapes, and bounded-parser overflows are skipped rather than linked
approximately. `matching.exclude_links_paths` also suppresses configured GraphQL
root fields from exact cross-linking while retaining their registry entries.
## Plugin architecture
```mermaid
@ -117,6 +132,7 @@ They use the `MATCH (n) WHERE labels(n) IN [...]` allowlist form, NOT the
`MATCH (n:A|B)` disjunction — LadybugDB's parser rejects a disjunction that
names a reserved keyword (e.g. `Macro`, `Union`), which is what broke the
`custom` branch in #2325:
- `topic` → `labels(n) IN ['Function','Method','Class','Interface']`
- `grpc`/`thrift` method → `labels(n) IN ['Function','Method']`, service → `labels(n) IN ['Class','Interface']`
- `lib` → `labels(n) IN ['Module']`
@ -144,7 +160,7 @@ without coordinating through any shared state.
## Cross-repo trace (`cross-trace.ts`)
A second consumer of the bridge. Where cross-impact fans a blast radius
*outward* from one symbol, cross-trace stitches a directed **path** between
_outward_ from one symbol, cross-trace stitches a directed **path** between
two symbols that live in different repos:
```mermaid
@ -158,7 +174,7 @@ flowchart TD
```
It reuses the same `symbolUid` join as cross-impact, but issues its own
*pair* query (`listCrossingsBetween`) because a path needs BOTH endpoints of
_pair_ query (`listCrossingsBetween`) because a path needs BOTH endpoints of
a crossing — the uid-filtered neighbor join (`resolveBridgeNeighbors`, shared
with impact) returns only the far side. The crossing is clamped to one
boundary (`MAX_SUPPORTED_CROSS_DEPTH`). With `pdg: true` the boundary-adjacent

View file

@ -3,14 +3,23 @@ import path from 'node:path';
import { createHash } from 'node:crypto';
import lbug from '@ladybugdb/core';
import type { LbugValue } from '@ladybugdb/core';
import type { BridgeHandle, BridgeMeta, StoredContract, CrossLink, RepoSnapshot } from './types.js';
import type {
BridgeHandle,
BridgeMeta,
StoredContract,
CrossLink,
RepoSnapshot,
MatchType,
} from './types.js';
import { BRIDGE_SCHEMA_QUERIES, BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
import { recordedMatchStages, recordedRepoList } from './completeness.js';
import {
closeLbugConnection,
openLbugConnection,
type LbugConnectionHandle,
} from '../lbug/lbug-config.js';
import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
import { withGroupSyncLock } from './group-lock.js';
import { createLogger } from '../logger.js';
import { retryRename, writeFileAtomic } from '../../storage/fs-atomic.js';
@ -647,15 +656,347 @@ export async function closeBridgeDb(handle: BridgeHandle): Promise<void> {
/* ------------------------------------------------------------------ */
export async function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void> {
await writeFileAtomic(path.join(groupDir, 'meta.json'), JSON.stringify(meta, null, 2));
// Strip the reader-only fields HERE rather than at each writer. `readBridgeMeta`
// sets both on what it returns, so any caller that reads-modifies-writes would
// round-trip them to disk — and `pairedWithDatabase` is the poisonous one:
// persisted, it tells every future reader the pair was verified when nothing
// verified it. That rule used to live in the body of the only such caller,
// which held exactly as long as there was one. There are now three writers and
// two of them read first. Enforced at the boundary, no writer can get it wrong.
const { repoListsUnreadable: _reader1, pairedWithDatabase: _reader2, ...persisted } = meta;
await writeFileAtomic(path.join(groupDir, 'meta.json'), JSON.stringify(persisted, null, 2));
}
/**
* Does `meta` still describe the `bridge.lbug` sitting next to it?
*
* `writeBridge` stamps the database's size and mtime into the metadata it
* writes, so a metadata file left over from an earlier sync cannot match a
* database that was replaced after it. Callers whose answer depends on the
* metadata being true of THIS database (cross-repo impact reads completeness
* from it) must not treat a mismatch as fact.
*
* When BOTH halves of the stamp are absent the metadata predates stamping, and
* it is judged on the write order of the two files instead — see
* {@link unstampedMetaPairsByWriteOrder}. Failing every unstamped metadata
* closed would mark all pre-existing bridges as incomplete until re-synced,
* trading a narrow window for a repo-wide regression; accepting them all hands
* back "verified" for the very window this pairing exists to catch.
*
* A stamp is a PAIR, so exactly one half present is rejected rather than waved
* through. That is not the legacy shape: something wrote a stamp and did not
* finish, which is the very condition stamping was added to detect. Joining the
* two `undefined` checks with `||` returned "verified" for precisely the shape
* that most deserves suspicion.
*
* Returns `false` when the database itself cannot be stat'd, on either path,
* since metadata describing a file that is not there describes nothing.
*
* The checks are ORDERED by how strong their evidence is, strongest first, and
* each later one is reached only because every earlier one had nothing to say.
* `provenanceUnknown` therefore comes first: a metadata file whose own writer
* says it cannot vouch for the database beside it has settled the question, and
* neither the stamp nor the write-order heuristic may overturn that.
*
* The marker is not decoration. `refreshPreservedBridgeMeta` rewrites this file
* atomically without touching the database, which leaves `meta.mtime` newer —
* the write order a paired write produces, and the one the unstamped branch
* ACCEPTS. Reading the marker after that branch (or not at all) hands back
* "verified" for a pair the same code path had just found broken.
*/
export async function bridgeMetaMatchesFile(groupDir: string, meta: BridgeMeta): Promise<boolean> {
if (meta.provenanceUnknown) return false;
const stampedSize = meta.bridgeSize !== undefined;
const stampedMtime = meta.bridgeMtimeMs !== undefined;
if (!stampedSize && !stampedMtime) return unstampedMetaPairsByWriteOrder(groupDir);
if (!stampedSize || !stampedMtime) return false;
try {
const stat = await fsp.stat(path.join(groupDir, 'bridge.lbug'));
return stat.size === meta.bridgeSize && stat.mtimeMs === meta.bridgeMtimeMs;
} catch {
return false;
}
}
/**
* Could the unstamped `meta.json` plausibly have been written by the sync that
* put this `bridge.lbug` beside it?
*
* `writeBridge` renames the database into place and writes the metadata AFTER,
* so `meta.mtime >= db.mtime` holds for any pair written together — including
* pairs written by builds from before the stamp existed, which is what makes
* this usable as back-compat rather than a repo-wide "re-sync everything".
* The only way to reach a database strictly NEWER than the metadata beside it
* is a swap whose metadata write did not land: the stale-meta-beside-a-new-
* database window, whose completeness `runGroupImpact` would otherwise spend as
* fact.
*
* This is a HEURISTIC ON WRITE ORDER, not proof of provenance. It answers "were
* these two written in the order a successful sync writes them?", and treats
* that as a proxy for "do these two belong together". It is wrong in two
* directions, and neither is theoretical:
* - FALSE ACCEPT, from a non-monotonic wall clock. `mtimeMs` is realtime, not
* monotonic, so an NTP step backwards, a VM snapshot restore or container
* clock skew between the database write and the metadata write can leave a
* genuinely mis-paired set reading as ordered. Anything that touches the
* stale metadata after a swap does the same — a restore from backup, an
* editor save, a copy that preserves only the database's times. The STAMP
* is what actually closes this; a pair that has one never reaches here.
*
* Coarse filesystem mtime granularity is NOT this hazard, despite looking
* like it: it collapses a pair written together to equal times, and equal
* is accepted, which is the correct verdict for that pair.
*
* - FALSE REJECT, from anything that rewrites the database's mtime after the
* metadata's — `cp -r`, `rsync` without `-t`, a machine move, a restore
* that replays files in directory order. An intact legacy pair is then
* demoted to a lower bound and stays there until the next successful sync
* re-stamps it; there is no other recovery, because nothing on the read
* path can distinguish it from the swap window it is imitating.
*
* This direction is the safe one — it degrades an answer to a floor rather
* than vouching for one — but it is a real, reachable cost, not a
* theoretical one, and it is NOT true that the rule can only ever demote
* pairs that were already broken.
*
* Equality counts as paired. On a filesystem with coarse mtime granularity both
* writes land in the same tick, and demanding a strictly newer metadata file
* would reject every legacy bridge there for a reason that is about the
* filesystem rather than about the bridge.
*
* A timestamp that cannot be measured is no match, the same convention the
* read-only handle cache applies to a bridge it could not stat: a comparison
* that could not be made is not a comparison that succeeded.
*/
async function unstampedMetaPairsByWriteOrder(groupDir: string): Promise<boolean> {
try {
const [dbStat, metaStat] = await Promise.all([
fsp.stat(path.join(groupDir, 'bridge.lbug')),
fsp.stat(path.join(groupDir, 'meta.json')),
]);
return metaStat.mtimeMs >= dbStat.mtimeMs;
} catch {
return false;
}
}
/**
* Read `meta.json`, validating the SHAPE of what it holds.
*
* The read and the parse have always been guarded — an absent or unparseable
* file answers `version: 0`, which every caller already treats as "no
* provenance". What was not guarded is a file that parses into something that
* is not this shape: `runGroupImpact` spread both repo lists directly into a
* `Set`, so a non-iterable there threw a TypeError out of the whole cross-repo
* query, from a point where the bridge lease had been taken and not yet
* released. A malformed file is a reason to answer "provenance unknown", never
* a reason to crash the question.
*/
export async function readBridgeMeta(groupDir: string): Promise<BridgeMeta> {
const unreadable: BridgeMeta = { version: 0, generatedAt: '', missingRepos: [] };
let parsed: unknown;
try {
const content = await fsp.readFile(path.join(groupDir, 'meta.json'), 'utf-8');
return JSON.parse(content) as BridgeMeta;
parsed = JSON.parse(content);
} catch {
return { version: 0, generatedAt: '', missingRepos: [] };
return unreadable;
}
// `JSON.parse` succeeds on `null`, `7` and `[]` too, and none of them are
// metadata. Reading `.version` off the first of those is a thrown TypeError;
// reading it off the others silently yields `undefined`, which passes the
// version gate as if the bridge had been vouched for.
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return unreadable;
const raw = parsed as Partial<BridgeMeta>;
const missingRepos = recordedRepoList(raw.missingRepos);
const unreadableRepos = recordedRepoList(raw.unreadableRepos);
// Each list is judged on its own: a file whose `unreadableRepos` is garbage
// can still carry a `missingRepos` that was genuinely measured, and throwing
// that away would turn one unknown into two.
const repoListsUnreadable =
(raw.missingRepos !== undefined && missingRepos === undefined) ||
(raw.unreadableRepos !== undefined && unreadableRepos === undefined);
const meta: BridgeMeta = {
...raw,
// A version that is not a number cannot be compared against
// BRIDGE_SCHEMA_VERSION; `0` is this file's existing word for "provenance
// unknown", which is exactly what such a file gives us.
// `0` is this file's word for "no provenance". A version that is not a
// positive integer is not a schema version, and letting one through splits
// the four gates that read this field: `ensureBridgeReady` and
// `openBridgeDbReadOnly` both compare `> 0 && !== CURRENT` and would open
// the bridge, `bridgeExists` compares `=== 0 || === CURRENT` and would say
// it is not there, and `bridgeProvenanceUnknown` compares `=== 0` and would
// call the answer complete. Normalizing here keeps all four agreeing
// instead of teaching each one the same new case.
version:
Number.isInteger(raw.version) && (raw.version as number) > 0 ? (raw.version as number) : 0,
generatedAt: typeof raw.generatedAt === 'string' ? raw.generatedAt : '',
missingRepos: missingRepos ?? [],
};
// Absent, not empty. `unreadableRepos` is optional and "not recorded" is a
// distinct state from "measured none", so an unusable value is dropped rather
// than carried through — `repoListsUnreadable` is what records that something
// was there and could not be read.
if (unreadableRepos) meta.unreadableRepos = unreadableRepos;
else delete meta.unreadableRepos;
// Same absent-vs-empty rule, through the one shared reader.
const suppressed = recordedMatchStages(raw.suppressedMatchStages);
if (suppressed) meta.suppressedMatchStages = suppressed;
else delete meta.suppressedMatchStages;
if (repoListsUnreadable) meta.repoListsUnreadable = true;
return meta;
}
/* ------------------------------------------------------------------ */
/* refreshPreservedBridgeMeta */
/* ------------------------------------------------------------------ */
/**
* What a refresh did to `meta.json`.
*
* - `restamped` — the pair still matched, so the lists were refreshed
* and the stamp re-taken from the database on disk.
* - `provenance-unknown` — the pair did NOT match (or there is no database to
* match), so the lists were refreshed and the metadata
* marked as unable to vouch for the file beside it.
* - `no-bridge` — neither `meta.json` nor `bridge.lbug` exists, so
* there is no pair to keep honest and nothing written.
*/
export type PreservedBridgeMetaOutcome = 'restamped' | 'provenance-unknown' | 'no-bridge';
async function fileExists(filePath: string): Promise<boolean> {
try {
await fsp.access(filePath);
return true;
} catch {
return false;
}
}
/**
* Bring `meta.json`'s diagnostic lists up to date with a sync that PRESERVED
* the bridge instead of rebuilding it, without ever making the metadata claim
* more about the database than it did before.
*
* `syncGroup`'s total-failure path keeps the previous run's contracts and
* deliberately leaves `bridge.lbug` alone — the contracts that bridge holds are
* the ones being preserved. But `runGroupImpact` reads completeness from
* `meta.json`, not from `contracts.json`, so leaving the metadata alone too left
* the two files telling different stories: the registry said "this sync could
* not read svc/users" while a cross-repo query answered "complete, nothing
* depends on this" (R4/R6).
*
* The refresh is the whole difficulty. It rewrites `meta.json` atomically, so
* the file's mtime becomes now while the database's stays old — which is the
* write order a paired write produces, and precisely what
* `unstampedMetaPairsByWriteOrder` accepts. Three rules follow, and each of them
* is load-bearing:
*
* 1. Ask `bridgeMetaMatchesFile` FIRST, on the file as it stands. After the
* write the question is unanswerable, because the write is what destroys
* the evidence.
* 2. Re-stamp only when that answer was yes. Re-stamping a pair that already
* failed would MANUFACTURE the provenance the failure just denied — the
* same metadata/database mis-pairing stamping exists to prevent (KTD6).
* 3. When it was no, record `provenanceUnknown` explicitly and carry the
* existing stamp fields through verbatim. Writing "no stamp" instead is
* worse, not better: an unstamped file is judged on the two file times,
* and this write has just put them in the accepting order.
*
* Nothing here opens, reads, or writes the database. The only `stat` of it
* happens on the branch where the pair was just verified.
*
* NOT SPLIT into locked/unlocked halves the way {@link writeBridge} is, and
* deliberately. Its one caller is `syncGroup`'s preserve branch, which is
* already inside `withGroupSyncLock` — so this write is ALREADY serialized
* against every other sync of the group, and taking the lock here would be the
* second acquisition of a non-reentrant primitive that the split exists to
* avoid. An acquiring wrapper would therefore have zero production callers,
* and no test calls this function at all: it would be dead code standing in for
* a guarantee the caller already provides. If a caller outside the critical
* section ever appears, it needs the same treatment `writeBridge` got — a
* wrapper, not a lock moved down here.
*/
export async function refreshPreservedBridgeMeta(
groupDir: string,
// Deliberately NOT `suppressedMatchStages`. This path preserves an EARLIER
// sync's database, so stamping it with this run's request would claim the
// untouched bridge was built with a flag it never saw. The registry's own
// preserve write (`{ ...prior, missingRepos, unreadableRepos }`) omits it for
// exactly this reason, and the two artifacts have to agree about which run
// they describe.
diagnostics: { missingRepos: string[]; unreadableRepos: string[] },
): Promise<PreservedBridgeMetaOutcome> {
const dbPath = path.join(groupDir, 'bridge.lbug');
const [metaOnDisk, dbOnDisk] = await Promise.all([
fileExists(path.join(groupDir, 'meta.json')),
fileExists(dbPath),
]);
// Nothing on either side of the pair. `readBridgeMeta` already answers
// `version: 0` — provenance unknown — for an absent file, so a file written
// here would say what the absence already says while inventing state for a
// bridge that has never existed.
if (!metaOnDisk && !dbOnDisk) return 'no-bridge';
const existing = await readBridgeMeta(groupDir);
const paired = await bridgeMetaMatchesFile(groupDir, existing);
const refreshed: BridgeMeta = { ...existing, ...diagnostics };
// NEVER PERSISTED (see `BridgeMeta`): both are things a READER computes ABOUT
// a file, and this is the first code in the repo that reads metadata and
// writes it back. The strip itself now lives in `writeBridgeMeta`, so every
// writer inherits it rather than each remembering.
if (paired) {
const stat = await fsp.stat(dbPath).catch(() => null);
if (stat) {
refreshed.bridgeSize = stat.size;
refreshed.bridgeMtimeMs = stat.mtimeMs;
await writeBridgeMeta(groupDir, refreshed);
return 'restamped';
}
// The database disappeared between the pairing check and this stat. There
// is nothing left to stamp, so fall through and say so rather than write a
// stamp describing a file that is gone.
}
refreshed.provenanceUnknown = true;
await writeBridgeMeta(groupDir, refreshed);
return 'provenance-unknown';
}
/**
* Withdraw the bridge's claim to be complete, without touching the database.
*
* The one path this exists for: `contracts.json` committed, then the bridge
* replacement failed. The old database is still physically usable and still
* answers queries, but it now describes an EARLIER sync than the canonical
* registry beside it — so `group_contracts` can report a narrowed or advanced
* contract set while `group_impact` traverses the old graph and calls its
* answer complete. Two public surfaces, contradictory epistemic claims, from
* one sync.
*
* Setting `provenanceUnknown` is the smallest thing that makes that safe:
* `bridgeMetaMatchesFile` gives it highest precedence and refuses to vouch for
* the pair, so every cross-repo answer downgrades to a floor until a sync
* succeeds. Deliberately NOT a re-stamp — the metadata still describes the
* database it was written for, and claiming otherwise is the mis-pairing the
* preserve path is careful to avoid. Deliberately not a delete either: the
* previous graph is better than nothing as long as nobody calls it complete.
*
* Best-effort by construction. It runs inside a failure handler, so a throw
* here would replace a reported bridge failure with an unrelated one.
*/
export async function markBridgeProvenanceUnknown(groupDir: string): Promise<boolean> {
try {
const existing = await readBridgeMeta(groupDir);
if (existing.version === 0) return false;
await writeBridgeMeta(groupDir, { ...existing, provenanceUnknown: true });
return true;
} catch {
return false;
}
}
@ -668,6 +1009,29 @@ export interface WriteBridgeInput {
crossLinks: CrossLink[];
repoSnapshots: Record<string, RepoSnapshot>;
missingRepos: string[];
/**
* Repos this sync could not extract from — see
* `ContractRegistry.unreadableRepos` for the full definition, which this
* field carries unchanged.
*
* Deliberately not restated here. The narrower wording this once had ("whose
* index could not be opened") described one of the two causes and silently
* excluded the other, an extractor that threw partway through — so the same
* field meant one thing on the registry, another on the bridge input, and a
* third on the result. One definition, referenced twice, cannot drift.
*
* Recorded in meta.json so cross-repo impact can tell "nothing depends on
* this" from "we could not look": the bridge built here is missing every
* contract those repos own.
*/
unreadableRepos?: string[];
/**
* Matching stages the sync was asked to skip. Recorded here for the same
* reason `unreadableRepos` is: a later cross-repo query reads this bridge
* with no access to the run that built it, and a graph narrowed by request
* looks exactly like a complete one.
*/
suppressedMatchStages?: MatchType[];
}
/**
@ -702,7 +1066,33 @@ function errMessage(err: unknown): string {
}
}
export async function writeBridge(
/**
* Rebuild `bridge.lbug` and its `meta.json`, ASSUMING THE CALLER ALREADY HOLDS
* THE GROUP SYNC LOCK for `groupDir` (R9).
*
* PRECONDITION — the group lock is held. There is exactly one production call
* site, `syncGroup` in sync.ts, and it is already inside
* `withGroupSyncLock(groupDir, …)` when it gets here. Enforced by this comment
* rather than by a type, matching `registerRepoUnlocked` / `withRegistryLock`
* in repo-manager.ts, which splits the same shape for the same reason.
*
* WHY THE SPLIT EXISTS AT ALL. The swap this function performs — old database
* aside, temp database into place, then `meta.json` written as a SECOND
* operation — is the write two concurrent syncs can interleave into a pairing
* that never existed: one sync's metadata beside the other's database. That
* needs mutual exclusion. But taking the lock HERE would be a second
* acquisition of a non-reentrant primitive inside a region that already holds
* it, and it would hang every single sync on the happy path, not some rare
* interleave. So the exclusion is the caller's, and this function only states
* the precondition. {@link writeBridge} is the acquiring wrapper for callers
* who are not already inside that region.
*
* SCOPE — writer-writer only. The reader-side promotion of a leftover
* `bridge.lbug.bak` runs on ordinary reads, outside anybody's critical section;
* `bridgeMetaMatchesFile` remains the reader's defense there and is not
* replaced by this lock.
*/
export async function writeBridgeUnlocked(
groupDir: string,
input: WriteBridgeInput,
): Promise<WriteBridgeReport> {
@ -962,11 +1352,42 @@ export async function writeBridge(
}
await removeLbugFile(bakPath);
// 4. Write meta.json
// 4. Write the new meta.json, STAMPED WITH THE FILE IT DESCRIBES.
//
// meta.json carries the bridge's completeness, and since #3011 that is
// load-bearing: `runGroupImpact` folds `unreadableRepos ∪ missingRepos`
// into its truncation fields. The swap above and this write are two
// operations, so a sync that stops between them leaves the previous sync's
// meta beside a new database — and reading that as fact is a confidently
// wrong answer about the one thing this channel exists to make legible.
//
// Deleting the old meta before the swap would decide which way that window
// fails, but at an unacceptable price: the rename of the old database is
// wrapped in a catch that also swallows a FAILED rename (a held read-only
// handle does this on Windows), so `writeBridge` can throw with the old,
// perfectly good database still in place — and its metadata already gone,
// unrecoverably, for as long as the swap keeps failing.
//
// So destroy nothing and pair the two instead: record the size and mtime of
// the database this metadata describes, and let readers check that the pair
// still belongs together (`bridgeMetaMatchesFile`). A stale meta cannot match
// a freshly renamed database, and a sync that fails before the swap leaves a
// matching pair untouched.
const finalStat = await fsp.stat(finalPath);
await writeBridgeMeta(groupDir, {
version: BRIDGE_SCHEMA_VERSION,
generatedAt: new Date().toISOString(),
bridgeSize: finalStat.size,
bridgeMtimeMs: finalStat.mtimeMs,
missingRepos: input.missingRepos,
// Persisted whenever the caller supplied it, `[]` included: an empty list
// is the measurement "this sync accounted for every repo", and it is a
// different claim from a bridge that never recorded the field. Omitted
// only when the caller passed nothing to record.
...(input.unreadableRepos ? { unreadableRepos: input.unreadableRepos } : {}),
...(input.suppressedMatchStages
? { suppressedMatchStages: input.suppressedMatchStages }
: {}),
});
return report;
@ -982,6 +1403,33 @@ export async function writeBridge(
}
}
/**
* Rebuild `bridge.lbug` and its `meta.json` as the only writer of `groupDir`.
*
* The acquiring half of the split described on {@link writeBridgeUnlocked}: for
* callers that are NOT already inside the group's critical section, this takes
* the group sync lock around the whole swap and releases it afterwards. Two
* concurrent calls therefore run one after the other, so the `meta.json` left
* on disk is stamped for the `bridge.lbug` left on disk instead of for the
* loser's, which is the pairing the swap-plus-metadata sequence would otherwise
* let them interleave into.
*
* NOT used by `syncGroup`, and it must not be: that path already holds this
* lock, and `acquireIndexLock` is not reentrant, so routing it here would make
* every ordinary sync wait out the full `GROUP_SYNC_LOCK_TIMEOUT_MS` ceiling
* against itself. It calls {@link writeBridgeUnlocked} directly.
*
* Fails closed exactly as `withGroupSyncLock` does: if the lock cannot be
* acquired, a `GroupSyncLockError` is thrown and NOTHING is written —
* `bridge.lbug` and `meta.json` are left as they were.
*/
export async function writeBridge(
groupDir: string,
input: WriteBridgeInput,
): Promise<WriteBridgeReport> {
return withGroupSyncLock(groupDir, () => writeBridgeUnlocked(groupDir, input));
}
/* ------------------------------------------------------------------ */
/* openBridgeDbReadOnly */
/* ------------------------------------------------------------------ */

View file

@ -0,0 +1,169 @@
/**
* The one computation of "is this cross-repo answer complete?" (KTD10), and the
* truncation vocabulary it speaks.
*
* A LEAF MODULE, deliberately, and that is the whole reason it exists apart from
* `cross-impact.ts`. Three surfaces need this fold — impact, trace, and the
* contract listing — but `cross-impact.ts` statically imports `bridge-db.ts`,
* and through it the native LadybugDB binding. `service.ts` therefore had to
* reach the fold through `await import('./cross-impact.js')`, which loaded that
* entire module graph on the first `group_contracts` of every process — 44-51ms
* and 8.4MB of RSS to run a `Set` union and a ternary, once per CLI invocation.
*
* Nothing here imports anything but types. Keep it that way: the moment this
* file gains a runtime import, every consumer pays for it again.
*/
import type { GroupImpactTruncationReason, MatchType } from './types.js';
/**
* A union rather than `Pick<GroupImpactResult, ...>` so the two states are
* distinguishable by their `truncated` discriminant: a caller that folds these
* fields into its own result (see `crossRepoCompleteness`) can then read
* `truncationReason` on the truncated branch without a fallback for a value
* that cannot be absent there.
*/
export type TruncationFields =
| { truncated: false }
| {
truncated: true;
truncationReason: GroupImpactTruncationReason;
riskEpistemic: 'lower-bound';
};
/**
* Build the truncation fields every `runGroupImpact` return path shares.
*
* `riskEpistemic` must follow `truncated` mechanically: it is the marker that
* tells a caller the `risk` value is a floor rather than a verdict, and
* `mergeRisk` can only under-report once a crossing is dropped. Attaching it at
* each return let two of the four paths set `truncated` without it, so a
* truncated result read as complete — deriving it in one place is what keeps
* the invariant from drifting again (#2787).
*/
export function truncationFields(
truncated: boolean,
// Only read on the truncated branch, so the not-truncated call sites omit it
// rather than passing a reason that is thrown away.
reasonIfTruncated: GroupImpactTruncationReason = 'partial',
): TruncationFields {
if (!truncated) return { truncated: false };
return { truncated: true, truncationReason: reasonIfTruncated, riskEpistemic: 'lower-bound' };
}
/**
* Everything a caller needs in order to say whether a cross-repo answer is
* complete — deliberately WITHOUT naming where any of it came from.
*
* `BridgeMeta` is not in this signature, and must not be: `groupContracts`
* answers the same question from `contracts.json` (via
* `loadContractRegistryResilient`) and never opens a bridge at all, so
* `version` / `repoListsUnreadable` / `pairedWithDatabase` do not exist on that
* path. Each caller computes its own `provenanceUnknown` from whatever
* provenance IT has and passes the boolean in.
*/
export interface CrossRepoCompletenessInput {
/**
* Repos the sync could not extract from, and repos it found no entry for.
* Two independent diagnostics with one consequence — none of those repos'
* contracts are in the artifact — so they are folded into one set.
*/
unreadableRepos?: readonly string[];
missingRepos?: readonly string[];
/**
* Matching stages the sync was asked to skip. Absent or empty means it
* suppressed none; a populated list makes the answer a floor for a reason
* that is neither a runtime limit nor an unreadable repo.
*/
suppressedMatchStages?: readonly string[];
/** Computed by the caller; see `bridgeProvenanceUnknown` for the bridge one. */
provenanceUnknown: boolean;
/**
* The query's DECLARED scope, not the set of repos the walk happened to
* reach: the subgroup filter for an impact query, the two endpoint repos for
* a trace, every member for a query that names none. An incomplete repo the
* caller never asked about cannot make the caller's answer a floor, and
* marking it anyway is how the marker stops meaning anything. Passing the
* predicate in — rather than a repo list, or a subgroup — is what keeps
* narrowing a scope a call-site change.
*/
inScope: (repoPath: string) => boolean;
}
/** The structured triple, plus the in-scope repos that produced it. */
export type CrossRepoCompleteness = TruncationFields & {
/**
* In-scope repos absent from the artifact, deduped, in first-seen order.
* Empty on a provenance-unknown answer: nothing was measured there, and
* inventing names out of an unreadable value is not a measurement.
*/
incompleteRepos: string[];
};
/**
* Read a persisted `suppressedMatchStages` list.
*
* Sibling of `recordedRepoList` and here for the same stated reason: it had
* lived in two files verbatim, so tightening one would silently leave the other.
* All-or-nothing like its sibling — a stale member (this repo has already
* retired `'bm25'` and `'embedding'`) makes the whole list unreadable rather
* than filtering down to `[]`, which on this field would mean "measured,
* nothing suppressed": a clean answer manufactured from a value we could not
* read.
*/
export function recordedMatchStages(value: unknown): MatchType[] | undefined {
if (!Array.isArray(value)) return undefined;
const known: MatchType[] = ['exact', 'manifest', 'wildcard'];
return value.every((v): v is MatchType => known.includes(v as MatchType)) ? value : undefined;
}
/**
* The ONE computation of "is this cross-repo answer complete?" (KTD10).
*
* Three surfaces can return a partial cross-repo answer — impact, trace, and
* the contract listing — and each used to decide for itself, in its own
* vocabulary, which is how two of them ended up saying it in prose only. The
* answer is the same structured triple `GroupImpactResult` already carries, so
* an agent reading any of them learns "complete" vs "floor" the same way.
*
* `truncationFields` derives `riskEpistemic` from `truncated` mechanically, and
* is reused here rather than re-implemented for the same reason it exists: the
* marker that says "this is a floor, not a verdict" may never drift away from
* the flag that says the answer was cut short (#2787).
*/
export function crossRepoCompleteness(input: CrossRepoCompletenessInput): CrossRepoCompleteness {
const incompleteRepos = [
...new Set([...(input.unreadableRepos ?? []), ...(input.missingRepos ?? [])]),
].filter((repoPath) => input.inScope(repoPath));
// An unreadable or unaccounted repo outranks a suppressed stage: it is the
// more serious structural gap and its remedy (repair the repo, re-sync) has
// to be the one reported. A suppressed stage only decides the reason when
// the repo side is otherwise clean.
const suppressed = (input.suppressedMatchStages ?? []).length > 0;
const repoSideIncomplete = input.provenanceUnknown || incompleteRepos.length > 0;
return {
...truncationFields(
repoSideIncomplete || suppressed,
repoSideIncomplete ? 'incomplete-sync' : 'suppressed-stage',
),
incompleteRepos,
};
}
/**
* A recorded repo list is an array of strings. Anything else — a bare string, an
* object, an array of objects — is a value we could not read, which is "not
* recorded", not "none".
*
* ONE definition, deliberately. This gate is the predicate the whole
* absent-vs-empty-vs-populated distinction rests on, and it applies to the same
* two lists on both the registry and the bridge metadata. It lived in two files
* verbatim, which meant tightening it — say, to reject blank strings — would
* have fixed one surface and silently left the other.
*
* `Array.isArray` alone is not enough: only an array of strings survives
* `cli/group.ts`'s `.join(', ')` as repo paths rather than as `[object Object]`.
*/
export function recordedRepoList(value: unknown): string[] | undefined {
if (!Array.isArray(value)) return undefined;
return value.every((entry) => typeof entry === 'string') ? (value as string[]) : undefined;
}

View file

@ -1,10 +1,15 @@
import { createRequire } from 'node:module';
import type { GroupConfig, GroupManifestLink, ContractType, ContractRole } from './types.js';
import type {
ContractRole,
GroupConfig,
GroupManifestLink,
ManifestContractType,
} from './types.js';
const _require = createRequire(import.meta.url);
const yaml = _require('js-yaml') as typeof import('js-yaml');
const VALID_CONTRACT_TYPES: ContractType[] = [
const VALID_CONTRACT_TYPES: ManifestContractType[] = [
'http',
'grpc',
'thrift',
@ -26,19 +31,15 @@ const VALID_ROLES: ContractRole[] = ['provider', 'consumer'];
// repos that need cross-repo header tracking.
const DEFAULT_DETECT = {
http: true,
graphql: false,
grpc: true,
thrift: true,
topics: true,
shared_libs: true,
embedding_fallback: true,
includes: false,
workspace_deps: false,
};
const DEFAULT_MATCHING = {
bm25_threshold: 0.7,
embedding_threshold: 0.65,
max_candidates_per_step: 3,
exclude_links_paths: [] as string[],
exclude_links_param_only_paths: false,
};
@ -71,7 +72,7 @@ export function parseGroupConfig(yamlContent: string): GroupConfig {
if (!link.to || !repoPaths.has(link.to as string)) {
throw new Error(`links[${i}].to "${link.to}" does not match any repo path in group`);
}
if (!VALID_CONTRACT_TYPES.includes(link.type as ContractType)) {
if (!VALID_CONTRACT_TYPES.includes(link.type as ManifestContractType)) {
throw new Error(
`links[${i}].type "${link.type}" is invalid. Expected: ${VALID_CONTRACT_TYPES.join(', ')}`,
);
@ -89,13 +90,25 @@ export function parseGroupConfig(yamlContent: string): GroupConfig {
return {
from: link.from as string,
to: link.to as string,
type: link.type as ContractType,
type: link.type as ManifestContractType,
contract: String(link.contract),
role: link.role as ContractRole,
};
});
const detect = { ...DEFAULT_DETECT, ...((raw.detect as object) || {}) };
const rawDetect = raw.detect;
if (
rawDetect !== undefined &&
(!rawDetect || typeof rawDetect !== 'object' || Array.isArray(rawDetect))
) {
throw new Error('detect must be a mapping of boolean flags');
}
for (const [key, value] of Object.entries((rawDetect as Record<string, unknown>) || {})) {
if (key in DEFAULT_DETECT && typeof value !== 'boolean') {
throw new Error(`detect.${key} must be true or false`);
}
}
const detect = { ...DEFAULT_DETECT, ...((rawDetect as object) || {}) };
const matching = { ...DEFAULT_MATCHING, ...((raw.matching as object) || {}) };
const packages = (raw.packages as Record<string, Record<string, string>>) || {};

View file

@ -7,11 +7,11 @@ import fsp from 'node:fs/promises';
import path from 'node:path';
import type {
BridgeHandle,
BridgeMeta,
ContractType,
CrossRepoImpact,
GroupConfig,
GroupImpactResult,
GroupImpactTruncationReason,
MatchType,
OutOfScopeLink,
} from './types.js';
@ -24,12 +24,23 @@ import {
} from './group-path-utils.js';
import { getGroupDir } from './storage.js';
import {
bridgeMetaMatchesFile,
closeBridgeDb,
getCachedBridgeReadOnly,
queryBridge,
readBridgeMeta,
} from './bridge-db.js';
import { BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
// Re-exported so the three surfaces keep one import site for the vocabulary,
// while the fold itself stays in a leaf module no native binding reaches.
export {
truncationFields,
crossRepoCompleteness,
type TruncationFields,
type CrossRepoCompleteness,
type CrossRepoCompletenessInput,
} from './completeness.js';
import { truncationFields, crossRepoCompleteness } from './completeness.js';
import { compareCodeUnits } from '../../lib/utils.js';
// High limit for the local phase of group impact so collectImpactSymbolUids
@ -381,23 +392,30 @@ export function mergeRisk(localRisk: string, cross: CrossRepoImpact[]): string {
}
/**
* Build the truncation fields every `runGroupImpact` return path shares.
* Is this bridge's metadata unable to say where its contents came from?
*
* `riskEpistemic` must follow `truncated` mechanically: it is the marker that
* tells a caller the `risk` value is a floor rather than a verdict, and
* `mergeRisk` can only under-report once a crossing is dropped. Attaching it at
* each return let two of the four paths set `truncated` without it, so a
* truncated result read as complete — deriving it in one place is what keeps
* the invariant from drifting again (#2787).
* The three reads are all about a `BridgeMeta` and stay OUT of
* `crossRepoCompleteness` on purpose (see its doc): they are how a caller that
* opened a bridge computes `provenanceUnknown`, not how every caller does.
*
* - `version === 0` — no readable meta.json at all (`readBridgeMeta` answers
* that for both "absent" and "unparseable");
* - `repoListsUnreadable` — a meta.json that parsed but whose repo lists are
* not repo lists. A value we could not read is not a measurement of zero,
* so it may not be spent as one;
* - `pairedWithDatabase === false` — a meta.json that does not describe the
* database sitting beside it, which is what a sync interrupted between the
* swap and the metadata write leaves behind. Measured by
* `ensureBridgeReady` BEFORE the database is opened and carried on the
* meta; this only reads the answer (#3012).
*
* Treating any of them as complete is the fail-open the completeness channel
* exists to close.
*/
function truncationFields(
truncated: boolean,
// Only read on the truncated branch, so the not-truncated call sites omit it
// rather than passing a reason that is thrown away.
reasonIfTruncated: GroupImpactTruncationReason = 'partial',
): Pick<GroupImpactResult, 'truncated' | 'truncationReason' | 'riskEpistemic'> {
if (!truncated) return { truncated: false };
return { truncated: true, truncationReason: reasonIfTruncated, riskEpistemic: 'lower-bound' };
export function bridgeProvenanceUnknown(meta: BridgeMeta): boolean {
return (
meta.version === 0 || meta.repoListsUnreadable === true || meta.pairedWithDatabase === false
);
}
function addCrossImpact(cross: CrossRepoImpact[], candidate: CrossRepoImpact): void {
@ -418,7 +436,7 @@ function addCrossImpact(cross: CrossRepoImpact[], candidate: CrossRepoImpact): v
export async function ensureBridgeReady(
groupDir: string,
): Promise<{ handle: BridgeHandle } | { error: string }> {
): Promise<{ handle: BridgeHandle; meta: BridgeMeta } | { error: string }> {
const meta = await readBridgeMeta(groupDir);
if (meta.version > 0 && meta.version !== BRIDGE_SCHEMA_VERSION) {
return {
@ -433,6 +451,13 @@ export async function ensureBridgeReady(
error: `No bridge.lbug in this group directory. Run gitnexus group sync (schema ${BRIDGE_SCHEMA_VERSION}).`,
};
}
// Pair the metadata to the database BEFORE opening it, and carry the answer.
// An unstamped pair is judged on the two files' write order, so any open that
// touched `bridge.lbug`'s mtime would silently convert "legacy but intact"
// into "provenance unknown" for every pre-stamp bridge on that platform. This
// ordering removes the question rather than betting on the answer.
meta.pairedWithDatabase = await bridgeMetaMatchesFile(groupDir, meta);
// Use the cached read-only handle if available — avoids reopening the same
// bridge.lbug in a long-lived MCP server, which fails on Windows because
// the OS handle isn't fully released before the next open races in.
@ -442,7 +467,7 @@ export async function ensureBridgeReady(
error: `Could not open bridge.lbug read-only (schema ${BRIDGE_SCHEMA_VERSION}). Run gitnexus group sync.`,
};
}
return { handle };
return { handle, meta };
}
function rowToNeighbor(r: Record<string, unknown>): BridgeNeighborRow | null {
@ -641,6 +666,25 @@ export async function runGroupImpact(
if ('error' in bridgePrep) return { error: bridgePrep.error };
const handle = bridgePrep.handle;
// Repos the sync that built this bridge could not account for. Their
// contracts — and every cross-link touching them — are simply absent from
// bridge.lbug, and nothing else in this walk can notice that: the only
// incompleteness channel on the result is `truncationFields`, driven by
// fan-out state. Without folding these in, a query about a symbol whose one
// downstream consumer lives in an unreadable repo returns
// `{ cross: [], truncated: false }` — "complete: nothing depends on this" —
// which is a wrong answer, not an empty one, for a tool an agent uses to
// license a delete or a rename.
//
// The metadata read that answers it (`bridgeProvenanceUnknown`) happens
// INSIDE the `try` below, and the flag is initialized fail-closed here only
// because it outlives that block. The lease taken by `ensureBridgeReady` is
// released by the `finally` and nowhere else, so work done between the lease
// and the `try` is work whose every throw leaks a refcount the cached handle
// can never get back — which is how a malformed meta.json used to wedge the
// handle as well as crash the query. (The repo lists are folded in after the
// `finally`, where a throw can no longer strand the lease.)
let provenanceUnknown = true;
const cross: CrossRepoImpact[] = [];
const outOfScope: OutOfScopeLink[] = [];
const truncatedRepos: string[] = [];
@ -650,6 +694,8 @@ export async function runGroupImpact(
let fanoutTimedOut = false;
try {
provenanceUnknown = bridgeProvenanceUnknown(bridgePrep.meta);
const neighbors = await resolveBridgeNeighbors(handle, {
localRepo: repoPath,
uids,
@ -782,7 +828,46 @@ export async function runGroupImpact(
const localSum = (local as { summary?: Record<string, number> })?.summary || {};
const localRisk = String((local as { risk?: string }).risk ?? 'LOW');
const localPartial = Boolean((local as { partial?: boolean }).partial);
const truncated = truncatedRepos.length > 0 || localPartial;
// The bridge's own incompleteness, in the shared vocabulary, read through
// what this query DECLARED. The fan-out above already drops every neighbour
// outside `subgroup`, so an incomplete repo the query excluded could not have
// contributed a crossing to this answer — marking the answer a floor because
// of it makes the marker fire on results it does not describe, which is how a
// caller learns to ignore it. An unscoped query passes `subgroup: undefined`,
// which `repoInSubgroup` answers true for, so the intersection is the whole
// set and that path is byte-for-byte the old behaviour.
//
// The declared scope is the subgroup PLUS the query's own repo (`exact`
// reuses the one membership helper for the equality, rather than growing a
// second notion of it): the walk starts from `repoPath`'s contracts in the
// bridge, so if THAT is the repo the sync could not read there are no
// crossings to find for any scope, and a subgroup excluding it must not turn
// that vacuum into a confident "complete".
//
// Declared scope, not traversed scope: an incomplete repo's contracts are
// absent from the bridge by definition, so it is never in the set the walk
// reached — filtering on what was traversed would empty the intersection on
// every query and silently restore the fail-open.
//
// Sound only while `MAX_SUPPORTED_CROSS_DEPTH` is 1. At depth 2+ an
// out-of-scope repo can sit BETWEEN two in-scope ones, so dropping it would
// convert a genuine lower bound into a confident complete answer; widen this
// predicate in the same change that raises the depth.
const bridge = crossRepoCompleteness({
unreadableRepos: bridgePrep.meta.unreadableRepos,
missingRepos: bridgePrep.meta.missingRepos,
suppressedMatchStages: bridgePrep.meta.suppressedMatchStages,
provenanceUnknown,
inScope: (candidate) =>
repoInSubgroup(candidate, subgroup) || repoInSubgroup(candidate, repoPath, true),
});
// One predicate, read twice below. Written out at both sites, a third runtime
// cause added to the flag and forgotten at the reason would label a
// retry-able answer `incomplete-sync` — telling the operator to re-sync for
// something a retry fixes. That reason-vs-flag drift is what `truncationFields`
// exists to prevent.
const runtimeTruncated = truncatedRepos.length > 0 || localPartial;
const truncated = runtimeTruncated || bridge.truncated;
const result: GroupImpactResult = {
local,
@ -794,8 +879,25 @@ export async function runGroupImpact(
// and under-reporting a blast radius is the unsafe direction (an agent told
// LOW proceeds; told CRITICAL it stops). Marking the floor keeps the
// warning intact while making the incompleteness legible.
...truncationFields(truncated, fanoutTimedOut ? 'timeout' : 'partial'),
truncatedRepos: [...new Set(truncatedRepos)],
// Runtime limits first — they are what the caller can retry. Past those, the
// BRIDGE's own reason wins: it already distinguished an unreadable repo
// ('incomplete-sync', remedy: re-sync) from a stage the sync was asked to
// skip ('suppressed-stage', remedy: re-sync WITHOUT the flag). Hardcoding
// the fallback here overrode that and told every caller to repair a repo
// that read fine — and made the second value unreachable from this surface
// while the tool description promised it. `cross-trace.ts` re-spreads the
// bridge's fields for the same reason.
...truncationFields(
truncated,
fanoutTimedOut
? 'timeout'
: runtimeTruncated
? 'partial'
: bridge.truncated
? bridge.truncationReason
: 'incomplete-sync',
),
truncatedRepos: [...new Set([...truncatedRepos, ...bridge.incompleteRepos])],
summary: {
direct: localSum.direct ?? 0,
processes_affected: localSum.processes_affected ?? 0,

View file

@ -25,16 +25,29 @@
import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
import { getGroupDir } from './storage.js';
import { ensureBridgeReady, MAX_SUPPORTED_CROSS_DEPTH } from './cross-impact.js';
import {
bridgeProvenanceUnknown,
crossRepoCompleteness,
ensureBridgeReady,
MAX_SUPPORTED_CROSS_DEPTH,
} from './cross-impact.js';
import type { CrossRepoCompleteness } from './completeness.js';
import { truncationFields } from './completeness.js';
import { compareCodeUnits } from '../../lib/utils.js';
import { closeBridgeDb, queryBridge } from './bridge-db.js';
import { repoInSubgroup } from './group-path-utils.js';
import type {
GroupPdgFlowHop,
GroupRepoHandle,
GroupSymbolResolution,
GroupToolPort,
} from './service.js';
import type { BridgeHandle, GroupConfig } from './types.js';
import type {
BridgeHandle,
BridgeMeta,
GroupConfig,
GroupImpactTruncationReason,
} from './types.js';
// ── Result types (discriminated on `status`) ─────────────────────────────
@ -77,7 +90,29 @@ export interface GroupTraceEndpoint {
repo: string;
}
export interface GroupTraceOkResult {
/**
* The incompleteness vocabulary, verbatim from `GroupImpactResult` (KTD10).
*
* A cross-repo trace and a cross-repo impact can both be cut short by the same
* two kinds of cause — a runtime limit inside this walk, or a bridge that never
* held part of the group — and an agent must not have to learn a second
* vocabulary (or parse a `notes` string) to tell "no path exists" from "we
* could not have seen the path". Every field here means exactly what it means
* on `GroupImpactResult`; `notes` stays a human-readable ADDITION to them,
* never the machine-readable channel.
*/
export interface GroupTraceCompleteness {
/** True when this answer is a floor rather than a verdict. */
truncated?: boolean;
/** Why, when `truncated` — runtime limit ('partial'/'timeout') before structure. */
truncationReason?: GroupImpactTruncationReason;
/** Set with `truncated`: the answer under-reports, it never over-reports. */
riskEpistemic?: 'lower-bound';
/** In-scope repos absent from the bridge; omitted when none were measured. */
truncatedRepos?: string[];
}
export interface GroupTraceOkResult extends GroupTraceCompleteness {
status: 'ok';
group: string;
from: GroupTraceEndpoint;
@ -89,7 +124,6 @@ export interface GroupTraceOkResult {
edges: TraceEdge[];
/** Present only when PDG enrichment ran for at least one segment. */
dataFlow?: SegmentDataFlow[];
truncated?: boolean;
notes: string[];
}
@ -101,23 +135,23 @@ export interface GroupTraceCandidate {
startLine: number;
}
export interface GroupTraceNotFoundResult {
/**
* `truncated: true` here means the answer is NOT authoritative — either the
* crossing cap (`MAX_CROSSINGS_TO_TRY`) was hit so a connecting ContractLink
* ranked beyond it may have been skipped, or the bridge itself never held part
* of the group. Both read as "unknown", not as "no path exists";
* `truncationReason` says which.
*/
export interface GroupTraceNotFoundResult extends GroupTraceCompleteness {
status: 'not_found';
group: string;
role?: 'from' | 'to';
query?: string;
/**
* True when the answer is NOT authoritative: the crossing cap
* (`MAX_CROSSINGS_TO_TRY`) was hit, so a connecting ContractLink ranked beyond
* the cap may have been skipped. A consumer should treat this as "unknown",
* not "no path exists".
*/
truncated?: boolean;
notes: string[];
suggestion?: string;
}
export interface GroupTraceAmbiguousResult {
export interface GroupTraceAmbiguousResult extends GroupTraceCompleteness {
status: 'ambiguous';
group: string;
role: 'from' | 'to';
@ -187,6 +221,55 @@ export const TRACE_NOTES = {
'The candidates are listed; trace from the exact calling function or pass `to_uid`.',
} as const;
/**
* Fold this bridge's completeness into the runtime-truncation flag a trace call
* site already computed, and answer in the shared vocabulary.
*
* Precedence mirrors `runGroupImpact`: a runtime limit wins the reason, because
* it is the cause the caller can act on (narrow the query, raise maxDepth),
* while `'incomplete-sync'` needs a different remedy — `gitnexus group sync` —
* and would otherwise mask it.
*
* Returns `{}` — not `{ truncated: false }` — when the answer is complete, so a
* clean trace result keeps the exact shape it has always had.
*/
function traceCompleteness(
bridge: CrossRepoCompleteness,
runtimeTruncated: boolean,
): GroupTraceCompleteness {
const repos = bridge.incompleteRepos.length > 0 ? { truncatedRepos: bridge.incompleteRepos } : {};
// Through `truncationFields`, not hand-written: `riskEpistemic` must follow
// `truncated` mechanically, and a third writer of that pair is how the
// invariant drifts (#2787). The bridge branch re-spreads the helper's own
// output rather than naming its fields.
if (runtimeTruncated) return { ...truncationFields(true, 'partial'), ...repos };
if (!bridge.truncated) return {};
const { incompleteRepos: _incompleteRepos, ...fields } = bridge;
return { ...fields, ...repos };
}
/**
* The trace's declared scope for `crossRepoCompleteness`.
*
* A symbol-to-symbol trace asks about exactly two repos, so an unreadable third
* member cannot make its answer a floor. A DESTINATION trace declares no `to`
* at all — the call may land in any member — so every repo is in scope there,
* which is why the predicate is built per call site rather than derived from
* the endpoints inside the helper.
*/
function bridgeCompletenessFor(
meta: BridgeMeta,
inScope: (repoPath: string) => boolean,
): CrossRepoCompleteness {
return crossRepoCompleteness({
unreadableRepos: meta.unreadableRepos,
missingRepos: meta.missingRepos,
suppressedMatchStages: meta.suppressedMatchStages,
provenanceUnknown: bridgeProvenanceUnknown(meta),
inScope,
});
}
/** Repo-relative path equality, tolerant of a leading "./" / "/" or a repo prefix. */
function sameFile(a: string, b: string): boolean {
if (!a || !b) return false;
@ -873,6 +956,23 @@ async function stitchCrossRepo(
if (p.pdg) notes.push(TRACE_NOTES.pdgRequested);
try {
// Inside the `try`, like `runGroupImpact`'s equivalent: the lease taken by
// `ensureBridgeReady` is released by this block's `finally` and nowhere
// else, so anything computed between the lease and the `try` is work whose
// every throw would strand a refcount the cached handle never gets back.
//
// Declared scope = the two endpoint repos. Whether either of them is a repo
// this bridge could not read decides whether "no ContractLink connects
// them" is a verdict or a floor.
const bridge = bridgeCompletenessFor(
bridgePrep.meta,
// `repoInSubgroup(..., exact)` rather than `===`: it normalizes separators
// and strips trailing slashes, which bare equality does not, so the same
// group.yaml spelling cannot be in scope for impact and out of scope here.
(repoPath) =>
repoInSubgroup(repoPath, fromEp.member.repoPath, true) ||
repoInSubgroup(repoPath, toEp.member.repoPath, true),
);
const { crossings, truncated: crossingsTruncated } = await listCrossingsBetween(
handle,
fromEp.member.repoPath,
@ -883,6 +983,10 @@ async function stitchCrossRepo(
return {
status: 'not_found',
group: p.name,
// No crossings at all is exactly the answer a bridge that never held an
// endpoint's repo produces, so it is the one that most needs the floor
// marker. (Nothing was capped: there were zero rows to cap.)
...traceCompleteness(bridge, false),
notes,
suggestion:
'The endpoints live in different repos with no ContractLink between them. ' +
@ -1016,6 +1120,13 @@ async function stitchCrossRepo(
hopCount: edges.length,
hops: [...hopsA, ...hopsB],
edges,
// A found path is still an answer from this bridge: if its provenance is
// unknown, or an endpoint's repo never made it in, the path may be stale
// and it is certainly not the only one. An incompleteness channel that
// fires only on the empty answer teaches an agent that a non-empty one
// is always complete. The crossing cap is NOT folded in here — a path
// that connected is not a capped search — so this site passes `false`.
...traceCompleteness(bridge, false),
notes,
...(dataFlow.length > 0 ? { dataFlow } : {}),
};
@ -1028,7 +1139,7 @@ async function stitchCrossRepo(
return {
status: 'not_found',
group: p.name,
...(crossingsTruncated ? { truncated: true } : {}),
...traceCompleteness(bridge, crossingsTruncated),
notes,
suggestion: crossingsTruncated
? `No connecting crossing among the ${MAX_CROSSINGS_TO_TRY} highest-confidence ` +
@ -1099,6 +1210,12 @@ async function stitchToDestination(
if (p.crossDepthClamped) notes.push(TRACE_NOTES.crossDepthClamped);
try {
// Inside the `try` for the lease reason above `stitchCrossRepo`'s copy. A
// destination trace declares NO `to`: the call may land in any member, so
// every repo is in the query's scope and no incomplete one can be filtered
// out. An unreadable provider repo is precisely how "no outgoing
// ContractLink leaves this repo" becomes a wrong answer, not an empty one.
const bridge = bridgeCompletenessFor(bridgePrep.meta, () => true);
const { crossings, truncated } = await listCrossingsFrom(handle, fromEp.member.repoPath);
if (crossings.length === 0) {
notes.push(TRACE_NOTES.destinationNoLink);
@ -1107,6 +1224,8 @@ async function stitchToDestination(
group: p.name,
role: 'to',
query: p.from_uid ?? p.from,
// Zero rows to cap, so only the bridge's own completeness can speak.
...traceCompleteness(bridge, false),
notes,
suggestion: 'Pass a `to` symbol for a symbol-to-symbol trace, or run group_sync.',
};
@ -1224,7 +1343,9 @@ async function stitchToDestination(
hopCount: edgesA.length + 1,
hops: [...hopsA, providerHop],
edges: [...edgesA, boundaryEdge],
...(truncated ? { truncated: true } : {}),
// The cap already marked this result; the bridge's completeness folds
// into the same fields rather than beside them.
...traceCompleteness(bridge, truncated),
notes: resultNotes,
};
};
@ -1240,6 +1361,8 @@ async function stitchToDestination(
group: p.name,
role: 'to',
candidates: candidatesFrom(precise),
// The candidate LIST is what an incomplete bridge shortens here.
...traceCompleteness(bridge, truncated),
notes: [...notes, TRACE_NOTES.destinationMultiple],
};
}
@ -1255,6 +1378,7 @@ async function stitchToDestination(
group: p.name,
role: 'to',
candidates: candidatesFrom(fileLevel),
...traceCompleteness(bridge, truncated),
notes: [...notes, TRACE_NOTES.destinationAmbiguousFile],
};
}
@ -1265,7 +1389,7 @@ async function stitchToDestination(
group: p.name,
role: 'to',
query: p.from_uid ?? p.from,
...(truncated ? { truncated: true } : {}),
...traceCompleteness(bridge, truncated),
notes,
suggestion: 'Trace from the function that issues the HTTP request, or pass a `to` symbol.',
};

View file

@ -21,3 +21,94 @@ export function readSafe(repoPath: string, rel: string): string | null {
return null;
}
}
/** Read a regular in-repo file without buffering more than `maxBytes`. */
export async function readSafeBounded(
repoPath: string,
rel: string,
maxBytes: number,
): Promise<string | null> {
if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) return null;
const abs = path.resolve(repoPath, rel);
const base = path.resolve(repoPath);
const relToBase = path.relative(base, abs);
if (relToBase.startsWith('..') || path.isAbsolute(relToBase)) return null;
try {
const canonicalBase = await fs.promises.realpath(base);
const canonicalFile = await fs.promises.realpath(abs);
const canonicalRelative = path.relative(canonicalBase, canonicalFile);
if (canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) return null;
const beforeOpen = await fs.promises.lstat(canonicalFile);
if (!beforeOpen.isFile() || beforeOpen.size > maxBytes) return null;
if (maxBytes === 0) return beforeOpen.size === 0 ? '' : null;
return await new Promise<string | null>((resolve) => {
const stream = fs.createReadStream(canonicalFile, {
flags: 'r',
start: 0,
end: maxBytes,
autoClose: true,
});
const chunks: Buffer[] = [];
let totalBytes = 0;
let validated = false;
let settled = false;
const finish = (value: string | null): void => {
if (settled) return;
settled = true;
resolve(value);
};
stream.pause();
stream.once('open', (fd) => {
try {
const opened = fs.fstatSync(fd);
if (!opened.isFile() || opened.size > maxBytes) {
finish(null);
stream.destroy();
return;
}
const currentCanonical = fs.realpathSync(canonicalFile);
const currentRelative = path.relative(canonicalBase, currentCanonical);
const current = fs.statSync(currentCanonical);
if (
currentRelative.startsWith('..') ||
path.isAbsolute(currentRelative) ||
opened.dev !== current.dev ||
opened.ino !== current.ino
) {
finish(null);
stream.destroy();
return;
}
validated = true;
stream.resume();
} catch {
finish(null);
stream.destroy();
}
});
stream.on('data', (chunk: Buffer | string) => {
const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
totalBytes += bytes.length;
if (totalBytes > maxBytes) {
finish(null);
stream.destroy();
return;
}
chunks.push(bytes);
});
stream.once('end', () => {
finish(validated ? Buffer.concat(chunks, totalBytes).toString('utf8') : null);
});
stream.once('error', () => finish(null));
stream.once('close', () => finish(null));
});
} catch {
return null;
}
}

View file

@ -0,0 +1,707 @@
import { glob } from 'glob';
import {
Kind,
parse,
type DocumentNode,
type FragmentDefinitionNode,
type OperationDefinitionNode,
type SelectionSetNode,
} from 'graphql';
import Parser from 'tree-sitter';
import TypeScript from 'tree-sitter-typescript';
import { createIgnoreFilter } from '../../../config/ignore-service.js';
import { getMaxFileSizeBytes } from '../../ingestion/utils/max-file-size.js';
import { logger } from '../../logger.js';
import { ParseTimeoutError, parseSourceSafe } from '../../tree-sitter/safe-parse.js';
import type { ContractExtractor, CypherExecutor } from '../contract-extractor.js';
import type { ExtractedContract, RepoHandle } from '../types.js';
import { readSafeBounded } from './fs-utils.js';
const PROVIDER_GLOB = '**/*.{ts,tsx,mts,cts}';
const DOCUMENT_GLOB = '**/*.{graphql,gql}';
const NEST_GRAPHQL_PACKAGE = '@nestjs/graphql';
const MAX_GRAPHQL_TOKENS = 100_000;
const MAX_GRAPHQL_DEFINITIONS = 5_000;
const MAX_GRAPHQL_OPERATIONS = 500;
const MAX_GRAPHQL_SELECTIONS = 10_000;
const MAX_GRAPHQL_TRAVERSAL_DEPTH = 64;
const MAX_PROVIDER_AST_NODES = 100_000;
const MAX_PROVIDER_AST_DEPTH = 256;
const GRAPHQL_NAME = /^[_A-Za-z][_0-9A-Za-z]*$/;
type GraphqlOperationKind = 'query' | 'mutation' | 'subscription';
interface ResolvedSymbol {
uid: string;
name: string;
filePath: string;
}
interface DecoratorBindings {
operations: Map<string, GraphqlOperationKind>;
resolvers: Set<string>;
}
type DecoratorFieldName =
| { kind: 'absent' }
| { kind: 'literal'; value: string }
| { kind: 'dynamic' };
type GeneratedSymbolIndex = Map<string, Parser.SyntaxNode[]>;
type GeneratedIndexCache = Map<string, Promise<GeneratedSymbolIndex | null>>;
export const RESOLVE_METHOD_QUERY = `
MATCH (n)
WHERE labels(n) IN ['Method','Function','Property','CodeElement']
AND n.name = $name AND n.filePath = $filePath AND n.startLine = $startLine AND n.id <> ''
RETURN n.id AS uid, n.name AS name, n.filePath AS filePath
ORDER BY n.id ASC
LIMIT 2`;
// LadybugDB returns labels(n) as a scalar string, not Neo4j's string array.
// The real-db integration test executes this exact query and guards that dialect contract.
export const RESOLVE_GENERATED_SYMBOL_QUERY = `
MATCH (n)
WHERE labels(n) IN ['Const','Variable','Function','Method','CodeElement']
AND n.name = $name AND n.filePath <> '' AND n.id <> ''
RETURN n.id AS uid, n.name AS name, n.filePath AS filePath
ORDER BY n.id ASC
LIMIT 2`;
function rowValue(row: Record<string, unknown>, key: string, position: number): string {
return String(row[key] ?? row[position] ?? '');
}
function uniqueRealSymbol(rows: Record<string, unknown>[]): ResolvedSymbol | null {
if (rows.length !== 1) return null;
const row = rows[0];
const symbol = {
uid: rowValue(row, 'uid', 0),
name: rowValue(row, 'name', 1),
filePath: rowValue(row, 'filePath', 2).replace(/\\/g, '/'),
};
return symbol.uid && symbol.name && symbol.filePath ? symbol : null;
}
function unquote(text: string): string | null {
const trimmed = text.trim();
if (trimmed.length < 2) return null;
const quote = trimmed[0];
if ((quote !== "'" && quote !== '"' && quote !== '`') || trimmed.at(-1) !== quote) return null;
const value = trimmed.slice(1, -1);
return value.includes('${') ? null : value;
}
function unwrapExpression(node: Parser.SyntaxNode): Parser.SyntaxNode {
let current = node;
while (
['as_expression', 'satisfies_expression', 'parenthesized_expression'].includes(current.type) &&
current.namedChildren[0]
) {
current = current.namedChildren[0];
}
return current;
}
function objectPairValue(node: Parser.SyntaxNode, key: string): Parser.SyntaxNode | null {
const object = unwrapExpression(node);
if (object.type !== 'object') return null;
for (const pair of object.namedChildren) {
if (pair.type !== 'pair') continue;
const keyNode = pair.childForFieldName('key');
const pairKey = keyNode ? (unquote(keyNode.text) ?? keyNode.text) : null;
if (pairKey === key) return pair.childForFieldName('value');
}
return null;
}
function literalValue(node: Parser.SyntaxNode | null): string | null {
return node ? unquote(unwrapExpression(node).text) : null;
}
function graphqlNameValue(node: Parser.SyntaxNode | null): string | null {
return node ? literalValue(objectPairValue(node, 'value')) : null;
}
function withinGeneratedAstBudget(root: Parser.SyntaxNode): boolean {
const pending: Array<{ node: Parser.SyntaxNode; depth: number }> = [{ node: root, depth: 0 }];
let visited = 0;
while (pending.length > 0) {
const current = pending.pop();
if (!current) break;
visited++;
if (visited > MAX_PROVIDER_AST_NODES || current.depth > MAX_PROVIDER_AST_DEPTH) return false;
for (let index = current.node.namedChildren.length - 1; index >= 0; index--) {
const child = current.node.namedChildren[index];
if (child) pending.push({ node: child, depth: current.depth + 1 });
}
}
return true;
}
function generatedRootFields(
selectionSet: Parser.SyntaxNode | null,
fragments: ReadonlyMap<string, Parser.SyntaxNode>,
): Set<string> | null {
const fields = new Set<string>();
if (!selectionSet) return null;
const seenFragments = new Set<string>();
const pending: Array<{ selectionSet: Parser.SyntaxNode; depth: number }> = [
{ selectionSet, depth: 0 },
];
let selectionsVisited = 0;
while (pending.length > 0) {
const current = pending.pop();
if (!current) break;
if (current.depth > MAX_GRAPHQL_TRAVERSAL_DEPTH) return null;
const selections = objectPairValue(current.selectionSet, 'selections');
const array = selections ? unwrapExpression(selections) : null;
if (!array || array.type !== 'array') return null;
for (const item of array.namedChildren) {
selectionsVisited++;
if (selectionsVisited > MAX_GRAPHQL_SELECTIONS) return null;
const selection = unwrapExpression(item);
const kind = literalValue(objectPairValue(selection, 'kind'));
if (kind === 'Field') {
const field = graphqlNameValue(objectPairValue(selection, 'name'));
if (field) fields.add(field);
continue;
}
if (kind === 'InlineFragment') {
const nested = objectPairValue(selection, 'selectionSet');
if (nested) pending.push({ selectionSet: nested, depth: current.depth + 1 });
continue;
}
if (kind !== 'FragmentSpread') continue;
const name = graphqlNameValue(objectPairValue(selection, 'name'));
if (!name || seenFragments.has(name)) continue;
const fragment = fragments.get(name);
if (!fragment) continue;
const nested = objectPairValue(fragment, 'selectionSet');
if (!nested) continue;
seenFragments.add(name);
pending.push({ selectionSet: nested, depth: current.depth + 1 });
}
}
return fields;
}
function parsedDocumentProof(
source: string,
operationKind: GraphqlOperationKind,
operationName: string,
requiredFields: readonly string[],
): boolean {
let document: DocumentNode;
try {
document = parse(source, { noLocation: true, maxTokens: MAX_GRAPHQL_TOKENS });
} catch {
return false;
}
if (document.definitions.length > MAX_GRAPHQL_DEFINITIONS) return false;
const fragments = new Map<string, FragmentDefinitionNode>();
for (const definition of document.definitions) {
if (definition.kind === Kind.FRAGMENT_DEFINITION)
fragments.set(definition.name.value, definition);
}
for (const definition of document.definitions) {
if (definition.kind !== Kind.OPERATION_DEFINITION) continue;
if (definition.operation !== operationKind || definition.name?.value !== operationName)
continue;
const fields = rootFields(definition.selectionSet, fragments);
return fields !== null && requiredFields.every((field) => fields.includes(field));
}
return false;
}
function staticGraphqlSource(initializer: Parser.SyntaxNode): string | null {
const value = unwrapExpression(initializer);
if (value.type === 'string') {
if (value.text.startsWith('"')) {
try {
return JSON.parse(value.text) as string;
} catch {
return null;
}
}
return unquote(value.text);
}
if (value.type === 'template_string') return unquote(value.text);
if (value.type === 'call_expression') {
const template = value.namedChildren.find((child) => child.type === 'template_string');
return template ? unquote(template.text) : null;
}
if (value.type !== 'new_expression') return null;
const constructor = value.childForFieldName('constructor') ?? value.namedChildren[0];
if (!constructor || !constructor.text.endsWith('TypedDocumentString')) return null;
const args = value.childForFieldName('arguments');
const first = args?.namedChildren[0];
return first ? staticGraphqlSource(first) : null;
}
export function hasGeneratedDocumentProof(
initializer: Parser.SyntaxNode,
operationKind: GraphqlOperationKind,
operationName: string,
requiredFields: readonly string[],
): boolean {
if (!withinGeneratedAstBudget(initializer)) return false;
const staticSource = staticGraphqlSource(initializer);
if (staticSource !== null) {
return parsedDocumentProof(staticSource, operationKind, operationName, requiredFields);
}
const document = unwrapExpression(initializer);
if (literalValue(objectPairValue(document, 'kind')) !== 'Document') return false;
const definitions = objectPairValue(document, 'definitions');
const array = definitions ? unwrapExpression(definitions) : null;
if (!array || array.type !== 'array') return false;
const fragments = new Map<string, Parser.SyntaxNode>();
for (const item of array.namedChildren) {
const definition = unwrapExpression(item);
if (literalValue(objectPairValue(definition, 'kind')) !== 'FragmentDefinition') continue;
const name = graphqlNameValue(objectPairValue(definition, 'name'));
if (name) fragments.set(name, definition);
}
for (const item of array.namedChildren) {
const definition = unwrapExpression(item);
if (literalValue(objectPairValue(definition, 'kind')) !== 'OperationDefinition') continue;
if (literalValue(objectPairValue(definition, 'operation')) !== operationKind) continue;
if (graphqlNameValue(objectPairValue(definition, 'name')) !== operationName) continue;
const fields = generatedRootFields(objectPairValue(definition, 'selectionSet'), fragments);
if (fields && requiredFields.every((field) => fields.has(field))) return true;
}
return false;
}
function importedDecoratorBindings(root: Parser.SyntaxNode): DecoratorBindings {
const operations = new Map<string, GraphqlOperationKind>();
const resolvers = new Set<string>();
for (const child of root.namedChildren) {
if (child.type !== 'import_statement') continue;
const source = child.childForFieldName('source');
if (!source || unquote(source.text) !== NEST_GRAPHQL_PACKAGE) continue;
const namedImports = child.namedChildren
.find((node) => node.type === 'import_clause')
?.namedChildren.find((node) => node.type === 'named_imports');
if (!namedImports) continue;
for (const specifier of namedImports.namedChildren) {
if (specifier.type !== 'import_specifier') continue;
const imported = specifier.childForFieldName('name')?.text;
const local = specifier.childForFieldName('alias')?.text ?? imported;
if (!imported || !local) continue;
const kind = imported.toLowerCase();
if (kind === 'query' || kind === 'mutation' || kind === 'subscription') {
operations.set(local, kind);
} else if (imported === 'Resolver') {
resolvers.add(local);
}
}
}
return { operations, resolvers };
}
function decoratorKind(
decorator: Parser.SyntaxNode,
bindings: Map<string, GraphqlOperationKind>,
): { kind: GraphqlOperationKind; argumentsNode?: Parser.SyntaxNode } | null {
const expression = decorator.namedChildren[0];
if (!expression) return null;
if (expression.type === 'identifier') {
const kind = bindings.get(expression.text);
return kind ? { kind } : null;
}
if (expression.type !== 'call_expression') return null;
const callee = expression.childForFieldName('function');
if (!callee || callee.type !== 'identifier') return null;
const kind = bindings.get(callee.text);
if (!kind) return null;
return { kind, argumentsNode: expression.childForFieldName('arguments') ?? undefined };
}
function decoratorFieldName(argumentsNode: Parser.SyntaxNode | undefined): DecoratorFieldName {
if (!argumentsNode || argumentsNode.namedChildren.length === 0) return { kind: 'absent' };
const args = argumentsNode.namedChildren;
if (args[0] && ['string', 'template_string'].includes(args[0].type)) {
const direct = unquote(args[0].text);
return direct === null ? { kind: 'dynamic' } : { kind: 'literal', value: direct };
}
let sawOptions = false;
for (const arg of args) {
if (arg.type !== 'object') continue;
sawOptions = true;
for (const pair of arg.namedChildren) {
if (pair.type === 'spread_element' || pair.type.startsWith('shorthand_property_identifier')) {
return { kind: 'dynamic' };
}
if (pair.type !== 'pair') continue;
const key = pair.childForFieldName('key')?.text.replace(/^['"]|['"]$/g, '');
if (key !== 'name') continue;
const value = pair.childForFieldName('value');
if (!value || !['string', 'template_string'].includes(value.type)) {
return { kind: 'dynamic' };
}
const literal = unquote(value.text);
return literal === null ? { kind: 'dynamic' } : { kind: 'literal', value: literal };
}
}
if (sawOptions || args.length === 1) return { kind: 'absent' };
return { kind: 'dynamic' };
}
function topLevelResolverClassBodies(
root: Parser.SyntaxNode,
resolverBindings: ReadonlySet<string>,
): Parser.SyntaxNode[] | null {
if (!withinGeneratedAstBudget(root)) return null;
const bodies: Parser.SyntaxNode[] = [];
for (const statement of root.namedChildren) {
const classNode =
statement.type === 'class_declaration'
? statement
: statement.type === 'export_statement'
? statement.namedChildren.find((child) => child.type === 'class_declaration')
: undefined;
if (!classNode) continue;
const decorators = [
...new Set([
...statement.namedChildren.filter((child) => child.type === 'decorator'),
...classNode.namedChildren.filter((child) => child.type === 'decorator'),
]),
];
const isResolver = decorators.some((decorator) => {
const expression = decorator.namedChildren[0];
if (!expression) return false;
const callee =
expression.type === 'call_expression'
? expression.childForFieldName('function')
: expression;
return callee?.type === 'identifier' && resolverBindings.has(callee.text);
});
if (!isResolver) continue;
const body = classNode.childForFieldName('body');
if (body) bodies.push(body);
}
return bodies;
}
function rootFields(
selectionSet: SelectionSetNode,
fragments: ReadonlyMap<string, FragmentDefinitionNode>,
): string[] | null {
const fields: string[] = [];
const seenFragments = new Set<string>();
const pending: Array<{ selectionSet: SelectionSetNode; depth: number }> = [
{ selectionSet, depth: 0 },
];
let selectionsVisited = 0;
while (pending.length > 0) {
const current = pending.pop();
if (!current) break;
if (current.depth > MAX_GRAPHQL_TRAVERSAL_DEPTH) return null;
for (const selection of current.selectionSet.selections) {
selectionsVisited++;
if (selectionsVisited > MAX_GRAPHQL_SELECTIONS) return null;
if (selection.kind === Kind.FIELD) {
fields.push(selection.name.value);
continue;
}
if (selection.kind === Kind.INLINE_FRAGMENT) {
pending.push({ selectionSet: selection.selectionSet, depth: current.depth + 1 });
continue;
}
const name = selection.name.value;
if (seenFragments.has(name)) continue;
const fragment = fragments.get(name);
if (!fragment) continue;
seenFragments.add(name);
pending.push({ selectionSet: fragment.selectionSet, depth: current.depth + 1 });
}
}
return fields;
}
function generatedCandidates(operation: OperationDefinitionNode): string[] {
const name = operation.name?.value;
return name ? [`${name}Document`] : [];
}
async function generatedDocumentMatches(
repoPath: string,
symbol: ResolvedSymbol,
operationKind: GraphqlOperationKind,
operationName: string,
requiredFields: readonly string[],
cache: GeneratedIndexCache,
): Promise<boolean> {
const normalizedPath = symbol.filePath.replace(/\\/g, '/');
let pendingIndex = cache.get(normalizedPath);
if (!pendingIndex) {
pendingIndex = buildGeneratedSymbolIndex(repoPath, normalizedPath);
cache.set(normalizedPath, pendingIndex);
}
const index = await pendingIndex;
const values = index?.get(symbol.name) ?? [];
return values.some((value) =>
hasGeneratedDocumentProof(value, operationKind, operationName, requiredFields),
);
}
async function buildGeneratedSymbolIndex(
repoPath: string,
filePath: string,
): Promise<GeneratedSymbolIndex | null> {
const source = await readSafeBounded(repoPath, filePath, getMaxFileSizeBytes());
if (source === null) return null;
const parser = new Parser();
parser.setLanguage(
filePath.toLowerCase().endsWith('.tsx') ? TypeScript.tsx : TypeScript.typescript,
);
let tree: Parser.Tree;
try {
tree = parseSourceSafe(parser, source, undefined, undefined, filePath);
} catch (error) {
if (error instanceof ParseTimeoutError) return null;
throw error;
}
return indexGeneratedDeclarators(tree.rootNode);
}
export function indexGeneratedDeclarators(root: Parser.SyntaxNode): GeneratedSymbolIndex {
const index: GeneratedSymbolIndex = new Map();
const pending = [root];
while (pending.length > 0) {
const node = pending.pop();
if (!node) break;
if (node.type === 'variable_declarator') {
const name = node.childForFieldName('name')?.text;
const value = node.childForFieldName('value');
if (name && value) {
const values = index.get(name) ?? [];
values.push(value);
index.set(name, values);
}
}
for (let child = node.namedChildren.length - 1; child >= 0; child--) {
pending.push(node.namedChildren[child]);
}
}
return index;
}
function dedupe(contracts: ExtractedContract[]): ExtractedContract[] {
const seen = new Set<string>();
return contracts.filter((contract) => {
const key = `${contract.contractId}|${contract.role}|${contract.symbolUid}`;
if (seen.has(key)) return false;
seen.add(key);
return true;
});
}
export class GraphqlExtractor implements ContractExtractor {
type = 'graphql' as const;
async canExtract(_repo: RepoHandle): Promise<boolean> {
return true;
}
async extract(
dbExecutor: CypherExecutor | null,
repoPath: string,
_repo: RepoHandle,
): Promise<ExtractedContract[]> {
if (!dbExecutor) return [];
const ignore = await createIgnoreFilter(repoPath);
const [providerFiles, documentFiles] = await Promise.all([
glob(PROVIDER_GLOB, { cwd: repoPath, ignore, nodir: true }),
glob(DOCUMENT_GLOB, { cwd: repoPath, ignore, nodir: true }),
]);
const contracts = [
...(await this.extractProviders(dbExecutor, repoPath, providerFiles)),
...(await this.extractConsumers(dbExecutor, repoPath, documentFiles)),
];
return dedupe(contracts);
}
private async extractProviders(
dbExecutor: CypherExecutor,
repoPath: string,
files: string[],
): Promise<ExtractedContract[]> {
const parser = new Parser();
const contracts: ExtractedContract[] = [];
const maxFileSizeBytes = getMaxFileSizeBytes();
for (const rel of files) {
if (/\.(?:spec|test)\.[cm]?tsx?$/i.test(rel)) continue;
const source = await readSafeBounded(repoPath, rel, maxFileSizeBytes);
if (source === null || !source.includes(NEST_GRAPHQL_PACKAGE)) continue;
parser.setLanguage(
rel.toLowerCase().endsWith('.tsx') ? TypeScript.tsx : TypeScript.typescript,
);
let tree: Parser.Tree;
try {
tree = parseSourceSafe(parser, source, undefined, undefined, rel);
} catch (error) {
if (error instanceof ParseTimeoutError) continue;
throw error;
}
const bindings = importedDecoratorBindings(tree.rootNode);
if (bindings.operations.size === 0 || bindings.resolvers.size === 0) continue;
const bodies = topLevelResolverClassBodies(tree.rootNode, bindings.resolvers);
if (bodies === null) continue;
for (const body of bodies) {
let decorators: Parser.SyntaxNode[] = [];
for (const member of body.namedChildren) {
if (member.type === 'comment') continue;
if (member.type === 'decorator') {
decorators.push(member);
continue;
}
if (member.type !== 'method_definition' && member.type !== 'public_field_definition') {
decorators = [];
continue;
}
const memberDecorators = [
...new Set([
...decorators,
...member.namedChildren.filter((child) => child.type === 'decorator'),
]),
];
const methodName = member.childForFieldName('name')?.text;
if (!methodName) {
decorators = [];
continue;
}
for (const decorator of memberDecorators) {
const operation = decoratorKind(decorator, bindings.operations);
if (!operation) continue;
const parsedField = decoratorFieldName(operation.argumentsNode);
if (parsedField.kind === 'dynamic') continue;
const field = parsedField.kind === 'literal' ? parsedField.value : methodName;
if (!GRAPHQL_NAME.test(field)) continue;
const filePath = rel.replace(/\\/g, '/');
const symbol = uniqueRealSymbol(
await dbExecutor(RESOLVE_METHOD_QUERY, {
name: methodName,
filePath,
startLine:
member.type === 'public_field_definition'
? (member.childForFieldName('value')?.startPosition.row ??
member.startPosition.row) + 1
: member.startPosition.row + 1,
}),
);
if (!symbol) continue;
contracts.push({
contractId: `graphql::${operation.kind}::${field}`,
type: 'graphql',
role: 'provider',
symbolUid: symbol.uid,
symbolRef: { filePath: symbol.filePath, name: symbol.name },
symbolName: symbol.name,
confidence: 1,
meta: {
operationKind: operation.kind,
fieldName: field,
resolverPath: filePath,
extractionStrategy: 'nestjs_decorator',
},
});
}
decorators = [];
}
}
}
return contracts;
}
private async extractConsumers(
dbExecutor: CypherExecutor,
repoPath: string,
files: string[],
): Promise<ExtractedContract[]> {
const contracts: ExtractedContract[] = [];
const generatedIndexCache: GeneratedIndexCache = new Map();
const maxFileSizeBytes = getMaxFileSizeBytes();
for (const rel of files) {
const source = await readSafeBounded(repoPath, rel, maxFileSizeBytes);
if (source === null) continue;
let document: DocumentNode;
try {
document = parse(source, { noLocation: true, maxTokens: MAX_GRAPHQL_TOKENS });
} catch (error) {
logger.debug({ file: rel, error }, 'skipping invalid GraphQL document');
continue;
}
if (document.definitions.length > MAX_GRAPHQL_DEFINITIONS) continue;
const fragments = new Map<string, FragmentDefinitionNode>();
for (const definition of document.definitions) {
if (definition.kind === Kind.FRAGMENT_DEFINITION) {
fragments.set(definition.name.value, definition);
}
}
const operations = document.definitions.filter(
(definition): definition is OperationDefinitionNode =>
definition.kind === Kind.OPERATION_DEFINITION && definition.name !== undefined,
);
if (operations.length > MAX_GRAPHQL_OPERATIONS) continue;
for (const definition of operations) {
const operationName = definition.name?.value;
if (!operationName) continue;
const documentPath = rel.replace(/\\/g, '/');
const operationFields = rootFields(definition.selectionSet, fragments);
if (operationFields === null) continue;
const uniqueFields = [...new Set(operationFields)];
let symbol: ResolvedSymbol | null = null;
for (const candidate of generatedCandidates(definition)) {
const resolved = uniqueRealSymbol(
await dbExecutor(RESOLVE_GENERATED_SYMBOL_QUERY, { name: candidate }),
);
if (
resolved &&
(await generatedDocumentMatches(
repoPath,
resolved,
definition.operation,
operationName,
uniqueFields,
generatedIndexCache,
))
) {
symbol = resolved;
break;
}
}
if (!symbol) continue;
for (const field of uniqueFields) {
contracts.push({
contractId: `graphql::${definition.operation}::${field}`,
type: 'graphql',
role: 'consumer',
symbolUid: symbol.uid,
symbolRef: { filePath: symbol.filePath, name: symbol.name },
symbolName: symbol.name,
confidence: 1,
meta: {
operationKind: definition.operation,
operationName: definition.name.value,
fieldName: field,
documentPath,
extractionStrategy: 'graphql_ast',
},
});
}
}
}
return contracts;
}
}

View file

@ -28,6 +28,13 @@ import {
REQUEST_LINE_CONFIDENCE,
EXCHANGE_CONFIDENCE,
} from './spring-consumer-shared.js';
import {
extractJavaModuleConstants,
foldJavaOperands,
isJavaConstantFile,
parseJavaConstOperands,
type RepoConstants,
} from '../../../ingestion/route-extractors/java-const-resolver.js';
import {
extractStaticPathExpression,
inferOkHttpMethod,
@ -165,6 +172,34 @@ const JAVA_ROUTE_ANNOTATION_PATTERNS = compilePatterns({
key: (identifier) @key
value: [(string_literal) @value (element_value_array_initializer (string_literal) @value)]))))
name: (identifier) @member) @node
(class_declaration
(modifiers
(annotation
name: [(identifier) (scoped_identifier)] @ann
arguments: (annotation_argument_list [(identifier) @value_expr (field_access) @value_expr (binary_expression) @value_expr])))) @node
(class_declaration
(modifiers
(annotation
name: [(identifier) (scoped_identifier)] @ann
arguments: (annotation_argument_list
(element_value_pair
key: (identifier) @key
value: [(identifier) @value_expr (field_access) @value_expr (binary_expression) @value_expr]))))) @node
(method_declaration
(modifiers
(annotation
name: [(identifier) (scoped_identifier)] @ann
arguments: (annotation_argument_list [(identifier) @value_expr (field_access) @value_expr (binary_expression) @value_expr])))
name: (identifier) @member) @node
(method_declaration
(modifiers
(annotation
name: [(identifier) (scoped_identifier)] @ann
arguments: (annotation_argument_list
(element_value_pair
key: (identifier) @key
value: [(identifier) @value_expr (field_access) @value_expr (binary_expression) @value_expr]))))
name: (identifier) @member) @node
]
`,
},
@ -469,6 +504,12 @@ interface MethodRouteAnnotation {
rawPath: string;
/** OpenFeign's single effective verb; null means its contract is invalid/ambiguous. */
feignHttpMethod?: string | null;
/**
* Non-literal path operands (constant ref or `+`-concat), captured when the
* annotation value is not a string literal. Resolved against the repo-wide
* Java constant map in scan(); a failed fold drops the route (skip floor).
*/
pathOperands?: readonly import('../../../ingestion/route-extractors/constant-resolver.js').Operand[];
}
interface RequestLineAnnotation {
@ -484,6 +525,16 @@ interface RouteAnnotationScan {
feignPrefixByInterfaceId: Map<number, string[]>;
/** Spring HTTP Interface `@HttpExchange(url|value)` type-level prefixes per class/interface node id. */
httpExchangePrefixByTypeId: Map<number, string[]>;
/**
* Class node ids whose `@RequestMapping` prefix is a constant reference or
* concat rather than a literal. Folding a TYPE-level prefix would need the
* repo constant map inside `scanRouteAnnotations`, which has no access to it,
* so `scan()` suppresses every method route under such a class instead of
* emitting it with the prefix silently dropped (a wrong path, not a missing
* one). Ingestion's `extractSpringRoutes` applies the identical rule — R4
* parity.
*/
typesWithUnfoldablePrefix: Set<number>;
/** Resolved Spring shortcut/`@RequestMapping` routes — paths × verbs yield one entry each. */
methodRoutes: MethodRouteAnnotation[];
/** One entry per OpenFeign `@RequestLine` whose value parses to a verb + path. */
@ -511,6 +562,7 @@ function scanRouteAnnotations(tree: Parser.Tree): RouteAnnotationScan {
// feeds the OpenFeign *consumer* path in scan(). An interface carrying both
// `@RequestMapping` and `@FeignClient(path)` lands a different value in each.
const prefixByTypeId = new Map<number, string[]>();
const typesWithUnfoldablePrefix = new Set<number>();
const feignPrefixByInterfaceId = new Map<number, string[]>();
const httpExchangePrefixByTypeId = new Map<number, string[]>();
const methodRoutes: MethodRouteAnnotation[] = [];
@ -527,7 +579,10 @@ function scanRouteAnnotations(tree: Parser.Tree): RouteAnnotationScan {
const annNode = captures.ann;
const node = captures.node;
const valueNode = captures.value;
if (!annNode || !node || !valueNode) continue;
// A non-literal annotation value (constant ref / `+`-concat) is captured
// as @value_expr instead of @value — one of the two must be present.
const valueExprNode = captures.value_expr;
if (!annNode || !node || (!valueNode && !valueExprNode)) continue;
// Discrimination is on the trailing segment only (`simpleName`), so a
// non-Spring annotation whose last segment collides with a route annotation
// (e.g. `@com.evil.GetMapping("/x")`) is treated as a route. This is the
@ -550,7 +605,7 @@ function scanRouteAnnotations(tree: Parser.Tree): RouteAnnotationScan {
const feignHttpMethod =
httpMethods.length === 1 ? (httpMethods[0] === '*' ? 'GET' : httpMethods[0]) : null;
if (!isRouteMemberKey(keyNode)) continue;
const rawPath = unquoteLiteral(valueNode.text);
const rawPath = valueNode ? unquoteLiteral(valueNode.text) : null;
if (rawPath !== null) {
for (const httpMethod of httpMethods) {
methodRoutes.push({
@ -561,10 +616,33 @@ function scanRouteAnnotations(tree: Parser.Tree): RouteAnnotationScan {
feignHttpMethod,
});
}
} else {
// Non-literal path (a constant reference or `+`-concatenation).
// Defer to scan(): the fold needs the repo-wide constant map built
// by prepareRepo. Capture the operand list now; resolution happens
// in scan() against JavaRepoContext, and an unresolvable operand
// list leaves the route skipped (KTD5 skip floor).
const operands = parseJavaConstOperands(valueExprNode);
if (operands !== null) {
for (const httpMethod of httpMethods) {
methodRoutes.push({
methodNode: node,
methodName: captures.member?.text ?? null,
httpMethod,
rawPath: '',
feignHttpMethod,
pathOperands: operands,
});
}
}
}
} else if (ann === 'RequestLine') {
// Feign packs verb + path in one literal; its only named argument is `value`.
if (keyNode && keyNode.text !== 'value') continue;
// A constant-valued `@RequestLine` arrives as @value_expr, not @value —
// `valueNode` is undefined in that shape. Skip rather than dereference
// (constant folding for Feign verb+path literals is out of scope here).
if (!valueNode) continue;
const raw = unquoteLiteral(valueNode.text);
const parsed = raw !== null ? parseRequestLine(raw) : null;
if (parsed) {
@ -579,7 +657,7 @@ function scanRouteAnnotations(tree: Parser.Tree): RouteAnnotationScan {
// `url` or `value` attribute (or positionally); other attributes
// (`accept`, `contentType`, …) are not routes.
if (keyNode && keyNode.text !== 'url' && keyNode.text !== 'value') continue;
const rawPath = unquoteLiteral(valueNode.text);
const rawPath = valueNode ? unquoteLiteral(valueNode.text) : null;
if (rawPath !== null) {
exchangeRoutes.push({
methodNode: node,
@ -596,6 +674,11 @@ function scanRouteAnnotations(tree: Parser.Tree): RouteAnnotationScan {
// — on an interface — an OpenFeign `@FeignClient(path = "...")` prefix.
if (ann === 'RequestMapping') {
if (!isRouteMemberKey(keyNode)) continue;
if (!valueNode) {
// Constant-valued class prefix — see `typesWithUnfoldablePrefix`.
typesWithUnfoldablePrefix.add(node.id);
continue;
}
const prefix = unquoteLiteral(valueNode.text);
if (prefix !== null) {
pushPrefix(prefixByTypeId, node.id, prefix);
@ -606,13 +689,13 @@ function scanRouteAnnotations(tree: Parser.Tree): RouteAnnotationScan {
} else if (ann === 'FeignClient' && node.type === 'interface_declaration') {
// Feign's `name`/`value` identify a service, not a path — only `path` is a prefix.
if (!keyNode || keyNode.text !== 'path') continue;
const prefix = unquoteLiteral(valueNode.text);
const prefix = valueNode ? unquoteLiteral(valueNode.text) : null;
if (prefix !== null) pushPrefix(feignPrefixByInterfaceId, node.id, prefix);
} else if (ann === 'HttpExchange') {
// Spring HTTP Interface type-level prefix: the path lives in `url`/`value`
// (or positionally). Applies to its `@(Get|...)Exchange` consumer methods.
if (keyNode && keyNode.text !== 'url' && keyNode.text !== 'value') continue;
const prefix = unquoteLiteral(valueNode.text);
const prefix = valueNode ? unquoteLiteral(valueNode.text) : null;
if (prefix !== null) pushPrefix(httpExchangePrefixByTypeId, node.id, prefix);
}
}
@ -662,6 +745,7 @@ function scanRouteAnnotations(tree: Parser.Tree): RouteAnnotationScan {
return {
prefixByTypeId,
typesWithUnfoldablePrefix,
feignPrefixByInterfaceId,
httpExchangePrefixByTypeId,
methodRoutes: constrainedMethodRoutes,
@ -707,9 +791,20 @@ function collectImplementedInterfaces(typeNode: Parser.SyntaxNode): string[] {
}
function collectSpringTypes(filePath: string, tree: Parser.Tree): SharedSpringType[] {
const { prefixByTypeId, methodRoutes } = scanRouteAnnotations(tree);
const { prefixByTypeId, typesWithUnfoldablePrefix, methodRoutes } = scanRouteAnnotations(tree);
const routesByMethodId = new Map<number, Array<{ method: string; path: string }>>();
for (const route of methodRoutes) {
// Constant-valued class prefix: no single prefix string exists here, so the
// inheritance view would publish this route unprefixed. Skip — same rule as
// scan() and as ingestion (R4 parity).
const owner = findEnclosingClass(route.methodNode);
if (owner && typesWithUnfoldablePrefix.has(owner.id)) continue;
// A constant-referencing route still carries `rawPath: ''` here — folding
// happens in scan() against the repo constant map, which this
// inheritance-view collector has no access to. Emitting it as an empty
// path would publish `POST /`-shaped noise into the shared type view;
// skip instead (ingestion keeps the same skip floor — R4 parity).
if (route.pathOperands) continue;
const routes = routesByMethodId.get(route.methodNode.id) ?? [];
routes.push({ method: route.httpMethod, path: route.rawPath });
routesByMethodId.set(route.methodNode.id, routes);
@ -781,8 +876,62 @@ export const JAVA_HTTP_PLUGIN: HttpLanguagePlugin = {
content,
);
},
scan(tree) {
prepareRepo(args) {
// Build the repo-wide Java string-constant map once per extract() run
// (mirrors the Python binding's cost-gated pre-pass). A cheap content
// gate keeps literal-only repos at zero parses: only files containing a
// `static final String` declaration are parsed for constants.
try {
// The orchestrator hands over a bare Parser (no language set yet);
// bind Java explicitly — Python's prepareRepo does the same — otherwise
// parseSourceSafe spins to its 15 s budget per file.
args.parser.setLanguage(Java);
} catch {
// fall through: a parser that rejects binding cannot produce a constant
// map; per-file try/catch below then skips everything harmlessly.
}
const constants = new Map<
string,
import('../../../ingestion/route-extractors/constant-resolver.js').ModuleConstants
>();
for (const rel of args.files) {
if (!rel.endsWith('.java')) continue;
try {
const src = args.readFile(rel);
// Cheap content gate: only constant-DEFINITION candidates get parsed
// here (~hundreds of files). Import-only files (every controller)
// are deliberately NOT parsed in this pass — scan() lazily extracts
// the importing file's own import table from the tree it already
// holds when a constant-referencing route actually needs the fold.
// A gate that also matched `import ...;` would parse the entire
// repository here (tens of thousands of files) just to build import
// tables the fold can derive per-file on demand.
//
// The predicate is the SHARED one the ingestion provider uses, so the
// two subsystems agree on which files define constants. Its previous
// local spelling missed `final static String` and lowercase interface
// names, and admitted an interface that ingestion's gate rejected.
if (!src || !isJavaConstantFile(src)) {
continue;
}
const tree = args.parseSource(args.parser, src);
if (!tree) continue;
const mc = extractJavaModuleConstants(tree);
if (mc.literals.size > 0 || mc.exprs.size > 0 || mc.imports.size > 0) {
constants.set(rel, mc);
}
} catch {
// Per-file resilience: one unreadable/oversized/ill-formed file must
// not forfeit the whole repo's constant map (a missing constants
// class only degrades refs that pointed at it).
continue;
}
}
return { constants };
},
scan(tree, repoContext, fileRel) {
const out: HttpDetection[] = [];
const javaCtx = repoContext as { constants: RepoConstants } | undefined;
// ─── Spring providers + OpenFeign consumers (one query pass) ────
// `scanRouteAnnotations` resolves every route-defining annotation —
@ -790,6 +939,7 @@ export const JAVA_HTTP_PLUGIN: HttpLanguagePlugin = {
// `@RequestLine`s — from a single `matches()` pass over the tree.
const {
prefixByTypeId,
typesWithUnfoldablePrefix,
feignPrefixByInterfaceId,
httpExchangePrefixByTypeId,
methodRoutes,
@ -802,7 +952,48 @@ export const JAVA_HTTP_PLUGIN: HttpLanguagePlugin = {
// class is a Spring *provider*. A mapping on a non-Feign interface has no
// enclosing class and is dropped here — interface→controller inheritance is
// handled by `scanProject`.
// Lazy per-file constants view. prepareRepo only indexes constant-
// DEFINING files (cheap gate); an importing controller is absent from
// that map. When a route actually references a constant, extract THIS
// file's import table from the tree scan() already holds (zero extra
// parses) and overlay it for the fold. Files whose routes are all
// literal — the overwhelming majority — never pay this cost.
let foldConstants: RepoConstants | undefined;
const getFoldConstants = (): RepoConstants | undefined => {
if (foldConstants !== undefined) return foldConstants;
foldConstants = javaCtx?.constants;
if (!javaCtx?.constants || !fileRel) return foldConstants;
if (javaCtx.constants.has(fileRel)) return foldConstants;
try {
const mc = extractJavaModuleConstants(tree);
if (mc.imports.size > 0) {
const merged = new Map(javaCtx.constants);
merged.set(fileRel, mc);
foldConstants = merged;
}
} catch {
// fold falls back to the repo-wide map (imports stay unresolved)
}
return foldConstants;
};
for (const route of methodRoutes) {
// A constant-valued CLASS prefix cannot be folded here, so every method
// route under such a class is suppressed rather than emitted at a wrong
// (unprefixed) path — the same rule `classesWithArrayPrefix` already
// encodes for the array form, and the same rule ingestion applies.
const owner = findEnclosingClass(route.methodNode);
if (owner && typesWithUnfoldablePrefix.has(owner.id)) continue;
// Non-literal route path: fold the operand list against the repo-wide
// constant map. Skip (never a guessed path) when the fold fails or the
// repo context is absent (context-less fallback scanning).
if (route.pathOperands && javaCtx && fileRel) {
const resolved = foldJavaOperands(fileRel, route.pathOperands, getFoldConstants()!);
if (resolved === null) continue;
route.rawPath = resolved;
} else if (route.pathOperands) {
continue;
}
const enclosingInterface = findEnclosingInterface(route.methodNode);
if (enclosingInterface && hasAnnotation(enclosingInterface, 'FeignClient')) {
if (!route.feignHttpMethod) continue;

View file

@ -18,6 +18,19 @@ import {
joinPath,
type SharedSpringType,
} from '../../../ingestion/route-extractors/spring-shared.js';
import {
buildKotlinConstantIndex,
extractKotlinModuleConstants,
foldKotlinOperands,
isKotlinConstantFile,
overlayKotlinConstantIndex,
parseKotlinConstOperands,
unfoldableDeclarationsOf,
unquoteKotlinIdentifier,
type KotlinConstantIndex,
type ModuleConstants,
type RepoConstants,
} from '../../../ingestion/route-extractors/kotlin-const-resolver.js';
import {
REST_TEMPLATE_TO_HTTP,
WEB_CLIENT_SHORT_TO_HTTP,
@ -42,6 +55,24 @@ import {
* named annotation arguments (`@GetMapping(value = "/x")` and
* `@GetMapping(path = "/x")`) are supported.
*
* A method path that is a CONSTANT rather than a literal —
* `@GetMapping(ApiPaths.ORDERS)`, `@PostMapping(value = ApiPaths.BASE + "/create")` —
* is folded against a repo-wide Kotlin constant map built once per `extract()`
* run by `prepareRepo`, mirroring what the Java plugin does for the same shape
* in `java.ts`. An unresolvable fold skips the route (never a guessed path), and
* a class prefix that resolves to NO literal at all suppresses every method
* route under that class — the rule `java.ts` applies too, because emitting
* those routes unprefixed would publish paths the application does not serve.
* A prefix that resolves only PARTLY (Kotlin's vararg spelling
* `@RequestMapping("/lit", ApiPaths.BASE)`) still publishes its resolvable arm:
* suppression exists to avoid wrong routes, not to discard right ones. An EMPTY
* path array (`@RequestMapping(arrayOf())`) is not a prefix at all and
* suppresses nothing — see `classifyPathArgument`. On a
* `@FeignClient` the same rule is applied to whichever prefix GOVERNS, in the
* "path wins" order the URL is assembled in — `@FeignClient(path)` first, then
* the interface's `@RequestMapping` — and to both consumer lanes, `@(Get|...)Mapping`
* and `@RequestLine`.
*
* **Consumers** — four call-site patterns common in Kotlin
* Spring projects:
*
@ -131,6 +162,180 @@ const arrayOfArg = (cap: string): string => `(call_expression
(simple_identifier) @arrayOf (#eq? @arrayOf "arrayOf")
(call_suffix (value_arguments (value_argument (string_literal) ${cap}))))`;
/**
* Expression node types a METHOD route path can be FOLDED from. A
* `string_literal` is deliberately absent: literal paths are already captured by
* the dedicated literal patterns, so admitting one here would emit the same
* route twice.
*
* This is an allow-list on purpose, and only safe because it gates FOLDING: a
* shape missing from it yields no route, which is the skip floor. The
* unfoldable-CLASS-PREFIX analysis must not be written this way — there a shape
* missing from the list means "emit unprefixed", a wrong route — so it inverts
* the test instead (see `classifyPathArgument`).
*/
const FOLDABLE_PATH_EXPRESSIONS: ReadonlySet<string> = new Set([
'simple_identifier',
'navigation_expression',
'additive_expression',
]);
/**
* Repo-relative path in the POSIX form the Kotlin constant map is keyed by.
*
* The orchestrator's file list comes from glob v13, which has no `posix: true`
* option and joins with the platform separator, so on Windows `prepareRepo`
* receives `src\main\kotlin\com\example\ApiPaths.kt` and `scan` receives the
* same for `fileRel`. `resolveKotlinImport` turns an import specifier into
* `com/example/ApiPaths.kt` and asks whether a key ENDS WITH it — a test no
* backslashed key can pass. Left unnormalized, every cross-file constant fold
* returns null on Windows and on Windows only: the pre-pass still runs, the
* context is still built, and the feature is simply, silently absent. The unit
* fixtures build POSIX keys by hand, so CI cannot see it.
*
* Normalizing at this boundary — write side (the map keys below) and read side
* (`fileRel`) — is the same fix `node.ts` (`normalizeRel`) and `python.ts`
* (`fileShortKey` / `fileLongKey`) already apply for the same reason, and it is
* the only coherent place: the resolver returns the key it matched, so
* normalizing inside it would hand back a value that misses in a map nobody
* normalized. `readFile` still receives the ORIGINAL `rel`, since the filesystem
* wants the platform's own spelling.
*/
function normalizeRel(rel: string): string {
return rel.replace(/\\/g, '/').replace(/^\.\//, '');
}
/**
* The path expression carried by one route-annotation argument, or null when the
* argument does not designate a path.
*
* tree-sitter-kotlin gives positional and named arguments the same
* `value_argument` node, distinguished only by a leading `simple_identifier` and
* an `=` token — so the key must be read here rather than constrained in the
* query. Non-route keys (`produces`, `consumes`, `headers`, …) return null,
* matching the `#match? @key "^(path|value)$"` guard the literal patterns use.
*/
function kotlinRouteArgumentExpression(arg: Parser.SyntaxNode): Parser.SyntaxNode | null {
const first = arg.namedChild(0);
if (!first) return null;
if (!arg.children.some((c) => c.type === '=')) return first; // positional
if (first.type !== 'simple_identifier') return null;
if (first.text !== 'path' && first.text !== 'value') return null;
return arg.namedChild(1);
}
/**
* The `path = …` expression of one `@FeignClient` argument, or null.
*
* Deliberately narrower than {@link kotlinRouteArgumentExpression}: on a Feign
* client the positional argument and `value =` name a SERVICE, not a path, so
* only the explicit `path` key contributes a URL prefix. This mirrors the
* `#eq? @key "path"` guard the literal `@FeignClient` patterns use, and the
* `keyNode.text !== 'path'` guard `java.ts` applies to the same annotation.
*/
function kotlinFeignPathArgumentExpression(arg: Parser.SyntaxNode): Parser.SyntaxNode | null {
const first = arg.namedChild(0);
if (!first || first.type !== 'simple_identifier') return null;
if (!arg.children.some((c) => c.type === '=')) return null;
if (first.text !== 'path') return null;
return arg.namedChild(1);
}
/**
* Is `node` a string literal whose value is fully known at parse time — that is,
* a literal carrying no interpolation?
*
* tree-sitter-kotlin models `"$base/x"` and `"${base}/x"` as a `string_literal`
* whose named children INTERLEAVE `string_content` runs with interpolation nodes
* — `interpolation_identifier_start`/`interpolated_identifier` for the `$name`
* form, `interpolation_expression_start`/`interpolated_expression`/
* `interpolation_expression_end` for `${…}` — so the test has to be `every`, not
* `some`: `"pre${A.B}post"` carries `string_content` too. The route layer
* unquotes the RAW TEXT, so treating one as a literal publishes the source
* spelling — `/${ApiPaths.BASE}/orders` — as though the application served it.
* Escape sequences are NOT separate nodes in this grammar (`"/a\nb"` is one
* `string_content`), so this accepts exactly what it accepted before; a future
* grammar that split them would floor to "unknown" rather than to a de-escaped
* guess. Same test the constant resolver's `stringLiteralValue` applies, so a
* path is either literal on both sides or folded on neither.
*/
function isPlainStringLiteral(node: Parser.SyntaxNode): boolean {
if (node.type !== 'string_literal') return false;
return node.namedChildren.every((child) => child.type === 'string_content');
}
/**
* Element expressions of a Kotlin `arrayOf(...)` call, or null when `node` is
* not one. The JS mirror of the {@link arrayOfArg} query fragment, so the
* unfoldable-prefix analysis inspects exactly the elements the literal prefix
* patterns harvest.
*/
function kotlinArrayOfElements(node: Parser.SyntaxNode): Parser.SyntaxNode[] | null {
if (node.type !== 'call_expression') return null;
const callee = node.namedChild(0);
if (callee?.type !== 'simple_identifier' || callee.text !== 'arrayOf') return null;
const suffix = node.namedChildren.find((c) => c.type === 'call_suffix');
const args = suffix?.namedChildren.find((c) => c.type === 'value_arguments');
if (!args) return null;
return args.namedChildren
.filter((c) => c.type === 'value_argument')
.map((c) => c.namedChild(0))
.filter((c): c is Parser.SyntaxNode => c !== null);
}
/**
* What a route-annotation path argument says about the prefix it designates.
* Only `'unresolvable'` may suppress a route:
*
* - `'literal'` — at least one element is a plain literal, already harvested by
* the literal prefix patterns, so there is nothing to suppress.
* - `'none'` — no prefix. Empty `arrayOf()` or `[]` is Spring's "map at the root".
* Kept distinct from `'unresolvable'` because conflating them suppressed even
* plain literal routes below such a class, which no constant fold was ever
* involved in. tree-sitter-kotlin (fwcd) represents empty `[]` with a
* zero-width recovery child; filtering it is required for route interfaces,
* which do parse as `class_declaration`.
* - `'unresolvable'` — a non-empty argument with no literal element
* (`ApiPaths.BASE`, `buildPath()`, a template). Served path is unknowable.
*/
type PathArgumentPrefix = 'literal' | 'none' | 'unresolvable';
function classifyPathArgument(expr: Parser.SyntaxNode): PathArgumentPrefix {
if (isPlainStringLiteral(expr)) return 'literal';
if (expr.type === 'collection_literal') {
const elements = expr.namedChildren.filter((child) => child.text.length > 0);
if (elements.length === 0) return 'none';
return elements.some(isPlainStringLiteral) ? 'literal' : 'unresolvable';
}
const elements = kotlinArrayOfElements(expr);
if (elements) {
if (elements.length === 0) return 'none';
return elements.some(isPlainStringLiteral) ? 'literal' : 'unresolvable';
}
return 'unresolvable';
}
/**
* Type declarations enclosing `node`, innermost first, by qualified type path.
*
* The scope a bare constant in a route annotation is resolved against; passed to
* `foldKotlinOperands`, which applies it. Collects `class_declaration` (including
* interfaces) and `object_declaration`. A `companion_object` adds no link of
* its own — members are keyed under the enclosing class one hop up. For a node
* inside `Outer.Inner`, returns `['Outer.Inner', 'Outer']`, matching the keys
* produced by `extractKotlinModuleConstants`. Skips unnamed types rather than
* guessing.
*/
function kotlinEnclosingTypeNames(node: Parser.SyntaxNode): string[] {
const simpleNames: string[] = [];
for (let cur = node.parent; cur; cur = cur.parent) {
if (cur.type !== 'class_declaration' && cur.type !== 'object_declaration') continue;
const ident = cur.children.find((c) => c.type === 'type_identifier');
if (ident) simpleNames.push(unquoteKotlinIdentifier(ident.text));
}
return simpleNames.map((_, index) => simpleNames.slice(index).reverse().join('.'));
}
// ─── Kotlin OkHttp builder verb-walk (parity with java-static-path.ts) ──
// Mirrors `inferOkHttpMethod`, adapted to the Kotlin grammar: a call `X.name(args)`
// is a `call_expression` whose callee is a `navigation_expression` (receiver +
@ -399,6 +604,151 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
],
} satisfies LanguagePatterns<Record<string, never>>);
// ─── Provider: constant-valued @RequestMapping / @(Get|...)Mapping ────
// The literal patterns above pin the path node itself (`(string_literal) @path`),
// which structurally cannot match `@GetMapping(ApiPaths.ORDERS)`. These two
// capture the whole `value_argument` instead and let
// `kotlinRouteArgumentExpression` sort out positional vs `path =`/`value =`
// in JS — a query-level split is not available here, because tree-sitter-kotlin
// uses one `value_argument` node for both forms and 0.21.x has no negation to
// test the `=` token with.
//
// These deliberately match LITERAL arguments too (any `value_argument` does).
// The method-route loop drops those via `FOLDABLE_PATH_EXPRESSIONS` so a
// literal route is emitted once, by the literal patterns; the class-prefix
// collector instead KEEPS them and tests them for literalness, which is how a
// prefix that no literal pattern could resolve gets noticed at all.
const SPRING_CONST_CLASS_PREFIX_PATTERNS = compilePatterns({
name: 'kotlin-spring-const-class-prefix',
language,
patterns: [
{
meta: {},
query: `
(class_declaration
(modifiers
(annotation
(constructor_invocation
(user_type (type_identifier) @ann (#eq? @ann "RequestMapping"))
(value_arguments (value_argument) @arg))))
(type_identifier) @cls) @class
`,
},
],
} satisfies LanguagePatterns<Record<string, never>>);
const SPRING_CONST_METHOD_ROUTE_PATTERNS = compilePatterns({
name: 'kotlin-spring-const-method-route',
language,
patterns: [
{
meta: {},
query: `
(function_declaration
(modifiers
(annotation
(constructor_invocation
(user_type (type_identifier) @ann (#match? @ann "^(Get|Post|Put|Delete|Patch)Mapping$"))
(value_arguments (value_argument) @arg))))
(simple_identifier) @method_name) @method
`,
},
],
} satisfies LanguagePatterns<Record<string, never>>);
const SPRING_CONST_FEIGN_PATH_PATTERNS = compilePatterns({
name: 'kotlin-spring-const-feign-path',
language,
patterns: [
{
meta: {},
query: `
(class_declaration
(modifiers
(annotation
(constructor_invocation
(user_type (type_identifier) @ann (#eq? @ann "FeignClient"))
(value_arguments (value_argument) @arg))))) @class
`,
},
],
} satisfies LanguagePatterns<Record<string, never>>);
/**
* Ids of classes whose `@RequestMapping` prefix cannot be resolved to any
* literal, so no route under them can be published at a path the application
* actually serves.
*
* The predicate is INVERTED rather than an allow-list of non-literal node
* types: a class is marked unless its `path`/`value` argument is provably
* literal (recursing into `[…]` and `arrayOf(…)` elements, and refusing an
* interpolated `string_literal`). An allow-list has to enumerate every
* non-literal spelling and silently passes the ones it forgot —
* `[ApiPaths.BASE]`, `arrayOf(ApiPaths.BASE)`, `buildPath()`,
* `if (…) "/a" else "/b"` — each of which then publishes its methods at their
* UNPREFIXED path, a route the application does not serve. `java.ts` gates on
* the ABSENCE of a literal (`if (!valueNode)`) for the same reason.
*
* `resolvedPrefixes` is the literal prefix map built by the pass ABOVE, and a
* class holding an entry there is deliberately NOT marked: Kotlin's vararg
* spelling `@RequestMapping("/lit", ApiPaths.BASE)` leaves a resolvable `/lit`
* behind, and suppressing it would drop a route that IS derivable — trading a
* wrong route for a missing one, which is not the bargain this suppression
* exists to make. The prefix set is then partial (the constant arm is absent)
* exactly as it was before constant folding existed.
*
* The prefix is never folded here: it also feeds the cross-file
* interface-inheritance pass, which has no repo context, so folding it in
* `scan` alone would make the two views disagree. Same rule `java.ts` applies
* (`typesWithUnfoldablePrefix`); folding class prefixes cross-file is a
* follow-up on both sides. Used by BOTH `scan` and the inheritance-view
* collector — with the prefix map each has already built — so the two cannot
* drift apart.
*/
const collectUnfoldablePrefixClassIds = (
tree: Parser.Tree,
resolvedPrefixes: ReadonlyMap<number, string[]>,
): Set<number> => {
const ids = new Set<number>();
for (const match of runCompiledPatterns(SPRING_CONST_CLASS_PREFIX_PATTERNS, tree)) {
const argNode = match.captures.arg;
const classNode = match.captures.class;
if (!argNode || !classNode) continue;
if ((resolvedPrefixes.get(classNode.id) ?? []).length > 0) continue;
const expr = kotlinRouteArgumentExpression(argNode);
if (!expr || classifyPathArgument(expr) !== 'unresolvable') continue;
ids.add(classNode.id);
}
return ids;
};
/**
* Ids of `@FeignClient` interfaces whose `path` argument is present but not
* resolvable to a literal.
*
* `collectUnfoldablePrefixClassIds` cannot see these: it matches
* `@RequestMapping` only, so `@FeignClient(path = ApiPaths.BASE)` fell through
* to the `['']` prefix fallback and published the consumer at its unprefixed
* path — a call the service never makes. Kept as its own set rather than
* merged into the `@RequestMapping` one because `path` OUTRANKS
* `@RequestMapping` on a Feign client: an unresolvable `path` is fatal
* whatever the `@RequestMapping` says, and a resolvable `path` rescues a route
* whose `@RequestMapping` is a constant. The consumer lanes therefore consult
* the two in that same "path wins" order.
*/
const collectFeignUnfoldablePathClassIds = (tree: Parser.Tree): Set<number> => {
const ids = new Set<number>();
for (const match of runCompiledPatterns(SPRING_CONST_FEIGN_PATH_PATTERNS, tree)) {
const argNode = match.captures.arg;
const classNode = match.captures.class;
if (!argNode || !classNode) continue;
const expr = kotlinFeignPathArgumentExpression(argNode);
if (!expr || classifyPathArgument(expr) !== 'unresolvable') continue;
ids.add(classNode.id);
}
return ids;
};
// ─── Consumer: Spring RestTemplate ────────────────────────────────────
// Kotlin call-site shape mirrors the Java plugin's
// `REST_TEMPLATE_PATTERNS`, but goes through tree-sitter-kotlin's
@ -875,11 +1225,24 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
const prefixNode = match.captures.prefix;
const classNode = match.captures.class;
if (!prefixNode || !classNode) continue;
// An INTERPOLATED literal (`"${ApiPaths.BASE}"`) is not a path — unquoting
// its raw text would carry the source spelling into the shared type view
// as a served prefix. Refusing it here is also what lets the unfoldable
// analysis below mark such a class (it skips classes with a resolved
// prefix), so the two stay one decision rather than two.
if (!isPlainStringLiteral(prefixNode)) continue;
const prefix = unquoteLiteral(prefixNode.text);
if (prefix !== null) pushPrefix(prefixByClassId, classNode.id, prefix);
}
// Method @(Get|...)Mapping routes keyed by the function_declaration node id.
//
// Only LITERAL paths land here. A constant-valued path is folded in `scan`
// against the repo constant map, which this inheritance-view collector has
// no access to; publishing it as an empty path would put `POST /`-shaped
// noise into the shared type view, so it is left out — the same skip floor
// `java.ts`'s `collectSpringTypes` keeps.
const routesByMethodId = new Map<number, Array<{ method: string; path: string }>>();
const unfoldablePrefixClassIds = collectUnfoldablePrefixClassIds(tree, prefixByClassId);
for (const match of runCompiledPatterns(SPRING_METHOD_ROUTE_PATTERNS, tree)) {
const annNode = match.captures.ann;
const pathNode = match.captures.path;
@ -889,6 +1252,10 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
if (!httpMethod) continue;
const rawPath = unquoteLiteral(pathNode.text);
if (rawPath === null) continue;
// A constant class prefix leaves no single prefix string for the
// inheritance view to carry, so this route would be published unprefixed.
const owner = findEnclosingClass(methodNode);
if (owner && unfoldablePrefixClassIds.has(owner.id)) continue;
const arr = routesByMethodId.get(methodNode.id) ?? [];
arr.push({ method: httpMethod, path: rawPath });
routesByMethodId.set(methodNode.id, arr);
@ -931,8 +1298,90 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
return {
name: 'kotlin-http',
language,
scan(tree) {
prepareRepo(args) {
// Build the repo-wide Kotlin string-constant map and import index once per
// extract() run. The orchestrator hands over a bare Parser with no language
// bound; bind Kotlin explicitly or `parseSource` spins to its whole time
// budget on every file.
try {
args.parser.setLanguage(language);
} catch {
// A parser that rejects binding cannot produce a constant map; the
// per-file try/catch below then skips everything harmlessly.
}
const constants = new Map<string, ModuleConstants>();
for (const rel of args.files) {
if (!rel.endsWith('.kt') && !rel.endsWith('.kts')) continue;
try {
const src = args.readFile(rel);
// Cheap content gate: only constant-DEFINITION candidates are parsed
// here. Import-only files (every controller) are deliberately NOT
// parsed in this pass — `scan` extracts the importing file's own
// import table from the tree it already holds, on demand, for the
// rare file that actually references a constant. A gate that also
// matched `import …` would parse the entire repository here.
if (!src || !isKotlinConstantFile(src)) continue;
const tree = args.parseSource(args.parser, src);
if (!tree) continue;
const mc = extractKotlinModuleConstants(tree);
if (
mc.literals.size > 0 ||
mc.exprs.size > 0 ||
mc.imports.size > 0 ||
unfoldableDeclarationsOf(mc).size > 0
) {
// POSIX key (see `normalizeRel`); `readFile` above got the raw `rel`.
constants.set(normalizeRel(rel), mc);
}
} catch {
// Per-file resilience: one unreadable/oversized/ill-formed file must
// not forfeit the whole repo's constant map.
continue;
}
}
return { constants, index: buildKotlinConstantIndex(constants) };
},
scan(tree, repoContext, fileRel) {
const out: HttpDetection[] = [];
const kotlinCtx = repoContext as
| { constants: RepoConstants; index: KotlinConstantIndex }
| undefined;
// Read side of the POSIX keying (see `normalizeRel`): the map `prepareRepo`
// built is keyed by normalized path, so every lookup and every fold entry
// point below uses `fileKey`, never the raw `fileRel`.
const fileKey = fileRel === undefined ? undefined : normalizeRel(fileRel);
// Lazy per-file constants/index view. `prepareRepo` only indexes constant-
// DEFINING files, so an importing controller is absent from that map. When
// a route references a constant, extract THIS file's import table from the
// tree `scan` already holds and overlay it. Import-only overlays reuse the
// prepared package projections; files whose routes are all literal never
// pay this cost.
let foldIndex: KotlinConstantIndex | undefined;
const getFoldIndex = (): KotlinConstantIndex | undefined => {
if (foldIndex !== undefined) return foldIndex;
foldIndex = kotlinCtx?.index;
if (!kotlinCtx || !fileKey) return foldIndex;
if (kotlinCtx.constants.has(fileKey)) return foldIndex;
try {
const mc = extractKotlinModuleConstants(tree);
// Same admission test the pre-pass applies above. Keeping the complete
// test here also makes this overlay correct if a future gate safely
// excludes another declaration shape.
if (
mc.literals.size > 0 ||
mc.exprs.size > 0 ||
mc.imports.size > 0 ||
unfoldableDeclarationsOf(mc).size > 0
) {
foldIndex = overlayKotlinConstantIndex(kotlinCtx.index, fileKey, mc);
}
} catch {
// fold falls back to the repo-wide map (imports stay unresolved)
}
return foldIndex;
};
// ─── Class prefixes ─────────────────────────────────────────────
const prefixByClassId = new Map<number, string[]>();
@ -940,10 +1389,17 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
const prefixNode = match.captures.prefix;
const classNode = match.captures.class;
if (!prefixNode || !classNode) continue;
// An INTERPOLATED literal (`"${ApiPaths.BASE}"`) is not a path — see
// `isPlainStringLiteral`. Refusing it here also lets the unfoldable
// analysis below mark such a class, since that skips classes whose
// prefix already resolved.
if (!isPlainStringLiteral(prefixNode)) continue;
const prefix = unquoteLiteral(prefixNode.text);
if (prefix !== null) pushPrefix(prefixByClassId, classNode.id, prefix);
}
const classesWithUnfoldablePrefix = collectUnfoldablePrefixClassIds(tree, prefixByClassId);
// ─── OpenFeign client interfaces + HTTP Interface type prefixes ──
// In tree-sitter-kotlin an `interface` is a `class_declaration`, so a
// `@FeignClient` interface's @(Get|...)Mapping methods would otherwise be
@ -956,11 +1412,12 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
if (!classNode) continue;
feignClassIds.add(classNode.id);
const prefixNode = match.captures.prefix;
if (prefixNode) {
if (prefixNode && isPlainStringLiteral(prefixNode)) {
const prefix = unquoteLiteral(prefixNode.text);
if (prefix !== null) pushPrefix(feignPrefixByClassId, classNode.id, prefix);
}
}
const feignClassesWithUnfoldablePath = collectFeignUnfoldablePathClassIds(tree);
const httpExchangePrefixByClassId = new Map<number, string[]>();
for (const match of runCompiledPatterns(SPRING_HTTP_EXCHANGE_CLASS_PATTERNS, tree)) {
const classNode = match.captures.class;
@ -971,24 +1428,91 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
}
// ─── Method routes (Spring providers) + OpenFeign consumers ─────
// Literal and constant-valued paths are normalized into one candidate list
// so both reach the same Feign/interface/prefix classification below.
const methodRoutes: Array<{
httpMethod: string;
rawPath: string;
nameNode: Parser.SyntaxNode | undefined;
methodNode: Parser.SyntaxNode;
}> = [];
for (const match of runCompiledPatterns(SPRING_METHOD_ROUTE_PATTERNS, tree)) {
const annNode = match.captures.ann;
const pathNode = match.captures.path;
const nameNode = match.captures.method_name;
const methodNode = match.captures.method;
if (!annNode || !pathNode || !methodNode) continue;
const httpMethod = METHOD_ANNOTATION_TO_HTTP[annNode.text];
if (!httpMethod) continue;
const rawPath = unquoteLiteral(pathNode.text);
if (rawPath === null) continue;
methodRoutes.push({
httpMethod,
rawPath,
nameNode: match.captures.method_name,
methodNode,
});
}
for (const match of runCompiledPatterns(SPRING_CONST_METHOD_ROUTE_PATTERNS, tree)) {
const annNode = match.captures.ann;
const argNode = match.captures.arg;
const methodNode = match.captures.method;
if (!annNode || !argNode || !methodNode) continue;
const httpMethod = METHOD_ANNOTATION_TO_HTTP[annNode.text];
if (!httpMethod) continue;
const expr = kotlinRouteArgumentExpression(argNode);
if (!expr || !FOLDABLE_PATH_EXPRESSIONS.has(expr.type)) continue;
// No repo context (context-less fallback scanning) means no constant map
// and therefore no honest answer — skip rather than guess a path.
if (!fileKey) continue;
const index = getFoldIndex();
if (!index) continue;
const operands = parseKotlinConstOperands(expr);
if (operands === null) continue;
// A bare reference means whatever the ENCLOSING types bind it to before
// it means anything at file level — Kotlin's rule for a companion
// member, which is in scope unqualified only inside its own class body.
const rawPath = foldKotlinOperands(
fileKey,
operands,
index.repo,
kotlinEnclosingTypeNames(methodNode),
index,
);
if (rawPath === null) continue;
methodRoutes.push({
httpMethod,
rawPath,
nameNode: match.captures.method_name,
methodNode,
});
}
for (const { httpMethod, rawPath, nameNode, methodNode } of methodRoutes) {
const enclosingClass = findEnclosingClass(methodNode);
// A @(Get|...)Mapping inside a @FeignClient interface is an OpenFeign
// consumer (a remote call), not a route this service serves.
if (enclosingClass && feignClassIds.has(enclosingClass.id)) {
// Whichever prefix GOVERNS must be resolvable, or the remote URL is
// unknowable and an unprefixed consumer would be a call this service
// never makes. Checked in the same "path wins" order the fallback
// below resolves in, so an unresolvable `@RequestMapping` does not
// suppress a client whose literal `@FeignClient(path)` outranks it,
// and an unresolvable `path` is fatal even when `@RequestMapping` is
// a literal.
//
// This reaches a Feign INTERFACE at all because tree-sitter-kotlin
// models `interface` as a `class_declaration`, and it should: Spring
// Cloud prepends the governing prefix to every method of the client.
// Java diverges only by accident of its grammar — `findEnclosingClass`
// skips `interface_declaration`, so `java.ts` still emits such a
// consumer at its unprefixed path. Aligning Java is a change to Java's
// behavior and belongs in its own follow-up, not in the Kotlin binding.
if (feignClassesWithUnfoldablePath.has(enclosingClass.id)) continue;
const feignPrefixes = feignPrefixByClassId.get(enclosingClass.id);
if (!feignPrefixes && classesWithUnfoldablePrefix.has(enclosingClass.id)) continue;
// @FeignClient(path) wins over @RequestMapping; a multi-element prefix
// yields one consumer per (prefix × this route).
const prefixes = feignPrefixByClassId.get(enclosingClass.id) ??
prefixByClassId.get(enclosingClass.id) ?? [''];
const prefixes = feignPrefixes ?? prefixByClassId.get(enclosingClass.id) ?? [''];
for (const prefix of prefixes) {
out.push({
role: 'consumer',
@ -1002,6 +1526,10 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
}
continue;
}
// An unresolvable class prefix leaves no path this service serves, so
// every route under such a class is dropped rather than emitted at a
// wrong (unprefixed) one — the rule `java.ts` applies for Java.
if (enclosingClass && classesWithUnfoldablePrefix.has(enclosingClass.id)) continue;
// A @(Get|...)Mapping on a (non-Feign) interface declares a route
// *contract*, not a route this service serves — the implementing
// @RestController is the provider, emitted via scanProject's interface
@ -1171,13 +1699,21 @@ function buildKotlinPlugin(language: unknown): HttpLanguagePlugin {
if (!parsed) continue;
const enclosingClass = findEnclosingClass(methodNode);
if (!enclosingClass || !isKotlinInterface(enclosingClass)) continue;
// The same governing-prefix resolvability guard the @(Get|...)Mapping-in-Feign
// lane applies, in the same "path wins" order — this loop resolves through
// the identical fallback chain, so an unresolvable governing prefix leaves
// the remote URL just as unknowable here. Without it a single interface
// could suppress its @(Get|...)Mapping routes and publish its @RequestLine
// routes under the very same unresolvable prefix.
if (feignClassesWithUnfoldablePath.has(enclosingClass.id)) continue;
const feignPrefixes = feignPrefixByClassId.get(enclosingClass.id);
if (!feignPrefixes && classesWithUnfoldablePrefix.has(enclosingClass.id)) continue;
// Mirror java.ts (which pre-merges the @RequestMapping fallback into
// feignPrefixByInterfaceId, "path wins"): @FeignClient(path) wins, else
// the interface's class-level @RequestMapping prefix, else none. Without
// the prefixByClassId fallback Kotlin dropped the class prefix that Java
// applies — the same fallback chain the @GetMapping-in-Feign path uses above.
const prefixes = feignPrefixByClassId.get(enclosingClass.id) ??
prefixByClassId.get(enclosingClass.id) ?? [''];
const prefixes = feignPrefixes ?? prefixByClassId.get(enclosingClass.id) ?? [''];
for (const prefix of prefixes) {
out.push({
role: 'consumer',

View file

@ -9,15 +9,28 @@ import {
type LanguagePatterns,
type PatternSpec,
} from '../tree-sitter-scanner.js';
import type { HttpDetection, HttpLanguagePlugin } from './types.js';
import type { HttpDetection, HttpLanguagePlugin, RepoContext } from './types.js';
import { MAX_FOLD_LENGTH } from '../../../ingestion/route-extractors/constant-resolver.js';
import {
DATA_ROUTE_TABLE_SOURCE,
scanDataRouteTables,
} from '../../../ingestion/route-extractors/data-route-table.js';
import { extractNestRoutes } from '../../../ingestion/route-extractors/nest.js';
import { normalizeExtractedRoutePath } from '../../../ingestion/route-extractors/route-path.js';
import {
buildJsRepoFacts,
extractJsModuleFacts,
isAxiosNamespace,
isHttpClientRef,
resolveJsPathExpression,
type JsModuleFacts,
type JsRepoFacts,
} from '../../../ingestion/route-extractors/js-const-resolver.js';
/**
* Node.js / TypeScript HTTP plugin family. Handles:
* - NestJS `@Controller('prefix')` classes with `@Get(':id')` methods
* - NestJS `@Controller('prefix')` classes with `@Get(':id')` methods,
* delegated wholesale to the indexer's `extractNestRoutes`
* - Express `router.get(...)` / `app.post(...)` providers
* - `fetch(url)` / `fetch(url, { method: 'POST' })` consumers
* - `axios.get(url)` / `axios.delete(url)` consumers
@ -32,34 +45,8 @@ import {
* same `scan` function but bind to different grammars.
*/
// ─── Provider: NestJS — class-level @Controller('prefix') ────────────
// In tree-sitter-typescript decorators are NOT children of
// class_declaration / method_definition — they're siblings in the
// surrounding class_body / program node. We therefore match the
// decorator standalone and walk to its related class/method in JS.
const NEST_CONTROLLER_SPEC: PatternSpec<Record<string, never>> = {
meta: {},
query: `
(decorator
(call_expression
function: (identifier) @dec (#eq? @dec "Controller")
arguments: (arguments . [(string) (template_string)] @prefix))) @ctrl_decorator
`,
};
// ─── Provider: NestJS — method-level @Get/@Post/... decorators ───────
// Matches either `@Get('path')` or `@Get()`. The `@path` capture is
// optional — when the first argument isn't a string, the plugin falls
// back to '/' for the method-level path.
const NEST_METHOD_SPEC: PatternSpec<Record<string, never>> = {
meta: {},
query: `
(decorator
(call_expression
function: (identifier) @dec (#match? @dec "^(Get|Post|Put|Delete|Patch)$")
arguments: (arguments) @args)) @method_decorator
`,
};
// NestJS providers are not queried here at all — see the `extractNestRoutes`
// call in `scanBundle`.
// ─── Provider: Express — router.get/app.post/... ─────────────────────
const EXPRESS_SPEC: PatternSpec<Record<string, never>> = {
@ -98,15 +85,28 @@ const FETCH_WITH_OPTIONS_SPEC: PatternSpec<Record<string, never>> = {
`,
};
// ─── Consumer: axios.get/post/... ────────────────────────────────────
const AXIOS_SPEC: PatternSpec<Record<string, never>> = {
// ─── Consumer: <httpClient>.get/post/... ─────────────────────────────
// Widened from a literal `axios` receiver with a literal path. Application
// code satisfies neither: it calls through a configured instance
// (`const api = axios.create({ baseURL })`, imported at the call site under
// whatever name the app chose) and passes the path by reference from a shared
// route table (`api.get(API_ROUTE_PATH.LINKS)`). The query therefore matches
// ANY identifier receiver with an HTTP-verb method and ANY first argument;
// `scanBundle` admits a match only after PROVING the receiver is an axios
// instance and resolving the argument to a path.
//
// The proof gate is load-bearing, not belt-and-braces: EXPRESS_SPEC above
// matches `router.get('/x', handler)` / `app.post(...)` as PROVIDERS. A
// receiver admitted on spelling alone would re-emit every Express route in the
// repo as a consumer of itself, on both sides of every cross-repo pair.
const HTTP_CLIENT_SPEC: PatternSpec<Record<string, never>> = {
meta: {},
query: `
(call_expression
function: (member_expression
object: (identifier) @obj (#eq? @obj "axios")
object: (identifier) @obj
property: (property_identifier) @http_method (#match? @http_method "^(get|post|put|delete|patch)$"))
arguments: (arguments . [(string) (template_string)] @path))
arguments: (arguments . (_) @path))
`,
};
@ -153,12 +153,10 @@ const AXIOS_OBJECT_SPEC: PatternSpec<Record<string, never>> = {
};
interface NodePatternBundle {
controller: CompiledPatterns<Record<string, never>>;
methodDecorator: CompiledPatterns<Record<string, never>>;
express: CompiledPatterns<Record<string, never>>;
fetchNoOptions: CompiledPatterns<Record<string, never>>;
fetchWithOptions: CompiledPatterns<Record<string, never>>;
axios: CompiledPatterns<Record<string, never>>;
httpClient: CompiledPatterns<Record<string, never>>;
jqueryShorthand: CompiledPatterns<Record<string, never>>;
jqueryAjax: CompiledPatterns<Record<string, never>>;
axiosObject: CompiledPatterns<Record<string, never>>;
@ -172,12 +170,10 @@ function compileBundle(language: unknown, name: string): NodePatternBundle {
patterns: [spec],
} satisfies LanguagePatterns<Record<string, never>>);
return {
controller: mk(NEST_CONTROLLER_SPEC, 'nest-controller'),
methodDecorator: mk(NEST_METHOD_SPEC, 'nest-method-decorator'),
express: mk(EXPRESS_SPEC, 'express'),
fetchNoOptions: mk(FETCH_NO_OPTIONS_SPEC, 'fetch-no-options'),
fetchWithOptions: mk(FETCH_WITH_OPTIONS_SPEC, 'fetch-with-options'),
axios: mk(AXIOS_SPEC, 'axios'),
httpClient: mk(HTTP_CLIENT_SPEC, 'http-client'),
jqueryShorthand: mk(JQUERY_SHORTHAND_SPEC, 'jquery-shorthand'),
jqueryAjax: mk(JQUERY_AJAX_SPEC, 'jquery-ajax'),
axiosObject: mk(AXIOS_OBJECT_SPEC, 'axios-object'),
@ -188,33 +184,6 @@ const JAVASCRIPT_BUNDLE = compileBundle(JavaScript, 'javascript-http');
const TYPESCRIPT_BUNDLE = compileBundle(TypeScript.typescript, 'typescript-http');
const TSX_BUNDLE = compileBundle(TypeScript.tsx, 'tsx-http');
const NEST_DECORATOR_TO_HTTP: Record<string, string> = {
Get: 'GET',
Post: 'POST',
Put: 'PUT',
Delete: 'DELETE',
Patch: 'PATCH',
};
/**
* Find the nearest enclosing class_declaration for a node, or null.
*/
function findEnclosingClass(node: Parser.SyntaxNode): Parser.SyntaxNode | null {
let cur: Parser.SyntaxNode | null = node.parent;
while (cur) {
if (cur.type === 'class_declaration') return cur;
cur = cur.parent;
}
return null;
}
function joinPath(prefix: string, sub: string): string {
const cleanPrefix = prefix.replace(/^\/+/, '').replace(/\/+$/, '');
const cleanSub = sub.replace(/^\/+/, '');
if (!cleanPrefix) return `/${cleanSub}`;
return `/${cleanPrefix}/${cleanSub}`;
}
/**
* Walk `pair` children of an `object` literal and return the unquoted
* string/template_string value for the first pair whose key matches one
@ -237,68 +206,6 @@ function readStringProp(objectNode: Parser.SyntaxNode, keyNames: readonly string
return null;
}
/**
* For a standalone `decorator` node (child of class_body / program),
* find the related `class_declaration` node that it decorates. In
* tree-sitter-typescript the decorator is placed before the class
* declaration as a sibling (when decorating a class) or inside the
* class_body before a method_definition (when decorating a method);
* we walk the parent chain until we find the enclosing class.
*/
function findDecoratedClass(decoratorNode: Parser.SyntaxNode): Parser.SyntaxNode | null {
const parent = decoratorNode.parent;
if (!parent) return null;
// Case 1: decorator is a sibling of the class_declaration at program /
// export_statement level. Walk forward through siblings until we find
// the class_declaration this decorator belongs to.
for (let i = 0; i < parent.namedChildCount; i++) {
const child = parent.namedChild(i);
if (child && child.id === decoratorNode.id) {
for (let j = i + 1; j < parent.namedChildCount; j++) {
const next = parent.namedChild(j);
if (!next) continue;
if (next.type === 'decorator') continue; // adjacent decorators stack
if (next.type === 'class_declaration') return next;
if (next.type === 'export_statement') {
// `export class Foo { ... }` wraps the declaration.
for (let k = 0; k < next.namedChildCount; k++) {
const inner = next.namedChild(k);
if (inner?.type === 'class_declaration') return inner;
}
}
break;
}
break;
}
}
// Case 2: decorator is inside a class_body (decorating a method) —
// walk up to the enclosing class_declaration.
return findEnclosingClass(decoratorNode);
}
/**
* For a method-level decorator node (child of class_body before a
* method_definition), find the method_definition it decorates.
*/
function findDecoratedMethod(decoratorNode: Parser.SyntaxNode): Parser.SyntaxNode | null {
const parent = decoratorNode.parent;
if (!parent || parent.type !== 'class_body') return null;
for (let i = 0; i < parent.namedChildCount; i++) {
const child = parent.namedChild(i);
if (child && child.id === decoratorNode.id) {
for (let j = i + 1; j < parent.namedChildCount; j++) {
const next = parent.namedChild(j);
if (!next) continue;
if (next.type === 'decorator') continue;
if (next.type === 'method_definition') return next;
return null;
}
return null;
}
}
return null;
}
/**
* Map each named import's LOCAL binding to its DECLARED export name and source
* module, by walking the file's `import { x as y } from 'm'` statements. Lets
@ -309,12 +216,22 @@ function findDecoratedMethod(decoratorNode: Parser.SyntaxNode): Parser.SyntaxNod
*/
function buildImportMap(tree: Parser.Tree): Map<string, { name: string; module: string }> {
const map = new Map<string, { name: string; module: string }>();
const walk = (node: Parser.SyntaxNode): void => {
// Both walks are explicit-stack, not recursive. They visit EVERY node of the
// file, so their depth is the source's nesting depth — and `scan` may not
// throw: a `RangeError` here escapes to `sync.ts`, which records the repo as
// an unexplained "missing repo" and drops every contract of every kind for
// it, silently. A file nesting template substitutions ~4 000 deep (well
// inside what tree-sitter will parse) was enough.
const stack: Parser.SyntaxNode[] = [tree.rootNode];
while (stack.length > 0) {
const node = stack.pop() as Parser.SyntaxNode;
if (node.type === 'import_statement') {
const sourceNode = node.childForFieldName('source');
const module = sourceNode ? unquoteLiteral(sourceNode.text) : null;
if (module !== null) {
const collect = (n: Parser.SyntaxNode): void => {
const inner: Parser.SyntaxNode[] = [node];
while (inner.length > 0) {
const n = inner.pop() as Parser.SyntaxNode;
if (n.type === 'import_specifier') {
const nameNode = n.childForFieldName('name');
const aliasNode = n.childForFieldName('alias');
@ -323,81 +240,266 @@ function buildImportMap(tree: Parser.Tree): Map<string, { name: string; module:
map.set(local.text, { name: nameNode.text, module });
}
}
for (let i = 0; i < n.namedChildCount; i++) {
const c = n.namedChild(i);
if (c) collect(c);
}
};
collect(node);
for (const c of n.namedChildren) inner.push(c);
}
}
// An import statement cannot contain another one, and the inner loop has
// already visited its whole subtree.
continue;
}
for (let i = 0; i < node.namedChildCount; i++) {
const c = node.namedChild(i);
if (c) walk(c);
}
};
walk(tree.rootNode);
for (const c of node.namedChildren) stack.push(c);
}
return map;
}
function scanBundle(bundle: NodePatternBundle, tree: Parser.Tree): HttpDetection[] {
// ─── Repo pre-pass: cross-file route tables + HTTP client instances ──
//
// Both halves of a real consumer call live in files OTHER than the call site:
// the client is created in `lib/axios.config.ts` and the path in
// `shared/api-routes.ts`. A per-file scan cannot see either, which is why the
// literal-only patterns matched almost nothing on application code. The
// pre-pass builds a repo-wide fact map once so `scan` can resolve both.
interface NodeRepoContext {
readonly facts: JsRepoFacts;
}
/**
* Shared across the three JS/TS plugins.
*
* JS, TS and TSX are distinct `HttpLanguagePlugin` objects, and the
* orchestrator caches `prepareRepo` output per plugin NAME — so a polyglot
* frontend would build this identical map three times. All three are called
* with the same memoized file-list array within one extraction run, so keying
* on that array's identity collapses the work to a single pass. A later run
* passes a different array and correctly rebuilds; the weak key lets the old
* map be collected with it.
*/
const REPO_CONTEXT_BY_FILE_LIST = new WeakMap<readonly string[], NodeRepoContext>();
/**
* Skip ceiling for the pre-pass, mirroring the analyzer's default
* `--max-file-size`. A minified bundle is megabytes on one line and defines no
* route table a human wrote; parsing it costs far more than it can return.
*/
const MAX_PREPASS_FILE_BYTES = 512 * 1024;
/** Repo-relative path in the same POSIX form the fact map is keyed by. */
function normalizeRel(rel: string): string {
return rel.replace(/\\/g, '/').replace(/^\.\//, '');
}
/** The grammar a JS/TS-family file should be parsed with, or null if not one. */
function grammarForFile(rel: string): unknown | null {
const lower = rel.toLowerCase();
if (lower.endsWith('.tsx')) return TypeScript.tsx;
if (/\.[cm]?ts$/.test(lower)) return TypeScript.typescript;
if (/\.[cm]?jsx?$/.test(lower)) return JavaScript;
return null;
}
function buildNodeRepoContext(args: {
files: string[];
readFile: (rel: string) => string | null;
parseSource: (parser: Parser, src: string) => Parser.Tree | null;
}): NodeRepoContext {
const cached = REPO_CONTEXT_BY_FILE_LIST.get(args.files);
if (cached) return cached;
const byFile = new Map<string, JsModuleFacts>();
const parsers = new Map<unknown, Parser>();
const parserFor = (language: unknown): Parser => {
let parser = parsers.get(language);
if (!parser) {
parser = new Parser();
parser.setLanguage(language as Parameters<Parser['setLanguage']>[0]);
parsers.set(language, parser);
}
return parser;
};
// Cost gate, in the spirit of the sibling `python.ts` pre-pass: every fact
// this map holds exists to prove a receiver is an axios instance or to fold a
// path for one. A repo where the string `axios` appears nowhere can prove no
// receiver, so every parse below is dead work — and parsing is the expensive
// half (measured 4.36 s / +258 MB RSS over 827 TypeScript files, on top of
// the parse `getScanInput` already does).
// Only the file's identity is carried between the passes, never its text: a
// large monorepo's whole source tree held in one array at once is the shape
// that produced the analyzer's scale problems, and the second read is cheap
// beside the parse it gates.
const eligible: Array<{ rel: string; language: unknown }> = [];
let sawAxios = false;
for (const rel of args.files) {
const language = grammarForFile(rel);
if (language === null) continue;
const content = args.readFile(rel);
// `MAX_PREPASS_FILE_BYTES` is a BYTE ceiling; `String.length` counts UTF-16
// code units, which under-counts every multi-byte source.
if (content === null || Buffer.byteLength(content, 'utf8') > MAX_PREPASS_FILE_BYTES) continue;
if (!sawAxios && content.includes('axios')) sawAxios = true;
eligible.push({ rel, language });
}
if (sawAxios) {
for (const { rel, language } of eligible) {
try {
const content = args.readFile(rel);
if (content === null) continue;
// `parseSource` belongs INSIDE the guard: `safe-parse.ts` throws
// `ParseTimeoutError` and makes catching it a per-caller obligation, and
// `prepareRepo` is contractually non-throwing. One escape here left the
// fact map unwritten for the WHOLE repo — and, because the orchestrator
// caches per plugin NAME, made all three JS/TS plugins re-walk it and
// fail the same way before falling back to literal-only scanning.
const tree = args.parseSource(parserFor(language), content);
if (!tree) continue;
byFile.set(normalizeRel(rel), extractJsModuleFacts(tree));
} catch {
// One malformed file must never abort the pre-pass — it simply stays
// unresolved, exactly as it is without this pass at all.
}
}
}
const ctx: NodeRepoContext = { facts: buildJsRepoFacts(byFile) };
REPO_CONTEXT_BY_FILE_LIST.set(args.files, ctx);
return ctx;
}
/** The repo facts to resolve against, or null when there was no pre-pass. */
function resolveFactsFor(
repoContext: RepoContext | undefined,
fileRel: string | undefined,
): JsRepoFacts | null {
const ctx = repoContext as NodeRepoContext | undefined;
if (!ctx || fileRel === undefined) return null;
return ctx.facts;
}
/**
* Whether a folded first argument is plausibly a URL path.
*
* The query now captures ANY first argument, and "it folded to a string" is not
* "it is a path" — `normalizeConsumerPath` is a canonicalizer, not a validator,
* and it happily turns non-paths into contracts that exact-match real provider
* routes:
*
* api.get(CONFIG.TIMEOUT) // "5000" -> http::GET::/{param}
* api.post(MSG.ERROR) // "Could not reach the …" -> http::POST::/could not reach the server
*
* `/{param}` matches every one-segment provider route in the group, and
* `matching.exclude_links_param_only_paths` defaults to `false`. A path whose
* leading term is an unresolved placeholder is refused for the same reason —
* nothing pins where it starts. (`resolveJsPathExpression` already refuses those
* it folded itself; this also covers the literal fallback below.)
*/
function looksLikeHttpPath(path: string): boolean {
if (path === '') return false;
if (/^https?:\/\//i.test(path)) return true;
// A `${…}` term is a runtime value that `normalizeConsumerPath` rewrites to
// `{param}`; its SOURCE text can be any expression (`${draft ? 'a' : 'b'}`,
// `${id ?? ''}`), so the checks below have to run against the normalized
// shape. Testing the raw source dropped every partially folded path whose
// unresolved term happened to contain a space.
const shape = path.replace(/\$\{[^}]+\}/g, '{param}');
if (/\s/.test(shape)) return false;
if (shape.startsWith('{param}')) return false;
// An all-digit string is a path only when it is written as one. A leading
// slash is that evidence: `client.get('/123')` is a route whose segment the
// consumer normalizer reads as `{param}`, while a bare `"5000"` folded out of
// `CONFIG.TIMEOUT` is a timeout that would match every one-segment provider.
if (!shape.startsWith('/')) return !/^\d+$/.test(shape);
return true;
}
/**
* The path a consumer call's first argument denotes.
*
* Prefers full resolution against the repo facts; falls back to the raw
* literal for a string/template node so a repo with no pre-pass (or an
* unresolvable reference) behaves exactly as it did before.
*
* `fileKey` is already `normalizeRel`-ed by the caller — see `scanBundle`.
*
* `legacyShape` marks the exact combination this pattern matched BEFORE it was
* widened: the literal receiver `axios` with a string or template-string first
* argument. That combination keeps its old output verbatim, so this PR adds
* detections without removing any — `axios.get(`${API_BASE}/users`)` still
* yields `/{param}/users`. Everything the widened query NEWLY admits (any other
* receiver, or any non-literal argument) has to clear the gates.
*/
function resolveConsumerPath(
pathNode: Parser.SyntaxNode,
facts: JsRepoFacts | null,
fileKey: string | undefined,
legacyShape: boolean,
): string | null {
if (facts && fileKey !== undefined) {
const resolved = resolveJsPathExpression(fileKey, pathNode, facts);
if (resolved !== null && looksLikeHttpPath(resolved)) return resolved;
}
// The fallback is deliberately gated on node TYPE: `unquoteLiteral` returns
// unrecognized input unchanged, so handing it a `member_expression` would
// yield the literal text `API_ROUTE_PATH.LINKS` as if it were a URL path.
if (pathNode.type !== 'string' && pathNode.type !== 'template_string') return null;
const literal = unquoteLiteral(pathNode.text);
// The fold bails past `MAX_FOLD_LENGTH`; the raw source it falls back to has
// no such bound and lands in `contractId` and `meta.path` all the same.
if (literal === null || literal.length > MAX_FOLD_LENGTH) return null;
return legacyShape || looksLikeHttpPath(literal) ? literal : null;
}
function scanBundle(
bundle: NodePatternBundle,
tree: Parser.Tree,
repoContext?: RepoContext,
fileRel?: string,
): HttpDetection[] {
const out: HttpDetection[] = [];
// Repo-wide constant / HTTP-client facts, when the orchestrator ran the
// `prepareRepo` pre-pass. Absent for a bare `scan(tree)` call, in which case
// every cross-file resolution below floors to the literal-only behavior.
const facts = resolveFactsFor(repoContext, fileRel);
// The fact map is keyed by `normalizeRel(rel)`. Normalizing at ONE place and
// using that value for every read keeps the two sides in step: the receiver
// gate used to read the raw `fileRel`, and `isHttpClientRef` cannot tell a key
// miss from "not a client", so any non-POSIX path (glob v13 has no
// `posix: true` and its walker joins with the platform separator; graph rows
// are a second unnormalized source) silently returned zero consumers.
const fileKey = fileRel === undefined ? undefined : normalizeRel(fileRel);
// Local-binding → { declared export name, module } for the file's named
// imports, so an express handler that is an imported (possibly aliased)
// symbol resolves to the real definition rather than its local alias text.
const importMap = buildImportMap(tree);
// NestJS: collect `@Controller('prefix')` class decorators, keyed by
// the `class_declaration` they decorate.
const prefixByClassId = new Map<number, string>();
for (const match of runCompiledPatterns(bundle.controller, tree)) {
const prefixNode = match.captures.prefix;
const decoratorNode = match.captures.ctrl_decorator;
if (!prefixNode || !decoratorNode) continue;
const prefix = unquoteLiteral(prefixNode.text);
if (prefix === null) continue;
const classNode = findDecoratedClass(decoratorNode);
if (!classNode) continue;
prefixByClassId.set(classNode.id, prefix);
}
// NestJS: method-level @Get/@Post/... decorators. The decorator's
// arguments list may be empty (`@Get()`), a string (`@Get('path')`),
// or something else (which we skip).
for (const match of runCompiledPatterns(bundle.methodDecorator, tree)) {
const decNode = match.captures.dec;
const argsNode = match.captures.args;
const decoratorNode = match.captures.method_decorator;
if (!decNode || !argsNode || !decoratorNode) continue;
const httpMethod = NEST_DECORATOR_TO_HTTP[decNode.text];
if (!httpMethod) continue;
const methodNode = findDecoratedMethod(decoratorNode);
if (!methodNode) continue;
const enclosingClass = findEnclosingClass(methodNode);
// Only emit NestJS detections when the class actually has a
// @Controller decorator — without it, the match is almost certainly
// something else (e.g. an unrelated library using similar names).
if (!enclosingClass || !prefixByClassId.has(enclosingClass.id)) continue;
const prefix = prefixByClassId.get(enclosingClass.id) ?? '';
let rawPath = '/';
const firstArg = argsNode.namedChild(0);
if (firstArg && (firstArg.type === 'string' || firstArg.type === 'template_string')) {
const unquoted = unquoteLiteral(firstArg.text);
if (unquoted !== null) rawPath = unquoted;
}
// Get the method name from the decorated method_definition.
const methodNameNode = methodNode.childForFieldName('name');
const name = methodNameNode?.text ?? null;
// NestJS: delegated to the indexer's extractor rather than re-queried here.
// Two independent readings of the same decorators is how the layers drift:
// the local scan saw only `class_declaration` (never `abstract class`), only
// five of the nine verbs, only a positional string `@Controller('x')`, and
// — worst — INVENTED `/` for a method path it could not read, so
// `@Get(ROUTES.SEARCH)` became a `GET /venues` contract that the graph, which
// correctly drops it, has no Route node for. "A missing route is a coverage
// limit; an invented one is a lie" (ARCHITECTURE.md). Calling the extractor
// makes that divergence structurally impossible, exactly as the
// `scanDataRouteTables` call below already does for static route tables.
//
// `filePath` rides only on the returned struct and never reaches the
// `HttpDetection`, so a bare `scan(tree)` with no `fileRel` passes '' rather
// than losing the routes. `lineOffset` is 0: the group scanner parses whole
// files, so `lineNumber` is already the absolute 1-based line this
// `HttpDetection.line` wants.
for (const route of extractNestRoutes(tree, fileRel ?? '', 0)) {
out.push({
role: 'provider',
framework: 'nest',
method: httpMethod,
path: joinPath(prefix, rawPath),
name,
line: methodNode.startPosition.row + 1,
method: route.httpMethod,
// The prefix travels separately at the ingestion layer, so the join is
// ours to do — with ingestion's own joiner, so the two layers cannot
// disagree about the URL either.
path: normalizeExtractedRoutePath(route.routePath, route.prefix ?? null),
name: route.handlerName ?? null,
line: route.lineNumber,
confidence: 0.8,
});
}
@ -471,22 +573,57 @@ function scanBundle(bundle: NodePatternBundle, tree: Parser.Tree): HttpDetection
});
}
// Consumer: axios.<verb>(url)
for (const match of runCompiledPatterns(bundle.axios, tree)) {
// Consumer: <httpClient>.<verb>(url) — `axios` itself, or any receiver the
// repo pre-pass proves is an axios instance.
for (const match of runCompiledPatterns(bundle.httpClient, tree)) {
const methodNode = match.captures.http_method;
const pathNode = match.captures.path;
if (!methodNode || !pathNode) continue;
const path = unquoteLiteral(pathNode.text);
if (path === null) continue;
out.push({
role: 'consumer',
framework: 'axios',
method: methodNode.text.toUpperCase(),
path,
name: null,
line: pathNode.startPosition.row + 1,
confidence: 0.7,
});
const objNode = match.captures.obj;
if (!methodNode || !pathNode || !objNode) continue;
// Receiver gate. `axios.get(...)` needs no proof; anything else must be
// traced to an `axios.create(...)` binding, or it is not ours to claim.
const receiver = objNode.text;
// Cross-file resolution is the only work in this file that walks a
// repo-wide graph, and `HttpLanguagePlugin.scan` may not throw: a single
// hostile call site must cost its own detection, not the repo's whole
// contract set (`sync.ts` catches a throw here as an unexplained "missing
// repo", silently, for every contract type).
try {
// The receiver is admitted when it IS the axios module — the bare
// spelling this pattern trusted before it was widened, or a declared
// import/require of 'axios' under any name — or when it traces to an
// `axios.create(...)` instance. Nothing else.
const isModule =
facts === null || fileKey === undefined
? receiver === 'axios'
: isAxiosNamespace(fileKey, receiver, facts);
if (!isModule) {
if (!facts || fileKey === undefined) continue;
if (!isHttpClientRef(fileKey, receiver, facts)) continue;
}
const path = resolveConsumerPath(
pathNode,
facts,
fileKey,
isModule && (pathNode.type === 'string' || pathNode.type === 'template_string'),
);
if (path === null) continue;
out.push({
role: 'consumer',
framework: 'axios',
method: methodNode.text.toUpperCase(),
path,
name: null,
line: pathNode.startPosition.row + 1,
confidence: 0.7,
});
} catch {
// Unresolvable is the same outcome as unresolved — skip this call site.
}
}
// Consumer: jQuery shorthand $.get(url) / $.post(url, ...)
@ -574,17 +711,20 @@ function scanBundle(bundle: NodePatternBundle, tree: Parser.Tree): HttpDetection
export const JAVASCRIPT_HTTP_PLUGIN: HttpLanguagePlugin = {
name: 'javascript-http',
language: JavaScript,
scan: (tree) => scanBundle(JAVASCRIPT_BUNDLE, tree),
prepareRepo: buildNodeRepoContext,
scan: (tree, repoContext, fileRel) => scanBundle(JAVASCRIPT_BUNDLE, tree, repoContext, fileRel),
};
export const TYPESCRIPT_HTTP_PLUGIN: HttpLanguagePlugin = {
name: 'typescript-http',
language: TypeScript.typescript,
scan: (tree) => scanBundle(TYPESCRIPT_BUNDLE, tree),
prepareRepo: buildNodeRepoContext,
scan: (tree, repoContext, fileRel) => scanBundle(TYPESCRIPT_BUNDLE, tree, repoContext, fileRel),
};
export const TSX_HTTP_PLUGIN: HttpLanguagePlugin = {
name: 'tsx-http',
language: TypeScript.tsx,
scan: (tree) => scanBundle(TSX_BUNDLE, tree),
prepareRepo: buildNodeRepoContext,
scan: (tree, repoContext, fileRel) => scanBundle(TSX_BUNDLE, tree, repoContext, fileRel),
};

View file

@ -15,20 +15,36 @@ import type { HttpDetection, HttpLanguagePlugin } from './types.js';
* Providers:
* - Laravel `Route::get/post/...`
*
* Consumers (string-literal URLs only):
* Consumers (string-literal URLs only, unless noted):
* - Laravel HTTP client: `Http::get/post/put/delete/patch($url)`
* - Guzzle / generic object method: `$client->get/post/...($url)`
* - `file_get_contents($url)`
* - `new Request($method, $host . $resourcePath)` — the openapi-generator-php
* / swagger-codegen client shape. `$resourcePath` is resolved via a
* single-scope backward constant fold (see `resolveLocalStringLiteral`),
* not a string literal at the call site itself.
*
* The pipeline already uses `PHP.php_only` for ingesting plain `.php`
* files (see `core/tree-sitter/parser-loader.ts`), and we do the same
* here so Laravel route files are parsed with the right grammar dialect.
*
* Scope notes: consumer patterns match string literals only. URLs built
* via binary concatenation (`$base . '/path'`), `sprintf`, or config
* lookup (`config('services.foo.base').'/path'`) are intentionally left
* for a follow-up — they require constant-folding the surrounding
* scope to be meaningful.
* Scope notes: consumer patterns match string literals only, with one
* narrow exception (above). URLs built via `sprintf`, config lookup
* (`config('services.foo.base').'/path'`), or a variable resolved from
* outside its own function/method body are intentionally left for a
* follow-up — they require constant-folding beyond one local scope to
* be meaningful.
*
* That narrow exception (`resolveLocalStringLiteral`) is a temporary,
* single-scope fallback, not this language's entry into the shared
* cross-file constant-fold used by the other languages in this plugin
* (`constant-resolver.ts`, wired in via `java-const-resolver.ts` /
* `python-const-resolver.ts` / `js-const-resolver.ts`). PHP has no such
* binding yet — adding one is a real, separate project (this repo's PHP
* import resolution for `use`-statements is its own multi-file subsystem
* under `ingestion/import-resolvers/php.ts`, built for symbol/scope
* resolution, not constant extraction) and is intentionally out of scope
* here. Tracked as a follow-up, not silently punted.
*/
const LARAVEL_ROUTE_SPEC: PatternSpec<Record<string, never>> = {
@ -71,11 +87,31 @@ const FILE_GET_CONTENTS_SPEC: PatternSpec<Record<string, never>> = {
`,
};
/**
* `new Request($method, $host . $resourcePath)` — the shape swagger-codegen /
* openapi-generator-php emit for every operation of a generated API client
* (Guzzle's `\GuzzleHttp\Psr7\Request`, or a bare `Request` behind a `use`
* import). Matches both `(name)` and `(qualified_name)` class references;
* `scan()` below filters to the last path segment being exactly `Request`
* and resolves the concatenated path argument (see `resolveLocalStringLiteral`).
*/
const GUZZLE_REQUEST_CTOR_SPEC: PatternSpec<Record<string, never>> = {
meta: {},
query: `
(object_creation_expression
[(name) (qualified_name)] @class
(arguments
. (argument (_) @methodArg)
. (argument (_) @pathArg)))
`,
};
interface PhpPatternBundle {
laravelRoute: CompiledPatterns<Record<string, never>>;
httpFacade: CompiledPatterns<Record<string, never>>;
guzzleMember: CompiledPatterns<Record<string, never>>;
fileGetContents: CompiledPatterns<Record<string, never>>;
guzzleRequestCtor: CompiledPatterns<Record<string, never>>;
}
const mk = (spec: PatternSpec<Record<string, never>>, suffix: string) =>
@ -90,6 +126,7 @@ const PHP_PATTERNS: PhpPatternBundle = {
httpFacade: mk(HTTP_FACADE_SPEC, 'http-facade'),
guzzleMember: mk(GUZZLE_MEMBER_SPEC, 'guzzle-member'),
fileGetContents: mk(FILE_GET_CONTENTS_SPEC, 'file-get-contents'),
guzzleRequestCtor: mk(GUZZLE_REQUEST_CTOR_SPEC, 'guzzle-request-ctor'),
};
/**
@ -129,6 +166,183 @@ function isHttpUrlLiteral(path: string): boolean {
return path.startsWith('http://') || path.startsWith('https://');
}
/**
* Last identifier segment of a class-name reference: `(name)` returns its
* own text, `(qualified_name)` returns the text of its last child (the
* unqualified class name — `\GuzzleHttp\Psr7\Request` → `Request`).
*/
function lastNameSegment(node: import('tree-sitter').SyntaxNode): string {
if (node.type === 'qualified_name') {
const last = node.child(node.childCount - 1);
return last ? last.text : node.text;
}
return node.text;
}
/**
* Return the variable at the LAST position of a `.`-concatenation
* expression, if (and only if) that position is a plain variable —
* generated clients build `<host> . <resourcePath>`, so the path segment
* is the one closest to the end.
*
* No fallback to an earlier operand: if the rightmost position is anything
* other than a variable, a parenthesized sub-expression, or a nested `.`
* concatenation (a literal, a function call, ...), that position is a real
* value we simply can't resolve — falling back to an EARLIER operand would
* silently substitute a different value (e.g. the host) for the one that's
* actually there. `null` here is a miss, not a signal to keep looking.
*/
function lastConcatVariable(
node: import('tree-sitter').SyntaxNode,
): import('tree-sitter').SyntaxNode | null {
if (node.type === 'variable_name') return node;
if (node.type === 'parenthesized_expression') {
const inner = node.namedChild(0);
return inner ? lastConcatVariable(inner) : null;
}
if (node.type === 'binary_expression') {
const operator = node.childForFieldName('operator');
if (!operator || operator.text !== '.') return null; // not concatenation
const right = node.childForFieldName('right');
return right ? lastConcatVariable(right) : null;
}
return null;
}
/**
* True if `node`'s subtree assigns to `$target` ANYWHERE inside it, at any
* depth (including inside nested functions — deliberately over-broad: a
* false positive here only costs a miss in the caller, never a wrong
* answer, so there's no need to be precise about scoping inside the probe
* itself).
*/
function containsAssignmentTo(node: import('tree-sitter').SyntaxNode, target: string): boolean {
if (node.type === 'assignment_expression') {
const lhs = node.childForFieldName('left');
if (lhs && lhs.type === 'variable_name' && lhs.text === target) return true;
}
for (let i = 0; i < node.namedChildCount; i++) {
const child = node.namedChild(i);
if (child && containsAssignmentTo(child, target)) return true;
}
return false;
}
/**
* True if an `anonymous_function` node's `use (...)` clause lists
* `$target`. PHP closures capture NOTHING automatically — only variables
* named in `use (...)` are visible inside — unlike arrow functions
* (`fn() => ...`), which auto-capture everything by value and have no
* `compound_statement` body of their own, so they're never seen as a
* `scope` by the walk below in the first place.
*/
function anonymousFunctionCaptures(
anonFn: import('tree-sitter').SyntaxNode,
target: string,
): boolean {
for (let i = 0; i < anonFn.namedChildCount; i++) {
const child = anonFn.namedChild(i);
if (!child || child.type !== 'anonymous_function_use_clause') continue;
for (let j = 0; j < child.namedChildCount; j++) {
const v = child.namedChild(j);
if (v && v.type === 'variable_name' && v.text === target) return true;
}
return false; // has a use(...) clause, but $target isn't in it
}
return false; // no use(...) clause at all — nothing is captured
}
/**
* Best-effort, single-scope constant fold: given a `variable_name` node
* referenced inside a `new Request(...)` argument, walk BACKWARD through
* the preceding statements of its immediately enclosing function/method
* body (or file scope, for top-level script code) looking for the nearest
* `$var = '<literal>';` assignment.
*
* "Enclosing body" is resolved level by level, not just the nearest
* `compound_statement` — a call site nested in `if`/`foreach`/`try` inside
* that function is still within the same function/method body, and a
* preceding assignment above that conditional must still be found. Each
* level searches only its own preceding siblings, then the search
* continues from the enclosing block itself one level up, UNLESS that
* block IS the body of a function/method/closure:
* - a regular `function_definition` or `method_declaration` boundary
* always stops the search — PHP gives a function or method no access
* to anything outside its own body (no automatic capture, no implicit
* global), so widening past one into the containing class or
* file-level scope would resolve a variable the call site could never
* actually see at runtime;
* - an `anonymous_function` boundary stops UNLESS `$target` is
* explicitly captured via `use (...)` — closures capture nothing
* automatically either.
* It stops at `program` regardless, for the case where the call site was
* at file/script scope all along.
*
* A preceding sibling that ISN'T a plain assignment but might reassign the
* target somewhere inside itself (an `if`/`foreach`/`try`/`switch`, ...)
* stops the search rather than being skipped over: whether that branch ran
* is unknown, so an older literal further back can't be trusted either.
*
* Deliberately conservative and bounded — no interprocedural resolution,
* no constant/property lookups. A miss just means the endpoint stays
* undetected, never a wrong one: this is exactly the class of case the
* module docblock flags as in-scope only for one local scope.
*/
function resolveLocalStringLiteral(varNode: import('tree-sitter').SyntaxNode): string | null {
const target = varNode.text; // includes the `$` sigil, e.g. "$resourcePath"
let cursor: import('tree-sitter').SyntaxNode = varNode;
for (;;) {
let scope: import('tree-sitter').SyntaxNode | null = cursor.parent;
while (scope && scope.type !== 'compound_statement' && scope.type !== 'program') {
scope = scope.parent;
}
if (!scope) return null;
let stmt: import('tree-sitter').SyntaxNode | null = cursor;
while (stmt && stmt.parent !== scope) stmt = stmt.parent;
if (!stmt) return null;
let sibling = stmt.previousNamedSibling;
while (sibling) {
if (sibling.type === 'expression_statement') {
const inner = sibling.namedChild(0);
if (inner && inner.type === 'assignment_expression') {
const lhs = inner.childForFieldName('left');
if (lhs && lhs.type === 'variable_name' && lhs.text === target) {
// The NEAREST assignment to this variable wins, full stop — an
// older literal further back is shadowed by this one even when
// this one isn't itself a resolvable string (`$v = f();`).
const rhs = inner.childForFieldName('right');
return rhs && rhs.type === 'string' ? phpStringText(rhs) : null;
}
}
} else if (containsAssignmentTo(sibling, target)) {
return null; // reassigned somewhere inside a conditional/loop/try
}
sibling = sibling.previousNamedSibling;
}
if (scope.type === 'program') return null;
const enclosing = scope.parent;
if (enclosing && enclosing.type === 'anonymous_function') {
// Closures capture nothing automatically — only what's use()'d.
if (!anonymousFunctionCaptures(enclosing, target)) return null;
} else if (
enclosing &&
(enclosing.type === 'function_definition' || enclosing.type === 'method_declaration')
) {
// A regular function or method boundary — NOT a closure. PHP gives
// these no access to anything outside their own body (no automatic
// capture, no implicit global): widening past one into the
// containing class body or file-level scope would resolve a
// variable the call site could never actually see at runtime.
return null;
}
cursor = scope; // one block up: search resumes from this block's own position
}
}
export const PHP_HTTP_PLUGIN: HttpLanguagePlugin = {
name: 'php-http',
language: PHP.php_only,
@ -136,12 +350,16 @@ export const PHP_HTTP_PLUGIN: HttpLanguagePlugin = {
// ingestion, so the graph is authoritative for PHP providers (#2138 Part 2).
routeCoverage: 'complete',
// Consumer signals scan() can detect: Laravel `Http::<verb>`, Guzzle client
// `->get/post/.../request(...)`, and `file_get_contents` of an HTTP URL. A
// provider-covered file with any of these must still be parsed (ingestion
// emits no FETCHES for PHP). Conservative — the `->verb(` shape over-matches
// ordinary method calls, which only costs a parse, never data.
// `->get/post/.../request(...)`, `file_get_contents` of an HTTP URL, and a
// generated-client `new ...Request(...)` constructor call. A provider-covered
// file with any of these must still be parsed (ingestion emits no FETCHES for
// PHP). Conservative — the `->verb(`/`new ...Request(` shapes over-match
// ordinary method calls and unrelated constructors, which only costs a
// parse, never data.
hasConsumerSignals(content) {
return /Http::|file_get_contents|->\s*(get|post|put|delete|patch|request)\s*\(/i.test(content);
return /Http::|file_get_contents|->\s*(get|post|put|delete|patch|request)\s*\(|new\s+[\\\w]*Request\s*\(/i.test(
content,
);
},
scan(tree) {
const out: HttpDetection[] = [];
@ -222,6 +440,62 @@ export const PHP_HTTP_PLUGIN: HttpLanguagePlugin = {
});
}
for (const match of runCompiledPatterns(PHP_PATTERNS.guzzleRequestCtor, tree)) {
const classNode = match.captures.class;
const methodArg = match.captures.methodArg;
const pathArg = match.captures.pathArg;
if (!classNode || !methodArg || !pathArg) continue;
// PHP class names are case-insensitive at the language level, and
// `hasConsumerSignals` above matches case-insensitively (`/i`) for
// the same reason — this comparison must agree with it, or a valid
// `new request(...)` / `new \NS\REQUEST(...)` call would be waved
// through the parse-skip gate as a signal and then silently dropped
// here.
if (lastNameSegment(classNode).toLowerCase() !== 'request') continue;
// Path: a direct string literal, or the last variable in a
// concatenation chain (see `lastConcatVariable`) resolved to a
// locally-assigned literal.
let path: string | null = null;
if (pathArg.type === 'string') {
path = phpStringText(pathArg);
} else {
const lastVar = lastConcatVariable(pathArg);
path = lastVar ? resolveLocalStringLiteral(lastVar) : null;
}
if (path === null || !isHttpClientPath(path)) continue;
// The HTTP verb is a literal, a local variable resolved the same way
// as the path (see `resolveLocalStringLiteral` above), or — commonly
// in generated clients — a parameter of the enclosing builder method
// fixed by ITS caller, not by this call site. That last case needs
// the same interprocedural reach the module docblock rules out, so it
// falls through to a wildcard verb, matching this project's own
// convention for a contract whose verb isn't pinned (see manifest
// links, `http::*::`).
let method: string | null = null;
if (methodArg.type === 'string') {
method = phpStringText(methodArg);
} else if (methodArg.type === 'variable_name') {
method = resolveLocalStringLiteral(methodArg);
}
out.push({
role: 'consumer',
framework: 'guzzle-request-ctor',
method: method ? method.toUpperCase() : '*',
path,
name: null,
// Line of the path ARGUMENT, not the `new Request(` call — same
// choice the other three consumer patterns in this file make, but
// this is the one pattern where the two routinely differ (generated
// clients wrap the call across multiple lines). Line-span
// containment still resolves to the right symbol either way.
line: pathArg.startPosition.row + 1,
confidence: 0.6,
});
}
return out;
},
};

View file

@ -1,4 +1,9 @@
import type { ContractType, CrossLink, GroupManifestLink, StoredContract } from '../types.js';
import type {
CrossLink,
GroupManifestLink,
ManifestContractType,
StoredContract,
} from '../types.js';
import type { CypherExecutor } from '../contract-extractor.js';
import { logger } from '../../logger.js';
@ -366,11 +371,11 @@ export class ManifestExtractor {
* equality matching without requiring wildcard logic downstream.
*
* NOTE on exhaustiveness: the switch covers every current
* `ContractType` variant and falls through to a `never` assertion so
* manifest-declared contract type and falls through to a `never` assertion so
* TypeScript fails the build if a new variant is added without a
* corresponding case.
*/
private buildContractId(type: ContractType, contract: string): string {
private buildContractId(type: ManifestContractType, contract: string): string {
switch (type) {
case 'http': {
// Canonicalize method casing and path separators so logically

View file

@ -2,7 +2,11 @@ import fs from 'node:fs/promises';
import path from 'node:path';
import type { CypherExecutor } from '../contract-extractor.js';
import type { GroupManifestLink, ContractRole } from '../types.js';
import { shouldIgnorePath, loadIgnoreRules } from '../../../config/ignore-service.js';
import {
shouldIgnorePath,
loadIgnoreRules,
isHardcodedIgnoredDirectoryAtPath,
} from '../../../config/ignore-service.js';
import { logger } from '../../logger.js';
interface PythonPackageMeta {
@ -161,9 +165,11 @@ async function findPythonFiles(repoPath: string): Promise<string[]> {
for (const entry of entries) {
const childRel = rel ? `${rel}/${entry.name}` : entry.name;
if (entry.isDirectory()) {
const childPath = path.join(dir, entry.name);
if (shouldIgnorePath(childRel)) continue;
if (isHardcodedIgnoredDirectoryAtPath(repoPath, childPath)) continue;
if (ig && ig.ignores(childRel + '/')) continue;
await walk(path.join(dir, entry.name), childRel);
await walk(childPath, childRel);
} else if (entry.name.endsWith('.py')) {
if (shouldIgnorePath(childRel)) continue;
if (ig && ig.ignores(childRel)) continue;

View file

@ -0,0 +1,201 @@
/**
* Cross-process single-writer lock for one group's persisted state (R9).
*
* A group sync ends by REPLACING `contracts.json` and rebuilding `bridge.lbug`
* from a snapshot it computed minutes earlier. Two syncs of the same group that
* overlap therefore do not merge — the second one's write simply overwrites the
* first one's, and whichever finishes last wins with a registry assembled from
* repo state the other run never saw. Nothing detects it afterwards: both runs
* report success, and the group's contracts silently describe a mixture that was
* never true at any instant. This module serializes that section so one sync at
* a time can be inside it.
*
* WHERE THE LOCK LIVES. On a dedicated `sync-lock` directory INSIDE the group
* directory — mirroring `withRegistryLock`, which locks a `registry-lock`
* directory beside the registry rather than the registry's own directory
* (repo-manager.ts). {@link acquireIndexLock} is NOT reentrant and its file
* backend writes `analyze.lock` into the directory it is handed, so pointing it
* at a directory that some other code path might also lock — or that already
* holds a per-repo index slot — reintroduces exactly the collision the registry
* lock's own comment warns about. `<groupDir>/sync-lock` is a namespace nothing
* else claims: group directories live under `~/.gitnexus/groups/<name>` (or
* `$GITNEXUS_HOME`), never under a repo's `.gitnexus[/branches/<slug>]`.
*
* WHY IT FAILS CLOSED, unlike the registry lock. `withRegistryLock` degrades to
* running UNLOCKED on timeout, and that is right for it: it guards a sub-second
* JSON read/merge/write on a latency-critical path (`augment` runs on every
* editor tool call), and running unlocked is merely the pre-lock status quo. A
* group sync is the opposite on every axis — it is long, expensive, operator-
* initiated, and its lost update destroys contracts rather than a registry field.
* A sync that cannot be protected must not run at all, and there are three
* distinct ways it can fail to be protected; all three throw
* {@link GroupSyncLockError}:
*
* 1. TIMEOUT — the holder is still alive when the ceiling elapses.
* 2. LOCK-FREE DEGRADATION — `acquireIndexLock` answers a read-only or
* permission-denied filesystem with a no-op handle that is byte-identical
* to a real one at the API boundary. That is a deliberate tolerance for
* `analyze` (an unwritable index dir rejects every write anyway, so the
* lock is moot), but here it would hand back a handle that protects
* nothing while the sync went on to attempt its writes. The handle now
* carries {@link IndexLockHandle.lockFree}, so we can see it and refuse.
* 3. ANY OTHER ACQUIRE FAILURE — e.g. `sync-lock` cannot be created because a
* regular file already occupies the path. Silently proceeding on an error
* we did not anticipate is the same unprotected run under another name.
*
* WHY THE CEILING IS PASSED EXPLICITLY. The magnitude is not the point — 10
* minutes deliberately matches `acquireIndexLock`'s own default, because a group
* sync is analyze-shaped and a legitimately queued second sync must be able to
* wait out a full first one (the registry lock's 5s is sized for a sub-second
* merge and is the wrong model here). The reason to pass it is
* `resolveTimeoutMs`: it prefers an explicit argument over
* `GITNEXUS_INDEX_LOCK_TIMEOUT_MS`, and that variable's `<= 0` case resolves to
* `Number.POSITIVE_INFINITY`. Inheriting it would let an environment turn this
* lock's fail-closed timeout into an unbounded hang.
*
* ACQUIRED EXACTLY ONCE, by `syncGroup`, around its whole persist section.
* Nothing it calls beneath that point — `writeContractRegistry`,
* `refreshPreservedBridgeMeta`, `writeBridgeUnlocked` — takes this lock; a
* second acquisition would deadlock a non-reentrant primitive on the HAPPY
* path, not on some edge case. `bridge-db.ts` exports the swap in both forms
* for exactly that reason: `writeBridgeUnlocked` for the held-lock caller
* (`syncGroup`), and the `writeBridge` wrapper, which acquires here, for direct
* callers that are outside the region. The same split `repo-manager.ts` uses
* for `registerRepoUnlocked` / `registerRepo`.
*
* SCOPE CAVEAT (recorded, not solved): the default socket backend uses Linux
* abstract sockets, which are network-namespace-scoped. Two containers that
* share a bind-mounted group directory but sit in separate netns will NOT
* contend, exactly as documented for the index lock itself; forcing
* `GITNEXUS_INDEX_LOCK_BACKEND=file` is what covers that deployment.
*/
import path from 'node:path';
import {
acquireIndexLock,
IndexLockTimeoutError,
type IndexLockHandle,
} from '../../storage/index-lock.js';
import { logger } from '../logger.js';
/** Lock-directory name inside the group directory. Never the group dir itself. */
export const GROUP_SYNC_LOCK_DIRNAME = 'sync-lock';
/** The dedicated lock namespace for one group: `<groupDir>/sync-lock`. */
export const getGroupSyncLockDir = (groupDir: string): string =>
path.join(groupDir, GROUP_SYNC_LOCK_DIRNAME);
/**
* Wait ceiling for the group sync lock (10 min). See the module header: the
* magnitude matches `acquireIndexLock`'s analyze-sized default on purpose; the
* reason it is passed EXPLICITLY is to keep `GITNEXUS_INDEX_LOCK_TIMEOUT_MS`
* (whose `<= 0` case means unbounded) from turning fail-closed into a hang.
*/
export const GROUP_SYNC_LOCK_TIMEOUT_MS = 600_000;
/** Which of the three fail-closed exits produced a {@link GroupSyncLockError}. */
export type GroupSyncLockFailure = 'timeout' | 'lock-free' | 'unavailable';
/**
* A group sync could not be protected, so it did not run. One class for all
* three exits so both callers — the CLI command and the MCP service — have a
* single thing to catch and report.
*/
export class GroupSyncLockError extends Error {
readonly reason: GroupSyncLockFailure;
readonly groupDir: string;
constructor(reason: GroupSyncLockFailure, groupDir: string, message: string, cause?: unknown) {
super(message, cause === undefined ? undefined : { cause });
this.name = 'GroupSyncLockError';
this.reason = reason;
this.groupDir = groupDir;
}
}
/**
* Run `operation` as the only group sync touching `groupDir`, or throw
* {@link GroupSyncLockError} without running it at all.
*
* The lock is released in a `finally`, so it is dropped whether the operation
* succeeds or throws.
*/
export const withGroupSyncLock = async <T>(
groupDir: string,
operation: () => Promise<T>,
): Promise<T> => {
let handle: IndexLockHandle;
// The wrapper times the acquisition itself. `IndexLockTimeoutError` carries
// `holder` and `holderKnown` and nothing else — the elapsed wait exists only
// inside its inherited message string, so the figure has to be measured here
// to be reported without that message. `Date.now()` matches how the primitive
// measures its own wait.
const acquireStartedAt = Date.now();
try {
handle = await acquireIndexLock(getGroupSyncLockDir(groupDir), {
timeoutMs: GROUP_SYNC_LOCK_TIMEOUT_MS,
// `acquireIndexLock`'s own `log` texts name an "analyze" holder, which
// misattributes a group-sync wait — the same reason `withRegistryLock`
// supplies its own line instead of passing `log` through.
onWaitStart: () =>
logger.info(
{ groupDir },
'Waiting for another GitNexus process to finish syncing this group…',
),
});
} catch (err) {
// The inherited message names "another gitnexus analyze" as the holder —
// a cause this detection path cannot establish. Nothing but a group sync
// ever locks `<groupDir>/sync-lock` (see the module header), and on the
// socket backend the holder is not identifiable at all. Re-word it around
// what IS known: which group, which operation, and how long we waited.
if (err instanceof IndexLockTimeoutError) {
throw new GroupSyncLockError(
'timeout',
groupDir,
`Timed out after ${Date.now() - acquireStartedAt}ms waiting for the sync lock on ` +
`group "${path.basename(groupDir)}" (${getGroupSyncLockDir(groupDir)}). ` +
// `holderKnown` is false on the socket backend and on the file
// backend's malformed/vanished-lock timeouts, where `holder` is a
// placeholder (`pid -1`). Presenting that as a real owner would be the
// same unestablished claim in a new form.
(err.holderKnown
? `Held by pid ${err.holder.pid} on ${err.holder.hostname} ` +
`(invocation ${err.holder.invocationId}). `
: `The lock stayed held for the whole wait, but this lock backend ` +
`cannot identify the holder. `) +
`Nothing was written and this group was not synced. ` +
`Re-run once the other sync of this group has finished.`,
err,
);
}
throw new GroupSyncLockError(
'unavailable',
groupDir,
`Could not acquire the sync lock for this group (${getGroupSyncLockDir(groupDir)}): ` +
`${err instanceof Error ? err.message : String(err)}. Nothing was written.`,
err,
);
}
if (handle.lockFree) {
// A handle that owns nothing. Release it anyway (it is a no-op, but the
// contract is that every handle is released) and refuse to run: this sync
// would otherwise write `contracts.json` and `bridge.lbug` with no
// protection at all against a concurrent sync doing the same.
handle.release();
throw new GroupSyncLockError(
'lock-free',
groupDir,
`The sync lock for this group could not be created at ` +
`${getGroupSyncLockDir(groupDir)} (read-only or permission-denied filesystem), ` +
`so this sync cannot be protected against a concurrent one. Nothing was written. ` +
`Make the group directory writable and re-run.`,
undefined,
);
}
try {
return await operation();
} finally {
handle.release();
}
};

View file

@ -37,7 +37,13 @@ function buildNoisyContractFilter(
: new Set<string>();
const excludeParamOnly = matchingConfig?.exclude_links_param_only_paths === true;
return function isNoisyHttpContract(contractId: string): boolean {
return function isNoisyContract(contractId: string): boolean {
if (contractId.startsWith('graphql::')) {
const parts = contractId.split('::');
if (parts.length < 3) return false;
const field = parts.slice(2).join('::');
return excludePaths.has(field) || excludePaths.has(`/${field}`);
}
if (!contractId.startsWith('http::')) return false;
const parts = contractId.split('::');
if (parts.length < 3) return false;

View file

@ -6,7 +6,16 @@
import fsp from 'node:fs/promises';
import path from 'node:path';
import { checkStaleness } from '../git-staleness.js';
import { loadMeta, type RepoMeta } from '../../storage/repo-manager.js';
import {
canonicalizePath,
loadMeta,
readRegistryStrict,
registryPathEquals,
type RegistryEntry,
type RepoMeta,
} from '../../storage/repo-manager.js';
import { crossRepoCompleteness } from './completeness.js';
import { recordedMatchStages, recordedRepoList } from './completeness.js';
import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
import {
fileMatchesServicePrefix,
@ -222,10 +231,39 @@ function isCrossLink(raw: unknown): raw is CrossLink {
return typeof o.contractId === 'string' && typeof o.type === 'string';
}
/**
* Does the global registry hold a row for this configured group member?
*
* Consulted only once resolution has ALREADY failed, to choose which of the
* two failures `group status` reports. It mirrors the two tiers
* `LocalBackend.resolveRepo` matches a bare group-config value on — the
* registry `name`, case-insensitively, and the repo `path` — and deliberately
* stops short of its hashed-id and partial-name tiers: those exist to be
* generous about what an operator typed, while this predicate only decides
* between two labels, and a looser match here would relabel a genuine registry
* miss as an unresolvable row. That is the same conflation this reporting
* exists to remove, pointed the other way.
*/
function registryIdentifies(entries: RegistryEntry[], registryName: string): boolean {
const wantedName = registryName.toLowerCase();
// Path equality goes through the registry's own rule rather than a local
// `resolve` + platform-case compare. `canonicalizePath` also follows symlinks,
// so a row registered through one and looked up through the other still
// matches — and there is one definition of registry path identity instead of
// a third, weaker copy of it living in a group module nobody would grep.
const wantedPath = canonicalizePath(registryName);
return entries.some((entry) => {
if (typeof entry.name === 'string' && entry.name.toLowerCase() === wantedName) return true;
if (typeof entry.path !== 'string') return false;
return registryPathEquals(canonicalizePath(entry.path), wantedPath);
});
}
async function loadContractRegistryResilient(
groupDir: string,
): Promise<
{ ok: true; registry: ContractRegistry; skippedCorrupt: number } | { ok: false; error: string }
| { ok: true; registry: ContractRegistry; skippedCorrupt: number; suppressionUnreadable: boolean }
| { ok: false; error: string }
> {
const filePath = path.join(groupDir, 'contracts.json');
let raw: string;
@ -288,6 +326,17 @@ async function loadContractRegistryResilient(
}
}
// Bound once: the gate is a full array scan and the ternary below used it twice.
const recordedUnreadable = recordedRepoList(base.unreadableRepos);
const recordedSuppressed = recordedMatchStages(base.suppressedMatchStages);
// Present-but-unreadable is NOT the same as absent. `recordedMatchStages` is
// all-or-nothing, so garbage collapses to `undefined` — and a consumer that
// reads `undefined` as "nothing was suppressed" would throw that safety away
// and report a registry it could not parse as complete. Absent stays
// legitimate (a registry predating the field); only a value that was there
// and unreadable forces the answer to a floor.
const suppressionUnreadable =
base.suppressedMatchStages !== undefined && recordedSuppressed === undefined;
const registry: ContractRegistry = {
version: typeof base.version === 'number' ? base.version : 0,
generatedAt: typeof base.generatedAt === 'string' ? base.generatedAt : '',
@ -295,12 +344,89 @@ async function loadContractRegistryResilient(
base.repoSnapshots && typeof base.repoSnapshots === 'object' && base.repoSnapshots !== null
? (base.repoSnapshots as Record<string, { indexedAt: string; lastCommit: string }>)
: {},
missingRepos: Array.isArray(base.missingRepos) ? (base.missingRepos as string[]) : [],
// Same gate as `groupStatus` uses on the same field, for the same reason:
// `Array.isArray` alone waves through `[{repo:'x'}]`, and `groupContracts`
// now returns this list AND folds it into its completeness answer, so a
// value we could not read would be reported as a repo name. `missingRepos`
// has always been required, so — unlike `unreadableRepos` below — there is
// no "not recorded" state to preserve: an unreadable value degrades to empty.
missingRepos: recordedRepoList(base.missingRepos) ?? [],
// Spread, not `?? []`. `ContractRegistry.unreadableRepos` documents absence
// as "not recorded", and a registry written before the field existed has no
// opinion about which indexes were readable. Normalizing that to `[]` hands
// the caller "the last sync found none unreadable" — an unmeasured state
// rendered as a clean result, which is the same conflation this whole
// change removes.
...(recordedUnreadable ? { unreadableRepos: recordedUnreadable } : {}),
// Same omit-when-unrecorded rule. This reader rebuilds the envelope field
// by field with no spread of `base`, so a new on-disk field is dropped
// unless it is named here.
...(recordedSuppressed ? { suppressedMatchStages: recordedSuppressed } : {}),
contracts,
crossLinks,
};
return { ok: true, registry, skippedCorrupt };
return { ok: true, registry, skippedCorrupt, suppressionUnreadable };
}
/**
* Validate a boolean MCP parameter — reject, never coerce.
*
* `Boolean(params.x)` is the trap this exists to close: the string `"false"`
* is truthy, and an LLM caller emitting JSON produces that shape routinely.
* While `exactOnly` was inert the coercion was harmless; now that it gates a
* matching stage, a coerced `"false"` suppresses that stage and persists a
* registry with fewer cross-links than the caller asked for.
*
* Absent stays absent-as-false (the unchanged default). Anything that is not
* a real boolean returns a structured `{ error }`, mirroring
* `validateImpactMode` — the established shape for this boundary, and the one
* `groupSync`'s other guards already use.
*/
function validateBooleanParam(name: string, raw: unknown): { value: boolean } | { error: string } {
if (raw === undefined) return { value: false };
if (typeof raw === 'boolean') return { value: raw };
return { error: `Invalid "${name}": expected true or false, got ${describeValue(raw)}.` };
}
/**
* Render an untrusted value for an error message, without throwing.
*
* `JSON.stringify` is the right shape here — it distinguishes the string
* `"false"` from the boolean, which is the whole point of the message — but it
* throws on a BigInt and on a cyclic object. A validator whose ERROR path can
* throw does not return the structured `{ error }` it promises: the caller gets
* a rejected promise instead of feedback it can act on, and `callTool` is
* reachable directly, so neither input is hypothetical.
*/
function describeValue(raw: unknown): string {
try {
const rendered = JSON.stringify(raw);
// `undefined`, a function, or a symbol serialize to `undefined`.
return rendered ?? String(raw);
} catch {
return typeof raw === 'bigint' ? `${raw}n` : Object.prototype.toString.call(raw);
}
}
/**
* Refuse parameters this tool used to accept and no longer does.
*
* The CLI rejects a removed flag outright because commander errors on an
* unknown option. The MCP path had no equivalent, so an agent working from a
* cached tool schema kept sending a retired key and was told nothing — the
* removal took away discoverability, not acceptance. Naming the parameter is
* what lets the caller correct itself on the next call.
*/
function rejectRetiredSyncParams(params: Record<string, unknown>): { error: string } | null {
for (const retired of ['skipEmbeddings', 'allowStale']) {
if (params[retired] !== undefined) {
return {
error: `"${retired}" was removed and is no longer accepted. Drop it from the call.`,
};
}
}
return null;
}
export class GroupService {
@ -332,6 +458,13 @@ export class GroupService {
async groupSync(params: Record<string, unknown>): Promise<unknown> {
const name = String(params.name ?? '').trim();
if (!name) return { error: 'name is required' };
// Before anything reads the group off disk: the MCP SDK does not enforce a
// tool's advertised `inputSchema` and `callTool` is reachable directly, so
// this method is the real validation boundary.
const exactOnly = validateBooleanParam('exactOnly', params.exactOnly);
if ('error' in exactOnly) return exactOnly;
const retired = rejectRetiredSyncParams(params);
if (retired) return retired;
const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
let config: GroupConfig;
try {
@ -347,18 +480,39 @@ export class GroupService {
// MCP server startup entirely and off every non-sync group call. The CLI
// already does exactly this at `cli/group.ts`'s sync command.
const { syncGroup } = await import('./sync.js');
const result = await syncGroup(config, {
groupDir,
exactOnly: Boolean(params.exactOnly),
skipEmbeddings: Boolean(params.skipEmbeddings),
allowStale: Boolean(params.allowStale),
verbose: Boolean(params.verbose),
});
const { GroupSyncLockError } = await import('./group-lock.js');
let result: Awaited<ReturnType<typeof syncGroup>>;
try {
result = await syncGroup(config, {
groupDir,
exactOnly: exactOnly.value,
// `verbose` is deliberately NOT accepted here. It gates diagnostics on
// the server's logger, which an MCP caller cannot observe — advertising
// it would be exactly the kind of knob that does not do what the caller
// expects. `SyncOptions.verbose` stays for the CLI, which can see them.
});
} catch (err) {
// Fails closed (R9): this sync could not be protected against a concurrent
// one, so it did not run and wrote nothing. Return it through the same
// error channel a missing group uses — NEVER as a success payload of zeroes,
// which an agent would read as "the group genuinely has no contracts".
if (!(err instanceof GroupSyncLockError)) throw err;
return { error: err.message };
}
return {
contracts: result.contracts.length,
crossLinks: result.crossLinks.length,
unmatched: result.unmatched.length,
missingRepos: result.missingRepos,
unreadableRepos: result.unreadableRepos,
// The agent-facing half of the skipped-stage signal. A human sees it in
// the CLI summary; without this an agent would have to issue a second
// `group_contracts` call to discover its own sync was narrowed.
suppressedMatchStages: result.suppressedMatchStages,
// An agent that calls group_sync and then group_contracts a moment later
// can otherwise see contract counts that disagree with this payload, with
// nothing here explaining why the write was skipped.
registryOutcome: result.registryOutcome,
};
}
@ -386,7 +540,50 @@ export class GroupService {
);
contracts = contracts.filter((c) => !matchedIds.has(`${c.repo}::${c.contractId}`));
}
const out: Record<string, unknown> = { contracts, crossLinks: registry.crossLinks };
// `loadContractRegistryResilient` already applied `recordedRepoList` to
// both: `undefined` here is "the last sync recorded no opinion" (a registry
// written before the field existed, or a value we could not read), which is
// NOT the same answer as the measured empty list.
const { unreadableRepos, missingRepos } = registry;
// `incompleteRepos` is dropped on this surface only because the two lists it
// is derived from are returned verbatim right below; the truncation triple is
// the part that has no other channel here.
const { incompleteRepos: _incompleteRepos, ...truncation } = crossRepoCompleteness({
unreadableRepos,
missingRepos,
suppressedMatchStages: registry.suppressedMatchStages,
// An unrecorded `unreadableRepos` means this listing cannot say which
// repos the sync failed to read — so it cannot claim to be complete.
// Either kind of unreadable provenance forces the floor: a sync that
// could not say which repos it read, or a suppression record that was
// present and could not be parsed. Reading the second as "nothing was
// suppressed" would report an unparseable registry as complete.
provenanceUnknown: unreadableRepos === undefined || loaded.suppressionUnreadable,
// A contract LISTING declares no scope to intersect with: it is the whole
// registry, so every configured repo is in scope by construction. The
// `type`/`repo`/`unmatchedOnly` filters above narrow which rows are shown,
// not which repos the sync had to read to produce them.
inScope: () => true,
});
const out: Record<string, unknown> = {
contracts,
crossLinks: registry.crossLinks,
missingRepos,
// Omitted rather than `[]` when the registry never recorded it — the same
// convention `skippedCorrupt` follows below, and the difference between
// "the sync measured zero unreadable repos" and "the sync never said".
...(unreadableRepos ? { unreadableRepos } : {}),
// Same omit-when-unrecorded rule, and deliberately NOT folded into the
// truncation triple below: that triple reports limits a run hit by
// accident, whose remedy is to fix the repo. A suppressed stage was
// asked for, and its remedy is to re-sync without that flag.
...(registry.suppressedMatchStages
? { suppressedMatchStages: registry.suppressedMatchStages }
: {}),
// The structured triple, verbatim from the impact surface (KTD10):
// `truncated` always, `truncationReason` + `riskEpistemic` with it.
...truncation,
};
if (skippedCorrupt > 0) out.skippedCorrupt = skippedCorrupt;
return out;
}
@ -573,17 +770,80 @@ export class GroupService {
}
const registry = await readContractRegistry(groupDir);
/**
* The STRICT global-registry read, deliberately — this is the one caller
* that has to tell "the registry says nothing about this repo" apart from
* "the registry could not be read at all", and only the strict mode can.
* `readRegistry`'s `catch { return [] }` collapses a malformed registry
* into an empty one, which is indistinguishable from a genuine absence and
* would report every configured repo as having no entry — the exact
* conflation the two labels below exist to remove.
*
* The consequence is accepted knowingly: the strict read rejects the WHOLE
* registry when any single row fails to identify a repo, so one malformed
* row renders every member of the group unresolvable, including members
* whose own rows are fine. That is the honest verdict — a registry the
* resolver cannot trust row-wise cannot be trusted about any row — and it
* is reported as an unresolved state, never as a clean one.
*
* ENOENT is not a failure in either mode: no registry file genuinely means
* nothing has been registered yet, so every repo is legitimately missing.
*/
let registryEntries: RegistryEntry[] | null = null;
let registryReadError: string | null = null;
try {
registryEntries = await readRegistryStrict();
} catch (err) {
registryReadError = err instanceof Error ? err.message : String(err);
}
const repoStatuses: Record<
string,
{
indexStale: boolean;
contractsStale: boolean;
/**
* Unchanged meaning: this repo has no usable status. It stays `true`
* for BOTH failures below, so a consumer written before the split
* still sees every unusable repo flagged. Reporting an unresolvable
* repo as `missing: false` would hand that consumer `indexStale:
* false` for a repo nothing was ever read from — a false all-clear.
*/
missing: boolean;
/**
* Which failure `missing` means: `false` is a genuine registry miss,
* `true` is an entry the resolver could not turn into a repo. Additive
* — always present on every row, so an agent can branch on it without
* having to treat an absent key as either answer.
*/
unresolvable: boolean;
/** Set only when `unresolvable`; says what could not be resolved. */
unresolvableReason?: string;
commitsBehind?: number;
}
> = {};
for (const [repoPath, registryName] of Object.entries(config.repos)) {
if (registryEntries === null) {
repoStatuses[repoPath] = {
indexStale: false,
contractsStale: false,
missing: true,
unresolvable: true,
unresolvableReason: `the global registry could not be read: ${registryReadError}`,
};
continue;
}
// Only `resolveRepo` is inside the try that produces the
// "did not resolve" label, so the label is earned rather than assumed.
// `loadMeta` and `checkStaleness` cannot throw — the first returns null on
// every error, the second catches everything — but the reading below them
// can, and did: `registry.repoSnapshots` is read off a bare
// `JSON.parse(...) as ContractRegistry` with no shape check, so a
// contracts.json missing that field threw a TypeError into this catch and
// reported every repo as an unresolvable GLOBAL-registry entry. That sent
// the operator to repair the wrong file. The optional chain below closes
// the crash; this split stops the next one being mislabelled the same way.
try {
const repoObj = await this.port.resolveRepo(registryName);
const meta: Partial<Pick<RepoMeta, 'lastCommit' | 'indexedAt'>> =
@ -593,7 +853,7 @@ export class GroupService {
? checkStaleness(repoObj.repoPath, meta.lastCommit)
: { isStale: true, commitsBehind: -1 };
const snapshot = registry?.repoSnapshots[repoPath];
const snapshot = registry?.repoSnapshots?.[repoPath];
const contractsStale =
snapshot && meta.indexedAt ? snapshot.indexedAt !== meta.indexedAt : !snapshot;
@ -601,17 +861,49 @@ export class GroupService {
indexStale: staleness.isStale,
contractsStale: Boolean(contractsStale),
missing: false,
unresolvable: false,
commitsBehind: staleness.commitsBehind,
};
} catch {
repoStatuses[repoPath] = { indexStale: false, contractsStale: false, missing: true };
} catch (err) {
// The registry read succeeded, so its answer about this row is
// trustworthy: a row that is there and still would not resolve is a
// different fact from a row that was never there, and the operator's
// next move differs (repair the entry vs. index the repo).
const known = registryIdentifies(registryEntries, registryName);
const reason = err instanceof Error ? err.message : String(err);
repoStatuses[repoPath] = {
indexStale: false,
contractsStale: false,
missing: true,
unresolvable: known,
...(known
? { unresolvableReason: `registry entry "${registryName}" did not resolve: ${reason}` }
: {}),
};
}
}
return {
group: name,
lastSync: registry?.generatedAt || null,
missingRepos: registry?.missingRepos || [],
// `readContractRegistry` is a bare `JSON.parse(...) as ContractRegistry`,
// so both of these are whatever the file happened to hold — the
// validation in `loadContractRegistryResilient` never runs on this path.
// A `contracts.json` carrying a string here reached `cli/group.ts` and
// died in `.join(', ')`, i.e. an unreadable registry crashing the command
// whose job is to explain unreadable things.
//
// `missingRepos` has always been required, so there is no "not recorded"
// state to preserve for it — an unreadable value degrades to empty.
missingRepos: recordedRepoList(registry?.missingRepos) ?? [],
// `unreadableRepos` does have one: absent means "not recorded", not
// "none" (see ContractRegistry), and a value we could not read is equally
// unrecorded. Reporting either as an empty list is the same conflation.
unreadableRepos: recordedRepoList(registry?.unreadableRepos),
// Same tri-state, same reason: `group status` is where an operator goes
// to ask "is this group's answer trustworthy right now", and a registry
// narrowed on purpose is a different answer from a complete one.
suppressedMatchStages: recordedMatchStages(registry?.suppressedMatchStages),
repos: repoStatuses,
};
}

View file

@ -5,7 +5,7 @@ import * as os from 'node:os';
import type { ContractRegistry } from './types.js';
import { writeFileAtomic } from '../../storage/fs-atomic.js';
const CONTRACTS_FILE = 'contracts.json';
export const CONTRACTS_FILE = 'contracts.json';
export function getDefaultGitnexusDir(): string {
return process.env.GITNEXUS_HOME || path.join(os.homedir(), '.gitnexus');
@ -30,6 +30,11 @@ export function getGroupDir(gitnexusDir: string, groupName: string): string {
return path.join(gitnexusDir, 'groups', groupName);
}
/** The registry path, so callers that stat or watch the file do not respell its name. */
export function getContractRegistryPath(groupDir: string): string {
return path.join(groupDir, CONTRACTS_FILE);
}
export async function writeContractRegistry(
groupDir: string,
registry: ContractRegistry,
@ -91,15 +96,11 @@ packages: {}
detect:
http: true
graphql: false
grpc: true
topics: true
shared_libs: true
embedding_fallback: true
matching:
bm25_threshold: 0.7
embedding_threshold: 0.65
max_candidates_per_step: 3
# exclude_links_paths: [/ping, /health, /healthcheck]
# exclude_links_param_only_paths: false
`;

Binary file not shown.

View file

@ -1,5 +1,14 @@
export type ContractType = 'http' | 'grpc' | 'thrift' | 'topic' | 'lib' | 'custom' | 'include';
export type MatchType = 'exact' | 'manifest' | 'wildcard' | 'bm25' | 'embedding';
export type ContractType =
| 'http'
| 'graphql'
| 'grpc'
| 'thrift'
| 'topic'
| 'lib'
| 'custom'
| 'include';
export type ManifestContractType = Exclude<ContractType, 'graphql'>;
export type MatchType = 'exact' | 'manifest' | 'wildcard';
export type ContractRole = 'provider' | 'consumer';
export interface GroupConfig {
@ -16,32 +25,29 @@ export interface GroupConfig {
export interface GroupManifestLink {
from: string;
to: string;
type: ContractType;
type: ManifestContractType;
contract: string;
role: ContractRole;
}
export interface DetectConfig {
http: boolean;
graphql?: boolean;
grpc: boolean;
thrift: boolean;
topics: boolean;
shared_libs: boolean;
embedding_fallback: boolean;
includes: boolean;
workspace_deps: boolean;
}
export interface MatchingConfig {
bm25_threshold: number;
embedding_threshold: number;
max_candidates_per_step: number;
/**
* HTTP paths to exclude from cross-link matching. Contracts at these paths
* HTTP paths or GraphQL root fields to exclude from cross-link matching. Contracts at these paths
* are still extracted and visible in the registry, but they don't produce
* cross-repo links. Useful for health-check endpoints (`/ping`, `/health`)
* that every service exposes and would otherwise create N×M false links.
* Trailing slashes are normalized before comparison.
* Trailing slashes are normalized before comparison. GraphQL fields may be
* written as `health` or `/health`.
* @default []
*/
exclude_links_paths?: string[];
@ -100,7 +106,34 @@ export interface ContractRegistry {
version: number;
generatedAt: string;
repoSnapshots: Record<string, RepoSnapshot>;
/** Configured repos with no entry in the registry. */
missingRepos: string[];
/**
* Configured repos that ARE registered but that this sync could not extract
* from — the index would not open (version skew, lock, corruption), or an
* extractor threw partway through. The two are one bucket because the
* consequence is one thing: NONE of that repo's contracts are in this
* registry. Distinct from `missingRepos`, which is "no entry in the
* registry at all" and needs a different answer from the operator.
*
* Optional so a registry written before this field existed still parses —
* absent means "not recorded", not "none".
*/
unreadableRepos?: string[];
/**
* Matching stages this sync was ASKED to skip, so a later reader can tell a
* short cross-link list from a complete one. `--exact-only` / `exactOnly`
* suppresses the wildcard stage, and the registry it writes is otherwise
* indistinguishable from one where that stage ran and matched nothing.
*
* Same tri-state as `unreadableRepos` and for the same reason: absent means
* "not recorded" (written before this field existed), `[]` means "measured,
* nothing was suppressed", and a populated list names the stages. Distinct
* from `truncated` / `truncationReason`, which report limits this run hit by
* accident — a suppressed stage is a deliberate request, and its remedy is
* "re-sync without exactOnly", not "fix the unreadable repo".
*/
suppressedMatchStages?: MatchType[];
contracts: StoredContract[];
crossLinks: CrossLink[];
}
@ -117,8 +150,36 @@ export interface RepoHandle {
storagePath: string;
}
/** Why local impact or fan-out stopped early (e.g. wall-clock budget exhausted). */
export type GroupImpactTruncationReason = 'timeout' | 'partial';
/**
* Why local impact or fan-out stopped early (e.g. wall-clock budget exhausted).
*
* `'timeout'` and `'partial'` are runtime limits — the same query can succeed on
* a retry. `'incomplete-sync'` is structural: the bridge itself was built from a
* sync that could not read every configured repo, so those repos' contracts are
* absent from every query against it until `gitnexus group sync` succeeds.
* `'suppressed-stage'` is structural too but has its own remedy: the sync was
* ASKED to skip a matching stage (`--exact-only`), so cross-links that stage
* would have found are absent by request. Retrying returns the same floor, and
* so does re-running the sync — the fix is to re-run it WITHOUT the flag. Kept a
* separate member rather than folded into `'incomplete-sync'` precisely because
* that remedy differs; telling an agent to repair a repo it read fine is the
* failure this distinction exists to prevent.
*
* A runtime array rather than a bare type union: every value here has to be
* explained on the agent-facing surface that returns it, and only an enumerable
* list lets a guard test assert that. A test that hand-lists the members passes
* forever once a fourth is added — which is the exact drift the guard exists to
* catch, so the list an agent is promised and the list the code can emit have
* to come from the same place.
*/
export const GROUP_IMPACT_TRUNCATION_REASONS = [
'timeout',
'partial',
'incomplete-sync',
'suppressed-stage',
] as const;
export type GroupImpactTruncationReason = (typeof GROUP_IMPACT_TRUNCATION_REASONS)[number];
export interface GroupImpactResult {
local: unknown;
@ -222,5 +283,118 @@ export interface BridgeHandle {
export interface BridgeMeta {
version: number;
generatedAt: string;
/**
* Size and mtime of the `bridge.lbug` this metadata was written for, so a
* reader can tell whether the two still belong together.
*
* `writeBridge` replaces the database and writes this file as two operations;
* a sync that stops between them leaves the PREVIOUS sync's metadata beside a
* new database, and `runGroupImpact` reads completeness from that metadata.
* Stamping the pair is what lets `bridgeMetaMatchesFile` reject the mismatch
* without anything having to be deleted — deleting the old metadata up front
* would lose it permanently on a swap that fails with the old database still
* in place, which is a normal Windows outcome when a read-only handle is held.
*
* Optional: metadata written before this existed carries no stamp. Such a
* file is not waved through — `bridgeMetaMatchesFile` falls back to comparing
* the two files' modification times, since a successful write orders the
* database rename before the metadata write and a database NEWER than the
* metadata beside it therefore cannot be the one it describes.
*
* That fallback proves WRITE ORDER, not provenance, and is wrong in both
* directions — a non-monotonic clock can make a mis-paired set read as
* ordered, and any copy or restore that rewrites the database's times after
* the metadata's demotes an intact legacy pair to a lower bound until the
* next sync re-stamps it. A stamped pair never reaches that fallback, which
* is the reason to prefer stamping over widening the heuristic. Both
* directions are spelled out at `bridgeMetaMatchesFile`.
*/
bridgeSize?: number;
bridgeMtimeMs?: number;
/**
* Reader-side only: true when `meta.json` parsed but one of its repo lists
* held a value that was not a list of repo paths.
*
* NEVER PERSISTED. `readBridgeMeta` sets it to describe what it found in the
* file; `writeBridgeMeta`'s only caller builds a fresh literal, so it cannot
* round-trip back to disk. It lives on this interface rather than on a
* reader-only subtype so that `readBridgeMeta` keeps the exact signature
* every caller already compiles against.
*
* The unusable value is dropped rather than normalized, so `missingRepos: []`
* on such a result is inert filler — this flag, not the empty list, is what
* says the bridge's provenance is unknown.
*/
repoListsUnreadable?: boolean;
/**
* Reader-side only: did this metadata pair with the `bridge.lbug` beside it,
* measured BEFORE anything opened that database?
*
* NEVER PERSISTED, for the same reason as `repoListsUnreadable`.
*
* The measurement has to happen before the open, and the answer has to be
* carried rather than recomputed. `runGroupImpact` and `runGroupTrace` open
* the bridge and only then ask about provenance, so a platform where a
* read-only open advances the database's mtime would fail every unstamped
* pair the moment it was read — turning back-compat for pre-stamp bridges
* into a repo-wide "everything is a lower bound". Whether any given
* LadybugDB build and OS does that is not something a reader should have to
* know, and it cannot be observed on Windows, where the in-process
* write→read reopen this would need is a documented limitation. Ordering the
* check ahead of the open makes the question moot on every platform instead
* of true on the ones that happen to be testable.
*/
pairedWithDatabase?: boolean;
/**
* PERSISTED, unlike the two fields above: the writer of this metadata could
* not establish that it describes the `bridge.lbug` beside it, and no reader
* may conclude otherwise from the files alone.
*
* Written by `refreshPreservedBridgeMeta` — the preserve path in `syncGroup`,
* which refreshes the diagnostic lists of a bridge it deliberately does NOT
* rebuild. That refresh rewrites `meta.json` ATOMICALLY, so this file's mtime
* becomes now while the database's stays old; and "metadata newer than the
* database beside it" is exactly the write order that
* `unstampedMetaPairsByWriteOrder` accepts. A refresh that simply carried the
* old fields forward would therefore convert a pair that check had been
* REJECTING into one it waves through — laundering unknown provenance into
* verified provenance, which is the fail-open this whole channel exists to
* close.
*
* "Just don't write a stamp" is not a substitute, and is worse: an unstamped
* metadata file is judged on the two file times, and the refresh has already
* moved them into the accepting order. The verdict has to be recorded IN the
* file, because the write that records it is itself what destroys the
* evidence a reader would otherwise use.
*
* `bridgeMetaMatchesFile` rejects on this ahead of both the stamp and the
* write-order heuristic, so `ensureBridgeReady` answers
* `pairedWithDatabase: false` and `bridgeProvenanceUnknown` reports the
* cross-repo answer as a lower bound. That is the ONE enforcement point; do
* not add a second reader for this field.
*
* Self-clearing: a successful `writeBridge` builds fresh metadata from a
* literal and never sets it, so the next good sync retires the marker without
* anything having to delete it.
*/
provenanceUnknown?: boolean;
missingRepos: string[];
/**
* Configured repos the sync that produced this bridge could not extract from
* (see `ContractRegistry.unreadableRepos`). Their contracts and every
* cross-link touching them are absent from `bridge.lbug`, so a cross-repo
* impact query against this bridge is a lower bound, not a verdict —
* `runGroupImpact` folds a non-empty value into its truncation fields for
* exactly that reason.
* Optional: a bridge written before this field existed does not record it.
*/
unreadableRepos?: string[];
/**
* Matching stages the sync that built this bridge was asked to skip.
* PERSISTED, like `unreadableRepos` and unlike `repoListsUnreadable` — a
* later `group_impact` or `trace` reads this bridge with no access to the run
* that produced it, and a narrowed graph is otherwise indistinguishable from
* a complete one. Same tri-state: absent is "not recorded".
*/
suppressedMatchStages?: MatchType[];
}

View file

@ -1,11 +1,14 @@
import { checkpointKind } from './embedding-checkpoint.js';
import type { RepoMeta } from '../storage/repo-manager.js';
import { scopeExtractionFailureTotal } from './ingestion/scope-resolution/scope-extraction-failures.js';
export const INDEX_INCOMPLETE_REASONS = [
'incremental-in-progress',
'embedding-checkpoint-pending',
'embedding-count-unverified',
'graph-write-collapsed',
'scope-extraction-unverified',
'scope-extraction-failed',
] as const;
export type IndexIncompleteReason = (typeof INDEX_INCOMPLETE_REASONS)[number];
@ -130,7 +133,14 @@ export function detectGraphWriteCollapse(
/** Stable machine-readable reasons an index cannot be certified complete. */
export function getIndexIncompleteReasons(
meta:
| Pick<RepoMeta, 'incrementalInProgress' | 'embeddingCheckpoint' | 'graphWriteCollapsed'>
| Pick<
RepoMeta,
| 'incrementalInProgress'
| 'embeddingCheckpoint'
| 'graphWriteCollapsed'
| 'scopeExtractionFailures'
| 'scopeExtractionReceipt'
>
| null
| undefined,
): IndexIncompleteReason[] {
@ -142,6 +152,13 @@ export function getIndexIncompleteReasons(
// answers from a graph missing most of its edges, which is indistinguishable
// from a codebase that genuinely has no such relationships.
if (meta?.graphWriteCollapsed) reasons.push('graph-write-collapsed');
if (meta?.scopeExtractionReceipt !== 1) {
reasons.push('scope-extraction-unverified');
} else {
const total = scopeExtractionFailureTotal(meta.scopeExtractionFailures);
if (total === undefined) reasons.push('scope-extraction-unverified');
else if (total > 0) reasons.push('scope-extraction-failed');
}
if (meta?.embeddingCheckpoint) {
// The three checkpoint kinds are not one operator-facing state. GUARDRAILS
// and the runbook document `embedding-checkpoint-pending` as "N node(s)

View file

@ -22,6 +22,27 @@ export interface FilePath {
const READ_CONCURRENCY = 32;
const ANALYZE_PROGRESS_ACTIVE_ENV = 'GITNEXUS_ANALYZE_PROGRESS_ACTIVE';
const DECLARATION_COMPANION_SUFFIXES = [
{ declaration: '.d.ts', implementations: ['.ts', '.tsx'] },
{ declaration: '.d.mts', implementations: ['.mts'] },
{ declaration: '.d.cts', implementations: ['.cts'] },
] as const;
const hasImplementationSibling = (
declarationPath: string,
scannedPaths: ReadonlySet<string>,
): boolean => {
const companion = DECLARATION_COMPANION_SUFFIXES.find(({ declaration }) =>
declarationPath.endsWith(declaration),
);
if (!companion) return false;
// Keep standalone declarations. Only suppress declaration output that sits
// beside an implementation with the corresponding module suffix.
const stem = declarationPath.slice(0, -companion.declaration.length);
return companion.implementations.some((suffix) => scannedPaths.has(`${stem}${suffix}`));
};
const warnLargeFileSkip = (message: string): void => {
if (process.env[ANALYZE_PROGRESS_ACTIVE_ENV] === '1') {
// analyze.ts routes console.warn through the progress bar logger while
@ -84,10 +105,17 @@ export const walkRepositoryPaths = async (
}
}
const scannedPaths = new Set(entries.map((entry) => entry.path));
const deduplicatedEntries = entries.filter(
(entry) => !hasImplementationSibling(entry.path, scannedPaths),
);
// Filesystem/glob traversal order is not stable across filesystems or repeated
// scans. Canonicalize once at the scan boundary so every downstream phase sees
// the same repository order.
entries.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
deduplicatedEntries.sort((left, right) =>
left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
);
if (skippedLarge > 0) {
const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
@ -123,7 +151,7 @@ export const walkRepositoryPaths = async (
}
}
return entries;
return deduplicatedEntries;
};
/**

View file

@ -19,7 +19,7 @@ import fs from 'fs/promises';
import path from 'path';
import { createRequire } from 'node:module';
import { isHardcodedIgnoredDirectory } from '../../../config/ignore-service.js';
import { isHardcodedIgnoredDirectoryAtPath } from '../../../config/ignore-service.js';
import { logger } from '../../logger.js';
import { resolveFile } from '../languages/typescript/file-candidates.js';
@ -361,9 +361,10 @@ export async function loadNodeWorkspacePackages(
for (const entry of entries) {
if (entry.isDirectory()) {
if (isHardcodedIgnoredDirectory(entry.name)) continue;
const childDir = path.join(dir, entry.name);
if (isHardcodedIgnoredDirectoryAtPath(repoRoot, childDir)) continue;
if (depth < SCAN_MAX_DEPTH) {
queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
queue.push({ dir: childDir, depth: depth + 1 });
}
continue;
}

View file

@ -49,13 +49,29 @@ export function resolvePhpImportInternal(
if (composerConfig) {
const sorted = getSortedPsr4(composerConfig);
const authoritativePsr4 =
composerConfig.authoritativePsr4 ?? new Set(sorted.map(([namespace]) => namespace));
let matchedAuthoritativeNamespace = false;
let hasAuthoritativeCatchAllNamespace = false;
const ownershipPath = normalized.replace(/^\/+/, '');
for (const [nsPrefix, dirPrefix] of sorted) {
const nsPrefixSlash = nsPrefix.replace(/\\/g, '/');
if (normalized.startsWith(nsPrefixSlash + '/') || normalized === nsPrefixSlash) {
const remainder = normalized.slice(nsPrefixSlash.length).replace(/^\//, '');
const nsPrefixSlash = nsPrefix.replace(/\\/g, '/').replace(/\/+$/, '');
const isCatchAll = nsPrefixSlash === '';
if (
isCatchAll ||
ownershipPath.startsWith(nsPrefixSlash + '/') ||
ownershipPath === nsPrefixSlash
) {
const isAuthoritative = authoritativePsr4.has(nsPrefix);
matchedAuthoritativeNamespace ||= isAuthoritative;
hasAuthoritativeCatchAllNamespace ||= isAuthoritative && isCatchAll;
const remainder = ownershipPath.slice(nsPrefixSlash.length).replace(/^\//, '');
// 1. Try class-style PSR-4: full path → file (e.g. App\Models\User → app/Models/User.php)
const filePath = dirPrefix + (remainder ? '/' + remainder : '') + '.php';
const mappedPath =
dirPrefix === '' ? remainder : dirPrefix + (remainder ? '/' + remainder : '');
const filePath = mappedPath + '.php';
if (allFiles.has(filePath)) return filePath;
if (index) {
const result = index.getInsensitive(filePath);
@ -64,45 +80,64 @@ export function resolvePhpImportInternal(
// 2. Function/constant fallback: strip last segment (symbol name), scan namespace directory.
// e.g. App\Models\getUser → directory app/Models/, find first .php file in that dir.
const lastSlash = remainder.lastIndexOf('/');
const nsDir = lastSlash >= 0 ? dirPrefix + '/' + remainder.slice(0, lastSlash) : dirPrefix;
// A root/catch-all mapping cannot safely infer a symbol's declaring
// file from an arbitrary sibling. The higher-level PHP resolver has
// parsed symbol-kind and declaration evidence for function/const
// imports; class imports must not inherit this directory heuristic.
if (!isCatchAll && dirPrefix !== '') {
const lastSlash = remainder.lastIndexOf('/');
const relativeNamespace = lastSlash >= 0 ? remainder.slice(0, lastSlash) : '';
const nsDir = relativeNamespace === '' ? dirPrefix : `${dirPrefix}/${relativeNamespace}`;
// Prefer SuffixIndex directory lookup (O(log n + matches)) over linear scan.
//
// An EMPTY bucket is a final answer, not a miss to retry with the scan
// below — which is what the `else` restores, and what this comment
// always claimed. Re-scanning on empty was the last per-import
// workspace traversal left in PHP resolution after #2901: any `use`
// matching a PSR-4 prefix whose directory holds no direct `.php` child
// (`App\Legacy\Ghost`) paid a full pass, measured at 201 traversals for
// 200 imports.
//
// The bucket is a superset of what the scan can find, for BOTH index
// shapes that reach here. A root-anchored direct child `nsDir/<x>.php`
// has its directory exactly equal to `nsDir`, and `nsDir` is always one
// of that directory's own suffixes — so the shared `dirMap` (keyed on
// every directory suffix) necessarily contains it, as does the
// root-anchored parity index `languages/php/import-target.ts` builds.
// Empty superset therefore implies empty scan, and control falls
// through to the next PSR-4 prefix exactly as before.
if (index) {
const candidates = index.getFilesInDir(nsDir, '.php');
if (candidates.length > 0) return candidates[0];
} else {
// Linear scan, only when a SuffixIndex is genuinely unavailable.
const nsDirPrefix = nsDir.endsWith('/') ? nsDir : nsDir + '/';
for (const f of allFiles) {
if (
f.startsWith(nsDirPrefix) &&
f.endsWith('.php') &&
!f.slice(nsDirPrefix.length).includes('/')
) {
return f;
// Prefer SuffixIndex directory lookup (O(log n + matches)) over linear scan.
//
// An EMPTY bucket is a final answer, not a miss to retry with the scan
// below — which is what the `else` restores, and what this comment
// always claimed. Re-scanning on empty was the last per-import
// workspace traversal left in PHP resolution after #2901: any `use`
// matching a PSR-4 prefix whose directory holds no direct `.php` child
// (`App\Legacy\Ghost`) paid a full pass, measured at 201 traversals for
// 200 imports.
//
// The bucket is a superset of what the scan can find, for BOTH index
// shapes that reach here. A root-anchored direct child `nsDir/<x>.php`
// has its directory exactly equal to `nsDir`, and `nsDir` is always one
// of that directory's own suffixes — so the shared `dirMap` (keyed on
// every directory suffix) necessarily contains it, as does the
// root-anchored parity index `languages/php/import-target.ts` builds.
// Empty superset therefore implies empty scan, and control falls
// through to the next PSR-4 prefix exactly as before.
if (index) {
const candidates = index.getFilesInDir(nsDir, '.php');
if (candidates.length > 0) return candidates[0];
} else {
// Linear scan, only when a SuffixIndex is genuinely unavailable.
const nsDirPrefix = nsDir.endsWith('/') ? nsDir : nsDir + '/';
for (const f of allFiles) {
if (
f.startsWith(nsDirPrefix) &&
f.endsWith('.php') &&
!f.slice(nsDirPrefix.length).includes('/')
) {
return f;
}
}
}
}
}
}
// A non-empty PSR-4 map is authoritative for namespaces it does not own.
// Preserve the existing mapped-namespace fallback behavior; #2962 is the
// conservative external-namespace gate, not a rewrite of mapped lookup.
// A catch-all owns every namespace, so its misses remain authoritative.
if (
authoritativePsr4.size > 0 &&
!composerConfig.hasUnmodeledAutoload &&
(!matchedAuthoritativeNamespace || hasAuthoritativeCatchAllNamespace)
) {
return null;
}
}
// Fallback: suffix matching (works without composer.json)

View file

@ -30,11 +30,103 @@ export interface GoModuleConfig {
export interface ComposerConfig {
/** Map of namespace prefix -> directory (e.g., "App\\" -> "app/") */
psr4: Map<string, string>;
/** Production `autoload.psr-4` prefixes that may gate external namespaces.
* Absent on legacy/manual configs, where every mapping remains authoritative. */
authoritativePsr4?: ReadonlySet<string>;
/** True when Composer also declares an autoload mechanism this resolver does not model. */
hasUnmodeledAutoload?: boolean;
/** PSR-4 entries sorted by namespace length descending (longest match wins).
* Cached once at config load time to avoid re-sorting on every import. */
psr4Sorted?: readonly [string, string][];
}
function normalizeComposerDirectory(baseDir: string, directory: string): string {
const normalizedBase = baseDir.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
const normalizedDirectory = directory
.replace(/\\/g, '/')
.replace(/^(?:\.\/)+/, '')
.replace(/\/+$/, '');
if (normalizedBase === '') return normalizedDirectory;
if (normalizedDirectory === '') return normalizedBase;
return path.posix.normalize(`${normalizedBase}/${normalizedDirectory}`);
}
/** Parse one Composer manifest without performing I/O. */
export function parseComposerConfig(value: unknown, baseDir = ''): ComposerConfig | null {
if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
const composer = value as Record<string, unknown>;
const autoload = composer.autoload;
const autoloadDev = composer['autoload-dev'];
if (autoload === undefined && autoloadDev === undefined) return null;
const psr4 = new Map<string, string>();
const authoritativePsr4 = new Set<string>();
let hasUnmodeledAutoload = false;
const addSection = (sectionValue: unknown, authoritative: boolean): void => {
if (typeof sectionValue !== 'object' || sectionValue === null || Array.isArray(sectionValue)) {
return;
}
const section = sectionValue as Record<string, unknown>;
if ('psr-0' in section || 'classmap' in section) hasUnmodeledAutoload = true;
const rawPsr4 = section['psr-4'];
if (typeof rawPsr4 !== 'object' || rawPsr4 === null || Array.isArray(rawPsr4)) return;
for (const [namespace, directories] of Object.entries(rawPsr4)) {
const stringDirectories = Array.isArray(directories)
? directories.filter((entry): entry is string => typeof entry === 'string')
: typeof directories === 'string'
? [directories]
: [];
if (stringDirectories.length === 0) continue;
if (stringDirectories.length > 1) hasUnmodeledAutoload = true;
const normalizedNamespace = namespace.replace(/\\+$/, '');
const normalizedDirectory = normalizeComposerDirectory(baseDir, stringDirectories[0]);
const existing = psr4.get(normalizedNamespace);
if (existing !== undefined && existing !== normalizedDirectory) {
hasUnmodeledAutoload = true;
continue;
}
if (existing === undefined) psr4.set(normalizedNamespace, normalizedDirectory);
if (authoritative) authoritativePsr4.add(normalizedNamespace);
}
};
// Production mappings win duplicate prefixes. Development mappings remain
// usable for test code but do not establish authority for the external gate.
addSection(autoload, true);
addSection(autoloadDev, false);
return { psr4, authoritativePsr4, hasUnmodeledAutoload };
}
/** Merge package-local Composer manifests into one repository-relative config. */
export function mergeComposerConfigs(configs: readonly ComposerConfig[]): ComposerConfig | null {
if (configs.length === 0) return null;
const psr4 = new Map<string, string>();
const authoritativePsr4 = new Set<string>();
let hasUnmodeledAutoload = false;
for (const config of configs) {
hasUnmodeledAutoload ||= config.hasUnmodeledAutoload === true;
for (const [namespace, directory] of config.psr4) {
const existing = psr4.get(namespace);
if (existing !== undefined && existing !== directory) {
hasUnmodeledAutoload = true;
continue;
}
if (existing === undefined) psr4.set(namespace, directory);
}
for (const namespace of config.authoritativePsr4 ?? config.psr4.keys()) {
authoritativePsr4.add(namespace);
}
}
return { psr4, authoritativePsr4, hasUnmodeledAutoload };
}
/** C# project config parsed from .csproj files */
export interface CSharpProjectConfig {
/** Root namespace from <RootNamespace> or assembly name (default: project directory name) */
@ -161,22 +253,13 @@ export async function loadComposerConfig(repoRoot: string): Promise<ComposerConf
try {
const composerPath = path.join(repoRoot, 'composer.json');
const raw = await fs.readFile(composerPath, 'utf-8');
const composer = JSON.parse(raw);
const psr4Raw = composer.autoload?.['psr-4'] ?? {};
const psr4Dev = composer['autoload-dev']?.['psr-4'] ?? {};
const merged = { ...psr4Raw, ...psr4Dev };
const psr4 = new Map<string, string>();
for (const [ns, dir] of Object.entries(merged)) {
const nsNorm = (ns as string).replace(/\\+$/, '');
const dirNorm = (dir as string).replace(/\\/g, '/').replace(/\/+$/, '');
psr4.set(nsNorm, dirNorm);
}
const config = parseComposerConfig(JSON.parse(raw));
if (config === null) return null;
if (isDev) {
logger.info(`📦 Loaded ${psr4.size} PSR-4 mappings from composer.json`);
logger.info(`📦 Loaded ${config.psr4.size} PSR-4 mappings from composer.json`);
}
return { psr4 };
return config;
} catch {
return null;
}

View file

@ -39,6 +39,11 @@ import type { CfgVisitor } from './cfg/types.js';
import type { NodeLabel } from 'gitnexus-shared';
import type { ExtractedRoute } from './route-extractors/laravel.js';
import type { SharedSpringType } from './route-extractors/spring-shared.js';
import type {
ModuleConstants,
Operand,
RepoConstants,
} from './route-extractors/constant-resolver.js';
import type Parser from 'tree-sitter';
import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
@ -46,6 +51,44 @@ import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
/** Tree-sitter query captures: capture name → AST node (or undefined if not captured). */
export type CaptureMap = Record<string, SyntaxNode | undefined>;
export interface DefinitionPropertiesContext {
readonly nodeLabel: NodeLabel;
readonly nodeName: string;
readonly definitionNode: SyntaxNode;
readonly parsedImports: readonly ParsedImport[];
readonly isExported: boolean;
}
export type DefinitionPropertiesExtractor = (
context: DefinitionPropertiesContext,
) => Readonly<Record<string, unknown>> | undefined;
/** Run optional provider enrichment without allowing one hook failure to drop
* the rest of the worker's language batch. */
export function runDefinitionPropertiesExtractor(
extractor: DefinitionPropertiesExtractor,
context: DefinitionPropertiesContext,
onError: (error: unknown) => void,
): Readonly<Record<string, unknown>> | undefined {
try {
return extractor(context);
} catch (error) {
onError(error);
return undefined;
}
}
/** Provider metadata is additive; graph identity and source-location fields
* supplied by the worker remain authoritative. */
export function mergeCanonicalDefinitionProperties<
TCanonical extends Readonly<Record<string, unknown>>,
>(
providerProperties: Readonly<Record<string, unknown>>,
canonicalProperties: TCanonical,
): Record<string, unknown> & TCanonical {
return { ...providerProperties, ...canonicalProperties } as Record<string, unknown> & TCanonical;
}
// ── Strategy tag types ─────────────────────────────────────────────────────
// NOTE: `MroStrategy` is defined in `gitnexus-shared` and re-exported above
// so `core/ingestion/model/resolve.ts` can consume it without importing from
@ -64,6 +107,25 @@ export interface AstFrameworkPatternConfig {
* Required fields must be explicitly set; optional fields have defaults
* applied by defineLanguage().
*/
/**
* Should the parse worker run {@link LanguageProviderConfig.extractModuleConstants}
* on this file?
*
* Exported so the DECISION is testable without booting a worker. It encodes the
* one rule that is easy to get backwards: a provider that declares no
* `moduleConstantHeuristic` harvests unconditionally. Writing the gate as
* `provider.moduleConstantHeuristic?.(content)` reads `undefined` as "skip" and
* silently disables the hook for every provider without a heuristic — which is
* exactly how Python's already-shipped harvest was turned off (#2391/#2980).
*/
export function shouldHarvestModuleConstants(
provider: Pick<LanguageProvider, 'extractModuleConstants' | 'moduleConstantHeuristic'>,
content: string,
): boolean {
if (!provider.extractModuleConstants) return false;
return !provider.moduleConstantHeuristic || provider.moduleConstantHeuristic(content);
}
interface LanguageProviderConfig {
// ── Identity ──────────────────────────────────────────────────────
readonly id: SupportedLanguages;
@ -252,6 +314,10 @@ interface LanguageProviderConfig {
* constant, and static declarations. Produces VariableInfo with type, visibility,
* isConst, isStatic, isMutable metadata. Default: undefined (no variable extraction). */
readonly variableExtractor?: VariableExtractor;
/** Add language-owned, structured properties to a definition node. Values
* cross the worker boundary and must therefore be structured-clone-safe.
* Shared ingestion code treats these properties as opaque. */
readonly definitionPropertiesExtractor?: DefinitionPropertiesExtractor;
/** Class/type extractor for deriving canonical qualified names for class-like symbols.
* Uses the same provider-driven strategy pattern as method/field extraction so
* namespace/package/module rules stay language-specific. */
@ -336,6 +402,58 @@ interface LanguageProviderConfig {
filePath: string,
) => SharedSpringType[];
/**
* Harvest this file's module-level string constants (#2391 core, #2980 Java
* parity) into the language-agnostic {@link ModuleConstants} shape, so the
* parse phase can resolve non-literal decorator route paths cross-file.
*
* The worker calls this when BOTH hold:
* - the provider declares no `moduleConstantHeuristic`, or the one it
* declares matched — syntax-driven, e.g. a `static final String` field or
* a constants-bearing import; NEVER a class-name pattern like
* `*Constants`, which silently drops route constants living in classes
* named e.g. `ApiPaths`/`Routes`, and
* - the extraction yields something resolvable (a literal, an expression, or
* an import binding), keeping the aggregate bounded on large repos.
*
* Default: undefined (no constant harvest; non-literal route paths of this
* language floor to skip).
*/
readonly extractModuleConstants?: (tree: Parser.Tree) => ModuleConstants;
/**
* Cheap content heuristic deciding whether the worker should run
* {@link extractModuleConstants} on a file. Guards the harvest cost on huge
* repos: files that cannot contribute (no constant-bearing syntax) are not
* walked. Must be syntax-driven (field/import shape), not identifier
* pattern-matching on class names.
*
* Default: undefined — harvest EVERY file of this language. A gate is opt-in
* because getting it wrong silently drops routes that already resolve, and a
* missed gate only costs time. Declare one only where the cost bites (Java's
* Maven monorepos) and only after checking it against every shape
* {@link extractModuleConstants} accepts.
*/
readonly moduleConstantHeuristic?: (content: string) => boolean;
/**
* Fold one file's non-literal route-path operand list
* (`routePathExpr`/`routePathOperands` of an `ExtractedDecoratorRoute`)
* against the repo-wide, file-path-keyed constant map, or null when it cannot
* be fully folded (skip floor — never a phantom path). Languages whose
* qualified refs resolve through class imports (`Outer.CONST`,
* `com.example.ApiPaths.USERS`) need this hook because the shared fold has no
* notion of qualified names; Python's bare-name refs use the shared default.
*
* Default: undefined (the parse phase falls back to the shared
* language-agnostic operand fold).
*/
readonly foldRoutePathOperands?: (
filePath: string,
operands: readonly Operand[],
repo: RepoConstants,
) => string | null;
// ── Noise filtering ────────────────────────────────────────────────
/** Built-in/stdlib names that should be filtered from the call graph for this language.
* Default: undefined (no language-specific filtering). */

View file

@ -15,6 +15,11 @@ import type { AstFrameworkPatternConfig } from '../language-provider.js';
import { createLeadingDocDescriptionExtractor } from '../utils/ast-helpers.js';
import { javaTypeConfig } from '../type-extractors/jvm.js';
import { extractSpringRoutes, extractSpringTypes } from '../route-extractors/spring.js';
import {
extractJavaModuleConstants,
foldJavaOperands,
isJavaConstantFile,
} from '../route-extractors/java-const-resolver.js';
import { javaExportChecker } from '../export-detection.js';
import { createImportResolver } from '../import-resolvers/resolver-factory.js';
import { javaImportConfig } from '../import-resolvers/configs/jvm.js';
@ -216,4 +221,26 @@ export const javaProvider = defineLanguage({
// ── Route extraction ──
extractDecoratorRoutes: extractSpringRoutes,
extractRouteInheritanceTypes: extractSpringTypes,
// ── #2980: constant harvest + qualified-ref fold for non-literal mapping
// paths (`@PostMapping(ApiPaths.SAVE_V1)`) — kept behind provider hooks so
// the shared ingestion layers stay language-agnostic. The heuristic is
// SYNTAX-driven (field/import shape), never a class-name pattern: constant
// classes are routinely named `ApiPaths`/`Routes`/`Paths`, which a
// `*Constants`-style gate would silently drop (review round-2 High finding).
extractModuleConstants: extractJavaModuleConstants,
// One gate, shared with the group side's `prepareRepo` pre-pass so the two
// subsystems cannot disagree about which files define constants (see
// JAVA_CONSTANT_FILE_RE — the previous divergence dropped constant
// INTERFACES on this side only, which cost the graph its Route nodes while
// the group still published the contract).
moduleConstantHeuristic: (content) =>
isJavaConstantFile(content) ||
// `import com.winning.opt.common.ApiPaths;` — ANY class import can bind a
// constant ref (`ApiPaths.X` at an annotation site), so gate on the
// general import shape, not on the imported name. Ingestion-only: this
// side needs the importing controller's own import table, which the group
// side instead derives lazily from the tree it already holds.
/\bimport\s+(?:static\s+)?[\w.]+\s*;/.test(content),
foldRoutePathOperands: foldJavaOperands,
});

View file

@ -1,16 +1,45 @@
import type { ParsedImport, WorkspaceIndex } from 'gitnexus-shared';
import { KOTLIN_EXTENSIONS } from '../../import-resolvers/jvm.js';
/**
* Adapter from `(ParsedImport, WorkspaceIndex)` to Kotlin declared-package
* resolution. Package facts and module bindings are already present on the
* parsed workspace, so this performs no source I/O and no path inference.
*/
import type { ParsedFile, ParsedImport, WorkspaceIndex } from 'gitnexus-shared';
import { perFileSet } from '../../import-resolvers/per-file-set.js';
import { getKotlinPackageFact } from './package-facts.js';
import {
buildKotlinPackageIndex,
resolveKotlinModule,
type KotlinPackageIndex,
} from './module-resolution.js';
export interface KotlinResolveContext {
readonly fromFile: string;
readonly allFilePaths: ReadonlySet<string>;
/** Stable parsed-workspace identity supplied by the resolution pass. */
readonly parsedFiles?: readonly ParsedFile[];
}
const getKotlinPackageIndex = perFileSet(
(parsedFiles: readonly ParsedFile[]): KotlinPackageIndex =>
buildKotlinPackageIndex(parsedFiles, getKotlinPackageFact),
);
export function resolveKotlinImportTarget(
parsedImport: ParsedImport,
workspaceIndex: WorkspaceIndex,
): string | readonly string[] | null {
const ctx = narrowContext(workspaceIndex);
if (ctx === null || parsedImport.kind === 'dynamic-unresolved') return null;
if (parsedImport.targetRaw === null || parsedImport.targetRaw === '') return null;
const parsedFiles = ctx.parsedFiles;
if (parsedFiles === undefined || parsedFiles.length === 0) return null;
return resolveKotlinModule(parsedImport.targetRaw, getKotlinPackageIndex(parsedFiles));
}
function narrowContext(workspaceIndex: WorkspaceIndex): KotlinResolveContext | null {
const ctx = workspaceIndex as KotlinResolveContext | undefined;
if (
ctx === undefined ||
@ -19,355 +48,5 @@ export function resolveKotlinImportTarget(
) {
return null;
}
if (parsedImport.kind === 'dynamic-unresolved') return null;
if (parsedImport.targetRaw === null || parsedImport.targetRaw === '') return null;
const target = parsedImport.targetRaw.endsWith('.*')
? parsedImport.targetRaw.slice(0, -2)
: parsedImport.targetRaw;
const pathLike = target.replace(/\./g, '/');
// Resolution tiers, most-specific first:
// 1. The full `pathLike` matches a `.kt`/`.kts` file directly
// (`import util.User` → `util/User.kt`).
// 2. Stripped (last-segment removed) `pathLike` matches a file
// directly (`import util.OneArg.writeAudit` → `util/OneArg.kt`,
// a class-or-object holding `writeAudit`).
// 3. Stripped `pathLike` matches a *package directory* — fan out to
// every `.kt`/`.kts` file inside it (`import models.getRepo` →
// `[models/User.kt, models/Repo.kt]`). The finalize pass walks
// each candidate and picks the one whose `localDefs` actually
// export the imported name (#1759).
// 4. Progressive prefix strip for deeper namespace aliases that
// don't map 1:1 to directories.
const index = getKotlinFileIndex(ctx.allFilePaths);
const direct = findKotlinFile(index, pathLike);
if (direct !== null) return direct;
// Only tiers 2 and 3 need the stripped path, and tier 1 answers most
// imports, so it is computed here rather than above. `lastIndexOf`/`slice`
// rather than `split`/`slice`/`join`: same result for every input, two
// allocations fewer per import. The `li < 0` guard is load-bearing —
// `'a'.slice(0, -1)` is `''`, which is what the split form yields for a
// single-segment path, but only by accident of `[].join('/')`.
const li = pathLike.lastIndexOf('/');
const stripped = li < 0 ? '' : pathLike.slice(0, li);
return (
findKotlinExactOrSuffix(index, stripped) ??
findKotlinPackageFiles(index, stripped) ??
findByProgressivePrefixStrip(index, pathLike)
);
return ctx;
}
function findKotlinFile(index: KotlinFileIndex, pathLike: string): string | null {
return findKotlinExactOrSuffix(index, pathLike) ?? findKotlinDirectoryChild(index, pathLike);
}
/** Exact (`file === pathLike+ext`) or suffix (`file ends with /pathLike+ext`)
* match — does NOT fall back to picking an arbitrary file inside a
* `pathLike/` directory. Used by the stripped-path tier in
* `resolveKotlinImportTarget` so a package import like `models.getRepo`
* delegates to `findKotlinPackageFiles` (multi-file fan-out) instead of
* silently committing to the first directory child.
*
* An exact match anywhere in the workspace beats a suffix match anywhere,
* which is why the two are separate maps rather than one lookup: the old scan
* returned on the first exact hit but only remembered the first suffix hit,
* so an exact match found late still won. */
function findKotlinExactOrSuffix(index: KotlinFileIndex, pathLike: string): string | null {
if (pathLike === '') return null;
return index.exactByStem.get(pathLike) ?? index.suffixByStem.get(pathLike) ?? null;
}
/** First directory child of `pathLike/` — preserves the legacy single-
* file fallback for cases where `pathLike` itself is an unqualified
* package reference (rare in real Kotlin code; some fixtures rely on
* it). Multi-file package fan-out goes through
* `findKotlinPackageFiles` instead. */
function findKotlinDirectoryChild(index: KotlinFileIndex, pathLike: string): string | null {
if (pathLike === '') return null;
const children = index.dirChildren.get(pathLike);
// "First" is first in `allFilePaths` iteration order, which the index
// preserves by appending as it walks the set. Since #2881 that can be an
// EARLIER file than the pre-index scan returned, never a later one: the
// guards that fell take members away from no bucket, so a bucket only ever
// gains, and a gained member lands wherever set iteration puts it.
return children === undefined ? null : (children[0] ?? null);
}
/**
* Return every `.kt`/`.kts` file inside the package directory `dirPath`
* (e.g. `models` → `['models/User.kt', 'models/Repo.kt']`). Used as a
* fallback when an import like `models.getRepo` does not resolve to a
* file named after the symbol — in Kotlin the symbol can live in any
* file inside the package directory. The finalize pass walks each
* candidate and picks the one whose `localDefs` actually export the
* imported name (#1759).
*/
function findKotlinPackageFiles(index: KotlinFileIndex, dirPath: string): readonly string[] | null {
if (dirPath === '') return null;
return index.dirChildren.get(dirPath) ?? null;
}
function findByProgressivePrefixStrip(index: KotlinFileIndex, pathLike: string): string | null {
const segments = pathLike.split('/').filter(Boolean);
for (let skip = 1; skip < segments.length; skip++) {
const found = findKotlinFile(index, segments.slice(skip).join('/'));
if (found !== null) return found;
}
return null;
}
/**
* Per-file-set lookup tables for Kotlin import resolution, memoized on the
* `allFilePaths` Set object (the same Set is passed for every import in a run,
* so the index is built once and reused).
*
* WHY: every tier of `resolveKotlinImportTarget` used to walk the whole
* workspace — `for (const raw of allFilePaths)` with a `replace(/\\/g, '/')`
* and several string scans per entry — and the tiers are tried in cascade, so a
* single unresolved import cost two to four full passes. Across a repository
* with tens of thousands of Kotlin files that is `O(imports × files)` — on the
* order of 10^10 string operations on one thread, which presents as `analyze`
* sitting at exactly 1.00 core with a flat heap and no output for hours (every
* allocation is a short-lived string, so nothing accumulates to hint at
* progress). Small repositories hide it completely: at a few hundred files each
* pass is free.
*
* The maps below make each tier O(1), so resolution cost becomes O(files) once
* plus O(1) per import.
*
* - `exactByStem`: path minus its `.kt`/`.kts` extension -> raw path, for the
* `file === pathLike+ext` tier.
* - `suffixByStem`: every component-suffix of that stem -> raw path, for the
* `file ends with /pathLike+ext` tier. Keyed per suffix rather than per
* basename so a multi-segment import (`util/OneArg`) hits one bucket instead
* of filtering a basename bucket. The basename-bucket form Python uses was
* built and measured against this one during review: byte-identical output,
* ~66% less memory, and 7.3x slower per query on a repeated-basename corpus
* — enough to fail this resolver's own scaling budget at ~2.0. The memory
* the per-suffix keying costs is small in absolute terms (~60 MiB at 100k
* Kotlin files at depth 8), so it is not a trade worth revisiting.
* - `dirChildren`: package directory -> its direct `.kt`/`.kts` children, in
* set-iteration order, serving both the fan-out tier and the
* first-child fallback.
*
* Both stem maps keep the FIRST path inserted for a key, because the scans they
* replace returned the first match in set-iteration order.
*
* The shared `buildSuffixIndex` (`import-resolvers/utils.ts`, used by C#, Ruby,
* Vue and TypeScript) is deliberately NOT reused — the same call Python
* documents at `python/import-target.ts`. Run side by side against this
* resolver, three probes out of five diverge:
*
* - `['deep/util/User.kt', 'util/User.kt']` for `util.User` — it conflates
* exact and proper-suffix matches in one map, so the deep path wins where
* the scan returned the exact one;
* - `['deep/util/User.kt', 'util/User.kts']` for `util.User` — its keys carry
* the extension, so a `.kt` SUFFIX beats a `.kts` EXACT;
* - `['models/A.kts', 'models/B.kt']` for `models.getThing` — it splits the
* package into `:kt` and `:kts` buckets instead of returning both in set
* order.
*
* A fourth probe — `['data/src/…/data/Repo.kt']` for `data.getRepo`, where the
* shared index fanned out and this one returned null — stopped diverging in
* #2881, which removed the first-occurrence rule that caused it. The remaining
* three are still edges that would move in every Kotlin repository, so
* consolidating the two is a behaviour change, not a cleanup.
*
* `dirChildren` is likewise NOT the shared `import-resolvers/package-dir-index.ts`
* — the consolidation a maintainer will actually propose, since Java routes
* through exactly it (`languages/java/import-target.ts`). Measured, that swap is
* output-identical for 26.2% less retained memory, and costs 8114x on
* `import data.*` at 200 matching directories. `bench/kotlin-import-target`
* CANNOT see that regression — its corpus gives every module a unique package
* leaf — and the arm that can is `bench/import-target`'s kotlin `collide`. See
* `_blind_spot` in `bench/kotlin-import-target/baselines.json`.
*
* `dirChildren`'s bucket rule, and what #2881 removed
* ---------------------------------------------------
* A file is a child of its own directory and of every component-suffix of that
* directory, unguarded. The suffix half used to carry two guards inherited from
* the pre-index per-import scan rather than from anything Kotlin requires (the
* same generation of code put the `indexOf` half into
* `import-resolvers/package-dir-index.ts` and `import-resolvers/csharp.ts`,
* where it was removed under the same issue): `startsWith(s + '/')` skipped the
* bucket outright, and an `indexOf` equality demanded that the parent be the
* FIRST `/s/` in the path. Between them they dropped the bucket whenever the
* package name repeated higher up the tree, so
* `data/src/main/kotlin/com/example/data/Repo.kt` was not a child of `data`
* (leading segment, `startsWith`) and neither was `top/data/mid/data/Repo.kt`
* (mid-path, `indexOf`). `import data.helper` resolved to null in both. Only
* the fan-out tier looked affected — `data.Repo` answers from `suffixByStem`,
* which never had such a guard — which is why the shape looked narrow enough to
* preserve.
*
* Nothing downstream narrows a widened bucket back at the FILE level. The
* `localDefs` filter of #1759 constrains `targetDefId`/`BindingRef` ONLY: the
* finalize pass mints one draft PER CANDIDATE, each keeping its own
* `targetFile` (`gitnexus-shared/src/scope-resolution/finalize-algorithm.ts`),
* and the one File→File filter downstream
* (`scope-resolution/graph-bridge/imports-to-edges.ts`) tests `targetFile`
* against `null` and against the source file, never reads `linkStatus`, and
* emits `IMPORTS` at confidence 1.0. So every extra bucket member becomes an
* unconditional File→File `IMPORTS` edge: one `import data.load` on an
* Android-style layout measured 5 → 6 edges, the added one `unresolved`. That
* is a real cost, paid deliberately — a MISSING bucket is unrecoverable, and
* there is no version of the bucket that is right for one consumer and wrong
* for the other. Narrowing the File→File side, if it is ever wanted, is a
* downstream filter and a separate change.
*
* What moved, over the corpus: of the 235 records the published census counted,
* 149 are a different first child, 32 are a wider fan-out array, and 54 are
* null → resolved — none of which turns a bound answer into an unbound one.
* That taxonomy has no bucket for a fourth outcome class this change
* introduces, and did not count it. Tier 3
* (`findKotlinPackageFiles`) precedes tier 4 (`findByProgressivePrefixStrip`),
* so a bucket the guards used to leave empty returned null and let tier 4 run;
* a now-populated bucket stops tier 4 from running at all, which turns a
* resolved answer into an unresolved one and a `string` into an array:
*
* ['data/src/main/kotlin/com/example/data/Repo.kt', 'common/helper.kt']
* with `import data.helper`
* before → 'common/helper.kt' (bound)
* after → ['data/src/main/kotlin/com/example/data/Repo.kt'] (no `helper`)
*
* Over the census corpus that class is ZERO records — and the zero is the
* point, not a reprieve. The shape above is real and reproduces by hand in
* both iteration orders; running `bench/kotlin-import-target`'s own generator
* at 10x (4000 repositories, ~198 600 distinct records) hits it 4-12 times per
* seed, i.e. an expectation of about ONE over this corpus's 19 968. So the
* fingerprint does not gate this class: it is the same blindness the go arm had
* before #2881 widened its corpus — a gate cannot catch a shape its corpus
* cannot express. Adding a case is a deliberate fingerprint move and belongs in
* its own change, with the re-baseline that implies.
*/
interface KotlinFileIndex {
readonly exactByStem: Map<string, string>;
readonly suffixByStem: Map<string, string>;
/** Buckets are frozen once the build loop finishes — see `getKotlinFileIndex`. */
readonly dirChildren: Map<string, readonly string[]>;
}
const getKotlinFileIndex = perFileSet((allFilePaths: ReadonlySet<string>): KotlinFileIndex => {
// Runs on a cache miss only. That it happens once per run and not once per
// import is asserted by counting traversals of the Set itself, in
// `test/integration/kotlin-import-index-reuse.test.ts` (#2909).
const exactByStem = new Map<string, string>();
const suffixByStem = new Map<string, string>();
const dirChildren = new Map<string, string[]>();
/**
* BUILD-LOCAL: `dir` -> every `dirChildren` key a file in that directory
* contributes to. That list is a pure function of `dir`, and a package
* directory holds many files, so without this the walk below cuts one `slice`
* per component of the SAME directory once per FILE — and every slice after
* the first file's is a freshly allocated string that hashes to a key the map
* already holds and is then dropped. Interning them once per DIRECTORY
* instead of once per FILE is ~21% of the build at 32 000 files.
*
* It cannot move an answer. The array is filled on the first file of a
* directory, in the order the per-file walk produced, and every later file in
* that directory finds those keys already present — so the key set, the Map's
* key insertion order and every bucket's order are what the per-file form
* produced. `kotlin-index-internals.test.ts` pins the part of that a consumer
* can observe, and does it through the resolver's own surface rather than over
* the built maps: bucket CONTENTS and ORDER (from the fan-out tier, which
* hands out the bucket array itself), bucket IDENTITY across calls, and that
* the array handed out is FROZEN. Be precise about the limits, because the
* mutation matrix in that file's header measured them: a MIS-KEYED memo is
* caught, a DELETED one is not — the memo is output-identical by construction,
* so nothing observable can prove it ran. Likewise `Object.isFrozen` catches a
* missing freeze and a compacted-but-never-stored copy, but NOT a deleted
* `slice()`: a JS array's backing-store capacity has no reflective surface, so
* the compaction's only instrument is `heap_ceiling_bytes.kotlin` in
* `bench/import-target/baselines.json` — a CEILING, because compaction
* reclaims, so losing it makes the retained reading grow (+12.57% measured).
* Map key insertion ORDER is
* unasserted BY DESIGN:
* `dirChildren` is only ever read by `.get(key)`, so key order has no
* consumer and pinning it would assert an implementation detail nothing
* depends on. Nothing else watches it either — the correctness fingerprint
* sees this index only through the four tiers, so no fingerprint could catch
* a key-order move.
*
* Dropped with this frame, so it costs nothing retained.
*/
const dirKeys = new Map<string, string[]>();
for (const raw of allFilePaths) {
const norm = raw.replace(/\\/g, '/');
const ext = KOTLIN_EXTENSIONS.find((e) => norm.endsWith(e));
// Kotlin resolution only ever queries `.kt`/`.kts` paths, exactly as the
// scans did before skipping everything else first.
if (ext === undefined) continue;
const stem = norm.slice(0, norm.length - ext.length);
if (!exactByStem.has(stem)) exactByStem.set(stem, raw);
// Component-suffixes of the stem: one per '/' in it. `a/b/User` yields
// `b/User` and `User`, matching `norm.endsWith('/' + key + ext)`.
for (let i = 0; i < stem.length; i++) {
if (stem[i] !== '/') continue;
const suffix = stem.slice(i + 1);
if (!suffixByStem.has(suffix)) suffixByStem.set(suffix, raw);
}
// From `stem`, not `norm`: an extension carries no '/', so the last '/' of
// the two is the same character at the same index, and `stem.slice(0,
// lastSlash)` IS the string `norm.slice(0, norm.lastIndexOf('/'))` was. One
// backwards scan instead of two, over the string this loop already walked.
const lastSlash = stem.lastIndexOf('/');
if (lastSlash < 0) continue; // repo-root file has no package directory
const dir = stem.slice(0, lastSlash);
// The keys this file's directory contributes to, unguarded: `dir` itself,
// plus every component-suffix of it. A suffix `s` starts just after a '/',
// so `dir` ends with `/s` by construction and the file IS a direct child of
// a directory named `s`. The absence of a narrowing guard is deliberate —
// see the `dirChildren` section on `KotlinFileIndex` for the two guards
// #2881 dropped and for what the resulting width costs downstream.
let keys = dirKeys.get(dir);
if (keys === undefined) {
keys = [dir];
for (let i = 0; i < lastSlash; i++) {
if (dir[i] === '/') keys.push(dir.slice(i + 1));
}
dirKeys.set(dir, keys);
}
for (const key of keys) {
const bucket = dirChildren.get(key);
if (bucket === undefined) dirChildren.set(key, [raw]);
else bucket.push(raw);
}
}
// Buckets are mutable only while this function runs; the index type hands
// them out `readonly` and they are frozen here, before it is cached.
// `findKotlinPackageFiles` hands a bucket straight out of the index — the
// same array `findKotlinDirectoryChild` reads `children[0]` from — so a
// downstream sort would permanently reorder the cached bucket and flip the
// FIRST-child tier's answer for every later import in the run. The finalize
// pass normalizes with `Array.isArray(t) ? t : [t]` and `isArray`'s
// `arg is any[]` predicate widens the true branch; that one call site now
// carries an explicit `readonly string[]` annotation, but the annotation is
// one deletion away and covers only that site. Freezing makes the contract
// true at runtime, so a future mutation is a loud TypeError, not a silent
// edge move.
//
// COMPACTED as they are frozen: buckets grow by `push`, so V8's growth
// overshoot stays retained for the life of the index. `length === 1` never
// grew and is skipped — slicing it saves zero bytes and costs 31% of the
// build on a corpus of single-file packages. The byte accounting lives once,
// in `bench/import-target/baselines.json`.
for (const [key, bucket] of dirChildren) {
if (bucket.length === 1) {
Object.freeze(bucket);
continue;
}
const compacted = bucket.slice();
Object.freeze(compacted);
dirChildren.set(key, compacted);
}
return { exactByStem, suffixByStem, dirChildren };
});

View file

@ -8,6 +8,11 @@ export { getKotlinCaptureCacheStats, resetKotlinCaptureCacheStats } from './cach
export { interpretKotlinImport, interpretKotlinTypeBinding } from './interpret.js';
export { kotlinArityCompatibility } from './arity.js';
export { resolveKotlinImportTarget, type KotlinResolveContext } from './import-target.js';
export {
buildKotlinPackageIndex,
resolveKotlinModule,
type KotlinPackageIndex,
} from './module-resolution.js';
export { kotlinMergeBindings } from './merge-bindings.js';
export { populateKotlinOwners } from './owners.js';
export {

View file

@ -0,0 +1,136 @@
/**
* Kotlin import resolution against declared packages and module exports (#2960).
*
* Kotlin source layout is conventional, not semantic: a file may declare any
* package from any directory, and a top-level class, function or property need
* not match the file name. Resolution therefore uses the package fact captured
* during parsing plus the file's module-scope bindings. It never guesses from a
* coincidental path suffix.
*/
import type { ParsedFile } from 'gitnexus-shared';
import type { JvmPackageFact } from '../jvm/package-facts.js';
export interface KotlinPackageIndex {
/** Declared package -> top-level exported name -> files declaring that name. */
readonly declarationsByPackage: ReadonlyMap<string, ReadonlyMap<string, readonly string[]>>;
/** Declared package -> every file declaring it, for wildcard imports. */
readonly filesByPackage: ReadonlyMap<string, readonly string[]>;
/** Files whose package header could not be interpreted conservatively. */
readonly unreadablePackageFiles: number;
}
const EMPTY_INDEX: KotlinPackageIndex = {
declarationsByPackage: new Map(),
filesByPackage: new Map(),
unreadablePackageFiles: 0,
};
export function buildKotlinPackageIndex(
parsedFiles: readonly ParsedFile[],
packageOf: (filePath: string) => JvmPackageFact | undefined,
): KotlinPackageIndex {
if (parsedFiles.length === 0) return EMPTY_INDEX;
const declarationsByPackage = new Map<string, Map<string, string[]>>();
const filesByPackage = new Map<string, string[]>();
let unreadablePackageFiles = 0;
for (const parsed of parsedFiles) {
const fact = packageOf(parsed.filePath);
if (fact === undefined) continue;
if (fact.status !== 'known') {
unreadablePackageFiles++;
continue;
}
const packageName = fact.packageName;
const packageFiles = filesByPackage.get(packageName);
if (packageFiles === undefined) filesByPackage.set(packageName, [parsed.filePath]);
else packageFiles.push(parsed.filePath);
const moduleScope =
parsed.scopes.find((scope) => scope.id === parsed.moduleScope && scope.kind === 'Module') ??
parsed.scopes.find((scope) => scope.kind === 'Module');
if (moduleScope === undefined) continue;
let declarations = declarationsByPackage.get(packageName);
if (declarations === undefined) {
declarations = new Map();
declarationsByPackage.set(packageName, declarations);
}
for (const [name, refs] of moduleScope.bindings) {
if (
name === '' ||
!refs.some((ref) => ref.origin === 'local' && ref.def.filePath === parsed.filePath)
) {
continue;
}
const files = declarations.get(name);
if (files === undefined) declarations.set(name, [parsed.filePath]);
else if (!files.includes(parsed.filePath)) files.push(parsed.filePath);
}
}
return { declarationsByPackage, filesByPackage, unreadablePackageFiles };
}
/** Resolve a Kotlin import to the file(s) its declarations name. */
export function resolveKotlinModule(
targetRaw: string,
index: KotlinPackageIndex,
): string | readonly string[] | null {
if (targetRaw === '') return null;
if (targetRaw.endsWith('.*')) {
const stem = targetRaw.slice(0, -2);
if (stem === '') return null;
const packageFiles = index.filesByPackage.get(stem);
if (packageFiles !== undefined) return packageFiles;
// Kotlin also permits star imports from a class or object. Resolve the
// owning top-level declaration, while keeping an undeclared package null.
return resolveTopLevelDeclaration(stem, index);
}
return resolveTopLevelDeclaration(targetRaw, index);
}
function resolveTopLevelDeclaration(
qualifiedName: string,
index: KotlinPackageIndex,
): string | readonly string[] | null {
const parts = qualifiedName.split('.').filter((part) => part !== '');
if (parts.length === 0) return null;
// A bare name can refer to the special root package. It is still backed by
// package and binding evidence; no path fallback is involved.
if (parts.length === 1) {
const name = parts[0];
return name === undefined
? null
: declarationFiles(index.declarationsByPackage.get('')?.get(name));
}
for (let split = parts.length - 1; split >= 1; split--) {
const packageName = parts.slice(0, split).join('.');
const declarations = index.declarationsByPackage.get(packageName);
if (declarations === undefined) continue;
const declarationName = parts[split];
if (declarationName === undefined) continue;
const files = declarations.get(declarationName);
if (files === undefined) continue;
return declarationFiles(files);
}
return null;
}
function declarationFiles(files: readonly string[] | undefined): string | readonly string[] | null {
if (files === undefined || files.length === 0) return null;
// Kotlin permits overloaded top-level callables across files. Preserve the
// complete candidate set instead of choosing one by parse order.
return files.length === 1 ? (files[0] ?? null) : files;
}

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