scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-10-10 03:27:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Merge branch 'main' into rios/fix-augment-symbol-name-fallback

Browse source
This commit is contained in:
Gergő Magyar 2026-10-04 20:35:52 +01:00 • committed by GitHub
commit 8924290724
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
171 changed files with 13353 additions and 806 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
.github/workflows/build-tree-sitter-prebuilds.yml vendored
View file

@ -123,7 +123,7 @@ jobs:
matrix: ${{ steps.decide.outputs.matrix }}
release_app: ${{ steps.relapp.outputs.configured }}
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0 # need base history to diff recorded versions
persist-credentials: false
@ -392,7 +392,7 @@ jobs:
# and compiling them under emulation on the arm runners is slow.
timeout-minutes: 45
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false # this job uploads artifacts (artipacked)
@ -565,7 +565,7 @@ jobs:
app-id: ${{ secrets.RELEASE_APP_ID }}
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
token: ${{ steps.app-token.outputs.token }}
# On a (non-fork) PR, check out the PR's HEAD branch — not the merge ref —

4
.github/workflows/ci-devcontainer.yml vendored
View file

@ -36,7 +36,7 @@ jobs:
# persist-credentials: false — this job only reads (tests and syntax
# checks) and never pushes. The setting keeps GITHUB_TOKEN out of
# .git/config, which zizmor flags as the "artipacked" issue.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@ -57,7 +57,7 @@ jobs:
# persist-credentials: false — this is a read-only build smoke that
# never pushes. The setting keeps GITHUB_TOKEN out of .git/config,
# which zizmor flags as the "artipacked" issue.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0

4
.github/workflows/ci-e2e.yml vendored
View file

@ -14,7 +14,7 @@ jobs:
outputs:
web_changed: ${{ steps.filter.outputs.web }}
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v3
@ -31,7 +31,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

10
.github/workflows/ci-quality.yml vendored
View file

@ -13,7 +13,7 @@ jobs:
# canceled prettier at the 5-minute job cap; lint needed 7m41s the same run.
timeout-minutes: 10
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@ -28,7 +28,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@ -43,7 +43,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# tsc --noEmit reads source + gitnexus-shared/dist. Skip prepare/postinstall
@ -61,7 +61,7 @@ jobs:
# run is cold again.
timeout-minutes: 15
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ./.github/actions/setup-gitnexus-web
@ -84,7 +84,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Validate workflow concurrency convention

2
.github/workflows/ci-report.yml vendored
View file

@ -125,7 +125,7 @@ jobs:
- name: Checkout (for vitest config)
if: steps.meta.outputs.skip != 'true'
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
sparse-checkout: gitnexus/vitest.config.ts
sparse-checkout-cone-mode: false

26
.github/workflows/ci-tests.yml vendored
View file

@ -36,7 +36,7 @@ jobs:
# persist-credentials: false — runs tests + uploads a blob artifact; the
# default-persisted token must not be capturable through it (zizmor
# credential-persistence / artipacked audit). The job never pushes.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ./.github/actions/setup-gitnexus
@ -99,7 +99,7 @@ jobs:
env:
GITNEXUS_REQUIRE_FTS: '1'
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ./.github/actions/setup-gitnexus
@ -223,7 +223,7 @@ jobs:
steps:
# persist-credentials: false — runs tests only, never pushes (zizmor
# credential-persistence / artipacked audit).
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ./.github/actions/setup-gitnexus
@ -273,7 +273,7 @@ jobs:
runs-on: ${{ matrix.os }}
timeout-minutes: 20
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ./.github/actions/setup-gitnexus
@ -317,7 +317,7 @@ jobs:
# from a tarball and never pushes back; the token in .git/config would
# be at risk of leaking through any future artifact-upload step
# (zizmor artipacked audit). Disable upfront.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# Skip prepare/postinstall/build here. `npm pack` runs prepack, which
@ -430,7 +430,7 @@ jobs:
steps:
# persist-credentials: false — builds and import-links only, never pushes
# (zizmor credential-persistence / artipacked audit).
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@ -496,7 +496,7 @@ jobs:
# and never pushes; the default-persisted token in .git/config would be at
# risk of leaking through an artifact upload (zizmor credential-persistence
# / artipacked audit). Mirrors the packaged-install-smoke job below.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ./.github/actions/setup-gitnexus
@ -907,10 +907,10 @@ jobs:
timeout-minutes: 15
steps:
# persist-credentials: false — runs tests only, never pushes.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
version: '0.11.23'
python-version: '3.13'
@ -934,7 +934,7 @@ jobs:
GITNEXUS_REQUIRE_FULL_SWEEP: '1'
GITNEXUS_REQUIRE_CLAUDE_CANARY: '1'
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@ -944,7 +944,7 @@ jobs:
cache-dependency-path: |
gitnexus/package-lock.json
gitnexus-shared/package-lock.json
- uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
version: '0.11.23'
python-version: '3.13'
@ -1002,10 +1002,10 @@ jobs:
runs-on: windows-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
version: '0.11.23'
python-version: '3.13'

2
.github/workflows/claude.yml vendored
View file

@ -129,7 +129,7 @@ jobs:
core.setOutput('code_review', isCodeReview ? 'true' : 'false');
- name: Checkout repository
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ steps.pr.outputs.is_pr == 'true' && steps.pr.outputs.repo || github.repository }}
ref: ${{ steps.pr.outputs.is_pr == 'true' && steps.pr.outputs.sha || '' }}

6
.github/workflows/codeql.yml vendored
View file

@ -42,13 +42,13 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# Don't leave GITHUB_TOKEN in .git/config for downstream steps to read.
persist-credentials: false
- name: Initialize CodeQL
uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
uses: github/codeql-action/init@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
with:
languages: ${{ matrix.language }}
queries: security-and-quality
@ -87,6 +87,6 @@ jobs:
- '.github/scripts/fetch-lbug-fts-artifacts.mjs'
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
uses: github/codeql-action/analyze@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
with:
category: '/language:${{ matrix.language }}'

4
.github/workflows/commit-fork-prebuilds.yml vendored
View file

@ -145,7 +145,7 @@ jobs:
# checkout (the same trust anchor as this workflow file).
- name: Checkout identity verifier
if: steps.meta.outputs.deliver == 'true'
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
sparse-checkout: .github/scripts/verify-workflow-run-pr-identity.cjs
@ -171,7 +171,7 @@ jobs:
# never written to .git/config on disk.
- name: Checkout fork PR head
if: steps.meta.outputs.deliver == 'true' && steps.verify.outcome == 'success'
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ steps.verify.outputs.head_repo }}
ref: ${{ steps.verify.outputs.head_sha }}

2
.github/workflows/dependency-review.yml vendored
View file

@ -28,7 +28,7 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

2
.github/workflows/docker.yml vendored
View file

@ -103,7 +103,7 @@ jobs:
# When triggered by workflow_call the caller passes the RC tag as an input;
# we check out that tag so the Dockerfile and package.json match the built image.
# For tag-push events github.ref is already the tag ref — no override needed.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ inputs.tag || github.ref }}

2
.github/workflows/gitleaks.yml vendored
View file

@ -29,7 +29,7 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# Full history needed for the on-push full-history scan; on PRs the
# action diffs against the base ref so the cost is bounded by the PR.

8
.github/workflows/gitnexus-review-agent.yml vendored
View file

@ -303,7 +303,7 @@ jobs:
- name: Checkout trusted workflow control plane
id: checkout-control
if: steps.context.outputs.ready == 'true'
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ github.repository }}
ref: ${{ steps.context.outputs.control_sha }}
@ -315,7 +315,7 @@ jobs:
- name: Checkout exact PR head as passive data
id: checkout-head
if: steps.context.outputs.ready == 'true'
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ steps.context.outputs.head_repo }}
ref: ${{ steps.context.outputs.head_sha }}
@ -1294,7 +1294,7 @@ jobs:
steps.claude-recheck.outcome == 'success'
# Use the low-level base action: the high-level GitHub action can restore
# project configuration from a moving base branch before invoking Claude.
uses: anthropics/claude-code-action/base-action@3553f84341b92da26052e28acf1aa898f9511f32 # v1
uses: anthropics/claude-code-action/base-action@e0cf66d1d257526b5d07f141838c338921cb8455 # v1
env:
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: '1'
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '0'
@ -1447,7 +1447,7 @@ jobs:
if: >-
steps.precheck.outputs.repair_reason != '' &&
steps.repair-recheck.outcome == 'success'
uses: anthropics/claude-code-action/base-action@3553f84341b92da26052e28acf1aa898f9511f32 # v1
uses: anthropics/claude-code-action/base-action@e0cf66d1d257526b5d07f141838c338921cb8455 # v1
env:
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: '1'
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '0'

4
.github/workflows/gitnexus-skill-evolution.yml vendored
View file

@ -252,7 +252,7 @@ jobs:
exit 1
fi
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
fetch-depth: 0
@ -265,7 +265,7 @@ jobs:
gitnexus/package-lock.json
gitnexus-shared/package-lock.json
- uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
with:
version: '0.11.23'
python-version: '3.13'

2
.github/workflows/grammar-update-monitor.yml vendored
View file

@ -44,7 +44,7 @@ jobs:
permissions:
contents: read
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

2
.github/workflows/impact-pdg-mutation-report.yml vendored
View file

@ -37,7 +37,7 @@ jobs:
# artifact and never pushes; the default-persisted token in .git/config
# must not be capturable through that upload (zizmor credential-persistence
# / artipacked audit). Mirrors ci-tests.yml.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

2
.github/workflows/pr-autofix-apply.yml vendored
View file

@ -336,7 +336,7 @@ jobs:
# Push auth is provided inline at push time via the URL.
- name: Checkout PR head
if: steps.locate.outputs.found == 'true'
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v5.0.4
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ steps.locate.outputs.head_repo }}
ref: ${{ steps.locate.outputs.head_sha }}

2
.github/workflows/pr-autofix-publish.yml vendored
View file

@ -131,7 +131,7 @@ jobs:
# check-run SHA cannot be an unverified artifact field.
# Mismatch => fail loud BEFORE any sticky/check-run side effect.
- name: Checkout identity verifier
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
sparse-checkout: .github/scripts/verify-workflow-run-pr-identity.cjs

2
.github/workflows/pr-autofix.yml vendored
View file

@ -51,7 +51,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# PR head commit (not the synthetic merge ref) — we need the
# exact tree the contributor pushed so suggestions line up.

6
.github/workflows/publish.yml vendored
View file

@ -162,7 +162,7 @@ jobs:
should_run: ${{ steps.decide.outputs.should_run }}
head_sha: ${{ steps.decide.outputs.head_sha }}
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
fetch-tags: true
@ -332,7 +332,7 @@ jobs:
# on the RC path.
- name: Checkout (RC)
if: needs.route.outputs.mode == 'rc'
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
fetch-tags: true
@ -349,7 +349,7 @@ jobs:
- name: Checkout (stable)
if: needs.route.outputs.mode == 'stable'
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
# No `token:` — actions/checkout uses GITHUB_TOKEN by default. Stable
# path performs no git pushes; the default scope is sufficient.
with:

4
.github/workflows/scorecard.yml vendored
View file

@ -33,7 +33,7 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
@ -53,6 +53,6 @@ jobs:
retention-days: 5
- name: Upload to Security tab
uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
with:
sarif_file: results.sarif

2
.github/workflows/skill-sync.yml vendored
View file

@ -47,7 +47,7 @@ jobs:
timeout-minutes: 15
steps:
# persist-credentials: false — runs a read-only test, never pushes.
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0

2
.github/workflows/tree-sitter-upgrade-readiness.yml vendored
View file

@ -52,7 +52,7 @@ jobs:
report: ${{ steps.readiness.outputs.report }}
exit_code: ${{ steps.readiness.outputs.exit_code }}
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

2
.github/workflows/triage-sweep.yml vendored
View file

@ -59,7 +59,7 @@ jobs:
timeout-minutes: 30
steps:
- name: Checkout repository
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
sparse-checkout: .github/scripts/triage
sparse-checkout-cone-mode: false

6
.github/workflows/trivy.yml vendored
View file

@ -45,7 +45,7 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
@ -53,7 +53,7 @@ jobs:
uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
- name: Build image (load locally for scan)
uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
with:
context: .
file: ${{ matrix.image.dockerfile }}
@ -76,7 +76,7 @@ jobs:
exit-code: '0'
- name: Upload to Security tab
uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
with:
sarif_file: trivy-${{ matrix.image.name }}.sarif
category: trivy-${{ matrix.image.name }}

6
.github/workflows/workflow-lint.yml vendored
View file

@ -31,7 +31,7 @@ jobs:
contents: read
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
@ -53,7 +53,7 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
@ -76,7 +76,7 @@ jobs:
continue-on-error: true
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
with:
sarif_file: zizmor.sarif
category: zizmor

17
README.md
View file

@ -616,6 +616,7 @@ Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max
| `GITNEXUS_VERBOSE` | unset | When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`. | Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput. |
| `GITNEXUS_EMBEDDING_RETRY_TIMEOUTS` | unset | When truthy (`1`/`true`/`yes`), per-attempt HTTP embedding timeouts (`TimeoutError` on fetch or body read) go through the bounded `GITNEXUS_EMBEDDING_MAX_ATTEMPTS` retry loop instead of failing the job. Any other value leaves it off, so cloud/default timeouts remain terminal. | Local accelerators that drop a device lock when the client disconnects and succeed on the next request (observed with FastFlowLM on Ryzen AI). |
| `GITNEXUS_EMBEDDING_SIDECAR_TIMEOUT_MS` | `180000` (3 minutes) | Per-request IPC timeout for local embedding sidecar embed batches. On overrun the parent SIGKILLs the sidecar child and rejects the batch. Init still uses the HF download budget (`HF_DOWNLOAD_TIMEOUT_MS` × attempts), not this knob. | Large embed batches or slow local ONNX inference cause sidecar request timeouts during `analyze --embeddings`, `embeddings sync`, serve, or MCP. |
| `GITNEXUS_VECTOR_MAX_DISTANCE` | `0.6` for CLI/MCP `query`; `0.5` for standalone semantic search | Maximum cosine distance for vector hits, applied to both indexed search and exact-scan fallback. Hits must have `distance < cutoff`. Unset/blank uses the default; non-numeric, non-finite, zero, or negative values warn and use the default; finite values above `2` warn and clamp to `2`. | Paraphrased queries have weak semantic recall with your embedding model. See [Vector cutoff tuning](#vector-cutoff-tuning). |
| `GITNEXUS_ANALYZER_IDENTITY_IN_PROCESS_GUARDS` | unset | When truthy (`1`/`true`/`yes`), forces in-process cache-guard validation once a batch has ≥128 requests. In-process mode also auto-selects when `packageRoot`/`buildRoot` fail `W_OK` with `EACCES`/`EROFS`. Otherwise those large batches use a Node subprocess probe. Batches under 128 always stay in-process. | Trusted or read-only installs where two identity subprocess spawns per analyze dominate wall time; leave unset to keep the default isolation path on writable trees. |
| `GITNEXUS_RESOLVE_DEF_GRAPH_ID_MEMO` | on (unset) | Memoizes `resolveDefGraphId` per `nodeLookup` instance (WeakMap). Enabled by default. Set to `0`/`false`/`off`/`no` to disable and recompute on every call (debug / bisect memo bugs). | Suspecting stale graph-id resolution after a lookup rebuild, or comparing memo vs uncached cost on a large index. |
| `GITNEXUS_AUTH_TOKEN` | unset | Bearer token required when `eval-server` binds beyond loopback. May also be read from `.env.local` or `.env`; shell values take precedence. | Exposing the evaluation HTTP tools to a container, VM, or LAN. |
@ -655,6 +656,22 @@ Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max
| `GITNEXUS_PUBLIC_ORIGIN` | unset | The single browser origin `serve` is reached through, added to the CORS allowlist and to the write-route origin guard. A wildcard bind (`0.0.0.0`) has no host identity, so without this the server's own UI is refused. **Setting it currently refuses to start:** `serve` has no authentication, requests carrying no `Origin` header already reach `POST /api/analyze` and `DELETE /api/repo`, and this is the setting that would admit browser writes on top of that. Matching rules for when the gate lifts: the hostname must match exactly, and so must the scheme. A value with no scheme (`app.example.com`) means `https`, since a bare host comes from platform service discovery and those terminate TLS; spell out `http://app.example.com` for plain HTTP. An explicit port must match; with no port, any port on that hostname is accepted. Anything that is not one reachable host (a list, `*`, a bare port number, a `:0` port, a trailing dot) warns at startup and allows nothing. | `gitnexus serve` runs behind a reverse proxy or on a wildcard bind, and the UI's index/delete requests return `origin_not_allowed`. |
| `GITNEXUS_TRUST_PROXY` | `loopback, linklocal, uniquelocal` | Express `trust proxy` value — which upstream hops may set `X-Forwarded-*`, and so what the per-IP rate limiter reads as the client IP. Set it to the exact number of proxies you control. Every hop past that is one more entry of the chain the caller gets to write. `false`/`no`/`off` (and a `0` hop count) trust no hop; a proxy list Express can compile (`loopback`, `10.0.0.0/8, 127.0.0.1`) names them instead. `true`/`yes`/`on` is **rejected**: it reads the client-controlled leftmost `X-Forwarded-For` entry, so a spoofed chain earns a fresh rate-limit key per request, and express-rate-limit rejects it too (`ERR_ERL_PERMISSIVE_TRUST_PROXY`). Counts above `16` are rejected as well, as a sanity ceiling rather than a safety boundary. Any invalid value warns and falls back to the default. Bind non-loopback with this unset and `serve` warns: a load balancer outside the private ranges is untrusted, so every request keys to the balancer and the per-IP limit becomes one shared limit. | `serve` sits behind a load balancer outside the private ranges (AWS ALB, Cloudflare, CGNAT), where every request otherwise collapses to the proxy hop and rate limiting goes global. |
### Vector cutoff tuning
`GITNEXUS_VECTOR_MAX_DISTANCE` controls which vector candidates enter hybrid search. Cosine distance is lower for more similar vectors; the appropriate cutoff depends on the embedding model and repository. A higher cutoff can recover useful semantic matches, but can also admit less relevant hits and change the fused ranking. The default is `0.6` for CLI and MCP `query`, and `0.5` for the standalone semantic-search function.
For an index that already has embeddings, compare the default with `0.8` and `1.0` on representative queries, including paraphrases, exact symbol names, and queries that should have no relevant result:
```bash
GITNEXUS_VECTOR_MAX_DISTANCE=0.8 gitnexus query "how are expired sessions removed" --limit 10
```
Check both whether the expected symbols appear and where they rank. In [#3457](https://github.com/abhigyanpatwari/GitNexus/issues/3457), the reporter's `voyage-code-4` sample found 20 of 32 paraphrased targets at `0.6`, 25 at `0.8`, and 28 at `1.0`. Those values are a tuning starting point for that model, not universal recommendations: one paraphrased target fell from first to twelfth at `1.0`. The sample covered eight repositories, recorded no raw distances, used agent-written queries after reading the code, and did not send Voyage's `input_type`.
Set the variable in the process that runs the search. For MCP, add it to the server's launch environment and restart the server; for `gitnexus serve`, set it in that process's environment and restart it. Setting it only during `analyze`, or exporting it in another shell, does not configure an existing server. Changing the cutoff requires no reindex.
The cutoff only filters available vector candidates. It cannot add missing embeddings or repair a mismatch between the indexing and query-time embedding configuration; see the [embeddings runbook](RUNBOOK.md#embeddings). A cutoff of `2` is very permissive, but still rejects distance exactly `2` and retains the search candidate limits.
</details>
<details>

8
RUNBOOK.md
View file

@ -87,6 +87,14 @@ npx gitnexus analyze --force
If it recurs, the cause is almost always environmental rather than a code defect: check free disk space on the volume holding `.gitnexus/`, make sure no second `analyze` is running against the same repo (both use `.gitnexus/csv` for staging), then run `npx gitnexus doctor`. The check compares in-memory relationship totals (including streamed rows) against what the DB hands back, and is deliberately skipped on incremental runs, where the two counts are not comparable.
**Weak semantic recall despite existing embeddings:** If paraphrased queries look like keyword-only search, the distance cutoff may be too strict for the embedding model. CLI and MCP `query` default to `0.6`. From the indexed repository, try a broader cutoff:
```bash
GITNEXUS_VECTOR_MAX_DISTANCE=0.8 npx gitnexus query "how are expired sessions removed" --limit 10
```
Compare target inclusion and ranking against the default; a broader cutoff also admits less relevant hits. Set the variable in the MCP/serve launch environment and restart that process when tuning a server. A cutoff change needs no reindex and setting it only during `analyze` does not persist it. If the index has no vectors, generate embeddings first; if the embedding model or dimensions differ between indexing and querying, align that configuration and regenerate vectors. See [Vector cutoff tuning](README.md#vector-cutoff-tuning) for validation rules and the limited `voyage-code-4` evidence from #3457.
**Large repos:** Analyze may skip or limit embedding work when node counts are very high; watch CLI output.
---

45
docker-server.test.mjs
View file

@ -331,8 +331,8 @@ const respondOk = (_req, res) => {
//
// upstream request handler, replaceable mid-test via `ctx.handler`;
// null points the proxy at a port nothing ever listens on
// listenAfterMs bind the upstream this late, so the first attempt(s) hit
// ECONNREFUSED (a single-instance restart window)
// listenAfterMs bind the upstream this late after the first refused attempt
// (a single-instance restart window)
// schemeless drop http:// from GITNEXUS_UPSTREAM_URL, the way Render's
// `fromService: { property: hostport }` yields it
// env extra environment for docker-server.mjs
@ -366,18 +366,15 @@ async function withProxy(
})
: null;
// A late (or never) bind needs its port reserved up front; otherwise let the
// OS assign one at listen time.
const upstreamPort =
server && listenAfterMs === 0
? await new Promise((r) => server.listen(0, '127.0.0.1', () => r(server.address().port)))
: await getFreePort();
const bindTimer =
server && listenAfterMs > 0
? setTimeout(() => server.listen(upstreamPort, '127.0.0.1'), listenAfterMs)
: null;
// Keep the upstream port bound until the proxy port is chosen. Releasing it
// sooner lets the OS assign both services the same port and proxy to itself.
const reservation = server ?? createServer();
const upstreamPort = await new Promise((r) =>
reservation.listen(0, '127.0.0.1', () => r(reservation.address().port)),
);
const port = await getFreePort();
let bindTimer = null;
const target = `127.0.0.1:${upstreamPort}`;
const proc = spawnServerWithEnv(dir, port, {
GITNEXUS_UPSTREAM_URL: schemeless ? target : `http://${target}`,
@ -390,18 +387,25 @@ async function withProxy(
...env,
});
proc.stderr.setEncoding('utf8');
proc.stderr.on('data', (chunk) => {
const collectStderr = (chunk) => {
ctx.stderr += chunk;
});
// Process startup must not consume the restart window or skip the retry.
if (server && listenAfterMs > 0 && !bindTimer && ctx.stderr.includes('ECONNREFUSED; retry')) {
bindTimer = setTimeout(() => server.listen(upstreamPort, '127.0.0.1'), listenAfterMs);
}
};
proc.stderr.on('data', collectStderr);
try {
await waitForServer(port);
if (!server || listenAfterMs > 0) await new Promise((r) => reservation.close(r));
await fn(port, ctx);
} finally {
proc.stderr.off('data', collectStderr);
if (bindTimer) clearTimeout(bindTimer);
await killAndWait(proc);
if (server?.listening) {
server.closeAllConnections?.();
await new Promise((r) => server.close(r));
if (reservation.listening) {
reservation.closeAllConnections?.();
await new Promise((r) => reservation.close(r));
}
await rm(dir, { recursive: true, force: true });
}
@ -661,8 +665,8 @@ it('returns 502 when the upstream is unreachable', async () => {
// -- Connection-retry across an upstream restart window ---------------------
//
// `listenAfterMs: 400` binds the upstream late, so the first attempt hits
// ECONNREFUSED and must be retried — a single-instance restart. The default 3
// `listenAfterMs: 400` binds the upstream 400ms after the first ECONNREFUSED,
// so the request must be retried — a single-instance restart. The default 3
// attempts (backoff 250ms, 500ms) span ~750ms, so a retry lands after the bind.
it('retries a connection-refused POST and succeeds once the upstream is up', async () => {
@ -676,6 +680,7 @@ it('retries a connection-refused POST and succeeds once the upstream is up', asy
assert.match(res.body, /"ok":true/);
assert.equal(ctx.calls, 1, 'upstream must run the job exactly once (no double-execute)');
assert.equal(ctx.body, '{"repo":"x"}', 'buffered body replayed intact');
assert.match(ctx.stderr, /ECONNREFUSED; retry/, 'the restart gap must exercise a retry');
});
});

2
eval/tests/test_workflow_bench.py
View file

@ -185,7 +185,7 @@ def test_eval_ci_uses_locked_uv_and_blocking_native_containment_jobs():
step for step in containment["steps"] if str(step.get("uses", "")).startswith("actions/setup-node@")
)
claude_lock = json.loads((repo_root / ".github" / "claude-canary-runtime" / "package-lock.json").read_text())
setup_uv = "astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990"
setup_uv = "astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9"
assert workflow.count(setup_uv) >= 3
assert workflow.count("version: '0.11.23'") >= 3
assert workflow.count("uv run --locked --extra dev python -m pytest") >= 3

18
eval/uv.lock generated
View file

@ -1992,11 +1992,11 @@ wheels = [
[[package]]
name = "oauthlib"
version = "3.3.1"
version = "4.0.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/0b/5f/19930f824ffeb0ad4372da4812c50edbd1434f678c90c2733e1188edfc63/oauthlib-3.3.1.tar.gz", hash = "sha256:0f0f8aa759826a193cf66c12ea1af1637f87b9b4622d46e866952bb022e538c9", size = 185918, upload-time = "2025-06-19T22:48:08.269Z" }
sdist = { url = "https://files.pythonhosted.org/packages/7a/d8/a1bcc8ba112a627f8ffbdc212a78ce18d3ac07e91a5ca65d27918eee25a1/oauthlib-4.0.0.tar.gz", hash = "sha256:efb274799819440f95b4ab3b818869f1ce9ae26c5beacba0201d1a1b76b54f86", size = 187232, upload-time = "2026-09-28T06:01:18.77Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/be/9c/92789c596b8df838baa98fa71844d84283302f7604ed565dafe5a6b5041a/oauthlib-3.3.1-py3-none-any.whl", hash = "sha256:88119c938d2b8fb88561af5f6ee0eec8cc8d552b7bb1f712743136eb7523b7a1", size = 160065, upload-time = "2025-06-19T22:48:06.508Z" },
{ url = "https://files.pythonhosted.org/packages/d9/f4/78229a1066068ca14fc60fb26cf7381cabe4382261392b90e5f9552722d4/oauthlib-4.0.0-py3-none-any.whl", hash = "sha256:624c28c13a0a59cabf9747dfa52af63be3e512a7f2714df16e91b5b3a145e6cd", size = 159715, upload-time = "2026-09-28T06:01:17.008Z" },
]
[[package]]
@ -2522,11 +2522,11 @@ wheels = [
[[package]]
name = "pyjwt"
version = "2.13.0"
version = "2.15.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/3b/81/58d0ac84e1ef3a3843791d6954d94c0b33d526c75eeb1efbce9d0a4c4077/pyjwt-2.13.0.tar.gz", hash = "sha256:41571c89ca91598c79e8ef18a2d07367d4810fbbd6f637794879baf1b7703423", size = 107515, upload-time = "2026-05-21T19:54:36.618Z" }
sdist = { url = "https://files.pythonhosted.org/packages/02/a5/5197bfd06417837ac079921c66fa6393f1dea3557272a263cebfef69e432/pyjwt-2.15.0.tar.gz", hash = "sha256:b11c5f9791d7bf51c2b39a81ed669f6b2dbbd669df2942f6c60167e9e3d1abe4", size = 120513, upload-time = "2026-09-23T16:56:00.689Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/a3/5e/ecf12fdb62546d64385c158514e9b2b671f7832108ef2ecd2020ce0af2d1/pyjwt-2.13.0-py3-none-any.whl", hash = "sha256:66adcc2aff09b3f1bbd95fc1e1577df8ac8723c978552fd43304c8a290ac5728", size = 31274, upload-time = "2026-05-21T19:54:35.362Z" },
{ url = "https://files.pythonhosted.org/packages/e8/55/40e45bf052ee8ee12a4dfd785519660f8effa7b065442b91646ec6828619/pyjwt-2.15.0-py3-none-any.whl", hash = "sha256:7a3742debf6b879e912dbb9819ceec1594be812452b78c5f2e2dfc56564954f8", size = 33680, upload-time = "2026-09-23T16:55:59.241Z" },
]
[package.optional-dependencies]
@ -3306,11 +3306,11 @@ wheels = [
[[package]]
name = "urllib3"
version = "2.7.0"
version = "2.8.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
sdist = { url = "https://files.pythonhosted.org/packages/e3/05/b17359e1cefb4f909b5e40b1b90a496d987258916dbbf88e842c729f510e/urllib3-2.8.0.tar.gz", hash = "sha256:63bf2ead4c879426ebf22ef2a781eeb4aa3b4ae798a0435506f8687fd5bb9b63", size = 458972, upload-time = "2026-09-15T19:29:36.253Z" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
{ url = "https://files.pythonhosted.org/packages/92/9d/c4e665119135114480843e7ab388fa94d8480650450e6f8e26b70d323a4c/urllib3-2.8.0-py3-none-any.whl", hash = "sha256:0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3", size = 135717, upload-time = "2026-09-15T19:29:34.577Z" },
]
[[package]]

76
gitnexus-web/package-lock.json generated
View file

@ -9,16 +9,16 @@
"version": "0.0.0",
"dependencies": {
"@langchain/anthropic": "^1.5.8",
"@langchain/core": "^1.2.8",
"@langchain/core": "^1.2.13",
"@langchain/google-genai": "^2.3.1",
"@langchain/langgraph": "^1.4.14",
"@langchain/langgraph": "^1.4.18",
"@langchain/ollama": "^1.3.0",
"@langchain/openai": "^1.5.13",
"@sigma/edge-curve": "^3.1.0",
"@tailwindcss/vite": "^4.3.3",
"axios": "^1.20.0",
"d3": "^7.9.0",
"dompurify": "^3.4.15",
"dompurify": "^3.4.16",
"gitnexus-shared": "file:../gitnexus-shared",
"graphology": "^0.26.0",
"graphology-indices": "^0.17.0",
@ -26,9 +26,9 @@
"graphology-layout-forceatlas2": "^0.10.1",
"graphology-layout-noverlap": "^0.4.2",
"graphology-utils": "^2.3.0",
"i18next": "^26.3.6",
"i18next": "^26.4.2",
"i18next-browser-languagedetector": "^8.2.1",
"langchain": "^1.5.11",
"langchain": "^1.5.14",
"lru-cache": "^11.5.3",
"lucide-react": "^1.46.0",
"mermaid": "^11.17.2",
@ -53,7 +53,7 @@
"@testing-library/react": "^16.3.3",
"@testing-library/user-event": "^14.6.7",
"@types/dompurify": "^3.2.0",
"@types/node": "^26.5.1",
"@types/node": "^26.6.2",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"@types/react-syntax-highlighter": "^15.5.13",
@ -1083,9 +1083,9 @@
}
},
"node_modules/@langchain/core": {
"version": "1.2.11",
"resolved": "https://registry.npmjs.org/@langchain/core/-/core-1.2.11.tgz",
"integrity": "sha512-8yuWLLloTSYA453akm2JSadOVa8kGDY8v+kTzQ6kTY6aIETTEIxgysjZWyKrWQLo3UazctsSoGJ8JrdCGFL4/w==",
"version": "1.2.13",
"resolved": "https://registry.npmjs.org/@langchain/core/-/core-1.2.13.tgz",
"integrity": "sha512-ADGTxZ84n3civruUX1LlTOdua/PDGoni2U6TmKTX7hvRU2Jlepu8vLJI4Wnwj45KUKhUCrW94Il12Q2bxE3e8A==",
"license": "MIT",
"dependencies": {
"@cfworker/json-schema": "^4.0.2",
@ -1116,13 +1116,13 @@
}
},
"node_modules/@langchain/langgraph": {
"version": "1.4.14",
"resolved": "https://registry.npmjs.org/@langchain/langgraph/-/langgraph-1.4.14.tgz",
"integrity": "sha512-uWAdRYTllfKCnTrlyovExPJCHJwcf3Wl2LzUlnaqsT7Rmoo3aCeYtq/7MV/Pw4q11motG8pR8bjr6T6V8Pe1gQ==",
"version": "1.4.18",
"resolved": "https://registry.npmjs.org/@langchain/langgraph/-/langgraph-1.4.18.tgz",
"integrity": "sha512-yrMMJ9hk2NVMD2xU2WoVrgFawAU6s/RzEl/dX9BhlyxZHazo1wHY35z4K2BIBzTUh4z3giCzrUoqRAqW2CWpWg==",
"license": "MIT",
"dependencies": {
"@langchain/langgraph-checkpoint": "^1.1.5",
"@langchain/langgraph-sdk": "~1.10.2",
"@langchain/langgraph-sdk": "~1.12.0",
"@langchain/protocol": "^0.0.19",
"@standard-schema/spec": "1.1.0"
},
@ -1147,9 +1147,9 @@
}
},
"node_modules/@langchain/langgraph-sdk": {
"version": "1.10.2",
"resolved": "https://registry.npmjs.org/@langchain/langgraph-sdk/-/langgraph-sdk-1.10.2.tgz",
"integrity": "sha512-86qsfdBZWu1ZgywLN8AThU/jXi9rjPDZPWcTJp4SA1A/L62ypTNoSXbvtiwZt1odokXccYTxK1XWS8tmVdvEmw==",
"version": "1.12.0",
"resolved": "https://registry.npmjs.org/@langchain/langgraph-sdk/-/langgraph-sdk-1.12.0.tgz",
"integrity": "sha512-F3AOZjKZRUGmE3FzY+RaVZI6WzXOkwnuF7jqgto6rDPSnO9OdVdYGvwGDi3jjRGf5xLoDtX2dpsR9z5KptU+5A==",
"license": "MIT",
"dependencies": {
"@langchain/protocol": "^0.0.19",
@ -1194,9 +1194,9 @@
}
},
"node_modules/@langchain/langgraph-sdk/node_modules/p-timeout": {
"version": "7.0.1",
"resolved": "https://registry.npmjs.org/p-timeout/-/p-timeout-7.0.1.tgz",
"integrity": "sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg==",
"version": "7.0.2",
"resolved": "https://registry.npmjs.org/p-timeout/-/p-timeout-7.0.2.tgz",
"integrity": "sha512-prbX4Z3YszrFNgH+MW5Zoeq3baXrMtP/MQnFeET90UB/GtGcGDQ5Usg9OCy6ETjTTntOw1SL2z9fMPUppN3Guw==",
"license": "MIT",
"engines": {
"node": ">=20"
@ -2064,9 +2064,9 @@
"license": "MIT"
},
"node_modules/@ts-morph/common/node_modules/brace-expansion": {
"version": "1.1.18",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
"integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
"version": "1.1.21",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
"integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
"dev": true,
"license": "MIT",
"dependencies": {
@ -2438,9 +2438,9 @@
"license": "MIT"
},
"node_modules/@types/node": {
"version": "26.5.1",
"resolved": "https://registry.npmjs.org/@types/node/-/node-26.5.1.tgz",
"integrity": "sha512-CzNm2FezW4VR/LjG6yUdiEgLE/rAQ9Slj5gCu/C2VrdcW7I0ahNZ8DRbHT7zOZ6r3ONgd/bsQIeSaoDGrd1C6g==",
"version": "26.6.2",
"resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.2.tgz",
"integrity": "sha512-X1P21scMv4zGKLYqjdGjaKa7COa0RKVYYZZN/NfvLQ1JegxFhdhpZG/Lyn8AXx6CDUavKAd11v6BvfpkDByK8g==",
"devOptional": true,
"license": "MIT",
"dependencies": {
@ -3410,9 +3410,9 @@
}
},
"node_modules/brace-expansion": {
"version": "5.0.9",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
"integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
"version": "5.0.12",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz",
"integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==",
"dev": true,
"license": "MIT",
"dependencies": {
@ -4291,9 +4291,9 @@
"peer": true
},
"node_modules/dompurify": {
"version": "3.4.15",
"resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.15.tgz",
"integrity": "sha512-EUBjM+B+lkDE41iE82DDSCfkoPGfXx8IxFxPMjNzm/Uk4xDet77rTN9wqlxlVg71kK7XGuUMv6wUxJUwwv+Xyw==",
"version": "3.4.16",
"resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.16.tgz",
"integrity": "sha512-sqo+pNp3qRhCIpbgRi1y8Tgk27Bo2Ry7w0dC1NBeNTdZChWjz9Xb/KOoZbRP/R6pQZ80Qw8YhXw13hWWBbMRnQ==",
"license": "(MPL-2.0 OR Apache-2.0)",
"optionalDependencies": {
"@types/trusted-types": "^2.0.7"
@ -5108,9 +5108,9 @@
}
},
"node_modules/i18next": {
"version": "26.3.6",
"resolved": "https://registry.npmjs.org/i18next/-/i18next-26.3.6.tgz",
"integrity": "sha512-Bu5Z2nAXgfVyM8xvW3jk9EKRIuX37PudsrBViThNFx7CR7aaYTpP01cxNB/E4c4UUzTDiAZRstEhsRfPOL/8xA==",
"version": "26.4.2",
"resolved": "https://registry.npmjs.org/i18next/-/i18next-26.4.2.tgz",
"integrity": "sha512-RX+R0VLg13IbvRuJSxnqykUFS9vQZTl8wYpWPCIUDWVrSGjsQywB5Y+pjzrkboxGAuYfJZVH1InFTdgBdxq6ug==",
"funding": [
{
"type": "individual",
@ -5513,9 +5513,9 @@
"integrity": "sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw=="
},
"node_modules/langchain": {
"version": "1.5.11",
"resolved": "https://registry.npmjs.org/langchain/-/langchain-1.5.11.tgz",
"integrity": "sha512-6Sx9N5ylAJ11WrP1QnJLSIo75UABZbshzTJgG28H4mXuGcDk+w+7ZaNLkmGIh9sy/3PZcYS8UrI2rvH6A8NYIg==",
"version": "1.5.14",
"resolved": "https://registry.npmjs.org/langchain/-/langchain-1.5.14.tgz",
"integrity": "sha512-/orHDk5xbNSIJc9UhwmxFYHXbr/3RaBeQ3zX0xovEWfPg7Lmj8EJCMOXIUTCe2UtsFgfbyWtlwh51NM562LnZQ==",
"license": "MIT",
"dependencies": {
"@langchain/langgraph": "^1.4.13",
@ -5527,7 +5527,7 @@
"node": ">=20"
},
"peerDependencies": {
"@langchain/core": "^1.2.10"
"@langchain/core": "^1.2.13"
}
},
"node_modules/langsmith": {

12
gitnexus-web/package.json
View file

@ -19,16 +19,16 @@
},
"dependencies": {
"@langchain/anthropic": "^1.5.8",
"@langchain/core": "^1.2.8",
"@langchain/core": "^1.2.13",
"@langchain/google-genai": "^2.3.1",
"@langchain/langgraph": "^1.4.14",
"@langchain/langgraph": "^1.4.18",
"@langchain/ollama": "^1.3.0",
"@langchain/openai": "^1.5.13",
"@sigma/edge-curve": "^3.1.0",
"@tailwindcss/vite": "^4.3.3",
"axios": "^1.20.0",
"d3": "^7.9.0",
"dompurify": "^3.4.15",
"dompurify": "^3.4.16",
"gitnexus-shared": "file:../gitnexus-shared",
"graphology": "^0.26.0",
"graphology-indices": "^0.17.0",
@ -36,9 +36,9 @@
"graphology-layout-forceatlas2": "^0.10.1",
"graphology-layout-noverlap": "^0.4.2",
"graphology-utils": "^2.3.0",
"i18next": "^26.3.6",
"i18next": "^26.4.2",
"i18next-browser-languagedetector": "^8.2.1",
"langchain": "^1.5.11",
"langchain": "^1.5.14",
"lru-cache": "^11.5.3",
"lucide-react": "^1.46.0",
"mermaid": "^11.17.2",
@ -63,7 +63,7 @@
"@testing-library/react": "^16.3.3",
"@testing-library/user-event": "^14.6.7",
"@types/dompurify": "^3.2.0",
"@types/node": "^26.5.1",
"@types/node": "^26.6.2",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"@types/react-syntax-highlighter": "^15.5.13",

5
gitnexus/bench/emit-persistence/baselines-streaming.json
View file

@ -1,5 +1,6 @@
{
"fingerprint": "dadb6eb19a751c3d315b7c53effc6605f89e0a766b01cd5a2ae611b3720d0d55",
"fingerprint": "9408aad13feb6a65c6ce031a3264b72d1afdb1fdd1e984666fe30c3ecc24d66f",
"_rebaselined_3161_static_gated_column": "Same change as baselines.json's `_rebaselined_3161_static_gated_column`: every relationship row now ends in a `staticGated` cell (`0` here, no PDG edge is a gated call), so each of the 36,000 `rel_BasicBlock_BasicBlock.csv` data rows grew by 2 bytes (`...,\"T\",0` -> `...,\"T\",0,0`) while the 7,200 BasicBlock rows are unchanged. Evidence is the inverse operation: stripping the trailing `,0` from the rel rows and re-hashing the sorted bb + rel rows gives EXACTLY the prior baseline 381de8dede253140953775c290bf9a25f82ebf3cc8ecb5250ae06a63f648b089. byte_identical_nodes / byte_identical_edges stayed true and resident_basic_blocks stayed 0 while the fingerprint gate was red, so the streamed sink still matches the whole-graph emit byte for byte and the RSS bound holds. Prior 381de8dede253140953775c290bf9a25f82ebf3cc8ecb5250ae06a63f648b089 -> dadb6eb19a751c3d315b7c53effc6605f89e0a766b01cd5a2ae611b3720d0d55.",
"_note": "Byte-identity + bounded-retention gate for streaming/chunked PDG emit (#2202). fingerprint = sha256 of the sorted, header-stripped BasicBlock + PDG-edge data rows of the canonical synthetic set. --check also asserts the streamed PdgEmitSink output is byte-identical to the whole-graph streamAllCSVsToDisk emit (byte_identical_nodes/edges) and that the in-memory graph retains 0 BasicBlocks (resident_basic_blocks === 0, the O(chunk) RSS bound). Regenerate via `node --import tsx bench/emit-persistence/measure-streaming.mjs`."
"_note": "Byte-identity + bounded-retention gate for streaming/chunked PDG emit (#2202). fingerprint = sha256 of the sorted, header-stripped BasicBlock + PDG-edge data rows of the canonical synthetic set. --check also asserts the streamed PdgEmitSink output is byte-identical to the whole-graph streamAllCSVsToDisk emit (byte_identical_nodes/edges) and that the in-memory graph retains 0 BasicBlocks (resident_basic_blocks === 0, the O(chunk) RSS bound). Regenerate via `node --import tsx bench/emit-persistence/measure-streaming.mjs`.",
"_rebaselined_3442_ladybug_null_cells": "Same NULL serialization change as baselines.json (#3442). Compared the whole-graph output with the parent writer: file set, row order and all other bytes match. The fingerprinted BasicBlock and PDG-edge files contain exactly 38,400 quoted empty cells changed to bare cells (14,400 BasicBlock cells and 24,000 edge cells); restoring their quotes reproduces the exact prior fingerprint dadb6eb19a751c3d315b7c53effc6605f89e0a766b01cd5a2ae611b3720d0d55. The new fingerprint is 9408aad13feb6a65c6ce031a3264b72d1afdb1fdd1e984666fe30c3ecc24d66f. Both streamed/whole byte-identity flags remain true and resident_basic_blocks remains 0."
}

5
gitnexus/bench/emit-persistence/baselines.json
View file

@ -1,5 +1,5 @@
{
"fingerprint": "d3c3a53ead47663816344369dc0e501f31d60c462039de190ab6f5361037bd79",
"fingerprint": "2f5c46506cb8dfb79a65a276646ace766cc7645fabab8b383c89f5f0270cc30b",
"_rebaselined_objective_c_node_tables": "Objective-C support adds Protocol and Category node tables to csv-generator.ts's MULTI_LANG_TYPES, so this deterministic 2,400-entity synthetic emit now creates 38 CSV files rather than 36. The two additions, category.csv and protocol.csv, are both expected 55-byte header-only files because the synthetic graph contains no Objective-C nodes. Re-emitting the graph and recomputing the fingerprint after excluding exactly those two files yields the exact prior baseline 011485e5180c005be9dfec7ac8dc4e3bb0fcfc4a680a16dcae2cf2d8af5ef7e2, proving all 36 pre-existing files retain their bytes, routing, and within-file order. Prior 011485e5180c005be9dfec7ac8dc4e3bb0fcfc4a680a16dcae2cf2d8af5ef7e2 -> d3c3a53ead47663816344369dc0e501f31d60c462039de190ab6f5361037bd79. The timing guard remains within budget: local scaling_ratio 0.965 against 1.8 and elapsed_ms_large 69.24ms against 1000ms.",
"_rebaselined_3161_static_gated_column": "Every relationship row gained a trailing `staticGated` BOOLEAN column (RELATION_SCHEMA in src/core/lbug/schema.ts, REL_CSV_HEADER + buildRelRow in csv-generator.ts, the fallback CREATE in lbug-adapter.ts), written as `0` for every edge that does not carry the flag and `1` for a Zig call site inside a comptime-false branch (PR #3161). Unlike the earlier header-only rebaselines this one touches ROWS, so the evidence is the inverse operation rather than a file-set diff: re-emitting this bench's 2,400-entity graph on the branch produces the same 36 CSV files; exactly 3 of them differ from a copy with the new column stripped (`rel_File_Class.csv` 156228 -> 151416 bytes, `rel_File_Function.csv` 334008 -> 324396, `rel_Function_Function.csv` 185028 -> 180216: one header field plus `,0` per row, 4,800 / 9,600 / 4,800 rows, 2 bytes each), the other 33 files are byte-identical, and the per-file fingerprint over the stripped copies is EXACTLY the prior baseline 72096279092d4f118de7e179333705c19c9aff2664f77d71a7da48cd9f73fb5a. So no row moved between pair files and no row reordered; the only bytes that changed are the appended column. Prior 72096279092d4f118de7e179333705c19c9aff2664f77d71a7da48cd9f73fb5a -> 011485e5180c005be9dfec7ac8dc4e3bb0fcfc4a680a16dcae2cf2d8af5ef7e2. Timing gates passed while the guard was red: scaling_ratio 0.82 against the 1.8 budget, elapsed_ms_large 185.54ms against the 1000ms backstop, so no throughput claim is being rebaselined away.",
"scaling_budget": 1.8,
@ -9,5 +9,6 @@
"_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 \u2014 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.",
"_rebaselined_3107_route_runtime_evidence": "Route gained trailing runtimeConfirmed BOOLEAN, runtimeSource STRING, and runtimeStatus STRING columns in its schema, CSV header/rows, COPY statement, and graph API projection. The deterministic emit still produces the same 35 CSV files; the synthetic benchmark graph has no Route rows, so the only byte drift is the Route CSV header and no row moved or reordered. Prior c4d799c5336d616955b3530ba051b7dca300d1a0e412a66741cf2f27e04c533e -> 7b2ec01a110dcbc66868fba2c97714aaece8c3864c2eba00df68b5c027f034d2. While the guard was red, scaling_ratio was 1.044 against the 1.8 budget and elapsed_ms_large was 121.08ms against the 1000ms backstop.",
"_note": "fingerprint = sha256 over per-file digests (filename + sha256(file bytes)), entry list sorted \u2014 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 \u2014 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`."
"_note": "fingerprint = sha256 over per-file digests (filename + sha256(file bytes)), entry list sorted \u2014 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 \u2014 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`.",
"_rebaselined_3442_ladybug_null_cells": "LadybugDB 0.21.1 preserves quoted empty strings, so escapeCSVField now emits bare empty cells to retain the SQL NULL meaning of the 0.18.3 writer (#3442). Compared the canonical emit with the parent writer: all 38 file names and every row order match; exactly 31,200 quoted empty cells became bare cells in six files, with no other byte changes. Restoring quotes around those cells reproduces the exact prior fingerprint d3c3a53ead47663816344369dc0e501f31d60c462039de190ab6f5361037bd79. The new fingerprint is 2f5c46506cb8dfb79a65a276646ace766cc7645fabab8b383c89f5f0270cc30b. Timing budgets remain unchanged."
}

83
gitnexus/bench/incremental-write-integrity/README.md Normal file
View file

@ -0,0 +1,83 @@
# Incremental node identity reconciliation
From `gitnexus/`:
```sh
node --import tsx bench/incremental-write-integrity/measure.cjs --check
node bench/incremental-write-integrity/reproduce.cjs
```
The first command measures the production reconciliation, including every
single-label scan and comparison of ID, name, path and source range. Construction,
CSV loading, checkpoints and correctness controls are outside the timed region.
Two warm-ups precede seven measured samples. Exact counts and SHA-256 fixture
fingerprints reject empty or incomplete work. `--check` gates normalized scaling
against the committed budget, rather than a machine-specific time limit.
On Node v24.19.0, Linux x64, Xeon Platinum 8370C, the initial measurement was
583 ms for 16,384 nodes and 2,810 ms for 65,536 nodes per reconciliation. The
normalized scaling was 1.206 (budget 2). Analyze performs two reconciliations:
after graph COPY/checkpoint and after FTS/embedding work plus a final checkpoint,
before registration, freshness metadata or staging publication.
The verifier covers retained nodes as well as the write set. A path/range filter
would let a corrupted field hide its own row; a count would miss swapped fields
or blank IDs. Folder lifecycle, preserved Community/Process layers and streamed
BasicBlock rows require other oracles and are excluded. Relationships and source
content are outside this identity check.
## Native-only reduction
`reproduce.cjs` uses only `@ladybugdb/core`, its native schema/query/COPY API, and
synthetic ASCII CSV files. There is no parser, parse cache, graph adapter, FTS,
relationship table, periodic checkpoint driver or concurrent writer. Compression
is disabled and COPY is serial, matching the production settings.
It loads 8,192 Function rows, checkpoints, deletes 64 rows belonging to the first
and last owners, then copies back those same 64 tuples. An independent tuple-set
oracle validates the complete single-label scan before and after each operation.
It also compares affected scan rows with primary-key lookups after reopening.
Use `--keep` to retain the synthetic database and CSV files; the JSON output gives
their directory. `--require-corruption` is a diagnostic assertion, deliberately
not a CI requirement: it should fail when the native defect is fixed.
With the original `@ladybugdb/core` 0.18.3, this reduction produced:
| Phase | Rows | Incorrect tuples |
| ------------------------- | ----: | ---------------: |
| Initial COPY + checkpoint | 8,192 | 0 |
| DELETE | 8,128 | 0 |
| Incremental COPY | 8,192 | 3,936 |
| Explicit checkpoint | 8,192 | 3,936 |
| Read-only reopen | 8,192 | 3,936 |
With `@ladybugdb/core` 0.21.1, the same reduction returns zero incorrect
tuples in every phase. The production reconciliation and negative controls
remain required; this result covers the reduced fixture, not a replay of the
original incident.
For example, the scan returned an empty `id` at native offset 64, while a
primary-key lookup at that same offset returned
`Function:src/owner2.ts:fn64` with the correct name/path/range. Smaller 1,024,
2,048 and 4,096-row fixtures remained healthy in the same three-cycle adapter
probe. The affected tuple count varies with fixture size and scan shape.
This isolates a native scan/lookup discrepancy introduced by incremental COPY
into a previously populated table. It survives checkpoint and reopen, but does
not establish physical byte loss or the precise C++ defect. The reported Unicode
change and FTS build are unnecessary for this reduction; this does not prove
that the original incident has exactly the same native cause.
The measurement harness runs selective native writes too. An independent oracle
requires the production verifier to reject any inconsistent scan, both before
and after checkpoint/reopen; healthy scans must certify their complete identity
set. It does not quietly treat the native discrepancy as a successful graph.
Missing-row and swapped-range negative controls separately verify that the
check fails closed. Publication tests inject damage after COPY and after FTS,
assert unchanged registry/freshness, preserve the live staged baseline, and
exercise automatic dirty-index recovery followed by a no-op run.
An in-place verification failure keeps a non-FTS dirty phase: an FTS-only
repair cannot clear the marker and recertify the inconsistent graph.
The same protection applies when FTS returns but analyzer finalization fails
before the final identity scan: recovery still rebuilds the graph.

14
gitnexus/bench/incremental-write-integrity/baseline.json Normal file
View file

@ -0,0 +1,14 @@
{
"version": 1,
"linear_scaling_budget": 2,
"sizes": [
{
"nodes": 16384,
"fingerprint": "17aa2ded124af9cbd15a9fe13013410e92a478f88e63a2ad9859a05aacef8efe"
},
{
"nodes": 65536,
"fingerprint": "a6ce82aa1d07804d16b916892dfb6ca0e6f5ce5ed606f47cb1321eb124c6ac44"
}
]
}

194
gitnexus/bench/incremental-write-integrity/measure.cjs Normal file
View file

@ -0,0 +1,194 @@
#!/usr/bin/env node
/**
* Native identity reconciliation overhead and scaling.
* node --import tsx bench/incremental-write-integrity/measure.cjs [--check]
*
* COPY, graph construction, fingerprints and correctness controls are untimed.
* Each timed sample includes all single-label scans and exact tuple checks.
* Counts/fingerprints reject empty output; timing gates use normalized scaling.
*/
const assert = require('node:assert/strict');
const { mkdtemp, rm, readFile } = require('node:fs/promises');
const { tmpdir, cpus } = require('node:os');
const { join, resolve } = require('node:path');
const { pathToFileURL } = require('node:url');
const { createHash } = require('node:crypto');
const ROOT = resolve(__dirname, '../..');
const source = (file) => import(pathToFileURL(join(ROOT, file)).href);
(async () => {
const { createKnowledgeGraph } = await source('src/core/graph/graph.ts');
const { reconcileGraphNodeIdentities } = await source(
'src/core/incremental/write-reconciliation.ts',
);
const adapter = await source('src/core/lbug/lbug-adapter.ts');
const baseline = JSON.parse(await readFile(join(__dirname, 'baseline.json'), 'utf8'));
assert.equal(baseline.version, 1);
assert.ok(Number.isFinite(baseline.linear_scaling_budget) && baseline.linear_scaling_budget > 0);
const results = [];
for (const size of baseline.sizes) {
assert.ok(Number.isSafeInteger(size.nodes) && size.nodes > 0);
assert.match(size.fingerprint, /^[a-f0-9]{64}$/);
const graph = createKnowledgeGraph();
const hash = createHash('sha256');
for (let i = 0; i < size.nodes; i++) {
const id = `Function:src/owner${Math.floor(i / 32)}.ts:fn${i}`;
const properties = {
name: `fn${i}`,
filePath: `src/owner${Math.floor(i / 32)}.ts`,
startLine: (i % 32) * 4,
endLine: (i % 32) * 4 + 2,
};
graph.addNode({ id, label: 'Function', properties });
hash.update(
JSON.stringify([
id,
properties.name,
properties.filePath,
properties.startLine,
properties.endLine,
]) + '\n',
);
}
assert.equal(hash.digest('hex'), size.fingerprint);
const directory = await mkdtemp(join(tmpdir(), 'gnx-reconciliation-bench-'));
try {
await adapter.initLbug(join(directory, 'lbug'), { skipFts: true });
await adapter.loadGraphToLbug(
graph,
directory,
directory,
undefined,
undefined,
undefined,
'none',
);
await adapter.tryFlushWAL();
const samples = [];
let calls = 0;
const query = async (sql) => {
calls++;
return adapter.executeQuery(sql);
};
for (let run = 0; run < 9; run++) {
calls = 0;
const start = performance.now();
const receipt = await reconcileGraphNodeIdentities(graph, query, 'benchmark');
const elapsed = performance.now() - start;
assert.equal(receipt.nodes, size.nodes);
assert.equal(calls, receipt.tables);
if (run >= 2) samples.push(elapsed);
}
const first = graph.iterNodes().next().value;
const alteredQuery = async (sql) => {
const rows = await adapter.executeQuery(sql);
if (sql.includes('(n:`Function`)')) rows.find((r) => r.id === first.id).startLine++;
return rows;
};
await assert.rejects(
reconcileGraphNodeIdentities(graph, alteredQuery, 'negative-control'),
/startLine/,
);
await assert.rejects(
reconcileGraphNodeIdentities(graph, async () => [], 'negative-control'),
/missing ID/,
);
// Native 0.18.3 can corrupt scan projections after this real write, even
// without FTS. Use an independent tuple-set oracle to require rejection
// whenever the scan is wrong; a future native fix can pass normally.
const { extractChangedSubgraph } = await source('src/core/incremental/subgraph-extract.ts');
const files = new Set(['src/owner0.ts', `src/owner${Math.floor((size.nodes - 1) / 32)}.ts`]);
const wanted = new Set(
[...graph.iterNodes()].map((node) =>
JSON.stringify([
node.id,
node.properties.name,
node.properties.filePath,
node.properties.startLine,
node.properties.endLine,
]),
),
);
const nativePhases = [];
const audit = async (phase) => {
const rows = await adapter.executeQuery(
'MATCH (n:Function) RETURN n.id AS id, n.name AS name, ' +
'n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine',
);
const actual = new Set(
rows.map((r) => JSON.stringify([r.id, r.name, r.filePath, r.startLine, r.endLine])),
);
const mismatched = [...wanted].filter((tuple) => !actual.has(tuple)).length;
const rejected =
rows.length !== size.nodes || mismatched > 0 || actual.size !== wanted.size;
if (rejected) {
await assert.rejects(
reconcileGraphNodeIdentities(graph, adapter.executeQuery, phase),
/Graph identity reconciliation/,
);
} else {
assert.equal(
(await reconcileGraphNodeIdentities(graph, adapter.executeQuery, phase)).nodes,
size.nodes,
);
}
nativePhases.push({
phase,
rows: rows.length,
missing_tuples: mismatched,
verdict: rejected ? 'rejected' : 'certified',
});
};
await adapter.deleteNodesForFiles([...files]);
await adapter.loadGraphToLbug(
extractChangedSubgraph(graph, files),
directory,
directory,
undefined,
undefined,
undefined,
'none',
);
await audit('post-COPY');
await adapter.tryFlushWAL();
await audit('post-checkpoint');
await adapter.closeLbug();
await adapter.initLbug(join(directory, 'lbug'), { readOnly: true, skipFts: true });
await audit('reopened');
samples.sort((a, b) => a - b);
results.push({
nodes: size.nodes,
queries: calls,
min_ms: +samples[0].toFixed(3),
median_ms: +samples[Math.floor(samples.length / 2)].toFixed(3),
fingerprint: size.fingerprint,
native_phases: nativePhases,
});
} finally {
await adapter.closeLbug();
await rm(directory, { recursive: true, force: true });
}
}
const scaling =
results[1].median_ms / results[0].median_ms / (results[1].nodes / results[0].nodes);
const report = {
node: process.version,
platform: process.platform,
cpu: cpus()[0].model,
results,
normalized_scaling: +scaling.toFixed(3),
negative_controls: 'missing/swapped fields rejected',
native_sequences:
'selective delete/COPY, checkpoint and read-only reopen checked against independent tuple oracle',
};
process.stdout.write(JSON.stringify(report, null, 2) + '\n');
if (process.argv.includes('--check'))
assert.ok(
scaling <= baseline.linear_scaling_budget,
`normalized scaling ${scaling} exceeds ${baseline.linear_scaling_budget}`,
);
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});

187
gitnexus/bench/incremental-write-integrity/reproduce.cjs Normal file
View file

@ -0,0 +1,187 @@
#!/usr/bin/env node
/** Native-only selective COPY scan discrepancy; no parser, graph adapter or FTS. */
const assert = require('node:assert/strict');
const fs = require('node:fs/promises');
const os = require('node:os');
const path = require('node:path');
const lbug = require('@ladybugdb/core');
(async () => {
const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'ladybug-copy-identity-'));
let database;
let connection;
const close = async () => {
// Retire this session before closing so failures or reopening cannot close it twice.
const activeConnection = connection;
const activeDatabase = database;
connection = undefined;
database = undefined;
const errors = [];
try {
await activeConnection?.close();
} catch (error) {
errors.push(error);
}
try {
await activeDatabase?.close();
} catch (error) {
errors.push(error);
}
if (errors.length === 1) throw errors[0];
if (errors.length > 1) throw new AggregateError(errors, 'Native resource cleanup failed');
};
const errors = [];
try {
const dbPath = path.join(directory, 'lbug');
const count = 8192;
const tuple = (i) => [
`Function:src/owner${Math.floor(i / 32)}.ts:fn${i}`,
`fn${i}`,
`src/owner${Math.floor(i / 32)}.ts`,
(i % 32) * 4,
(i % 32) * 4 + 2,
];
const indices = Array.from({ length: count }, (_, i) => i);
const expected = new Set(indices.map((i) => JSON.stringify(tuple(i))));
const csv = (rows) =>
'id,name,filePath,startLine,endLine\n' +
rows
.map((i) =>
tuple(i)
.map((value) => JSON.stringify(value))
.join(','),
)
.join('\n') +
'\n';
await fs.writeFile(path.join(directory, 'full.csv'), csv(indices));
await fs.writeFile(
path.join(directory, 'delta.csv'),
csv(indices.filter((i) => i < 32 || i >= count - 32)),
);
// Match GitNexus's uncompressed native constructor and serial COPY options.
const open = (readOnly) =>
new lbug.Database(
dbPath,
256 * 1024 * 1024,
false,
readOnly,
4 * 1024 ** 3,
true,
64 * 1024 * 1024,
true,
true,
);
database = open(false);
connection = new lbug.Connection(database);
const query = async (cypher, params) => {
const result = params
? await connection.execute(await connection.prepare(cypher), params)
: await connection.query(cypher);
try {
return await result.getAll();
} finally {
await result.close();
}
};
const copy = (file) =>
query(
`COPY Function FROM "${path.join(directory, file).replace(/\\/g, '/')}" ` +
`(HEADER=true, ESCAPE='"', DELIM=',', QUOTE='"', PARALLEL=false, auto_detect=false)`,
);
const phases = [];
const scan = async (phase) => {
const rows = await query(
'MATCH (n:Function) RETURN id(n) AS internalID, n.id AS id, n.name AS name, ' +
'n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine',
);
const key = (r) => JSON.stringify([r.id, r.name, r.filePath, r.startLine, r.endLine]);
const bad = rows.filter((r) => !expected.has(key(r)));
const actual = new Set(rows.map(key));
const missing = [...expected].filter((value) => !actual.has(value)).length;
phases.push({
phase,
rows: rows.length,
wrong_tuples: bad.length,
missing_tuples: missing,
examples: bad.slice(0, 2),
});
return { rows, bad, missing };
};
await query(
'CREATE NODE TABLE Function(id STRING, name STRING, filePath STRING, ' +
'startLine INT64, endLine INT64, PRIMARY KEY(id))',
);
await copy('full.csv');
await query('CHECKPOINT');
const before = await scan('baseline');
assert.equal(before.rows.length, count);
assert.equal(before.missing, 0);
const baselineIdsByOffset = new Map(before.rows.map((r) => [r.internalID.offset, r.id]));
await query(
"MATCH (n:Function) WHERE n.filePath IN ['src/owner0.ts', 'src/owner255.ts'] DETACH DELETE n",
);
const deleted = await scan('after-delete');
assert.equal(deleted.rows.length, count - 64);
assert.equal(deleted.bad.length, 0);
await copy('delta.csv');
const copied = await scan('after-copy');
await query('CHECKPOINT');
await scan('after-checkpoint');
await close();
database = open(true);
connection = new lbug.Connection(database);
const reopened = await scan('reopened');
const pointLookups = [];
for (const row of reopened.bad.slice(0, 2)) {
const id = baselineIdsByOffset.get(row.internalID.offset);
if (!id) continue;
pointLookups.push({
scan: row,
lookup: await query(
'MATCH (n:Function {id: $id}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, ' +
'n.startLine AS startLine, n.endLine AS endLine',
{ id },
),
});
}
process.stdout.write(
JSON.stringify(
{
native_version: lbug.VERSION,
node: process.version,
phases,
point_lookups: pointLookups,
...(process.argv.includes('--keep') ? { directory } : {}),
},
null,
2,
) + '\n',
);
if (process.argv.includes('--require-corruption')) {
assert.ok(
copied.bad.length > 0 || copied.missing > 0 || copied.rows.length !== count,
'Native failure did not reproduce; this is a diagnostic, not a passing CI invariant',
);
}
} catch (error) {
errors.push(error);
} finally {
try {
await close();
} catch (error) {
errors.push(error);
}
try {
if (!process.argv.includes('--keep'))
await fs.rm(directory, { recursive: true, force: true });
} catch (error) {
errors.push(error);
}
}
if (errors.length === 1) throw errors[0];
if (errors.length > 1) throw new AggregateError(errors, 'Native benchmark failed');
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});

6
gitnexus/bench/scope-capture/baselines.json
View file

@ -119,7 +119,8 @@
"_rebaselined_3354_callable_alternatives": "#3354 callable alternatives: a callable chosen by a value-selecting source now flows every branch it can yield (`a ?? b`, `a || b`, `a or b`, `c ? a : b`, statement `if`, elvis), and an operator branch (`x == f || g`) stays opaque instead of seeding a qualified name. Verified by running the BASE (merge-base 233ca2849) and HEAD emitters over the SAME HEAD fixture corpus: every added or removed match is an `@callable-flow.*` match on one of those sources, and the pre-existing corpus is byte-identical (all other languages: zero delta). The rest of the drift is corpus growth from this PR's regression fixture, which this bench globs. Corpus growth: ruby-callable-alternatives/app.rb (+1 file, +58 groups). Emitter delta: +5 / -0: seeds for single-statement `if` / `elsif` branches (run_then, run_else, run_sweep, run_a, run_b); the multi-statement branch contributes nothing. capture_groups_fp 1358 -> 1416, fixture_count 91 -> 92; synthetic counts unchanged; scaling 1.04 < 1.5. Prior 1c8c9c4b54036fa24c2a81e39ea530e938645c856d369075e5f437da78218c57 -> 45e65d9fa8a9e5e905ddb596b179b77c86ed13ab5139c6b17ccaaf7315dfe46a."
},
"swift": {
"fingerprint": "d56406c2645637042899cfcc8dc73f603d77caef0a9a2bac179ffbec848258a3",
"fingerprint": "2507ac75ba6fb47c272a5caa97b5e8b9f6ebc5098c15295d05c7bff3cabc321a",
"_rebaselined_3425_injected_closure": "Swift capture fixture growth: 83 to 85 fixtures, 1436 to 1553 capture groups; scaling budget unchanged.",
"_rebaselined_3355_xcode_and_import_fixtures": "#3355 follow-up: new swift-xcode-targets fixture (four sources) and two sources added to swift-nested-packages (a Docs/Net folder decoy and an `import Net` caller). The capture query is unchanged; this is fixture-corpus growth only. capture_groups_fp 1393 -> 1436 and fixture_count 77 -> 83; synthetic scale counts remain 5012/16012. Prior aea33bf12f57561be7e3125929fb98cec7aed5a681e25aad435c7bb558747853 -> d56406c2645637042899cfcc8dc73f603d77caef0a9a2bac179ffbec848258a3; measured scaling 1.036 < 1.5.",
"_rebaselined_3355_nested_packages": "#3355: new swift-nested-packages fixture (three nested Package.swift manifests, six sources) for nested-package module grouping. The capture query is unchanged; this is fixture-corpus growth only. capture_groups_fp 1333 -> 1393 and fixture_count 68 -> 77; synthetic scale counts remain 5012/16012. Prior c9fc553662f0db18027fba882e3ff730744f6153cc46eca7b00667fabd6a0df8 -> aea33bf12f57561be7e3125929fb98cec7aed5a681e25aad435c7bb558747853; measured scaling 1.023 < 1.5.",
"scaling_budget": 1.5,
@ -187,7 +188,8 @@
"capture_groups_fp": 680
},
"typescript": {
"fingerprint": "77c9b4ea654123a64972db8348190ec250b669472b150db65ea8c7f20b355467",
"fingerprint": "a7972d87abd253583dafa37443bee8ddf5c635d41b4dfbb0c831efda71d82b47",
"_rebaselined_3446_mcp_tools_fixture": "#3446 adds typescript-mcp-tools/src/{handlers,server,tools}.ts: corpus growth only, with fixture_count 171 -> 174 and capture_groups_fp 2753 -> 2894. Excluding only that fixture directory restores the prior fingerprint 77c9b4ea654123a64972db8348190ec250b669472b150db65ea8c7f20b355467 exactly. The scope emitter, synthetic capture counts (4503/14403), scaling budget, and other language baselines are unchanged.",
"_rebaselined_3190": "Capture matches now retain explicit ESM export/private evidence, including synthesized default HOCs; CommonJS surfaces remain undecided. Capture group counts unchanged. Scaling budget unchanged.",
"scaling_budget": 1.5,
"_rebaselined_2934_import_type_only": "#2934: `import-decomposer.ts` attaches a presence-only `@import.type-only` synthetic capture to specifiers `tsc` erases, so `check --cycles` can stop counting type-only edges as initialization cycles. DIGEST DRIFT ONLY, NOT A CAPTURE-SET CHANGE \u2014 the tag is added to import matches that already existed, never a new match, the same shape as the #2747 receiver-chain rebaseline. Every count is unchanged: capture_groups_fp 2414, fixture_count 155, capture_groups_small/large 4503/14403 (those measure the SYNTHETIC scaling source, which has no imports at all). The fingerprint moves because `canonicalizeMatch` in measure.mjs hashes every TAG on every match, synthetics included, so one extra presence-only tag on an existing match rewrites that match's canonical string. Attribution is exact, not inferred: neutralizing ONLY the `m['@import.type-only'] = \u2026` assignment in import-decomposer.ts and re-running returns the fingerprint to c2fbf8a89e5686dd\u2026 byte-for-byte, so nothing else in the TypeScript capture stream moved. All 14 other languages report ok. Scaling 0.997 < 1.5. NOTE ON THE CONTROL: javascript did not move (2026993b\u2026, 43 fixtures), but it is a WEAK control here \u2014 `import type` is TypeScript-only syntax, so a JS corpus cannot express the construct and could not have drifted either way. It evidences no collateral damage, not the correctness of the TS change; the exact-attribution check above is what does that. Prior c2fbf8a89e5686dd1ff3659b20d41d8b05ebcc9790356e3653ee0c8ca5d365c8 -> f719163eb03a447c9e40ca316a905dd76cee82192a75a403df478ebbdc13e98f.",

86
gitnexus/package-lock.json generated
View file

@ -10,7 +10,7 @@
"hasInstallScript": true,
"license": "PolyForm-Noncommercial-1.0.0",
"dependencies": {
"@ladybugdb/core": "0.18.3",
"@ladybugdb/core": "0.21.1",
"@modelcontextprotocol/sdk": "^1.0.0",
"@scarf/scarf": "^1.4.0",
"busboy": "^1.6.0",
@ -724,9 +724,9 @@
}
},
"node_modules/@ladybugdb/core": {
"version": "0.18.3",
"resolved": "https://registry.npmjs.org/@ladybugdb/core/-/core-0.18.3.tgz",
"integrity": "sha512-XjpPKW4MrL28D2gYGTZuIjiEcPx12L21lx58QggrdrItw8o/e9Lmg/Ejoo4Kz08lZj+rIcC1Fu9thzIYOTUlJw==",
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core/-/core-0.21.1.tgz",
"integrity": "sha512-G0LWyn/dIqX9yHlyjpR12Rvou2o1dvCB9EkuzGa5ykCYbzur8EQhRUbi4fw3FlbckWvR6rK/tVbnFpBcRLwiHg==",
"hasInstallScript": true,
"license": "MIT",
"dependencies": {
@ -735,17 +735,17 @@
"node-addon-api": "^6.0.0"
},
"optionalDependencies": {
"@ladybugdb/core-darwin-arm64": "0.18.3",
"@ladybugdb/core-darwin-x64": "0.18.3",
"@ladybugdb/core-linux-arm64": "0.18.3",
"@ladybugdb/core-linux-x64": "0.18.3",
"@ladybugdb/core-win32-x64": "0.18.3"
"@ladybugdb/core-darwin-arm64": "0.21.1",
"@ladybugdb/core-darwin-x64": "0.21.1",
"@ladybugdb/core-linux-arm64": "0.21.1",
"@ladybugdb/core-linux-x64": "0.21.1",
"@ladybugdb/core-win32-x64": "0.21.1"
}
},
"node_modules/@ladybugdb/core-darwin-arm64": {
"version": "0.18.3",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-arm64/-/core-darwin-arm64-0.18.3.tgz",
"integrity": "sha512-DGZTOlvSS4esEb1vTekY5IDoAvZAeYzR5cXVkECtQj9BVkk05zsvCAdTPo1Rz1BuI0qvqUVF+2WlIerI67iA2g==",
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-arm64/-/core-darwin-arm64-0.21.1.tgz",
"integrity": "sha512-TEFYNqBdbIojf1t29p3esgRhMDm56lD5eK91dwWFZJTVWAZoGXn+yLKs0NUQgj3lW2ZquuRTLZGglPhFEsDL1Q==",
"cpu": [
"arm64"
],
@ -756,9 +756,9 @@
]
},
"node_modules/@ladybugdb/core-darwin-x64": {
"version": "0.18.3",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-x64/-/core-darwin-x64-0.18.3.tgz",
"integrity": "sha512-Qp6j0CM/orBlK6KD0p/s4ofkIhNUwi1hdCgMw+fj81UHugWHkVLiYV4grRBdHhyplw+snchZpTxvfpxFbkG1Cw==",
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-x64/-/core-darwin-x64-0.21.1.tgz",
"integrity": "sha512-w9p3oKrqeMOeWpX3xdCc/hQJHfrZtpB9We+Ir+0qyls68dSQoeXXR1GZYzzTElOtxr4OM5USwYbVyxADx+CMZg==",
"cpu": [
"x64"
],
@ -769,9 +769,9 @@
]
},
"node_modules/@ladybugdb/core-linux-arm64": {
"version": "0.18.3",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-arm64/-/core-linux-arm64-0.18.3.tgz",
"integrity": "sha512-F9miYjBuS43I7uNG199FNMqwdHJ98WA6dU3v2SZCeLXmXCdRzmYcuHQWlbNr2Tba9CX58w2XvBZoUaXZKJ/yKQ==",
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-arm64/-/core-linux-arm64-0.21.1.tgz",
"integrity": "sha512-TodWmzOHxmmKvXXo9buBXGeyolxf/NqBUbo/LcR/tuMViKhGH8TBzIXi8DfVVwmsJ+CQCU065TvXgv2JoHAlZg==",
"cpu": [
"arm64"
],
@ -782,9 +782,9 @@
]
},
"node_modules/@ladybugdb/core-linux-x64": {
"version": "0.18.3",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-x64/-/core-linux-x64-0.18.3.tgz",
"integrity": "sha512-AfG5RDp/f/IDctDMpTAT5+2MYNtlWT191xiQNjSaWD4X85DhY3Dzps8Qu5VteIAPih5d6mmoaKGs8q0XIjfkFA==",
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-x64/-/core-linux-x64-0.21.1.tgz",
"integrity": "sha512-hCcLYv8ds0x4fkTaRkuc4f75KLdH9e0EV51ne6uBNdQSY7kyc0RgSoUG3utUGfFDMMkfgIJAeIxQY4ck9jQiXg==",
"cpu": [
"x64"
],
@ -795,9 +795,9 @@
]
},
"node_modules/@ladybugdb/core-win32-x64": {
"version": "0.18.3",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-win32-x64/-/core-win32-x64-0.18.3.tgz",
"integrity": "sha512-bHuFk0m9cnq0WGd9I4D8or8g6cC/BS58iatMtilqM3JpDPIQIFk6MQl6exL7P4xyWbkLwQgsrv2ToDnyoQNKvg==",
"version": "0.21.1",
"resolved": "https://registry.npmjs.org/@ladybugdb/core-win32-x64/-/core-win32-x64-0.21.1.tgz",
"integrity": "sha512-nBS1XSRJfpexdlhkezmEiRtkUt2qEDp4zBjIhH+oxgRdD7UsRz1Jyit8foJuZAmUsoQGukN5LO+YeyDU2WZTyA==",
"cpu": [
"x64"
],
@ -854,9 +854,9 @@
}
},
"node_modules/@nodable/entities": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-3.0.0.tgz",
"integrity": "sha512-8L9xFeTYKhm49xfIypoe2W5wV1m/3Z58kT+7kR9A8OyFxcPduI4VmxaUMQyKYrRjUoLLSXv6EKKID5Tvj9cUVw==",
"version": "3.1.0",
"resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-3.1.0.tgz",
"integrity": "sha512-LsS/DjHr+uDM647Gru/cA8+J3a3HfhttwCKLyuoyN7yXTFCxKBtSgMQBvrW9yNPa2/zDRUNuGPaH5QUFoa4arQ==",
"funding": [
{
"type": "github",
@ -1277,9 +1277,9 @@
"license": "MIT"
},
"node_modules/@types/node": {
"version": "26.6.2",
"resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.2.tgz",
"integrity": "sha512-X1P21scMv4zGKLYqjdGjaKa7COa0RKVYYZZN/NfvLQ1JegxFhdhpZG/Lyn8AXx6CDUavKAd11v6BvfpkDByK8g==",
"version": "26.6.3",
"resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.3.tgz",
"integrity": "sha512-dsqMQQoeTLqu9wynDD00q573mNzso3IdQOAfHRJqLCcmCFPoGo9A1bDpUcv/9tnKpErQWv9uKeGfl37EIS02Yg==",
"dev": true,
"license": "MIT",
"dependencies": {
@ -2025,9 +2025,9 @@
}
},
"node_modules/brace-expansion": {
"version": "5.0.9",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
"integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
"version": "5.0.12",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz",
"integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==",
"license": "MIT",
"dependencies": {
"balanced-match": "^4.0.2"
@ -2701,9 +2701,9 @@
"license": "MIT"
},
"node_modules/fast-uri": {
"version": "3.1.7",
"resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.7.tgz",
"integrity": "sha512-dOvZVzjdZdz7phd9v6jCbwxrBW3fK6n8Rc0CtdmM4bumzMnxywBYhuph6J819RRw/ku+rLbelwfMunktuzVVHg==",
"version": "3.1.8",
"resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.8.tgz",
"integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==",
"funding": [
{
"type": "github",
@ -2733,9 +2733,9 @@
}
},
"node_modules/fast-xml-parser": {
"version": "5.11.1",
"resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.11.1.tgz",
"integrity": "sha512-TBw6K/fxoQGGjCmZDw9w/ZwP3uDcnTM4YH/g+PFRWr8sbe5idXtxNN6vITh4+1ruCZaho6uBFurElsA7F0zzgw==",
"version": "5.11.2",
"resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.11.2.tgz",
"integrity": "sha512-R9iDuNrQYeQut46cn2r2wHKn4HYzVDvDm5J1wW+koZewykv0yuO2HChTYeZtrULyHIDM9cj9TUXloCsueCQUog==",
"funding": [
{
"type": "github",
@ -2744,7 +2744,7 @@
],
"license": "MIT",
"dependencies": {
"@nodable/entities": "^3.0.0",
"@nodable/entities": "^3.0.1",
"fast-xml-builder": "^1.2.0",
"is-unsafe": "^2.0.0",
"path-expression-matcher": "^1.6.2",
@ -3130,9 +3130,9 @@
"license": "ISC"
},
"node_modules/ip-address": {
"version": "10.4.0",
"resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.4.0.tgz",
"integrity": "sha512-oSK96Grm3aP6OrS263xVxbNDGVL7rzBtYdpGqlDG8iQdoenDoTs/nkki+DflYbAEE8Xl6o5YxhxlrKvI3nqKXQ==",
"version": "10.7.2",
"resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.2.tgz",
"integrity": "sha512-7H/2gFSIitxc0hG3nOI1glS8QLo/EHBFFLk8vEUjXY/xu0AdL8jZ9U1IzO2PUm0d2D/ofQcAifb0g6OBkt8U7w==",
"license": "MIT",
"engines": {
"node": ">= 12"

2
gitnexus/package.json
View file

@ -65,7 +65,7 @@
"version": "node scripts/sync-plugin-manifests.mjs"
},
"dependencies": {
"@ladybugdb/core": "0.18.3",
"@ladybugdb/core": "0.21.1",
"@modelcontextprotocol/sdk": "^1.0.0",
"@scarf/scarf": "^1.4.0",
"busboy": "^1.6.0",

9
gitnexus/src/cli/detect-changes-format.ts
View file

@ -1,5 +1,6 @@
import { t } from './i18n/index.js';
import { formatSymbolLine } from './format-symbol.js';
import { formatPathForTerminal } from './format-path.js';
type DetectChangesSummary = {
changed_files?: number;
@ -32,6 +33,7 @@ type DetectChangesResult = {
summary?: DetectChangesSummary;
changed_symbols?: ChangedSymbol[];
affected_processes?: AffectedProcess[];
unmapped_files?: string[];
};
export function formatDetectChangesResult(result: unknown): string {
@ -47,6 +49,13 @@ export function formatDetectChangesResult(result: unknown): string {
// Both lead the output — a caveat printed after the summary is read too late.
const notes: string[] = [];
if (payload.partial) notes.push(t('tool.detectChanges.partial'));
if (payload.unmapped_files?.length) {
notes.push(
t('tool.detectChanges.unmappedSource', {
files: payload.unmapped_files.map(formatPathForTerminal).join(', '),
}),
);
}
// The plain truncation note reassures that the counts are whole. That is only
// true when the run did NOT also degrade — `changed_count` sums the batches
// that succeeded — so the two flags together get a different sentence.

18
gitnexus/src/cli/embeddings-sync.ts
View file

@ -4,7 +4,11 @@ import { LBUG_DIRECTORY } from '../storage/storage-constants.js';
import path from 'node:path';
import { cliInfo } from './cli-message.js';
import { getGitRoot } from '../storage/git.js';
import { acquireIndexLock, requireExclusiveIndexLock } from '../storage/index-lock.js';
import {
acquireIndexLock,
requireExclusiveIndexLock,
sweepStagingArtifacts,
} from '../storage/index-lock.js';
import { getStoragePaths, loadMeta, saveMeta } from '../storage/repo-manager.js';
import {
closeLbug,
@ -50,12 +54,22 @@ export const embeddingsSyncCommand = async (inputPath?: string): Promise<void> =
// Writes go to the slot's own graph. A shared-store checkout that reads an
// immutable commit graph (#3352) takes a private copy first.
const lbugPath = path.join(metaDir, LBUG_DIRECTORY);
const lock = await acquireIndexLock(metaDir);
const lock = await acquireIndexLock(metaDir, { sweep: false });
try {
requireExclusiveIndexLock(
lock,
`Cannot acquire the index lock at ${metaDir}; refusing an unlocked embeddings sync.`,
);
// Sync writes the published graph and cannot recover a staged generation.
// Reject even malformed receipts before sweeping staging files or writing.
const recoveryCheckpoint = (await loadMeta(metaDir))?.embeddingCheckpoint;
if (recoveryCheckpoint && Object.hasOwn(recoveryCheckpoint, 'recovery')) {
throw new Error(
'Cannot sync embeddings: the index checkpoint references staged embeddings. ' +
'Run `gitnexus analyze` to recover them first.',
);
}
sweepStagingArtifacts(metaDir);
if (!(await ensurePrivateSharedGraph(metaDir, (m) => console.log(` ${m}`)))) {
throw new Error('The shared graph this checkout reads is gone. Run gitnexus analyze first.');
}

8
gitnexus/src/cli/format-path.ts Normal file
View file

@ -0,0 +1,8 @@
/** Quote control-bearing paths for terminal output; structured results retain raw paths. */
export const formatPathForTerminal = (filePath: string): string =>
/[\u0000-\u001f\u007f-\u009f]/.test(filePath)
? JSON.stringify(filePath).replace(
/[\u007f-\u009f]/g,
(char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`,
)
: filePath;

7
gitnexus/src/cli/group-status-format.ts
View file

@ -4,16 +4,18 @@
* against a real group, which is how `STALE (-1 commits behind)` went unnoticed
* (#3256).
*/
import type { StalenessStatus } from '../core/staleness-status.js';
/** The fields of a `groupStatus` repo row the index column reads. */
export interface GroupRepoIndexRow {
indexStale: boolean;
commitsBehind?: number;
status?: StalenessStatus;
}
/**
* The index column of a `group status` row. The output is unchanged except
* for one case: a count that is not a real count renders as `?`.
* The index column of a `group status` row. Diverged indexes differ from HEAD
* without a forward commit count; an unavailable count renders as `?`.
*
* `group/service.ts` has always reported a repo with no recorded commit as
* `{ indexStale: true, commitsBehind: -1 }`. The previous `?? '?'` fallback
@ -21,6 +23,7 @@ export interface GroupRepoIndexRow {
*/
export const formatIndexStatusCell = (row: GroupRepoIndexRow): string => {
if (!row.indexStale) return 'OK ';
if (row.status === 'diverged') return 'STALE (index differs from HEAD)';
const n = row.commitsBehind;
const count = typeof n === 'number' && n >= 0 ? String(n) : '?';
return `STALE (${count} commits behind)`;

6
gitnexus/src/cli/i18n/en.ts
View file

@ -137,7 +137,9 @@ export const en = {
'tool.detectChanges.noOverlappingSymbols':
'Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.',
'tool.detectChanges.partial':
'PARTIAL RESULT: a graph query failed, so changed symbols may be missing. Do not read this as a clean pre-commit check.',
'PARTIAL RESULT: changed-symbol or process mapping is incomplete. Do not read this as a clean pre-commit check.',
'tool.detectChanges.unmappedSource':
'No symbols mapped for changed source files: {{files}}. Rebuild the index and inspect the diff; retry alone may not resolve missing or out-of-range symbols.',
'tool.detectChanges.truncated':
'LISTING CAPPED: the changed-symbol list was capped, so it does not name every changed symbol. The counts and risk level still cover all of them.',
// The reassurance above is only true on its own. When the run also degraded,
@ -428,5 +430,5 @@ export const en = {
'help.identityCache.environment':
'\nAnalyzer identity cache:\n GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n Operator-trusted persistent cache for warm cross-process status. The directory must pre-exist, be outside the GitNexus package/build roots, and contain no symlink or junction components. Defaults remain fail-closed on platforms without POSIX ownership APIs.',
'help.analyze.environment':
'\nEnvironment variables:\n GITNEXUS_NO_GITIGNORE=1 Skip .gitignore parsing (still reads .gitnexusignore)\n GITNEXUS_MAX_FILE_SIZE=N Override large-file skip threshold (KB). Default 512, max 32768.\n GITNEXUS_STORAGE_PATH=/absolute/index Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n GITNEXUS_STORAGE_ROOT=/absolute/root External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n GITNEXUS_CONTENT_RETENTION=full Source-text retention profile: full, symbol, or none. Default full.\n GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N Worker idle timeout in milliseconds. Default 30000.\n GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N Worker job byte budget. Default 8388608.\n GITNEXUS_WORKER_POOL_SIZE=N Parse worker count override. Default cores-1 capped at 16.\n GITNEXUS_PARSE_CHUNK_CONCURRENCY=N Concurrent in-flight parse chunks. Default 2.\n GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N Max replacement spawns per slot before drop. Default 3.\n GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N Total retry wall-time per job. Default 5x sub-batch timeout.\n GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n GITNEXUS_CPP_CAPTURE_BUDGET_MS=N Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n GITNEXUS_EMBEDDING_THREADS=N Limit local ONNX CPU threads for --embeddings.\n GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1 Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\n GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N Max embedding chunks for exact-scan fallback. Default 10000.\n GITNEXUS_VECTOR_MAX_DISTANCE=N Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for MCP, 0.5 elsewhere.\n GITNEXUS_MAX_PROCESSES=N Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Distinct from query-time IMPACT_MAX_CHUNKS.\n GITNEXUS_MAX_PROCESS_BRANCHING=N Process-detection per-node branching cap. Default 4.\n GITNEXUS_MAX_PROCESS_TRACE_DEPTH=N Process-detection DFS depth cap. Default 10.\n GITNEXUS_MAX_ENTRY_POINT_CANDIDATES=N Ranked entry-point candidate pool. Default 200. Raise when the warning names this knob; doubling is the usual first raise.\n\nCLI flags take precedence over `.gitnexusrc`, which takes precedence over env vars, which take precedence over built-in defaults.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n `!__tests__/` to index a directory that is auto-filtered by default (#771).',
'\nEnvironment variables:\n GITNEXUS_NO_GITIGNORE=1 Skip .gitignore parsing (still reads .gitnexusignore)\n GITNEXUS_MAX_FILE_SIZE=N Override large-file skip threshold (KB). Default 512, max 32768.\n GITNEXUS_STORAGE_PATH=/absolute/index Complete external index directory. Preserves the existing configuration semantics and overrides GITNEXUS_STORAGE_ROOT when both are set.\n GITNEXUS_STORAGE_ROOT=/absolute/root External index root; each repository uses an isolated <repo-basename>-<canonical-path-hash>/ slot.\n GITNEXUS_CONTENT_RETENTION=full Source-text retention profile: full, symbol, or none. Default full.\n GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir Operator-trusted persistent analyzer identity cache; must pre-exist, be outside package/build roots, and contain no symlink/junction components.\n GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N Worker idle timeout in milliseconds. Default 30000.\n GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N LadybugDB WAL auto-checkpoint threshold in bytes (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB).\n GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N Worker job byte budget. Default 8388608.\n GITNEXUS_WORKER_POOL_SIZE=N Parse worker count override. Default cores-1 capped at 16.\n GITNEXUS_PARSE_CHUNK_CONCURRENCY=N Concurrent in-flight parse chunks. Default 2.\n GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N Max replacement spawns per slot before drop. Default 3.\n GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N Total retry wall-time per job. Default 5x sub-batch timeout.\n GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N Max wait at pool shutdown for a retired worker still inside native code (terminated at its next safe point instead of aborting the process). Default 30000.\n GITNEXUS_CPP_CAPTURE_BUDGET_MS=N Per-file wall-clock budget for C++ capture extraction; on breach the file keeps partial captures with a warning. Default 20000.\n GITNEXUS_EMBEDDING_THREADS=N Limit local ONNX CPU threads for --embeddings.\n GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1 Retry per-attempt HTTP embedding timeouts through GITNEXUS_EMBEDDING_MAX_ATTEMPTS (default off; timeouts stay terminal).\n GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N Max embedding chunks for exact-scan fallback. Default 10000.\n GITNEXUS_VECTOR_MAX_DISTANCE=N Max accepted semantic/vector cosine distance (0 < N <= 2; higher values clamp to 2). Default 0.6 for CLI/MCP query, 0.5 for standalone semantic search. Tune for your embedding model: higher values can improve recall but may reduce relevance. Set in the query/server environment; no reindex needed.\n GITNEXUS_MAX_PROCESSES=N Process-detection process cap (positive integer). Replaces the dynamic max(20, round(symbols/10)) formula. Distinct from query-time IMPACT_MAX_CHUNKS.\n GITNEXUS_MAX_PROCESS_BRANCHING=N Process-detection per-node branching cap. Default 4.\n GITNEXUS_MAX_PROCESS_TRACE_DEPTH=N Process-detection DFS depth cap. Default 10.\n GITNEXUS_MAX_ENTRY_POINT_CANDIDATES=N Ranked entry-point candidate pool. Default 200. Raise when the warning names this knob; doubling is the usual first raise.\n\nCLI flags take precedence over `.gitnexusrc`, which takes precedence over env vars, which take precedence over built-in defaults.\n\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n `!__tests__/` to index a directory that is auto-filtered by default (#771).',
} as const;

6
gitnexus/src/cli/i18n/zh-CN.ts
View file

@ -128,7 +128,9 @@ export const zhCN = {
'tool.detectChanges.noOverlappingSymbols':
'diff 触及 {{files}} 个文件，但没有索引符号与这些 hunk 重叠 — 并非干净工作区。',
'tool.detectChanges.partial':
'结果不完整：图查询失败，可能遗漏已变更符号。请勿将其视为通过的提交前检查。',
'结果不完整：变更符号或流程映射不完整。请勿将其视为通过的提交前检查。',
'tool.detectChanges.unmappedSource':
'变更源码文件未映射到符号：{{files}}。请重建索引并检查 diff；仅重试可能无法解决符号缺失或源码范围不匹配。',
'tool.detectChanges.truncated':
'列表已截断：已变更符号列表被截断，未列出全部变更符号。计数与风险等级仍涵盖全部符号。',
'tool.detectChanges.truncatedDegraded':
@ -390,5 +392,5 @@ export const zhCN = {
'help.identityCache.environment':
'\n分析器身份缓存：\n GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir\n 由操作员明确信任的持久缓存，用于跨进程快速查询状态。目录必须预先存在、位于 GitNexus 包/构建根目录之外，且路径中不得包含符号链接或 junction。缺少 POSIX 所有权 API 的平台默认保持故障关闭。',
'help.analyze.environment':
'\n环境变量：\n GITNEXUS_NO_GITIGNORE=1 跳过 .gitignore 解析（仍读取 .gitnexusignore）\n GITNEXUS_MAX_FILE_SIZE=N 覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n GITNEXUS_STORAGE_PATH=/absolute/index 完整外部索引目录。保留既有配置语义；与 GITNEXUS_STORAGE_ROOT 同时设置时优先使用。\n GITNEXUS_STORAGE_ROOT=/absolute/root 外部索引根目录；每个仓库使用独立的 <仓库名>-<规范路径哈希>/ 子目录。\n GITNEXUS_CONTENT_RETENTION=full 源码文本保留策略：full、symbol 或 none。默认 full。\n GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir 由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\n GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N Worker 空闲超时（毫秒）。默认 30000。\n GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N Worker 作业字节预算。默认 8388608。\n GITNEXUS_WORKER_POOL_SIZE=N 解析 worker 数量覆盖值。默认 cores-1，最多 16。\n GITNEXUS_PARSE_CHUNK_CONCURRENCY=N 并发进行中的解析分块数。默认 2。\n GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N 每个 slot 丢弃前允许的最大替换进程数。默认 3。\n GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N 每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N 每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N 线程池关闭时等待仍在原生代码中的已退役 worker 的最长时间（到达安全点后再终止，避免进程级 abort）。默认 30000。\n GITNEXUS_CPP_CAPTURE_BUDGET_MS=N C++ 捕获提取的每文件墙钟预算；超出后该文件保留部分捕获并输出警告。默认 20000。\n GITNEXUS_EMBEDDING_THREADS=N 限制 --embeddings 的本地 ONNX CPU 线程数。\n GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1 将单次 HTTP 嵌入超时纳入 GITNEXUS_EMBEDDING_MAX_ATTEMPTS 重试（默认关闭，超时仍为终止错误）。\n GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N exact-scan 回退的最大嵌入分块数。默认 10000。\n GITNEXUS_VECTOR_MAX_DISTANCE=N 语义/向量搜索接受的最大余弦距离（0 < N <= 2；超出则钳制为 2）。MCP 默认 0.6，其他路径默认 0.5。\n GITNEXUS_MAX_PROCESSES=N 流程检测的流程数量上限（正整数）。覆盖动态的 max(20, round(symbols/10)) 公式。与查询时的 IMPACT_MAX_CHUNKS 无关。\n GITNEXUS_MAX_PROCESS_BRANCHING=N 流程检测的单节点分支上限。默认 4。\n GITNEXUS_MAX_PROCESS_TRACE_DEPTH=N 流程检测的 DFS 深度上限。默认 10。\n GITNEXUS_MAX_ENTRY_POINT_CANDIDATES=N 排序后的入口点候选池。默认 200。仅在警告点名该上限时提高；那时通常先翻倍。\n\nCLI 参数优先于 `.gitnexusrc`，后者优先于环境变量，环境变量优先于内置默认值。\n\n提示：`.gitnexusignore` 支持 `.gitignore` 风格的取反。比如添加\n `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
'\n环境变量：\n GITNEXUS_NO_GITIGNORE=1 跳过 .gitignore 解析（仍读取 .gitnexusignore）\n GITNEXUS_MAX_FILE_SIZE=N 覆盖大文件跳过阈值（KB）。默认 512，最大 32768。\n GITNEXUS_STORAGE_PATH=/absolute/index 完整外部索引目录。保留既有配置语义；与 GITNEXUS_STORAGE_ROOT 同时设置时优先使用。\n GITNEXUS_STORAGE_ROOT=/absolute/root 外部索引根目录；每个仓库使用独立的 <仓库名>-<规范路径哈希>/ 子目录。\n GITNEXUS_CONTENT_RETENTION=full 源码文本保留策略：full、symbol 或 none。默认 full。\n GITNEXUS_ANALYZER_IDENTITY_CACHE_DIR=/absolute/protected/dir 由操作员明确信任的持久分析器身份缓存；目录必须预先存在、位于包/构建根目录之外，且路径中不得包含符号链接或 junction。\n GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N Worker 空闲超时（毫秒）。默认 30000。\n GITNEXUS_WAL_CHECKPOINT_THRESHOLD=N LadybugDB WAL 自动 checkpoint 阈值（字节，默认 67108864 = 64 MiB；-1 保持 Ladybug 默认约 16 MiB）。\n GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N Worker 作业字节预算。默认 8388608。\n GITNEXUS_WORKER_POOL_SIZE=N 解析 worker 数量覆盖值。默认 cores-1，最多 16。\n GITNEXUS_PARSE_CHUNK_CONCURRENCY=N 并发进行中的解析分块数。默认 2。\n GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N 每个 slot 丢弃前允许的最大替换进程数。默认 3。\n GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N 每个作业的总重试墙钟时间。默认 5 倍子批次超时。\n GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N 每个 slot 触发熔断的死亡次数。默认 max(3, poolSize)。\n GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS=N 线程池关闭时等待仍在原生代码中的已退役 worker 的最长时间（到达安全点后再终止，避免进程级 abort）。默认 30000。\n GITNEXUS_CPP_CAPTURE_BUDGET_MS=N C++ 捕获提取的每文件墙钟预算；超出后该文件保留部分捕获并输出警告。默认 20000。\n GITNEXUS_EMBEDDING_THREADS=N 限制 --embeddings 的本地 ONNX CPU 线程数。\n GITNEXUS_EMBEDDING_RETRY_TIMEOUTS=1 将单次 HTTP 嵌入超时纳入 GITNEXUS_EMBEDDING_MAX_ATTEMPTS 重试（默认关闭，超时仍为终止错误）。\n GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N exact-scan 回退的最大嵌入分块数。默认 10000。\n GITNEXUS_VECTOR_MAX_DISTANCE=N 语义/向量搜索接受的最大余弦距离（0 < N <= 2；超出则钳制为 2）。CLI/MCP query 默认 0.6，独立语义搜索默认 0.5。应根据嵌入模型调节：提高阈值可增加召回，但可能降低相关性。在查询/服务器进程的环境中设置，无需重新索引。\n GITNEXUS_MAX_PROCESSES=N 流程检测的流程数量上限（正整数）。覆盖动态的 max(20, round(symbols/10)) 公式。与查询时的 IMPACT_MAX_CHUNKS 无关。\n GITNEXUS_MAX_PROCESS_BRANCHING=N 流程检测的单节点分支上限。默认 4。\n GITNEXUS_MAX_PROCESS_TRACE_DEPTH=N 流程检测的 DFS 深度上限。默认 10。\n GITNEXUS_MAX_ENTRY_POINT_CANDIDATES=N 排序后的入口点候选池。默认 200。仅在警告点名该上限时提高；那时通常先翻倍。\n\nCLI 参数优先于 `.gitnexusrc`，后者优先于环境变量，环境变量优先于内置默认值。\n\n提示：`.gitnexusignore` 支持 `.gitignore` 风格的取反。比如添加\n `!__tests__/` 可以索引默认自动过滤的目录（#771）。',
} satisfies EnglishMessages;

39
gitnexus/src/cli/skill-gen.ts
View file

@ -114,21 +114,21 @@ export const generateSkillFiles = async (
}
}
if (!communityResult || !communityResult.memberships.length) {
const memberships = communityResult?.rawMemberships ?? communityResult?.memberships ?? [];
if (!communityResult || !memberships.length) {
console.log('\n Skills: no communities detected, skipping skill generation');
return { skills: [], outputPath: outputDir };
}
console.log('\n Generating repo-specific skills...');
// Step 1: Build communities from memberships (not the filtered communities array).
// The community processor skips singletons from its communities array but memberships
// include ALL assignments. For repos with sparse CALLS edges, the communities array
// can be empty while memberships still has useful groupings.
// Step 1: Use raw assignments for the fallback when all communities were
// filtered as singletons. Same-folder aggregation can still produce skills
// for these sparse graphs without emitting dangling MEMBER_OF edges.
const communities =
communityResult.communities.length > 0
? communityResult.communities
: buildCommunitiesFromMemberships(communityResult.memberships, graph, repoPath);
: buildCommunitiesFromMemberships(memberships, graph, repoPath);
const aggregated = aggregateCommunities(communities);
@ -145,11 +145,8 @@ export const generateSkillFiles = async (
}
// Step 3: Build lookup maps
const membershipsByComm = buildMembershipMap(communityResult.memberships);
const nodeIdToCommunityLabel = buildNodeCommunityLabelMap(
communityResult.memberships,
communities,
);
const membershipsByComm = buildMembershipMap(memberships);
const nodeIdToCommunityLabel = buildNodeCommunityLabelMap(memberships, communities);
// Step 4: Ensure the shared project-skill root exists. Never clear it: it
// also contains user-authored and standard GitNexus skills.
@ -185,7 +182,7 @@ export const generateSkillFiles = async (
const entryPoints = gatherEntryPoints(members);
// Gather execution flows
const flows = gatherFlows(community.rawIds, processResult?.processes || []);
const flows = gatherFlows(community.rawIds, members, processResult?.processes || []);
// Gather cross-community connections
const connections = gatherCrossConnections(
@ -529,14 +526,26 @@ const gatherEntryPoints = (members: MemberSymbol[]): MemberSymbol[] => {
/**
* @brief Gather execution flows touching this community
* @param {string[]} rawIds - Raw community IDs for this aggregated community
* @param {MemberSymbol[]} members - Member symbols, including raw singleton assignments
* @param {ProcessNode[]} processes - All detected processes
* @returns {ProcessNode[]} Processes whose communities intersect rawIds, sorted by stepCount
* @returns {ProcessNode[]} Processes matching the community IDs or member symbols, sorted by stepCount
*/
const gatherFlows = (rawIds: string[], processes: ProcessNode[]): ProcessNode[] => {
const gatherFlows = (
rawIds: string[],
members: MemberSymbol[],
processes: ProcessNode[],
): ProcessNode[] => {
const rawIdSet = new Set(rawIds);
const memberIds = new Set(members.map((member) => member.id));
return processes
.filter((proc) => proc.communities.some((cid) => rawIdSet.has(cid)))
.filter(
(proc) =>
proc.communities.some((cid) => rawIdSet.has(cid)) ||
// Filtered singleton communities are absent from process metadata,
// but their symbols still participate in detected execution traces.
proc.trace.some((nodeId) => memberIds.has(nodeId)),
)
.sort((a, b) => b.stepCount - a.stepCount);
};

4
gitnexus/src/cli/status.ts
View file

@ -48,6 +48,7 @@ import {
isFullSourceAvailable,
} from '../core/content-retention.js';
import { t } from './i18n/index.js';
import { formatPathForTerminal as formatDriftPath } from './format-path.js';
/** How many drifted paths the report names before summarizing the rest. */
const DRIFT_SAMPLE_LIMIT = 10;
@ -84,9 +85,6 @@ const describeContentDrift = (drift: IndexContentDrift | undefined) => {
};
};
/** Escape control characters in repo-relative paths before printing. */
const formatDriftPath = (rel: string): string =>
/[\u0000-\u001f\u007f]/.test(rel) ? JSON.stringify(rel) : rel;
const printDriftDetail = (drift: Extract<IndexContentDrift, { kind: 'drifted' }>): void => {
console.log(
t('status.indexContentDrifted', {

204
gitnexus/src/config/ignore-service.ts
View file

@ -1,5 +1,13 @@
import ignore, { type Ignore } from 'ignore';
import { existsSync } from 'fs';
import {
closeSync,
constants as fsConstants,
existsSync,
fstatSync,
lstatSync,
openSync,
readFileSync,
} from 'fs';
import fs from 'fs/promises';
import nodePath from 'path';
import type { Path } from 'path-scurry';
@ -531,9 +539,163 @@ const hasExplicitUnignore = (ig: Ignore, rel: string): boolean => {
return false;
};
/**
* Read a nested `.gitignore` only if it is a regular file, not a symlink.
*
* git does not follow a symlinked `.gitignore` in the working tree, and
* reading one could pull rules from outside the repository. Where the
* platform supports it, the file is opened with O_NOFOLLOW (a symlink fails
* with ELOOP). Windows has no O_NOFOLLOW, so there the path is lstat'ed after
* opening and must be the same regular file as the open descriptor. Either
* way the content is read through the descriptor that was checked, never by
* path, so the file cannot be swapped between the check and the read.
*
* The open also passes O_NONBLOCK where it exists. Opening a FIFO for reading
* blocks in open(2) until a writer appears, so a `.gitignore` that is a FIFO
* would hang the scan before the isFile() check could reject it (glob's
* ignore callback is synchronous). The flag makes that open return at once
* and changes nothing for a regular file. Same reasoning as readBoundedFile
* in src/core/ingestion/asyncapi/document.ts.
*/
const readNestedGitignore = (filePath: string): string | null => {
const noFollow = fsConstants.O_NOFOLLOW;
const nonBlock = fsConstants.O_NONBLOCK;
const fd = openSync(filePath, fsConstants.O_RDONLY | (noFollow ?? 0) | (nonBlock ?? 0));
try {
const stat = fstatSync(fd);
if (!stat.isFile()) return null;
if (noFollow === undefined) {
const link = lstatSync(filePath);
if (!link.isFile() || link.ino !== stat.ino || link.dev !== stat.dev) return null;
}
return readFileSync(fd, 'utf-8');
} finally {
closeSync(fd);
}
};
/**
* Resolve `.gitignore` files below the repository root (#2675).
*
* `loadIgnoreRules` only reads the root `.gitignore`, so a monorepo package
* or checked-out submodule with its own `.gitignore` had its generated
* output indexed anyway. Each nested file is read lazily (glob's filter is
* synchronous) and cached per directory, and its patterns are matched
* against the path relative to that directory, like git does.
*
* Returns the effective decision when nested rules affect the path or an
* ancestor, and `undefined` otherwise. Root rules participate so a directory
* negation does not erase independent root exclusions for its children.
* The caller still gives `.gitnexusignore` its higher precedence.
*/
const createNestedGitignoreMatcher = (
repoPath: string,
rootRules: Ignore | null,
): ((rel: string, isDirectory: boolean) => boolean | undefined) => {
const rulesFor = (dirRel: string): Ignore | null => {
let rules: Ignore | null = null;
const filePath = nodePath.join(repoPath, dirRel, '.gitignore');
try {
const content = readNestedGitignore(filePath);
if (content !== null) rules = ignore().add(content);
} catch (err: unknown) {
const code = (err as NodeJS.ErrnoException).code;
if (code !== 'ENOENT' && code !== 'ENOTDIR' && code !== 'ELOOP') {
logger.warn(` Warning: could not read ${filePath}: ${(err as Error).message}`);
}
}
return rules;
};
interface Scope {
base: string;
rules: Ignore;
}
interface DirectoryContext {
scopes: Scope[];
ignored: boolean;
nested: boolean;
}
const relativeTo = (base: string, rel: string): string =>
base ? rel.slice(base.length + 1) : rel;
const match = (scopes: Scope[], rel: string, isDirectory: boolean) => {
for (let i = scopes.length - 1; i >= 0; i--) {
const { base, rules } = scopes[i];
const sub = relativeTo(base, rel);
const result = rules.test(isDirectory ? `${sub}/` : sub);
if (result.ignored || result.unignored) {
return { ignored: result.ignored, nested: base !== '' };
}
}
return undefined;
};
const contexts = new Map<string, DirectoryContext>([
[
'',
{
scopes: rootRules ? [{ base: '', rules: rootRules }] : [],
ignored: false,
nested: false,
},
],
]);
const contextFor = (dir: string): DirectoryContext => {
const cached = contexts.get(dir);
if (cached) return cached;
const parentDir = nodePath.posix.dirname(dir);
const parent = contextFor(parentDir === '.' ? '' : parentDir);
// A .gitignore inside an excluded directory cannot bring that directory
// back. Do not read rules below a parent that traversal would prune.
if (parent.ignored) {
contexts.set(dir, parent);
return parent;
}
const result = match(parent.scopes, dir, true);
const context: DirectoryContext = {
scopes: parent.scopes,
ignored: result?.ignored ?? false,
nested: parent.nested || (result?.nested ?? false),
};
if (!context.ignored) {
context.scopes = parent.scopes.map(({ base, rules }) => {
const sub = relativeTo(base, dir);
if (!rules.test(`${sub}/`).ignored) return { base, rules };
// A deeper rule let us enter this directory. Clear only its inherited
// exclusion in the shallower layer; child rules must still be tested.
// Keep patterns in their original scope, and escape this literal path.
const literal = sub.replace(/[\\*?\[\]]/g, '\\$&');
return {
base,
rules: ignore()
.add(rules)
.add({ pattern: `!/${literal}/` }),
};
});
const rules = rulesFor(dir);
if (rules) context.scopes.push({ base: dir, rules });
}
contexts.set(dir, context);
return context;
};
return (rel: string, isDirectory: boolean): boolean | undefined => {
const parentDir = nodePath.posix.dirname(rel);
const parent = contextFor(parentDir === '.' ? '' : parentDir);
if (parent.ignored) return parent.nested ? true : undefined;
const result = match(parent.scopes, rel, isDirectory);
if (parent.nested || result?.nested) return result?.ignored ?? false;
return undefined;
};
};
/**
* Create a glob-compatible ignore filter combining:
* - .gitignore / .gitnexusignore patterns (via `ignore` package)
* - nested .gitignore files, scoped to their own directory (#2675)
* - Hardcoded DEFAULT_IGNORE_LIST, IGNORED_EXTENSIONS, IGNORED_FILES
*
* Returns an IgnoreLike object for glob's `ignore` option,
@ -550,6 +712,13 @@ const hasExplicitUnignore = (ig: Ignore, rel: string): boolean => {
*/
export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptions) => {
const ig = await loadIgnoreRules(repoPath, options);
const skipGitignore = options?.noGitignore ?? !!process.env.GITNEXUS_NO_GITIGNORE;
const nestedIgnores = skipGitignore ? null : createNestedGitignoreMatcher(repoPath, ig);
// A nested negation outranks the root .gitignore, as in git, but not the
// user's .gitnexusignore, so keep a matcher for that file on its own.
const nexusIgnore = nestedIgnores
? await loadIgnoreRules(repoPath, { ...options, noGitignore: true, noGlobalIgnore: true })
: null;
return {
ignored(p: Path): boolean {
@ -557,6 +726,23 @@ export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptio
// native separators on Windows when called through glob.
const rel = p.relative().replace(/\\/g, '/');
if (!rel) return false;
// Nested .gitignore files below the root (#2675). .gitnexusignore
// comes first, then the deepest nested .gitignore, which outranks the
// root .gitignore as in git. The nested matcher preserves independent
// root exclusions; a nested negation never rescues a hardcoded default.
// With no nested opinion the original order below applies unchanged.
if (nestedIgnores) {
if (nexusIgnore) {
if (hasExplicitUnignore(nexusIgnore, rel) && !ig?.ignores(rel)) return false;
if (nexusIgnore.ignores(rel)) return true;
}
const nested = nestedIgnores(rel, false);
if (nested === true) return true;
if (nested === false) {
if (ig && hasExplicitUnignore(ig, rel) && !ig.ignores(rel)) return false;
return shouldIgnorePath(rel);
}
}
// User's .gitnexusignore negation takes precedence over hardcoded
// rules (#771). If any ancestor or the path itself was explicitly
// unignored AND no more-specific rule re-ignores this exact path,
@ -576,6 +762,22 @@ export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptio
// list check below is defense-in-depth — do not remove `dot: false`
// assuming this covers it.
const rel = p.relative().replace(/\\/g, '/');
// Nested .gitignore files below the root (#2675), same precedence as in
// `ignored` above.
if (nestedIgnores && rel) {
if (nexusIgnore) {
if (hasExplicitUnignore(nexusIgnore, rel) && !ig?.ignores(rel + '/')) {
return false;
}
if (nexusIgnore.ignores(rel + '/')) return true;
}
const nested = nestedIgnores(rel, true);
if (nested === true) return true;
if (nested === false) {
if (ig && hasExplicitUnignore(ig, rel) && !ig.ignores(rel + '/')) return false;
return isHardcodedIgnoredDirectoryAtPath(repoPath, nodePath.join(repoPath, rel));
}
}
// User's .gitnexusignore negation takes precedence (#771) — if the
// user explicitly unignored this directory or any ancestor via a
// !pattern rule, allow descent even if the directory name is in

181
gitnexus/src/core/embeddings/staged-embedding-recovery-child.ts Normal file
View file

@ -0,0 +1,181 @@
/** Isolated strict native reader. Never import this entrypoint into analyze. */
import fs from 'node:fs';
import path from 'node:path';
import lbug from '@ladybugdb/core';
import { createLbugDatabase, toNativeSafePath } from '../lbug/lbug-config.js';
import { FAMILY_SUFFIXES } from '../../storage/embedding-recovery.js';
import {
abortCachedEmbeddingsBuilder,
createCachedEmbeddingsBuilder,
finalizeCachedEmbeddingsSnapshot,
ingestCachedEmbeddingRow,
} from './embedding-restore-spill.js';
import type { StagedEmbeddingExport } from './staged-embedding-recovery.js';
/** Native replay and close may checkpoint; only give them disposable copies. */
function copyRecoveryFamily(dbPath: string, exportDir: string): string {
const replayDir = fs.mkdtempSync(path.join(exportDir, 'replay-'));
const replayPath = path.join(replayDir, path.basename(dbPath));
const noFollow = fs.constants.O_NOFOLLOW ?? 0;
const flags = fs.constants.O_RDONLY | noFollow | (fs.constants.O_NONBLOCK ?? 0);
const buffer = Buffer.allocUnsafe(1024 * 1024);
for (const suffix of FAMILY_SUFFIXES) {
const sourcePath = dbPath + suffix;
let entry: fs.BigIntStats;
try {
entry = fs.lstatSync(sourcePath, { bigint: true });
} catch (error) {
if (suffix && (error as NodeJS.ErrnoException).code === 'ENOENT') continue;
throw error;
}
if (!entry.isFile()) throw new Error('staged embedding family is not a regular file');
const source = fs.openSync(sourcePath, flags);
let destination: number | undefined;
try {
const opened = fs.fstatSync(source, { bigint: true });
const current = fs.lstatSync(sourcePath, { bigint: true });
if (
!opened.isFile() ||
!current.isFile() ||
(noFollow === 0 && opened.ino === 0n) ||
opened.dev !== entry.dev ||
opened.ino !== entry.ino ||
opened.dev !== current.dev ||
opened.ino !== current.ino
) {
throw new Error('staged embedding family changed while opening');
}
destination = fs.openSync(replayPath + suffix, 'wx', 0o600);
let copied = 0n;
for (;;) {
const bytesRead = fs.readSync(source, buffer, 0, buffer.length, null);
if (bytesRead === 0) break;
fs.writeFileSync(destination, buffer.subarray(0, bytesRead));
copied += BigInt(bytesRead);
}
const after = fs.fstatSync(source, { bigint: true });
if (
copied !== opened.size ||
after.size !== opened.size ||
after.mtimeNs !== opened.mtimeNs ||
after.ctimeNs !== opened.ctimeNs
) {
throw new Error('staged embedding family changed while copying');
}
} finally {
try {
if (destination !== undefined) fs.closeSync(destination);
} finally {
fs.closeSync(source);
}
}
}
return replayPath;
}
async function extract(): Promise<void> {
const [dbPath, exportDir, dimensionsArg] = process.argv.slice(2);
const dimensions = Number(dimensionsArg);
if (!dbPath || !exportDir || !Number.isInteger(dimensions) || dimensions <= 0) {
throw new Error('invalid staged embedding extraction arguments');
}
// The parent owns exportDir and reclaims it even after killing this child.
const replayPath = copyRecoveryFamily(dbPath, exportDir);
const builder = createCachedEmbeddingsBuilder({ inMemoryRowLimit: 0, spillDir: exportDir });
const rejectedNodeIds = new Set<string>();
let db: lbug.Database | undefined;
let conn: lbug.Connection | undefined;
try {
// Avoid openLbugConnection's test-fixture lock sweep: a recovery source must
// never have its WAL removed, even when an external slot resembles a fixture.
db = createLbugDatabase(lbug, toNativeSafePath(replayPath), { throwOnWalReplayFailure: true });
conn = new lbug.Connection(db);
const queried = await conn.query(
'MATCH (e:CodeEmbedding) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding, e.contentHash AS contentHash',
);
const results = Array.isArray(queried) ? queried : [queried];
try {
if (results.length !== 1) throw new Error('unexpected staged embedding query result');
const result = results[0];
while (await result.hasNext()) {
const raw = await result.getNext();
const rec = raw as Record<string, unknown> & unknown[];
const nodeId = rec.nodeId ?? rec[0];
if (typeof nodeId !== 'string' || !nodeId)
throw new Error('invalid staged embedding node id');
const chunkIndex = rec.chunkIndex ?? rec[1];
const startLine = rec.startLine ?? rec[2];
const endLine = rec.endLine ?? rec[3];
const embedding = rec.embedding ?? rec[4];
const contentHash = rec.contentHash ?? rec[5];
const vector =
Array.isArray(embedding) ||
(ArrayBuffer.isView(embedding) && !(embedding instanceof DataView))
? Array.from(embedding as ArrayLike<number>)
: undefined;
if (
!Number.isInteger(chunkIndex) ||
Number(chunkIndex) < 0 ||
!Number.isInteger(startLine) ||
Number(startLine) < 0 ||
!Number.isInteger(endLine) ||
Number(endLine) < Number(startLine) ||
typeof contentHash !== 'string' ||
!contentHash ||
!vector ||
vector.length !== dimensions ||
vector.some(
(value) =>
typeof value !== 'number' ||
!Number.isFinite(value) ||
!Number.isFinite(Math.fround(value)),
)
) {
rejectedNodeIds.add(nodeId);
continue;
}
ingestCachedEmbeddingRow(
builder,
{ nodeId, chunkIndex, startLine, endLine, embedding: vector, contentHash },
true,
);
}
} finally {
for (const result of results) await result.close();
}
// Both closes must succeed. Suppressed native teardown errors are unsafe.
await conn.close();
await db.close();
const snapshot = finalizeCachedEmbeddingsSnapshot(builder);
if (snapshot.spill) fs.renameSync(snapshot.spill.path, path.join(exportDir, 'vectors.bin'));
const manifest: StagedEmbeddingExport = {
version: 1,
dimensions,
rows: snapshot.rows,
rejectedNodeIds: [...rejectedNodeIds],
};
fs.writeFileSync(path.join(exportDir, 'manifest.json'), JSON.stringify(manifest), {
flag: 'wx',
mode: 0o600,
});
} catch (err) {
abortCachedEmbeddingsBuilder(builder);
// Cleanup is best effort on a rejected source, never used to approve output.
try {
await conn?.close();
} catch {
/* rejected */
}
try {
await db?.close();
} catch {
/* rejected */
}
throw err;
}
}
extract().catch((err: unknown) => {
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
process.exitCode = 1;
});

244
gitnexus/src/core/embeddings/staged-embedding-recovery.ts Normal file
View file

@ -0,0 +1,244 @@
/** Recover paid embedding rows without opening an interrupted native DB in analyze. */
import { spawn } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import {
abortCachedEmbeddingsBuilder,
createCachedEmbeddingsBuilder,
EmbeddingSpillReader,
emptyCachedEmbeddingsSnapshot,
finalizeCachedEmbeddingsSnapshot,
ingestCachedEmbeddingRow,
materializeCachedEmbeddings,
type CachedEmbeddingMeta,
type CachedEmbeddingsSnapshot,
} from './embedding-restore-spill.js';
export interface StagedEmbeddingRecoveryOptions {
dimensions: number;
/** Active checkpoint window and any incomplete inherited restore groups. */
excludedNodeIds?: Iterable<string>;
timeoutMs?: number;
}
export interface StagedEmbeddingExport {
version: 1;
dimensions: number;
rows: CachedEmbeddingMeta[];
rejectedNodeIds: string[];
}
const RESTORE_BATCH_SIZE = 200;
const DEFAULT_EXTRACTION_TIMEOUT_MS = 120_000;
/** A contiguous prefix is safe only when its node is outside every unsafe window. */
export function validateRecoveredNodeGroups(
rows: readonly CachedEmbeddingMeta[],
excludedNodeIds: ReadonlySet<string> = new Set(),
): Set<string> {
const groups = new Map<string, { hash: string; ordinals: Set<number>; invalid: boolean }>();
for (const row of rows) {
let group = groups.get(row.nodeId);
if (!group) {
group = { hash: row.contentHash, ordinals: new Set(), invalid: false };
groups.set(row.nodeId, group);
}
if (
typeof row.nodeId !== 'string' ||
!row.nodeId ||
typeof row.contentHash !== 'string' ||
!row.contentHash ||
row.contentHash !== group.hash ||
!Number.isInteger(row.chunkIndex) ||
row.chunkIndex < 0 ||
group.ordinals.has(row.chunkIndex) ||
!Number.isInteger(row.startLine) ||
row.startLine < 0 ||
!Number.isInteger(row.endLine) ||
row.endLine < row.startLine
)
group.invalid = true;
group.ordinals.add(row.chunkIndex);
}
const accepted = new Set<string>();
for (const [nodeId, group] of groups) {
if (group.invalid || excludedNodeIds.has(nodeId)) continue;
// Unique ordinals with max n-1 and zero present have no holes.
if (!group.ordinals.has(0)) continue;
if ([...group.ordinals].some((ordinal) => ordinal >= group.ordinals.size)) continue;
accepted.add(nodeId);
}
return accepted;
}
/** Whole recovered nodes replace whole published groups; vectors stay in bounded batches. */
export function mergeRecoveredEmbeddings(
live: CachedEmbeddingsSnapshot,
recovered: CachedEmbeddingsSnapshot,
): CachedEmbeddingsSnapshot {
const builder = createCachedEmbeddingsBuilder({ inMemoryRowLimit: 0 });
try {
appendSnapshotRows(
live,
live.rows.filter((row) => !recovered.embeddingNodeIds.has(row.nodeId)),
builder,
);
appendSnapshotRows(recovered, recovered.rows, builder);
return finalizeCachedEmbeddingsSnapshot(builder);
} catch (err) {
abortCachedEmbeddingsBuilder(builder);
throw err;
}
}
function appendSnapshotRows(
snapshot: CachedEmbeddingsSnapshot,
rows: readonly CachedEmbeddingMeta[],
builder: ReturnType<typeof createCachedEmbeddingsBuilder>,
): void {
const reader = snapshot.spill ? new EmbeddingSpillReader(snapshot.spill) : undefined;
try {
for (let i = 0; i < rows.length; i += RESTORE_BATCH_SIZE) {
const batch = materializeCachedEmbeddings(
snapshot,
rows.slice(i, i + RESTORE_BATCH_SIZE),
reader,
);
for (const row of batch)
ingestCachedEmbeddingRow(builder, row as unknown as Record<string, unknown>, true);
}
} finally {
reader?.close();
}
}
/**
* Caller must validate checkpoint identity, schema, exact generation, and hold the
* index lock. A subprocess contains native WAL replay/query/destructor failures.
* A failed strict open is never retried with WAL removed or validation disabled.
*/
export async function recoverStagedEmbeddings(
dbPath: string,
options: StagedEmbeddingRecoveryOptions,
): Promise<CachedEmbeddingsSnapshot> {
if (!Number.isInteger(options.dimensions) || options.dimensions <= 0) {
throw new Error('invalid staged embedding dimensions');
}
const dbStat = fs.lstatSync(dbPath);
if (!dbStat.isFile() || dbStat.isSymbolicLink())
throw new Error('staged embedding DB is not a regular file');
const exportDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-stage-export-'));
try {
await runExtractionChild(dbPath, exportDir, options);
const manifestPath = path.join(exportDir, 'manifest.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as StagedEmbeddingExport;
if (
manifest.version !== 1 ||
manifest.dimensions !== options.dimensions ||
!Array.isArray(manifest.rows) ||
!Array.isArray(manifest.rejectedNodeIds) ||
manifest.rejectedNodeIds.some((id) => typeof id !== 'string') ||
manifest.rows.some((row, i) => !row || row.vectorIndex !== i)
)
throw new Error('invalid staged embedding export manifest');
if (manifest.rows.length === 0) return emptyCachedEmbeddingsSnapshot();
const spill = {
path: path.join(exportDir, 'vectors.bin'),
dims: options.dimensions,
rowCount: manifest.rows.length,
};
const vectorStat = fs.lstatSync(spill.path);
if (
!vectorStat.isFile() ||
vectorStat.isSymbolicLink() ||
vectorStat.size !== 12 + spill.rowCount * spill.dims * 4
) {
throw new Error('invalid staged embedding export size');
}
const excluded = new Set(options.excludedNodeIds ?? []);
for (const nodeId of manifest.rejectedNodeIds) excluded.add(nodeId);
const accepted = validateRecoveredNodeGroups(manifest.rows, excluded);
const exported: CachedEmbeddingsSnapshot = {
rows: manifest.rows,
embeddings: [],
embeddingNodeIds: accepted,
spill,
};
const builder = createCachedEmbeddingsBuilder({ inMemoryRowLimit: 0 });
const reader = new EmbeddingSpillReader(spill);
try {
const rows = manifest.rows.filter((row) => accepted.has(row.nodeId));
for (let i = 0; i < rows.length; i += RESTORE_BATCH_SIZE) {
for (const row of materializeCachedEmbeddings(
exported,
rows.slice(i, i + RESTORE_BATCH_SIZE),
reader,
)) {
if (
row.embedding.length !== options.dimensions ||
row.embedding.some((value) => !Number.isFinite(value))
) {
throw new Error('invalid staged embedding vector');
}
ingestCachedEmbeddingRow(builder, row as unknown as Record<string, unknown>, true);
}
}
return finalizeCachedEmbeddingsSnapshot(builder);
} catch (err) {
abortCachedEmbeddingsBuilder(builder);
throw err;
} finally {
reader.close();
}
} finally {
fs.rmSync(exportDir, { recursive: true, force: true });
}
}
function runExtractionChild(
dbPath: string,
exportDir: string,
options: StagedEmbeddingRecoveryOptions,
): Promise<void> {
const compiledPath = fileURLToPath(
new URL('./staged-embedding-recovery-child.js', import.meta.url),
);
const sourcePath = compiledPath.replace(/\.js$/, '.ts');
const childPath = fs.existsSync(compiledPath) ? compiledPath : sourcePath;
const args = childPath.endsWith('.ts')
? ['--import', import.meta.resolve('tsx'), childPath]
: [childPath];
args.push(dbPath, exportDir, String(options.dimensions));
return new Promise((resolve, reject) => {
const child = spawn(process.execPath, args, {
stdio: ['ignore', 'ignore', 'pipe'],
windowsHide: true,
});
let stderr = '';
let timedOut = false;
child.stderr.on('data', (chunk: Buffer) => {
if (stderr.length < 4096) stderr += chunk.toString().slice(0, 4096 - stderr.length);
});
const timer = setTimeout(() => {
timedOut = true;
// A process boundary is safe to kill even while native code is executing.
child.kill('SIGKILL');
}, options.timeoutMs ?? DEFAULT_EXTRACTION_TIMEOUT_MS);
child.once('error', (err) => {
clearTimeout(timer);
reject(err);
});
child.once('close', (code, signal) => {
clearTimeout(timer);
if (code === 0 && !signal && !timedOut) resolve();
else
reject(
new Error(
`staged embedding extraction failed${timedOut ? ' (timeout)' : ` (${signal ?? code})`}${stderr ? `: ${stderr.trim()}` : ''}`,
),
);
});
});
}

94
gitnexus/src/core/git-staleness.ts
View file

@ -17,8 +17,8 @@ export type { StalenessInfo, StalenessStatus } from './staleness-status.js';
const execFileAsync = promisify(execFile);
/**
* Ceiling for one `git rev-list` staleness probe. Generous for the local
* history walk this is, and short enough that an unresponsive working tree
* Per-command ceiling for async `git rev-list` and both HEAD probes.
* Generous for local Git queries, and short enough that an unresponsive working tree
* degrades to "not stale" quickly rather than holding a request open.
*/
const STALENESS_TIMEOUT_MS = 5_000;
@ -33,12 +33,23 @@ const behindHint = (n: number): string =>
const DIVERGED_HINT =
"⚠️ Index is not at HEAD and the commit gap could not be counted — the recorded commit may no longer be in this clone's history. Run analyze tool to update.";
// `rev-list --count lastCommit..HEAD` answering 0 does NOT mean "HEAD is the
// indexed commit" — it means "HEAD has no commits lastCommit lacks", which is
// also true when HEAD is an *ancestor* of lastCommit (the working tree checked
// out an older commit than the one indexed, or switched to a line of history
// behind it). That read a rollback as `current` until this hint existed.
const REGRESSED_HINT =
'⚠️ Index is not at HEAD — the indexed commit is not reachable from the checked-out commit (the working tree may have checked out an older commit, or a different line of history). Run analyze tool to update.';
const unknown = (): StalenessInfo => ({ isStale: false, commitsBehind: 0, status: 'unknown' });
const fromCount = (commitsBehind: number): StalenessInfo =>
commitsBehind > 0
? { isStale: true, commitsBehind, hint: behindHint(commitsBehind), status: 'behind' }
: { isStale: false, commitsBehind: 0, status: 'current' };
// Called only once a positive HEAD-only count is in hand.
const behind = (commitsBehind: number): StalenessInfo => ({
isStale: true,
commitsBehind,
hint: behindHint(commitsBehind),
status: 'behind',
});
/**
* `rev-list` could not answer. Asking for HEAD alone needs no history walk and
@ -53,6 +64,26 @@ const fromHead = (head: string | null, lastCommit: string): StalenessInfo => {
return { isStale: false, commitsBehind: 0, hint: DIVERGED_HINT, status: 'diverged' };
};
/**
* `rev-list --left-right --count lastCommit...HEAD` measures both sides in
* one process, so a later HEAD change cannot mix two snapshots. The left
* count identifies a rollback even when the HEAD-only (right) count is 0.
* Positive right counts keep the existing `behind` behavior, including when
* both sides have commits (divergent branches or a re-shallowed clone).
*/
const fromCounts = (output: string): StalenessInfo => {
const counts = /^(\d+)\s+(\d+)$/.exec(output.trim());
if (!counts) return unknown();
const indexedOnly = Number(counts[1]);
const headOnly = Number(counts[2]);
if (!Number.isSafeInteger(indexedOnly) || !Number.isSafeInteger(headOnly)) return unknown();
if (headOnly > 0) return behind(headOnly);
if (indexedOnly > 0) {
return { isStale: true, commitsBehind: 0, hint: REGRESSED_HINT, status: 'diverged' };
}
return { isStale: false, commitsBehind: 0, status: 'current' };
};
const readHeadSync = (repoPath: string): string | null => {
try {
return (
@ -61,6 +92,7 @@ const readHeadSync = (repoPath: string): string | null => {
encoding: 'utf-8',
stdio: ['pipe', 'pipe', 'pipe'],
windowsHide: true,
timeout: STALENESS_TIMEOUT_MS,
}).trim() || null
);
} catch {
@ -89,14 +121,18 @@ export function checkStaleness(repoPath: string, lastCommit: string): StalenessI
// No recorded commit is not "at HEAD": there is nothing to measure against.
if (!lastCommit) return unknown();
try {
const result = execFileSync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
cwd: repoPath,
encoding: 'utf-8',
stdio: ['pipe', 'pipe', 'pipe'],
windowsHide: true,
}).trim();
const result = execFileSync(
'git',
['rev-list', '--left-right', '--count', `${lastCommit}...HEAD`],
{
cwd: repoPath,
encoding: 'utf-8',
stdio: ['pipe', 'pipe', 'pipe'],
windowsHide: true,
},
);
return fromCount(parseInt(result, 10) || 0);
return fromCounts(result);
} catch {
return fromHead(readHeadSync(repoPath), lastCommit);
}
@ -115,21 +151,25 @@ export async function checkStalenessAsync(
try {
// Note: promisified execFile captures stdout/stderr by default (no stdio option needed,
// unlike the sync variant which requires explicit stdio: ['pipe','pipe','pipe']).
const { stdout } = await execFileAsync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
cwd: repoPath,
encoding: 'utf-8',
windowsHide: true,
// The catch below fails closed on every git ERROR, but a hang is not an
// error — it is silence, and without a bound this await never settles.
// A working tree on a disconnected network mount or behind a stuck lock
// does exactly that, and `/api/repos` fans this out once per registered
// repo, so one unreachable mount could hold the whole listing open
// (#3232 review). The timeout kills the child and rejects, and the catch
// below reports it as `unknown` — still the fail-closed `isStale: false`.
timeout: STALENESS_TIMEOUT_MS,
});
const { stdout } = await execFileAsync(
'git',
['rev-list', '--left-right', '--count', `${lastCommit}...HEAD`],
{
cwd: repoPath,
encoding: 'utf-8',
windowsHide: true,
// The catch below fails closed on every git ERROR, but a hang is not an
// error — it is silence, and without a bound this await never settles.
// A working tree on a disconnected network mount or behind a stuck lock
// does exactly that, and `/api/repos` fans this out once per registered
// repo, so one unreachable mount could hold the whole listing open
// (#3232 review). The timeout kills the child and rejects, and the catch
// below reports it as `unknown` — still the fail-closed `isStale: false`.
timeout: STALENESS_TIMEOUT_MS,
},
);
return fromCount(parseInt(stdout.trim(), 10) || 0);
return fromCounts(stdout);
} catch (err) {
// A rev-list that timed out means the working tree is not answering. Asking
// it again for HEAD would only double the bound #3232 put on a hung mount.

532
gitnexus/src/core/group/extractors/http-patterns/go.ts
View file

@ -1,27 +1,38 @@
import type Parser from 'tree-sitter';
import Go from 'tree-sitter-go';
import { goImportPackageName } from '../../../ingestion/languages/go/import-package-name.js';
import { stringLiteral } from '../../../ingestion/route-extractors/go-shared.js';
import {
compilePatterns,
runCompiledPatterns,
unquoteLiteral,
type LanguagePatterns,
} from '../tree-sitter-scanner.js';
import type { HttpDetection, HttpLanguagePlugin } from './types.js';
/**
* Go HTTP plugin. Handles:
* - gin / echo / chi framework routing — `r.GET("/path", handler)`
* - gin / echo framework routing — `r.GET("/path", handler)`, including
* prefixes from route groups bound in the same function (`r.Group("/api")`)
* - net/http stdlib — `http.HandleFunc("/path", handler)`
* - net/http consumer — `http.Get(...)`, `http.NewRequest("METHOD", ...)`
* - resty consumer — `client.R().Delete("/path")`
*/
// ─── Provider: framework routing ──────────────────────────────────────
// Matches `\w+\.GET(...)` etc. (gin, echo, chi all share this shape).
// Captures the HTTP method (field name), path literal, and the handler —
// anchored to the LAST argument (`@handler .`) so a variadic middleware
// chain (`r.GET("/x", mw, handler)`, gin/echo/chi style) binds the real
// handler, not a middleware identifier (which would otherwise over-match
// and attach the route to the wrong symbol — see #2276 review).
// Matches `\w+\.GET(...)` etc. (gin and echo share this shape).
// Captures the receiver, the HTTP method (field name), and the path literal
// (either Go string form; stringLiteral decodes both, as ingestion does). The
// query does not anchor the path with `.`: tree-sitter counts comments as
// named children, so `GET(/* c */ "/p", h)` would fail the anchor. scan instead
// requires the path to be the first argument in code (comments skipped) and
// picks the handler out of the remaining code arguments. Which argument that is depends on the framework:
// gin is `GET(path, middleware..., handler)` (last), echo is
// `GET(path, handler, middleware...)` (first) — see readFrameworkImports and
// the per-call choice in scan below.
// The handler must be an identifier, an inline func literal, or a method
// value / package-qualified function (`h.ListUsers`, `handlers.ListUsers`);
// anything else there means the call cannot be attributed to a symbol, so it
// is dropped rather than guessed (variadic-middleware over-match, #2276).
const FRAMEWORK_ROUTE_PATTERNS = compilePatterns({
name: 'go-framework-route',
language: Go,
@ -31,16 +42,431 @@ const FRAMEWORK_ROUTE_PATTERNS = compilePatterns({
query: `
(call_expression
function: (selector_expression
operand: (_) @receiver
field: (field_identifier) @http_method (#match? @http_method "^(GET|POST|PUT|DELETE|PATCH)$"))
arguments: (argument_list
(interpreted_string_literal) @path
[(identifier) (func_literal)] @handler
.))
[(interpreted_string_literal) (raw_string_literal)] @path))
`,
},
],
} satisfies LanguagePatterns<Record<string, never>>);
/** Named children that are code, not comments (tree-sitter names comments). */
function codeChildren(node: Parser.SyntaxNode | null | undefined): Parser.SyntaxNode[] {
return node ? node.namedChildren.filter((c) => c.type !== 'comment') : [];
}
/** Argument forms a route handler may take. */
const HANDLER_ARG_TYPES: ReadonlySet<string> = new Set([
'identifier',
'func_literal',
'selector_expression',
]);
/**
* The file's framework import aliases: which local qualifiers resolve to
* echo and to gin. Matched on the import path rather than the local name, so
* an aliased import still counts; an unaliased import is keyed by its
* conventional package name (`goImportPackageName`). `_` and `.` imports bind
* no qualifier this file can route through. An empty set means the file
* proves nothing about that framework. Echo's verb calls take the handler as
* the FIRST argument after the path (`GET(path, handler, middleware...)`),
* gin's as the LAST (`GET(path, middleware..., handler)`) — `scan` picks the
* rule per call from these sets.
*/
function readFrameworkImports(root: Parser.SyntaxNode): {
echo: Set<string>;
gin: Set<string>;
} {
// Imports sit only at file scope; skip bodies.
const specs = root.namedChildren
.filter((node) => node.type === 'import_declaration')
.flatMap((decl) => decl.descendantsOfType('import_spec'));
const echo = new Set<string>();
const gin = new Set<string>();
for (const spec of specs) {
const importPath = stringLiteral(spec.childForFieldName('path'));
if (importPath === null) continue;
const local = spec.childForFieldName('name')?.text ?? goImportPackageName(importPath);
if (local === '_' || local === '.') continue;
if (importPath.includes('labstack/echo')) echo.add(local);
else if (importPath.includes('gin-gonic/gin')) gin.add(local);
}
return { echo, gin };
}
// ─── Route groups: `v1 := r.Group("/api/v1")` ─────────────────────────
// gin (`*gin.RouterGroup`) and echo (`*echo.Group`) routes registered on a
// group inherit every enclosing `Group(prefix)`. The prefix is recovered by
// walking the route's receiver back through its bindings, lexically, inside
// the enclosing function declaration only: a group handed to another
// function (`registerAdmin(v1)`) arrives as a parameter and contributes no
// prefix there, and a receiver bound to anything but a literal-prefix
// `Group(...)` call contributes none either — the route keeps its literal path.
// Statement-scoped bindings count too: an `if`/`switch` initializer, a `for`
// clause (including `range`), a type-switch guard, and declarations inside a
// switch case all scope over their statement the same way Go scopes them, so
// they shadow an outer group of the same name instead of being skipped. A
// select case's receive binding (`case g := <-ch:`) stops the walk entirely:
// what arrives from the channel is statically unknown, so the route keeps its
// literal path rather than inheriting an outer group.
const MAX_GROUP_DEPTH = 32;
function joinRoutePath(prefix: string, relative: string): string {
let joined = relative;
if (prefix && relative) {
joined = `${prefix.replace(/\/+$/, '')}/${relative.replace(/^\/+/, '')}`;
} else if (prefix) {
joined = prefix;
}
// Collapse duplicate slashes on the FINAL result — every return branch, not
// just the join — because ingestion's normalizeExtractedRoutePath collapses
// all "//" while the downstream contract-id normalizer does not: a path
// that keeps "//" would split into two contract ids across the strategies.
const collapsed = joined.replace(/\/+/g, '/');
// Force a leading "/" for the same reason: ingestion's
// normalizeExtractedRoutePath always adds one, while normalizeHttpPath (the
// shared contract-id normalizer) does not — a literal "x" or a slashless
// Group("api") prefix would emit `...::x` here and `...::/x` there. Gin
// also refuses a registration path that does not start with "/".
return collapsed.startsWith('/') ? collapsed : `/${collapsed}`;
}
/** `parent.Group("/p", mw...)` → its receiver and literal prefix; null otherwise. */
function asGroupCall(
node: Parser.SyntaxNode,
): { parent: Parser.SyntaxNode; prefix: string } | null {
if (node.type !== 'call_expression') return null;
const fn = node.childForFieldName('function');
if (fn?.type !== 'selector_expression' || fn.childForFieldName('field')?.text !== 'Group') {
return null;
}
const parent = fn.childForFieldName('operand');
const first = codeChildren(node.childForFieldName('arguments'))[0];
// Only a string literal carries a prefix, and it must decode to the text
// the runtime registers: stringLiteral applies Go unescaping (both `"…"`
// with escapes and raw `` `…` `` strings). A non-literal argument (a
// variable, concatenation) or an undecodable string contributes no prefix.
const prefix = first ? stringLiteral(first) : null;
if (!parent || prefix === null) return null;
return { parent, prefix };
}
/** The expression `name` is assigned by `stmt` (`:=`, `=`, or `var`), if any. */
function boundValue(stmt: Parser.SyntaxNode, name: string): Parser.SyntaxNode | null | undefined {
const pick = (
names: Parser.SyntaxNode[],
values: Parser.SyntaxNode | null,
): Parser.SyntaxNode | null | undefined => {
const i = names.findIndex((n) => n.type === 'identifier' && n.text === name);
if (i < 0) return undefined;
return codeChildren(values)[i] ?? null;
};
switch (stmt.type) {
case 'short_var_declaration':
case 'assignment_statement':
return pick(codeChildren(stmt.childForFieldName('left')), stmt.childForFieldName('right'));
case 'var_spec':
return pick(stmt.childrenForFieldName('name'), stmt.childForFieldName('value'));
case 'var_declaration': {
const specs = stmt.namedChildren.flatMap((c) =>
c.type === 'var_spec_list' ? c.namedChildren : [c],
);
for (const spec of specs) {
if (spec.type !== 'var_spec') continue;
const value = pick(spec.childrenForFieldName('name'), spec.childForFieldName('value'));
if (value !== undefined) return value;
}
return undefined;
}
default:
return undefined;
}
}
/**
* A binding whose value cannot be established statically: an earlier
* statement writes the name inside a nested scope (`{ g = r.Group("/new") }`,
* a branch or loop body), so which value reaches the use depends on control
* flow. Callers decline the route instead of picking the older binding.
*/
const CONFLICT = Symbol('conflicting-binding');
/** The name is a parameter (or method receiver): its declaration carries a static type. */
interface ParamBinding {
param: Parser.SyntaxNode;
}
type Binding = Parser.SyntaxNode | null | undefined | typeof CONFLICT | ParamBinding;
function isParamBinding(b: Binding): b is ParamBinding {
return typeof b === 'object' && b !== null && 'param' in b;
}
/** The parameter_declaration of `fn` (parameters or method receiver) declaring `name`. */
function paramDeclaring(fn: Parser.SyntaxNode, name: string): Parser.SyntaxNode | null {
for (const list of [fn.childForFieldName('parameters'), fn.childForFieldName('receiver')]) {
for (const decl of codeChildren(list)) {
if (decl.type !== 'parameter_declaration' && decl.type !== 'variadic_parameter_declaration') {
continue;
}
if (decl.childrenForFieldName('name').some((n) => n.text === name)) return decl;
}
}
return null;
}
/** Whether `inner` lies within `outer`'s source span. */
function within(outer: Parser.SyntaxNode | null, inner: Parser.SyntaxNode): boolean {
return !!outer && outer.startIndex <= inner.startIndex && inner.endIndex <= outer.endIndex;
}
/**
* Whether `stmt` writes `name` with a plain assignment somewhere inside it
* (`g = …` in a nested block, branch, loop, or closure body). A nested `:=`
* declares a new variable and is not a write to the outer one.
*/
function writesNameInside(stmt: Parser.SyntaxNode, name: string): boolean {
return [stmt, ...stmt.descendantsOfType('assignment_statement')].some(
(a) => a.type === 'assignment_statement' && declaresName(a.childForFieldName('left'), name),
);
}
/** Whether an identifier or expression_list (e.g. a range left side) declares `name`. */
function declaresName(node: Parser.SyntaxNode | null, name: string): boolean {
if (!node) return false;
if (node.type === 'identifier') return node.text === name;
return node.namedChildren.some((n) => n.type === 'identifier' && n.text === name);
}
/**
* The value last bound to identifier `ident` before its use: the nearest
* binding site in the enclosing scopes, walking outward — preceding statements
* in blocks and switch/select cases (`expression_case`/`type_case`/
* `communication_case`/`default_case` act as statement containers), then
* statement-scoped bindings (`if`/`switch` initializers, `for` clauses
* including `range`, type-switch guards), up to the enclosing function
* declaration. Returns null when the name is a parameter, is bound without a
* value, is received from a channel by a select case head (the received value
* is statically unknown, so the walk stops instead of escaping to an outer
* group), or is not bound in scope.
*/
function findBinding(ident: Parser.SyntaxNode): Parser.SyntaxNode | null | typeof CONFLICT {
const binding = lookupBinding(ident);
return isParamBinding(binding) ? null : (binding ?? null);
}
/**
* findBinding's walk, keeping "declared without a traceable value" (null: a
* `func` literal parameter, `var x T`, a select receive) apart from "not
* declared before reaching the enclosing function declaration" (undefined).
* CONFLICT means a preceding statement writes the name in a nested scope, so
* the value at the use is control-flow dependent. A parameter or method
* receiver of the enclosing function returns its declaration (ParamBinding):
* no value, but a static type.
*/
function lookupBinding(ident: Parser.SyntaxNode): Binding {
const name = ident.text;
let child: Parser.SyntaxNode = ident;
for (let node = ident.parent; node; child = node, node = node.parent) {
if (
node.type === 'function_declaration' ||
node.type === 'method_declaration' ||
node.type === 'func_literal'
) {
const param = paramDeclaring(node, name);
if (param) return { param };
if (node.type === 'func_literal') continue;
return undefined;
}
// Inside a grouped `var ( a = …; b = a.Group(…) )`, the specs before the
// one holding the use are already in scope; the current and later specs
// are not (`var g = g.Group(…)` reads the outer g).
if (node.type === 'var_spec_list') {
const specs = codeChildren(node);
const useIndex = specs.findIndex((s) => s.id === child.id);
for (const spec of specs.slice(0, useIndex).reverse()) {
const value = boundValue(spec, name);
if (value !== undefined) return value;
}
continue;
}
if (
node.type === 'block' ||
node.type === 'expression_case' ||
node.type === 'type_case' ||
node.type === 'communication_case' ||
node.type === 'default_case'
) {
// A select case head can rebind the name (`case g := <-ch:` or
// `case g = <-ch:`); the received value is statically unknown, so the
// walk must STOP with no traceable value — the same decline the
// ingestion-side route bindings record (value null) — instead of
// escaping to an outer group of the same name.
if (node.type === 'communication_case') {
for (const head of node.children) {
if (
head.type === 'receive_statement' &&
declaresName(head.childForFieldName('left'), name)
) {
return null;
}
}
}
const stmts = codeChildren(node);
const useIndex = stmts.findIndex((s) => s.id === child.id);
for (const stmt of stmts.slice(0, useIndex).reverse()) {
const value = boundValue(stmt, name);
if (value !== undefined) return value;
// A write nested in an earlier statement (block, branch, loop) may or
// may not run before the use: the reaching value is unprovable.
if (writesNameInside(stmt, name)) return CONFLICT;
}
continue;
}
// Statement-scoped bindings enclose the use the same way Go scopes them.
if (node.type === 'if_statement' || node.type === 'expression_switch_statement') {
// A use inside the initializer itself (`if g := g.Group(…); …`) reads
// the OUTER binding: the new one only scopes over what follows it.
const init = node.childForFieldName('initializer');
if (init && !within(init, ident)) {
const value = boundValue(init, name);
if (value !== undefined) return value;
}
continue;
}
if (node.type === 'for_statement') {
const clause = codeChildren(node)[0];
// A write in the loop's post statement, condition, or body runs between
// iterations, so from the second pass on the body sees that value
// instead of the one it entered with (`for ; c; g = r.Group("/post")`):
// the prefix is control-flow dependent, so decline it.
if (within(node.childForFieldName('body'), ident)) {
const loopParts = [
node.childForFieldName('body'),
clause?.type === 'for_clause' ? clause.childForFieldName('update') : null,
clause?.type === 'for_clause' ? clause.childForFieldName('condition') : null,
];
if (loopParts.some((part) => part && writesNameInside(part, name))) return CONFLICT;
}
if (clause?.type === 'for_clause') {
// Only the initializer binds before the body; an absent initializer
// (`for ; c; i++`) binds nothing.
const init = clause.childForFieldName('initializer');
if (init && !within(init, ident)) {
const value = boundValue(init, name);
if (value !== undefined) return value;
}
} else if (clause?.type === 'range_clause') {
if (
declaresName(clause.childForFieldName('left'), name) &&
!within(clause.childForFieldName('right'), ident)
) {
return clause.childForFieldName('right') ?? null;
}
}
continue;
}
if (node.type === 'type_switch_statement') {
// `switch g := x.(type)` — the guard list is the `alias` field, which
// only the `:=` form has (bare `switch x.(type)` parses with none),
// matching how the ingestion-side route-bindings read it. The switched
// value is the operand right after the guard list.
const guard = node.childForFieldName('alias');
const switched = codeChildren(node)[1] ?? null;
if (
guard?.type === 'expression_list' &&
declaresName(guard, name) &&
!within(switched, ident)
) {
return switched;
}
continue;
}
}
return undefined;
}
/**
* Whether a mixed-import file's route receiver traces back to echo's
* constructor — `e := echo.New()` / `echo.Default()` with `echo` resolving to
* one of the file's verified echo import aliases — either directly or through
* enclosing `Group(...)` calls (`users := api.Group(…)` ← `api := e.Group(…)`
* ← `echo.New()`), the normal shape of grouped routes (review #7, #10).
* A parameter or method receiver counts by its declared type instead:
* `e *echo.Echo` / `g *echo.Group` (with `echo` one of those aliases) proves
* echo; any other type — gin's, or one the file cannot tie to echo — does not.
* Unrelated packages' `New()`, a local that shadows the echo import name, and
* anything else return false so the caller keeps the conservative
* last-argument fallback instead of guessing. Returns null when the Group chain exceeds MAX_GROUP_DEPTH or a
* binding on it is control-flow dependent (CONFLICT): the framework is then
* unprovable either way, so the caller declines the route.
*/
function receiverBindsToEchoConstructor(
receiver: Parser.SyntaxNode,
echoAliases: ReadonlySet<string>,
depth = 0,
): boolean | null {
if (depth > MAX_GROUP_DEPTH) return null;
// An identifier resolves through its binding; a chained `X.Group(…).Group(…)`
// operand is already a call and is inspected as-is.
const value = receiver.type === 'identifier' ? lookupBinding(receiver) : receiver;
if (value === CONFLICT) return null;
if (isParamBinding(value))
return isEchoRouterType(value.param.childForFieldName('type'), echoAliases);
if (value?.type !== 'call_expression') return false;
const fn = value.childForFieldName('function');
if (fn?.type !== 'selector_expression') return false;
const field = fn.childForFieldName('field')?.text;
const operand = fn.childForFieldName('operand');
if (!operand) return false;
if (field === 'New' || field === 'Default') {
return operand.type === 'identifier' && echoAliases.has(operand.text) && !isLocalName(operand);
}
if (field === 'Group') {
return receiverBindsToEchoConstructor(operand, echoAliases, depth + 1);
}
return false;
}
/** `*echo.Echo` / `echo.Echo` / `*echo.Group` with `echo` a verified echo import alias. */
function isEchoRouterType(
type: Parser.SyntaxNode | null,
echoAliases: ReadonlySet<string>,
): boolean {
const named = type?.type === 'pointer_type' ? codeChildren(type)[0] : type;
if (named?.type !== 'qualified_type') return false;
const pkg = named.childForFieldName('package')?.text;
const typeName = named.childForFieldName('name')?.text;
return !!pkg && echoAliases.has(pkg) && (typeName === 'Echo' || typeName === 'Group');
}
/**
* Whether `ident` names a local value rather than an imported package: a
* declaration in scope (with or without a value — `var echo Factory` shadows
* too) or a parameter/receiver of an enclosing function. Go lets either
* shadow a package qualifier (`func f(echo *Factory) { echo.New() }`).
*/
function isLocalName(ident: Parser.SyntaxNode): boolean {
// lookupBinding covers parameters and receivers too (ParamBinding).
return lookupBinding(ident) !== undefined;
}
/**
* Joined `Group(...)` prefix of a route receiver; '' when it cannot be traced.
* Returns null when the chain exceeds MAX_GROUP_DEPTH, or when a binding on it
* is control-flow dependent (CONFLICT): a partial or stale prefix would emit
* a wrong path, so the caller declines the route instead.
*/
function groupPrefix(receiver: Parser.SyntaxNode, depth = 0): string | null {
if (depth > MAX_GROUP_DEPTH) return null;
const value = receiver.type === 'identifier' ? findBinding(receiver) : receiver;
if (value === CONFLICT) return null;
const group = value ? asGroupCall(value) : null;
if (!group) return '';
const outer = groupPrefix(group.parent, depth + 1);
return outer === null ? null : joinRoutePath(outer, group.prefix);
}
// ─── Provider: net/http `http.HandleFunc("/p", handler)` ─────────────
const HANDLE_FUNC_PATTERNS = compilePatterns({
name: 'go-handle-func',
@ -135,27 +561,87 @@ export const GO_HTTP_PLUGIN: HttpLanguagePlugin = {
scan(tree) {
const out: HttpDetection[] = [];
// Framework providers: r.GET/POST/... with handler identifier
// Framework providers: r.GET/POST/... on an engine or (nested) route group
const imports = readFrameworkImports(tree.rootNode);
const echoOnly = imports.echo.size > 0 && imports.gin.size === 0;
const mixed = imports.echo.size > 0 && imports.gin.size > 0;
// Handler names declared more than once in this file (`(h *A) List` and
// `(o *B) List`): the emitted name is field-only, so these must resolve
// only when unique in the file instead of taking the first same-named row.
const declaredNames = new Map<string, number>();
for (const decl of tree.rootNode.descendantsOfType([
'function_declaration',
'method_declaration',
])) {
const declName = decl.childForFieldName('name')?.text;
if (declName) declaredNames.set(declName, (declaredNames.get(declName) ?? 0) + 1);
}
for (const match of runCompiledPatterns(FRAMEWORK_ROUTE_PATTERNS, tree)) {
const methodNode = match.captures.http_method;
const pathNode = match.captures.path;
const handlerNode = match.captures.handler;
const receiverNode = match.captures.receiver;
if (!methodNode || !pathNode) continue;
const path = unquoteLiteral(pathNode.text);
if (path === null) continue;
const literalPath = stringLiteral(pathNode);
if (literalPath === null) continue;
const argList = pathNode.parent;
if (argList?.type !== 'argument_list') continue;
const args = codeChildren(argList);
if (args[0]?.id !== pathNode.id) continue;
// The path is the first code argument, so everything after it is a handler or
// middleware candidate: echo's verb calls take the FIRST of those, gin's
// the LAST (see FRAMEWORK_ROUTE_PATTERNS / readFrameworkImports). The
// rule is chosen per call: an echo-only file is unambiguous; a
// mixed-import file takes the first argument only when the receiver
// provably traces to echo's constructor (directly or through enclosing
// Group() calls) — everything else keeps the last-argument anchor,
// gin's order and the safer default when the file proves nothing.
const rest = args.slice(1);
if (rest.length === 0) continue;
const echoOrder = mixed
? receiverNode
? receiverBindsToEchoConstructor(receiverNode, imports.echo)
: false
: echoOnly;
// A Group chain deeper than MAX_GROUP_DEPTH proves neither the full
// prefix nor the framework order: decline rather than emit a guess.
if (echoOrder === null) continue;
const prefix = receiverNode ? groupPrefix(receiverNode) : '';
if (prefix === null) continue;
const handlerNode = echoOrder ? rest[0] : rest[rest.length - 1];
if (!HANDLER_ARG_TYPES.has(handlerNode.type)) continue;
const path = receiverNode ? joinRoutePath(prefix, literalPath) : literalPath;
// An inline `func(){…}` handler has no name → emit `name: null` and a
// `line` so it resolves to its containing/closure symbol by line-span
// containment (like a consumer). A named identifier handler keeps its
// name and resolves by name; `line` is harmless there.
// containment (like a consumer). A named handler keeps its name and
// resolves by name; `line` is harmless there. For a method value or a
// package-qualified function (`h.List`, `pkg.List`) that name is the
// field, and the operand (usually a local variable, not the receiver
// type) does not prove where `List` is declared — so the detection is
// marked qualifiedHandler: resolve only to a repo-wide unique `List`,
// never to a same-named local method that merely shares the name.
const isInlineHandler = handlerNode?.type === 'func_literal';
const isQualified = handlerNode?.type === 'selector_expression';
const handlerName = isQualified
? (handlerNode.childForFieldName('field')?.text ?? null)
: (handlerNode?.text ?? null);
out.push({
role: 'provider',
framework: 'go-framework',
method: methodNode.text.toUpperCase(),
path,
name: isInlineHandler ? null : (handlerNode?.text ?? null),
name: isInlineHandler ? null : handlerName,
line: (handlerNode ?? pathNode).startPosition.row + 1,
confidence: 0.8,
...(isQualified ? { qualifiedHandler: true } : {}),
// A bare name declared more than once in this file (a function and a
// method of the same name) resolves only when the file holds exactly
// one match, rather than binding to whichever row the graph lists first.
...(!isQualified &&
!isInlineHandler &&
handlerName &&
(declaredNames.get(handlerName) ?? 0) > 1
? { strictHandlerResolution: true }
: {}),
});
}
@ -164,7 +650,7 @@ export const GO_HTTP_PLUGIN: HttpLanguagePlugin = {
const pathNode = match.captures.path;
const handlerNode = match.captures.handler;
if (!pathNode) continue;
const path = unquoteLiteral(pathNode.text);
const path = stringLiteral(pathNode);
if (path === null) continue;
// Inline `func(){…}` handler → resolve by containment (see go-framework
// note above); a named handler resolves by name.
@ -187,7 +673,7 @@ export const GO_HTTP_PLUGIN: HttpLanguagePlugin = {
if (!fnNode || !pathNode) continue;
const httpMethod = HTTP_CLIENT_METHOD_TO_HTTP[fnNode.text];
if (!httpMethod) continue;
const path = unquoteLiteral(pathNode.text);
const path = stringLiteral(pathNode);
if (path === null) continue;
out.push({
role: 'consumer',
@ -205,8 +691,8 @@ export const GO_HTTP_PLUGIN: HttpLanguagePlugin = {
const methodNode = match.captures.http_method;
const pathNode = match.captures.path;
if (!methodNode || !pathNode) continue;
const method = unquoteLiteral(methodNode.text);
const path = unquoteLiteral(pathNode.text);
const method = stringLiteral(methodNode);
const path = stringLiteral(pathNode);
if (method === null || path === null) continue;
out.push({
role: 'consumer',
@ -224,7 +710,7 @@ export const GO_HTTP_PLUGIN: HttpLanguagePlugin = {
const methodNode = match.captures.http_method;
const pathNode = match.captures.path;
if (!methodNode || !pathNode) continue;
const path = unquoteLiteral(pathNode.text);
const path = stringLiteral(pathNode);
if (path === null) continue;
out.push({
role: 'consumer',

8
gitnexus/src/core/group/extractors/http-patterns/types.ts
View file

@ -58,6 +58,14 @@ export interface HttpDetection {
handlerImport?: { name: string; module: string };
/** Resolve only from the registration file or exact import target; never guess repo-wide. */
strictHandlerResolution?: boolean;
/**
* The handler was designated through a qualifier the plugin cannot tie to a
* declaration (`recv.name`, `pkg.name`): `name` alone does not prove the
* handler lives in the registration file. Skip the file-scoped name lookup
* — a same-named but unrelated local symbol would win it — and accept only
* a repo-wide unique match, else keep the file-level fallback.
*/
qualifiedHandler?: boolean;
/**
* The plugin saw a provider handler designator but could not prove its owner.
* Prevents the orchestrator from treating it as an anonymous inline handler

16
gitnexus/src/core/group/extractors/http-route-extractor.ts
View file

@ -629,11 +629,17 @@ export class HttpRouteExtractor implements ContractExtractor {
if (d.strictHandlerResolution) return null;
return resolveSymbolByNameUnique(d.handlerImport.name);
}
const byName = d.strictHandlerResolution
? resolveFileSymbolByNameUnique(syms, d.name)
: resolveSymbolByName(syms, d.name);
if (byName) return byName;
if (d.strictHandlerResolution) return null;
// A qualified designator (`recv.name`) does not prove the handler is
// declared in this file, so the file-first rung could bind an
// unrelated same-named local symbol: go straight to the unique
// repo-wide match.
if (!d.qualifiedHandler) {
const byName = d.strictHandlerResolution
? resolveFileSymbolByNameUnique(syms, d.name)
: resolveSymbolByName(syms, d.name);
if (byName) return byName;
if (d.strictHandlerResolution) return null;
}
const byGlobal = await resolveSymbolByNameUnique(d.name);
if (byGlobal) return byGlobal;
// A NAMED handler we could not resolve by name (neither file-scoped nor

107
gitnexus/src/core/incremental/write-reconciliation.ts Normal file
View file

@ -0,0 +1,107 @@
import type { GraphNode } from 'gitnexus-shared';
import type { KnowledgeGraph } from '../graph/types.js';
import { NODE_TABLES, type NodeTableName } from '../lbug/schema.js';
import { sanitizeUTF8 } from '../lbug/csv-generator.js';
// These layers need a different oracle: folders can outlive their last file,
// derived nodes may be preserved without recomputation, and PDG can be streamed.
const EXCLUDED = new Set<NodeTableName>(['Folder', 'Community', 'Process', 'BasicBlock']);
const WITHOUT_RANGE = new Set<NodeTableName>(['File', 'Route', 'Tool']);
interface IdentityRow {
id: string;
name: string | null;
filePath: string | null;
startLine?: number | null;
endLine?: number | null;
}
const storedString = (value: string | undefined): string => sanitizeUTF8(value || '');
const storedIdentityField = (node: GraphNode, field: string): unknown => {
const value = node.properties[field];
if (field === 'name' || field === 'filePath') {
return storedString(value as string | undefined);
}
if (node.label === 'Destination') {
return typeof value === 'number' && Number.isFinite(value) ? value : null;
}
return value ?? -1;
};
/**
* Certify the identity fields used by context/impact/detect_changes, including
* retained rows. A write-set-only probe misses corruption of an unchanged row.
* Scan one label at a time, without path/range predicates: a corrupt field must
* not be able to hide its own row. No multi-label scans (#3139), N+1 ID lookups,
* source-content copies, or whole-graph row materialization.
*
* This certifies node identity, not relationships or native storage internals.
* Call after COPY/checkpoint and after FTS/embedding/checkpoint, before metadata.
*/
export async function reconcileGraphNodeIdentities(
graph: KnowledgeGraph,
query: (cypher: string) => Promise<IdentityRow[]>,
phase: string,
): Promise<{ nodes: number; tables: number }> {
const expected = new Map<NodeTableName, Map<string, GraphNode>>();
for (const table of NODE_TABLES) {
if (!EXCLUDED.has(table)) expected.set(table, new Map());
}
for (const node of graph.iterNodes()) {
const table = expected.get(node.label as NodeTableName);
if (!table) continue;
const id = storedString(node.id);
if (!id || table.has(id)) {
throw new Error(`Graph identity reconciliation (${phase}): invalid or duplicate ID ${id}`);
}
table.set(id, node);
}
let nodes = 0;
for (const [table, remaining] of expected) {
const fields = WITHOUT_RANGE.has(table)
? ['id', 'name', 'filePath']
: ['id', 'name', 'filePath', 'startLine', 'endLine'];
const identityFields = fields.slice(1);
const fail: (detail: string, cause?: unknown) => never = (detail, cause) => {
throw new Error(
`Graph identity reconciliation failed (${phase}, ${table}): ${detail}. ` +
'Freshness was not advanced; run `gitnexus analyze --force` to rebuild the graph.',
{ cause },
);
};
let rows: IdentityRow[];
try {
rows = await query(
`MATCH (n:\`${table}\`) RETURN ${fields.map((f) => `n.${f} AS ${f}`).join(', ')}`,
);
} catch (error) {
fail(
`could not read identity fields: ${error instanceof Error ? error.message : String(error)}`,
error,
);
}
for (const row of rows) {
const node = remaining.get(row.id);
if (!node) fail(`unexpected or duplicate ID ${JSON.stringify(row.id)}`);
for (const field of identityFields) {
const wanted = storedIdentityField(node, field);
const actual = field === 'name' || field === 'filePath' ? (row[field] ?? '') : row[field];
if (actual !== wanted) {
fail(
`${row.id}.${field}: expected ${JSON.stringify(wanted)}, read ${JSON.stringify(actual)}`,
);
}
}
remaining.delete(row.id);
nodes++;
}
if (remaining.size) {
fail(
`${remaining.size} missing ID(s), including ${JSON.stringify(remaining.keys().next().value)}`,
);
}
}
return { nodes, tables: expected.size };
}

16
gitnexus/src/core/ingestion/cobol-processor.ts
View file

@ -26,6 +26,8 @@ import {
import { expandCopies } from './cobol/cobol-copy-expander.js';
import { processJclFiles } from './cobol/jcl-processor.js';
import { resolveCobolCopyTarget } from './languages/cobol/copy-target.js';
import { COBOL_EXTENSIONS, JCL_EXTENSIONS } from './cobol/file-types.js';
export { isCobolFile, isJclFile } from './cobol/file-types.js';
import { logger } from '../logger.js';
@ -33,10 +35,6 @@ import { logger } from '../logger.js';
// File detection
// ---------------------------------------------------------------------------
const COBOL_EXTENSIONS = new Set(['.cob', '.cbl', '.cobol', '.cpy', '.copybook']);
const JCL_EXTENSIONS = new Set(['.jcl', '.job', '.proc']);
const COPYBOOK_EXTENSIONS = new Set(['.cpy', '.copybook']);
interface CobolFile {
@ -67,16 +65,6 @@ export interface CobolProcessResult {
arithmeticOps: number;
}
/** Returns true if the file is a COBOL or copybook file. */
export function isCobolFile(filePath: string): boolean {
return COBOL_EXTENSIONS.has(path.extname(filePath).toLowerCase());
}
/** Returns true if the file is a JCL file. */
export function isJclFile(filePath: string): boolean {
return JCL_EXTENSIONS.has(path.extname(filePath).toLowerCase());
}
/** Returns true if the file is a COBOL copybook. */
function isCopybook(filePath: string): boolean {
return COPYBOOK_EXTENSIONS.has(path.extname(filePath).toLowerCase());

15
gitnexus/src/core/ingestion/cobol/file-types.ts Normal file
View file

@ -0,0 +1,15 @@
import path from 'node:path';
// Keep detection shared without loading the analyze-only language providers.
export const COBOL_EXTENSIONS = new Set(['.cob', '.cbl', '.cobol', '.cpy', '.copybook']);
export const JCL_EXTENSIONS = new Set(['.jcl', '.job', '.proc']);
/** Includes COBOL programs and copybooks accepted by ingestion. */
export function isCobolFile(filePath: string): boolean {
return COBOL_EXTENSIONS.has(path.extname(filePath).toLowerCase());
}
/** Includes job and procedure aliases accepted by JCL ingestion. */
export function isJclFile(filePath: string): boolean {
return JCL_EXTENSIONS.has(path.extname(filePath).toLowerCase());
}

18
gitnexus/src/core/ingestion/community-processor.ts
View file

@ -176,7 +176,10 @@ export interface CommunityMembership {
export interface CommunityDetectionResult {
communities: CommunityNode[];
/** Assignments to retained communities, safe to emit as MEMBER_OF edges. */
memberships: CommunityMembership[];
/** All Leiden assignments, including filtered singletons. Optional for legacy producers. */
rawMemberships?: CommunityMembership[];
stats: {
totalCommunities: number;
modularity: number;
@ -235,6 +238,7 @@ export const processCommunities = async (
return {
communities: [],
memberships: [],
rawMemberships: [],
stats: {
totalCommunities: 0,
modularity: 0,
@ -267,13 +271,16 @@ export const processCommunities = async (
onProgress?.('Creating membership edges...', 80);
// Step 4: Create membership mappings
// Step 4: Preserve all assignments for skill generation, but only emit
// memberships for retained communities with a corresponding graph node.
const retainedCommunityIds = new Set(communityNodes.map((community) => community.id));
const memberships: CommunityMembership[] = [];
const rawMemberships: CommunityMembership[] = [];
Object.entries(details.communities).forEach(([nodeId, communityNum]) => {
memberships.push({
nodeId,
communityId: `comm_${communityNum}`,
});
const communityId = `comm_${communityNum}`;
const membership = { nodeId, communityId };
rawMemberships.push(membership);
if (retainedCommunityIds.has(communityId)) memberships.push(membership);
});
onProgress?.('Community detection complete!', 100);
@ -281,6 +288,7 @@ export const processCommunities = async (
return {
communities: communityNodes,
memberships,
rawMemberships,
stats: {
totalCommunities: details.count,
modularity: details.modularity,

11
gitnexus/src/core/ingestion/language-provider.ts
View file

@ -46,7 +46,7 @@ import type {
RepoConstants,
} from './route-extractors/constant-resolver.js';
import type Parser from 'tree-sitter';
import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
import type { ExtractedDecoratorRoute, ExtractedToolDef } from './workers/parse-worker.js';
import type { SemanticModel } from './model/semantic-model.js';
/** What a provider's {@link LanguageProviderConfig.resolveRouteHandler} can see. */
@ -546,6 +546,15 @@ interface LanguageProviderConfig {
*/
readonly extractTextRoutes?: (filePath: string, content: string) => ExtractedRoute[];
/** Extract tool registrations after captures, using only emitted callable identities.
* The map keys are declaration-name AST node IDs, local to this parsed tree. */
readonly extractToolDefinitions?: (
tree: Parser.Tree,
filePath: string,
lineOffset: number,
callableBindings: ReadonlyMap<number, string>,
) => ExtractedToolDef[];
/**
* Extract routes that a parsed file declares in its own AST.
*

78
gitnexus/src/core/ingestion/languages/swift/callable-visibility.ts Normal file
View file

@ -0,0 +1,78 @@
import type { ParsedFile, ScopeId, SymbolDefinition, TypeRef } from 'gitnexus-shared';
import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
import { findClassBindingInScope } from '../../scope-resolution/scope/walkers.js';
export function swiftIsCallableVisibleFromCaller(ctx: {
readonly candidate: SymbolDefinition;
readonly callerParsed?: ParsedFile;
readonly callArity?: number;
readonly callerScope?: ScopeId;
readonly scopes?: ScopeResolutionIndexes;
}): boolean {
const indexes = ctx.scopes;
if (ctx.callerScope === undefined || indexes === undefined || ctx.callArity !== 0) return true;
const name = ctx.candidate.qualifiedName?.split('.').at(-1);
if (name === undefined) return true;
let scopeId: ScopeId | null = ctx.callerScope;
let selfType: TypeRef | undefined;
while (scopeId !== null) {
const scope = indexes.scopeTree.getScope(scopeId);
if (scope === undefined) break;
// A local function selected inside the caller wins before member lookup.
if (
scope.kind !== 'Class' &&
scope.ownedDefs.some((def) => def.nodeId === ctx.candidate.nodeId)
)
return true;
selfType ??= scope.typeBindings.get('self');
if (scope.kind === 'Class') {
const classDef =
scope.ownedDefs.find((def) => def.type === 'Class') ??
(selfType === undefined
? undefined
: findClassBindingInScope(ctx.callerScope, selfType.rawName, indexes, undefined, {
uniqueQualifiedNameFallback: false,
}));
const propertyOnOwner = (ownerId: string, ownerName: string): boolean =>
indexes.qualifiedNames.get(`${ownerName}.${name}`).some((defId) => {
const def = indexes.defs.get(defId);
return def?.type === 'Property' && def.ownerId === ownerId;
});
const ownProperty =
scope.ownedDefs.some(
(def) => def.type === 'Property' && def.qualifiedName?.split('.').at(-1) === name,
) ||
(classDef !== undefined &&
classDef.qualifiedName !== undefined &&
propertyOnOwner(classDef.nodeId, classDef.qualifiedName));
const inheritedProperty =
classDef !== undefined &&
indexes.methodDispatch.mroFor(classDef.nodeId).some((ownerId) => {
const ownerName = indexes.defs.get(ownerId)?.qualifiedName;
return ownerName !== undefined && propertyOnOwner(ownerId, ownerName);
});
if (!ownProperty && !inheritedProperty) return true;
// Swift's nested function is owned by its own Function scope. A
// same-file sibling must not count as a nearer lexical binding.
const declarationScope = ctx.callerParsed?.scopes.find((candidateScope) =>
candidateScope.ownedDefs.some((def) => def.nodeId === ctx.candidate.nodeId),
);
if (
declarationScope !== undefined &&
declarationScope.kind === 'Function' &&
(declarationScope.id === ctx.callerScope ||
indexes.scopeTree.getAncestors(declarationScope.id).includes(ctx.callerScope))
)
return true;
// Scope defs do not carry Swift access modifiers. A method positively
// selected on this type must not be vetoed by an uncertain ancestor.
return classDef !== undefined && ctx.candidate.ownerId === classDef.nodeId;
}
scopeId = scope.parent;
}
return true;
}

2
gitnexus/src/core/ingestion/languages/swift/scope-resolver.ts
View file

@ -70,6 +70,7 @@ import {
import { stripSwiftTypePreservingDecoration } from './interpret.js';
import { groupSwiftFilesByModule } from './target-grouping.js';
import { swiftIsGlobalNameFallbackPlausible } from './name-fallback-visibility.js';
import { swiftIsCallableVisibleFromCaller } from './callable-visibility.js';
const ZERO_RANGE = { startLine: 0, startCol: 0, endLine: 0, endCol: 0 } as const;
@ -155,6 +156,7 @@ const swiftScopeResolver: ScopeResolver = {
// no-`new` constructor + cross-file free-call shape).
allowGlobalFreeCallFallback: true,
isGlobalNameFallbackPlausible: swiftIsGlobalNameFallbackPlausible,
isCallableVisibleFromCaller: swiftIsCallableVisibleFromCaller,
// Swift's call graph models `Type(...)` as a reference to the type
// itself, not its `init` — both the legacy DAG and this test suite link

3
gitnexus/src/core/ingestion/languages/typescript.ts
View file

@ -130,6 +130,7 @@ import { extractDataRouteTableRoutes } from '../route-extractors/data-route-tabl
import { extractNestRoutes } from '../route-extractors/nest.js';
import { extractTrpcRoutes, shouldScanForTrpcRoutes } from '../route-extractors/trpc.js';
import { extractConvexEndpointProperties } from './typescript/convex-endpoint-metadata.js';
import { extractToolDefinitions } from './typescript/tool-definitions.js';
const extractJsTsRoutes = (...args: Parameters<typeof extractDispatchGuardRoutes>) => [
...extractDispatchGuardRoutes(...args),
@ -494,6 +495,7 @@ export const typescriptProvider = defineLanguage({
// Content-based (not AST): tRPC procedure routers are scanned from source text.
// Path-gate lives here (language provider), not in the shared parse worker.
extractTextRoutes: extractJsTsTextRoutes,
extractToolDefinitions,
});
export const javascriptProvider = defineLanguage({
@ -577,4 +579,5 @@ export const javascriptProvider = defineLanguage({
extractDecoratorRoutes: extractJsTsRoutes,
// Content-based (not AST): tRPC procedure routers are scanned from source text.
extractTextRoutes: extractJsTsTextRoutes,
extractToolDefinitions,
});

365
gitnexus/src/core/ingestion/languages/typescript/tool-definitions.ts Normal file
View file

@ -0,0 +1,365 @@
import type Parser from 'tree-sitter';
import type { SyntaxNode } from 'tree-sitter';
import type { ExtractedToolDef } from '../../workers/parse-worker.js';
import { plainString, propertyName } from '../../route-extractors/data-route-table.js';
interface Scope {
parent?: Scope;
functionScope: boolean;
bindings: Map<string, Binding>;
}
interface Binding {
name: SyntaxNode;
scope: Scope;
kind: 'unknown' | 'sdk' | 'sdk-namespace' | 'variable' | 'parameter' | 'function';
value?: SyntaxNode;
type?: SyntaxNode;
typeOnly?: boolean;
immutable?: boolean;
invalid?: boolean;
}
const FUNCTIONS = new Set([
'function_declaration',
'generator_function_declaration',
'function_expression',
'generator_function',
'arrow_function',
'method_definition',
]);
const BLOCKS = new Set([
'statement_block',
'for_statement',
'for_in_statement',
'switch_body',
'catch_clause',
'class_body',
]);
const SDK_MODULES = new Set([
'@modelcontextprotocol/sdk/server/mcp.js',
'@modelcontextprotocol/sdk/server/mcp',
]);
function lookup(scope: Scope, name: string): Binding | undefined {
for (let current: Scope | undefined = scope; current; current = current.parent) {
const binding = current.bindings.get(name);
if (binding) return binding;
}
}
/** Only binding/assignment patterns: never descend into keys, types or defaults.
* Member assignment targets are reported separately from binding names. */
function patternNames(pattern: SyntaxNode, onMember?: (member: SyntaxNode) => void): SyntaxNode[] {
const names: SyntaxNode[] = [];
const pending = [pattern];
while (pending.length) {
const node = pending.pop()!;
if (node.type === 'identifier' || node.type === 'shorthand_property_identifier_pattern') {
names.push(node);
} else if (node.type === 'member_expression' || node.type === 'subscript_expression') {
onMember?.(node);
} else if (node.type === 'pair_pattern') {
const value = node.childForFieldName('value');
if (value) pending.push(value);
} else if (node.type === 'assignment_pattern' || node.type === 'object_assignment_pattern') {
const left = node.childForFieldName('left');
if (left) pending.push(left);
} else if (
node.type === 'array_pattern' ||
node.type === 'object_pattern' ||
node.type === 'rest_pattern'
) {
pending.push(...node.namedChildren);
}
}
return names;
}
function declare(scope: Scope, name: SyntaxNode, details: Partial<Binding> = {}): void {
const previous = scope.bindings.get(name.text);
if (previous) {
previous.invalid = true;
} else {
scope.bindings.set(name.text, { name, scope, kind: 'unknown', ...details });
}
}
function variableScope(scope: Scope): Scope {
while (!scope.functionScope && scope.parent) scope = scope.parent;
return scope;
}
function collectBindings(root: SyntaxNode) {
const moduleScope: Scope = { functionScope: true, bindings: new Map() };
const scopes = new Map<number, Scope>();
const calls: SyntaxNode[] = [];
const writes: SyntaxNode[] = [];
const pending = [{ node: root, scope: moduleScope }];
while (pending.length) {
const entry = pending.pop()!;
const node = entry.node;
let scope = entry.scope;
const isFunction = FUNCTIONS.has(node.type);
const name = node.childForFieldName('name');
if (node.type === 'function_declaration' || node.type === 'generator_function_declaration') {
if (name) declare(scope, name, { kind: 'function', value: node, immutable: true });
} else if (
[
'class_declaration',
'interface_declaration',
'type_alias_declaration',
'enum_declaration',
].includes(node.type)
) {
if (name) declare(scope, name);
}
if (
isFunction ||
BLOCKS.has(node.type) ||
node.type === 'class' ||
node.type === 'class_declaration'
) {
scope = { parent: scope, functionScope: isFunction, bindings: new Map() };
}
scopes.set(node.id, scope);
if (node.type === 'class' && name) declare(scope, name);
if (isFunction) {
if (name && (node.type === 'function_expression' || node.type === 'generator_function')) {
declare(scope, name, { kind: 'function', value: node, immutable: true });
}
const parameters = node.childForFieldName('parameters');
const single = node.childForFieldName('parameter');
for (const parameter of parameters?.namedChildren ?? (single ? [single] : [])) {
const pattern = parameter.childForFieldName('pattern') ?? parameter;
const type = parameter.childForFieldName('type')?.namedChildren[0];
for (const bindingName of patternNames(pattern)) {
declare(scope, bindingName, {
kind: 'parameter',
...(pattern.type === 'identifier' && type ? { type } : {}),
});
}
}
} else if (node.type === 'import_statement') {
const source = node.childForFieldName('source');
const sdk = source !== null && SDK_MODULES.has(plainString(source) ?? '');
const typeOnly = node.children.some((child) => child.type === 'type');
const clause = node.namedChildren.find((child) => child.type === 'import_clause');
for (const child of clause?.namedChildren ?? []) {
if (child.type === 'identifier') declare(scope, child);
else if (child.type === 'namespace_import') {
const local = child.namedChildren[0];
if (local) declare(scope, local, { kind: sdk ? 'sdk-namespace' : 'unknown', typeOnly });
} else if (child.type === 'named_imports') {
for (const specifier of child.namedChildren) {
const imported = specifier.childForFieldName('name');
const local = specifier.childForFieldName('alias') ?? imported;
if (local)
declare(scope, local, {
kind: sdk && imported?.text === 'McpServer' ? 'sdk' : 'unknown',
typeOnly: typeOnly || specifier.children.some((part) => part.type === 'type'),
});
}
}
}
} else if (node.type === 'variable_declarator') {
if (name) {
const target = node.parent?.type === 'variable_declaration' ? variableScope(scope) : scope;
for (const bindingName of patternNames(name)) {
declare(target, bindingName, {
kind: 'variable',
immutable: node.parent?.childForFieldName('kind')?.type === 'const',
...(name.type === 'identifier'
? { value: node.childForFieldName('value') ?? undefined }
: {}),
});
}
}
} else if (node.type === 'catch_clause') {
const parameter = node.childForFieldName('parameter');
if (parameter) for (const bindingName of patternNames(parameter)) declare(scope, bindingName);
} else if (node.type === 'for_in_statement') {
const left = node.childForFieldName('left');
const kind = node.childForFieldName('kind');
if (left && kind) {
const target = kind.type === 'var' ? variableScope(scope) : scope;
for (const bindingName of patternNames(left)) declare(target, bindingName);
} else if (left) writes.push(left);
} else if (node.type === 'type_parameter') {
if (name) declare(scope, name);
}
if (node.type === 'call_expression') calls.push(node);
if (node.type === 'assignment_expression' || node.type === 'augmented_assignment_expression') {
const left = node.childForFieldName('left');
if (left) writes.push(left);
} else if (
node.type === 'update_expression' ||
(node.type === 'unary_expression' && node.children.some((child) => child.type === 'delete'))
) {
const argument = node.childForFieldName('argument');
if (argument) writes.push(argument);
}
for (let index = node.namedChildCount - 1; index >= 0; index--) {
pending.push({ node: node.namedChild(index)!, scope });
}
}
// Resolve writes after declarations so later declarations also shadow outer names.
while (writes.length) {
let target = writes.pop()!;
const scope = scopes.get(target.id)!;
const members: Array<string | null> = [];
while (target.type === 'member_expression' || target.type === 'subscript_expression') {
const object = target.childForFieldName('object');
if (!object) break;
const property = target.childForFieldName('property');
const index = target.childForFieldName('index');
members.push(property ? propertyName(property) : index ? plainString(index) : null);
target = object;
}
// Nested member targets must pass the same guard as direct property writes.
for (const name of patternNames(target, (member) => writes.push(member))) {
const binding = lookup(scope, name.text);
// Lifecycle callbacks and other known properties do not replace the receiver
// or its registration methods. Unknown keys and constructor mutations remain unsafe.
if (
binding?.kind !== 'sdk' &&
binding?.kind !== 'sdk-namespace' &&
members.length > 0 &&
members.every((member) => member !== null) &&
!['tool', 'registerTool', '__proto__'].includes(members[members.length - 1]!)
)
continue;
if (binding) binding.invalid = true;
}
}
return { scopes, calls };
}
function sdkBinding(node: SyntaxNode, scope: Scope, forType = false): boolean {
let kind: Binding['kind'] = 'sdk';
if (node.type === (forType ? 'nested_type_identifier' : 'member_expression')) {
const namespace = node.childForFieldName(forType ? 'module' : 'object');
const member = node.childForFieldName(forType ? 'name' : 'property');
if (namespace?.type !== 'identifier' || member?.text !== 'McpServer') return false;
node = namespace;
kind = 'sdk-namespace';
}
if (node.type !== 'identifier' && node.type !== 'type_identifier') return false;
const binding = lookup(scope, node.text);
return binding?.kind === kind && !binding.invalid && (forType || !binding.typeOnly);
}
function sdkReceiver(node: SyntaxNode, scope: Scope, scopes: ReadonlyMap<number, Scope>): boolean {
if (node.type !== 'identifier') return false;
const binding = lookup(scope, node.text);
if (!binding || binding.invalid) return false;
if (binding.kind === 'parameter' && binding.type) {
return sdkBinding(binding.type, binding.scope, true);
}
const value = binding.value;
if (binding.kind !== 'variable' || value?.type !== 'new_expression') return false;
if (value.endIndex > node.startIndex && variableScope(binding.scope) === variableScope(scope))
return false;
const constructor = value.childForFieldName('constructor');
return constructor !== null && sdkBinding(constructor, scopes.get(value.id)!);
}
/** An unknown later property can replace description; a later explicit property restores proof. */
function descriptionFromConfig(config: SyntaxNode): string {
let description = '';
if (config.type !== 'object') return description;
for (const child of config.namedChildren) {
if (child.type === 'comment') continue;
const key = child.childForFieldName('key') ?? child.childForFieldName('name');
const name =
child.type === 'shorthand_property_identifier' ? child.text : key && propertyName(key);
if (child.type === 'pair' && name === 'description') {
const value = child.childForFieldName('value');
description = value ? (plainString(value) ?? '') : '';
} else if (!name || name === 'description') {
description = '';
}
}
return description;
}
function handlerNodeId(
node: SyntaxNode,
scope: Scope,
callableBindings: ReadonlyMap<number, string> | undefined,
): string | undefined {
if (node.type !== 'identifier') return undefined;
const binding = lookup(scope, node.text);
if (!binding || binding.invalid) return undefined;
if (binding.kind === 'variable') {
const value = binding.value;
if (
!binding.immutable ||
!value ||
(value.type !== 'arrow_function' && value.type !== 'function_expression')
)
return undefined;
if (value.endIndex > node.startIndex && variableScope(binding.scope) === variableScope(scope))
return undefined;
} else if (binding.kind !== 'function') return undefined;
return callableBindings?.get(binding.name.id);
}
/** Direct SDK registrations only; no wrapper, alias-chain or runtime-value inference. */
export function extractToolDefinitions(
tree: Parser.Tree,
filePath: string,
lineOffset = 0,
callableBindings?: ReadonlyMap<number, string>,
): ExtractedToolDef[] {
// Ordinary files need no lexical walk; every supported receiver originates here.
const importsSdk = tree.rootNode.namedChildren.some((node) => {
if (node.type !== 'import_statement') return false;
const source = node.childForFieldName('source');
return source !== null && SDK_MODULES.has(plainString(source) ?? '');
});
if (!importsSdk) return [];
const { scopes, calls } = collectBindings(tree.rootNode);
const definitions: ExtractedToolDef[] = [];
for (const call of calls) {
const callee = call.childForFieldName('function');
if (call.hasError || callee?.type !== 'member_expression') continue;
const receiver = callee.childForFieldName('object');
const method = callee.childForFieldName('property');
if (
!receiver ||
method?.type !== 'property_identifier' ||
(method.text !== 'registerTool' && method.text !== 'tool') ||
!sdkReceiver(receiver, scopes.get(call.id)!, scopes)
)
continue;
const args =
call
.childForFieldName('arguments')
?.namedChildren.filter((child) => child.type !== 'comment') ?? [];
if (args.some((arg) => arg.type === 'spread_element')) continue;
if (method.text === 'registerTool' ? args.length !== 3 : args.length < 2 || args.length > 5)
continue;
const toolName = plainString(args[0]);
if (toolName === null) continue;
const description =
method.text === 'registerTool'
? descriptionFromConfig(args[1])
: args.length > 2
? (plainString(args[1]) ?? '')
: '';
const handler = handlerNodeId(args[args.length - 1], scopes.get(call.id)!, callableBindings);
definitions.push({
filePath,
toolName,
description,
lineNumber: call.startPosition.row + 1 + lineOffset,
...(handler !== undefined ? { handlerNodeId: handler } : {}),
allowFileFallback: false,
});
}
return definitions;
}

1
gitnexus/src/core/ingestion/pipeline-phases/processes.ts
View file

@ -323,6 +323,7 @@ export const processesPhase: PipelinePhase<ProcessesOutput> = {
const toolsByHandlerId = new Map<string, string[]>();
const toolsWithoutHandlerByFile = new Map<string, string[]>();
for (const td of toolDefs) {
if (!td.handlerNodeId && td.allowFileFallback === false) continue;
const key = td.handlerNodeId ?? td.filePath;
const targetMap = td.handlerNodeId ? toolsByHandlerId : toolsWithoutHandlerByFile;
let list = targetMap.get(key);

15
gitnexus/src/core/ingestion/pipeline-phases/routes.ts
View file

@ -14,7 +14,7 @@
import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
import { getPhaseOutput } from './types.js';
import type { ParseOutput } from './parse.js';
import { isBladeTemplateFilename } from 'gitnexus-shared';
import { isTemplateRouteCandidate } from '../utils/template-file.js';
import { nextjsFileToRouteURL, normalizeFetchURL } from '../route-extractors/nextjs.js';
import { expoFileToRouteURL } from '../route-extractors/expo.js';
import { phpFileToRouteURL } from '../route-extractors/php.js';
@ -41,6 +41,8 @@ import { readFileContents } from '../filesystem-walker.js';
import { isDev } from '../utils/env.js';
import { logger } from '../../logger.js';
export { isTemplateRouteCandidate } from '../utils/template-file.js';
const EXPO_NAV_PATTERNS = [
/router\.(push|replace|navigate)\(\s*['"`]([^'"`]+)['"`]/g,
/<Link\s+[^>]*href=\s*['"`]([^'"`]+)['"`]/g,
@ -121,17 +123,6 @@ function hasRouteParameters(routeUrl: string): boolean {
return /\{[^}]+\}/.test(routeUrl);
}
export const isTemplateRouteCandidate = (filePath: string): boolean => {
const normalized = filePath.replace(/\\/g, '/').toLowerCase();
return (
normalized.endsWith('.html') ||
normalized.endsWith('.htm') ||
normalized.endsWith('.ejs') ||
normalized.endsWith('.hbs') ||
isBladeTemplateFilename(normalized)
);
};
export function extractTemplateStaticFetchCalls(
filePath: string,
content: string,

2
gitnexus/src/core/ingestion/pipeline-phases/tools.ts
View file

@ -22,6 +22,7 @@ export interface ToolDef {
filePath: string;
description: string;
handlerNodeId?: string;
allowFileFallback?: false;
}
export interface ToolsOutput {
@ -51,6 +52,7 @@ export const toolsPhase: PipelinePhase<ToolsOutput> = {
filePath: td.filePath,
description: td.description,
...(handlerNodeId !== undefined ? { handlerNodeId } : {}),
...(td.allowFileFallback === false ? { allowFileFallback: false as const } : {}),
});
}

54
gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts
View file

@ -26,6 +26,7 @@
import type Parser from 'tree-sitter';
import { goImportPackageName } from '../languages/go/import-package-name.js';
import { GoRouteBindings, type GoRouteBinding } from '../languages/go/route-bindings.js';
import { stringLiteral } from './go-shared.js';
import { normalizeExtractedRoutePath } from './route-path.js';
import type { SyntaxNode } from 'tree-sitter';
import type { ExtractedDecoratorRoute, RouteHandlerReceiver } from '../workers/parse-worker.js';
@ -58,59 +59,6 @@ interface Framework {
const FUNCTION_TYPE_LIST = ['function_declaration', 'method_declaration', 'func_literal'];
const FUNCTION_TYPES: ReadonlySet<string> = new Set(FUNCTION_TYPE_LIST);
function stringLiteral(node: SyntaxNode | null | undefined): string | null {
if (!node || node.hasError) return null;
const body = node.text.slice(1, -1);
// Go discards carriage returns in raw strings, including CRLF source files.
if (node.type === 'raw_string_literal') return body.replace(/\r/g, '');
if (node.type !== 'interpreted_string_literal') return null;
if (!body.includes('\\')) return body;
const simple: Readonly<Record<string, string>> = {
a: '\x07',
b: '\b',
f: '\f',
n: '\n',
r: '\r',
t: '\t',
v: '\v',
'\\': '\\',
'"': '"',
};
const chunks: Buffer[] = [];
const tokens =
/\\(?:[abfnrtv\\"]|[0-7]{3}|x[\da-fA-F]{2}|u[\da-fA-F]{4}|U[\da-fA-F]{8})|[^\\"\n]+/g;
let consumed = 0;
for (const match of body.matchAll(tokens)) {
if (match.index !== consumed) return null;
const token = match[0];
consumed += token.length;
if (!token.startsWith('\\')) {
chunks.push(Buffer.from(token));
} else if (simple[token[1]] !== undefined) {
chunks.push(Buffer.from(simple[token[1]]));
} else {
const octal = /[0-7]/.test(token[1]);
const value = Number.parseInt(token.slice(octal ? 1 : 2), octal ? 8 : 16);
if (octal || token[1] === 'x') {
// Octal and hex escapes encode bytes, not Unicode code points.
if (value > 255) return null;
chunks.push(Buffer.from([value]));
} else {
if (value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff)) return null;
chunks.push(Buffer.from(String.fromCodePoint(value)));
}
}
}
if (consumed !== body.length) return null;
try {
// Arbitrary non-UTF-8 Go byte strings cannot be represented losslessly in a URL.
return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
} catch {
return null;
}
}
/** The framework this file routes with, when exactly one is imported. */
function readImports(root: SyntaxNode): {
readonly framework: Framework | null;

75
gitnexus/src/core/ingestion/route-extractors/go-shared.ts Normal file
View file

@ -0,0 +1,75 @@
import type { SyntaxNode } from 'tree-sitter';
/**
* Go string-literal decoding shared by the Go route extractors on both
* layers: the ingestion extractor (`go-gin-echo.ts`, Strategy A) and the
* group-mode HTTP plugin (`group/extractors/http-patterns/go.ts`,
* Strategy B). Both sides must produce the SAME text for a route literal,
* or the same route lands under two different contract ids that never
* collide in the merge — a wrong-path duplicate that survives alongside
* the graph's correct entry.
*
* Go's semantics, per `strconv.Unquote`:
* - interpreted (`"…"`) strings decode escapes (`\n`, `\x2f`, `ሴ`,
* `\101`, …); hex and octal escapes encode BYTES, not code points;
* - raw (`` `…` ``) strings have no escapes (a backslash is literal),
* and Go discards carriage returns in them, including CRLF source files;
* - a string that cannot be decoded to valid UTF-8 text (invalid escape,
* non-UTF-8 bytes) returns null — callers decline instead of guessing,
* since a URL cannot carry those bytes losslessly.
*
* Nodes that are not string literals (an identifier prefix, a rune
* literal, an errored subtree) also return null.
*/
export function stringLiteral(node: SyntaxNode | null | undefined): string | null {
if (!node || node.hasError) return null;
const body = node.text.slice(1, -1);
// Go discards carriage returns in raw strings, including CRLF source files.
if (node.type === 'raw_string_literal') return body.replace(/\r/g, '');
if (node.type !== 'interpreted_string_literal') return null;
if (!body.includes('\\')) return body;
const simple: Readonly<Record<string, string>> = {
a: '\x07',
b: '\b',
f: '\f',
n: '\n',
r: '\r',
t: '\t',
v: '\v',
'\\': '\\',
'"': '"',
};
const chunks: Buffer[] = [];
const tokens =
/\\(?:[abfnrtv\\"]|[0-7]{3}|x[\da-fA-F]{2}|u[\da-fA-F]{4}|U[\da-fA-F]{8})|[^\\"\n]+/g;
let consumed = 0;
for (const match of body.matchAll(tokens)) {
if (match.index !== consumed) return null;
const token = match[0];
consumed += token.length;
if (!token.startsWith('\\')) {
chunks.push(Buffer.from(token));
} else if (simple[token[1]] !== undefined) {
chunks.push(Buffer.from(simple[token[1]]));
} else {
const octal = /[0-7]/.test(token[1]);
const value = Number.parseInt(token.slice(octal ? 1 : 2), octal ? 8 : 16);
if (octal || token[1] === 'x') {
// Octal and hex escapes encode bytes, not Unicode code points.
if (value > 255) return null;
chunks.push(Buffer.from([value]));
} else {
if (value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff)) return null;
chunks.push(Buffer.from(String.fromCodePoint(value)));
}
}
}
if (consumed !== body.length) return null;
try {
// Arbitrary non-UTF-8 Go byte strings cannot be represented losslessly in a URL.
return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
} catch {
return null;
}
}

3
gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts
View file

@ -1235,6 +1235,9 @@ export interface ScopeResolver {
readonly isCallableVisibleFromCaller?: (ctx: {
readonly callerParsed: ParsedFile;
readonly candidate: SymbolDefinition;
/** Arity of the actual call, when known. A visibility veto must not
* infer applicability from a name match alone. */
readonly callArity?: number;
/** Caller's enclosing scope id. Languages that gate visibility on
* caller scope (e.g. C++ two-phase template lookup) consult it;
* others ignore. Optional so existing implementations stay valid. */

9
gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts
View file

@ -84,12 +84,7 @@ export function emitFreeCallFallback(
* appended to its reason. See `ScopeResolver.markConstructionSites`. */
readonly markConstructionSites?: boolean;
readonly isFileLocalDef?: (def: SymbolDefinition) => boolean;
readonly isCallableVisibleFromCaller?: (ctx: {
readonly callerParsed: ParsedFile;
readonly candidate: SymbolDefinition;
readonly callerScope?: ScopeId;
readonly scopes?: ScopeResolutionIndexes;
}) => boolean;
readonly isCallableVisibleFromCaller?: ScopeResolver['isCallableVisibleFromCaller'];
readonly resolveAdlCandidates?: (
site: {
readonly name: string;
@ -620,6 +615,7 @@ export function emitFreeCallFallback(
options.isCallableVisibleFromCaller!({
callerParsed: parsed,
candidate,
callArity: site.arity,
callerScope: site.inScope,
scopes,
})
@ -698,6 +694,7 @@ export function emitFreeCallFallback(
!options.isCallableVisibleFromCaller({
callerParsed: parsed,
candidate: fnDef,
callArity: site.arity,
callerScope: site.inScope,
scopes,
})

13
gitnexus/src/core/ingestion/utils/template-file.ts Normal file
View file

@ -0,0 +1,13 @@
import { isBladeTemplateFilename } from 'gitnexus-shared';
/** Templates whose URLs and fetches can contribute route relationships to the graph. */
export const isTemplateRouteCandidate = (filePath: string): boolean => {
const normalized = filePath.replace(/\\/g, '/').toLowerCase();
return (
normalized.endsWith('.html') ||
normalized.endsWith('.htm') ||
normalized.endsWith('.ejs') ||
normalized.endsWith('.hbs') ||
isBladeTemplateFilename(normalized)
);
};

25
gitnexus/src/core/ingestion/workers/parse-worker.ts
View file

@ -439,6 +439,8 @@ export interface ExtractedToolDef {
description: string;
lineNumber: number;
handlerNodeId?: string;
/** Unresolved registrations must not inherit unrelated same-file flows. */
allowFileFallback?: false;
}
export interface ExtractedORMQuery {
@ -1685,6 +1687,7 @@ const processFileGroup = (
// node id → graph node id for classes THIS file's capture loop materialized.
// Keyed by in-memory AST identity (never persisted); filled below.
const classOwnersByNodeId = new Map<number, string>();
const callableBindings = new Map<number, string>();
// #2687: ONE pass over `matches` yields both suppression sets — the
// definition-name claims by rank (callable > Property > value), so the dedup
@ -3123,6 +3126,11 @@ const processFileGroup = (
}),
});
// Keep actual emitted identities; providers must not reconstruct graph IDs.
if (nameNode && (nodeLabel === 'Function' || nodeLabel === 'Method')) {
callableBindings.set(nameNode.id, nodeId);
}
// enclosingClassId already computed above (before nodeId generation)
const ownerId = enclosingClassId ?? objectLiteralOwnerInfo?.ownerId;
@ -3225,6 +3233,23 @@ const processFileGroup = (
}
}
if (provider.extractToolDefinitions) {
// Distinct lexical declarations can share a graph ID (for example, sibling
// block-scoped functions). Such IDs cannot prove which handler owns a tool.
const seenCallableIds = new Set<string>();
const ambiguousCallableIds = new Set<string>();
for (const nodeId of callableBindings.values()) {
if (seenCallableIds.has(nodeId)) ambiguousCallableIds.add(nodeId);
seenCallableIds.add(nodeId);
}
for (const [bindingId, nodeId] of callableBindings) {
if (ambiguousCallableIds.has(nodeId)) callableBindings.delete(bindingId);
}
result.toolDefs.push(
...provider.extractToolDefinitions(tree, file.path, lineOffset, callableBindings),
);
}
// Extract framework routes via provider detection (e.g., Laravel routes.php)
if (provider.isRouteFile?.(file.path)) {
const extractedRoutes = extractLaravelRoutes(tree, file.path);

6
gitnexus/src/core/lbug/csv-generator.ts
View file

@ -110,9 +110,13 @@ export const sanitizeUTF8 = (str: string): string => {
};
export const escapeCSVField = (value: string | number | undefined | null): string => {
if (value === undefined || value === null) return '""';
if (value === undefined || value === null) return '';
let str = String(value);
str = sanitizeUTF8(str);
// Preserve the NULL meaning of absent strings from the 0.18.3 writer.
// Newer LadybugDB readers retain a quoted empty field as a STRING value;
// it must stay unquoted or unresolved destination addresses can join.
if (str.length === 0) return '';
return `"${str.replace(/"/g, '""')}"`;
};

97
gitnexus/src/core/lbug/lbug-adapter.ts
View file

@ -1101,28 +1101,78 @@ export type LbugProgressCallback = (message: string) => void;
/**
* Run a COPY, retrying once with IGNORE_ERRORS=true (which skips row-level
* errors) on first failure. On a second failure, hand the RAW retry error to
* `onError` — each call site formats + slices its own message (#2226 F5: node
* COPY slices to 200 chars and throws; relationship COPY slices to 80 and warns,
* so the helper must not pre-format and lose that distinction). `onError` may
* throw to propagate the failure.
* errors) on first failure. Log the original failure and native COPY/warning
* receipts even when the retry succeeds. Node COPY requires every row; a
* skipped-node receipt is a failure. Call sites retain their own message
* limits and relationship fallback policy.
*/
const copyCsvWithRetry = async (
targetConn: lbug.Connection,
copyQuery: string,
onError: (retryErr: unknown) => void,
expectedRows?: number,
): Promise<void> => {
try {
await queryAndDrain(targetConn, copyQuery);
} catch {
} catch (firstError) {
logger.warn(
{ err: firstError, copyQuery },
'First COPY failure; retrying with IGNORE_ERRORS=true',
);
try {
const retryQuery = copyQuery.replace(
'auto_detect=false)',
'auto_detect=false, IGNORE_ERRORS=true)',
);
await queryAndDrain(targetConn, retryQuery);
// Keep COPY and its connection-local warning receipt in one critical
// section. Only project diagnostics, never skipped_line_or_record: that
// column contains source text. Warnings are retained at a bounded native
// limit, so their count is a lower bound, not the exact skipped total.
const retry = async () => {
await drainQueryResult(await targetConn.query('CALL CLEAR_WARNINGS()'));
const result = await readQueryRows(await targetConn.query(retryQuery));
const warnings = await readQueryRows(
await targetConn.query('CALL SHOW_WARNINGS() RETURN message, file_path, line_number'),
);
// The native warning limit can be zero; warning rows alone cannot
// prove that every CSV row landed. Node COPY exposes its copied count
// in the result receipt even when warning retention is disabled.
const countReceipt = result
.map((row) => String(row.result ?? ''))
.map((message) => /^(\d+) tuples have been copied/.exec(message))
.find(Boolean);
const copiedRows = countReceipt ? Number(countReceipt[1]) : undefined;
logger.warn(
{
copyQuery,
copyResult: result,
expectedRows,
copiedRows,
skippedRows:
expectedRows !== undefined && copiedRows !== undefined
? Math.max(0, expectedRows - copiedRows)
: undefined,
retainedWarnings: warnings.length,
warningSamples: warnings.slice(0, 5),
},
'COPY retry completed; retained warnings describe skipped rows (a lower bound)',
);
if (expectedRows !== undefined && (copiedRows !== expectedRows || warnings.length > 0)) {
throw new Error(
`COPY retry skipped rows or could not verify a complete node load ` +
`(copied ${copiedRows ?? 'unknown'} of ${expectedRows}; ${warnings.length} retained warning(s))`,
);
}
};
await (isSharedSingletonConn(targetConn) ? withConnLock(retry) : retry());
} catch (retryErr) {
onError(retryErr);
const firstMessage = firstError instanceof Error ? firstError.message : String(firstError);
const retryMessage = retryErr instanceof Error ? retryErr.message : String(retryErr);
onError(
new Error(`COPY retry failed: ${retryMessage}; first failure: ${firstMessage}`, {
cause: retryErr,
}),
);
}
}
};
@ -1192,17 +1242,22 @@ const copyNodeCSVs = async (
if (!(await stagingCsvExists(csvPath))) throw missingStagingCsvError(table, csvPath, rows);
const copyQuery = getCopyQuery(table, normalizeCopyPath(csvPath));
await copyCsvWithRetry(targetConn, copyQuery, (retryErr) => {
const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
// Pool exhaustion gets a remedy (#2631): the raw binder text gives the
// operator nothing to act on, and on non-4K-page hosts (Ascend aarch64,
// Apple Silicon) the pool bills up to pageSize/4KiB x faster than the
// sizing was calibrated for — name the knob and the mechanism.
const remedy = bufferPoolExhaustionRemedy(retryMsg);
throw new Error(
`COPY failed for ${table}: ${retryMsg.slice(0, 200)}${remedy ? ` ${remedy}` : ''}`,
);
});
await copyCsvWithRetry(
targetConn,
copyQuery,
(retryErr) => {
const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
// Pool exhaustion gets a remedy (#2631): the raw binder text gives the
// operator nothing to act on, and on non-4K-page hosts (Ascend aarch64,
// Apple Silicon) the pool bills up to pageSize/4KiB x faster than the
// sizing was calibrated for — name the knob and the mechanism.
const remedy = bufferPoolExhaustionRemedy(retryMsg);
throw new Error(
`COPY failed for ${table}: ${retryMsg.slice(0, 200)}${remedy ? ` ${remedy}` : ''}`,
);
},
rows,
);
}
};
@ -3989,6 +4044,7 @@ export const buildFtsQueryCypher = (
* @param query - Search query string
* @param limit - Maximum results
* @param conjunctive - If true, all terms must match (AND); if false, any term matches (OR)
* @param missingIndex - Preserve the empty-result default, or propagate missing indexes for diagnostics
* @returns Array of { node properties, score }
*/
export const queryFTS = async (
@ -3997,6 +4053,7 @@ export const queryFTS = async (
query: string,
limit: number = 20,
conjunctive: boolean = false,
missingIndex: 'empty' | 'throw' = 'empty',
): Promise<
Array<{ nodeId: string; name: string; filePath: string; score: number; [key: string]: any }>
> => {
@ -4027,7 +4084,7 @@ export const queryFTS = async (
// NEW-6 — this used to be a bare `.includes('does not exist')` check
// that could not tell the two apart).
const message = e instanceof Error ? e.message : String(e);
if (classifyFtsQueryError(message) === 'missing-index') {
if (missingIndex === 'empty' && classifyFtsQueryError(message) === 'missing-index') {
return [];
}
throw e;

419
gitnexus/src/core/run-analyze.ts
View file

@ -36,7 +36,12 @@ import fs from 'fs/promises';
import { constants as fsConstants, existsSync } from 'node:fs';
import { randomUUID } from 'node:crypto';
import { retryRename } from '../storage/fs-atomic.js';
import { acquireIndexLock, requireExclusiveIndexLock } from '../storage/index-lock.js';
import {
acquireIndexLock,
requireExclusiveIndexLock,
sweepStagingArtifacts,
} from '../storage/index-lock.js';
import { resolveEmbeddingRecovery } from '../storage/embedding-recovery.js';
import { invalidateNodeWorkspacePackages } from './ingestion/import-resolvers/node-workspace-packages.js';
import {
logNameFallbackSummary,
@ -51,6 +56,7 @@ import {
import { summarizeUndecidedSatisfaction } from './ingestion/scope-resolution/undecided-satisfaction.js';
import { summarizeScopeExtractionFailures } from './ingestion/scope-resolution/scope-extraction-failures.js';
import type { KnowledgeGraph } from './graph/types.js';
import { reconcileGraphNodeIdentities } from './incremental/write-reconciliation.js';
import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
import {
initLbug,
@ -128,6 +134,7 @@ import { resolveFtsVersionPair } from './lbug/vendored-extension-path.js';
import {
startWalCheckpointDriver,
checkpointOnce,
isManualCheckpointEnabled,
type WalCheckpointDriver,
} from './lbug/wal-checkpoint-driver.js';
import {
@ -1285,6 +1292,8 @@ export async function runFullAnalysis(
const log = (msg: string) => callbacks.onLog?.(stripControlCharacters(msg));
const acquireOpts = {
log,
// Resolve and validate the canonical slot under the lock before cleanup.
sweep: false,
onWaitStart: () =>
callbacks.onProgress('lock', 0, 'Waiting for another analyze to finish on this index…'),
};
@ -1343,6 +1352,7 @@ export async function runFullAnalysis(
}
const flatShared = writeTarget.placement.branch ? undefined : writeTarget.sharedStore;
if (flatShared) await seedSharedSlot(flatShared, repoPath, log);
sweepStagingArtifacts(writeTarget.metaDir, log);
const slotToLeave = options.noShare ? await optedInSlotToLeave(repoPath) : undefined;
const result = await runFullAnalysisInner(
repoPath,
@ -1840,7 +1850,13 @@ async function runFullAnalysisInner(
decision = decideEmbeddingResume(checkpoint, embeddingIdentityForRun, resumeOptions);
}
if (decision.action === 'abort') throw new Error(decision.error);
log(decision.log);
log(
decision.action === 'resume' && checkpoint.recovery
? `Previous analyze recorded an embedding checkpoint (${checkpoint.nodesProcessed}/` +
`${checkpoint.totalNodes} nodes); validating staged vectors before retrying ` +
`${decision.pendingNodeIds.size} pending node(s).`
: decision.log,
);
if (options.dropEmbeddings) {
// --drop-embeddings has always implied a rebuild here; the decision only
// covers the marker.
@ -2669,6 +2685,74 @@ async function runFullAnalysisInner(
}
}
// A checkpoint's pending decision and its paid, complete vectors are
// independent: --force discards the former but can still reuse the latter.
// Select only the explicitly referenced generation, never an orphan by age.
const stagedRecovery = resolveEmbeddingRecovery(metaDir, existingMeta?.embeddingCheckpoint);
const stagedCheckpoint = existingMeta?.embeddingCheckpoint;
const inheritedUnsafeNodeIds = new Set([
...pendingEmbeddingNodeIds,
...(stagedRecovery?.unsafeNodeIds ?? []),
]);
if (shouldLoadCache && !options.dropEmbeddings && stagedRecovery && stagedCheckpoint) {
if (!embeddingIdentityForRun) {
const { resolveEmbeddingIdentity } = await import('./embeddings/embedding-identity.js');
embeddingIdentityForRun = resolveEmbeddingIdentity();
}
const marker = stagedCheckpoint;
const matchesIdentity =
marker.model === embeddingIdentityForRun.model &&
marker.dimensions === embeddingIdentityForRun.dimensions &&
marker.provider === embeddingIdentityForRun.provider;
if (matchesIdentity && stagedRecovery.schemaFingerprint === SCHEMA_FINGERPRINT) {
// A force-discarded pending decision must not turn a known incomplete
// inherited group into a reusable cache merely because its hash matches.
if (inheritedUnsafeNodeIds.size > 0) {
const rows = cachedSnapshot.rows.filter((row) => !inheritedUnsafeNodeIds.has(row.nodeId));
cachedSnapshot = {
...cachedSnapshot,
rows,
embeddingNodeIds: new Set(rows.map((row) => row.nodeId)),
};
}
let recovered: CachedEmbeddingsSnapshot | undefined;
try {
const { recoverStagedEmbeddings, mergeRecoveredEmbeddings } =
await import('./embeddings/staged-embedding-recovery.js');
recovered = await recoverStagedEmbeddings(stagedRecovery.dbPath, {
dimensions: embeddingIdentityForRun.dimensions,
excludedNodeIds: stagedRecovery.unsafeNodeIds,
});
const liveCacheDims = snapshotEmbeddingDims(cachedSnapshot);
if (liveCacheDims !== undefined && liveCacheDims !== embeddingIdentityForRun.dimensions) {
log(
`Embedding dimensions changed (${liveCacheDims}d -> ` +
`${embeddingIdentityForRun.dimensions}d), discarding published cache`,
);
discardCachedEmbeddings();
}
if (recovered.rows.length > 0) {
const merged = mergeRecoveredEmbeddings(cachedSnapshot, recovered);
disposeEmbeddingSpill(cachedSnapshot.spill);
adoptCachedEmbeddings(merged);
}
log(
`Recovered ${recovered.rows.length} complete staged embedding chunk(s) ` +
`for ${recovered.embeddingNodeIds.size} node(s); unchanged content can reuse them.`,
);
} catch (err) {
log(
`Warning: could not recover staged embeddings (${(err as Error).message}); ` +
'the retry will regenerate missing chunks.',
);
} finally {
disposeEmbeddingSpill(recovered?.spill);
}
} else {
log('Staged embedding identity or schema changed; its vectors will not be reused.');
}
}
// ── Load incremental parse cache ──────────────────────────────────
// Content-addressed: `--force` reuses parser shards; `useParseCache: false`
// stages a new generation under a run-unique parse-rebuild.* dir and publishes
@ -2854,7 +2938,7 @@ async function runFullAnalysisInner(
// (Bugbot review on PR #1479: a prediction that flipped post-pipeline
// could skip the embedding cache load and then take the full-rebuild
// path, silently losing embeddings).
const isIncremental =
const incrementalEligible =
!options.force &&
!!existingMeta &&
// Belt and braces, not a second gate: the guard above already set `force`
@ -2867,6 +2951,13 @@ async function runFullAnalysisInner(
repoHasGit &&
allFilePaths.length > 0;
// Select a full build before any selective mutation when the operator has
// disabled the checkpoint needed to certify an incremental publication.
const isIncremental = incrementalEligible && isManualCheckpointEnabled();
if (incrementalEligible && !isIncremental) {
log('Manual WAL checkpoints are disabled; switching to a full DB write before mutation.');
}
const hashDiff = isIncremental
? diffFileHashes(newFileHashes, existingMeta!.fileHashes)
: undefined;
@ -3112,6 +3203,24 @@ async function runFullAnalysisInner(
// collapse check compares the whole in-memory graph against the whole DB,
// which is only a like-for-like comparison on a full rebuild.
let wroteChangedSubgraphOnly = false;
const markIncrementalGraphVerification = async (): Promise<void> => {
if (buildPath !== lbugPath) return;
const latest = await loadMeta(metaDir);
if (!latest?.incrementalInProgress) {
throw new Error('Cannot certify incremental graph without its dirty metadata marker.');
}
// A failed or aborted identity scan is a graph failure. FTS-only repair
// and FTS crash recovery must not clear it while retaining these rows.
await saveMeta(metaDir, {
...latest,
incrementalInProgress: {
...latest.incrementalInProgress,
phase: 'graph-reconciliation',
updatedAt: Date.now(),
checkpointSucceeded: false,
},
});
};
let incrementalFtsRebuildTables: Set<string> | undefined;
if (isIncremental && hashDiff) {
// ── Incremental DB writeback ───────────────────────────────────
@ -3163,6 +3272,8 @@ async function runFullAnalysisInner(
phase: string,
extra: Partial<NonNullable<RepoMeta['incrementalInProgress']>> = {},
): Promise<void> => {
// Do not stamp live metadata while writing a staging database.
if (buildPath !== lbugPath) return;
await saveMeta(metaDir, {
...existingMeta!,
incrementalInProgress: {
@ -3906,6 +4017,14 @@ async function runFullAnalysisInner(
'Continuing; recovery will treat the graph-boundary checkpoint as unsuccessful.',
);
}
if (wroteChangedSubgraphOnly) {
await markIncrementalGraphVerification();
await reconcileGraphNodeIdentities(
pipelineResult.graph,
executeQuery,
'post-COPY/checkpoint',
);
}
if (shouldStampFtsDirtyPhase(ftsWritePlan)) {
// Lift the prior-meta precondition: a first-ever in-place run (Windows
// full rebuild, or any in-place incremental) must stamp too. Staging
@ -4002,6 +4121,7 @@ async function runFullAnalysisInner(
? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)
: undefined,
});
if (wroteChangedSubgraphOnly) await markIncrementalGraphVerification();
if (ftsResult.ok) {
progress('fts', 90, 'Search indexes ready');
} else if (ftsFailureIsFatal(ftsResult.failureClass, useAtomicSwap)) {
@ -4054,6 +4174,12 @@ async function runFullAnalysisInner(
progress('fts', 90, 'Search indexes skipped (FTS unavailable)');
}
if (wroteChangedSubgraphOnly) {
// FTS has returned. Later embedding/finalization failures must require
// graph recovery, since post-FTS node identities are not yet certified.
await markIncrementalGraphVerification();
}
// ── Phase 3.5: Re-insert cached embeddings ────────────────────────
// Runs on BOTH the full-rebuild path and the incremental path:
// - Full rebuild / escalated write: DB was wiped, every cached row
@ -4428,6 +4554,7 @@ async function runFullAnalysisInner(
semanticMode = vectorIndexReady ? 'vector-index' : 'exact-scan';
}
let stagedCheckpointEmbeddingCount: number | undefined;
if (!embeddingSkipped) {
const { isHttpMode } = await import('./embeddings/http-client.js');
const httpMode = isHttpMode();
@ -4442,6 +4569,16 @@ async function runFullAnalysisInner(
embeddingIdentityForRun = resolveEmbeddingIdentity();
}
const embeddingIdentity = embeddingIdentityForRun;
const stagedRecoveryEnabled = useAtomicSwap && isManualCheckpointEnabled();
if (useAtomicSwap && !stagedRecoveryEnabled) {
log(
'Manual WAL checkpoints are disabled; new staged work cannot be recovered after interruption. ' +
'Any previous durable recovery source is retained until publication.',
);
}
const unsafeRecoveryNodeIds = new Set([...inheritedUnsafeNodeIds, ...restoreFailedNodeIds]);
let activeWindowNodeIds: string[] = [];
let recoveryGenerationDurable = false;
// Build a Map<nodeId, contentHash> from cached embeddings for incremental mode
let existingEmbeddings: Map<string, string> | undefined;
if (cachedSnapshot.embeddingNodeIds.size > 0) {
@ -4478,11 +4615,10 @@ async function runFullAnalysisInner(
// /api/embed checkpoint writer in server/api.ts already uses, which also
// keeps a concurrent writer's update from being reverted by a stale
// snapshot) and replace ONLY `embeddingCheckpoint` — plus
// `stats.embeddings` when the caller actually MEASURED the live count
// (the post-window `onCheckpoint`). The window-start callback passes
// nothing: restating the previous run's count there both re-published a
// stale number and clobbered the live count a preceding `onCheckpoint`
// had just written.
// `stats.embeddings` when the caller actually MEASURED the published
// index (the post-window `onCheckpoint` on an in-place build). A staging
// build's count is not published until the atomic swap succeeds. The
// window-start callback passes nothing, preserving the latest count.
const saveEmbeddingCheckpoint = async (
checkpoint: {
nodesProcessed: number;
@ -4492,7 +4628,18 @@ async function runFullAnalysisInner(
pendingNodeIds: string[],
embeddings?: number,
): Promise<void> => {
if (embeddings !== undefined && buildPath !== lbugPath) {
stagedCheckpointEmbeddingCount = embeddings;
}
const latestMeta = (await loadMeta(metaDir)) ?? existingMeta;
// An in-place write or manual-checkpoint opt-out cannot create a new
// recoverable staged generation. Keep the complete previous receipt:
// updated progress or unsafe nodes would describe different source bytes.
const preservedRecoveryCheckpoint =
!stagedRecoveryEnabled &&
resolveEmbeddingRecovery(metaDir, latestMeta?.embeddingCheckpoint)
? latestMeta?.embeddingCheckpoint
: undefined;
// First-ever analyze of this repo: no meta exists on disk yet (the
// pre-wipe dirty stamp only fires when one does). Mint the minimum
// RepoMeta requires, with `lastCommit: ''` — never `currentCommit` —
@ -4503,16 +4650,30 @@ async function runFullAnalysisInner(
lastCommit: '',
indexedAt: new Date().toISOString(),
};
const interrupted = mintInterruptedCheckpoint(
embeddingIdentity,
checkpoint,
pendingNodeIds,
);
await saveMeta(metaDir, {
...base,
...(embeddings === undefined ? {} : { stats: { ...base.stats, embeddings } }),
...(embeddings === undefined || buildPath !== lbugPath
? {}
: { stats: { ...base.stats, embeddings } }),
// Written by a run that is still IN FLIGHT — see the `kind` doc in
// repo-manager.ts.
embeddingCheckpoint: mintInterruptedCheckpoint(
embeddingIdentity,
checkpoint,
pendingNodeIds,
),
embeddingCheckpoint: preservedRecoveryCheckpoint ?? {
...interrupted,
...(stagedRecoveryEnabled
? {
recovery: {
stagingFile: path.basename(buildPath),
schemaFingerprint: SCHEMA_FINGERPRINT,
unsafeNodeIds: [...unsafeRecoveryNodeIds],
},
}
: {}),
},
});
};
@ -4535,7 +4696,21 @@ async function runFullAnalysisInner(
{
forceReembedNodeIds: pendingEmbeddingNodeIds,
onCheckpointWindowStart: async ({ nodeIds, ...checkpoint }) => {
const handoff = stagedRecoveryEnabled && !recoveryGenerationDurable;
if (handoff) {
if (!(await checkpointOnce())) {
throw new Error(
'Could not checkpoint restored embeddings before recovery handoff.',
);
}
recoveryGenerationDurable = true;
}
activeWindowNodeIds = nodeIds;
for (const id of nodeIds) unsafeRecoveryNodeIds.add(id);
await saveEmbeddingCheckpoint(checkpoint, nodeIds);
// Reclaim the old source only after the new durable generation's
// reference is saved. Later windows retain this same generation.
if (handoff) sweepStagingArtifacts(metaDir, log);
},
// ── The mid-run count is a DIAGNOSTIC, not a gate (#2790) ──────
// This used to run the count query bare. THIS callback's rejection
@ -4549,7 +4724,12 @@ async function runFullAnalysisInner(
// touch stats.embeddings" signal — so the checkpoint still lands,
// with whatever count is already on disk left alone.
onCheckpoint: async (checkpoint) => {
await checkpointOnce();
const durable = await checkpointOnce();
if (stagedRecoveryEnabled && !durable) {
throw new Error('Could not checkpoint the completed embedding window for recovery.');
}
for (const id of activeWindowNodeIds) unsafeRecoveryNodeIds.delete(id);
activeWindowNodeIds = [];
const measured = await measurePersistedEmbeddingCount(executeQuery);
if (measured.kind === 'unknown') {
log(
@ -4708,14 +4888,13 @@ async function runFullAnalysisInner(
// already written to disk: prior meta says 0, a clean run inserts
// embeddings and checkpoints the real count, the final probe is
// unavailable, and finalization carries the stale 0 forward while reporting
// success. `loadMeta` never throws (it returns null), and the checkpoint
// writer already re-reads the same way, so this is the same freshness
// discipline applied to the same field.
// success. For a staged build, use its last measured count only in the
// final meta, written after the swap; never publish it at a checkpoint.
const latestMetaForCount =
embeddingCount === undefined ? ((await loadMeta(metaDir)) ?? existingMeta) : undefined;
const persistedEmbeddingCount = resolvePersistedEmbeddingCount(
measuredEmbeddingCount,
latestMetaForCount?.stats?.embeddings,
stagedCheckpointEmbeddingCount ?? latestMetaForCount?.stats?.embeddings,
);
const { getRuntimeCapabilities } = await import('./platform/capabilities.js');
@ -4956,96 +5135,25 @@ async function runFullAnalysisInner(
// Parse-cache publish waits until after that swap + saveMeta so a failed
// registerRepo / close / swap cannot replace live shards (#3153).
// Forward the --name alias and the registry-collision bypass bit.
// `allowDuplicateName` is its own concern — independent from the
// pipeline `force` above. The CLI maps it from
// `--allow-duplicate-name` only; `--force` and `--skills` both
// trigger pipeline re-run but never bypass the registry guard.
// The returned name is the one actually written to the registry
// (after applying the precedence chain in registerRepo) — reuse it
// so AGENTS.md / skill files reference the same name MCP clients
// will look up (#979).
const projectName = await registerRepo(repoPath, meta, {
name: options.registryName,
onRename: (previousName, nextName) =>
log(`Registry name changed: "${previousName}" -> "${nextName}".`),
allowDuplicateName: options.allowDuplicateName,
// Non-primary branch runs upsert into the entry's branches[]; the
// primary/flat run (placement.branch === undefined) refreshes the
// top-level fields (#2106).
branch: placement.branch,
storagePath,
});
// ── #2354: the flat workspace slot has adopted this run's branch ──────
// Drop a now-shadowed `branches/<slug>/` sub-index for the same label
// (unreachable once the flat slot serves it) and align the registry's
// top-level branch label. Best-effort (#2364 review F5): the index is
// complete and registered, and a failure
// here leaves only a stale registry label / undeleted shadowed dir —
// never wrong routing, because the flat meta this run already stamped is
// what applyBranchScope trusts. Retried by the next content-changing run
// (same-commit fast-path runs skip it: their guard compares the
// already-stamped meta label).
if (!placement.branch && branchLabel) {
try {
await adoptFlatBranchLabel(repoPath, branchLabel, storagePath);
} catch (e) {
log(
`Warning: could not sync the workspace branch label (${(e as Error).message}); continuing.`,
if (wroteChangedSubgraphOnly) {
// Registry freshness must not advance either. Include FTS, embedding
// restoration and the final WAL drain in the certified boundary.
await markIncrementalGraphVerification();
await walCheckpointDriver.stop();
if (!(await checkpointOnce())) {
throw new Error(
'Graph identity reconciliation failed: final checkpoint could not be verified; run `gitnexus analyze --force`.',
);
}
await reconcileGraphNodeIdentities(
pipelineResult.graph,
executeQuery,
'pre-publish/checkpoint',
);
}
// Keep generated .gitnexus contents ignored without editing the user's root .gitignore.
await ensureGitNexusIgnored(repoPath, storagePath);
// ── Generate AI context files (best-effort) ───────────────────────
let aggregatedClusterCount = 0;
if (pipelineResult.communityResult?.communities) {
const groups = new Map<string, number>();
for (const c of pipelineResult.communityResult.communities) {
const label = c.heuristicLabel || c.label || 'Unknown';
groups.set(label, (groups.get(label) || 0) + c.symbolCount);
}
aggregatedClusterCount = Array.from(groups.values()).filter((count) => count >= 5).length;
}
// Only (re)generate the repo-root AI context files (AGENTS.md / CLAUDE.md /
// skills) for the primary/flat index (#2106). A non-primary branch analyze
// must not churn the repo's committed AGENTS.md with branch-specific stats.
if (!placement.branch) {
try {
await generateAIContextFiles(
repoPath,
storagePath,
projectName,
{
files: pipelineResult.totalFileCount,
nodes: stats.nodes,
edges: stats.edges,
communities:
pipelineResult.communityResult?.stats.totalCommunities ??
existingMeta?.stats?.communities,
clusters: aggregatedClusterCount,
processes:
pipelineResult.processResult?.stats.totalProcesses ?? existingMeta?.stats?.processes,
},
undefined,
{
skipAgentsMd: options.skipAgentsMd,
skipSkills: options.skipSkills,
noStats: options.noStats,
defaultBranch: options.defaultBranch,
hasPdg: options.pdg === true,
hasSpringActuator: options.springActuatorPath !== undefined,
},
);
} catch {
// Best-effort — don't fail the entire analysis for context file issues
}
}
// ── Close LadybugDB ──────────────────────────────────────────────
// Stop the manual checkpoint driver before closeLbug so its
// in-flight CHECKPOINT cannot race the `safeClose` CHECKPOINT.
@ -5108,6 +5216,97 @@ async function runFullAnalysisInner(
// is a crash-safety improvement: a failed swap leaves the previous index
// live and the next run recovers via the full-rebuild path.
await saveMeta(metaDir, meta);
sweepStagingArtifacts(metaDir, log);
// Registry freshness is published only after the graph and its metadata.
// A failed close, swap, or metadata save must leave the previous registry
// receipt intact, just as it leaves the cache unpublished.
// Forward the --name alias and the registry-collision bypass bit.
// `allowDuplicateName` is its own concern — independent from the
// pipeline `force` above. The CLI maps it from
// `--allow-duplicate-name` only; `--force` and `--skills` both
// trigger pipeline re-run but never bypass the registry guard.
// The returned name is the one actually written to the registry
// (after applying the precedence chain in registerRepo) — reuse it
// so AGENTS.md / skill files reference the same name MCP clients
// will look up (#979).
const projectName = await registerRepo(repoPath, meta, {
name: options.registryName,
onRename: (previousName, nextName) =>
log(`Registry name changed: "${previousName}" -> "${nextName}".`),
allowDuplicateName: options.allowDuplicateName,
// Non-primary branch runs upsert into the entry's branches[]; the
// primary/flat run (placement.branch === undefined) refreshes the
// top-level fields (#2106).
branch: placement.branch,
storagePath,
});
// ── #2354: the flat workspace slot has adopted this run's branch ──────
// Drop a now-shadowed `branches/<slug>/` sub-index for the same label
// (unreachable once the flat slot serves it) and align the registry's
// top-level branch label. Best-effort (#2364 review F5): the index is
// complete and registered, and a failure
// here leaves only a stale registry label / undeleted shadowed dir —
// never wrong routing, because the flat meta this run already stamped is
// what applyBranchScope trusts. Retried by the next content-changing run
// (same-commit fast-path runs skip it: their guard compares the
// already-stamped meta label).
if (!placement.branch && branchLabel) {
try {
await adoptFlatBranchLabel(repoPath, branchLabel, storagePath);
} catch (e) {
log(
`Warning: could not sync the workspace branch label (${(e as Error).message}); continuing.`,
);
}
}
// ── Generate AI context files (best-effort) ───────────────────────
let aggregatedClusterCount = 0;
if (pipelineResult.communityResult?.communities) {
const groups = new Map<string, number>();
for (const c of pipelineResult.communityResult.communities) {
const label = c.heuristicLabel || c.label || 'Unknown';
groups.set(label, (groups.get(label) || 0) + c.symbolCount);
}
aggregatedClusterCount = Array.from(groups.values()).filter((count) => count >= 5).length;
}
// Only (re)generate the repo-root AI context files (AGENTS.md / CLAUDE.md /
// skills) for the primary/flat index (#2106). A non-primary branch analyze
// must not churn the repo's committed AGENTS.md with branch-specific stats.
if (!placement.branch) {
try {
await generateAIContextFiles(
repoPath,
storagePath,
projectName,
{
files: pipelineResult.totalFileCount,
nodes: stats.nodes,
edges: stats.edges,
communities:
pipelineResult.communityResult?.stats.totalCommunities ??
existingMeta?.stats?.communities,
clusters: aggregatedClusterCount,
processes:
pipelineResult.processResult?.stats.totalProcesses ?? existingMeta?.stats?.processes,
},
undefined,
{
skipAgentsMd: options.skipAgentsMd,
skipSkills: options.skipSkills,
noStats: options.noStats,
defaultBranch: options.defaultBranch,
hasPdg: options.pdg === true,
hasSpringActuator: options.springActuatorPath !== undefined,
},
);
} catch {
// Best-effort — don't fail the entire analysis for context file issues
}
}
// Persist the incremental parse cache only after a successful graph
// publish (#3153). try/catch so a cache-write failure never breaks an
@ -5227,7 +5426,13 @@ async function runFullAnalysisInner(
// rethrow below is the surface, and the lock's sweep remains the backstop.
if (useAtomicSwap && buildPath !== lbugPath) {
try {
await wipeLbugDbFiles(buildPath);
const recovery = resolveEmbeddingRecovery(
metaDir,
(await loadMeta(metaDir))?.embeddingCheckpoint,
);
// Both paths belong to this locked slot. The validated generation
// basename identifies the same file even through a directory alias.
if (recovery?.stagingFile !== path.basename(buildPath)) await wipeLbugDbFiles(buildPath);
} catch {
/* swallow — orphan reclamation must never mask the real failure */
}
@ -5239,6 +5444,12 @@ async function runFullAnalysisInner(
// IndexLockTimeoutError and other domain failures with `instanceof`.
recordLiveIndexMutationRisk(err);
}
if (/max(?:imum)?(?: database| db)? size|database size limit|maxDBSize/i.test(String(err))) {
log(
'The database size limit was reached. Set GITNEXUS_LBUG_MAX_DB_SIZE to a larger ' +
'byte limit before retrying analyze; retained complete embeddings can be reused.',
);
}
throw err;
}
}

22
gitnexus/src/core/search/bm25-index.ts
View file

@ -47,6 +47,8 @@ export interface FTSSearchResponse {
* which only does so when every table failed).
*/
nonBenignErrors?: string[];
/** Configured table.index names that could not be queried because their index is missing. */
missingIndexes?: string[];
}
/**
@ -142,6 +144,7 @@ export const searchFTSFromLbug = async (
const resultsByIndex: any[][] = [];
let queriesSucceeded = 0;
const nonBenignErrors: string[] = [];
const missingIndexes: string[] = [];
const ftsExtension = getExtensionCapabilities().find((c) => c.name === 'fts');
if (ftsExtension && !ftsExtension.loaded) {
@ -171,24 +174,28 @@ export const searchFTSFromLbug = async (
if (outcome.rows) {
queriesSucceeded++;
resultsByIndex.push(outcome.rows);
} else if (!outcome.benign) {
} else if (outcome.benign) {
missingIndexes.push(`${table}.${indexName}`);
} else {
nonBenignErrors.push(redactPaths(outcome.message ?? 'Unknown FTS query error'));
}
}
} else {
// Use core lbug adapter (CLI / pipeline context) — also sequential for safety.
// tri-review Residual-1: `queryFTS` itself only swallows a genuinely-missing
// index (via the SAME classifyFtsQueryError this module re-exports); a
// missing-table or real query error rethrows here — track it the same way
// the MCP pool path does instead of a bare `catch {}` that dropped it.
// Opt into missing-index propagation so absent indexes cannot masquerade
// as successful zero-match queries. Keep core/pool classification identical.
for (const { table, indexName } of FTS_INDEXES) {
try {
const result = await queryFTS(table, indexName, searchQuery, limit, false);
const result = await queryFTS(table, indexName, searchQuery, limit, false, 'throw');
queriesSucceeded++;
resultsByIndex.push(result);
} catch (e) {
const message = e instanceof Error ? e.message : String(e);
nonBenignErrors.push(redactPaths(message));
if (classifyFtsQueryError(message) === 'missing-index') {
missingIndexes.push(`${table}.${indexName}`);
} else {
nonBenignErrors.push(redactPaths(message));
}
}
}
}
@ -234,5 +241,6 @@ export const searchFTSFromLbug = async (
})),
ftsAvailable,
...(nonBenignErrors.length > 0 && { nonBenignErrors }),
...(missingIndexes.length > 0 && { missingIndexes }),
};
};

22
gitnexus/src/core/search/fts-indexes.ts
View file

@ -110,19 +110,21 @@ export const ftsDegradedWarning = (
};
/**
* Warning for when the FTS extension is loaded and indexes exist, but every
* configured table's query failed for a real, non-benign reason (timeout,
* connection reset, native fault) — as opposed to `ftsDegradedWarning`'s
* missing-index case. `--repair-fts` will not fix a query/connection error,
* so this deliberately does NOT suggest it: reusing the missing-index
* message here would reproduce, for this cause, the exact misleading
* "run --repair-fts" guidance #2767 itself was about (tri-review NEW-1).
* Warning when no FTS query succeeded and at least one failed for a real,
* non-benign reason (timeout, connection reset, native fault). `--repair-fts`
* will not fix those errors. If indexes are also missing, the caller composes
* their repair guidance separately; do not deny that additional failure cause.
*/
export const ftsQueryFailedWarning = (context: FtsWarningContext): string =>
export const ftsQueryFailedWarning = (
context: FtsWarningContext,
hasMissingIndexes = false,
): string =>
'FTS keyword search failed — every configured index query returned an error' +
(context.lastErrorRedacted ? ` (${context.lastErrorRedacted})` : '') +
'; results do not include keyword matches. This is not a missing-index ' +
'condition — see server logs for details.' +
'; results do not include keyword matches. ' +
(hasMissingIndexes
? 'See server logs for query error details.'
: 'This is not a missing-index condition — see server logs for details.') +
` (resolved: ${formatResolvedSuffix(context)})`;
// Stemmers shipped by the LadybugDB FTS extension. Mirrors the lowercase token

42
gitnexus/src/core/staleness-status.ts
View file

@ -18,21 +18,35 @@
* provably stale index indistinguishable from a fresh one. `status` is the
* additive channel that separates them for a caller that wants to act on it:
*
* - `current` — the index is at HEAD: `rev-list` answered 0, or it could not
* answer but HEAD alone resolved to the indexed commit.
* - `behind` — `rev-list` answered N > 0; `commitsBehind` is N.
* - `diverged` — `rev-list` could not answer, but HEAD resolved and is not the
* indexed commit. The index is provably not at HEAD; only the count is
* unknown. A branch-pinned `serve` clone reaches this once git prunes the
* commit a failed re-index left behind — the pinned update is a
* `fetch --depth 1`, which orphans it — and a rewritten history reaches it
* directly. It is the rule the Claude hook already applies:
* HEAD !== lastCommit.
* - `unknown` — HEAD could not be resolved at all: not a git repository, git
* timed out, or no commit was recorded.
* The successful probe is `rev-list --left-right --count lastCommit...HEAD`:
* the left count is indexed-only commits, and the right is HEAD-only commits.
* Both counts come from one HEAD snapshot, without a follow-up process.
*
* `isStale` and `commitsBehind` keep their historical values in every case, so
* no existing consumer changes behaviour unless it reads `status`.
* - `current` — both counts are 0, or `rev-list` could not answer but a
* fallback `rev-parse HEAD` resolved to the indexed commit.
* - `behind` — the right count is N > 0; `commitsBehind` is N, including
* when the left count is positive too (divergent or shallow history).
* - `diverged` — the index is provably not at HEAD, reached two different ways:
* - The left count is positive and the right is 0: HEAD is an ancestor
* of the indexed commit (#3127). The working tree checked out an older
* commit than the one indexed, or a release branch behind the indexed
* tip. The mismatch is established: `isStale` is `true` and
* `commitsBehind` stays 0 (there is no forward count to report).
* - `rev-list` could not answer at all, but HEAD resolved and is not the
* indexed commit: only the count is unknown. A branch-pinned `serve`
* clone reaches this once git prunes the commit a failed re-index left
* behind — the pinned update is a `fetch --depth 1`, which orphans it —
* and a rewritten history reaches it directly. This arm keeps the
* historical fail-open `isStale: false` (see below).
* - `unknown` — the probe could not establish the relationship: no readable
* HEAD, a timeout, no recorded commit, or malformed count output.
*
* `isStale` and `commitsBehind` keep their historical fail-open values
* (`false` / `0`) whenever the check could not fully answer — every `unknown`,
* and the `rev-list`-failure arm of `diverged` — so no existing consumer
* changes behaviour there unless it reads `status`. The other arm of
* `diverged` (the confirmed rollback) is a successful, computed
* answer rather than a failure, so `isStale` reflects it (`true`) instead.
*/
export type StalenessStatus = 'current' | 'behind' | 'diverged' | 'unknown';

27
gitnexus/src/mcp/local/aop-metadata.ts
View file

@ -1,4 +1,9 @@
import { executeParameterized } from '../../core/lbug/pool-adapter.js';
import {
assertSymbolIdentity,
assertIdentityFields,
rethrowSymbolIdentityError,
} from './query-result-integrity.js';
import {
decodeSpringAopReason,
type SpringAopReason,
@ -151,6 +156,7 @@ const DETERMINISTIC_RELATIONSHIP_ORDER = 'ORDER BY sourceId, targetId, reason, s
* shared decoder. Other DECLARES edges (for example Spring Bean factories)
* and malformed/forward-version evidence are ignored. Query failures are
* fail-soft because older or partially upgraded indexes must remain readable.
* Corrupt identities propagate to the context/impact integrity error boundary.
*/
export async function querySpringAopMetadata(
lbugPath: string,
@ -204,6 +210,24 @@ export async function querySpringAopMetadata(
),
]);
for (const rows of [
outgoingAdviceRows,
incomingAdviceRows,
outgoingPointcutRows,
incomingPointcutRows,
]) {
for (const row of rows) {
assertSymbolIdentity(readRowValue(row, 'sourceId', 0));
assertSymbolIdentity(readRowValue(row, 'targetId', 3));
assertIdentityFields(
readRowValue(row, 'sourceName', 1),
readRowValue(row, 'sourceFilePath', 2),
readRowValue(row, 'targetName', 4),
readRowValue(row, 'targetFilePath', 5),
);
}
}
const behaviors: SpringAopBehaviorMetadata[] = [];
const advices: SpringAopAdviceMetadata[] = [];
const resolvedPointcuts: SpringAopResolvedPointcutMetadata[] = [];
@ -346,7 +370,8 @@ export async function querySpringAopMetadata(
resolvedPointcuts: dedupedResolvedPointcuts,
unresolvedPointcuts: dedupedPointcuts,
};
} catch {
} catch (error) {
rethrowSymbolIdentityError(error);
return undefined;
}
}

302
gitnexus/src/mcp/local/local-backend.ts
View file

@ -10,7 +10,12 @@ import { resolveGraphPath } from '../../storage/shared-store.js';
import fs from 'fs/promises';
import path from 'path';
import { createHash } from 'crypto';
import { scoreImpactRisk, unusedAxesForImpactWalk, type ImpactRiskResult } from 'gitnexus-shared';
import {
scoreImpactRisk,
unusedAxesForImpactWalk,
getLanguageFromFilename,
type ImpactRiskResult,
} from 'gitnexus-shared';
import {
initLbug,
executeQuery,
@ -23,6 +28,15 @@ import {
} from '../../core/lbug/pool-adapter.js';
import { queryClassBeanMetadata } from './bean-metadata.js';
import { querySpringAopMetadata } from './aop-metadata.js';
import {
SYMBOL_IDENTITY_RECOVERY_SUGGESTION,
SymbolIdentityError,
assertSymbolIdentity,
queryRowValue,
assertIdentityFields,
assertQueryIdentity,
rethrowSymbolIdentityError,
} from './query-result-integrity.js';
import { queryConvexDispatchMetadata } from './convex-metadata.js';
import { isValidQueryParams } from '../../core/lbug/query-params.js';
import { toDisplayLine } from './line-display.js';
@ -30,8 +44,10 @@ import { shapeQueryProcessAttaches } from './query-process-attaches.js';
import { LBUG_ID_PROBE_BATCH_SIZE, LBUG_QUERY_BATCH_SIZE } from '../../core/lbug/query-batch.js';
import { chunk, mapConcurrent } from '../../lib/utils.js';
import { pathSuffixOf } from './path-predicate.js';
import { isCobolFile, isJclFile } from '../../core/ingestion/cobol/file-types.js';
import { toOneBasedLine } from '../../core/ingestion/utils/line-base.js';
import { isTestFilePath } from '../../core/ingestion/utils/test-file-path.js';
import { isTemplateRouteCandidate } from '../../core/ingestion/utils/template-file.js';
import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../../core/lbug/lbug-config.js';
// Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
// at MCP server startup — crashes on unsupported Node ABI versions (#89)
@ -317,6 +333,70 @@ function nonBlankUid(value: unknown): string | undefined {
return typeof value === 'string' ? value.trim() || undefined : undefined;
}
function assertSymbolRowIdentity(row: unknown): void {
assertQueryIdentity(row, 'id', 0, [
['name', 1],
['type', 2],
['filePath', 3],
]);
}
function assertContextRefs(rows: unknown[]): void {
for (const row of rows) {
assertQueryIdentity(row, 'uid', 1, [
['name', 2],
['filePath', 3],
['kind', 4],
]);
assertSymbolIdentity(queryRowValue(row, 'relType', 0));
}
}
const RESPONSE_IDENTITY_FIELDS = new Set([
'id',
'uid',
'name',
'filePath',
'label',
'kind',
'type',
'relationType',
'processType',
'url',
'method',
'sourceId',
'targetId',
'symbolId',
'symbolName',
'symbolFilePath',
'adviceId',
'adviceName',
'adviceFilePath',
'advisedId',
'advisedName',
'advisedFilePath',
'evidenceId',
]);
/** Cover nested additive identity fields while leaving source/metadata text alone. */
function assertResponseIdentities(value: unknown): void {
if (Array.isArray(value)) {
for (const item of value) assertResponseIdentities(item);
} else if (value !== null && typeof value === 'object') {
for (const [key, field] of Object.entries(value)) {
if (key === 'seedBlocks' || key === 'reachableBlocks' || key === 'intraReachableBlocks') {
if (!Array.isArray(field)) throw new SymbolIdentityError();
for (const id of field) assertSymbolIdentity(id);
continue;
}
if (RESPONSE_IDENTITY_FIELDS.has(key)) assertIdentityFields(field);
if (key !== 'content' && key !== 'methodMetadata' && key !== 'bean') {
assertResponseIdentities(field);
}
}
}
}
interface StringAliasDefinition {
canonical: string;
aliases: readonly string[];
@ -3143,6 +3223,7 @@ export class LocalBackend {
// regardless of whether OTHER tables succeeded — previously a real error
// on N-1 of N tables while one succeeded left zero diagnostic trail.
const ftsQueryErrors = bm25SearchResult?.nonBenignErrors;
const ftsMissingIndexes = bm25SearchResult?.missingIndexes;
if (ftsQueryErrors) {
// tri-review NEW-5: these strings are already classified non-benign by
// classifyFtsQueryError — do NOT route them through logQueryError,
@ -3632,13 +3713,15 @@ export class LocalBackend {
branch: repo.branch,
indexedAt: this.lastObservedPoolState.get(repo.lbugPath)?.indexedAt ?? repo.indexedAt,
};
// tri-review NEW-1: every table failing for a REAL error (timeout,
// connection reset) is not a missing-index condition — `ftsDegradedWarning`'s
// "run --repair-fts" headline won't fix it. Route to a dedicated message
// instead of burying the real cause as a trailing suffix on bad advice.
// Real errors (timeout, connection reset) need their own diagnosis.
// When some indexes are also missing, preserve both causes and append
// their repair guidance below even though no FTS query succeeded.
warnings.push(
ftsQueryErrors
? ftsQueryFailedWarning({ ...warningContext, lastErrorRedacted: ftsQueryErrors[0] })
? ftsQueryFailedWarning(
{ ...warningContext, lastErrorRedacted: ftsQueryErrors[0] },
!!ftsMissingIndexes?.length,
)
: ftsDegradedWarning(warningContext, ftsDisabledReason),
);
} else if (ftsQueryErrors) {
@ -3651,6 +3734,12 @@ export class LocalBackend {
`FTS keyword search partially failed — ${ftsQueryErrors.length} of the configured indexes hit a query error and were skipped; results may be missing matches from those node types (see server logs).`,
);
}
if (ftsMissingIndexes?.length && (ftsUsed || ftsQueryErrors)) {
warnings.push(
`FTS keyword search is incomplete: missing configured indexes (${ftsMissingIndexes.join(', ')}). ` +
'Results may be missing matches from those node types. Run `gitnexus analyze --repair-fts`.',
);
}
// #2331: a CJK query against a server process resolving
// GITNEXUS_FTS_CJK_SEGMENTATION to 'none' silently misses sub-phrase
// matches with no other signal — this is the only place an agent driving
@ -3782,7 +3871,7 @@ export class LocalBackend {
// #2767: a partial FTS failure (some tables ok, one or more real errors)
// is as much a "results may be incomplete" signal as enrichmentDegraded —
// flag it the same way rather than only via the warning string.
const ftsPartial = ftsUsed && !!ftsQueryErrors;
const ftsPartial = ftsUsed && (!!ftsQueryErrors || !!ftsMissingIndexes?.length);
return {
processes,
@ -3803,7 +3892,12 @@ export class LocalBackend {
query: string,
limit: number,
disabledReason?: FtsDisabledReason,
): Promise<{ results: any[]; ftsUsed: boolean; nonBenignErrors?: string[] }> {
): Promise<{
results: any[];
ftsUsed: boolean;
nonBenignErrors?: string[];
missingIndexes?: string[];
}> {
if (disabledReason) return { results: [], ftsUsed: false };
let searchFTSFromLbug;
try {
@ -3837,6 +3931,7 @@ export class LocalBackend {
const bm25Results = ftsResponse?.results ?? [];
const ftsUsed = ftsResponse?.ftsAvailable ?? false;
const nonBenignErrors = ftsResponse?.nonBenignErrors;
const missingIndexes = ftsResponse?.missingIndexes;
const results: any[] = [];
@ -3910,7 +4005,12 @@ export class LocalBackend {
}
}
return { results, ftsUsed, ...(nonBenignErrors && { nonBenignErrors }) };
return {
results,
ftsUsed,
...(nonBenignErrors && { nonBenignErrors }),
...(missingIndexes && { missingIndexes }),
};
}
/**
@ -4344,9 +4444,10 @@ export class LocalBackend {
* "unknown kind" and, worse, makes the `kind` disambiguation hint unable to
* filter it out (#2687).
*
* Failures are swallowed: label enrichment is an optimisation for
* Ordinary query failures are swallowed: label enrichment is an optimisation for
* downstream scoring and #480 Class/Interface BFS seeding; if it fails
* the symbol still resolves, just without the kind-priority bonus.
* Corrupt identities propagate to the context/impact error envelope.
*/
private async enrichCandidateLabels(
repo: RepoHandle,
@ -4380,6 +4481,7 @@ export class LocalBackend {
);
const labelById = new Map<string, string>();
for (const r of rows as any[]) {
assertQueryIdentity(r, 'id', 0, [['label', 1]]);
const id = (r.id ?? r[0]) as string;
const label = (r.label ?? r[1]) as string;
if (id && label && !labelById.has(id)) labelById.set(id, label);
@ -4387,7 +4489,8 @@ export class LocalBackend {
for (const c of candidates) {
if (c.type === '' && labelById.has(c.id)) c.type = labelById.get(c.id) as string;
}
} catch {
} catch (error) {
rethrowSymbolIdentityError(error);
/* best-effort — downstream resolvers still work without the label */
}
}
@ -4512,6 +4615,7 @@ export class LocalBackend {
{ uid },
);
if (rows.length === 0) return { kind: 'not_found' };
assertSymbolRowIdentity(rows[0]);
const r = rows[0] as any;
const symbol = {
id: (r.id ?? r[0]) as string,
@ -4522,6 +4626,7 @@ export class LocalBackend {
endLine: (r.endLine ?? r[5]) as number,
...(include_content ? { content: (r.content ?? r[6]) as string | undefined } : {}),
};
assertSymbolIdentity(symbol.id, uid);
// Same LadybugDB label-enrichment as the name-based path: a UID
// pointing at a Class must still surface `type: 'Class'` so impact's
// Class/Interface BFS seed fires. No-op when type is already set.
@ -4645,6 +4750,10 @@ export class LocalBackend {
if (rows.length === 0) return { kind: 'not_found' };
// Reject every raw candidate before narrowing/scoring can hide a corrupt row.
for (const row of rows) {
assertSymbolRowIdentity(row);
}
// Normalise row shape across object / tuple returns from LadybugDB.
let normalized = rows.map((r: any) => ({
id: (r.id ?? r[0]) as string,
@ -4655,7 +4764,6 @@ export class LocalBackend {
endLine: (r.endLine ?? r[5]) as number,
...(include_content ? { content: (r.content ?? r[6]) as string | undefined } : {}),
}));
// An exact File path wins over anchored suffix candidates. Without this,
// `lib/a.ts` and `src/lib/a.ts` both score as File candidates and turn an
// otherwise unambiguous exact target into `ambiguous` (#3084 review P2).
@ -4805,9 +4913,14 @@ export class LocalBackend {
},
): Promise<any> {
try {
return await this._contextImpl(repo, params);
const result = await this._contextImpl(repo, params);
if (!result.error) assertResponseIdentities(result);
return result;
} catch (err: any) {
const msg = (err instanceof Error ? err.message : String(err)) || 'Context query failed';
if (err instanceof SymbolIdentityError) {
return { error: msg, recoverySuggestion: SYMBOL_IDENTITY_RECOVERY_SUGGESTION };
}
if (isWalCorruptionError(err)) {
return {
error: msg,
@ -4922,6 +5035,8 @@ export class LocalBackend {
{ symId },
),
]);
assertContextRefs(incomingRows);
assertContextRefs(incomingAdvisedRows);
incomingRows.push(...incomingAdvisedRows);
let typedPropertyRows: any[] = [];
@ -5026,6 +5141,16 @@ export class LocalBackend {
},
),
]);
assertContextRefs(ctorIncoming);
assertContextRefs(fileIncoming);
assertContextRefs(typedPropertyIncoming);
for (const row of typedProperties) {
assertQueryIdentity(row, 'uid', 0, [
['name', 1],
['filePath', 2],
['kind', 3],
]);
}
typedPropertyRows = typedProperties;
// Deduplicate by (relType, uid) — a caller can have multiple relation
@ -5042,6 +5167,7 @@ export class LocalBackend {
}
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('context:class-incoming-expansion', e);
}
}
@ -5072,6 +5198,8 @@ export class LocalBackend {
{ symId },
),
]);
assertContextRefs(outgoingRows);
assertContextRefs(outgoingAdvisedRows);
outgoingRows.push(...outgoingAdvisedRows);
// Process participation.
@ -5095,7 +5223,14 @@ export class LocalBackend {
`,
{ symId },
);
for (const row of processRows) {
assertQueryIdentity(row, 'pid', 0, [
['label', 1],
['entryPointId', 4],
]);
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('context:process-participation', e);
}
@ -5132,6 +5267,7 @@ export class LocalBackend {
// (GET/POST pair). URL-only dedup would drop the second endpoint.
const seenRoutes = new Set<string>();
for (const r of routeRows) {
assertIdentityFields(queryRowValue(r, 'url', 0), queryRowValue(r, 'method', 1));
const url = r.url ?? r[0];
const method = r.method ?? r[1];
const dedupKey = routeEnrichmentKey(method ? String(method) : undefined, url);
@ -5141,7 +5277,8 @@ export class LocalBackend {
}
}
} catch (e) {
// Best-effort enrichment — never fail the context call.
rethrowSymbolIdentityError(e);
// Ordinary query failures leave this best-effort enrichment unavailable.
logQueryError('context:route-lookup', e);
}
@ -5191,6 +5328,7 @@ export class LocalBackend {
);
const beanMetadataPromise = queryClassBeanMetadata(repo.lbugPath, symId, epistemicSymType);
const aopMetadataPromise = querySpringAopMetadata(repo.lbugPath, symId, epistemicSymType);
void aopMetadataPromise.catch(() => undefined);
// R3-1. A `Property` whose name the analyzer declined to link — because
// every definition of it lives in another language — otherwise returns an
@ -5285,6 +5423,7 @@ export class LocalBackend {
try {
chain = await this._computeContextChain(repo, symId, requestedDepth);
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('context:chain-bfs', e);
}
}
@ -5325,8 +5464,8 @@ export class LocalBackend {
processes: processRows.map((r: any) => ({
id: r.pid || r[0],
name: r.label || r[1],
step_index: r.step || r[2],
step_count: r.stepCount || r[3],
step_index: r.step ?? r[2],
step_count: r.stepCount ?? r[3],
})),
};
}
@ -5407,6 +5546,13 @@ export class LocalBackend {
visited: Array.from(visited),
});
if (rows.length === 0) return { nextFrontier: [] };
for (const row of rows) {
assertQueryIdentity(row, 'uid', 0, [
['name', 1],
['filePath', 2],
['kind', 3],
]);
}
// MATCH is one row per CALLS edge. Cypher `WITH DISTINCT` applies
// LIMIT 50 to unique neighbors; this second pass still collapses
// twins if a driver/engine ever returns duplicate rows.
@ -5426,6 +5572,7 @@ export class LocalBackend {
for (const r of fresh) visited.add(r.uid);
return { nodes, nextFrontier: fresh.map((r: any) => r.uid) };
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError(logLabel, e);
return { nextFrontier: [] };
}
@ -6445,6 +6592,7 @@ export class LocalBackend {
// throwaway arrays the size of the row set (40k rows 11.4ms → 4.5ms, 200k
// rows 71.3ms → 26.6ms).
const exactlyMatchedPaths = new Set<string>();
const mappedPaths = new Set<string>();
for (const row of symbolRows) {
if (row.filePath === row.diffPath) exactlyMatchedPaths.add(row.diffPath);
}
@ -6454,6 +6602,8 @@ export class LocalBackend {
if (sym.filePath !== sym.diffPath && exactlyMatchedPaths.has(diffPath)) continue;
const hunks = hunksByPath.get(diffPath) ?? [];
if (!hunksOverlapRange(hunks, sym.startLine, sym.endLine)) continue;
// A suffix fallback is a hint, not proof that this is the changed file.
if (sym.filePath === diffPath) mappedPaths.add(diffPath);
if (changedSymbols.has(sym.id)) continue;
changedSymbols.set(sym.id, {
@ -6465,6 +6615,27 @@ export class LocalBackend {
});
}
// An empty successful query cannot prove a source diff is safe: its rows
// may be missing, outside indexed spans, or not yet indexed. Keep ordinary
// docs/config diffs measurable, but withhold a ranked source-risk verdict.
const isSourceFile = (file: string): boolean =>
getLanguageFromFilename(file) !== null ||
isCobolFile(file) ||
isJclFile(file) ||
isTemplateRouteCandidate(file);
const unmappedFiles = [
...new Set(
fileDiffs
.filter(
({ filePath, oldFilePath }) =>
!mappedPaths.has(filePath) &&
(isSourceFile(filePath) || (oldFilePath !== undefined && isSourceFile(oldFilePath))),
)
.map(({ filePath }) => filePath),
),
];
if (unmappedFiles.length > 0) queryDegraded = true;
// Find affected processes -- batched queries instead of N+1
const affectedProcesses = new Map<string, any>();
if (changedSymbols.size > 0) {
@ -6565,8 +6736,9 @@ export class LocalBackend {
},
changed_symbols: listedSymbols,
affected_processes: Array.from(affectedProcesses.values()),
// A swallowed query failure makes the counts/risk above incomplete — tell
// the caller so the safety gate isn't trusted as a clean result (#2283).
...(unmappedFiles.length > 0 && { unmapped_files: unmappedFiles }),
// Failed queries or unmapped source files leave counts/risk incomplete;
// the safety gate must not treat that as a clean result (#2283).
...(queryDegraded && { partial: true }),
...(listedSymbols.length < changedSymbols.size && { truncated: true }),
};
@ -7082,13 +7254,23 @@ export class LocalBackend {
private async impact(repo: RepoHandle, params: ImpactParams): Promise<any> {
try {
return await this._impactImpl(repo, params);
const result = await this._impactImpl(repo, params);
if (!result.error) assertResponseIdentities(result);
return result;
} catch (err: any) {
// Return structured error instead of crashing (#321)
const message =
(err instanceof Error ? err.message : String(err)) || 'Impact analysis failed';
const suggestion = 'The graph query failed — try gitnexus context <symbol> as a fallback';
const recoverySuggestion = isWalCorruptionError(err) ? WAL_RECOVERY_SUGGESTION : undefined;
const recoverySuggestion =
err instanceof SymbolIdentityError
? SYMBOL_IDENTITY_RECOVERY_SUGGESTION
: isWalCorruptionError(err)
? WAL_RECOVERY_SUGGESTION
: undefined;
const suggestion =
err instanceof SymbolIdentityError
? SYMBOL_IDENTITY_RECOVERY_SUGGESTION
: 'The graph query failed — try gitnexus context <symbol> as a fallback';
if (params.mode === 'pdg') {
// Symbol resolution never reached the catch with a resolved symbol (the
// throw can originate before/within resolution), so the envelope carries
@ -7392,6 +7574,7 @@ export class LocalBackend {
} catch (e) {
probeFailed = true;
candidateProbeFailed = true;
rethrowSymbolIdentityError(e);
logQueryError('impact:ambiguous-candidate', e);
}
return {
@ -7649,6 +7832,7 @@ export class LocalBackend {
});
return composeUnifiedPdgImpactResult(pdgResult, interproceduralResult);
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:pdg-interprocedural-reach', e);
return composeUnifiedPdgImpactResult(pdgResult, null, e);
}
@ -7686,10 +7870,12 @@ export class LocalBackend {
{ ids: blockIds },
);
for (const r of rows as any[]) {
assertIdentityFields(r.callees ?? r[0]);
const raw = String(r.callees ?? r[0] ?? '');
for (const n of raw.split(' ')) if (n) names.add(n);
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:pdg-slice-callees', e);
}
return names;
@ -7725,6 +7911,7 @@ export class LocalBackend {
for (const id of splitCalleeIds(r.calleeIds ?? r[0])) ids.add(id);
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:pdg-slice-callee-ids', e);
}
return ids;
@ -7878,7 +8065,10 @@ export class LocalBackend {
ORDER BY id
LIMIT 25`,
{ symId, heritage: HERITAGE_TYPES },
).catch(() => []);
).catch((error) => {
rethrowSymbolIdentityError(error);
return [];
});
const undecidedSummary = meta?.undecidedInterfaceSatisfaction;
const undecidedDrops =
undecidedSummary === undefined
@ -7917,6 +8107,10 @@ export class LocalBackend {
}
const ifaceRows = await interfaceRowsPromise;
for (const r of ifaceRows) {
assertQueryIdentity(r, 'id', 0, [
['name', 1],
['label', 2],
]);
const id = (r.id ?? r[0]) as string;
if (id && !boundary.has(id)) {
boundary.set(id, {
@ -7942,7 +8136,10 @@ export class LocalBackend {
WHERE iface.id = $ifaceId AND r.type IN $types
RETURN COUNT(DISTINCT other.id) AS cnt`,
{ ifaceId, types },
).catch(() => []);
).catch((error) => {
rethrowSymbolIdentityError(error);
return [];
});
const cnt =
rows.length > 0 ? Number((rows[0] as any).cnt ?? (rows[0] as any)[0] ?? 0) : 0;
m.set(ifaceId, cnt);
@ -8001,7 +8198,8 @@ export class LocalBackend {
callableValueReferences: droppedBoundaries.callableValueReferences,
},
};
} catch {
} catch (error) {
rethrowSymbolIdentityError(error);
// Never let the heritage probe's failure suppress a drop we already know
// about — the whole point is that silence must not read as certainty.
return epistemicFrom(droppedBoundaries);
@ -8093,6 +8291,7 @@ export class LocalBackend {
`Impact target '${sym.name || sym[1] || '?'}' resolved without a node id; refusing to report a blast radius`,
);
}
assertSymbolRowIdentity(sym);
// #1858 — kick off the epistemic boundary probe concurrently with the BFS.
// It depends only on symId/symType/symName (all known now) and touches no
@ -8128,6 +8327,7 @@ export class LocalBackend {
opts.skipEpistemic || summaryOnly
? Promise.resolve(undefined)
: querySpringAopMetadata(repo.lbugPath, symId, symType);
void aopMetadataPromise.catch(() => undefined);
const impacted: any[] = [];
const visited = new Set<string>([symId]);
const pdgBridgeEvidenceById = new Map<string, PdgBridgeEvidenceInfo>();
@ -8172,6 +8372,7 @@ export class LocalBackend {
]);
for (const r of ctorRows) {
assertSymbolRowIdentity(r);
const rid = r.id || r[0];
if (rid && !visited.has(rid)) {
visited.add(rid);
@ -8179,6 +8380,7 @@ export class LocalBackend {
}
}
for (const r of fileRows) {
assertSymbolRowIdentity(r);
const rid = r.id || r[0];
if (rid && !visited.has(rid)) {
visited.add(rid);
@ -8203,6 +8405,7 @@ export class LocalBackend {
);
for (const r of typedPropertyRows) {
assertSymbolRowIdentity(r);
const rid = r.id || r[0];
if (rid && !visited.has(rid)) {
visited.add(rid);
@ -8210,6 +8413,7 @@ export class LocalBackend {
}
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:class-node-expansion', e);
traversalComplete = false;
}
@ -8247,6 +8451,9 @@ export class LocalBackend {
`,
{ symId },
);
for (const row of memberRows) {
assertSymbolRowIdentity(row);
}
memberRows.sort((a, b) => compareCodeUnits(String(a.id ?? a[0]), String(b.id ?? b[0])));
if (memberRows.length > OBJECT_CALLABLE_MEMBER_CAP) traversalComplete = false;
for (const row of memberRows.slice(0, OBJECT_CALLABLE_MEMBER_CAP)) {
@ -8266,6 +8473,7 @@ export class LocalBackend {
}
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:object-callable-expansion', e);
traversalComplete = false;
}
@ -8322,6 +8530,17 @@ export class LocalBackend {
relTypes: relationTypes,
...(safeMinConfidence > 0 ? { minConfidence: safeMinConfidence } : {}),
});
// Validate before filtering/deduplication; a discarded corrupt edge is
// still evidence that this result's counts cannot be trusted.
for (const row of related) {
assertQueryIdentity(row, 'id', 1, [
['sourceId', 0],
['name', 2],
['type', 3],
['filePath', 4],
]);
assertSymbolIdentity(queryRowValue(row, 'relType', 5));
}
const edges: ImpactFrontierEdge[] = related.map((rel) => ({
id: rel.id || rel[1],
@ -8421,6 +8640,7 @@ export class LocalBackend {
});
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:depth-traversal', e);
// Break out of depth loop on query failure but return partial results
// collected so far, rather than silently swallowing the error (#321)
@ -8546,6 +8766,7 @@ export class LocalBackend {
`,
{ ids },
).catch((err) => {
rethrowSymbolIdentityError(err);
processQueryFailed = true;
enrichmentDegraded = true;
logQueryError('impact:process-chunk', err);
@ -8553,6 +8774,14 @@ export class LocalBackend {
});
for (const row of rows) {
assertQueryIdentity(row, 'pId', 0, [
['name', 1],
['processType', 2],
['entryPointId', 3],
['epName', 7],
['epType', 8],
['epFilePath', 9],
]);
const pId = row.pId ?? row[0];
const epId = row.entryPointId ?? row[3] ?? row.pId ?? row[0];
// Track mapping from process -> entryPoint so we can backfill missing minStep
@ -8601,6 +8830,7 @@ export class LocalBackend {
ep.earliest_broken_step = Math.min(ep.earliest_broken_step, minStep ?? Infinity);
}
} catch (e) {
rethrowSymbolIdentityError(e);
processQueryFailed = true;
enrichmentDegraded = true;
logQueryError('impact:process-chunk', e);
@ -8623,12 +8853,14 @@ export class LocalBackend {
`,
{ pIds, ids: allImpactedIds },
).catch((err) => {
rethrowSymbolIdentityError(err);
enrichmentDegraded = true;
logQueryError('impact:process-chunk-backfill', err);
return [];
});
for (const mr of missingRows) {
assertQueryIdentity(mr, 'pid', 0, []);
const pid = mr.pid ?? mr[0];
const minStep = mr.minStep ?? mr[1];
const epId = processToEntryPoint.get(String(pid));
@ -8640,6 +8872,7 @@ export class LocalBackend {
}
}
} catch (e) {
rethrowSymbolIdentityError(e);
enrichmentDegraded = true;
logQueryError('impact:process-chunk-backfill', e);
}
@ -8702,6 +8935,7 @@ export class LocalBackend {
`,
{ ids: idsChunk },
).catch((err) => {
rethrowSymbolIdentityError(err);
moduleQueryFailed = true;
enrichmentDegraded = true;
logQueryError('impact:module-chunk', err);
@ -8709,12 +8943,14 @@ export class LocalBackend {
});
for (const r of rows) {
assertIdentityFields(queryRowValue(r, 'name', 0));
const name = r.name ?? r[0] ?? null;
const hits = (r.hits ?? r[1]) || 0;
if (!name) continue;
moduleHitsMap.set(name, (moduleHitsMap.get(name) || 0) + hits);
}
} catch (e) {
rethrowSymbolIdentityError(e);
moduleQueryFailed = true;
enrichmentDegraded = true;
logQueryError('impact:module-chunk', e);
@ -8743,16 +8979,19 @@ export class LocalBackend {
`,
{ ids: idsChunk },
).catch((err) => {
rethrowSymbolIdentityError(err);
enrichmentDegraded = true;
moduleClassificationFailed = true;
logQueryError('impact:direct-module-chunk', err);
return [];
});
for (const r of rows) {
assertIdentityFields(queryRowValue(r, 'name', 0));
const name = r.name ?? r[0] ?? null;
if (name) directModuleSet.add(name);
}
} catch (e) {
rethrowSymbolIdentityError(e);
enrichmentDegraded = true;
moduleClassificationFailed = true;
logQueryError('impact:direct-module-chunk', e);
@ -8814,11 +9053,14 @@ export class LocalBackend {
`,
{ ids: chunkIds },
).catch((err) => {
rethrowSymbolIdentityError(err);
enrichmentDegraded = true;
logQueryError('impact:route-chunk', err);
return [];
});
for (const row of rows) {
assertSymbolIdentity(queryRowValue(row, 'hid', 0));
assertIdentityFields(queryRowValue(row, 'url', 1), queryRowValue(row, 'method', 2));
const hid = String(row.hid ?? row[0] ?? '');
const url = row.url ?? row[1];
if (!hid || typeof url !== 'string') continue;
@ -8975,8 +9217,16 @@ export class LocalBackend {
p.processType AS pType, MIN(r.step) AS step
`,
{ ids: chunkIds },
).catch(() => []);
).catch((err) => {
rethrowSymbolIdentityError(err);
return [];
});
for (const row of rows) {
assertQueryIdentity(row, 'sid', 0, []);
assertQueryIdentity(row, 'pid', 1, [
['pName', 2],
['pType', 3],
]);
const sid = row.sid ?? row[0];
if (!sid) continue;
const procEntry = {
@ -8990,6 +9240,7 @@ export class LocalBackend {
else perSymbolProcesses.set(String(sid), [procEntry]);
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:per-symbol-process-chunk', e);
}
}
@ -9106,6 +9357,7 @@ export class LocalBackend {
];
try {
assertSymbolIdentity(sym.id ?? sym[0], uid);
// skipPerSymbolEnrichment suppresses ONLY the per-symbol STEP_IN_PROCESS
// enrichment pass while preserving byDepth. Group-mode cross-repo fan-out
// may fan across many repos; the per-symbol pass adds up to MAX_CHUNKS

27
gitnexus/src/mcp/local/pdg-impact.ts
View file

@ -27,6 +27,11 @@ import { toDisplayLine } from './line-display.js';
import { toOneBasedLine } from '../../core/ingestion/utils/line-base.js';
import { decodeCallSummary } from '../../core/ingestion/taint/call-summary-codec.js';
import { decodeReachingDefReason } from '../../core/ingestion/cfg/reaching-def-reason-codec.js';
import {
assertSymbolIdentity,
assertIdentityFields,
assertQueryIdentity,
} from './query-result-integrity.js';
/**
* Parse the `<fnLine>` segment out of a `BasicBlock` id (1-based function start
@ -90,14 +95,19 @@ const INTERPROC_NODE_BUDGET = 5000;
* `classifyPdgBridgeEvidence`); this is the same fact, read at the descent side.
*/
function parseCalleeIdsCell(raw: unknown): { ids: string[]; truncated: boolean } {
assertIdentityFields(raw);
const ids: string[] = [];
let truncated = false;
if (!String(raw ?? '').trim()) return { ids, truncated };
// Split on the SHARED CALLEE_ID_SEP (tab) — ids embed file paths / multi-word
// C++ type tokens that can contain a space, so a space split would fragment
// them. Producer (calleeIdsOfBlock) joins with the same constant.
for (const id of String(raw ?? '').split(CALLEE_ID_SEP)) {
if (id === CALLEES_TRUNCATED_SENTINEL) truncated = true;
else if (id) ids.push(id);
else {
assertSymbolIdentity(id);
ids.push(id);
}
}
return { ids, truncated };
}
@ -218,6 +228,7 @@ async function selfReachingDefEdgesByBlock(
{ ids: blockIds },
);
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0);
const id = String(r['id'] ?? '');
if (!id) continue;
const decoded = decodeReachingDefReason(r['reason']);
@ -297,6 +308,7 @@ async function pdgStatementsForBlocks(
// Narrow the awaited rows ONCE at the boundary to a typed record shape; read
// the aliased cells via bracket access with String()/Number() coercion.
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0);
const id = String(r['id'] ?? '');
const line = Number(r['line'] ?? 0);
if (!id || !Number.isFinite(line) || line <= 0) continue;
@ -501,6 +513,10 @@ async function projectBlocksToSymbols(deps: {
// non-aliased row shape) — no per-field `as any`, matching the typed-row
// pattern used elsewhere in this file (e.g. lines ~264, ~1309, ~1386).
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0, [
['name', 1],
['label', 2],
]);
resolved.push({
id: String(r['id'] ?? r['0'] ?? ''),
name: String(r['name'] ?? r['1'] ?? ''),
@ -1718,6 +1734,7 @@ async function bfsReachableBlocks(input: {
// Narrow the awaited rows ONCE at the boundary (executeParameterized returns
// any[]) to a typed record shape, then read the aliased `id` via bracket
// access — no `as any` sprayed per field.
for (const row of rawRows) assertQueryIdentity(row, 'id', 0);
const rows = rawRows.slice(0, stepLimit) as Array<Record<string, unknown>>;
depthReached = depth + 1;
if (rawRows.length > stepLimit) truncatedByLimit = true;
@ -1796,6 +1813,10 @@ async function calleeIdsByBlock(
// Narrow the awaited rows ONCE at the boundary to a typed record shape; read
// the aliased cells via bracket access — no per-field `as any`.
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0, [
['calleeIds', 1],
['callees', 2],
]);
const blockId = String(r['id'] ?? '');
if (!blockId) continue;
// ONE pass over the cell classifies BOTH facts — a second full split just to
@ -1877,6 +1898,7 @@ async function calleesWithReturnFlow(
{ ids: calleeIds },
);
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0);
const id = String(r['id'] ?? '');
if (!id) continue;
const decoded = decodeCallSummary(r['reason']);
@ -1931,6 +1953,7 @@ async function resolveCalleeSpans(
// the aliased columns via bracket access with Number()/String() coercion —
// no per-field `as any` (the same boundary-narrowing the typed helpers use).
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0, [['filePath', 1]]);
const id = String(r['id'] ?? '');
const filePath = String(r['filePath'] ?? '');
const startLine = Number(r['startLine']);
@ -2168,6 +2191,7 @@ async function interproceduralDescent(input: {
seedBlockQuery(anchorClause, probeLimit),
queryParams,
);
for (const row of rawSeedRows) assertQueryIdentity(row, 'id', 0);
const exceeded = rawSeedRows.length > stepLimit;
const seeds = rawSeedRows
.slice(0, stepLimit)
@ -2353,6 +2377,7 @@ export async function runImpactPDG(deps: RunPdgImpactDeps): Promise<PdgImpactRes
seedBlockQuery(anchorClause, probeLimit),
queryParams,
);
for (const row of rawSeedRows) assertQueryIdentity(row, 'id', 0);
const seedRows = rawSeedRows.slice(0, stepLimit) as Array<Record<string, unknown>>;
let seedBlocks: string[] = seedRows
.map((r) => String(r['id'] ?? ''))

57
gitnexus/src/mcp/local/query-result-integrity.ts Normal file
View file

@ -0,0 +1,57 @@
/** Shared integrity boundary for identities returned by impact/context queries. */
export const SYMBOL_IDENTITY_RECOVERY_SUGGESTION =
'Run gitnexus analyze --force from the affected repository root to rebuild the index.';
export class SymbolIdentityError extends Error {
constructor() {
super('The index returned an invalid symbol identity. ' + SYMBOL_IDENTITY_RECOVERY_SUGGESTION);
this.name = 'SymbolIdentityError';
}
}
/** Validate database identities before using them as graph traversal anchors. */
export function assertSymbolIdentity(id: unknown, expectedUid?: string): asserts id is string {
if (
typeof id !== 'string' ||
!id.trim() ||
id.includes('\0') ||
(expectedUid !== undefined && id !== expectedUid)
) {
throw new SymbolIdentityError();
}
}
/** Read either native row shape without turning an absent row into a TypeError. */
export function queryRowValue(row: unknown, key: string, index: number): unknown {
if (typeof row !== 'object' || row === null) return undefined;
const value = row as Record<string, unknown>;
return value[key] ?? value[index];
}
/** Optional labels/paths may be empty or NULL; NUL is never a usable identity. */
export function assertIdentityFields(...values: unknown[]): void {
for (const value of values) {
if (
value !== null &&
value !== undefined &&
(typeof value !== 'string' || value.includes('\0'))
) {
throw new SymbolIdentityError();
}
}
}
export function assertQueryIdentity(
row: unknown,
idKey: string,
idIndex: number,
fields: ReadonlyArray<readonly [string, number]> = [],
): void {
assertSymbolIdentity(queryRowValue(row, idKey, idIndex));
for (const [key, index] of fields) assertIdentityFields(queryRowValue(row, key, index));
}
/** Ordinary query failures may degrade; corrupt identities must reach the outer error envelope. */
export function rethrowSymbolIdentityError(error: unknown): void {
if (error instanceof SymbolIdentityError) throw error;
}

2
gitnexus/src/mcp/resources.ts
View file

@ -351,7 +351,7 @@ async function getContextResource(backend: LocalBackend, repoName?: string): Pro
// Check staleness using the current on-disk lastCommit (not the cached handle)
const repoPath = repo.repoPath;
const lastCommit = freshMeta?.lastCommit ?? repo.lastCommit ?? 'HEAD';
const lastCommit = freshMeta?.lastCommit ?? repo.lastCommit ?? '';
const staleness = repoPath
? checkStaleness(repoPath, lastCommit)
: { isStale: false, commitsBehind: 0 };

2
gitnexus/src/mcp/tools.ts
View file

@ -400,7 +400,7 @@ AFTER THIS: Review affected processes. Use context() on high-risk symbols. READ
GIT WORKTREE SUPPORT: GitNexus automatically detects when the MCP server was launched from inside a linked git worktree and runs git diff against that worktree — no extra parameters needed in the common case. Pass "worktree" explicitly only when the server was started from a different directory than the worktree you are editing (e.g., the server runs from the canonical root but your changes are in a linked worktree at a different path).
Returns: changed symbols, affected processes, and a risk summary.
- partial: true — a step failed and was swallowed, so the result is incomplete and risk_level is "unknown" instead of a ranked level. Two causes, with different blast radii: the symbol query (or an unparseable diff) degrades everything — changed_symbols, both counts, and the processes derived from them — while a failed process lookup degrades only affected_processes and the risk read off it, leaving the changed-symbol counts sound. changed_count:0 with partial:true is NOT a clean pre-commit check; re-run before treating the diff as safe.
- partial: true — mapping is incomplete, so risk_level is "unknown" instead of a ranked level. A failed symbol query (or an unparseable diff) degrades changed_symbols, both counts, and derived processes; a failed process lookup degrades only affected_processes and risk, leaving changed-symbol counts sound. unmapped_files lists changed supported source files with no mapped symbols, including source renames without hunks: their symbols may be missing, unindexed, or outside indexed ranges even when every query succeeded. Rebuild the index and inspect those diffs; retry alone may not resolve this state. changed_count:0 with partial:true is NOT a clean pre-commit check.
- truncated: true — the changed_symbols LISTING was capped for this response. summary.changed_count counts every symbol the run observed: the true total normally, a LOWER BOUND when partial:true. Compare it with the array length rather than trusting the array.`,
annotations: READ_ONLY_TOOL_ANNOTATIONS,
inputSchema: {

15
gitnexus/src/server/api.ts
View file

@ -12,6 +12,7 @@ import {
acquireIndexLock,
IndexLockTimeoutError,
requireExclusiveIndexLock,
sweepStagingArtifacts,
type IndexLockHandle,
} from '../storage/index-lock.js';
import { ensurePrivateSharedGraph } from '../core/shared-store-analyze.js';
@ -550,7 +551,7 @@ const mapGraphRelationshipRow = (row: any): GraphRelationship => ({
sourceId: row.sourceId,
targetId: row.targetId,
confidence: row.confidence,
reason: row.reason,
reason: row.reason ?? '',
step: row.step,
});
@ -2152,11 +2153,21 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
// for the whole embedding write, released in the finally below.
let slotLock: IndexLockHandle | undefined;
try {
slotLock = await acquireIndexLock(storagePath);
slotLock = await acquireIndexLock(storagePath, { sweep: false });
requireExclusiveIndexLock(
slotLock,
`Cannot acquire the index lock at ${storagePath}; refusing an unlocked embedding run.`,
);
// This writer cannot recover staged generations. Preserve their
// receipts, including malformed ones, before sweeping or writing.
const recoveryCheckpoint = (await loadMeta(storagePath))?.embeddingCheckpoint;
if (recoveryCheckpoint && Object.hasOwn(recoveryCheckpoint, 'recovery')) {
throw new Error(
'Cannot generate embeddings: the index checkpoint references staged embeddings. ' +
'Run `gitnexus analyze` to recover them first.',
);
}
sweepStagingArtifacts(storagePath);
// Writes go to the slot's own graph; a shared-store checkout
// reading an immutable commit graph (#3352) takes a private copy.
if (!(await ensurePrivateSharedGraph(storagePath, () => {}))) {

167
gitnexus/src/storage/embedding-recovery.ts Normal file
View file

@ -0,0 +1,167 @@
/**
* Filesystem-only staged embedding provenance. Keep this independent of native
* and model imports: every index-lock caller needs the retention decision.
*/
import {
closeSync,
constants,
fstatSync,
lstatSync,
openSync,
readFileSync,
realpathSync,
} from 'node:fs';
import path from 'node:path';
import type { EmbeddingRecoveryReference } from './repo-meta.js';
import { INDEX_METADATA_FILE, LEGACY_METADATA_FILE } from './storage-constants.js';
const STAGING_FILENAME =
/^lbug\.staging\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
export const FAMILY_SUFFIXES = [
'',
'.wal',
'.shadow',
'.wal.checkpoint',
'.lock',
'.checkpoint.intent.lock',
'.checkpoint.apply.lock',
] as const;
export interface ResolvedEmbeddingRecovery extends EmbeddingRecoveryReference {
dbPath: string;
/** Exact basenames, never a prefix match that can preserve another generation. */
familyFiles: string[];
}
const isRecord = (value: unknown): value is Record<string, unknown> =>
value !== null && typeof value === 'object' && !Array.isArray(value);
const isNonemptyString = (value: unknown): value is string =>
typeof value === 'string' && value.length > 0;
const isNodeIds = (value: unknown): value is string[] =>
Array.isArray(value) && value.every(isNonemptyString);
const isCount = (value: unknown): value is number =>
typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
/**
* Resolve only an explicit interrupted-generation receipt in this canonical
* slot. This validates provenance, not native contents or current identity;
* those checks must pass separately before any rows can be reused.
*/
export const resolveEmbeddingRecovery = (
lockDir: string,
checkpoint: unknown,
): ResolvedEmbeddingRecovery | undefined => {
if (!isRecord(checkpoint) || !isRecord(checkpoint.recovery)) return undefined;
if (checkpoint.kind !== undefined && checkpoint.kind !== 'interrupted') return undefined;
if (
!isNonemptyString(checkpoint.at) ||
!Number.isFinite(Date.parse(checkpoint.at)) ||
!isCount(checkpoint.nodesProcessed) ||
!isCount(checkpoint.totalNodes) ||
checkpoint.nodesProcessed > checkpoint.totalNodes ||
!isCount(checkpoint.chunksProcessed) ||
!isNonemptyString(checkpoint.model) ||
!isCount(checkpoint.dimensions) ||
checkpoint.dimensions === 0 ||
!isNonemptyString(checkpoint.provider) ||
(checkpoint.pendingNodeIds !== undefined && !isNodeIds(checkpoint.pendingNodeIds))
) {
return undefined;
}
const recovery = checkpoint.recovery;
if (
!isNonemptyString(recovery.stagingFile) ||
!STAGING_FILENAME.test(recovery.stagingFile) ||
!isNonemptyString(recovery.schemaFingerprint) ||
!isNodeIds(recovery.unsafeNodeIds)
) {
return undefined;
}
const unsafeNodeIds = new Set(recovery.unsafeNodeIds);
if (
isNodeIds(checkpoint.pendingNodeIds) &&
checkpoint.pendingNodeIds.some((nodeId) => !unsafeNodeIds.has(nodeId))
) {
return undefined;
}
try {
const canonicalDir = realpathSync(lockDir);
if (!lstatSync(canonicalDir).isDirectory()) return undefined;
const familyFiles = FAMILY_SUFFIXES.map((suffix) => recovery.stagingFile + suffix);
for (const [index, filename] of familyFiles.entries()) {
try {
// lstat refuses both live and dangling symlinks, without following one
// to a database outside the slot. The base file must exist.
if (!lstatSync(path.join(canonicalDir, filename)).isFile()) return undefined;
} catch (error) {
if (index > 0 && (error as NodeJS.ErrnoException).code === 'ENOENT') continue;
return undefined;
}
}
return {
dbPath: path.join(canonicalDir, recovery.stagingFile),
stagingFile: recovery.stagingFile,
schemaFingerprint: recovery.schemaFingerprint,
unsafeNodeIds: [...unsafeNodeIds],
familyFiles,
};
} catch {
return undefined;
}
};
/** Synchronous mirror of loadMeta's primary-first, absent-only fallback rule. */
export const readEmbeddingRecovery = (lockDir: string): ResolvedEmbeddingRecovery | undefined => {
let metadataPath = path.join(lockDir, INDEX_METADATA_FILE);
let descriptor: number | undefined;
const noFollow = constants.O_NOFOLLOW ?? 0;
const flags = constants.O_RDONLY | noFollow | (constants.O_NONBLOCK ?? 0);
try {
try {
descriptor = openSync(metadataPath, flags);
} catch (error) {
const code = (error as NodeJS.ErrnoException).code;
if (code !== 'ENOENT' && code !== 'ENOTDIR') return undefined;
// Windows cannot open with O_NOFOLLOW: an open of a dangling symlink
// reports ENOENT, but that existing primary entry must prevent fallback.
try {
lstatSync(metadataPath);
return undefined;
} catch (statError) {
const statCode = (statError as NodeJS.ErrnoException).code;
if (statCode !== 'ENOENT' && statCode !== 'ENOTDIR') return undefined;
}
metadataPath = path.join(lockDir, LEGACY_METADATA_FILE);
descriptor = openSync(metadataPath, flags);
}
const opened = fstatSync(descriptor, { bigint: true });
const entry = lstatSync(metadataPath, { bigint: true });
// Check the opened file itself and match the current non-symlink entry.
// This also refuses replacement on platforms without O_NOFOLLOW.
if (
!opened.isFile() ||
!entry.isFile() ||
(noFollow === 0 && opened.ino === 0n) ||
opened.dev !== entry.dev ||
opened.ino !== entry.ino
) {
return undefined;
}
const meta: unknown = JSON.parse(readFileSync(descriptor, 'utf8'));
if (!isRecord(meta)) return undefined;
// storagePath describes the flat/cache root, including in branch-slot
// metadata. The current locked directory is the generation boundary.
return resolveEmbeddingRecovery(lockDir, meta.embeddingCheckpoint);
} catch {
return undefined;
} finally {
if (descriptor !== undefined) {
try {
closeSync(descriptor);
} catch {
/* best-effort */
}
}
}
};

7
gitnexus/src/storage/git.ts
View file

@ -827,6 +827,8 @@ export interface DiffHunk {
export interface FileDiff {
filePath: string;
/** Decoded pre-rename path; either side can identify a source-file change. */
oldFilePath?: string;
hunks: DiffHunk[];
}
@ -1061,7 +1063,10 @@ export function parseDiffHunksResult(diffOutput: string): DiffHunkParseResult {
} else {
unparsedGitHeaders++;
}
} else if (line.startsWith('rename to ')) {
} else if (!inHunk && line.startsWith('rename from ')) {
const oldFilePath = decodeGitPathToken(line.slice('rename from '.length));
if (current && oldFilePath) current.oldFilePath = oldFilePath;
} else if (!inHunk && line.startsWith('rename to ')) {
const filePath = pathFromRenameTo(line);
if (!filePath) continue;
if (current) current.filePath = filePath;

9
gitnexus/src/storage/index-lock.ts
View file

@ -62,6 +62,7 @@ import path from 'node:path';
import os from 'node:os';
import { randomBytes, randomUUID, createHash } from 'node:crypto';
import { isProcessAlive } from '../utils/process-identity.js';
import { readEmbeddingRecovery } from './embedding-recovery.js';
const LOCK_FILENAME = 'analyze.lock';
const LOCK_RECORD_VERSION = 1 as const;
@ -433,8 +434,9 @@ const deniedCreateHandle = (
/**
* Delete orphaned build/staging artifacts left in the lock directory by a
* crashed prior writer. Safe precisely because we hold the exclusive lock: no
* other writer can be creating these here right now, so anything present is a
* crash orphan. Matches this slot's staging files ONLY — never `lbug` itself,
* other writer can be creating these here right now. A checkpoint-referenced
* generation is retained for embedding recovery; all other stages are orphans.
* Matches this slot's staging files ONLY — never `lbug` itself,
* never `lbug.wal`/`lbug.shadow` (the LIVE index's own sidecars), and never a
* `branches/<slug>/` sub-slot (which owns its own lock + sweep). Non-recursive.
*/
@ -442,6 +444,7 @@ export const sweepStagingArtifacts = (lockDir: string, log?: (msg: string) => vo
// Matches `lbug.new`, `lbug.new.wal`, `lbug.staging.<id>`, `lbug.staging.<id>.wal`, …
// Does NOT match `lbug`, `lbug.wal`, `lbug.shadow`.
const stagingRe = /^lbug\.(staging\..+|new(\..+)?)$/;
const retained = new Set(readEmbeddingRecovery(lockDir)?.familyFiles ?? []);
let removed = 0;
let entries: string[];
try {
@ -450,7 +453,7 @@ export const sweepStagingArtifacts = (lockDir: string, log?: (msg: string) => vo
return;
}
for (const name of entries) {
if (!stagingRe.test(name)) continue;
if (!stagingRe.test(name) || retained.has(name)) continue;
try {
unlinkSync(path.join(lockDir, name));
removed++;

9
gitnexus/src/storage/parse-cache.ts
View file

@ -822,7 +822,14 @@ import { copyV8CacheIfPresent, tryLoadV8Cache, writeV8CacheFile } from './v8-sid
// `handlerReceiver` hint. Warm v123 Go worker results carry no routes.
// v125 (#3402): Go route hints now honor lexical declarations and captured writes;
// namespace imports retain whether their local name comes from the package clause.
const SCHEMA_BUMP = 125;
// v126 (#3446): SDK positional tool registrations now emit tool definitions,
// exact handler identities, and an opt-out from unrelated file-level flows.
// Warm v125 worker results omit these definitions and must be re-extracted.
// v127 (#3450): Destructured member writes invalidate SDK registration evidence.
// Warm v126 worker results can retain false tools after a method replacement.
// v128 (#3450): SDK namespace imports now prove positional tool receivers.
// Warm v127 worker results omit these definitions and must be re-extracted.
const SCHEMA_BUMP = 128;
const GITNEXUS_PKG_VERSION = (() => {
try {
// package.json sits at gitnexus/package.json — two levels up from

14
gitnexus/src/storage/repo-meta.ts
View file

@ -43,6 +43,15 @@ export type ContentRetention = 'full' | 'symbol' | 'none';
export type FtsProfile = 'full' | 'symbol-no-file-content' | 'name-only';
export const CONTENT_RETENTION_SCHEMA_VERSION = 1;
/** Exact staged generation whose completed embedding groups can survive a retry. */
export interface EmbeddingRecoveryReference {
/** A run-minted basename within this metadata file's index slot. */
stagingFile: string;
schemaFingerprint: string;
/** Active-window and inherited incomplete groups: never reusable until completed. */
unsafeNodeIds: string[];
}
/**
* Versioned receipt for the analyzer process that produced an index.
*
@ -521,6 +530,11 @@ export interface RepoMeta {
* subset of their chunks; for `'partial'` they hold none.
*/
pendingNodeIds?: string[];
/**
* Interrupted atomic builds only. This does not publish the staged graph
* or advance live embedding statistics; it identifies a recovery source.
*/
recovery?: EmbeddingRecoveryReference;
};
/**
* Name of the git branch this index represents (#2106). Absent for the

54
gitnexus/test/fixtures/lang-resolution/swift-injected-closure-call/Caller.swift vendored Normal file
View file

@ -0,0 +1,54 @@
import Foundation
enum Example {
static func runScenario() -> Int {
makeValue(input: 1)
}
}
final class Service {
private let clock: () -> Date
init(clock: @escaping () -> Date) {
self.clock = clock
}
func refreshValue() -> Date {
clock()
}
func refreshWithLocalClock() -> Int {
func clock() -> Int { 2 }
return clock()
}
}
class BaseService {
let clock: () -> Date
init(clock: @escaping () -> Date) {
self.clock = clock
}
}
final class DerivedService: BaseService {
func refreshInheritedValue() -> Date {
clock()
}
}
final class LabeledService {
let first: Int = 1
func first(where value: Bool) -> Int {
value ? 2 : 0
}
func refreshLabeled() -> Int {
first(where: true)
}
}
class PrivateBase {
private let clock: () -> Int = { 1 }
}

39
gitnexus/test/fixtures/lang-resolution/swift-injected-closure-call/Helpers.swift vendored Normal file
View file

@ -0,0 +1,39 @@
import Foundation
extension Example {
static func makeValue(input: Int) -> Int {
input + 1
}
}
enum Other {
private static func makeValue(other: String) -> Int {
-1
}
static func clock() -> Date {
Date.distantPast
}
}
extension DerivedService {
func refreshInheritedFromExtension() -> Date {
clock()
}
}
extension BaseService {
func refreshOwnFromExtension() -> Date {
clock()
}
}
final class PrivateDerived: PrivateBase {
func clock() -> Int {
2
}
func refreshPrivateAncestor() -> Int {
clock()
}
}

1
gitnexus/test/fixtures/lang-resolution/typescript-mcp-tools/src/handlers.ts vendored Normal file
View file

@ -0,0 +1 @@
export function importedHandler() { return 'imported'; }

5
gitnexus/test/fixtures/lang-resolution/typescript-mcp-tools/src/server.js vendored Normal file
View file

@ -0,0 +1,5 @@
import { McpServer as Server } from '@modelcontextprotocol/sdk/server/mcp.js';
const server = new Server({ name: 'javascript', version: '1' });
function jsPing() { return 'pong'; }
server.registerTool('js_ping', { description: 'Ping JavaScript' }, jsPing);

52
gitnexus/test/fixtures/lang-resolution/typescript-mcp-tools/src/server.ts vendored Normal file
View file

@ -0,0 +1,52 @@
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { importedHandler } from './handlers.js';
const server = new McpServer({ name: 'fixture', version: '1' });
function formatSearch(query: string) { return query; }
function lookupSearch(query: string) { return formatSearch(query); }
export function searchFiles(query: string) { return lookupSearch(query); }
function formatFile(file: string) { return file; }
function lookupFile(file: string) { return formatFile(file); }
export const readFile = (file: string) => lookupFile(file);
function formatOther() { return 'other'; }
function lookupOther() { return formatOther(); }
export function unrelatedEntry() { return lookupOther(); }
server.registerTool('search-files', { description: 'Search files' }, searchFiles);
server.tool('read_file', 'Read a file', {}, readFile);
server.registerTool('inline_callback', {}, async () => 'inline');
server.tool('imported_callback', importedHandler);
function install(server: McpServer, searchFiles: () => string) {
server.registerTool('parameter_callback', {}, searchFiles);
}
let mutable = () => 'mutable';
server.tool('mutable_callback', mutable);
function replaced() { return 'before'; }
replaced = () => 'after';
server.tool('reassigned_callback', replaced);
{
const searchFiles = 'not callable';
server.tool('shadowed_callback', searchFiles);
}
const alias = readFile;
server.tool('alias_callback', alias);
const expressionHandler = function () { return 'expression'; };
server.registerTool('function_expression_tool', {}, expressionHandler);
{
const handler = () => lookupSearch('first');
server.tool('first_block_callback', handler);
}
{
const handler = () => lookupFile('second');
server.tool('second_block_callback', handler);
}

4
gitnexus/test/fixtures/lang-resolution/typescript-mcp-tools/src/tools.ts vendored Normal file
View file

@ -0,0 +1,4 @@
export const tools = [
{ name: 'manifest_tool', description: 'Existing object manifest', inputSchema: {} },
{ name: 'read_file', description: 'Duplicate manifest entry', inputSchema: {} },
];

12
gitnexus/test/fixtures/local-backend-seed.ts vendored
View file

@ -1,4 +1,5 @@
import type { FTSIndexDef } from '../helpers/test-indexed-db.js';
import { FTS_INDEXES } from '../../src/core/search/fts-schema.js';
export const LOCAL_BACKEND_SEED_DATA = [
// Files
@ -60,9 +61,8 @@ export const LOCAL_BACKEND_SEED_DATA = [
CREATE (c)-[:CodeRelation {type: 'HAS_METHOD', confidence: 1.0, reason: 'class-method', step: 0}]->(m)`,
];
export const LOCAL_BACKEND_FTS_INDEXES: FTSIndexDef[] = [
{ table: 'Function', indexName: 'function_fts', columns: ['name', 'content', 'description'] },
{ table: 'Class', indexName: 'class_fts', columns: ['name', 'content', 'description'] },
{ table: 'Method', indexName: 'method_fts', columns: ['name', 'content', 'description'] },
{ table: 'File', indexName: 'file_fts', columns: ['name', 'content'] },
];
// Healthy-backend fixtures must mirror the complete configured search index set.
// The old four-table subset is now correctly reported as partial FTS coverage.
export const LOCAL_BACKEND_FTS_INDEXES: FTSIndexDef[] = FTS_INDEXES.map(
({ table, indexName, properties }) => ({ table, indexName, columns: [...properties] }),
);

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