scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-10-05 02:43:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Merge remote-tracking branch 'upstream/main' into feat/mcp-otel-metrics-1351

Browse source
This commit is contained in:
Nathan Hangen 2026-05-16 16:12:14 -04:00
commit 8796466848
387 changed files with 29239 additions and 1659 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
.github/workflows/ci.yml vendored
View file

@ -11,14 +11,14 @@ permissions:
# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
# Hardcoded `CI-` prefix (not `${{ github.workflow }}`) because this workflow is
# invoked as a reusable workflow from publish.yml and release-candidate.yml. In
# called-workflow context `github.workflow` evaluation is ambiguous across GitHub
# Actions versions, and a prefix that could resolve to the caller's name would
# share a concurrency group with the caller → deadlock. A literal prefix is
# immune. Direct `pull_request` invocations use `CI-<ref>`; invocations from a
# reusable-workflow caller fall into a per-run-unique group that never serializes
# with the caller. `push` to main is handled by release-candidate.yml, which
# calls this workflow once before publishing.
# invoked as a reusable workflow from publish.yml. In called-workflow context
# `github.workflow` evaluation is ambiguous across GitHub Actions versions, and a
# prefix that could resolve to the caller's name would share a concurrency group
# with the caller → deadlock. A literal prefix is immune. Direct `pull_request`
# invocations use `CI-<ref>`; invocations from a reusable-workflow caller fall
# into a per-run-unique group that never serializes with the caller. `push` to
# main is handled by publish.yml (RC mode), which calls this workflow once
# before publishing.
concurrency:
group: ${{ github.event_name == 'pull_request' && format('CI-{0}', github.ref) || format('CI-nested-{0}', github.run_id) }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

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

@ -158,6 +158,8 @@ jobs:
github_token: ${{ secrets.GITHUB_TOKEN }}
allowed_non_write_users: '*'
show_full_output: true
# Review posts use Bash (`gh`, etc.); default mode asks for approval — impossible in CI.
claude_args: '--dangerously-skip-permissions'
plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
plugins: 'code-review@claude-code-plugins'
prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ steps.pr.outputs.number }}'
prompt: '/code-review:code-review https://github.com/${{ github.repository }}/pull/${{ steps.pr.outputs.number }} --comment'

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

@ -25,6 +25,15 @@ on:
a gitnexus/package.json whose version matches the tag.
required: true
type: string
# Explicit secret contract — callers pass these by name. Replaces the
# blanket `secrets: inherit` pattern (zizmor `secrets-inherit` audit).
# GHCR auth uses the implicit GITHUB_TOKEN; only Docker Hub credentials
# need to be passed through.
secrets:
DOCKERHUB_USERNAME:
required: true
DOCKERHUB_TOKEN:
required: true
permissions:
contents: read
@ -73,7 +82,7 @@ jobs:
steps:
# Only the workflow_call path requires a non-empty `inputs.tag` — callers
# (e.g. release-candidate.yml) must pass the RC tag explicitly. On direct
# (publish.yml in RC mode) must pass the RC tag explicitly. On direct
# tag pushes the tag comes from `github.ref`, so `inputs.tag` is always
# empty and validating it here would break every real release (#1064).
# The downstream "Verify tag matches gitnexus/package.json version" step
@ -135,7 +144,7 @@ jobs:
uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
- name: Install Cosign
uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003 # v4.1.1
uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
- name: Log in to GitHub Container Registry
if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}

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

@ -1,62 +1,421 @@
name: Publish to npm
name: Publish
# ─────────────────────────────────────────────────────────────────────────────
# Sole publisher for the `gitnexus` npm package, GitHub Releases, and Docker
# images. Replaces the former two-workflow design — see issue #1609 for the
# double-publish race this unification closes.
#
# Two release modes, both routed through this file:
# • Release candidate (rc) — triggered by push to `main` or workflow_dispatch.
# The RC path computes the next rc version, applies it in-CI, pushes a
# detached release commit with v<X.Y.Z>-rc.<N> + rc/<SHA> marker
# atomically, then publishes to npm with --tag rc and creates a GitHub
# prerelease. RC-only docker.yml invocation follows.
# • Stable — triggered by push of a v<X.Y.Z> tag (no -rc.*
# suffix). Verifies package.json matches the tag, publishes to npm with
# --tag latest, creates a stable GitHub Release. No docker (RC-only).
#
# ⚠️ SELF-TRIGGER INVARIANT — DO NOT WEAKEN ⚠️
# The `tags:` filter below uses a negative glob `'!v*-rc.*'` to prevent the
# workflow from re-triggering itself when the RC path pushes its own v-tag.
# Without this exclusion, every RC publish double-fires (the bug fixed by
# #1609). If a NEW prerelease channel is introduced (e.g. `-beta.N`,
# `-alpha.N`, `-next.N`), the negative-glob list MUST be extended in
# lock-step or self-trigger returns. The same invariant applies to the
# `Classify` step further below — its accepted-tag regex must align with
# the trigger filter's exclusion list.
# ─────────────────────────────────────────────────────────────────────────────
on:
push:
branches: [main]
paths-ignore:
- '**.md'
- 'docs/**'
- 'LICENSE'
tags:
# Negative-globbed exclusion of RC tags this workflow itself produces
# (see the SELF-TRIGGER INVARIANT in the header comment).
- 'v*'
# No workflow-level permissions — scoped per job below.
- '!v*-rc.*'
workflow_dispatch:
inputs:
bump:
description: >-
Cycle policy. 'auto' (default) continues the active rc cycle on
this branch if there is one, otherwise bumps patch from latest.
Choose 'patch' / 'minor' / 'major' to explicitly start or reset
an rc cycle.
required: false
default: 'auto'
type: choice
options:
- auto
- patch
- minor
- major
force:
description: 'Publish even when HEAD already has an rc marker'
required: false
default: 'false'
type: choice
options:
- 'false'
- 'true'
# Workflow-level deny-all; each job declares the minimum it needs.
permissions: {}
# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
# Tag refs are unique per release, so distinct tags run in parallel. Re-pushes of the
# same tag serialize. cancel-in-progress: false — never cancel a publish mid-flight.
# Distinct refs (refs/heads/main, refs/tags/v*) run in parallel. The
# release-PR-skip in rc-guard is the load-bearing invariant that prevents
# an RC main-push and a stable tag-push colliding on the same release commit.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
# ── Phase 1: classify the triggering event into a release mode ─────────────
route:
name: Classify release event
runs-on: ubuntu-latest
timeout-minutes: 2
permissions:
contents: read
outputs:
mode: ${{ steps.classify.outputs.mode }}
head_sha: ${{ steps.classify.outputs.head_sha }}
bump_input: ${{ inputs.bump }}
force_input: ${{ inputs.force }}
steps:
- name: Classify
id: classify
shell: bash
env:
EVENT_NAME: ${{ github.event_name }}
GH_REF: ${{ github.ref }}
GH_REF_NAME: ${{ github.ref_name }}
run: |
set -euo pipefail
HEAD_SHA="${GITHUB_SHA}"
echo "head_sha=${HEAD_SHA}" >> "$GITHUB_OUTPUT"
# Sanitize before logging (annotation-injection defense in depth).
REF_SAFE="${GH_REF//::/__}"
REF_NAME_SAFE="${GH_REF_NAME//::/__}"
echo "event=${EVENT_NAME} ref=${REF_SAFE} ref_name=${REF_NAME_SAFE}"
MODE=""
case "${EVENT_NAME}" in
workflow_dispatch)
# Manual dispatch is only valid on main — that's the only ref
# where a real publish makes sense.
if [ "${GH_REF}" = "refs/heads/main" ]; then
MODE="rc"
else
echo "::error::workflow_dispatch is only permitted on refs/heads/main (got ${REF_SAFE})."
exit 1
fi
;;
push)
case "${GH_REF}" in
refs/heads/main)
MODE="rc"
;;
refs/tags/v*)
# The trigger filter already excluded v*-rc.* tags. Anything
# reaching here is either a stable semver or a malformed v*.
TAG="${GH_REF#refs/tags/}"
if [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
MODE="stable"
else
echo "::error::malformed v* tag rejected: ${REF_NAME_SAFE}"
echo "::error::stable tags must match ^v[0-9]+\\.[0-9]+\\.[0-9]+\$"
exit 1
fi
;;
*)
echo "::error::unexpected push ref ${REF_SAFE} reached publish workflow."
exit 1
;;
esac
;;
*)
echo "::error::unsupported event ${EVENT_NAME}."
exit 1
;;
esac
echo "mode=${MODE}" >> "$GITHUB_OUTPUT"
echo "Classified as mode=${MODE}"
# ── Phase 2 (RC only): dedup marker + release-PR skip ──────────────────────
rc-guard:
name: RC guard (marker + release-PR skip)
needs: route
if: needs.route.outputs.mode == 'rc'
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
contents: read
pull-requests: read
outputs:
should_run: ${{ steps.decide.outputs.should_run }}
head_sha: ${{ steps.decide.outputs.head_sha }}
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 0
fetch-tags: true
# rc-guard reads only — no git pushes from this job. Skip the
# default extraheader credential persistence (artipacked audit).
persist-credentials: false
- name: Decide
id: decide
shell: bash
env:
FORCE: ${{ inputs.force }}
BUMP_INPUT: ${{ inputs.bump }}
EVENT_NAME: ${{ github.event_name }}
GH_TOKEN: ${{ github.token }}
REPO: ${{ github.repository }}
run: |
set -euo pipefail
HEAD_SHA=$(git rev-parse HEAD)
echo "head_sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
if [ "$FORCE" = "true" ]; then
echo "Force flag set — running regardless of marker tag."
echo "should_run=true" >> "$GITHUB_OUTPUT"
exit 0
fi
# Explicit cycle reset on dispatch bypasses dedup.
if [ "$EVENT_NAME" = "workflow_dispatch" ] \
&& [ -n "${BUMP_INPUT:-}" ] \
&& [ "${BUMP_INPUT:-auto}" != "auto" ]; then
echo "Explicit bump=$BUMP_INPUT — bypassing marker dedup."
echo "should_run=true" >> "$GITHUB_OUTPUT"
exit 0
fi
# ── Skip when the merge commit corresponds to a release ───────────
# This skip is load-bearing: it prevents an RC build firing on the
# release-PR commit from racing the imminent stable-tag push on the
# same SHA. Two complementary checks:
# 1. HEAD subject matches `chore: release vX.Y.Z` (the canonical
# release-PR title). Anchored to require the bare title or the
# squash-merge `(#NNNN)` suffix exactly. Case-insensitive so
# `Chore: Release v1.2.3` (IDE auto-capitalization) still
# matches — prior commit-author conventions left the door open.
# 2. Squash-merged PR carries the `release` label.
# Either match suppresses the rc build — stable releases publish on
# the v-tag instead.
HEAD_SUBJECT="$(git log -1 --pretty=%s HEAD)"
# Sanitize GitHub-Actions annotation prefixes before logging — even
# though %s strips newlines, a crafted subject containing `::error::`
# could forge log annotations.
HEAD_SUBJECT_SAFE="${HEAD_SUBJECT//::/__}"
RELEASE_SUBJECT_RE='^chore:[[:space:]]*release[[:space:]]+v[0-9]+\.[0-9]+\.[0-9]+([[:space:]]+\(#[0-9]+\))?$'
shopt -s nocasematch
if [[ "$HEAD_SUBJECT" =~ $RELEASE_SUBJECT_RE ]]; then
shopt -u nocasematch
echo "HEAD commit subject matches a release commit — skipping rc."
echo " subject (sanitised): $HEAD_SUBJECT_SAFE"
echo "should_run=false" >> "$GITHUB_OUTPUT"
exit 0
fi
shopt -u nocasematch
# Squash-merge commits include `(#NNNN)` at the end of the subject.
if [[ "$HEAD_SUBJECT" =~ \(#([0-9]+)\)[[:space:]]*$ ]]; then
PR_NUM="${BASH_REMATCH[1]}"
echo "Detected squash-merge of PR #$PR_NUM — checking labels."
if LABELS_JSON="$(gh pr view "$PR_NUM" --repo "$REPO" --json labels 2>/dev/null)"; then
if printf '%s' "$LABELS_JSON" | jq -e '.labels[] | select(.name == "release")' >/dev/null; then
echo "PR #$PR_NUM has the 'release' label — skipping rc."
echo "should_run=false" >> "$GITHUB_OUTPUT"
exit 0
fi
echo "PR #$PR_NUM has no 'release' label — proceeding."
else
# Lookup failure is not fatal — fall through to dedup check.
echo "::warning::Could not read labels for PR #${PR_NUM} — falling through."
fi
fi
# Dedup: is there already an rc/<HEAD_SHA> marker pointing at HEAD?
MARKER="rc/${HEAD_SHA}"
if git rev-parse "refs/tags/$MARKER" >/dev/null 2>&1; then
echo "HEAD already has marker $MARKER — skipping."
echo "should_run=false" >> "$GITHUB_OUTPUT"
else
echo "No marker on HEAD — proceeding."
echo "should_run=true" >> "$GITHUB_OUTPUT"
fi
# ── Phase 3: reusable CI gate ──────────────────────────────────────────────
# Runs for both rc (when guard says go) and stable. No `secrets:` passed —
# ci.yml and its entire reusable-workflow chain (ci-quality, ci-tests,
# ci-e2e, ci-scope-parity, ci-report) reference zero `secrets.*` values;
# passing any would be unused surface. GITHUB_TOKEN is implicit.
ci:
needs: [route, rc-guard]
if: ${{ always() && (needs.route.outputs.mode == 'stable' || needs.rc-guard.outputs.should_run == 'true') }}
uses: ./.github/workflows/ci.yml
permissions:
contents: read
actions: read
# No pull-requests:write — `ci.yml`'s save-pr-meta job is gated on
# `github.event_name == 'pull_request'`, so it never runs during a
# tag-triggered publish. Least-privilege for release-critical paths.
# ── Phase 4: publish to npm + push refs (RC path) ──────────────────────────
# INVARIANT: `timeout-minutes` MUST stay below the App-token TTL (~60 min
# for actions/create-github-app-token installation tokens). The atomic
# tag-push step relies on the token minted at job start; if the job ever
# runs longer than the TTL, the push fails with an opaque 401. If you
# need to raise the timeout, re-mint the token immediately before the
# `Create and push rc tags` step instead.
publish:
needs: ci
name: Publish to npm
needs: [route, rc-guard, ci]
if: ${{ always() && needs.ci.result == 'success' && (needs.route.outputs.mode == 'stable' || needs.rc-guard.outputs.should_run == 'true') }}
runs-on: ubuntu-latest
timeout-minutes: 15
timeout-minutes: 20
permissions:
# contents: write — RC path needs it for `git push --atomic` (v-tag +
# marker). Stable path runs in the same job and inherits the grant; it
# never invokes `git push`, so the elevated scope is unused there.
# id-token: write — npm provenance attestation.
contents: write
id-token: write
outputs:
# Two distinct step IDs feed this output; exactly one fires per run.
vtag: ${{ steps.rc-tags.outputs.vtag || steps.stable-vtag.outputs.vtag }}
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
# ── Mint short-lived GitHub App token (RC only) ──────────────────────
# Industry direction (2025-2026): GitHub Apps with
# `actions/create-github-app-token` over long-lived PATs for
# workflow-touching tag pushes. Same fine-grained permission surface,
# ~1h expiry, not tied to a user seat, organizationally auditable.
# Replaces a prior fine-grained PAT.
#
# Required secrets (set in repo Settings → Secrets and variables → Actions):
# secrets.RELEASE_APP_ID — the App's numeric ID
# secrets.RELEASE_APP_PRIVATE_KEY — the App's PEM private key
# (The App ID is technically not sensitive — it's visible on the App's
# settings page — but storing it as a secret is harmless and avoids
# mixing storage classes for the same App.)
# The App must be installed on this repository with:
# - Contents: write (push the v-tag and rc marker)
# - Workflows: write (because the v-tag's tree may touch
# .github/workflows/**, which the default
# GITHUB_TOKEN cannot author)
# - Metadata: read (required for the `gh api /users/<slug>[bot]`
# bot-identity lookup in the tag-push step)
- name: Mint GitHub App token (RC)
if: needs.route.outputs.mode == 'rc'
id: app-token
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
with:
# `client-id` is the renamed input that supersedes the deprecated
# `app-id` in v3.x. The action accepts the App's numeric ID or
# its Client ID under this name. We pass the numeric App ID,
# which the action resolves correctly.
client-id: ${{ secrets.RELEASE_APP_ID }}
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
# ── Separate checkout steps per mode ─────────────────────────────────
# Conditional `token:` expressions are footguns: empty string passed to
# actions/checkout fails opaquely, and `|| github.token` silently
# degrades a missing token to GITHUB_TOKEN, masking auth failures until
# the eventual `git push`. Two distinct steps make the auth contract
# explicit and fail loudly at checkout when the App token mint failed
# on the RC path.
- name: Checkout (RC)
if: needs.route.outputs.mode == 'rc'
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 0
fetch-tags: true
# Short-lived GitHub App installation token. Required because the
# v-tag push lands at a SHA whose tree may touch
# `.github/workflows/**`, which the default GITHUB_TOKEN cannot
# author.
token: ${{ steps.app-token.outputs.token }}
# Do not persist the token in .git/config (artipacked audit). The
# RC tag push uses an inline `http.extraheader` at push time only;
# the credential never lands on disk. See the
# `Create and push rc tags` step below.
persist-credentials: false
- name: Checkout (stable)
if: needs.route.outputs.mode == 'stable'
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
# No `token:` — actions/checkout uses GITHUB_TOKEN by default. Stable
# path performs no git pushes; the default scope is sufficient.
with:
# No git pushes from the stable path either. Skip credential
# persistence (artipacked audit).
persist-credentials: false
- name: Working-tree sanity
# Defense in depth (mirrors the vtag integrity gate, but on the input side):
# if a route-mode regression skipped both checkout `if:` gates, all
# downstream steps would run on a bare runner and produce confusing
# ENOENT errors. Fail loudly and early here instead.
shell: bash
run: |
if [ ! -f gitnexus/package.json ]; then
echo "::error::no working tree at gitnexus/package.json — route classification likely failed silently."
exit 1
fi
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version: 22
registry-url: https://registry.npmjs.org
# Hermetic install for the published artifact — no cache carry-over
# from non-tag contexts. setup-node v5+ caches by default when a
# packageManager field is present in package.json, so the explicit
# opt-out is required to clear the zizmor cache-poisoning audit.
# ~30s slower per release; runs rarely.
# Node 24 ships with npm >= 11.5.x, which is the minimum that
# supports npm Trusted Publishing OIDC. Node 22 ships with npm
# 10.9.x (no OIDC) and `npm install -g npm@latest` to self-upgrade
# is fragile — it can crash the in-flight reify with
# `MODULE_NOT_FOUND` on `promise-retry` etc. Bumping the Node
# version is the clean fix; the package's `engines` field is
# `>=22.0.0` so consumer-side compatibility is unaffected (this
# Node version is only used during publish, not by package users).
node-version: 24
# `registry-url:` is intentionally OMITTED. Under npm Trusted
# Publishing, OIDC only engages when no credential is configured.
# Setting `registry-url:` would make setup-node write
# `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}` into the
# runner's .npmrc AND export NODE_AUTH_TOKEN from its `token:`
# input (default github.token). `npm publish` would then attempt
# GITHUB_TOKEN as the npm token, get rejected with 404, and OIDC
# would never be tried. See actions/setup-node#1440 and the GitHub
# Community discussion #176761 for the upstream bug and consensus
# workaround.
#
# Hermetic install for published artifacts — opt out of the v5+
# default packageManager-based caching (clears the zizmor
# cache-poisoning audit). ~30s slower per release; runs rarely.
package-manager-cache: false
- name: Build gitnexus-shared
run: npm install && npm run build
working-directory: gitnexus-shared
- run: npm ci
- name: Install gitnexus dependencies
run: npm ci
working-directory: gitnexus
- name: Verify version consistency
# ── Stable-only: verify the tag and package.json agree ───────────────
- name: Verify version consistency (stable)
if: needs.route.outputs.mode == 'stable'
shell: bash
working-directory: gitnexus
run: |
set -euo pipefail
TAG_VERSION="${GITHUB_REF#refs/tags/v}"
if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
echo "::error::Tag does not follow semver: v$TAG_VERSION"
# Stable mode REJECTS prerelease suffixes — those are filtered at
# trigger by the negative-glob filter, but defend at the bash layer too.
if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "::error::Stable tag must be ^v[0-9]+.[0-9]+.[0-9]+$ — got v$TAG_VERSION"
exit 1
fi
PKG_VERSION=$(node -p "require('./package.json').version")
@ -65,24 +424,376 @@ jobs:
exit 1
fi
echo "Version verified: $PKG_VERSION"
working-directory: gitnexus
- name: Build
# ── RC-only: compute the next rc version against the live registry ──
- name: Resolve rc version (rc)
id: rc-version
if: needs.route.outputs.mode == 'rc'
shell: bash
working-directory: gitnexus
env:
BUMP_INPUT: ${{ inputs.bump }}
EVENT_NAME: ${{ github.event_name }}
PKG_NAME: gitnexus
run: |
set -euo pipefail
# 1. Current published `latest` — the floor for any new rc base.
# Only E404 ("never published") falls back to package.json; any
# other error (network, auth, malformed response) fails fast
# (retry-loud policy: never silently substitute on transient errors).
NPM_STDERR_LATEST="$(mktemp)"
if CURRENT_LATEST="$(npm view "$PKG_NAME" version 2>"$NPM_STDERR_LATEST")"; then
:
else
if grep -qiE 'E404|not found' "$NPM_STDERR_LATEST"; then
CURRENT_LATEST="$(node -p "require('./package.json').version")"
echo "Package not on registry (E404) — seeding from package.json: $CURRENT_LATEST"
else
echo "::error::npm registry unreachable for 'view version':" >&2
cat "$NPM_STDERR_LATEST" >&2
rm -f "$NPM_STDERR_LATEST"
exit 1
fi
fi
rm -f "$NPM_STDERR_LATEST"
CURRENT_LATEST_CLEAN="${CURRENT_LATEST%%-*}"
# 2. Full version list — needed for the counter and active-cycle
# inference. Same E404-only fallback.
NPM_STDERR_VERSIONS="$(mktemp)"
if VERSIONS_JSON="$(npm view "$PKG_NAME" versions --json 2>"$NPM_STDERR_VERSIONS")"; then
:
else
if grep -qiE 'E404|not found' "$NPM_STDERR_VERSIONS"; then
VERSIONS_JSON='[]'
echo "No published versions for $PKG_NAME yet (E404)."
else
echo "::error::npm registry unreachable for 'view versions':" >&2
cat "$NPM_STDERR_VERSIONS" >&2
rm -f "$NPM_STDERR_VERSIONS"
exit 1
fi
fi
rm -f "$NPM_STDERR_VERSIONS"
# 3. Base selection.
# - workflow_dispatch + bump != auto → explicit cycle reset.
# - Otherwise (push, or dispatch with bump=auto) → continue the
# highest active rc base > latest if any; else patch from latest.
# Curated wrapper around `npx semver` — bare npx errors are noisy
# and don't distinguish registry-unreachable from invalid-bump-spec.
semver_bump() {
local kind="$1" current="$2" stderr_file out
stderr_file="$(mktemp)"
if out="$(npx --yes -p semver@7 semver -i "$kind" "$current" 2>"$stderr_file")"; then
rm -f "$stderr_file"
printf '%s' "$out"
return 0
fi
echo "::error::semver bump failed (kind=${kind}, current=${current}):" >&2
cat "$stderr_file" >&2
rm -f "$stderr_file"
return 1
}
if [ "$EVENT_NAME" = "workflow_dispatch" ] \
&& [ -n "${BUMP_INPUT:-}" ] \
&& [ "${BUMP_INPUT:-auto}" != "auto" ]; then
BASE="$(semver_bump "$BUMP_INPUT" "$CURRENT_LATEST_CLEAN")"
echo "Explicit bump=$BUMP_INPUT → BASE=$BASE"
else
cat > /tmp/active_base.mjs <<'NODESCRIPT'
const latest = process.env.LATEST;
let v;
try { v = JSON.parse(process.env.VERSIONS_JSON); } catch { v = []; }
if (!Array.isArray(v)) v = [v];
const parse = s => s.split(".").map(n => parseInt(n, 10));
const gt = (a, b) => {
const [A, B] = [parse(a), parse(b)];
for (let i = 0; i < 3; i++) if (A[i] !== B[i]) return A[i] > B[i];
return false;
};
const bases = new Set();
for (const s of v) {
const m = /^(\d+\.\d+\.\d+)-rc\.\d+$/.exec(s);
if (m && gt(m[1], latest)) bases.add(m[1]);
}
if (!bases.size) { process.stdout.write(""); process.exit(0); }
const sorted = [...bases].sort((a, b) => gt(a, b) ? 1 : -1);
process.stdout.write(sorted[sorted.length - 1]);
NODESCRIPT
ACTIVE_BASE="$(LATEST="$CURRENT_LATEST_CLEAN" VERSIONS_JSON="$VERSIONS_JSON" node /tmp/active_base.mjs)"
if [ -n "$ACTIVE_BASE" ]; then
BASE="$ACTIVE_BASE"
echo "Continuing active rc cycle → BASE=$BASE"
else
BASE="$(semver_bump patch "$CURRENT_LATEST_CLEAN")"
echo "No active rc cycle → patch bump from latest → BASE=$BASE"
fi
fi
# 4. Counter: 1 + max existing N for `${BASE}-rc.*`, else 1.
cat > /tmp/next_rc.mjs <<'NODESCRIPT'
const base = process.env.BASE;
const prefix = base + "-rc.";
let v;
try { v = JSON.parse(process.env.VERSIONS_JSON); } catch { v = []; }
if (!Array.isArray(v)) v = [v];
const ns = v
.filter(s => typeof s === "string" && s.startsWith(prefix))
.map(s => parseInt(s.slice(prefix.length), 10))
.filter(n => Number.isInteger(n) && n >= 0);
process.stdout.write(String(ns.length ? Math.max(...ns) + 1 : 1));
NODESCRIPT
NEXT_N="$(BASE="$BASE" VERSIONS_JSON="$VERSIONS_JSON" node /tmp/next_rc.mjs)"
RC_VERSION="${BASE}-rc.${NEXT_N}"
echo "Computed rc: $RC_VERSION"
# 5. Defensive: if the exact version already exists on the registry
# (race with another run), abort before re-publishing.
NPM_STDERR_EXISTS="$(mktemp)"
if npm view "$PKG_NAME@$RC_VERSION" version 2>"$NPM_STDERR_EXISTS" >/dev/null; then
rm -f "$NPM_STDERR_EXISTS"
echo "::error::Version $RC_VERSION already exists on npm — aborting."
exit 1
else
if grep -qiE 'E404|not found' "$NPM_STDERR_EXISTS"; then
rm -f "$NPM_STDERR_EXISTS"
# Version doesn't exist — safe to proceed.
else
echo "::error::npm registry unreachable for existence check:" >&2
cat "$NPM_STDERR_EXISTS" >&2
rm -f "$NPM_STDERR_EXISTS"
exit 1
fi
fi
{
echo "base=$BASE"
echo "rc_n=$NEXT_N"
echo "rc_version=$RC_VERSION"
} >> "$GITHUB_OUTPUT"
- name: Apply rc version in-CI
if: needs.route.outputs.mode == 'rc'
shell: bash
working-directory: gitnexus
run: |
set -euo pipefail
npm version "${{ steps.rc-version.outputs.rc_version }}" \
--no-git-tag-version --allow-same-version
- name: Build gitnexus
run: npm run build
working-directory: gitnexus
- name: Dry-run publish
run: npm publish --dry-run
working-directory: gitnexus
- name: Publish to npm
run: npm publish --provenance --access public
# Cheap verification that the tarball assembles before the real publish.
shell: bash
working-directory: gitnexus
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
NPM_TAG: ${{ needs.route.outputs.mode == 'rc' && 'rc' || 'latest' }}
run: npm publish --dry-run --tag "$NPM_TAG"
- name: Extract release notes from CHANGELOG
# ── Acquire the "rc lock" BEFORE publishing (idempotency anchor) ─────
# We create two refs and push atomically:
# v<RC_VERSION> → annotated tag on a detached release commit whose
# tree contains the rewritten package.json, so the
# tag's source matches the npm tarball.
# rc/<HEAD_SHA> → lightweight tag on HEAD; the guard's dedup key.
# Push fails → nothing published. Push succeeds, npm fails → marker
# blocks retries until manual cleanup (see Rollback Runbook in plan).
- name: Create and push rc tags
id: rc-tags
if: needs.route.outputs.mode == 'rc'
shell: bash
working-directory: gitnexus
env:
RC_VERSION: ${{ steps.rc-version.outputs.rc_version }}
HEAD_SHA: ${{ needs.rc-guard.outputs.head_sha }}
# Short-lived GitHub App token. Auth is supplied inline at push
# time via `http.extraheader` (per GitHub's documented
# x-access-token Basic pattern). It is NOT persisted in
# .git/config (artipacked audit) — checkout above ran with
# `persist-credentials: false`.
PUSH_TOKEN: ${{ steps.app-token.outputs.token }}
# App's slug from create-github-app-token (e.g. `gitnexus-release-bot`).
# Used to attribute the release commit to the App identity rather
# than the generic github-actions[bot]. The bot's numeric user-id
# is resolved at runtime via the GitHub API (the action does not
# expose it directly as of v3.2.0).
APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
GH_TOKEN: ${{ steps.app-token.outputs.token }}
run: |
set -euo pipefail
VTAG="v${RC_VERSION}"
MARKER="rc/${HEAD_SHA}"
# Resolve the App's bot user-id and construct the noreply email
# in the GitHub-canonical `<id>+<slug>[bot]@users.noreply.github.com`
# shape. `[bot]` is part of the actual login on GitHub.
#
# The lookup is wrapped in a bounded retry because the first RC
# after App installation may hit propagation delay (404), and
# transient api.github.com 5xx during heavy org activity is a real
# failure class. Without retry, every transient blip aborts the
# entire release after CI has already succeeded.
BOT_LOGIN="${APP_SLUG}[bot]"
BOT_USER_ID=""
api_stderr="$(mktemp)"
for attempt in 1 2 3; do
if BOT_USER_ID="$(gh api "/users/${BOT_LOGIN}" --jq .id 2>"$api_stderr")" \
&& [[ "${BOT_USER_ID}" =~ ^[0-9]+$ ]]; then
break
fi
BOT_USER_ID=""
if [ "$attempt" -lt 3 ]; then
echo "::warning::bot user-id lookup attempt ${attempt} failed; retrying in $((attempt * 5))s"
sleep $((attempt * 5))
fi
done
if ! [[ "${BOT_USER_ID}" =~ ^[0-9]+$ ]]; then
echo "::error::Could not resolve bot user-id for ${BOT_LOGIN} after 3 attempts."
echo "::error::gh api stderr:"
cat "$api_stderr" >&2 || true
echo "::error::Common causes: (a) newly-installed App — user record still propagating to /users/ (wait ~5min, redispatch with force=true); (b) App lacks Metadata: read permission; (c) transient api.github.com 5xx (redispatch)."
rm -f "$api_stderr"
exit 1
fi
rm -f "$api_stderr"
git config user.name "${BOT_LOGIN}"
git config user.email "${BOT_USER_ID}+${BOT_LOGIN}@users.noreply.github.com"
# Detached release commit with the version bump — main stays
# pristine, but the v-tag's tree matches the published package
# exactly (release-integrity).
git add package.json package-lock.json 2>/dev/null || git add package.json
git commit -m "release: ${VTAG}" --allow-empty
RELEASE_SHA="$(git rev-parse HEAD)"
echo "Detached release commit: $RELEASE_SHA"
git tag -a "$VTAG" "$RELEASE_SHA" -m "$VTAG"
git tag "$MARKER" "$HEAD_SHA"
# Inline auth header. The base64-encoded form is masked as well
# as the raw token, because GitHub's secret-masker only masks the
# raw value — any subsequent `set -x` / GIT_TRACE line would
# otherwise expose the encoded credential.
#
# `set +x` wraps the compute+mask pair so that if an operator
# enables ACTIONS_STEP_DEBUG=true for triage (which turns on
# `set -x` globally), the assignment is NOT traced for the one
# line between compute and mask-registration. Without this wrap,
# debug mode would log `+ auth_header='Authorization: Basic <encoded>'`
# exposing a still-valid (~1h) App token.
{ set +x; } 2>/dev/null
auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${PUSH_TOKEN}" | base64 -w0)"
echo "::add-mask::${auth_header}"
# Re-enable tracing only when explicitly requested via step-debug.
if [ "${ACTIONS_STEP_DEBUG:-false}" = "true" ]; then set -x; fi
# Atomic push of both refs. If either would clobber an existing
# remote ref, the push fails and we stop before npm publish.
git -c http.extraheader="${auth_header}" \
push --atomic origin "refs/tags/$VTAG" "refs/tags/$MARKER"
{
echo "vtag=$VTAG"
echo "marker=$MARKER"
echo "release_sha=$RELEASE_SHA"
} >> "$GITHUB_OUTPUT"
- name: Set vtag (stable)
id: stable-vtag
if: needs.route.outputs.mode == 'stable'
shell: bash
# github.ref_name flows in via env to avoid templating into the
# shell source (template-injection audit). Even though refs are
# constrained by git naming rules, the env-passthrough pattern
# makes injection structurally impossible.
env:
REF_NAME: ${{ github.ref_name }}
run: |
echo "vtag=${REF_NAME}" >> "$GITHUB_OUTPUT"
# ── vtag integrity gate ──────────────────────────────────────────────
# Fail closed before any artifact-producing step (npm publish, Release,
# Docker) runs against an empty or mode-mismatched vtag. Prevents the
# silent "Release named main" / "Docker tagged from ref fallback"
# failure modes that the previous draft was vulnerable to.
- name: vtag integrity gate
id: vtag-gate
shell: bash
env:
MODE: ${{ needs.route.outputs.mode }}
VTAG: ${{ steps.rc-tags.outputs.vtag || steps.stable-vtag.outputs.vtag }}
run: |
set -euo pipefail
if [ -z "$VTAG" ]; then
echo "::error::vtag is empty — refusing to create GitHub Release or trigger Docker."
exit 1
fi
case "$MODE" in
rc)
if ! [[ "$VTAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$ ]]; then
echo "::error::vtag '${VTAG}' does not match rc shape ^v[0-9]+.[0-9]+.[0-9]+-rc.[0-9]+$"
exit 1
fi
;;
stable)
if ! [[ "$VTAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "::error::vtag '${VTAG}' does not match stable shape ^v[0-9]+.[0-9]+.[0-9]+$"
exit 1
fi
;;
*)
echo "::error::unknown mode '${MODE}' at vtag integrity gate."
exit 1
;;
esac
echo "vtag verified: ${VTAG} (mode=${MODE})"
echo "vtag=${VTAG}" >> "$GITHUB_OUTPUT"
# npm Trusted Publishing (GA'd 2025-07-31). OIDC authentication only
# engages when no npm credential is configured anywhere — the absence
# is the signal. Two upstream behaviors had to be neutralized for
# this to work:
#
# 1. setup-node's `registry-url:` is omitted (see the setup-node
# step above). With it, setup-node writes
# `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}` into
# .npmrc and exports NODE_AUTH_TOKEN from `token:` (defaulting
# to github.token). npm publish then sends GITHUB_TOKEN as the
# bearer credential and the registry returns 404. OIDC is never
# tried because npm thinks it already has a credential.
# 2. The runner's bundled npm (10.9.x on Node 22) has no OIDC
# support; the upgrade step above pins it to >= 11.5.1.
#
# Provenance is auto-attached by the registry on trusted-publisher
# publishes — no --provenance flag needed.
#
# Prerequisite: register the package as a trusted publisher at
# https://www.npmjs.com/package/gitnexus/access (Publishing access →
# Trusted Publishers → GitHub Actions):
# Owner: abhigyanpatwari
# Repository: GitNexus
# Workflow: publish.yml
# Environment: (none)
- name: Publish to npm
shell: bash
working-directory: gitnexus
env:
NPM_TAG: ${{ needs.route.outputs.mode == 'rc' && 'rc' || 'latest' }}
run: npm publish --access public --tag "$NPM_TAG"
# ── Stable-only: pull CHANGELOG body if present ──────────────────────
- name: Extract release notes from CHANGELOG (stable)
id: changelog
if: needs.route.outputs.mode == 'stable'
shell: bash
run: |
VERSION="${GITHUB_REF#refs/tags/v}"
@ -98,5 +809,90 @@ jobs:
- name: Create GitHub Release
uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
with:
body_path: ${{ steps.changelog.outputs.fallback == 'false' && '/tmp/release-notes.md' || '' }}
generate_release_notes: ${{ steps.changelog.outputs.fallback == 'true' }}
tag_name: ${{ steps.vtag-gate.outputs.vtag }}
name: >-
${{ needs.route.outputs.mode == 'rc'
&& format('Release Candidate {0}', steps.vtag-gate.outputs.vtag)
|| steps.vtag-gate.outputs.vtag }}
prerelease: ${{ needs.route.outputs.mode == 'rc' }}
make_latest: ${{ needs.route.outputs.mode == 'stable' && 'true' || 'false' }}
# Stable: prefer CHANGELOG body, fall back to auto-generated.
# RC: always auto-generated + the prerelease body block below.
body_path: >-
${{ needs.route.outputs.mode == 'stable' && steps.changelog.outputs.fallback == 'false'
&& '/tmp/release-notes.md' || '' }}
generate_release_notes: >-
${{ needs.route.outputs.mode == 'rc'
|| steps.changelog.outputs.fallback == 'true' }}
body: >-
${{ needs.route.outputs.mode == 'rc' && format(
'Automated release candidate build from `main`.{0}{0}**npm:** `npm install gitnexus@rc`{0}**Version:** `{1}`{0}**Target base:** `{2}` (rc #{3}){0}**Source commit (main):** {4}{0}**Release commit (versioned tree):** {5}{0}{0}Release candidates are pre-stable builds intended for early testing. Stable releases remain on the `latest` dist-tag.',
'\n',
steps.rc-version.outputs.rc_version,
steps.rc-version.outputs.base,
steps.rc-version.outputs.rc_n,
needs.rc-guard.outputs.head_sha,
steps.rc-tags.outputs.release_sha
) || '' }}
# ── RC partial-failure cleanup ───────────────────────────────────────
# If anything after the atomic tag-push step failed (npm publish
# blew up, GitHub Release call timed out, etc.), the v-tag and
# rc/<SHA> marker are already on origin. External consumers
# (Renovate, Dependabot, Releases RSS) can ingest a phantom tag for
# a version that was never published to npm. This step deletes them
# automatically so the operator's recovery is just "redispatch with
# force=true on the next commit", not a manual ref cleanup.
#
# Scoped strictly to RC + real (non-dry-run) + the rc-tags step
# actually produced a vtag (otherwise nothing to clean up). The
# App token is still valid (~1h TTL, job timeout 20min).
- name: Cleanup pushed tags on partial failure
if: ${{ failure() && needs.route.outputs.mode == 'rc' && steps.rc-tags.outputs.vtag != '' }}
shell: bash
working-directory: gitnexus
env:
VTAG: ${{ steps.rc-tags.outputs.vtag }}
MARKER: ${{ steps.rc-tags.outputs.marker }}
PUSH_TOKEN: ${{ steps.app-token.outputs.token }}
run: |
set -uo pipefail
echo "::warning::Publish step failed after tag push. Cleaning up remote refs to prevent phantom-version ingestion by downstream consumers."
{ set +x; } 2>/dev/null
auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${PUSH_TOKEN}" | base64 -w0)"
echo "::add-mask::${auth_header}"
if [ "${ACTIONS_STEP_DEBUG:-false}" = "true" ]; then set -x; fi
# Delete v-tag and marker. Each delete is best-effort — if one
# is already absent (atomic push partially rejected, or earlier
# cleanup ran), the other still gets attempted.
for ref in "refs/tags/${VTAG}" "refs/tags/${MARKER}"; do
if git -c http.extraheader="${auth_header}" push origin --delete "${ref}" 2>&1; then
echo "deleted origin ${ref}"
else
echo "::warning::could not delete origin ${ref} — may already be absent or protected. Manual cleanup may be required."
fi
done
echo "::notice::Cleanup complete. To retry the release, redispatch the workflow with force=true on the same SHA, or push a new commit to main."
# ── Phase 5 (RC only): Docker images ───────────────────────────────────────
# R6: Docker remains RC-only. Stable Docker builds are explicitly deferred.
# Secrets are passed explicitly (not via `secrets: inherit`) so the
# callee's secret surface is auditable from the caller's source.
docker:
name: Build & Push RC Docker images
needs: [route, publish]
if: ${{ needs.route.outputs.mode == 'rc' && needs.publish.outputs.vtag != '' }}
uses: ./.github/workflows/docker.yml
secrets:
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
permissions:
contents: read
packages: write
id-token: write
attestations: write
with:
tag: ${{ needs.publish.outputs.vtag }}

459
.github/workflows/release-candidate.yml vendored
View file

@ -1,459 +0,0 @@
name: Release Candidate
on:
# Publish a release-candidate build whenever a merge/commit lands on main.
# Docs/README-only changes are filtered out so prose updates don't
# cut a release.
push:
branches: [main]
paths-ignore:
- '**.md'
- 'docs/**'
- 'LICENSE'
workflow_dispatch:
inputs:
bump:
description: >-
Cycle policy. 'auto' (default) continues the active rc cycle on
this branch if there is one, otherwise bumps patch from latest.
Choose 'patch' / 'minor' / 'major' to explicitly start or reset
an rc cycle.
required: false
default: 'auto'
type: choice
options:
- auto
- patch
- minor
- major
force:
description: 'Publish even when HEAD already has an rc marker'
required: false
default: 'false'
type: choice
options:
- 'false'
- 'true'
# No workflow-level permissions — scoped per job below.
permissions: {}
# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
# Serialize all runs on the same ref (push + workflow_dispatch) to prevent two publishes
# racing on the rc counter. cancel-in-progress: false — the earlier merge publishes first.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
# ── Skip when HEAD already has an rc marker (retry / duplicate dispatch) ──
# The marker is a lightweight tag `rc/<HEAD_SHA>` pushed *before* `npm
# publish`, so a failed publish leaves the marker in place and the guard
# refuses to re-publish. Recovery path after a partial failure:
# git push --delete origin rc/<HEAD_SHA> v<RC_VERSION>
# then redispatch with force=true.
guard:
name: Check if release candidate should run
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
contents: read
pull-requests: read # read PR labels on the merge commit
outputs:
should_run: ${{ steps.decide.outputs.should_run }}
head_sha: ${{ steps.decide.outputs.head_sha }}
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 0
fetch-tags: true
- name: Decide
id: decide
shell: bash
env:
FORCE: ${{ inputs.force }}
BUMP_INPUT: ${{ inputs.bump }}
EVENT_NAME: ${{ github.event_name }}
GH_TOKEN: ${{ github.token }}
REPO: ${{ github.repository }}
run: |
set -euo pipefail
HEAD_SHA=$(git rev-parse HEAD)
echo "head_sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
if [ "$FORCE" = "true" ]; then
echo "Force flag set — running regardless of marker tag."
echo "should_run=true" >> "$GITHUB_OUTPUT"
exit 0
fi
# An explicit cycle reset on dispatch (bump != auto) also bypasses
# the dedup guard — the maintainer is deliberately asking for a
# new rc from the same commit.
if [ "$EVENT_NAME" = "workflow_dispatch" ] \
&& [ -n "${BUMP_INPUT:-}" ] \
&& [ "${BUMP_INPUT:-auto}" != "auto" ]; then
echo "Explicit bump=$BUMP_INPUT — bypassing marker dedup."
echo "should_run=true" >> "$GITHUB_OUTPUT"
exit 0
fi
# ── Skip when the merge commit corresponds to a release ─────────
# Two complementary checks (belt-and-suspenders):
# 1. The HEAD commit subject matches `chore: release vX.Y.Z`
# (the canonical release-PR title in this repo). Anchored
# at both ends to require the bare title or the squash-merge
# `(#NNNN)` suffix exactly — rejects noisy variants like
# `chore: release v1.0.0 (something unrelated)`.
# 2. The squash-merged PR carries the `release` label.
# Either match suppresses the rc build — stable releases publish
# via publish.yml on the v-tag, so the rc cycle should pause for
# them rather than racing the npm publish.
HEAD_SUBJECT="$(git log -1 --pretty=%s HEAD)"
# Sanitise GitHub-Actions annotation prefixes before logging the
# raw subject — defence-in-depth so a hypothetical commit subject
# containing `::error::` or `::set-output::` cannot forge log
# annotations even though %s strips newlines.
HEAD_SUBJECT_SAFE="${HEAD_SUBJECT//::/__}"
RELEASE_SUBJECT_RE='^chore:[[:space:]]*release[[:space:]]+v[0-9]+\.[0-9]+\.[0-9]+([[:space:]]+\(#[0-9]+\))?$'
if [[ "$HEAD_SUBJECT" =~ $RELEASE_SUBJECT_RE ]]; then
echo "HEAD commit subject matches a release commit — skipping rc."
echo " subject (sanitised): $HEAD_SUBJECT_SAFE"
echo "should_run=false" >> "$GITHUB_OUTPUT"
exit 0
fi
# Squash-merge commits include `(#NNNN)` at the end of the subject.
if [[ "$HEAD_SUBJECT" =~ \(#([0-9]+)\)[[:space:]]*$ ]]; then
PR_NUM="${BASH_REMATCH[1]}"
echo "Detected squash-merge of PR #$PR_NUM — checking labels."
if LABELS_JSON="$(gh pr view "$PR_NUM" --repo "$REPO" --json labels 2>/dev/null)"; then
if printf '%s' "$LABELS_JSON" | jq -e '.labels[] | select(.name == "release")' >/dev/null; then
echo "PR #$PR_NUM has the 'release' label — skipping rc."
echo "should_run=false" >> "$GITHUB_OUTPUT"
exit 0
fi
echo "PR #$PR_NUM has no 'release' label — proceeding."
else
# Lookup failure is not fatal — fall through to the dedup check
# so a transient GH API hiccup doesn't silently suppress rc builds.
echo "::warning::Could not read labels for PR #${PR_NUM} — falling through."
fi
fi
# Dedup: is there already an rc/<HEAD_SHA> marker pointing at HEAD?
MARKER="rc/${HEAD_SHA}"
if git rev-parse "refs/tags/$MARKER" >/dev/null 2>&1; then
echo "HEAD already has marker $MARKER — skipping."
echo "should_run=false" >> "$GITHUB_OUTPUT"
else
echo "No marker on HEAD — proceeding."
echo "should_run=true" >> "$GITHUB_OUTPUT"
fi
# ── Reuse the stable CI workflow ─────────────────────────────────────
ci:
needs: guard
if: needs.guard.outputs.should_run == 'true'
uses: ./.github/workflows/ci.yml
permissions:
contents: read
secrets: inherit
# ── Publish the rc build to npm + create GitHub prerelease ───────────
publish:
name: Publish release candidate to npm
needs: [guard, ci]
if: needs.guard.outputs.should_run == 'true'
runs-on: ubuntu-latest
timeout-minutes: 20
permissions:
# The default GITHUB_TOKEN cannot be granted `workflows: write`, so
# tag pushes that reach a commit which modified `.github/workflows/**`
# are rejected with: "refusing to allow a GitHub App to create or
# update workflow ... without `workflows` permission". We pass a
# fine-grained PAT (RELEASE_PUSH_TOKEN, scoped to this repo with
# Contents: write + Workflows: write) to `actions/checkout` so that
# the subsequent `git push --atomic` of the v-tag and rc marker
# carries the PAT's identity. Job-level GITHUB_TOKEN keeps its
# scoped permissions for everything else (npm provenance, etc.).
contents: write # push rc tag + marker (via PAT)
id-token: write # npm provenance
outputs:
vtag: ${{ steps.reltag.outputs.vtag }}
steps:
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 0
fetch-tags: true
# Use the PAT so `origin` is preauthed for `git push`. Without
# this the default GITHUB_TOKEN is wired into the remote, and a
# workflows-touching tag push is rejected — see the permissions
# block above.
token: ${{ secrets.RELEASE_PUSH_TOKEN }}
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version: 22
registry-url: https://registry.npmjs.org
# Hermetic install — release-candidate produces shipped artifacts.
# setup-node v5+ caches by default when a packageManager field is
# present in package.json; explicit opt-out is required to clear
# the zizmor cache-poisoning audit. See cache-poisoning audit.
package-manager-cache: false
- name: Build gitnexus-shared
run: npm install && npm run build
working-directory: gitnexus-shared
- name: Install gitnexus dependencies
run: npm ci
working-directory: gitnexus
- name: Resolve rc version
id: version
shell: bash
working-directory: gitnexus
env:
BUMP_INPUT: ${{ inputs.bump }}
EVENT_NAME: ${{ github.event_name }}
PKG_NAME: gitnexus
run: |
set -euo pipefail
# 1. Current published `latest` — the floor for any new rc base.
# Only E404 ("never published") falls back to package.json; any
# other error (network, auth, malformed response) fails fast.
NPM_STDERR_LATEST="$(mktemp)"
if CURRENT_LATEST="$(npm view "$PKG_NAME" version 2>"$NPM_STDERR_LATEST")"; then
:
else
if grep -q 'E404' "$NPM_STDERR_LATEST"; then
CURRENT_LATEST="$(node -p "require('./package.json').version")"
echo "Package not on registry (E404) — seeding from package.json: $CURRENT_LATEST"
else
echo "::error::npm registry unreachable for 'view version':" >&2
cat "$NPM_STDERR_LATEST" >&2
rm -f "$NPM_STDERR_LATEST"
exit 1
fi
fi
rm -f "$NPM_STDERR_LATEST"
CURRENT_LATEST_CLEAN="${CURRENT_LATEST%%-*}"
# 2. Full version list — needed for the counter and for active-cycle
# inference. Same E404-only fallback.
NPM_STDERR_VERSIONS="$(mktemp)"
if VERSIONS_JSON="$(npm view "$PKG_NAME" versions --json 2>"$NPM_STDERR_VERSIONS")"; then
:
else
if grep -q 'E404' "$NPM_STDERR_VERSIONS"; then
VERSIONS_JSON='[]'
echo "No published versions for $PKG_NAME yet (E404)."
else
echo "::error::npm registry unreachable for 'view versions':" >&2
cat "$NPM_STDERR_VERSIONS" >&2
rm -f "$NPM_STDERR_VERSIONS"
exit 1
fi
fi
rm -f "$NPM_STDERR_VERSIONS"
# 3. Base selection.
# - workflow_dispatch + bump ∈ {patch,minor,major} → explicit cycle
# reset from latest.
# - Everything else (push, or dispatch with bump=auto) → continue
# the highest active rc base > latest if one exists; else
# default to patch from latest.
if [ "$EVENT_NAME" = "workflow_dispatch" ] \
&& [ -n "${BUMP_INPUT:-}" ] \
&& [ "${BUMP_INPUT:-auto}" != "auto" ]; then
BASE="$(npx --yes -p semver@7 semver -i "$BUMP_INPUT" "$CURRENT_LATEST_CLEAN")"
echo "Explicit bump=$BUMP_INPUT → BASE=$BASE"
else
cat > /tmp/active_base.mjs <<'NODESCRIPT'
const latest = process.env.LATEST;
let v;
try { v = JSON.parse(process.env.VERSIONS_JSON); } catch { v = []; }
if (!Array.isArray(v)) v = [v];
const parse = s => s.split(".").map(n => parseInt(n, 10));
const gt = (a, b) => {
const [A, B] = [parse(a), parse(b)];
for (let i = 0; i < 3; i++) if (A[i] !== B[i]) return A[i] > B[i];
return false;
};
const bases = new Set();
for (const s of v) {
const m = /^(\d+\.\d+\.\d+)-rc\.\d+$/.exec(s);
if (m && gt(m[1], latest)) bases.add(m[1]);
}
if (!bases.size) { process.stdout.write(""); process.exit(0); }
const sorted = [...bases].sort((a, b) => gt(a, b) ? 1 : -1);
process.stdout.write(sorted[sorted.length - 1]);
NODESCRIPT
ACTIVE_BASE="$(LATEST="$CURRENT_LATEST_CLEAN" VERSIONS_JSON="$VERSIONS_JSON" node /tmp/active_base.mjs)"
if [ -n "$ACTIVE_BASE" ]; then
BASE="$ACTIVE_BASE"
echo "Continuing active rc cycle → BASE=$BASE"
else
BASE="$(npx --yes -p semver@7 semver -i patch "$CURRENT_LATEST_CLEAN")"
echo "No active rc cycle → patch bump from latest → BASE=$BASE"
fi
fi
# 4. Counter: 1 + max existing N for `${BASE}-rc.*`, else 1.
cat > /tmp/next_rc.mjs <<'NODESCRIPT'
const base = process.env.BASE;
const prefix = base + "-rc.";
let v;
try { v = JSON.parse(process.env.VERSIONS_JSON); } catch { v = []; }
if (!Array.isArray(v)) v = [v];
const ns = v
.filter(s => typeof s === "string" && s.startsWith(prefix))
.map(s => parseInt(s.slice(prefix.length), 10))
.filter(n => Number.isInteger(n) && n >= 0);
process.stdout.write(String(ns.length ? Math.max(...ns) + 1 : 1));
NODESCRIPT
NEXT_N="$(BASE="$BASE" VERSIONS_JSON="$VERSIONS_JSON" node /tmp/next_rc.mjs)"
RC_VERSION="${BASE}-rc.${NEXT_N}"
echo "Computed rc: $RC_VERSION"
# 5. Defensive: if the exact version already exists on the registry
# (e.g., race with another run), abort before re-publishing.
# Same E404-only pattern used above — a transient network
# failure must fail loudly, not pretend the version is missing.
NPM_STDERR_EXISTS="$(mktemp)"
if npm view "$PKG_NAME@$RC_VERSION" version 2>"$NPM_STDERR_EXISTS" >/dev/null; then
rm -f "$NPM_STDERR_EXISTS"
echo "::error::Version $RC_VERSION already exists on npm — aborting."
exit 1
else
if grep -qiE 'E404|not found' "$NPM_STDERR_EXISTS"; then
rm -f "$NPM_STDERR_EXISTS"
# Version doesn't exist — safe to proceed.
else
echo "::error::npm registry unreachable for existence check:" >&2
cat "$NPM_STDERR_EXISTS" >&2
rm -f "$NPM_STDERR_EXISTS"
exit 1
fi
fi
{
echo "base=$BASE"
echo "rc_n=$NEXT_N"
echo "rc_version=$RC_VERSION"
} >> "$GITHUB_OUTPUT"
- name: Apply rc version in-CI
shell: bash
working-directory: gitnexus
run: |
set -euo pipefail
npm version "${{ steps.version.outputs.rc_version }}" \
--no-git-tag-version --allow-same-version
- name: Build gitnexus
run: npm run build
working-directory: gitnexus
- name: Dry-run publish
run: npm publish --dry-run --tag rc
working-directory: gitnexus
# ── Acquire the "rc lock" BEFORE publishing (fixes idempotency) ─────
# We create two tags and push them atomically:
# v<RC_VERSION> → annotated tag on a detached release commit
# whose tree contains the rewritten package.json
# (so the tag's source matches the npm tarball)
# rc/<HEAD_SHA> → lightweight tag on HEAD; the guard's dedup key
# If this push fails, nothing is published — safe.
# If this push succeeds but npm publish fails, the marker stays on
# the remote and blocks retries until an operator manually cleans up.
- name: Create and push rc tags
id: reltag
shell: bash
working-directory: gitnexus
env:
RC_VERSION: ${{ steps.version.outputs.rc_version }}
HEAD_SHA: ${{ needs.guard.outputs.head_sha }}
run: |
set -euo pipefail
VTAG="v${RC_VERSION}"
MARKER="rc/${HEAD_SHA}"
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
# Detached release commit with the version bump — keeps `main`
# pristine but gives the v-tag a tree that matches the published
# package contents exactly (fixes release-integrity gap).
git add package.json package-lock.json 2>/dev/null || git add package.json
git commit -m "release: ${VTAG}" --allow-empty
RELEASE_SHA="$(git rev-parse HEAD)"
echo "Detached release commit: $RELEASE_SHA"
# Annotated release tag on the release commit.
git tag -a "$VTAG" "$RELEASE_SHA" -m "$VTAG"
# Lightweight marker on the user-visible HEAD for the guard.
git tag "$MARKER" "$HEAD_SHA"
# Atomic push of both refs. If either would clobber an existing
# remote ref, the push fails and we stop before npm publish.
git push --atomic origin "refs/tags/$VTAG" "refs/tags/$MARKER"
{
echo "vtag=$VTAG"
echo "marker=$MARKER"
echo "release_sha=$RELEASE_SHA"
} >> "$GITHUB_OUTPUT"
- name: Publish to npm (rc dist-tag)
run: npm publish --provenance --access public --tag rc
working-directory: gitnexus
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Create GitHub prerelease
uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
with:
tag_name: ${{ steps.reltag.outputs.vtag }}
name: Release Candidate ${{ steps.reltag.outputs.vtag }}
prerelease: true
make_latest: 'false'
generate_release_notes: true
body: |
Automated release candidate build from `main`.
**npm:** `npm install gitnexus@rc`
**Version:** `${{ steps.version.outputs.rc_version }}`
**Target base:** `${{ steps.version.outputs.base }}` (rc #${{ steps.version.outputs.rc_n }})
**Source commit (main):** ${{ needs.guard.outputs.head_sha }}
**Release commit (versioned tree):** ${{ steps.reltag.outputs.release_sha }}
Release candidates are pre-stable builds intended for early testing.
Stable releases remain on the `latest` dist-tag.
# ── Build & push RC Docker images ────────────────────────────────────
# Calls docker.yml as a reusable workflow so that the build, signing, and
# attestation logic stays in one place. The publish job exposes `vtag`
# (e.g. `v1.2.3-rc.1`) as an output so we can pass it as the tag input.
# RC images are signed with Cosign keyless signing; the OIDC identity
# will be `docker.yml@refs/heads/main` (the caller's ref) rather than a
# tag ref — see README.md § Docker for the correct verify command for RCs.
docker:
name: Build & Push RC Docker images
needs: [guard, publish]
if: needs.guard.outputs.should_run == 'true' && needs.publish.outputs.vtag != ''
uses: ./.github/workflows/docker.yml
# Reusable workflows do not receive caller secrets unless inherited; without
# this, DOCKERHUB_* / GITHUB_TOKEN are empty in docker.yml → "Username and
# password required" on Docker Hub login (see same pattern on `ci:` above).
secrets: inherit
permissions:
contents: read
packages: write
id-token: write
attestations: write
with:
tag: ${{ needs.publish.outputs.vtag }}

9
.github/zizmor.yml vendored
View file

@ -37,7 +37,8 @@ rules:
- pr-labeler.yml
# Note: cache-poisoning is NOT exempted. The two prior findings in
# publish.yml and release-candidate.yml were fixed structurally by
# dropping `cache: npm` from those workflows (matches the pattern used
# by PyO3/maturin for the same audit). See the commit that added this
# file for the rationale.
# publish.yml and the former release-candidate.yml were fixed structurally
# by dropping `cache: npm` from those workflows (matches the pattern used
# by PyO3/maturin for the same audit). After the publish-workflow
# unification (issue #1609), only publish.yml remains; the same
# cache-poisoning hardening applies there.

21
AGENTS.md
View file

@ -149,11 +149,16 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows)
## Keeping the Index Fresh
```bash
npx gitnexus analyze # basic refresh; preserves any existing embeddings
npx gitnexus analyze # incremental by default; preserves embeddings
npx gitnexus analyze --force # full rebuild from scratch (opt out of incremental)
npx gitnexus analyze --embeddings # also generate embeddings for new/changed nodes
npx gitnexus analyze --drop-embeddings # explicit opt-in to wipe existing embeddings
```
`analyze` runs **incrementally by default**. The pipeline still parses every file every run (cross-file resolution requires it), but tree-sitter parsing is **served from a content-addressed cache** under `.gitnexus/parse-cache/` (per-chunk JSON shards plus `index.json`) for chunks whose file contents haven't changed since the last run. Older installs may still have a legacy single file `.gitnexus/parse-cache.json`, which is read for backward compatibility but no longer written. Only changed-file rows (and their importers) are rewritten in LadybugDB; unchanged-file rows are preserved. Output is byte-equivalent to a full rebuild. Pass `--force` to wipe and re-index from scratch (e.g., to recover from a corrupt index, or after upgrading GitNexus).
The parse cache key is **content-addressed and version-tagged**: it survives `--force` runs, and is automatically invalidated by a `gitnexus` package upgrade (so a new tree-sitter grammar doesn't silently replay stale parse output). Safe to delete the whole `.gitnexus/parse-cache/` directory (and remove any legacy `.gitnexus/parse-cache.json` if present) at any time — it'll be rebuilt on the next analyze.
Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe.
> Claude Code: PostToolUse hook detects a stale index after `git commit` and `git merge` and prompts the agent to run `analyze`. The hook does not invoke `analyze` itself.
@ -169,6 +174,20 @@ Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no
| Tools/resources/schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
| CLI commands (index, status, clean, wiki) | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
## Hook env knobs
The Claude Code hook (`gitnexus/hooks/claude/gitnexus-hook.cjs` and the mirrored plugin copy under `gitnexus-claude-plugin/hooks/`) honours these env vars. Defaults work for normal installations; set them only to override resolution. All path overrides ignore values that do not exist on disk and fall through to the standard resolution chain.
| Env var | Type | Default | Purpose |
|---------|------|---------|---------|
| `GITNEXUS_HOOK_CLI_PATH` | path | resolved via package layout / `require.resolve` | Override path to the `gitnexus` CLI entry the hook spawns for `augment`. |
| `GITNEXUS_HOOK_LSOF_PATH` | path | `lsof` on `PATH` (with `/usr/bin/lsof`, `/usr/sbin/lsof`, `/sbin/lsof` fallbacks) | Override POSIX `lsof` location for the DB-lock probe. |
| `GITNEXUS_HOOK_PS_PATH` | path | `ps` on `PATH` (with `/bin/ps`, `/usr/bin/ps` fallbacks) | Override POSIX `ps` location. |
| `GITNEXUS_HOOK_POWERSHELL_PATH` | path | `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe` (then `SysWOW64`, then `powershell.exe` on `PATH`) | Override Windows PowerShell location used by the Restart-Manager probe. |
| `GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS` | integer ms | `1200` | Max wall-clock for the Linux `/proc` fd scan before bailing out to the `lsof` fallback. |
| `GITNEXUS_HOOK_RM_TARGET` | path | derived | Restart-Manager target file (the LadybugDB path under `.gitnexus/`). Set internally by the hook; rarely overridden manually. |
| `GITNEXUS_DEBUG` | boolean (`1`/`true`) | unset | Verbose stderr from the hook: prints discarded augment-stderr prefixes and one-shot `.ps1` load-failure warnings. |
<!-- gitnexus:end -->
## Repo reference

84
CONTRIBUTING.md
View file

@ -144,16 +144,18 @@ If you use coding agents, follow project context files (e.g. `AGENTS.md`, `CLAUD
## Releases
Two publish workflows ship `gitnexus` to npm:
One workflow ships `gitnexus` to npm — `.github/workflows/publish.yml`. It
routes between two modes based on the triggering event:
- **Stable** (`.github/workflows/publish.yml`) — triggered by pushing any `v*`
tag. Publishes to the `latest` dist-tag with a changelog-backed GitHub
release. Maintainers are expected to tag from `main` as a convention; the
workflow itself does not enforce branch reachability.
- **Release Candidate** (`.github/workflows/release-candidate.yml`) — runs on
every push to `main` (typically a merged PR) plus manual dispatch. Docs-only
changes are skipped via `paths-ignore`. Publishes to the `rc` dist-tag with
version `X.Y.Z-rc.N` and a GitHub prerelease, where:
- **Stable mode** — triggered by pushing any `v<X.Y.Z>` tag (no `-rc.*`
suffix; RC tags are excluded at trigger via a negative glob). Publishes to
the `latest` dist-tag with a changelog-backed GitHub release. Maintainers
are expected to tag from `main` as a convention; the workflow itself does
not enforce branch reachability. No Docker build (RC-only).
- **Release-candidate mode** — runs on every push to `main` (typically a
merged PR) plus manual `workflow_dispatch`. Docs-only changes are skipped
via `paths-ignore`. Publishes to the `rc` dist-tag with version
`X.Y.Z-rc.N` and a GitHub prerelease, where:
- `X.Y.Z` is selected automatically. On push (and on dispatch with
`bump: auto`, the default) the workflow **continues the active rc cycle**:
if the registry already has `X.Y.Z-rc.*` versions with `X.Y.Z` > current
@ -170,36 +172,64 @@ Two publish workflows ship `gitnexus` to npm:
caller's ref — see README.md § Docker for the verify command).
Idempotency: the workflow pushes an `rc/<HEAD_SHA>` marker tag and a
`v<RC>` release tag **atomically, before** calling `npm publish`. The guard
refuses to re-run once the marker exists, so a post-publish failure will
not mint a duplicate rc for the same commit. The `v<RC>` tag points at a
detached release commit whose `package.json` matches the npm tarball
exactly (traceable releases). Recovery after a partial failure:
`v<RC>` release tag **atomically, before** calling `npm publish`. The
RC guard refuses to re-run once the marker exists, so a post-publish
failure will not mint a duplicate rc for the same commit. The `v<RC>`
tag points at a detached release commit whose `package.json` matches
the npm tarball exactly (traceable releases). The RC tag is excluded
from this workflow's `push: tags:` filter, so it does **not** re-trigger
publishing — preventing the double-publish failure mode tracked in #1609.
Recovery after a partial failure: the workflow's `if: failure()` cleanup
step in the `publish` job auto-deletes the v-tag and marker on most
post-publish failures, so the typical retry is just:
```bash
gh workflow run publish.yml --ref main -f force=true
# or push a new commit to main, which will cut a fresh RC
```
If auto-cleanup didn't run (e.g. the cleanup step itself failed, or the
failure happened in the route/rc-guard phase before the marker was
pushed), manual cleanup is:
```bash
git push --delete origin rc/<HEAD_SHA> v<RC>
# then redispatch the workflow with force: true
# then redispatch with force: true
```
**Release-PR-skip subject pattern.** The rc-guard job recognizes a
squash-merged release commit by matching the commit subject against
`^chore: release vX.Y.Z` (optionally followed by ` (#NNNN)` for the
squash-merge PR-number suffix). Match is case-insensitive — `Chore: Release v1.2.3`
works too. PRs that should suppress the RC build must either use this
subject shape, or carry the `release` label so the label-based fallback
fires. Other release-style subjects (`chore(release): v1.2.3`,
`release: v1.2.3`) will NOT trigger the skip — please name the release
PR exactly `chore: release vX.Y.Z` to keep the dedup deterministic.
**Docker-only partial failure:** if `publish` succeeds (npm tarball + tags
are live) but the `docker` job subsequently fails (e.g. GHCR flakiness),
the npm RC is already published and the `rc/<HEAD_SHA>` marker is in place.
Re-running `release-candidate.yml` with `force: true` will abort at the
"Version already exists on npm" guard. To recover without cutting a new RC:
Recovery without cutting a new RC:
```bash
# 1. Manually trigger only the docker workflow, passing the existing RC tag:
gh workflow run docker.yml --ref main -f tag=v<RC_VERSION>
# (requires a workflow_dispatch trigger on docker.yml — see note below)
# Re-run only the failed docker job from the original workflow run:
gh run rerun <run-id> --failed
```
Because `docker.yml` intentionally has no `workflow_dispatch` (images are
tag-driven by design), the practical recovery options are:
- Wait for the next commit on `main`, which will cut a new RC that includes
the Docker build.
- Manually run `docker build` + `docker push` locally and sign with Cosign
against the same digest.
- Delete `rc/<HEAD_SHA>` and `v<RC>` tags, then redispatch with `force: true` to re-run the full RC pipeline (cuts a new RC number).
Find the run ID via `gh run list --workflow=publish.yml --branch main`.
`docker.yml` intentionally has no `workflow_dispatch` trigger (images are
tag-driven by design), so the gh-run-rerun path is the supported recovery.
**GitHub Release transient failure** (npm publish succeeded, Release step
failed): the npm artifact is live but no GitHub Release page exists.
Recover by either re-running the failed job (`gh run rerun <run-id> --failed`),
or creating the Release manually:
```bash
gh release create v<RC> --prerelease --generate-notes # RC
gh release create v<X.Y.Z> --notes-file gitnexus/CHANGELOG.md # stable
```
The rc workflow never moves `latest`. To verify after a change, inspect dist-tags:

14
Dockerfile.cli
View file

@ -40,8 +40,8 @@ RUN npm prune --omit=dev --prefix gitnexus
# node:22-bookworm-slim
FROM node:22-bookworm-slim@sha256:9f6d5975c7dca860947d3915877f85607946403fc55349f39b4bc3688448bb6e AS runtime
# curl for the healthcheck; git so `gitnexus` can clone repos at runtime.
RUN apt-get update && apt-get install -y --no-install-recommends curl git && rm -rf /var/lib/apt/lists/* \
# curl for the healthcheck; git for cloning; ca-certificates for TLS verification.
RUN apt-get update && apt-get install -y --no-install-recommends curl git ca-certificates && rm -rf /var/lib/apt/lists/* \
&& rm -rf /usr/local/lib/node_modules/npm \
&& rm -rf /usr/local/lib/node_modules/corepack \
&& rm -f /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack
@ -55,8 +55,18 @@ RUN mkdir -p /data/gitnexus && chown -R node:node /data
COPY --from=builder --chown=node:node /app/gitnexus/dist ./gitnexus/dist
COPY --from=builder --chown=node:node /app/gitnexus/node_modules ./gitnexus/node_modules
COPY --from=builder --chown=node:node /app/gitnexus/package.json ./gitnexus/package.json
COPY --from=builder --chown=node:node /app/gitnexus/scripts/install-duckdb-extension.mjs ./gitnexus/scripts/install-duckdb-extension.mjs
COPY --from=builder --chown=node:node /app/gitnexus/vendor ./gitnexus/vendor
# Expose the `gitnexus` binary on PATH so the documented Docker workflow
# (`docker compose exec gitnexus-server gitnexus index /workspace/<repo>`)
# works without users having to invoke `node /app/gitnexus/dist/cli/index.js`.
# `npm prune --omit=dev` in the builder stage strips `node_modules/.bin/`
# entries, so the `gitnexus` bin declared in package.json (`dist/cli/index.js`,
# which already carries `#!/usr/bin/env node` and 755 perms) is otherwise
# unreachable from $PATH.
RUN ln -s /app/gitnexus/dist/cli/index.js /usr/local/bin/gitnexus
USER node
# The web UI defaults to http://localhost:4747 - keep that contract.

8
GUARDRAILS.md
View file

@ -30,9 +30,15 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
### Stale graph after edits
- **Trigger:** MCP warns index is behind `HEAD`, or search doesn't match latest commit.
- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used).
- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used). Runs incrementally by default — the pipeline parses every file every run (cross-file resolution requires it), but tree-sitter dispatch is skipped for unchanged file chunks via the content-addressed cache, and only changed-file rows (plus their importers, transitively) are rewritten in LadybugDB.
- **Why:** Tools query LadybugDB from last analyze; git changes are invisible until re-indexed.
### Index seems corrupt or "incremental" is misbehaving
- **Trigger:** `analyze` produces unexpected results, or `meta.json.incrementalInProgress` is set, or the index is in a half-state after a crash.
- **Do:** `npx gitnexus analyze --force` to rebuild from scratch. The dirty-flag check forces this automatically when a previous incremental run didn't complete cleanly, but `--force` is the manual escape hatch. Safe to delete the `.gitnexus/parse-cache/` directory (and any legacy `.gitnexus/parse-cache.json`) at any time — content-addressed, will be regenerated.
- **Why:** Incremental writeback is selective DB row replacement; if the on-disk state is inconsistent for any reason, a full rebuild is the cheapest path back to a known-good index.
### Embeddings vanished after analyze
- **Trigger:** Semantic search quality drops; `stats.embeddings` in `meta.json` is 0 after refresh.

10
README.md
View file

@ -429,7 +429,7 @@ The Docker images are version-locked to the npm package:
Both registries receive the same digest from a single build step, so you can
pull from either and the signature verifies identically.
- Release-candidate images (e.g. `:1.7.0-rc.1`) are published alongside each
RC npm release. They are built by `release-candidate.yml` calling `docker.yml`
RC npm release. They are built by `publish.yml` calling `docker.yml`
as a reusable workflow after the RC tag is created and pushed.
- `:latest` is auto-promoted only from non-prerelease tags by the Docker
metadata action, so it always points at a real, npm-published version.
@ -462,7 +462,7 @@ registries because both sets of tags were signed at the same digest in one
workflow run.
**Release candidates** — signed from `refs/heads/main` (the caller's ref when
`release-candidate.yml` invokes `docker.yml` as a reusable workflow):
`publish.yml` invokes `docker.yml` as a reusable workflow):
```bash
cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
@ -722,6 +722,12 @@ gitnexus wiki --base-url https://api.anthropic.com/v1
# Force full regeneration
gitnexus wiki --force
# Increase the timeout or retries for large codebase or slow LLM providers
gitnexus wiki --timeout <seconds> # Per-attempt LLM request timeout in seconds (default: 60)
gitnexus wiki --retries <n> # Max LLM retry attempts per request (default: 3)
```
The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.

6
eval/uv.lock generated
View file

@ -2278,11 +2278,11 @@ wheels = [
[[package]]
name = "urllib3"
version = "2.6.3"
version = "2.7.0"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
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" }
wheels = [
{ url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
{ 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" },
]
[[package]]

51
gitnexus-claude-plugin/hooks/gitnexus-hook.js
View file

@ -14,6 +14,8 @@
const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
const { acquireHookSlot } = require('./hook-lock.js');
const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
/**
* Read JSON input from stdin synchronously.
@ -102,6 +104,28 @@ function findGitNexusDir(startDir) {
return null;
}
function hasGitNexusServerOwner(gitNexusDir) {
return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
}
function extractAugmentContext(stderr) {
const output = (stderr || '').trim();
const marker = output.indexOf('[GitNexus]');
const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
if (debug && output.length > 0) {
// Emit the FULL discarded prefix (everything before the marker, or all of
// it when no marker is present) so suppressed diagnostics — LadybugDB lock
// warnings, parser errors, etc. — remain recoverable on the hook's own
// stderr. The untruncated payload lets operators see exactly what was
// filtered out instead of a 180-char JSON-quoted preview.
const discarded = marker === -1 ? output : output.slice(0, marker).trim();
if (discarded.length > 0) {
process.stderr.write(`[GitNexus hook] augment stderr discarded prefix:\n${discarded}\n`);
}
}
return marker === -1 ? '' : output.slice(marker).trim();
}
/**
* Extract search pattern from tool input.
*/
@ -169,6 +193,15 @@ function extractPattern(toolName, toolInput) {
*/
function runGitNexusCli(args, cwd, timeout) {
const isWin = process.platform === 'win32';
const hookCli = process.env.GITNEXUS_HOOK_CLI_PATH;
if (hookCli !== undefined && String(hookCli).trim() && fs.existsSync(String(hookCli))) {
return spawnSync(process.execPath, [String(hookCli), ...args], {
encoding: 'utf-8',
timeout,
cwd,
stdio: ['pipe', 'pipe', 'pipe'],
});
}
// Detect whether 'gitnexus' is on PATH (cheap check, no execution)
let useDirectBinary = false;
@ -217,7 +250,8 @@ function sendHookResponse(hookEventName, message) {
function handlePreToolUse(input) {
const cwd = input.cwd || process.cwd();
if (!path.isAbsolute(cwd)) return;
if (!findGitNexusDir(cwd)) return;
const gitNexusDir = findGitNexusDir(cwd);
if (!gitNexusDir) return;
const toolName = input.tool_name || '';
const toolInput = input.tool_input || {};
@ -226,19 +260,28 @@ function handlePreToolUse(input) {
const pattern = extractPattern(toolName, toolInput);
if (!pattern || pattern.length < 3) return;
if (hasGitNexusServerOwner(gitNexusDir)) {
process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
return;
}
const release = acquireHookSlot(gitNexusDir);
if (!release) return;
let result = '';
try {
const child = runGitNexusCli(['augment', '--', pattern], cwd, 7000);
if (!child.error && child.status === 0) {
result = child.stderr || '';
result = extractAugmentContext(child.stderr || '');
}
} catch {
/* graceful failure */
} finally {
release();
}
if (result && result.trim()) {
sendHookResponse('PreToolUse', result.trim());
if (result) {
sendHookResponse('PreToolUse', result);
}
}

238
gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs Normal file
View file

@ -0,0 +1,238 @@
/**
* Cross-platform best-effort probe: does another process hold dbPath open
* with a command line that looks like a GitNexus MCP/serve server?
*
* Backends (no user-installed Sysinternals):
* - Linux: scan procfs under /proc (per-PID fd entries) via stat(2) (dev+inode); works without lsof;
* optional lsof fallback when proc scan finds nothing.
* - macOS / *BSD / etc.: trusted lsof + ps (absolute paths first).
* - Windows: Restart Manager (rstrtmgr) via bundled PowerShell script +
* Win32_Process for command lines; trusted powershell.exe under %SystemRoot%.
*
* Fail-open on most errors; fail-closed only on lsof ETIMEDOUT (Unix) or
* PowerShell ETIMEDOUT (Windows), matching the hook contract.
*/
const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
function isGitNexusServerCommand(command) {
const hasServerMode = /(?:^|\s)(mcp|serve)(?:\s|$)/.test(command);
const hasGitNexus =
/(?:^|[/\\\s])gitnexus(?:\.cmd)?(?:\s|$)/.test(command) ||
/node_modules[/\\]gitnexus[/\\]/.test(command);
return hasServerMode && hasGitNexus;
}
function resolveHookBinary(tool) {
const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH';
const fromEnv = process.env[envKey];
if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) {
return String(fromEnv);
}
const candidates =
tool === 'lsof'
? ['/usr/bin/lsof', '/usr/sbin/lsof', '/sbin/lsof', tool]
: ['/bin/ps', '/usr/bin/ps', tool];
for (const candidate of candidates) {
if (candidate === tool) return tool;
try {
if (fs.existsSync(candidate)) return candidate;
} catch {
/* ignore */
}
}
return tool;
}
function resolveWindowsPowerShellPath() {
const fromEnv = process.env.GITNEXUS_HOOK_POWERSHELL_PATH;
if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv).trim())) {
return String(fromEnv).trim();
}
const root = process.env.SystemRoot || 'C:\\Windows';
const ps = path.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
if (fs.existsSync(ps)) return ps;
const psWow = path.join(root, 'SysWOW64', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
if (fs.existsSync(psWow)) return psWow;
return 'powershell.exe';
}
// Sentinel:
// undefined = not loaded yet (try the read)
// string = encoded PowerShell command (successful load)
// null = load attempted and failed (do not retry; warning already emitted)
let windowsRmListPsEncodedCommandCache;
let windowsRmListPsLoadFailureWarned = false;
function getWindowsRmListEncodedCommand() {
if (windowsRmListPsEncodedCommandCache !== undefined) {
return windowsRmListPsEncodedCommandCache;
}
try {
const ps1Path = path.join(__dirname, 'win-rm-list-json.ps1');
const src = fs
.readFileSync(ps1Path, 'utf8')
.replace(/^\uFEFF/, '')
.replace(/\r\n/g, '\n');
windowsRmListPsEncodedCommandCache = Buffer.from(src, 'utf16le').toString('base64');
} catch (err) {
windowsRmListPsEncodedCommandCache = null;
if (
!windowsRmListPsLoadFailureWarned &&
(process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true')
) {
windowsRmListPsLoadFailureWarned = true;
const msg = err && err.message ? String(err.message).slice(0, 200) : 'unknown';
process.stderr.write(`[GitNexus hook] win-rm-list-json.ps1 load failed: ${msg}\n`);
}
}
return windowsRmListPsEncodedCommandCache;
}
function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) {
const encoded = getWindowsRmListEncodedCommand();
if (!encoded) return false;
const psExe = resolveWindowsPowerShellPath();
const r = spawnSync(
psExe,
[
'-NoProfile',
'-NonInteractive',
'-ExecutionPolicy',
'Bypass',
'-STA',
'-EncodedCommand',
encoded,
],
{
encoding: 'utf-8',
timeout: 6000,
stdio: ['ignore', 'pipe', 'ignore'],
env: { ...process.env, GITNEXUS_HOOK_RM_TARGET: dbPathAbs },
},
);
// ETIMEDOUT means the PowerShell probe didn't return in time; treat as 'unresponsive process holds DB' → fail-closed (skip augment).
if (r.error) return r.error.code === 'ETIMEDOUT';
if (r.status !== 0) return false;
let rows;
try {
rows = JSON.parse(String(r.stdout || '').trim() || '[]');
} catch {
return false;
}
if (!Array.isArray(rows)) return false;
for (const row of rows) {
const procId = Number(row.pid);
const cmd = String(row.cmd || '');
if (!Number.isFinite(procId) || procId === myPid) continue;
if (isGitNexusServerCommand(cmd)) return true;
}
return false;
}
function readLinuxCmdline(pidStr) {
try {
return fs.readFileSync(`/proc/${pidStr}/cmdline`, 'utf8').replace(/\0+/g, ' ').trim();
} catch {
return '';
}
}
function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
const raw = process.env.GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS;
const budget = Number(raw && String(raw).trim()) ? Number.parseInt(String(raw), 10) : 1200;
const start = Date.now();
let targetStat;
try {
targetStat = fs.statSync(dbPathAbs);
} catch {
return false;
}
let procEntries;
try {
procEntries = fs.readdirSync('/proc', { withFileTypes: true });
} catch {
return false;
}
for (const ent of procEntries) {
if (Date.now() - start > budget) return false;
if (!ent.isDirectory() || !/^\d+$/.test(ent.name)) continue;
const pid = Number.parseInt(ent.name, 10);
if (!Number.isFinite(pid) || pid === myPid) continue;
const fdDir = path.join('/proc', ent.name, 'fd');
let fds;
try {
fds = fs.readdirSync(fdDir);
} catch {
continue;
}
let holds = false;
for (const fd of fds) {
if (Date.now() - start > budget) return false;
try {
const st = fs.statSync(path.join(fdDir, fd));
if (st.dev === targetStat.dev && st.ino === targetStat.ino) {
holds = true;
break;
}
} catch {
/* ignore */
}
}
if (!holds) continue;
if (isGitNexusServerCommand(readLinuxCmdline(ent.name))) return true;
}
return false;
}
function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
const lsofPath = resolveHookBinary('lsof');
const lsof = spawnSync(lsofPath, ['-nP', '-t', '--', dbPathAbs], {
encoding: 'utf-8',
timeout: 1000,
stdio: ['ignore', 'pipe', 'ignore'],
});
if (lsof.error) return lsof.error.code === 'ETIMEDOUT';
const pids = (lsof.stdout || '').split(/\s+/).filter(Boolean);
const psPath = resolveHookBinary('ps');
for (const pid of pids) {
if (Number(pid) === myPid) continue;
const ps = spawnSync(psPath, ['-p', pid, '-o', 'command='], {
encoding: 'utf-8',
timeout: 500,
stdio: ['ignore', 'pipe', 'ignore'],
});
if (ps.error) {
if (ps.error.code === 'ETIMEDOUT') return true;
continue;
}
if (isGitNexusServerCommand(ps.stdout || '')) return true;
}
return false;
}
/**
* @param {string} dbPath Absolute or relative path to the DB file (e.g. .../lbug).
* @param {number} myPid Current process PID (hook runner), excluded from matches.
*/
function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) {
if (!fs.existsSync(dbPath)) return false;
const dbPathAbs = path.resolve(dbPath);
if (process.platform === 'win32') {
return hasGitNexusServerOwnerWindows(dbPathAbs, myPid);
}
if (process.platform === 'linux') {
if (linuxProcScanFindGitNexusServer(dbPathAbs, myPid)) return true;
return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
}
return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
}
module.exports = {
hasGitNexusDbLockedByGitNexusServer,
};

119
gitnexus-claude-plugin/hooks/hook-lock.js Normal file
View file

@ -0,0 +1,119 @@
const fs = require('fs');
const path = require('path');
const HOOK_LOCK_SUBDIR = '.hook-locks';
const HOOK_LOCK_MAX_INFLIGHT = 3;
const HOOK_LOCK_STALE_MS = 30000;
function acquireHookSlot(gitNexusDir) {
const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR);
try {
fs.mkdirSync(lockDir, { recursive: true });
} catch {
// Cannot create lock dir (read-only fs, cross-user perm denial, out of
// inodes, etc.) — fail closed by returning null. Caller skips augment.
// Fail-open here would let N concurrent hooks all proceed unguarded and
// reintroduce the #1486 fan-out the guard exists to prevent.
return null;
}
const myPidStr = String(process.pid);
for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) {
const slotPath = path.join(lockDir, `slot-${slot}.lock`);
for (let attempt = 0; attempt < 2; attempt++) {
try {
fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' });
let released = false;
const release = () => {
if (released) return;
released = true;
try {
// Only unlink if we still own the slot. If we appeared stale and
// another hook took over, the file now belongs to it — leave alone.
const content = fs.readFileSync(slotPath, 'utf-8').trim();
if (content === myPidStr) fs.unlinkSync(slotPath);
} catch {
/* already removed or unreadable */
}
};
process.on('exit', release);
return release;
} catch {
// Slot exists. Decide whether to take it over.
// Open once and inspect mtime + content via the same fd so there's
// no TOCTOU between the metadata check and the content read
// (codeql js/file-system-race).
let fd;
try {
fd = fs.openSync(slotPath, 'r');
} catch {
continue; // Vanished between EEXIST and open — retry this slot.
}
let isLive = false;
let mtimeMs = Date.now();
try {
mtimeMs = fs.fstatSync(fd).mtimeMs;
const buf = Buffer.alloc(32);
const n = fs.readSync(fd, buf, 0, 32, 0);
const ownerStr = buf.slice(0, n).toString('utf-8').trim();
if (ownerStr === '') {
// Owner created the file but hasn't written its PID yet. The
// wx open+write window is microseconds; give it the benefit
// of the doubt and treat as live.
isLive = true;
} else {
const owner = Number.parseInt(ownerStr, 10);
if (Number.isFinite(owner) && owner > 0) {
try {
process.kill(owner, 0);
isLive = true;
} catch (e) {
// ESRCH = process gone → treat as dead. EPERM = process exists
// but owned by another user (cross-user lock dir) → still alive,
// keep the slot. Anything else: be conservative, assume alive.
if (e && e.code === 'ESRCH') {
isLive = false;
} else {
isLive = true;
}
}
}
}
} catch {
/* unreadable — treat as dead */
} finally {
try {
fs.closeSync(fd);
} catch {
/* already closed */
}
}
// For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins —
// a slow-but-alive hook is never wrongly evicted. For older slots,
// age is the final arbiter as a defense against PID reuse on long-
// abandoned slots. 30s >> the 7s augment timeout, so a healthy run
// never crosses this threshold.
if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) {
isLive = false;
}
if (isLive) break; // Try the next slot.
try {
fs.unlinkSync(slotPath);
} catch {
/* another hook beat us to it — retry will hit EEXIST */
}
// Loop and retry this slot.
}
}
}
return null;
}
module.exports = {
HOOK_LOCK_SUBDIR,
HOOK_LOCK_MAX_INFLIGHT,
HOOK_LOCK_STALE_MS,
acquireHookSlot,
};

76
gitnexus-claude-plugin/hooks/win-rm-list-json.ps1 Normal file
View file

@ -0,0 +1,76 @@
$ErrorActionPreference = 'Stop'
$target = $env:GITNEXUS_HOOK_RM_TARGET
if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
$target = (Resolve-Path -LiteralPath $target).ProviderPath
if (-not ([Management.Automation.PSTypeName]'GitNexusHookRm.Native').Type) {
Add-Type @'
using System;
using System.Runtime.InteropServices;
namespace GitNexusHookRm {
public static class Native {
public const int ErrorMoreData = 234;
[StructLayout(LayoutKind.Sequential, Pack = 4)]
public struct RM_UNIQUE_PROCESS {
public int dwProcessId;
public long ProcessStartTime;
}
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct RM_PROCESS_INFO {
public RM_UNIQUE_PROCESS Process;
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
public string strAppName;
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)]
public string strServiceShortName;
public uint ApplicationType;
public uint AppStatus;
public uint TSSessionId;
public uint bRestartable;
}
[DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)]
public static extern int RmStartSession(out uint pSessionHandle, uint dwSessionFlags, string strSessionKey);
[DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)]
public static extern int RmRegisterResources(uint pSessionHandle, uint nFiles, string[] rgsFileNames, uint nApplications, IntPtr rgApplications, uint nServices, string[] rgsServiceNames);
[DllImport("rstrtmgr.dll")]
public static extern int RmGetList(uint dwSessionHandle, out uint pnProcInfoNeeded, ref uint pnProcInfo, [In, Out] RM_PROCESS_INFO[] rgAffectedApps, ref uint lpdwRebootReasons);
[DllImport("rstrtmgr.dll")]
public static extern int RmEndSession(uint pSessionHandle);
}
}
'@
}
$h = [uint32]0
$key = [guid]::NewGuid().ToString('N')
$rmErr = [GitNexusHookRm.Native]::RmStartSession([ref]$h, 0, $key)
if ($rmErr -ne 0) { Write-Output '[]'; exit 0 }
$files = @($target)
$err = [GitNexusHookRm.Native]::RmRegisterResources($h, 1, $files, 0, [IntPtr]::Zero, 0, $null)
if ($err -ne 0) {
[void][GitNexusHookRm.Native]::RmEndSession($h)
Write-Output '[]'
exit 0
}
$need = [uint32]0
$n = [uint32]0
$reboot = [uint32]0
$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $null, [ref]$reboot)
if ($err -ne [GitNexusHookRm.Native]::ErrorMoreData) {
[void][GitNexusHookRm.Native]::RmEndSession($h)
Write-Output '[]'
exit 0
}
$n = $need
$buf = New-Object GitNexusHookRm.Native+RM_PROCESS_INFO[] ([int]$n)
$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $buf, [ref]$reboot)
[void][GitNexusHookRm.Native]::RmEndSession($h)
if ($err -ne 0) { Write-Output '[]'; exit 0 }
$out = @()
for ($i = 0; $i -lt [int]$n; $i++) {
$procId = $buf[$i].Process.dwProcessId
$p = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$procId" -ErrorAction SilentlyContinue
$cmd = if ($p) { $p.CommandLine } else { '' }
$out += [PSCustomObject]@{ pid = [int]$procId; cmd = $cmd }
}
ConvertTo-Json -InputObject @($out) -Compress

2
gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md
View file

@ -62,6 +62,8 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
| `--api-key <key>` | LLM API key |
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
| `--gist` | Publish wiki as a public GitHub Gist |
| `--timeout <seconds>` | Per-attempt LLM request timeout in seconds (default: 60) |
| `--retries <n>` | Max LLM retry attempts per request (default: 3) |
### list — Show all indexed repos

12
gitnexus-cursor-integration/README.md
View file

@ -10,20 +10,21 @@ Static config that adds GitNexus knowledge-graph augmentation and skill files to
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **MCP** | `gitnexus` MCP server with 16 tools (`query`, `context`, `impact`, `detect_changes`, `rename`, …) | `npx gitnexus setup` writes `~/.cursor/mcp.json` automatically. |
| **Skills** | `/gitnexus-exploring`, `/gitnexus-debugging`, `/gitnexus-impact-analysis`, `/gitnexus-refactoring`, `/gitnexus-pr-review` markdown skills | `npx gitnexus setup` copies them to `~/.cursor/skills/gitnexus/`. |
| **Hooks** _(this README)_ | `postToolUse` hook that enriches `Shell` / `Read` / `Grep` tool calls with graph context — same augmentation Claude Code gets | **Manual** — copy the two files described below into your project's `.cursor/`. |
| **Hooks** _(this README)_ | `postToolUse` hook that enriches `Shell` / `Read` / `Grep` tool calls with graph context — same augmentation Claude Code gets | **Manual** — copy the files described below into your project's `.cursor/`. |
## Hook install
Cursor 2.4+ reads `.cursor/hooks.json` from the project root and runs hook commands with the project root as the working directory ([docs](https://cursor.com/docs/agent/hooks)).
From this repo's `gitnexus-cursor-integration/hooks/`, copy the two files into your **project root**:
From this repo's `gitnexus-cursor-integration/hooks/`, copy the files below into your **project root**:
```text
<your-project>/
├── .cursor/
│ └── hooks.json ← from gitnexus-cursor-integration/hooks/hooks.json
└── hooks/
└── gitnexus-hook.cjs ← from gitnexus-cursor-integration/hooks/gitnexus-hook.cjs
├── gitnexus-hook.cjs ← from gitnexus-cursor-integration/hooks/gitnexus-hook.cjs
└── hook-lock.cjs ← from gitnexus-cursor-integration/hooks/hook-lock.cjs
```
Equivalent shell commands (run from your project root, with `$GITNEXUS_REPO` pointing at a clone of this repo):
@ -32,6 +33,7 @@ Equivalent shell commands (run from your project root, with `$GITNEXUS_REPO` poi
mkdir -p .cursor hooks
cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/hooks.json" .cursor/hooks.json
cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/gitnexus-hook.cjs" hooks/gitnexus-hook.cjs
cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/hook-lock.cjs" hooks/hook-lock.cjs
```
If you already have a `.cursor/hooks.json`, merge the `hooks.postToolUse` array rather than overwriting.
@ -49,7 +51,7 @@ If you already have a `.cursor/hooks.json`, merge the `hooks.postToolUse` array
| -------------------------------------------------------------------- | ------------------------------ |
| `~/.cursor/mcp.json` | ✅ |
| `~/.cursor/skills/gitnexus/*` | ✅ |
| `<project>/.cursor/hooks.json` + `<project>/hooks/gitnexus-hook.cjs` | ❌ — copy manually (see above) |
| `<project>/.cursor/hooks.json` + `<project>/hooks/gitnexus-hook.cjs` + `<project>/hooks/hook-lock.cjs` | ❌ — copy manually (see above) |
Hook install is per-project (Cursor scopes hooks to a project root); skills and MCP config are global.
@ -84,6 +86,6 @@ Empty stdout means "no augmentation, continue normally" — the hook never block
## Troubleshooting
- **Nothing happens** — Confirm Cursor is on 2.4+ and the project root has both `.cursor/hooks.json` and the script at `hooks/gitnexus-hook.cjs`. Then `npx gitnexus list` to confirm the project is indexed.
- **Nothing happens** — Confirm Cursor is on 2.4+ and the project root has `.cursor/hooks.json` plus both hook files at `hooks/gitnexus-hook.cjs` and `hooks/hook-lock.cjs`. Then `npx gitnexus list` to confirm the project is indexed.
- **`gitnexus` not found** — The hook prefers a locally-resolvable `gitnexus/dist/cli/index.js` and falls back to `npx -y gitnexus`. Install globally with `npm i -g gitnexus` to skip the npx cold-start latency.
- **Wrong pattern extracted** — Set `GITNEXUS_DEBUG=1` and run a tool call. The raw stdin payload is logged to stderr; use it to confirm Cursor's actual `tool_input` field names against the table above. If they differ, file an issue with the captured payload.

9
gitnexus-cursor-integration/hooks/gitnexus-hook.cjs
View file

@ -18,6 +18,7 @@
const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
const { acquireHookSlot } = require('./hook-lock.cjs');
function readInput() {
try {
@ -227,7 +228,8 @@ function main() {
}
const cwd = input.cwd || process.cwd();
if (!path.isAbsolute(cwd)) return;
if (!findGitNexusDir(cwd)) return;
const gitNexusDir = findGitNexusDir(cwd);
if (!gitNexusDir) return;
const toolName = input.tool_name || '';
const toolInput = input.tool_input || {};
@ -235,6 +237,9 @@ function main() {
const pattern = extractPattern(toolName, toolInput);
if (!pattern || pattern.length < 3) return;
const release = acquireHookSlot(gitNexusDir);
if (!release) return;
const cliPath = resolveCliPath();
let result = '';
try {
@ -244,6 +249,8 @@ function main() {
}
} catch {
/* graceful failure */
} finally {
release();
}
if (result && result.trim()) {

119
gitnexus-cursor-integration/hooks/hook-lock.cjs Normal file
View file

@ -0,0 +1,119 @@
const fs = require('fs');
const path = require('path');
const HOOK_LOCK_SUBDIR = '.hook-locks';
const HOOK_LOCK_MAX_INFLIGHT = 3;
const HOOK_LOCK_STALE_MS = 30000;
function acquireHookSlot(gitNexusDir) {
const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR);
try {
fs.mkdirSync(lockDir, { recursive: true });
} catch {
// Cannot create lock dir (read-only fs, cross-user perm denial, out of
// inodes, etc.) — fail closed by returning null. Caller skips augment.
// Fail-open here would let N concurrent hooks all proceed unguarded and
// reintroduce the #1486 fan-out the guard exists to prevent.
return null;
}
const myPidStr = String(process.pid);
for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) {
const slotPath = path.join(lockDir, `slot-${slot}.lock`);
for (let attempt = 0; attempt < 2; attempt++) {
try {
fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' });
let released = false;
const release = () => {
if (released) return;
released = true;
try {
// Only unlink if we still own the slot. If we appeared stale and
// another hook took over, the file now belongs to it — leave alone.
const content = fs.readFileSync(slotPath, 'utf-8').trim();
if (content === myPidStr) fs.unlinkSync(slotPath);
} catch {
/* already removed or unreadable */
}
};
process.on('exit', release);
return release;
} catch {
// Slot exists. Decide whether to take it over.
// Open once and inspect mtime + content via the same fd so there's
// no TOCTOU between the metadata check and the content read
// (codeql js/file-system-race).
let fd;
try {
fd = fs.openSync(slotPath, 'r');
} catch {
continue; // Vanished between EEXIST and open — retry this slot.
}
let isLive = false;
let mtimeMs = Date.now();
try {
mtimeMs = fs.fstatSync(fd).mtimeMs;
const buf = Buffer.alloc(32);
const n = fs.readSync(fd, buf, 0, 32, 0);
const ownerStr = buf.slice(0, n).toString('utf-8').trim();
if (ownerStr === '') {
// Owner created the file but hasn't written its PID yet. The
// wx open+write window is microseconds; give it the benefit
// of the doubt and treat as live.
isLive = true;
} else {
const owner = Number.parseInt(ownerStr, 10);
if (Number.isFinite(owner) && owner > 0) {
try {
process.kill(owner, 0);
isLive = true;
} catch (e) {
// ESRCH = process gone → treat as dead. EPERM = process exists
// but owned by another user (cross-user lock dir) → still alive,
// keep the slot. Anything else: be conservative, assume alive.
if (e && e.code === 'ESRCH') {
isLive = false;
} else {
isLive = true;
}
}
}
}
} catch {
/* unreadable — treat as dead */
} finally {
try {
fs.closeSync(fd);
} catch {
/* already closed */
}
}
// For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins —
// a slow-but-alive hook is never wrongly evicted. For older slots,
// age is the final arbiter as a defense against PID reuse on long-
// abandoned slots. 30s >> the 7s augment timeout, so a healthy run
// never crosses this threshold.
if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) {
isLive = false;
}
if (isLive) break; // Try the next slot.
try {
fs.unlinkSync(slotPath);
} catch {
/* another hook beat us to it — retry will hit EEXIST */
}
// Loop and retry this slot.
}
}
}
return null;
}
module.exports = {
HOOK_LOCK_SUBDIR,
HOOK_LOCK_MAX_INFLIGHT,
HOOK_LOCK_STALE_MS,
acquireHookSlot,
};

1
gitnexus-shared/src/index.ts
View file

@ -129,6 +129,7 @@ export type {
RegistryProviders,
OwnerScopedContributor,
ArityVerdict,
ConstraintContext,
} from './scope-resolution/registries/context.js';
// Scope tree spine + position lookup (RFC §2.2 + §3.1; Ring 2 SHARED #912)

11
gitnexus-shared/src/scope-resolution/finalize-algorithm.ts
View file

@ -833,7 +833,16 @@ function expandWildcard(
if (target === undefined) return [edge];
const names = hooks.expandsWildcardTo(edge.targetModuleScope, workspace);
if (names.length === 0) return [];
if (names.length === 0) {
// Resolved wildcard with zero propagating names is still a real file-
// level dependency (e.g. a C++ header that only declares classes —
// `#include` is a valid IMPORTS edge, but unqualified-binding names
// are correctly empty since class methods require `Class::method`).
// Preserve the original wildcard edge so the file→file IMPORTS edge
// survives; downstream binding materialization sees no propagated
// names because the edge has no `targetExportedName`/`localName`.
return [edge];
}
const expanded: ImportEdge[] = [];
for (const name of names) {

52
gitnexus-shared/src/scope-resolution/method-dispatch-index.ts
View file

@ -40,11 +40,27 @@ export interface MethodDispatchIndex {
readonly mroByOwnerDefId: ReadonlyMap<DefId, readonly DefId[]>;
/** Interfaces / traits → classes that implement them. */
readonly implsByInterfaceDefId: ReadonlyMap<DefId, readonly DefId[]>;
/**
* Optional parallel MRO view that EXCLUDES mixin-like augmentation
* (e.g., PHP traits). Populated only when the input supplies
* `computeExtendsOnlyMro`. Used by the super-branch dispatch in
* `receiver-bound-calls` so that `parent::method()` walks the
* inheritance chain only, not the trait-augmented one. Undefined for
* languages without mixin-like semantics — callers should fall back
* to `mroFor` when this is missing.
*/
readonly extendsOnlyMroByOwnerDefId?: ReadonlyMap<DefId, readonly DefId[]>;
/** `mroByOwnerDefId.get`, with an empty frozen array on miss. */
mroFor(ownerDefId: DefId): readonly DefId[];
/** `implsByInterfaceDefId.get`, with an empty frozen array on miss. */
implementorsOf(interfaceDefId: DefId): readonly DefId[];
/**
* `extendsOnlyMroByOwnerDefId.get`, with an empty frozen array on miss.
* Undefined when `extendsOnlyMroByOwnerDefId` was not populated; callers
* should treat this as equivalent to `mroFor` for non-mixin languages.
*/
readonly extendsOnlyMroFor?: (ownerDefId: DefId) => readonly DefId[];
}
export interface MethodDispatchInput {
@ -81,12 +97,25 @@ export interface MethodDispatchInput {
* write-wins policy and fires at most once per unique owner.
*/
readonly implementsOf: (ownerDefId: DefId) => readonly DefId[];
/**
* Optional: return the EXTENDS-only ancestor chain for `ownerDefId`,
* excluding the owner itself AND any mixin-like augmentation (e.g.,
* PHP traits). Languages without mixin semantics leave this undefined
* and the index's `extendsOnlyMroByOwnerDefId` stays unpopulated.
*
* Same contract as `computeMro`: pure, deterministic, `[]` on no parents.
* Called at most once per unique owner (first-write-wins).
*/
readonly computeExtendsOnlyMro?: (ownerDefId: DefId) => readonly DefId[];
}
// ─── Builder ────────────────────────────────────────────────────────────────
export function buildMethodDispatchIndex(input: MethodDispatchInput): MethodDispatchIndex {
const mroByOwnerDefId = new Map<DefId, readonly DefId[]>();
const extendsOnlyByOwnerDefId = input.computeExtendsOnlyMro
? new Map<DefId, readonly DefId[]>()
: undefined;
const implsBuilding = new Map<DefId, DefId[]>();
const implsSeen = new Map<DefId, Set<DefId>>();
@ -97,6 +126,14 @@ export function buildMethodDispatchIndex(input: MethodDispatchInput): MethodDisp
const chain = input.computeMro(ownerId);
mroByOwnerDefId.set(ownerId, Object.freeze(chain.slice()));
}
if (
input.computeExtendsOnlyMro !== undefined &&
extendsOnlyByOwnerDefId !== undefined &&
!extendsOnlyByOwnerDefId.has(ownerId)
) {
const extOnly = input.computeExtendsOnlyMro(ownerId);
extendsOnlyByOwnerDefId.set(ownerId, Object.freeze(extOnly.slice()));
}
for (const ifaceId of input.implementsOf(ownerId)) {
let seen = implsSeen.get(ifaceId);
@ -121,7 +158,7 @@ export function buildMethodDispatchIndex(input: MethodDispatchInput): MethodDisp
implsByInterfaceDefId.set(ifaceId, Object.freeze(owners.slice()));
}
return wrapIndex(mroByOwnerDefId, implsByInterfaceDefId);
return wrapIndex(mroByOwnerDefId, implsByInterfaceDefId, extendsOnlyByOwnerDefId);
}
// ─── Internal ───────────────────────────────────────────────────────────────
@ -131,8 +168,9 @@ const EMPTY: readonly DefId[] = Object.freeze([]);
function wrapIndex(
mroByOwnerDefId: Map<DefId, readonly DefId[]>,
implsByInterfaceDefId: Map<DefId, readonly DefId[]>,
extendsOnlyMroByOwnerDefId: Map<DefId, readonly DefId[]> | undefined,
): MethodDispatchIndex {
return {
const base: MethodDispatchIndex = {
mroByOwnerDefId,
implsByInterfaceDefId,
mroFor(ownerDefId: DefId): readonly DefId[] {
@ -142,4 +180,14 @@ function wrapIndex(
return implsByInterfaceDefId.get(interfaceDefId) ?? EMPTY;
},
};
if (extendsOnlyMroByOwnerDefId !== undefined) {
return {
...base,
extendsOnlyMroByOwnerDefId,
extendsOnlyMroFor(ownerDefId: DefId): readonly DefId[] {
return extendsOnlyMroByOwnerDefId.get(ownerDefId) ?? EMPTY;
},
};
}
return base;
}

33
gitnexus-shared/src/scope-resolution/registries/context.ts
View file

@ -30,10 +30,43 @@ export interface RegistryProviders {
* when absent, every candidate receives `'unknown'` (neutral signal).
*/
arityCompatibility?(callsite: Callsite, def: SymbolDefinition): ArityVerdict;
/**
* Language-specific constraint compatibility between a callsite and a
* candidate `def`. Mirrors `arityCompatibility` and shares its three-valued
* verdict shape; the third value `'unknown'` MUST keep the candidate
* (monotonicity: adding a predicate can only narrow correctly, never
* produce a wrong edge). Consulted by `narrowOverloadCandidates` after
* arity + type filters when a candidate carries `templateConstraints`.
*
* Optional; when absent the constraint filter is a pass-through. Languages
* with no constrained-overload semantics leave this undefined.
*/
constraintCompatibility?(
callsite: Callsite,
def: SymbolDefinition,
ctx: ConstraintContext,
): ArityVerdict;
}
export type ArityVerdict = 'compatible' | 'unknown' | 'incompatible';
/**
* Context threaded into `constraintCompatibility`. Kept minimal in the
* Tier-A scope (only `argumentTypes`, riding here until a separate
* `Callsite`-widening refactor moves them onto the call site directly).
* Future Tier-B graph-aware predicates (`is_base_of_v`, etc.) will widen
* this interface with `lookupTypeByName` and similar helpers.
*/
export interface ConstraintContext {
/**
* Per-slot argument types at the call site, normalized per the language
* adapter. Empty string means unknown. Same convention as
* `narrowOverloadCandidates`' `argTypes` parameter.
*/
readonly argumentTypes?: readonly string[];
}
// ─── Owner-scoped contributor (concrete shape for `RegistryContributor`) ────
/**

19
gitnexus-shared/src/scope-resolution/registries/lookup-core.ts
View file

@ -423,13 +423,30 @@ function applyArityFilter(
}
let anyCompatible = false;
let anyUnknown = false;
for (const state of perCandidate.values()) {
const verdict = arityFn(callsite, state.def);
state.signals.arityVerdict = verdict;
if (verdict === 'compatible') anyCompatible = true;
else if (verdict === 'unknown') anyUnknown = true;
}
if (!anyCompatible) return;
// When ALL candidates are 'incompatible' (none compatible, none unknown),
// the call is genuinely arity-broken — drop every candidate so the
// registry returns no resolution. This matches the PHP variadic case
// f(int $req, ...$rest) called with zero args: every candidate definitively
// rejects, and emitting an edge to a definitively-rejected callable is
// a false positive. When some candidates are 'unknown' (missing metadata),
// keep the set so downstream evidence can break the tie — that's the
// original safety-fallback behavior.
if (!anyCompatible) {
if (!anyUnknown) {
for (const defId of perCandidate.keys()) {
perCandidate.delete(defId);
}
}
return;
}
// Filter: when at least one compatible candidate exists, drop incompatibles.
for (const [defId, state] of perCandidate) {

9
gitnexus-shared/src/scope-resolution/symbol-definition.ts
View file

@ -30,6 +30,15 @@ export interface SymbolDefinition {
returnType?: string;
/** Declared type for non-callable symbols — fields/properties (e.g. 'Address', 'List<User>') */
declaredType?: string;
/** Generic/template specialization arguments for class-like symbols (e.g. ['User'], ['T*']). */
templateArguments?: string[];
/** Per-language constraint payload for template / generic overloads
* (e.g. C++ `enable_if_t<P, T>` predicate trees, C++20 `requires` clauses).
* Opaque to shared code — the producing language adapter owns the shape
* and is the only consumer. Read via the optional
* `ScopeResolver.constraintCompatibility` hook during overload narrowing.
* Absent for symbols that have no constraints (the common case). */
templateConstraints?: unknown;
/** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
ownerId?: string;
}

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

@ -10,7 +10,7 @@
"dependencies": {
"@langchain/anthropic": "^1.3.29",
"@langchain/core": "^1.1.44",
"@langchain/google-genai": "^2.1.28",
"@langchain/google-genai": "^2.1.30",
"@langchain/langgraph": "^1.2.9",
"@langchain/ollama": "^1.2.6",
"@langchain/openai": "^1.4.5",
@ -29,7 +29,7 @@
"langchain": "^1.3.5",
"lru-cache": "^11.2.4",
"lucide-react": "^1.14.0",
"mermaid": "^11.14.0",
"mermaid": "^11.15.0",
"mnemonist": "^0.39.0",
"pandemonium": "^2.4.0",
"react": "^19.2.5",
@ -60,7 +60,7 @@
"jsdom": "^29.1.1",
"tree-sitter-wasms": "^0.1.13",
"typescript": "^5.4.5",
"vite": "^8.0.10",
"vite": "^8.0.11",
"vitest": "^4.1.5",
"wait-on": "^9.0.5"
},
@ -528,41 +528,10 @@
"integrity": "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og==",
"license": "MIT"
},
"node_modules/@chevrotain/cst-dts-gen": {
"version": "12.0.0",
"resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-12.0.0.tgz",
"integrity": "sha512-fSL4KXjTl7cDgf0B5Rip9Q05BOrYvkJV/RrBTE/bKDN096E4hN/ySpcBK5B24T76dlQ2i32Zc3PAE27jFnFrKg==",
"license": "Apache-2.0",
"dependencies": {
"@chevrotain/gast": "12.0.0",
"@chevrotain/types": "12.0.0"
}
},
"node_modules/@chevrotain/gast": {
"version": "12.0.0",
"resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-12.0.0.tgz",
"integrity": "sha512-1ne/m3XsIT8aEdrvT33so0GUC+wkctpUPK6zU9IlOyJLUbR0rg4G7ZiApiJbggpgPir9ERy3FRjT6T7lpgetnQ==",
"license": "Apache-2.0",
"dependencies": {
"@chevrotain/types": "12.0.0"
}
},
"node_modules/@chevrotain/regexp-to-ast": {
"version": "12.0.0",
"resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-12.0.0.tgz",
"integrity": "sha512-p+EW9MaJwgaHguhoqwOtx/FwuGr+DnNn857sXWOi/mClXIkPGl3rn7hGNWvo31HA3vyeQxjqe+H36yZJwYU8cA==",
"license": "Apache-2.0"
},
"node_modules/@chevrotain/types": {
"version": "12.0.0",
"resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-12.0.0.tgz",
"integrity": "sha512-S+04vjFQKeuYw0/eW3U52LkAHQsB1ASxsPGsLPUyQgrZ2iNNibQrsidruDzjEX2JYfespXMG0eZmXlhA6z7nWA==",
"license": "Apache-2.0"
},
"node_modules/@chevrotain/utils": {
"version": "12.0.0",
"resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-12.0.0.tgz",
"integrity": "sha512-lB59uJoaGIfOOL9knQqQRfhl9g7x8/wqFkp13zTdkRu1huG9kg6IJs1O8hqj9rs6h7orGxHJUKb+mX3rPbWGhA==",
"version": "11.1.2",
"resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.1.2.tgz",
"integrity": "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==",
"license": "Apache-2.0"
},
"node_modules/@cspotcode/source-map-support": {
@ -1433,32 +1402,18 @@
}
},
"node_modules/@langchain/google-genai": {
"version": "2.1.28",
"resolved": "https://registry.npmjs.org/@langchain/google-genai/-/google-genai-2.1.28.tgz",
"integrity": "sha512-iTzNYWST8hTRqOXZdme18tq5GnCUwtrrJECE51ZCjg6Vg0mPsV44amdC+/bc+UK0+uphKWESGWs277aAyM2MlA==",
"version": "2.1.30",
"resolved": "https://registry.npmjs.org/@langchain/google-genai/-/google-genai-2.1.30.tgz",
"integrity": "sha512-0wKgy1NvV89fw5MwYiOOhh18SnUEH20z6MZrPV6Tj2hMAA3jAHVSLlIcCQ2mDRJo2r1aHLV8MDXhzkvD1tEHoQ==",
"license": "MIT",
"dependencies": {
"@google/generative-ai": "^0.24.0",
"uuid": "^11.1.0"
"@google/generative-ai": "^0.24.0"
},
"engines": {
"node": ">=20"
},
"peerDependencies": {
"@langchain/core": "^1.1.41"
}
},
"node_modules/@langchain/google-genai/node_modules/uuid": {
"version": "11.1.0",
"resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz",
"integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==",
"funding": [
"https://github.com/sponsors/broofa",
"https://github.com/sponsors/ctavan"
],
"license": "MIT",
"bin": {
"uuid": "dist/esm/bin/uuid"
"@langchain/core": "^1.1.43"
}
},
"node_modules/@langchain/langgraph": {
@ -1679,12 +1634,12 @@
}
},
"node_modules/@mermaid-js/parser": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.0.tgz",
"integrity": "sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==",
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.1.tgz",
"integrity": "sha512-VuHdsYMK1bT6X2JbcAaWAhugTRvRBRyuZgd+c22swUeI9g/ntaxF7CY7dYarhZovofCbUNO0G7JesfmNtjYOCw==",
"license": "MIT",
"dependencies": {
"langium": "^4.0.0"
"@chevrotain/types": "~11.1.1"
}
},
"node_modules/@napi-rs/wasm-runtime": {
@ -1744,9 +1699,9 @@
}
},
"node_modules/@oxc-project/types": {
"version": "0.127.0",
"resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.127.0.tgz",
"integrity": "sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ==",
"version": "0.128.0",
"resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.128.0.tgz",
"integrity": "sha512-huv1Y/LzBJkBVHt3OlC7u0zHBW9qXf1FdD7sGmc1rXc2P1mTwHssYv7jyGx5KAACSCH+9B3Bhn6Z9luHRvf7pQ==",
"license": "MIT",
"funding": {
"url": "https://github.com/sponsors/Boshen"
@ -1769,9 +1724,9 @@
}
},
"node_modules/@rolldown/binding-android-arm64": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.17.tgz",
"integrity": "sha512-s70pVGhw4zqGeFnXWvAzJDlvxhlRollagdCCKRgOsgUOH3N1l0LIxf83AtGzmb5SiVM4Hjl5HyarMRfdfj3DaQ==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.18.tgz",
"integrity": "sha512-lIDyUAfD7U3+BWKzdxMbJcsYHuqXqmGz40aeRqvuAm3y5TkJSYTBW2RDrn65DJFPQqVjUAUqq5uz8urzQ8aBdQ==",
"cpu": [
"arm64"
],
@ -1785,9 +1740,9 @@
}
},
"node_modules/@rolldown/binding-darwin-arm64": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.17.tgz",
"integrity": "sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.18.tgz",
"integrity": "sha512-apJq2ktnGp27nSInMR5Vcj8kY6xJzDAvfdIFlpDcAK/w4cDO58qVoi1YQsES/SKiFNge/6e4CUzgjfHduYqWpQ==",
"cpu": [
"arm64"
],
@ -1801,9 +1756,9 @@
}
},
"node_modules/@rolldown/binding-darwin-x64": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.17.tgz",
"integrity": "sha512-SUSDOI6WwUVNcWxd02QEBjLdY1VPHvlEkw6T/8nYG322iYWCTxRb1vzk4E+mWWYehTp7ERibq54LSJGjmouOsw==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.18.tgz",
"integrity": "sha512-5Ofot8xbs+pxRHJqm9/9N/4sTQOvdrwEsmPE9pdLEEoAbdZtG6F2LMDfO1sp6ZAtXJuJV/21ew2srq3W8NXB5g==",
"cpu": [
"x64"
],
@ -1817,9 +1772,9 @@
}
},
"node_modules/@rolldown/binding-freebsd-x64": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.17.tgz",
"integrity": "sha512-hwnz3nw9dbJ05EDO/PvcjaaewqqDy7Y1rn1UO81l8iIK1GjenME75dl16ajbvSSMfv66WXSRCYKIqfgq2KCfxw==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.18.tgz",
"integrity": "sha512-7h8eeOTT1eyqJyx64BFCnWZpNm486hGWt2sqeLLgDxA0xI1oGZ9H7gK1S85uNGmBhkdPwa/6reTxfFFKvIsebw==",
"cpu": [
"x64"
],
@ -1833,9 +1788,9 @@
}
},
"node_modules/@rolldown/binding-linux-arm-gnueabihf": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.17.tgz",
"integrity": "sha512-IS+W7epTcwANmFSQFrS1SivEXHtl1JtuQA9wlxrZTcNi6mx+FDOYrakGevvvTwgj2JvWiK8B29/qD9BELZPyXQ==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.18.tgz",
"integrity": "sha512-eRcm/HVt9U/JFu5RKAEKwGQYtDCKWLiaH6wOnsSEp6NMBb/3Os8LgHZlNyzMpFVNmiiMFlfb2zEnebfzJrHFmg==",
"cpu": [
"arm"
],
@ -1849,9 +1804,9 @@
}
},
"node_modules/@rolldown/binding-linux-arm64-gnu": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.17.tgz",
"integrity": "sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.18.tgz",
"integrity": "sha512-SOrT/cT4ukTmgnrEz/Hg3m7LBnuCLW9psDeMKrimRWY4I8DmnO7Lco8W2vtqPmMkbVu8iJ+g4GFLVLLOVjJ9DQ==",
"cpu": [
"arm64"
],
@ -1865,9 +1820,9 @@
}
},
"node_modules/@rolldown/binding-linux-arm64-musl": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.17.tgz",
"integrity": "sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.18.tgz",
"integrity": "sha512-QWjdxN1HJCpBTAcZ5N5F7wju3gVPzRzSpmGzx7na0c/1qpN9CFil+xt+l9lV/1M6/gqHSNXCiqPfwhVJPeLnug==",
"cpu": [
"arm64"
],
@ -1881,9 +1836,9 @@
}
},
"node_modules/@rolldown/binding-linux-ppc64-gnu": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.17.tgz",
"integrity": "sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.18.tgz",
"integrity": "sha512-ugCOyj7a4d9h3q9B+wXmf6g3a68UsjGh6dob5DHevHGMwDUbhsYNbSPxJsENcIttJZ9jv7qGM2UesLw5jqIhdg==",
"cpu": [
"ppc64"
],
@ -1897,9 +1852,9 @@
}
},
"node_modules/@rolldown/binding-linux-s390x-gnu": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.17.tgz",
"integrity": "sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.18.tgz",
"integrity": "sha512-kKWRhbsotpXkGbcd5dllUWg5gEXcDAa8u5YnP9AV5DYNbvJHGzzuwv7dpmhc8NqKMJldl0a+x76IHbspEpEmdA==",
"cpu": [
"s390x"
],
@ -1913,9 +1868,9 @@
}
},
"node_modules/@rolldown/binding-linux-x64-gnu": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.17.tgz",
"integrity": "sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.18.tgz",
"integrity": "sha512-uCo8ElcCIAMyYAZyuIZ81oFkhTSIllNvUCHCAlbhlN4ji3uC28h7IIdlXyIvGO7HsuqnV9p3rD/bpH7XhIyhRw==",
"cpu": [
"x64"
],
@ -1929,9 +1884,9 @@
}
},
"node_modules/@rolldown/binding-linux-x64-musl": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.17.tgz",
"integrity": "sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.18.tgz",
"integrity": "sha512-XNOQZtuE6yUIvx4rwGemwh8kpL1xvU41FXy/s9K7T/3JVcqGzo3NfKM2HrbrGgfPYGFW42f07Wk++aOC6B9NWA==",
"cpu": [
"x64"
],
@ -1945,9 +1900,9 @@
}
},
"node_modules/@rolldown/binding-openharmony-arm64": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.17.tgz",
"integrity": "sha512-0ag/hEgXOwgw4t8QyQvUCxvEg+V0KBcA6YuOx9g0r02MprutRF5dyljgm3EmR02O292UX7UeS6HzWHAl6KgyhA==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.18.tgz",
"integrity": "sha512-tSn/kzrfa7tNOXr7sEacDBN4YsIqTyLqh45IO0nHDwtpKIDNDJr+VFojt+4klSpChxB29JLyduSsE0MKEwa65A==",
"cpu": [
"arm64"
],
@ -1961,9 +1916,9 @@
}
},
"node_modules/@rolldown/binding-wasm32-wasi": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.17.tgz",
"integrity": "sha512-LEXei6vo0E5wTGwpkJ4KoT3OZJRnglwldt5ziLzOlc6qqb55z4tWNq2A+PFqCJuvWWdP53CVhG1Z9NtToDPJrA==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.18.tgz",
"integrity": "sha512-+J9YGmc+czgqlhYmwun3S3O0FIZhsH8ep2456xwjAdIOmuJxM7xz4P4PtrxU+Bz17a/5bqPA8o3HAAoX0teUdg==",
"cpu": [
"wasm32"
],
@ -1979,9 +1934,9 @@
}
},
"node_modules/@rolldown/binding-win32-arm64-msvc": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.17.tgz",
"integrity": "sha512-gUmyzBl3SPMa6hrqFUth9sVfcLBlYsbMzBx5PlexMroZStgzGqlZ26pYG89rBb45Mnia+oil6YAIFeEWGWhoZA==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.18.tgz",
"integrity": "sha512-zsu47DgU0FQzSwi6sU9dZoEdUv7pc1AptSEz/Z8HBg54sV0Pbs3N0+CrIbTsgiu6EyoaNN9CHboqbLaz9lhOyQ==",
"cpu": [
"arm64"
],
@ -1995,9 +1950,9 @@
}
},
"node_modules/@rolldown/binding-win32-x64-msvc": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.17.tgz",
"integrity": "sha512-3hkiolcUAvPB9FLb3UZdfjVVNWherN1f/skkGWJP/fgSQhYUZpSIRr0/I8ZK9TkF3F7kxvJAk0+IcKvPHk9qQg==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.18.tgz",
"integrity": "sha512-7H+3yqGgmnlDTRRhw/xpYY9J1kf4GC681nVc4GqKhExZTDrVVrV2tsOR9kso0fvgBdcTCcQShx4SLLoHgaLwhg==",
"cpu": [
"x64"
],
@ -3643,34 +3598,6 @@
"url": "https://github.com/sponsors/wooorm"
}
},
"node_modules/chevrotain": {
"version": "12.0.0",
"resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-12.0.0.tgz",
"integrity": "sha512-csJvb+6kEiQaqo1woTdSAuOWdN0WTLIydkKrBnS+V5gZz0oqBrp4kQ35519QgK6TpBThiG3V1vNSHlIkv4AglQ==",
"license": "Apache-2.0",
"dependencies": {
"@chevrotain/cst-dts-gen": "12.0.0",
"@chevrotain/gast": "12.0.0",
"@chevrotain/regexp-to-ast": "12.0.0",
"@chevrotain/types": "12.0.0",
"@chevrotain/utils": "12.0.0"
},
"engines": {
"node": ">=22.0.0"
}
},
"node_modules/chevrotain-allstar": {
"version": "0.4.1",
"resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.4.1.tgz",
"integrity": "sha512-PvVJm3oGqrveUVW2Vt/eZGeiAIsJszYweUcYwcskg9e+IubNYKKD+rHHem7A6XVO22eDAL+inxNIGAzZ/VIWlA==",
"license": "MIT",
"dependencies": {
"lodash-es": "^4.17.21"
},
"peerDependencies": {
"chevrotain": "^12.0.0"
}
},
"node_modules/chownr": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz",
@ -4628,6 +4555,16 @@
"node": ">= 0.4"
}
},
"node_modules/es-toolkit": {
"version": "1.46.1",
"resolved": "https://registry.npmjs.org/es-toolkit/-/es-toolkit-1.46.1.tgz",
"integrity": "sha512-5eNtXOs3tbfxXOj04tjjseeWkRWaoCjdEI+96DgwzZoe6c9juL49pXlzAFTI72aWC9Y8p7168g6XIKjh7k6pyQ==",
"license": "MIT",
"workspaces": [
"docs",
"benchmarks"
]
},
"node_modules/esbuild": {
"version": "0.27.0",
"resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.0.tgz",
@ -5661,24 +5598,6 @@
"@langchain/core": "^1.1.42"
}
},
"node_modules/langium": {
"version": "4.2.2",
"resolved": "https://registry.npmjs.org/langium/-/langium-4.2.2.tgz",
"integrity": "sha512-JUshTRAfHI4/MF9dH2WupvjSXyn8JBuUEWazB8ZVJUtXutT0doDlAv1XKbZ1Pb5sMexa8FF4CFBc0iiul7gbUQ==",
"license": "MIT",
"dependencies": {
"@chevrotain/regexp-to-ast": "~12.0.0",
"chevrotain": "~12.0.0",
"chevrotain-allstar": "~0.4.1",
"vscode-languageserver": "~9.0.1",
"vscode-languageserver-textdocument": "~1.0.11",
"vscode-uri": "~3.1.0"
},
"engines": {
"node": ">=20.10.0",
"npm": ">=10.2.3"
}
},
"node_modules/langsmith": {
"version": "0.5.23",
"resolved": "https://registry.npmjs.org/langsmith/-/langsmith-0.5.23.tgz",
@ -6422,14 +6341,14 @@
}
},
"node_modules/mermaid": {
"version": "11.14.0",
"resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz",
"integrity": "sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==",
"version": "11.15.0",
"resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.15.0.tgz",
"integrity": "sha512-pTMbcf3rWdtLiYGpmoTjHEpeY8seiy6sR+9nD7LOs8KfUbHE4lOUAprTRqRAcWSQ6MQpdX+YEsxShtGsINtPtw==",
"license": "MIT",
"dependencies": {
"@braintree/sanitize-url": "^7.1.1",
"@iconify/utils": "^3.0.2",
"@mermaid-js/parser": "^1.1.0",
"@mermaid-js/parser": "^1.1.1",
"@types/d3": "^7.4.3",
"@upsetjs/venn.js": "^2.0.0",
"cytoscape": "^3.33.1",
@ -6440,27 +6359,14 @@
"dagre-d3-es": "7.0.14",
"dayjs": "^1.11.19",
"dompurify": "^3.3.1",
"es-toolkit": "^1.45.1",
"katex": "^0.16.25",
"khroma": "^2.1.0",
"lodash-es": "^4.17.23",
"marked": "^16.3.0",
"roughjs": "^4.6.6",
"stylis": "^4.3.6",
"ts-dedent": "^2.2.0",
"uuid": "^11.1.0"
}
},
"node_modules/mermaid/node_modules/uuid": {
"version": "11.1.0",
"resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz",
"integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==",
"funding": [
"https://github.com/sponsors/broofa",
"https://github.com/sponsors/ctavan"
],
"license": "MIT",
"bin": {
"uuid": "dist/esm/bin/uuid"
"uuid": "^11.1.0 || ^12 || ^13 || ^14.0.0"
}
},
"node_modules/micromark": {
@ -7216,9 +7122,9 @@
}
},
"node_modules/nanoid": {
"version": "3.3.11",
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
"integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
"version": "3.3.12",
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
"integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
"funding": [
{
"type": "github",
@ -7595,9 +7501,9 @@
}
},
"node_modules/postcss": {
"version": "8.5.10",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
"integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
"version": "8.5.14",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
"integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
"funding": [
{
"type": "opencollective",
@ -7947,13 +7853,13 @@
"license": "Unlicense"
},
"node_modules/rolldown": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.17.tgz",
"integrity": "sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.18.tgz",
"integrity": "sha512-phmyKBpuBdRYDf4hgyynGAYn/rDDe+iZXKVJ7WX5b1zQzpLkP5oJRPGsfJuHdzPMlyyEO/4sPW6yfSx2gf7lVg==",
"license": "MIT",
"dependencies": {
"@oxc-project/types": "=0.127.0",
"@rolldown/pluginutils": "1.0.0-rc.17"
"@oxc-project/types": "=0.128.0",
"@rolldown/pluginutils": "1.0.0-rc.18"
},
"bin": {
"rolldown": "bin/cli.mjs"
@ -7962,27 +7868,27 @@
"node": "^20.19.0 || >=22.12.0"
},
"optionalDependencies": {
"@rolldown/binding-android-arm64": "1.0.0-rc.17",
"@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
"@rolldown/binding-darwin-x64": "1.0.0-rc.17",
"@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
"@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
"@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
"@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
"@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
"@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
"@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
"@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
"@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
"@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
"@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
"@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
"@rolldown/binding-android-arm64": "1.0.0-rc.18",
"@rolldown/binding-darwin-arm64": "1.0.0-rc.18",
"@rolldown/binding-darwin-x64": "1.0.0-rc.18",
"@rolldown/binding-freebsd-x64": "1.0.0-rc.18",
"@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.18",
"@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.18",
"@rolldown/binding-linux-arm64-musl": "1.0.0-rc.18",
"@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.18",
"@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.18",
"@rolldown/binding-linux-x64-gnu": "1.0.0-rc.18",
"@rolldown/binding-linux-x64-musl": "1.0.0-rc.18",
"@rolldown/binding-openharmony-arm64": "1.0.0-rc.18",
"@rolldown/binding-wasm32-wasi": "1.0.0-rc.18",
"@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.18",
"@rolldown/binding-win32-x64-msvc": "1.0.0-rc.18"
}
},
"node_modules/rolldown/node_modules/@rolldown/pluginutils": {
"version": "1.0.0-rc.17",
"resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.17.tgz",
"integrity": "sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg==",
"version": "1.0.0-rc.18",
"resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.18.tgz",
"integrity": "sha512-CUY5Mnhe64xQBGZEEXQ5WyZwsc1JU3vAZLIxtrsBt3LO6UOb+C8GunVKqe9sT8NeWb4lqSaoJtp2xo6GxT1MNw==",
"license": "MIT"
},
"node_modules/roughjs": {
@ -8702,15 +8608,15 @@
}
},
"node_modules/vite": {
"version": "8.0.10",
"resolved": "https://registry.npmjs.org/vite/-/vite-8.0.10.tgz",
"integrity": "sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw==",
"version": "8.0.11",
"resolved": "https://registry.npmjs.org/vite/-/vite-8.0.11.tgz",
"integrity": "sha512-Jz1mxtUBR5xTT65VOdJZUUeoyLtqljmFkiUXhPTLZka3RDc9vpi/xXkyrnsdRcm2lIi3l3GPMnAidTsEGIj3Ow==",
"license": "MIT",
"dependencies": {
"lightningcss": "^1.32.0",
"picomatch": "^4.0.4",
"postcss": "^8.5.10",
"rolldown": "1.0.0-rc.17",
"postcss": "^8.5.14",
"rolldown": "1.0.0-rc.18",
"tinyglobby": "^0.2.16"
},
"bin": {
@ -8727,7 +8633,7 @@
},
"peerDependencies": {
"@types/node": "^20.19.0 || >=22.12.0",
"@vitejs/devtools": "^0.1.0",
"@vitejs/devtools": "^0.1.18",
"esbuild": "^0.27.0 || ^0.28.0",
"jiti": ">=1.21.0",
"less": "^4.0.0",
@ -8875,55 +8781,6 @@
"dev": true,
"license": "MIT"
},
"node_modules/vscode-jsonrpc": {
"version": "8.2.0",
"resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
"integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
"license": "MIT",
"engines": {
"node": ">=14.0.0"
}
},
"node_modules/vscode-languageserver": {
"version": "9.0.1",
"resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
"integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
"license": "MIT",
"dependencies": {
"vscode-languageserver-protocol": "3.17.5"
},
"bin": {
"installServerIntoExtension": "bin/installServerIntoExtension"
}
},
"node_modules/vscode-languageserver-protocol": {
"version": "3.17.5",
"resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
"integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
"license": "MIT",
"dependencies": {
"vscode-jsonrpc": "8.2.0",
"vscode-languageserver-types": "3.17.5"
}
},
"node_modules/vscode-languageserver-textdocument": {
"version": "1.0.12",
"resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
"integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==",
"license": "MIT"
},
"node_modules/vscode-languageserver-types": {
"version": "3.17.5",
"resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
"integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
"license": "MIT"
},
"node_modules/vscode-uri": {
"version": "3.1.0",
"resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.1.0.tgz",
"integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==",
"license": "MIT"
},
"node_modules/w3c-xmlserializer": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",

6
gitnexus-web/package.json
View file

@ -21,7 +21,7 @@
"gitnexus-shared": "file:../gitnexus-shared",
"@langchain/anthropic": "^1.3.29",
"@langchain/core": "^1.1.44",
"@langchain/google-genai": "^2.1.28",
"@langchain/google-genai": "^2.1.30",
"@langchain/langgraph": "^1.2.9",
"@langchain/ollama": "^1.2.6",
"@langchain/openai": "^1.4.5",
@ -39,7 +39,7 @@
"langchain": "^1.3.5",
"lru-cache": "^11.2.4",
"lucide-react": "^1.14.0",
"mermaid": "^11.14.0",
"mermaid": "^11.15.0",
"mnemonist": "^0.39.0",
"pandemonium": "^2.4.0",
"react": "^19.2.5",
@ -70,7 +70,7 @@
"jsdom": "^29.1.1",
"tree-sitter-wasms": "^0.1.13",
"typescript": "^5.4.5",
"vite": "^8.0.10",
"vite": "^8.0.11",
"vitest": "^4.1.5",
"wait-on": "^9.0.5"
}

17
gitnexus/.claude/settings.local.json
View file

@ -1,5 +1,18 @@
{
"permissions": {
"allow": ["mcp__plugin_claude-mem_mcp-search__get_observations"]
}
"allow": [
"mcp__plugin_claude-mem_mcp-search__get_observations",
"Skill(gitnexus-exploring)",
"Bash(npx gitnexus *)",
"mcp__obsidian-memory__search_nodes",
"mcp__obsidian-memory__add_observations",
"WebSearch",
"WebFetch(domain:cppreference.net)",
"Bash(xargs grep -l \"templateArguments\\\\|parameterTypes\")",
"Bash(gh issue *)",
"Bash(gh pr *)"
]
},
"enableAllProjectMcpServers": true,
"enabledMcpjsonServers": ["gitnexus"]
}

54
gitnexus/CHANGELOG.md
View file

@ -4,6 +4,60 @@ All notable changes to GitNexus will be documented in this file.
## [Unreleased]
## [1.6.5] - 2026-05-16
### Added
- **C++ ADL V2** — Argument-Dependent Lookup overhaul. Class-typed reference args (incl. rvalue refs) contribute associated namespaces (#1595); class-pointer args and template-specialization args (with nested template args) included (#1592, #1596); base-class associated namespaces walked via MRO (#1597); free-function reference args contribute enclosing namespace (#1598); ordinary and ADL free-call candidates merged before overload selection (#1599)
- **C++ standard-conversion-sequence ranking** for overload resolution (#1606)
- **C++ scope-resolution migration** — C++ now runs on the registry-primary RFC #909 path (#938, #1520); template-body `this->` + `using ns::name` calls resolved in the scope resolver (#1590); template specializations disambiguated in class graph IDs and receiver routing (#1587); EXTENDS edges for template and qualified template bases (#1581)
- **PHP scope-resolution migration** — PHP moved to scope-based resolution (#938, #1497, supersedes #1124)
- **Java scope-resolution migration** — RFC #909 Ring 3 (#1482)
- **C scope-resolution migration** — RFC #909 Ring 3 (#1481)
- **Incremental indexing** — `gitnexus analyze` now reuses a parse cache, writes back to DB, and short-circuits scope resolution when nothing changed (#1479)
- **`gitnexus:keep` marker** — preserves custom context sections (#605, #1508)
- **`gitnexus analyze --skip-skills` and `--index-only`** flags (#742, #1485)
- **`gitnexus wiki --timeout` and `--retries` flags** — mitigate timeout aborts on large module pages (#1543)
- **HTTP embedding `dimensions` parameter** — now forwarded to the embedding endpoint (#1498)
- **Cursor 2.4 `postToolUse` hooks** — upgraded for Read/Grep/Shell coverage (#1467)
### Fixed
- **Cross-file type propagation** — resolved a stall on large repos (#1626)
- **C++ inline-namespace ambiguity** — detect same-name ambiguity across inline namespace children (#1564, #1600); workspace-wide dependent-base name resolution for cross-file templates (#1586)
- **Parse cache persistence** — sharded on large repos to avoid corruption (#1580)
- **TypeScript ESM `.js` extension** — fallback applied to tsconfig path-alias resolution (#1530) and `.js` → `.ts` source resolution (#1525)
- **Markdown CRLF line endings** — section heading parser now handles them (#1469)
- **`gitnexus analyze --no-stats`** — actually omits volatile counts (#1477, #1478)
- **`ensureGitNexusIgnored`** — tolerate read-only workspaces (#1549, #1550)
- **Claude augment hook** — skipped when GitNexus server owns the DB (#1493)
- **Docker runtime image** — symlink `gitnexus` binary onto `$PATH` (#1551); install `ca-certificates` for TLS verification (#1545, #1547); include duckdb installer script (#1502)
- **Windows reliability** — fix 32767-char tree-sitter crash and VECTOR-extension SIGSEGV (#1433); platform-aware `tsc` build command for win32 (#1531)
- **Search / FTS** — guard against undefined `bm25Results` when FTS is unavailable (#1489, #1540); CONTAINS fallback in augment when FTS indexes unavailable (#1476)
- **Wiki** — sanitize generated mermaid diagrams (#1539)
- **Hooks** — cap concurrent augment subprocesses to prevent runaway fan-out (#1486, #1510)
- **LadybugDB** — drain checkpoint result before close (#1506); recover `gitnexus analyze` from orphan sidecars when the main DB file is missing (#1622)
- **Group / contracts** — detect `httpx` async consumers (#1408)
- **Server hardening** — sanitize repo name to prevent argument injection on `/api/analyze` (#1305)
### Changed
- **CI release pipeline unified under `publish.yml`** — single source of truth for npm publish, provenance, and GitHub Release creation (#1610)
- **CI: skip RC build on release PRs** — release/* branches no longer cut redundant RCs (#1474)
- **CI (Claude review): make `/review` reliably post PR comments** (#1522); allow Bash in code-review job without interactive approval (#1523)
- **CI publish (post-merge fixes)** — bump publish job to Node 24 for npm OIDC support (#1628); engage npm Trusted Publishing OIDC properly (#1627)
- **Tests** — remove flaky regression test for resource exhaustion (#1521); de-flake regex linearity assertions in U8 (#1475)
### Chore / Dependencies
- `vitest` 4.1.5 → 4.1.6 in /gitnexus (#1605)
- `@langchain/google-genai` bump in /gitnexus-web (#1554)
- `vite` 8.0.10 → 8.0.11 in /gitnexus-web (#1555)
- `mermaid` bump (#1514)
- `protobufjs` 7.5.5 → 7.5.8 + `@protobufjs/utf8` in /gitnexus (#1535, #1536)
- `urllib3` bump in /eval uv group (#1512)
- GitHub Actions: `sigstore/cosign-installer` 4.1.1 → 4.1.2 (#1557)
## [1.6.4] - 2026-05-10
### Added

46
gitnexus/hooks/claude/gitnexus-hook.cjs
View file

@ -14,6 +14,8 @@
const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
const { acquireHookSlot } = require('./hook-lock.cjs');
const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
/**
* Read JSON input from stdin synchronously.
@ -102,6 +104,28 @@ function findGitNexusDir(startDir) {
return null;
}
function hasGitNexusServerOwner(gitNexusDir) {
return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
}
function extractAugmentContext(stderr) {
const output = (stderr || '').trim();
const marker = output.indexOf('[GitNexus]');
const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
if (debug && output.length > 0) {
// Emit the FULL discarded prefix (everything before the marker, or all of
// it when no marker is present) so suppressed diagnostics — KuzuDB lock
// warnings, parser errors, etc. — remain recoverable on the hook's own
// stderr. The untruncated payload lets operators see exactly what was
// filtered out instead of a 180-char JSON-quoted preview.
const discarded = marker === -1 ? output : output.slice(0, marker).trim();
if (discarded.length > 0) {
process.stderr.write(`[GitNexus hook] augment stderr discarded prefix:\n${discarded}\n`);
}
}
return marker === -1 ? '' : output.slice(marker).trim();
}
/**
* Extract search pattern from tool input.
*/
@ -167,6 +191,10 @@ function extractPattern(toolName, toolInput) {
* 3. Fall back to npx (returns empty string)
*/
function resolveCliPath() {
const fromEnv = process.env.GITNEXUS_HOOK_CLI_PATH;
if (fromEnv !== undefined && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) {
return String(fromEnv);
}
let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js');
if (!fs.existsSync(cliPath)) {
try {
@ -207,7 +235,8 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
function handlePreToolUse(input) {
const cwd = input.cwd || process.cwd();
if (!path.isAbsolute(cwd)) return;
if (!findGitNexusDir(cwd)) return;
const gitNexusDir = findGitNexusDir(cwd);
if (!gitNexusDir) return;
const toolName = input.tool_name || '';
const toolInput = input.tool_input || {};
@ -216,20 +245,29 @@ function handlePreToolUse(input) {
const pattern = extractPattern(toolName, toolInput);
if (!pattern || pattern.length < 3) return;
if (hasGitNexusServerOwner(gitNexusDir)) {
process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
return;
}
const release = acquireHookSlot(gitNexusDir);
if (!release) return;
const cliPath = resolveCliPath();
let result = '';
try {
const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000);
if (!child.error && child.status === 0) {
result = child.stderr || '';
result = extractAugmentContext(child.stderr || '');
}
} catch {
/* graceful failure */
} finally {
release();
}
if (result && result.trim()) {
sendHookResponse('PreToolUse', result.trim());
if (result) {
sendHookResponse('PreToolUse', result);
}
}

238
gitnexus/hooks/claude/hook-db-lock-probe.cjs Normal file
View file

@ -0,0 +1,238 @@
/**
* Cross-platform best-effort probe: does another process hold dbPath open
* with a command line that looks like a GitNexus MCP/serve server?
*
* Backends (no user-installed Sysinternals):
* - Linux: scan procfs under /proc (per-PID fd entries) via stat(2) (dev+inode); works without lsof;
* optional lsof fallback when proc scan finds nothing.
* - macOS / *BSD / etc.: trusted lsof + ps (absolute paths first).
* - Windows: Restart Manager (rstrtmgr) via bundled PowerShell script +
* Win32_Process for command lines; trusted powershell.exe under %SystemRoot%.
*
* Fail-open on most errors; fail-closed only on lsof ETIMEDOUT (Unix) or
* PowerShell ETIMEDOUT (Windows), matching the hook contract.
*/
const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
function isGitNexusServerCommand(command) {
const hasServerMode = /(?:^|\s)(mcp|serve)(?:\s|$)/.test(command);
const hasGitNexus =
/(?:^|[/\\\s])gitnexus(?:\.cmd)?(?:\s|$)/.test(command) ||
/node_modules[/\\]gitnexus[/\\]/.test(command);
return hasServerMode && hasGitNexus;
}
function resolveHookBinary(tool) {
const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH';
const fromEnv = process.env[envKey];
if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) {
return String(fromEnv);
}
const candidates =
tool === 'lsof'
? ['/usr/bin/lsof', '/usr/sbin/lsof', '/sbin/lsof', tool]
: ['/bin/ps', '/usr/bin/ps', tool];
for (const candidate of candidates) {
if (candidate === tool) return tool;
try {
if (fs.existsSync(candidate)) return candidate;
} catch {
/* ignore */
}
}
return tool;
}
function resolveWindowsPowerShellPath() {
const fromEnv = process.env.GITNEXUS_HOOK_POWERSHELL_PATH;
if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv).trim())) {
return String(fromEnv).trim();
}
const root = process.env.SystemRoot || 'C:\\Windows';
const ps = path.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
if (fs.existsSync(ps)) return ps;
const psWow = path.join(root, 'SysWOW64', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
if (fs.existsSync(psWow)) return psWow;
return 'powershell.exe';
}
// Sentinel:
// undefined = not loaded yet (try the read)
// string = encoded PowerShell command (successful load)
// null = load attempted and failed (do not retry; warning already emitted)
let windowsRmListPsEncodedCommandCache;
let windowsRmListPsLoadFailureWarned = false;
function getWindowsRmListEncodedCommand() {
if (windowsRmListPsEncodedCommandCache !== undefined) {
return windowsRmListPsEncodedCommandCache;
}
try {
const ps1Path = path.join(__dirname, 'win-rm-list-json.ps1');
const src = fs
.readFileSync(ps1Path, 'utf8')
.replace(/^\uFEFF/, '')
.replace(/\r\n/g, '\n');
windowsRmListPsEncodedCommandCache = Buffer.from(src, 'utf16le').toString('base64');
} catch (err) {
windowsRmListPsEncodedCommandCache = null;
if (
!windowsRmListPsLoadFailureWarned &&
(process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true')
) {
windowsRmListPsLoadFailureWarned = true;
const msg = err && err.message ? String(err.message).slice(0, 200) : 'unknown';
process.stderr.write(`[GitNexus hook] win-rm-list-json.ps1 load failed: ${msg}\n`);
}
}
return windowsRmListPsEncodedCommandCache;
}
function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) {
const encoded = getWindowsRmListEncodedCommand();
if (!encoded) return false;
const psExe = resolveWindowsPowerShellPath();
const r = spawnSync(
psExe,
[
'-NoProfile',
'-NonInteractive',
'-ExecutionPolicy',
'Bypass',
'-STA',
'-EncodedCommand',
encoded,
],
{
encoding: 'utf-8',
timeout: 6000,
stdio: ['ignore', 'pipe', 'ignore'],
env: { ...process.env, GITNEXUS_HOOK_RM_TARGET: dbPathAbs },
},
);
// ETIMEDOUT means the PowerShell probe didn't return in time; treat as 'unresponsive process holds DB' → fail-closed (skip augment).
if (r.error) return r.error.code === 'ETIMEDOUT';
if (r.status !== 0) return false;
let rows;
try {
rows = JSON.parse(String(r.stdout || '').trim() || '[]');
} catch {
return false;
}
if (!Array.isArray(rows)) return false;
for (const row of rows) {
const procId = Number(row.pid);
const cmd = String(row.cmd || '');
if (!Number.isFinite(procId) || procId === myPid) continue;
if (isGitNexusServerCommand(cmd)) return true;
}
return false;
}
function readLinuxCmdline(pidStr) {
try {
return fs.readFileSync(`/proc/${pidStr}/cmdline`, 'utf8').replace(/\0+/g, ' ').trim();
} catch {
return '';
}
}
function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
const raw = process.env.GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS;
const budget = Number(raw && String(raw).trim()) ? Number.parseInt(String(raw), 10) : 1200;
const start = Date.now();
let targetStat;
try {
targetStat = fs.statSync(dbPathAbs);
} catch {
return false;
}
let procEntries;
try {
procEntries = fs.readdirSync('/proc', { withFileTypes: true });
} catch {
return false;
}
for (const ent of procEntries) {
if (Date.now() - start > budget) return false;
if (!ent.isDirectory() || !/^\d+$/.test(ent.name)) continue;
const pid = Number.parseInt(ent.name, 10);
if (!Number.isFinite(pid) || pid === myPid) continue;
const fdDir = path.join('/proc', ent.name, 'fd');
let fds;
try {
fds = fs.readdirSync(fdDir);
} catch {
continue;
}
let holds = false;
for (const fd of fds) {
if (Date.now() - start > budget) return false;
try {
const st = fs.statSync(path.join(fdDir, fd));
if (st.dev === targetStat.dev && st.ino === targetStat.ino) {
holds = true;
break;
}
} catch {
/* ignore */
}
}
if (!holds) continue;
if (isGitNexusServerCommand(readLinuxCmdline(ent.name))) return true;
}
return false;
}
function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
const lsofPath = resolveHookBinary('lsof');
const lsof = spawnSync(lsofPath, ['-nP', '-t', '--', dbPathAbs], {
encoding: 'utf-8',
timeout: 1000,
stdio: ['ignore', 'pipe', 'ignore'],
});
if (lsof.error) return lsof.error.code === 'ETIMEDOUT';
const pids = (lsof.stdout || '').split(/\s+/).filter(Boolean);
const psPath = resolveHookBinary('ps');
for (const pid of pids) {
if (Number(pid) === myPid) continue;
const ps = spawnSync(psPath, ['-p', pid, '-o', 'command='], {
encoding: 'utf-8',
timeout: 500,
stdio: ['ignore', 'pipe', 'ignore'],
});
if (ps.error) {
if (ps.error.code === 'ETIMEDOUT') return true;
continue;
}
if (isGitNexusServerCommand(ps.stdout || '')) return true;
}
return false;
}
/**
* @param {string} dbPath Absolute or relative path to the DB file (e.g. .../lbug).
* @param {number} myPid Current process PID (hook runner), excluded from matches.
*/
function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) {
if (!fs.existsSync(dbPath)) return false;
const dbPathAbs = path.resolve(dbPath);
if (process.platform === 'win32') {
return hasGitNexusServerOwnerWindows(dbPathAbs, myPid);
}
if (process.platform === 'linux') {
if (linuxProcScanFindGitNexusServer(dbPathAbs, myPid)) return true;
return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
}
return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
}
module.exports = {
hasGitNexusDbLockedByGitNexusServer,
};

119
gitnexus/hooks/claude/hook-lock.cjs Normal file
View file

@ -0,0 +1,119 @@
const fs = require('fs');
const path = require('path');
const HOOK_LOCK_SUBDIR = '.hook-locks';
const HOOK_LOCK_MAX_INFLIGHT = 3;
const HOOK_LOCK_STALE_MS = 30000;
function acquireHookSlot(gitNexusDir) {
const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR);
try {
fs.mkdirSync(lockDir, { recursive: true });
} catch {
// Cannot create lock dir (read-only fs, cross-user perm denial, out of
// inodes, etc.) — fail closed by returning null. Caller skips augment.
// Fail-open here would let N concurrent hooks all proceed unguarded and
// reintroduce the #1486 fan-out the guard exists to prevent.
return null;
}
const myPidStr = String(process.pid);
for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) {
const slotPath = path.join(lockDir, `slot-${slot}.lock`);
for (let attempt = 0; attempt < 2; attempt++) {
try {
fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' });
let released = false;
const release = () => {
if (released) return;
released = true;
try {
// Only unlink if we still own the slot. If we appeared stale and
// another hook took over, the file now belongs to it — leave alone.
const content = fs.readFileSync(slotPath, 'utf-8').trim();
if (content === myPidStr) fs.unlinkSync(slotPath);
} catch {
/* already removed or unreadable */
}
};
process.on('exit', release);
return release;
} catch {
// Slot exists. Decide whether to take it over.
// Open once and inspect mtime + content via the same fd so there's
// no TOCTOU between the metadata check and the content read
// (codeql js/file-system-race).
let fd;
try {
fd = fs.openSync(slotPath, 'r');
} catch {
continue; // Vanished between EEXIST and open — retry this slot.
}
let isLive = false;
let mtimeMs = Date.now();
try {
mtimeMs = fs.fstatSync(fd).mtimeMs;
const buf = Buffer.alloc(32);
const n = fs.readSync(fd, buf, 0, 32, 0);
const ownerStr = buf.slice(0, n).toString('utf-8').trim();
if (ownerStr === '') {
// Owner created the file but hasn't written its PID yet. The
// wx open+write window is microseconds; give it the benefit
// of the doubt and treat as live.
isLive = true;
} else {
const owner = Number.parseInt(ownerStr, 10);
if (Number.isFinite(owner) && owner > 0) {
try {
process.kill(owner, 0);
isLive = true;
} catch (e) {
// ESRCH = process gone → treat as dead. EPERM = process exists
// but owned by another user (cross-user lock dir) → still alive,
// keep the slot. Anything else: be conservative, assume alive.
if (e && e.code === 'ESRCH') {
isLive = false;
} else {
isLive = true;
}
}
}
}
} catch {
/* unreadable — treat as dead */
} finally {
try {
fs.closeSync(fd);
} catch {
/* already closed */
}
}
// For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins —
// a slow-but-alive hook is never wrongly evicted. For older slots,
// age is the final arbiter as a defense against PID reuse on long-
// abandoned slots. 30s >> the 7s augment timeout, so a healthy run
// never crosses this threshold.
if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) {
isLive = false;
}
if (isLive) break; // Try the next slot.
try {
fs.unlinkSync(slotPath);
} catch {
/* another hook beat us to it — retry will hit EEXIST */
}
// Loop and retry this slot.
}
}
}
return null;
}
module.exports = {
HOOK_LOCK_SUBDIR,
HOOK_LOCK_MAX_INFLIGHT,
HOOK_LOCK_STALE_MS,
acquireHookSlot,
};

76
gitnexus/hooks/claude/win-rm-list-json.ps1 Normal file
View file

@ -0,0 +1,76 @@
$ErrorActionPreference = 'Stop'
$target = $env:GITNEXUS_HOOK_RM_TARGET
if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
$target = (Resolve-Path -LiteralPath $target).ProviderPath
if (-not ([Management.Automation.PSTypeName]'GitNexusHookRm.Native').Type) {
Add-Type @'
using System;
using System.Runtime.InteropServices;
namespace GitNexusHookRm {
public static class Native {
public const int ErrorMoreData = 234;
[StructLayout(LayoutKind.Sequential, Pack = 4)]
public struct RM_UNIQUE_PROCESS {
public int dwProcessId;
public long ProcessStartTime;
}
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct RM_PROCESS_INFO {
public RM_UNIQUE_PROCESS Process;
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
public string strAppName;
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)]
public string strServiceShortName;
public uint ApplicationType;
public uint AppStatus;
public uint TSSessionId;
public uint bRestartable;
}
[DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)]
public static extern int RmStartSession(out uint pSessionHandle, uint dwSessionFlags, string strSessionKey);
[DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)]
public static extern int RmRegisterResources(uint pSessionHandle, uint nFiles, string[] rgsFileNames, uint nApplications, IntPtr rgApplications, uint nServices, string[] rgsServiceNames);
[DllImport("rstrtmgr.dll")]
public static extern int RmGetList(uint dwSessionHandle, out uint pnProcInfoNeeded, ref uint pnProcInfo, [In, Out] RM_PROCESS_INFO[] rgAffectedApps, ref uint lpdwRebootReasons);
[DllImport("rstrtmgr.dll")]
public static extern int RmEndSession(uint pSessionHandle);
}
}
'@
}
$h = [uint32]0
$key = [guid]::NewGuid().ToString('N')
$rmErr = [GitNexusHookRm.Native]::RmStartSession([ref]$h, 0, $key)
if ($rmErr -ne 0) { Write-Output '[]'; exit 0 }
$files = @($target)
$err = [GitNexusHookRm.Native]::RmRegisterResources($h, 1, $files, 0, [IntPtr]::Zero, 0, $null)
if ($err -ne 0) {
[void][GitNexusHookRm.Native]::RmEndSession($h)
Write-Output '[]'
exit 0
}
$need = [uint32]0
$n = [uint32]0
$reboot = [uint32]0
$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $null, [ref]$reboot)
if ($err -ne [GitNexusHookRm.Native]::ErrorMoreData) {
[void][GitNexusHookRm.Native]::RmEndSession($h)
Write-Output '[]'
exit 0
}
$n = $need
$buf = New-Object GitNexusHookRm.Native+RM_PROCESS_INFO[] ([int]$n)
$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $buf, [ref]$reboot)
[void][GitNexusHookRm.Native]::RmEndSession($h)
if ($err -ne 0) { Write-Output '[]'; exit 0 }
$out = @()
for ($i = 0; $i -lt [int]$n; $i++) {
$procId = $buf[$i].Process.dwProcessId
$p = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$procId" -ErrorAction SilentlyContinue
$cmd = if ($p) { $p.CommandLine } else { '' }
$out += [PSCustomObject]@{ pid = [int]$procId; cmd = $cmd }
}
ConvertTo-Json -InputObject @($out) -Compress

322
gitnexus/package-lock.json generated
View file

@ -1,12 +1,12 @@
{
"name": "gitnexus",
"version": "1.6.4",
"version": "1.6.5",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "gitnexus",
"version": "1.6.4",
"version": "1.6.5",
"hasInstallScript": true,
"license": "PolyForm-Noncommercial-1.0.0",
"dependencies": {
@ -147,9 +147,9 @@
}
},
"node_modules/@emnapi/core": {
"version": "1.9.2",
"resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.2.tgz",
"integrity": "sha512-UC+ZhH3XtczQYfOlu3lNEkdW/p4dsJ1r/bP7H8+rhao3TTTMO1ATq/4DdIi23XuGoFY+Cz0JmCbdVl0hz9jZcA==",
"version": "1.10.0",
"resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
"integrity": "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==",
"dev": true,
"license": "MIT",
"optional": true,
@ -1660,9 +1660,9 @@
}
},
"node_modules/@oxc-project/types": {
"version": "0.126.0",
"resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.126.0.tgz",
"integrity": "sha512-oGfVtjAgwQVVpfBrbtk4e1XDyWHRFta6BS3GWVzrF8xYBT2VGQAk39yJS/wFSMrZqoiCU4oghT3Ch0HaHGIHcQ==",
"version": "0.130.0",
"resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.130.0.tgz",
"integrity": "sha512-ibD2usx9JRu7f5pu2tMKMI4cpA4NgXJQoYRP4pQ7Pxmn1l6k/53qWtQWZayhYy3X4QZkt90Ot+mJEaeXouio6Q==",
"dev": true,
"license": "MIT",
"funding": {
@ -1688,9 +1688,9 @@
"license": "BSD-3-Clause"
},
"node_modules/@protobufjs/codegen": {
"version": "2.0.4",
"resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.4.tgz",
"integrity": "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==",
"version": "2.0.5",
"resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz",
"integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
"license": "BSD-3-Clause"
},
"node_modules/@protobufjs/eventemitter": {
@ -1716,9 +1716,9 @@
"license": "BSD-3-Clause"
},
"node_modules/@protobufjs/inquire": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.0.tgz",
"integrity": "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==",
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.1.tgz",
"integrity": "sha512-mnzgDV26ueAvk7rsbt9L7bE0SuAoqyuys/sMMrmVcN5x9VsxpcG3rqAUSgDyLp0UZlmNfIbQ4fHfCtreVBk8Ew==",
"license": "BSD-3-Clause"
},
"node_modules/@protobufjs/path": {
@ -1734,15 +1734,15 @@
"license": "BSD-3-Clause"
},
"node_modules/@protobufjs/utf8": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.0.tgz",
"integrity": "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==",
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.1.tgz",
"integrity": "sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==",
"license": "BSD-3-Clause"
},
"node_modules/@rolldown/binding-android-arm64": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.16.tgz",
"integrity": "sha512-rhY3k7Bsae9qQfOtph2Pm2jZEA+s8Gmjoz4hhmx70K9iMQ/ddeae+xhRQcM5IuVx5ry1+bGfkvMn7D6MJggVSA==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.1.tgz",
"integrity": "sha512-fJI3I0r3C3Oj/zdBCpaCmBRZYf07xpaq4yCfDDoSFm+beWNzbIl26puW8RraUdugoJw/95zerNOn6jasAhzSmg==",
"cpu": [
"arm64"
],
@ -1757,9 +1757,9 @@
}
},
"node_modules/@rolldown/binding-darwin-arm64": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.16.tgz",
"integrity": "sha512-rNz0yK078yrNn3DrdgN+PKiMOW8HfQ92jQiXxwX8yW899ayV00MLVdaCNeVBhG/TbH3ouYVObo8/yrkiectkcQ==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.1.tgz",
"integrity": "sha512-cKnAhWEsV7TPcA/5EAteDp6KcJZBQ2G+BqE7zayMMi7kMvwRsbv7WT9aOnn0WNl4SKEIf43vjS31iUPu80nzXg==",
"cpu": [
"arm64"
],
@ -1774,9 +1774,9 @@
}
},
"node_modules/@rolldown/binding-darwin-x64": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.16.tgz",
"integrity": "sha512-r/OmdR00HmD4i79Z//xO06uEPOq5hRXdhw7nzkxQxwSavs3PSHa1ijntdpOiZ2mzOQ3fVVu8C1M19FoNM+dMUQ==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.1.tgz",
"integrity": "sha512-YKrVwQjIRBPo+5G/u03wGjbdy4q7pyzCe93DK9VJ7zkVmeg8LJ7GbgsiHWdR4xSoe4CAXRD7Bcjgbtr64bkXNg==",
"cpu": [
"x64"
],
@ -1791,9 +1791,9 @@
}
},
"node_modules/@rolldown/binding-freebsd-x64": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.16.tgz",
"integrity": "sha512-KcRE5w8h0OnjUatG8pldyD14/CQ5Phs1oxfR+3pKDjboHRo9+MkqQaiIZlZRpsxC15paeXme/I127tUa9TXJ6g==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.1.tgz",
"integrity": "sha512-z/oBsREo46SsFqBwYtFe0kpJeBijAT48O/WXLI4suiCLBkr03RTtTJMCzSdDd2znlh8VJizL09XVkQgk8IZonw==",
"cpu": [
"x64"
],
@ -1808,9 +1808,9 @@
}
},
"node_modules/@rolldown/binding-linux-arm-gnueabihf": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.16.tgz",
"integrity": "sha512-bT0guA1bpxEJ/ZhTRniQf7rNF8ybvXOuWbNIeLABaV5NGjx4EtOWBTSRGWFU9ZWVkPOZ+HNFP8RMcBokBiZ0Kg==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.1.tgz",
"integrity": "sha512-ik8q7GM11zxvYxFc2PeDcT6TBvhCQMaUxfph/M5l9sKuTs/Sjg3L+Byw0F7w0ZVLBZmx30P+gG0ECzzN+MFcmQ==",
"cpu": [
"arm"
],
@ -1825,9 +1825,9 @@
}
},
"node_modules/@rolldown/binding-linux-arm64-gnu": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.16.tgz",
"integrity": "sha512-+tHktCHWV8BDQSjemUqm/Jl/TPk3QObCTIjmdDy/nlupcujZghmKK2962LYrqFpWu+ai01AN/REOH3NEpqvYQg==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.1.tgz",
"integrity": "sha512-QoSx2EkyrrdZ6kcyE8stqZ62t0Yra8Fs5ia9lOxJrh6TMQJK7gQKmscdTHf7pOXKREKrVwOtJcQG3qVSfc866A==",
"cpu": [
"arm64"
],
@ -1842,9 +1842,9 @@
}
},
"node_modules/@rolldown/binding-linux-arm64-musl": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.16.tgz",
"integrity": "sha512-3fPzdREH806oRLxpTWW1Gt4tQHs0TitZFOECB2xzCFLPKnSOy90gwA7P29cksYilFO6XVRY1kzga0cL2nRjKPg==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.1.tgz",
"integrity": "sha512-uwNwFpwKeNiZawfAWBgg0VIztPTV3ihhh1vV334h9ivnNLorxnQMU6Fz8wG1Zb4Qh9LC1/MkcyT3YlDXG3Rsgg==",
"cpu": [
"arm64"
],
@ -1859,9 +1859,9 @@
}
},
"node_modules/@rolldown/binding-linux-ppc64-gnu": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.16.tgz",
"integrity": "sha512-EKwI1tSrLs7YVw+JPJT/G2dJQ1jl9qlTTTEG0V2Ok/RdOenRfBw2PQdLPyjhIu58ocdBfP7vIRN/pvMsPxs/AQ==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.1.tgz",
"integrity": "sha512-zY1bul7OWr7DFBiJ++wofXvnr8B45ce3QsQUhKrIhXsygAh7bTkwyeM1bi1a2g5C/yC/N8TZyGDEoMfm/l9mpg==",
"cpu": [
"ppc64"
],
@ -1876,9 +1876,9 @@
}
},
"node_modules/@rolldown/binding-linux-s390x-gnu": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.16.tgz",
"integrity": "sha512-Uknladnb3Sxqu6SEcqBldQyJUpk8NleooZEc0MbRBJ4inEhRYWZX0NJu12vNf2mqAq7gsofAxHrGghiUYjhaLQ==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.1.tgz",
"integrity": "sha512-0frlsT/f4Ft6I7SMESTKnF3cZsdicQn1dCMkF/jT9wDLE+gGoiQfv1nmT9e+s7s/fekvvy6tZM2jHvI2tkbJDQ==",
"cpu": [
"s390x"
],
@ -1893,9 +1893,9 @@
}
},
"node_modules/@rolldown/binding-linux-x64-gnu": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.16.tgz",
"integrity": "sha512-FIb8+uG49sZBtLTn+zt1AJ20TqVcqWeSIyoVt0or7uAWesgKaHbiBh6OpA/k9v0LTt+PTrb1Lao133kP4uVxkg==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.1.tgz",
"integrity": "sha512-XABVmGp9Tg0WspTVvwduTc4fpqy6JnAUrSQe6OuyqD/03nI7r0O9OWUkMIwFrjKAIqolvqoA4ZrJppgwE0Gxmw==",
"cpu": [
"x64"
],
@ -1910,9 +1910,9 @@
}
},
"node_modules/@rolldown/binding-linux-x64-musl": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.16.tgz",
"integrity": "sha512-RuERhF9/EgWxZEXYWCOaViUWHIboceK4/ivdtQ3R0T44NjLkIIlGIAVAuCddFxsZ7vnRHtNQUrt2vR2n2slB2w==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.1.tgz",
"integrity": "sha512-bV4fzswuzVcKD90o/VM6QqKxnxlDq0g2BISDLNVmxrnhpv1DDbyPhCIjYfvzYLV+MvkKKnQt2Q6AO86SEBULUQ==",
"cpu": [
"x64"
],
@ -1927,9 +1927,9 @@
}
},
"node_modules/@rolldown/binding-openharmony-arm64": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.16.tgz",
"integrity": "sha512-mXcXnvd9GpazCxeUCCnZ2+YF7nut+ZOEbE4GtaiPtyY6AkhZWbK70y1KK3j+RDhjVq5+U8FySkKRb/+w0EeUwA==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.1.tgz",
"integrity": "sha512-/Mh0Zhq3OP7fVs0kcQHZP6lZEthMGTaSf8UBQYSFEZDWGXXlEC+nJ6EqenaK2t4LBXMe3A+K/G2BVXXdtOr4PQ==",
"cpu": [
"arm64"
],
@ -1944,9 +1944,9 @@
}
},
"node_modules/@rolldown/binding-wasm32-wasi": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.16.tgz",
"integrity": "sha512-3Q2KQxnC8IJOLqXmUMoYwyIPZU9hzRbnHaoV3Euz+VVnjZKcY8ktnNP8T9R4/GGQtb27C/UYKABxesKWb8lsvQ==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.1.tgz",
"integrity": "sha512-+1xc9X45l8ufsBAm6Gjvx2qDRIY9lTVt0cgWNcJ+1gdhXvkbxePA60yRTwSTuXL09CMhyJmjpV7E3NoyxbqFQQ==",
"cpu": [
"wasm32"
],
@ -1954,8 +1954,8 @@
"license": "MIT",
"optional": true,
"dependencies": {
"@emnapi/core": "1.9.2",
"@emnapi/runtime": "1.9.2",
"@emnapi/core": "1.10.0",
"@emnapi/runtime": "1.10.0",
"@napi-rs/wasm-runtime": "^1.1.4"
},
"engines": {
@ -1963,9 +1963,9 @@
}
},
"node_modules/@rolldown/binding-wasm32-wasi/node_modules/@emnapi/runtime": {
"version": "1.9.2",
"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.9.2.tgz",
"integrity": "sha512-3U4+MIWHImeyu1wnmVygh5WlgfYDtyf0k8AbLhMFxOipihf6nrWC4syIm/SwEeec0mNSafiiNnMJwbza/Is6Lw==",
"version": "1.10.0",
"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
"integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
"dev": true,
"license": "MIT",
"optional": true,
@ -1974,9 +1974,9 @@
}
},
"node_modules/@rolldown/binding-win32-arm64-msvc": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.16.tgz",
"integrity": "sha512-tj7XRemQcOcFwv7qhpUxMTBbI5mWMlE4c1Omhg5+h8GuLXzyj8HviYgR+bB2DMDgRqUE+jiDleqSCRjx4aYk/Q==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.1.tgz",
"integrity": "sha512-1D+UqZdfnuR+Jy1GgMJwi85bD40H21uNmOPRWQhw4oRSuolZ/B5rixZ45DK2KXOTCvmVCecauWgEhbw8bI7tOw==",
"cpu": [
"arm64"
],
@ -1991,9 +1991,9 @@
}
},
"node_modules/@rolldown/binding-win32-x64-msvc": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.16.tgz",
"integrity": "sha512-PH5DRZT+F4f2PTXRXR8uJxnBq2po/xFtddyabTJVJs/ZYVHqXPEgNIr35IHTEa6bpa0Q8Awg+ymkTaGnKITw4g==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.1.tgz",
"integrity": "sha512-INAycaWuhlOK3wk4mRHGsdgwYWmd9cChdPdE9bwWmy6rn9VqVNYNFGhOdXrofXUxwHIncSiPNb8tNm8knDVIeQ==",
"cpu": [
"x64"
],
@ -2008,9 +2008,9 @@
}
},
"node_modules/@rolldown/pluginutils": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.16.tgz",
"integrity": "sha512-45+YtqxLYKDWQouLKCrpIZhke+nXxhsw+qAHVzHDVwttyBlHNBVs2K25rDXrZzhpTp9w1FlAlvweV1H++fdZoA==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz",
"integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==",
"dev": true,
"license": "MIT"
},
@ -2029,9 +2029,9 @@
"license": "MIT"
},
"node_modules/@tybys/wasm-util": {
"version": "0.10.1",
"resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
"integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
"version": "0.10.2",
"resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.2.tgz",
"integrity": "sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==",
"dev": true,
"license": "MIT",
"optional": true,
@ -2220,14 +2220,14 @@
}
},
"node_modules/@vitest/coverage-v8": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.5.tgz",
"integrity": "sha512-38C0/Ddb7HcRG0Z4/DUem8x57d2p9jYgp18mkaYswEOQBGsI1CG4f/hjm0ZCeaJfWhSZ4k7jgs29V1Zom7Ki9A==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.6.tgz",
"integrity": "sha512-36l628fQ/9a/8ihy97eOtEnvWQEdqULQOJtcaxtoNq0G1w3Mxd4szSahOaMM9/NGyZ+hyKcMtIW/WIxq0XQViQ==",
"dev": true,
"license": "MIT",
"dependencies": {
"@bcoe/v8-coverage": "^1.0.2",
"@vitest/utils": "4.1.5",
"@vitest/utils": "4.1.6",
"ast-v8-to-istanbul": "^1.0.0",
"istanbul-lib-coverage": "^3.2.2",
"istanbul-lib-report": "^3.0.1",
@ -2241,8 +2241,8 @@
"url": "https://opencollective.com/vitest"
},
"peerDependencies": {
"@vitest/browser": "4.1.5",
"vitest": "4.1.5"
"@vitest/browser": "4.1.6",
"vitest": "4.1.6"
},
"peerDependenciesMeta": {
"@vitest/browser": {
@ -2251,16 +2251,16 @@
}
},
"node_modules/@vitest/expect": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.5.tgz",
"integrity": "sha512-PWBaRY5JoKuRnHlUHfpV/KohFylaDZTupcXN1H9vYryNLOnitSw60Mw9IAE2r67NbwwzBw/Cc/8q9BK3kIX8Kw==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.6.tgz",
"integrity": "sha512-7EHDquPthALSV0jhhjgEW8FXaviMx7rSqu8W6oqCoAuOhKov814P99QDV1pxMA3QPv21YudvJngIhjrNI4opLg==",
"dev": true,
"license": "MIT",
"dependencies": {
"@standard-schema/spec": "^1.1.0",
"@types/chai": "^5.2.2",
"@vitest/spy": "4.1.5",
"@vitest/utils": "4.1.5",
"@vitest/spy": "4.1.6",
"@vitest/utils": "4.1.6",
"chai": "^6.2.2",
"tinyrainbow": "^3.1.0"
},
@ -2269,13 +2269,13 @@
}
},
"node_modules/@vitest/mocker": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.5.tgz",
"integrity": "sha512-/x2EmFC4mT4NNzqvC3fmesuV97w5FC903KPmey4gsnJiMQ3Be1IlDKVaDaG8iqaLFHqJ2FVEkxZk5VmeLjIItw==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.6.tgz",
"integrity": "sha512-MCFc63czMjEInOlcY2cpQCvCN+KgbAn+60xu9cMgP4sKaLC5JNAKw7JH8QdAnoAC88hW1IiSNZ+GgVXlN1UcMQ==",
"dev": true,
"license": "MIT",
"dependencies": {
"@vitest/spy": "4.1.5",
"@vitest/spy": "4.1.6",
"estree-walker": "^3.0.3",
"magic-string": "^0.30.21"
},
@ -2296,9 +2296,9 @@
}
},
"node_modules/@vitest/pretty-format": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.5.tgz",
"integrity": "sha512-7I3q6l5qr03dVfMX2wCo9FxwSJbPdwKjy2uu/YPpU3wfHvIL4QHwVRp57OfGrDFeUJ8/8QdfBKIV12FTtLn00g==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.6.tgz",
"integrity": "sha512-h5SxD/IzNhZYnrSZRsUZQIC+vD0GY8cUvq0iwsmkFKixRCKLLWqCXa/FIQ4S1R+sI+PGoojkHsdNrbZiM9Qpgw==",
"dev": true,
"license": "MIT",
"dependencies": {
@ -2309,13 +2309,13 @@
}
},
"node_modules/@vitest/runner": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.5.tgz",
"integrity": "sha512-2D+o7Pr82IEO46YPpoA/YU0neeyr6FTerQb5Ro7BUnBuv6NQtT/kmVnczngiMEBhzgqz2UZYl5gArejsyERDSQ==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.6.tgz",
"integrity": "sha512-nOPCmn2+yD0ZNmKdsXGv/UxMMWbMuKeD6GyYncNwdkYDxpQvrPSKYj2rWuDjC2Y4b6w6hjip5dBKFzEUuZe3vA==",
"dev": true,
"license": "MIT",
"dependencies": {
"@vitest/utils": "4.1.5",
"@vitest/utils": "4.1.6",
"pathe": "^2.0.3"
},
"funding": {
@ -2323,14 +2323,14 @@
}
},
"node_modules/@vitest/snapshot": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.5.tgz",
"integrity": "sha512-zypXEt4KH/XgKGPUz4eC2AvErYx0My5hfL8oDb1HzGFpEk1P62bxSohdyOmvz+d9UJwanI68MKwr2EquOaOgMQ==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.6.tgz",
"integrity": "sha512-YhsdE6xAVfTDmzjxL2ZDUvjj+ZsgyOKe+TdQzqkD72wIOmHka8NuGQ6NpTNZv9D2Z63fbwWKJPeVpEw4EQgYxw==",
"dev": true,
"license": "MIT",
"dependencies": {
"@vitest/pretty-format": "4.1.5",
"@vitest/utils": "4.1.5",
"@vitest/pretty-format": "4.1.6",
"@vitest/utils": "4.1.6",
"magic-string": "^0.30.21",
"pathe": "^2.0.3"
},
@ -2339,9 +2339,9 @@
}
},
"node_modules/@vitest/spy": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.5.tgz",
"integrity": "sha512-2lNOsh6+R2Idnf1TCZqSwYlKN2E/iDlD8sgU59kYVl+OMDmvldO1VDk39smRfpUNwYpNRVn3w4YfuC7KfbBnkQ==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.6.tgz",
"integrity": "sha512-JFKxMx6udhwKh/Ldo270e17QX710vgunMkuPAvXjHSvC6oqLWAHhVhjg/I71q0u0CBSErIODV1Kjv0FQNSWjdg==",
"dev": true,
"license": "MIT",
"funding": {
@ -2349,13 +2349,13 @@
}
},
"node_modules/@vitest/utils": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.5.tgz",
"integrity": "sha512-76wdkrmfXfqGjueGgnb45ITPyUi1ycZ4IHgC2bhPDUfWHklY/q3MdLOAB+TF1e6xfl8NxNY0ZYaPCFNWSsw3Ug==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.6.tgz",
"integrity": "sha512-FxIY+U81R3LGKCxaHHFRQ5+g6/iRgGLmeHWdp2Amj4ljQRrEIWHmZyDfDYBRZlpyqA7qKxtS9DD1dhk8RnRIVQ==",
"dev": true,
"license": "MIT",
"dependencies": {
"@vitest/pretty-format": "4.1.5",
"@vitest/pretty-format": "4.1.6",
"convert-source-map": "^2.0.0",
"tinyrainbow": "^3.1.0"
},
@ -4239,9 +4239,9 @@
"license": "MIT"
},
"node_modules/nanoid": {
"version": "3.3.11",
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
"integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
"version": "3.3.12",
"resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
"integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
"dev": true,
"funding": [
{
@ -4586,9 +4586,9 @@
"license": "MIT"
},
"node_modules/postcss": {
"version": "8.5.10",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
"integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
"version": "8.5.14",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
"integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
"dev": true,
"funding": [
{
@ -4631,22 +4631,22 @@
"license": "MIT"
},
"node_modules/protobufjs": {
"version": "7.5.5",
"resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.5.tgz",
"integrity": "sha512-3wY1AxV+VBNW8Yypfd1yQY9pXnqTAN+KwQxL8iYm3/BjKYMNg4i0owhEe26PWDOMaIrzeeF98Lqd5NGz4omiIg==",
"version": "7.5.8",
"resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.8.tgz",
"integrity": "sha512-dvpCIeLPbXZS/Ete7yLaO7RenOdken2NHKykBXbsaGxZT0UTltcarBciw+A78SRQs9iMAAVpsYA+l8b1hTePIA==",
"hasInstallScript": true,
"license": "BSD-3-Clause",
"dependencies": {
"@protobufjs/aspromise": "^1.1.2",
"@protobufjs/base64": "^1.1.2",
"@protobufjs/codegen": "^2.0.4",
"@protobufjs/codegen": "^2.0.5",
"@protobufjs/eventemitter": "^1.1.0",
"@protobufjs/fetch": "^1.1.0",
"@protobufjs/float": "^1.0.2",
"@protobufjs/inquire": "^1.1.0",
"@protobufjs/inquire": "^1.1.1",
"@protobufjs/path": "^1.1.2",
"@protobufjs/pool": "^1.1.0",
"@protobufjs/utf8": "^1.1.0",
"@protobufjs/utf8": "^1.1.1",
"@types/node": ">=13.7.0",
"long": "^5.0.0"
},
@ -4791,14 +4791,14 @@
}
},
"node_modules/rolldown": {
"version": "1.0.0-rc.16",
"resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.16.tgz",
"integrity": "sha512-rzi5WqKzEZw3SooTt7cgm4eqIoujPIyGcJNGFL7iPEuajQw7vxMHUkXylu4/vhCkJGXsgRmxqMKXUpT6FEgl0g==",
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.1.tgz",
"integrity": "sha512-X0KQHljNnEkWNqqiz9zJrGunh1B0HgOxLXvnFpCOcadzcy5qohZ3tqMEUg00vncoRovXuK3ZqCT9KnnKzoInFQ==",
"dev": true,
"license": "MIT",
"dependencies": {
"@oxc-project/types": "=0.126.0",
"@rolldown/pluginutils": "1.0.0-rc.16"
"@oxc-project/types": "=0.130.0",
"@rolldown/pluginutils": "^1.0.0"
},
"bin": {
"rolldown": "bin/cli.mjs"
@ -4807,21 +4807,21 @@
"node": "^20.19.0 || >=22.12.0"
},
"optionalDependencies": {
"@rolldown/binding-android-arm64": "1.0.0-rc.16",
"@rolldown/binding-darwin-arm64": "1.0.0-rc.16",
"@rolldown/binding-darwin-x64": "1.0.0-rc.16",
"@rolldown/binding-freebsd-x64": "1.0.0-rc.16",
"@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.16",
"@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.16",
"@rolldown/binding-linux-arm64-musl": "1.0.0-rc.16",
"@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.16",
"@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.16",
"@rolldown/binding-linux-x64-gnu": "1.0.0-rc.16",
"@rolldown/binding-linux-x64-musl": "1.0.0-rc.16",
"@rolldown/binding-openharmony-arm64": "1.0.0-rc.16",
"@rolldown/binding-wasm32-wasi": "1.0.0-rc.16",
"@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.16",
"@rolldown/binding-win32-x64-msvc": "1.0.0-rc.16"
"@rolldown/binding-android-arm64": "1.0.1",
"@rolldown/binding-darwin-arm64": "1.0.1",
"@rolldown/binding-darwin-x64": "1.0.1",
"@rolldown/binding-freebsd-x64": "1.0.1",
"@rolldown/binding-linux-arm-gnueabihf": "1.0.1",
"@rolldown/binding-linux-arm64-gnu": "1.0.1",
"@rolldown/binding-linux-arm64-musl": "1.0.1",
"@rolldown/binding-linux-ppc64-gnu": "1.0.1",
"@rolldown/binding-linux-s390x-gnu": "1.0.1",
"@rolldown/binding-linux-x64-gnu": "1.0.1",
"@rolldown/binding-linux-x64-musl": "1.0.1",
"@rolldown/binding-openharmony-arm64": "1.0.1",
"@rolldown/binding-wasm32-wasi": "1.0.1",
"@rolldown/binding-win32-arm64-msvc": "1.0.1",
"@rolldown/binding-win32-x64-msvc": "1.0.1"
}
},
"node_modules/router": {
@ -5700,16 +5700,16 @@
}
},
"node_modules/vite": {
"version": "8.0.9",
"resolved": "https://registry.npmjs.org/vite/-/vite-8.0.9.tgz",
"integrity": "sha512-t7g7GVRpMXjNpa67HaVWI/8BWtdVIQPCL2WoozXXA7LBGEFK4AkkKkHx2hAQf5x1GZSlcmEDPkVLSGahxnEEZw==",
"version": "8.0.13",
"resolved": "https://registry.npmjs.org/vite/-/vite-8.0.13.tgz",
"integrity": "sha512-MFtjBYgzmSxmgA4RAfjIyXWpGe1oALnjgUTzzV7QLx/TKxCzjtMH6Fd9/eVK+5Fg1qNoz5VAwsmMs/NofrmJvw==",
"dev": true,
"license": "MIT",
"dependencies": {
"lightningcss": "^1.32.0",
"picomatch": "^4.0.4",
"postcss": "^8.5.10",
"rolldown": "1.0.0-rc.16",
"postcss": "^8.5.14",
"rolldown": "1.0.1",
"tinyglobby": "^0.2.16"
},
"bin": {
@ -5726,7 +5726,7 @@
},
"peerDependencies": {
"@types/node": "^20.19.0 || >=22.12.0",
"@vitejs/devtools": "^0.1.0",
"@vitejs/devtools": "^0.1.18",
"esbuild": "^0.27.0 || ^0.28.0",
"jiti": ">=1.21.0",
"less": "^4.0.0",
@ -5778,19 +5778,19 @@
}
},
"node_modules/vitest": {
"version": "4.1.5",
"resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.5.tgz",
"integrity": "sha512-9Xx1v3/ih3m9hN+SbfkUyy0JAs72ap3r7joc87XL6jwF0jGg6mFBvQ1SrwaX+h8BlkX6Hz9shdd1uo6AF+ZGpg==",
"version": "4.1.6",
"resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.6.tgz",
"integrity": "sha512-6lvjbS3p9b4CrdCmguzbh2/4uoXhGE2q71R4OX5sqF9R1bo9Xd6fGrMAfvp5wnCzlBnFVdCOp6onuTQVbo8iUQ==",
"dev": true,
"license": "MIT",
"dependencies": {
"@vitest/expect": "4.1.5",
"@vitest/mocker": "4.1.5",
"@vitest/pretty-format": "4.1.5",
"@vitest/runner": "4.1.5",
"@vitest/snapshot": "4.1.5",
"@vitest/spy": "4.1.5",
"@vitest/utils": "4.1.5",
"@vitest/expect": "4.1.6",
"@vitest/mocker": "4.1.6",
"@vitest/pretty-format": "4.1.6",
"@vitest/runner": "4.1.6",
"@vitest/snapshot": "4.1.6",
"@vitest/spy": "4.1.6",
"@vitest/utils": "4.1.6",
"es-module-lexer": "^2.0.0",
"expect-type": "^1.3.0",
"magic-string": "^0.30.21",
@ -5818,12 +5818,12 @@
"@edge-runtime/vm": "*",
"@opentelemetry/api": "^1.9.0",
"@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
"@vitest/browser-playwright": "4.1.5",
"@vitest/browser-preview": "4.1.5",
"@vitest/browser-webdriverio": "4.1.5",
"@vitest/coverage-istanbul": "4.1.5",
"@vitest/coverage-v8": "4.1.5",
"@vitest/ui": "4.1.5",
"@vitest/browser-playwright": "4.1.6",
"@vitest/browser-preview": "4.1.6",
"@vitest/browser-webdriverio": "4.1.6",
"@vitest/coverage-istanbul": "4.1.6",
"@vitest/coverage-v8": "4.1.6",
"@vitest/ui": "4.1.6",
"happy-dom": "*",
"jsdom": "*",
"vite": "^6.0.0 || ^7.0.0 || ^8.0.0"

2
gitnexus/package.json
View file

@ -1,6 +1,6 @@
{
"name": "gitnexus",
"version": "1.6.4",
"version": "1.6.5",
"description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
"author": "Abhigyan Patwari",
"license": "PolyForm-Noncommercial-1.0.0",

8
gitnexus/scripts/build.js
View file

@ -21,11 +21,15 @@ const SHARED_DEST = path.join(DIST, '_shared');
// ── 1. Build gitnexus-shared ───────────────────────────────────────
console.log('[build] compiling gitnexus-shared…');
execSync('npx tsc', { cwd: SHARED_ROOT, stdio: 'inherit', timeout: 120_000 });
const tscCmd =
process.platform === 'win32'
? path.join('node_modules', '.bin', 'tsc.cmd')
: path.join('node_modules', '.bin', 'tsc');
execSync(tscCmd, { cwd: SHARED_ROOT, stdio: 'inherit', timeout: 120_000 });
// ── 2. Build gitnexus ──────────────────────────────────────────────
console.log('[build] compiling gitnexus…');
execSync('npx tsc', { cwd: ROOT, stdio: 'inherit', timeout: 120_000 });
execSync(tscCmd, { cwd: ROOT, stdio: 'inherit', timeout: 120_000 });
// ── 3. Copy shared dist ────────────────────────────────────────────
console.log('[build] copying shared module into dist/_shared…');

96
gitnexus/src/cli/ai-context.ts
View file

@ -28,6 +28,7 @@ interface RepoStats {
export interface AIContextOptions {
skipAgentsMd?: boolean;
noStats?: boolean;
skipSkills?: boolean;
}
const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
@ -94,6 +95,7 @@ function generateGitNexusContent(
generatedSkills?: GeneratedSkillInfo[],
groupNames?: string[],
noStats?: boolean,
skipSkills?: boolean,
): string {
const generatedRows =
generatedSkills && generatedSkills.length > 0
@ -105,14 +107,26 @@ function generateGitNexusContent(
.join('\n')
: '';
const skillsTable = `| Task | Read this skill file |
|------|---------------------|
| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
// Standard skill rows reference files installed by installSkills(). When
// --skip-skills suppresses that install, these rows must be omitted — else
// AGENTS.md/CLAUDE.md would direct agents to read files that don't exist.
// Community skills (generatedRows) live in .claude/skills/generated/ and
// are independent of --skip-skills, so they remain when present.
const standardSkillsRows = skipSkills
? ''
: `| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
| Rename / extract / split / refactor | \`.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
| Tools, resources, schema reference | \`.claude/skills/gitnexus/gitnexus-guide/SKILL.md\` |
| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |${generatedRows ? '\n' + generatedRows : ''}`;
| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |`;
const tableBody = [standardSkillsRows, generatedRows].filter(Boolean).join('\n');
const skillsTable = tableBody
? `| Task | Read this skill file |
|------|---------------------|
${tableBody}`
: '';
return `${GITNEXUS_START_MARKER}
# GitNexus — Code Intelligence
@ -153,11 +167,15 @@ This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}**
`
: ''
}## CLI
}${
skillsTable
? `## CLI
${skillsTable}
${GITNEXUS_END_MARKER}`;
`
: ''
}${GITNEXUS_END_MARKER}`;
}
/**
@ -181,7 +199,9 @@ async function fileExists(filePath: string): Promise<boolean> {
async function upsertGitNexusSection(
filePath: string,
content: string,
): Promise<'created' | 'updated' | 'appended'> {
projectName: string,
stats: RepoStats,
): Promise<'created' | 'updated' | 'appended' | 'preserved'> {
const exists = await fileExists(filePath);
if (!exists) {
@ -205,7 +225,50 @@ async function upsertGitNexusSection(
);
if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
// Replace existing section
const existingSection = existingContent.substring(
startIdx,
endIdx + GITNEXUS_END_MARKER.length,
);
// If the existing section contains <!-- gitnexus:keep -->, preserve the user's
// custom layout and only update the stats line (node/edge/flow counts).
// This lets teams trim the verbose default template to a lean format without
// having it overwritten on every `gitnexus analyze`.
//
// Note: the keep-marker check operates on `existingSection` (the substring
// between valid section markers identified by findSectionMarkerIndex), so
// a keep marker in user prose OUTSIDE the GitNexus block has no effect.
if (existingSection.includes('<!-- gitnexus:keep -->')) {
// Build the new stats line from the caller-provided values directly.
// We do NOT re-extract from `content` because:
// (a) first-bold extraction is fragile if the template evolves
// (b) the parenthesized-text fallback can match unrelated tuples
// like `({target: "symbolName", direction: "upstream"})`
// when noStats is set
// Passing projectName + stats explicitly makes the contract obvious.
// noStats controls template generation, not keep-section stat updates — the user opted into a stats line by keeping it.
const newStatsInner = `${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows`;
const statsLine = `Indexed as **${projectName}** (${newStatsInner})`;
// Match either canonical phrasing at line start (`^` with `m` flag) so we
// cannot replace prose embedded mid-paragraph. Deliberately no `$`: text
// after the closing `)` on the same line (e.g. ". MCP tools.") stays intact.
const statsPattern = /^(?:Indexed as|indexed by GitNexus as) \*\*[^*]+\*\* \([^)]+\)/m;
if (statsPattern.test(existingSection)) {
const updatedSection = existingSection.replace(statsPattern, statsLine);
const before = existingContent.substring(0, startIdx);
const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length);
await fs.writeFile(filePath, (before + updatedSection + after).trim() + '\n', 'utf-8');
return 'updated';
}
// Keep marker present but no stats line matched. Section is preserved
// unchanged on disk; return a distinct status so callers/CLI output
// don't mis-report this as 'updated' (which would imply a write).
return 'preserved';
}
// No keep marker — replace existing section with full verbose content
const before = existingContent.substring(0, startIdx);
const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length);
const newContent = before + content + after;
@ -319,28 +382,33 @@ export async function generateAIContextFiles(
generatedSkills,
groupNames,
options?.noStats,
options?.skipSkills,
);
const createdFiles: string[] = [];
if (!options?.skipAgentsMd) {
// Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
const agentsPath = path.join(repoPath, 'AGENTS.md');
const agentsResult = await upsertGitNexusSection(agentsPath, content);
const agentsResult = await upsertGitNexusSection(agentsPath, content, projectName, stats);
createdFiles.push(`AGENTS.md (${agentsResult})`);
// Create CLAUDE.md (for Claude Code)
const claudePath = path.join(repoPath, 'CLAUDE.md');
const claudeResult = await upsertGitNexusSection(claudePath, content);
const claudeResult = await upsertGitNexusSection(claudePath, content, projectName, stats);
createdFiles.push(`CLAUDE.md (${claudeResult})`);
} else {
createdFiles.push('AGENTS.md (skipped via --skip-agents-md)');
createdFiles.push('CLAUDE.md (skipped via --skip-agents-md)');
}
// Install skills to .claude/skills/gitnexus/
const installedSkills = await installSkills(repoPath);
if (installedSkills.length > 0) {
createdFiles.push(`.claude/skills/gitnexus/ (${installedSkills.length} skills)`);
// Install skills to .claude/skills/gitnexus/ (unless --skip-skills)
if (!options?.skipSkills) {
const installedSkills = await installSkills(repoPath);
if (installedSkills.length > 0) {
createdFiles.push(`.claude/skills/gitnexus/ (${installedSkills.length} skills)`);
}
} else {
createdFiles.push('.claude/skills/gitnexus/ (skipped via --skip-skills)');
}
return { files: createdFiles };

75
gitnexus/src/cli/analyze.ts
View file

@ -117,8 +117,22 @@ export interface AnalyzeOptions {
verbose?: boolean;
/** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
skipAgentsMd?: boolean;
/** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
noStats?: boolean;
/**
* Stats inclusion in AGENTS.md and CLAUDE.md.
*
* Commander.js represents `--no-stats` as `stats: boolean` (default
* `true`; `false` when the user passes `--no-stats`), NOT as
* `noStats: boolean`. Reading the negated form would always be
* `undefined` and the flag would silently no-op (#1477). Consumers
* that want "did the user request --no-stats?" should compare with
* `=== false` to distinguish the explicit-off case from the
* default-on case.
*/
stats?: boolean;
/** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
skipSkills?: boolean;
/** Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills). */
indexOnly?: boolean;
/** Index the folder even when no .git directory is present. */
skipGit?: boolean;
/**
@ -150,6 +164,24 @@ export interface AnalyzeOptions {
embeddingDevice?: string;
}
/**
* Whether the post-index skill step should run.
*
* The gated block does two things in sequence: (1) generates the community
* skill files from `--skills`, and (2) re-runs `generateAIContextFiles` so
* AGENTS.md/CLAUDE.md can reference the freshly written skills. Both are
* suppressed together — `--index-only` drops the entire step, not just the
* community-skill write. Name retained for the test contract; see call site
* in `analyzeCommand` for the AGENTS.md/CLAUDE.md re-generation it also gates.
*
* Kept as a pure helper so the `--index-only --skills` contract is unit-tested
* without booting the full analyze pipeline (#742 review).
*/
export const shouldGenerateCommunitySkillFiles = (
options: Pick<AnalyzeOptions, 'skills' | 'indexOnly'> | undefined,
pipelineResult: unknown,
): boolean => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOptions) => {
if (ensureHeap()) return;
@ -245,6 +277,18 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
console.log('\n GitNexus Analyzer\n');
// `--index-only` is the stronger contract — it suppresses every form of file
// injection, including community skill writes that `--skills` would normally
// produce. Surface the override explicitly so users don't wonder why a
// pipeline re-index ran but no skill files appeared. The pipeline still
// re-runs (see `force: options?.force || options?.skills` below); the warning
// is purely about the dropped post-index write step.
if (options?.indexOnly && options?.skills) {
console.log(
' Note: --index-only overrides --skills; community skill files will not be written.\n',
);
}
let repoPath: string;
if (inputPath) {
repoPath = path.resolve(inputPath);
@ -399,6 +443,9 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
// ── Run shared analysis orchestrator ───────────────────────────────
try {
const skipAll = options?.indexOnly;
const skipAgentsMd = skipAll || options?.skipAgentsMd;
const skipSkills = skipAll || options?.skipSkills;
const result = await runFullAnalysis(
repoPath,
{
@ -410,8 +457,14 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
embeddingsNodeLimit,
dropEmbeddings: options?.dropEmbeddings,
skipGit: options?.skipGit,
skipAgentsMd: options?.skipAgentsMd,
noStats: options?.noStats,
skipAgentsMd,
skipSkills,
// commander.js `.option('--no-stats', …)` registers the flag as
// `options.stats` (boolean, default true; `false` when the user
// passed --no-stats). Reading `options?.noStats` here returns
// undefined every time, so the flag was a no-op on the markdown
// rewrite path before this fix. See #1477.
noStats: options?.stats === false,
registryName: options?.name,
// Registry-collision bypass — its own CLI flag, intentionally NOT
// overloading --force. A user who hits the collision guard should
@ -456,8 +509,10 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
// a healthy index.
await assertAnalysisFinalized(repoPath);
// Skill generation (CLI-only, uses pipeline result from analysis)
if (options?.skills && result.pipelineResult) {
// Skill generation (CLI-only, uses pipeline result from analysis).
// Gated so `--index-only --skills` skips community skill writes too
// (`shouldGenerateCommunitySkillFiles` — see unit test).
if (shouldGenerateCommunitySkillFiles(options, result.pipelineResult)) {
updateBar(99, 'Generating skill files...');
try {
const { generateSkillFiles } = await import('./skill-gen.js');
@ -497,7 +552,13 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
processes: s.processes,
},
skillResult.skills,
{ skipAgentsMd: options?.skipAgentsMd, noStats: options?.noStats },
{
skipAgentsMd,
skipSkills,
// Mirror runFullAnalysis `noStats` bridge (#1477) — same expression;
// exercised on the `--skills` path by analyze-no-stats-bridge.test.ts.
noStats: options?.stats === false,
},
);
}
} catch {

15
gitnexus/src/cli/index.ts
View file

@ -33,9 +33,20 @@ program
'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +
'preserves any embeddings already present in the index.',
)
.option('--skills', 'Generate repo-specific skill files from detected communities')
.option(
'--skills',
'Generate repo-specific skill files from detected communities ' +
'(no-op when --index-only is also set).',
)
.option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
.option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
.option(
'--skip-skills',
'Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. ' +
'Does not suppress community skills from --skills (those use .claude/skills/generated/). ' +
'Use --index-only to skip all AI-context file injection.',
)
.option('--index-only', 'Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills)')
.option(
'--skip-git',
'Treat the provided path/cwd as the index root and skip parent git-root discovery',
@ -150,6 +161,8 @@ program
)
.option('--no-reasoning-model', 'Disable reasoning model mode (overrides saved config)')
.option('--concurrency <n>', 'Parallel LLM calls (default: 3)', '3')
.option('--timeout <seconds>', 'Per-attempt LLM request timeout in seconds (default: 60)')
.option('--retries <n>', 'Max LLM retry attempts per request (default: 3)')
.option('--gist', 'Publish wiki as a public GitHub Gist after generation')
.option('-v, --verbose', 'Enable verbose output (show LLM commands and responses)')
.option('--review', 'Stop after grouping to review module structure before generating pages')

27
gitnexus/src/cli/setup.ts
View file

@ -364,6 +364,33 @@ async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
// Script not found in source — skip
}
try {
await fs.copyFile(
path.join(pluginHooksPath, 'hook-lock.cjs'),
path.join(destHooksDir, 'hook-lock.cjs'),
);
} catch {
// Helper not found in source — skip
}
try {
await fs.copyFile(
path.join(pluginHooksPath, 'hook-db-lock-probe.cjs'),
path.join(destHooksDir, 'hook-db-lock-probe.cjs'),
);
} catch {
// Helper not found in source — skip
}
try {
await fs.copyFile(
path.join(pluginHooksPath, 'win-rm-list-json.ps1'),
path.join(destHooksDir, 'win-rm-list-json.ps1'),
);
} catch {
// Helper not found in source — skip
}
const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
// Escape backslashes FIRST, then quotes (CodeQL js/incomplete-sanitization).
// The previous shape `replace(/"/g, '\\"')` alone would let `path\with"quote`

12
gitnexus/src/cli/wiki.ts
View file

@ -33,6 +33,8 @@ export interface WikiCommandOptions {
provider?: LLMProvider;
verbose?: boolean;
review?: boolean;
timeout?: string;
retries?: string;
}
/**
@ -347,6 +349,16 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
}
}
// ── Apply per-run overrides not saved to config ────────────────────
if (options?.timeout) {
const secs = parseInt(options.timeout, 10);
if (!isNaN(secs) && secs > 0) llmConfig.requestTimeoutMs = secs * 1000;
}
if (options?.retries) {
const n = parseInt(options.retries, 10);
if (!isNaN(n) && n > 0) llmConfig.maxAttempts = n;
}
// ── Setup progress bar with elapsed timer ──────────────────────────
const bar = new cliProgress.SingleBar(
{

32
gitnexus/src/core/augmentation/engine.ts
View file

@ -86,6 +86,9 @@ async function findRepoForCwd(cwd: string): Promise<{
export async function augment(pattern: string, cwd?: string): Promise<string> {
if (!pattern || pattern.length < 3) return '';
const patternFirstWord = pattern.trim().replace(/'/g, "''").split(/\s+/)[0];
if (!patternFirstWord || patternFirstWord.length < 2) return '';
const workDir = cwd || process.cwd();
try {
@ -104,9 +107,7 @@ export async function augment(pattern: string, cwd?: string): Promise<string> {
}
// Step 1: BM25 search (fast, no embeddings)
const { results: bm25Results } = await searchFTSFromLbug(pattern, 10, repoId);
if (bm25Results.length === 0) return '';
const { results: bm25Results, ftsAvailable } = await searchFTSFromLbug(pattern, 10, repoId);
// Step 2: Map BM25 file results to symbols
const symbolMatches: Array<{
@ -124,7 +125,7 @@ export async function augment(pattern: string, cwd?: string): Promise<string> {
repoId,
`
MATCH (n) WHERE n.filePath = '${escaped}'
AND n.name CONTAINS '${pattern.replace(/'/g, "''").split(/\s+/)[0]}'
AND n.name CONTAINS '${patternFirstWord}'
RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
LIMIT 3
`,
@ -143,6 +144,29 @@ export async function augment(pattern: string, cwd?: string): Promise<string> {
}
}
// When FTS indexes are unavailable (read-only DB, first run before indexes are built),
// fall back to a direct name CONTAINS query so enrichment still works.
if (symbolMatches.length === 0 && !ftsAvailable) {
const fallbackRows = await executeQuery(
repoId,
`
MATCH (n)
WHERE n.name CONTAINS '${patternFirstWord}'
RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
LIMIT 5
`,
).catch(() => []);
for (const sym of fallbackRows) {
symbolMatches.push({
nodeId: sym.id || sym[0],
name: sym.name || sym[1],
type: sym.type || sym[2],
filePath: sym.filePath || sym[3],
score: 1.0,
});
}
}
if (symbolMatches.length === 0) return '';
// Step 3: Batch-fetch callers/callees/processes/cohesion for top matches

42
gitnexus/src/core/embeddings/http-client.ts
View file

@ -40,8 +40,11 @@ const readConfig = (): HttpConfig | null => {
const rawDims = process.env.GITNEXUS_EMBEDDING_DIMS;
let dimensions: number | undefined;
if (rawDims !== undefined) {
if (!/^\d+$/.test(rawDims)) {
throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
}
const parsed = parseInt(rawDims, 10);
if (Number.isNaN(parsed) || parsed <= 0) {
if (parsed <= 0) {
throw new Error(`GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"`);
}
dimensions = parsed;
@ -91,7 +94,13 @@ interface EmbeddingItem {
* @param model - Model name for the request body
* @param apiKey - Bearer token (only used in Authorization header)
* @param batchIndex - Logical batch number (for error context)
* @param attempt - Current retry attempt (internal)
* @param dimensions - Optional output-vector size. When provided, sent as
* the `dimensions` field in the request body. Endpoints that implement
* Matryoshka truncation (OpenAI text-embedding-3-*, Cohere embed-v3,
* Voyage) return a truncated vector at that size; endpoints that do not
* recognise the field may ignore it or return 400. Leave
* `GITNEXUS_EMBEDDING_DIMS` unset for strict backends that reject
* unknown fields.
*/
const httpEmbedBatch = async (
url: string,
@ -99,7 +108,16 @@ const httpEmbedBatch = async (
model: string,
apiKey: string,
batchIndex = 0,
dimensions?: number,
): Promise<EmbeddingItem[]> => {
const requestBody: { input: string[]; model: string; dimensions?: number } = {
input: batch,
model,
};
if (dimensions !== undefined) {
requestBody.dimensions = dimensions;
}
let resp: Response;
try {
resp = await resilientFetch(
@ -111,7 +129,7 @@ const httpEmbedBatch = async (
'Content-Type': 'application/json',
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify({ input: batch, model }),
body: JSON.stringify(requestBody),
},
{
breakerKey: HTTP_BREAKER_KEY,
@ -169,7 +187,14 @@ export const httpEmbed = async (texts: string[]): Promise<Float32Array[]> => {
for (let i = 0; i < texts.length; i += HTTP_BATCH_SIZE) {
const batch = texts.slice(i, i + HTTP_BATCH_SIZE);
const batchIndex = Math.floor(i / HTTP_BATCH_SIZE);
const items = await httpEmbedBatch(url, batch, config.model, config.apiKey, batchIndex);
const items = await httpEmbedBatch(
url,
batch,
config.model,
config.apiKey,
batchIndex,
config.dimensions,
);
if (items.length !== batch.length) {
throw new Error(
@ -212,7 +237,14 @@ export const httpEmbedQuery = async (text: string): Promise<number[]> => {
if (!config) throw new Error('HTTP embedding not configured');
const url = `${config.baseUrl}/embeddings`;
const items = await httpEmbedBatch(url, [text], config.model, config.apiKey);
const items = await httpEmbedBatch(
url,
[text],
config.model,
config.apiKey,
0,
config.dimensions,
);
if (!items.length) {
throw new Error(`Embedding endpoint returned empty response (${safeUrl(url)})`);
}

191
gitnexus/src/core/group/extractors/http-patterns/python.ts
View file

@ -1,3 +1,4 @@
import type Parser from 'tree-sitter';
import Python from 'tree-sitter-python';
import {
compilePatterns,
@ -12,6 +13,7 @@ import type { HttpDetection, HttpLanguagePlugin } from './types.js';
* - FastAPI `@app.get("/path")` provider decorators
* - `requests.get/post/...("url")` consumer calls
* - Generic `requests.request("METHOD", "url")` consumer calls
* - `httpx.AsyncClient` instances calling `.get/.post/...("url")`
*/
const FASTAPI_VERBS: Record<string, string> = {
@ -77,11 +79,161 @@ const REQUESTS_GENERIC_PATTERNS = compilePatterns({
],
} satisfies LanguagePatterns<Record<string, never>>);
// ─── Consumer: httpx.AsyncClient assignments ────────────────────────
// NOTE: This targeted detector only tracks explicit `httpx.AsyncClient(...)`
// construction. Direct imports (`from httpx import AsyncClient`) and module
// aliases (`import httpx as hx`) and annotated assignments (`client: httpx.AsyncClient = ...`)
// are intentionally left for a follow-up. Module-scope clients are only matched
// at module scope; calls inside functions require a function/class-local tracked
// client to avoid false positives from same-name local variables.
const HTTPX_ASYNC_CLIENT_ASSIGN_PATTERNS = compilePatterns({
name: 'python-httpx-async-client-assign',
language: Python,
patterns: [
{
meta: {},
query: `
(assignment
left: (_) @client
right: (call
function: (attribute
object: (identifier) @module (#eq? @module "httpx")
attribute: (identifier) @client_class (#eq? @client_class "AsyncClient"))))
`,
},
],
} satisfies LanguagePatterns<Record<string, never>>);
// ─── Consumer: async with httpx.AsyncClient() as client ──────────────
const HTTPX_ASYNC_CLIENT_WITH_ALIAS_PATTERNS = compilePatterns({
name: 'python-httpx-async-client-with-alias',
language: Python,
patterns: [
{
meta: {},
query: `
(as_pattern
(call
function: (attribute
object: (identifier) @module (#eq? @module "httpx")
attribute: (identifier) @client_class (#eq? @client_class "AsyncClient")))
(as_pattern_target (identifier) @client))
`,
},
],
} satisfies LanguagePatterns<Record<string, never>>);
function getScopeKey(node: Parser.SyntaxNode | null, preferClass = false): string {
if (preferClass) {
let current: Parser.SyntaxNode | null = node;
while (current) {
if (current.type === 'class_definition') {
return `class:${current.startIndex}:${current.endIndex}`;
}
current = current.parent;
}
}
let current: Parser.SyntaxNode | null = node;
while (current) {
if (current.type === 'function_definition') {
return `function:${current.startIndex}:${current.endIndex}`;
}
current = current.parent;
}
return 'module';
}
function trackedClientScopeKey(clientNode: Parser.SyntaxNode): string {
return getScopeKey(clientNode.parent, clientNode.text.includes('.'));
}
function callScopeKeys(clientNode: Parser.SyntaxNode): string[] {
const keys = new Set<string>();
const preferClass = clientNode.text.includes('.');
const nearestScope = getScopeKey(clientNode.parent, preferClass);
keys.add(nearestScope);
return [...keys];
}
function collectHttpxAsyncClients(tree: Parser.Tree): Map<string, Set<string>> {
const clients = new Map<string, Set<string>>();
const addClient = (clientNode: Parser.SyntaxNode | undefined) => {
if (!clientNode) return;
const scopeKey = trackedClientScopeKey(clientNode);
const clientText = clientNode.text;
const scopes = clients.get(clientText) ?? new Set<string>();
scopes.add(scopeKey);
clients.set(clientText, scopes);
};
for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_ASSIGN_PATTERNS, tree)) {
addClient(match.captures.client);
}
for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_WITH_ALIAS_PATTERNS, tree)) {
addClient(match.captures.client);
}
return clients;
}
function hasTrackedHttpxAsyncClient(
clients: Map<string, Set<string>>,
clientNode: Parser.SyntaxNode,
): boolean {
const scopes = clients.get(clientNode.text);
if (!scopes) return false;
return callScopeKeys(clientNode).some((scopeKey) => scopes.has(scopeKey));
}
// ─── Consumer: httpx AsyncClient .get/.post/...("url") ──────────────
const HTTPX_ASYNC_CLIENT_VERB_PATTERNS = compilePatterns({
name: 'python-httpx-async-client-verb',
language: Python,
patterns: [
{
meta: {},
query: `
(call
function: (attribute
object: (_) @client
attribute: (identifier) @method (#match? @method "^(get|post|put|delete|patch)$"))
arguments: (argument_list . (string) @path))
`,
},
],
} satisfies LanguagePatterns<Record<string, never>>);
// ─── Consumer: httpx AsyncClient .request("METHOD", "url") ─────────
const HTTPX_ASYNC_CLIENT_GENERIC_PATTERNS = compilePatterns({
name: 'python-httpx-async-client-generic',
language: Python,
patterns: [
{
meta: {},
query: `
(call
function: (attribute
object: (_) @client
attribute: (identifier) @method (#eq? @method "request"))
arguments: (argument_list . (string) @http_method (string) @path))
`,
},
],
} satisfies LanguagePatterns<Record<string, never>>);
export const PYTHON_HTTP_PLUGIN: HttpLanguagePlugin = {
name: 'python-http',
language: Python,
scan(tree) {
const out: HttpDetection[] = [];
const httpxAsyncClients = collectHttpxAsyncClients(tree);
// Providers: FastAPI
for (const match of runCompiledPatterns(FASTAPI_PATTERNS, tree)) {
@ -137,6 +289,45 @@ export const PYTHON_HTTP_PLUGIN: HttpLanguagePlugin = {
});
}
// Consumers: httpx.AsyncClient.<verb>("url")
for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_VERB_PATTERNS, tree)) {
const clientNode = match.captures.client;
const methodNode = match.captures.method;
const pathNode = match.captures.path;
if (!clientNode || !methodNode || !pathNode) continue;
if (!hasTrackedHttpxAsyncClient(httpxAsyncClients, clientNode)) continue;
const path = unquoteLiteral(pathNode.text);
if (path === null) continue;
out.push({
role: 'consumer',
framework: 'python-httpx',
method: methodNode.text.toUpperCase(),
path,
name: null,
confidence: 0.7,
});
}
// Consumers: httpx.AsyncClient.request("METHOD", "url")
for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_GENERIC_PATTERNS, tree)) {
const clientNode = match.captures.client;
const methodNode = match.captures.http_method;
const pathNode = match.captures.path;
if (!clientNode || !methodNode || !pathNode) continue;
if (!hasTrackedHttpxAsyncClient(httpxAsyncClients, clientNode)) continue;
const methodRaw = unquoteLiteral(methodNode.text);
const path = unquoteLiteral(pathNode.text);
if (methodRaw === null || path === null) continue;
out.push({
role: 'consumer',
framework: 'python-httpx',
method: methodRaw.toUpperCase(),
path,
name: null,
confidence: 0.7,
});
}
return out;
},
};

76
gitnexus/src/core/incremental/shadow-candidates.ts Normal file
View file

@ -0,0 +1,76 @@
/**
* Shadow-candidate path derivation for incremental indexing.
*
* Background — Bugbot review on PR #1479:
* queryImporters() on a NEWLY ADDED file returns 0 importers in the
* pre-pipeline DB, because the new file's IMPORTS rows haven't been
* written yet. But pre-existing files may have IMPORTS edges that
* *resolved to a sibling path*, and the newcomer can now steal that
* resolution under standard JS/TS module-resolution rules. Without
* pulling those pre-existing files into the writable set, their
* stale CALLS edges remain pointing at the OLD resolution target.
*
* Given an added file path, this helper enumerates the pre-existing
* file paths whose import-resolution claim the newcomer can steal.
* Caller filters the candidates against the prior-run `fileHashes`
* map so we only query importers of paths that actually existed.
*
* Shadow patterns covered (resolution-priority-aware):
*
* (a) Same basename, different extension —
* added `foo/bar.ts` shadows `foo/bar.{tsx,js,jsx,mjs,cjs,d.ts}`.
* (b) Bare-file beats directory-style index —
* added `foo/bar.ts` shadows `foo/bar/index.{ts,tsx,...}`.
* (c) Directory-index beats bare-file —
* added `foo/index.ts` shadows `foo.{ts,tsx,...}` (rare but real,
* e.g. converting a single-file module into a directory module).
*
* Resolution-order priority is conservatively wide: we enumerate ALL
* common extensions because we don't know which the importer actually
* specified, and over-seeding is harmless (extra BFS work, but the
* subgraph extract still gates write-back by file membership).
*
* Cross-platform path separators: candidates are emitted with both `/`
* and `\` for shadow pattern (b), since the caller's prior fileHashes
* map may use either depending on the OS that wrote it.
*/
const SHADOW_EXTS = ['.d.ts', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
/**
* Enumerate pre-existing paths whose import-resolution `added` can steal.
*
* @param added — repo-relative path of a newly-added file
* @returns deduplicated list of candidate paths (NOT filtered against
* any known-files set — caller does that)
*/
export const shadowCandidatesFor = (added: string): string[] => {
const ext = SHADOW_EXTS.find((e) => added.endsWith(e));
if (!ext) return [];
const noExt = added.slice(0, -ext.length);
const out = new Set<string>();
// (a) Same basename, different extension.
for (const alt of SHADOW_EXTS) {
if (alt !== ext) out.add(noExt + alt);
}
// (b) Bare file beats sibling directory-style index.
for (const idx of SHADOW_EXTS) {
out.add(`${noExt}/index${idx}`);
out.add(`${noExt}\\index${idx}`);
}
// (c) New `foo/index.ext` shadows old `foo.ext`.
const idxSuffixSlash = '/index';
const idxSuffixBack = '\\index';
let dir: string | null = null;
if (noExt.endsWith(idxSuffixSlash)) dir = noExt.slice(0, -idxSuffixSlash.length);
else if (noExt.endsWith(idxSuffixBack)) dir = noExt.slice(0, -idxSuffixBack.length);
if (dir !== null) {
for (const alt of SHADOW_EXTS) out.add(dir + alt);
}
return [...out];
};

123
gitnexus/src/core/incremental/subgraph-extract.ts Normal file
View file

@ -0,0 +1,123 @@
/**
* Subgraph extraction for incremental DB writeback.
*
* Given the FULL ctx.graph produced by the pipeline (all files parsed,
* all phases run) and the set of file paths whose DB rows must be
* replaced, produce a smaller KnowledgeGraph that contains:
*
* - Every node whose `properties.filePath` is in `toWriteSet`.
* - Every graph-wide node (Community, Process) — these are regenerated
* each run by the communities/processes phases and must be fully
* rewritten.
* - Every relationship where AT LEAST ONE endpoint is in the writable
* set above. Relationships entirely between unchanged-file nodes
* are skipped — their rows are still in the DB and re-inserting
* them would PK-conflict at COPY time.
*
* The resulting subgraph is what gets passed to `loadGraphToLbug` after
* the orchestrator has deleted the corresponding DB rows. Hydrated
* unchanged-file rows are never touched in the DB.
*
* # Cross-file edge consistency (Finding 1)
*
* `extractChangedSubgraph` intentionally does NOT expand the set it is
* given — expansion is the orchestrator's job, so the SAME expanded set
* can be fed to both `deleteNodesForFile` and this function (asymmetry
* between the delete set and the write set silently corrupts the DB).
* `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop
* walk; the orchestrator composes it with its importer-BFS expansion and
* passes the result here.
*
* Why the 1-hop walk is needed: consider a barrel re-export change —
* file C (a barrel) shifts `export { foo } from './b'` to
* `export { foo } from './d'`. After scope resolution, file A's CALLS
* edge to `foo` resolves to D instead of B, even though A's content is
* byte-for-byte identical:
*
* - Old A→B edge survives in DB (neither A nor B is changed → not deleted)
* - New A→D edge is missing (neither A nor D in writable set → skipped)
*
* Pulling the unchanged-side file of every writable-boundary-crossing
* edge into the write set fixes both halves: the orchestrator's
* `DETACH DELETE` cleans up the stale unchanged-side rows, and the new
* cross-file edges land because at least one endpoint is now writable.
*
* Limitation (documented): if a file X *stopped* importing from a
* changed file C, X has no edge to C in the new graph, so this 1-hop
* walk doesn't catch it. The orchestrator's importer-BFS (which reads
* IMPORTS from the pre-pipeline DB) covers that case instead.
*/
import type { GraphNode, GraphRelationship } from 'gitnexus-shared';
import { createKnowledgeGraph } from '../graph/graph.js';
import type { KnowledgeGraph } from '../graph/types.js';
const isGraphWide = (label: string): boolean => label === 'Community' || label === 'Process';
/**
* Build a Map<nodeId, filePath> for every File-bound node in the graph.
* Graph-wide nodes (Community/Process) have no filePath and are filtered.
*/
const indexNodeFilePaths = (fullGraph: KnowledgeGraph): Map<string, string> => {
const idx = new Map<string, string>();
fullGraph.forEachNode((n: GraphNode) => {
const fp = n.properties?.filePath as string | undefined;
if (fp) idx.set(n.id, fp);
});
return idx;
};
export const extractChangedSubgraph = (
fullGraph: KnowledgeGraph,
toWriteSet: ReadonlySet<string>,
): KnowledgeGraph => {
const sub = createKnowledgeGraph();
const writableNodeIds = new Set<string>();
fullGraph.forEachNode((n: GraphNode) => {
const filePath = n.properties?.filePath as string | undefined;
const include = (filePath && toWriteSet.has(filePath)) || isGraphWide(n.label);
if (include) {
sub.addNode(n);
writableNodeIds.add(n.id);
}
});
fullGraph.forEachRelationship((r: GraphRelationship) => {
if (writableNodeIds.has(r.sourceId) || writableNodeIds.has(r.targetId)) {
sub.addRelationship(r);
}
});
return sub;
};
/**
* Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
* hop along every edge in the new graph that crosses the writable
* boundary (one endpoint in a writable file, the other in an unchanged
* file). The unchanged-side file is pulled in so its stale rows are
* deleted + rewritten in lockstep with the changed side.
*
* Single pass over the edge list. Does NOT mutate `toWriteSet`. The
* orchestrator MUST feed the returned set to both `deleteNodesForFile`
* and `extractChangedSubgraph` — feeding the unexpanded set to either
* one leaves stale rows or PK-conflicts at COPY time.
*/
export const computeEffectiveWriteSet = (
fullGraph: KnowledgeGraph,
toWriteSet: ReadonlySet<string>,
): Set<string> => {
const nodeFilePaths = indexNodeFilePaths(fullGraph);
const expanded = new Set<string>(toWriteSet);
fullGraph.forEachRelationship((r: GraphRelationship) => {
const sourcePath = nodeFilePaths.get(r.sourceId);
const targetPath = nodeFilePaths.get(r.targetId);
if (!sourcePath || !targetPath) return; // skip edges to graph-wide nodes
const sourceWritable = toWriteSet.has(sourcePath);
const targetWritable = toWriteSet.has(targetPath);
if (sourceWritable && !targetWritable) expanded.add(targetPath);
else if (targetWritable && !sourceWritable) expanded.add(sourcePath);
});
return expanded;
};

251
gitnexus/src/core/ingestion/call-processor.ts
View file

@ -42,12 +42,14 @@ import { isVerboseIngestionEnabled } from './utils/verbose.js';
import { yieldToEventLoop } from './utils/event-loop.js';
import { parseSourceSafe } from '../tree-sitter/safe-parse.js';
import {
CLASS_CONTAINER_TYPES,
FUNCTION_NODE_TYPES,
findEnclosingClassId,
findEnclosingClassInfo,
genericFuncName,
inferFunctionLabel,
} from './utils/ast-helpers.js';
import type { FieldInfo, FieldExtractorContext } from './field-types.js';
import type { LanguageProvider } from './language-provider.js';
import { typeTagForId, constTagForId, buildCollisionGroups } from './utils/method-props.js';
import type { MethodInfo } from './method-types.js';
import {
@ -77,6 +79,62 @@ import type { LiteralTypeInferrer } from './type-extractors/types.js';
import type { SyntaxNode } from './utils/ast-helpers.js';
import { logger } from '../logger.js';
// ── Property-prepass helpers (parity with parse-worker.ts) ──
// These mirror the sequential-path equivalents in parse-worker.ts so the main-
// thread `processCalls` pre-pass produces byte-identical Property nodes/symbols
// to the worker pool. Drift between the two paths breaks the
// `incremental ≡ --force` invariant the moment a repo crosses the worker
// threshold between runs.
/** Walk up to the nearest enclosing class/struct/interface AST node. */
const findEnclosingClassNode = (node: SyntaxNode): SyntaxNode | null => {
let current = node.parent;
while (current) {
if (CLASS_CONTAINER_TYPES.has(current.type)) return current;
current = current.parent;
}
return null;
};
/** No-op SymbolTable stub for FieldExtractorContext — matches parse-worker. */
const NOOP_SYMBOL_TABLE: SymbolTableReader = {
lookupExact: () => undefined,
lookupExactFull: () => undefined,
lookupExactAll: () => [],
lookupCallableByName: () => [],
getFiles: () => [][Symbol.iterator](),
getStats: () => ({ fileCount: 0 }),
};
/**
* Extract (and cache) field info for a class node. Cache is passed in so it
* stays scoped to a single `processCalls` invocation rather than leaking
* across analyze runs (worker uses module-level caching because each worker
* process is short-lived; the main thread is not).
*
* Cache key is `${filePath}:${classNode.startIndex}` — startIndex alone is a
* per-file byte offset, so almost every Ruby/Python file's leading class lands
* at byte 0 and would collide across files in the shared map.
*/
const getFieldInfo = (
classNode: SyntaxNode,
provider: LanguageProvider,
context: FieldExtractorContext,
cache: Map<string, Map<string, FieldInfo>>,
): Map<string, FieldInfo> | undefined => {
if (!provider.fieldExtractor) return undefined;
const cacheKey = `${context.filePath}:${classNode.startIndex}`;
const cached = cache.get(cacheKey);
if (cached) return cached;
const result = provider.fieldExtractor.extract(classNode, context);
if (!result?.fields?.length) return undefined;
const map = new Map<string, FieldInfo>();
for (const field of result.fields) map.set(field.name, field);
cache.set(cacheKey, map);
return map;
};
/** Per-file resolved type bindings for exported symbols.
* Populated during call processing, consumed by Phase 14 re-resolution pass. */
export type ExportedTypeMap = Map<string, Map<string, string>>;
@ -708,6 +766,15 @@ export const processCalls = async (
importedRawReturnTypesMap?: ReadonlyMap<string, ReadonlyMap<string, string>>,
heritageMap?: HeritageMap,
bindingAccumulator?: BindingAccumulator,
/**
* Optional cache for compiled `Parser.Query` objects keyed by language name.
* When provided, compiled queries are reused across calls instead of being
* re-compiled from the query string for every file. Callers that invoke
* `processCalls` many times with single-file batches (e.g. the cross-file
* propagation phase) should pass a long-lived map here to avoid O(N)
* query recompilation overhead.
*/
compiledQueryCache?: Map<SupportedLanguages, Parser.Query>,
): Promise<ExtractedHeritage[]> => {
const parser = await loadParser();
const collectedHeritage: ExtractedHeritage[] = [];
@ -716,6 +783,7 @@ export const processCalls = async (
propertyName: string;
filePath: string;
srcId: string;
line?: number;
}[] = [];
// Phase P cross-file: accumulate heritage across files for cross-file isSubclassOf.
// Used as a secondary check when per-file parentMap lacks the relationship — helps
@ -784,7 +852,11 @@ export const processCalls = async (
let matches;
try {
const lang = parser.getLanguage();
const query = new Parser.Query(lang, queryStr);
let query = compiledQueryCache?.get(language);
if (!query) {
query = new Parser.Query(lang, queryStr);
compiledQueryCache?.set(language, query);
}
matches = query.matches(tree.rootNode);
} catch (queryError) {
logger.warn({ queryError }, `Query error for ${file.path}:`);
@ -860,6 +932,120 @@ export const processCalls = async (
prepared.push({ file, language, provider, tree, matches, parentMap, typeEnv });
}
// ── Property-registration pre-pass ──
// Register all routed properties (e.g. Ruby attr_accessor) BEFORE the
// resolution loop so cross-file field-type lookups (e.g.
// `user.address.save → Address#save`) succeed regardless of file
// processing order. This MUST stay in lockstep with the equivalent
// worker-path block in parse-worker.ts (kind === 'properties') — any
// divergence between the two paths breaks the `incremental ≡ --force`
// invariant once a repo crosses the worker threshold between runs.
const fieldInfoCache = new Map<string, Map<string, FieldInfo>>();
for (const { file, language, provider, matches, typeEnv } of prepared) {
const callRouter = provider.callRouter;
if (!callRouter) continue;
matches.forEach((match) => {
const captureMap: Record<string, any> = {};
match.captures.forEach((c) => (captureMap[c.name] = c.node));
if (!captureMap['call']) return;
const callNameNode = captureMap['call.name'];
if (!callNameNode) return;
const routed = callRouter(callNameNode.text, captureMap['call']);
if (!routed || routed.kind !== 'properties') return;
const propEnclosingInfo = findEnclosingClassInfo(
captureMap['call'],
file.path,
provider.resolveEnclosingOwner,
);
const propEnclosingClassId = propEnclosingInfo?.classId ?? null;
// Enrich routed properties with FieldExtractor metadata so types
// discovered from constructor assignments (e.g. `@address = Address.new`)
// are propagated even when the routing payload itself lacks declaredType.
let routedFieldMap: Map<string, FieldInfo> | undefined;
if (provider.fieldExtractor && typeEnv) {
const classNode = findEnclosingClassNode(captureMap['call']);
if (classNode) {
routedFieldMap = getFieldInfo(
classNode,
provider,
{
typeEnv,
symbolTable: NOOP_SYMBOL_TABLE,
filePath: file.path,
language,
},
fieldInfoCache,
);
}
}
const fileId = generateId('File', file.path);
for (const item of routed.items) {
const routedFieldInfo = routedFieldMap?.get(item.propName);
const propQualifiedName = propEnclosingInfo
? `${propEnclosingInfo.className}.${item.propName}`
: item.propName;
const nodeId = generateId('Property', `${file.path}:${propQualifiedName}`);
graph.addNode({
id: nodeId,
label: 'Property',
properties: {
name: item.propName,
filePath: file.path,
startLine: item.startLine,
endLine: item.endLine,
language,
isExported: true,
description: item.accessorType,
...(item.declaredType
? { declaredType: item.declaredType }
: routedFieldInfo?.type
? { declaredType: routedFieldInfo.type }
: {}),
...(routedFieldInfo?.visibility !== undefined
? { visibility: routedFieldInfo.visibility }
: {}),
...(routedFieldInfo?.isStatic !== undefined
? { isStatic: routedFieldInfo.isStatic }
: {}),
...(routedFieldInfo?.isReadonly !== undefined
? { isReadonly: routedFieldInfo.isReadonly }
: {}),
},
});
ctx.model.symbols.add(file.path, item.propName, nodeId, 'Property', {
...(propEnclosingClassId ? { ownerId: propEnclosingClassId } : {}),
...(item.declaredType
? { declaredType: item.declaredType }
: routedFieldInfo?.type
? { declaredType: routedFieldInfo.type }
: {}),
});
const relId = generateId('DEFINES', `${fileId}->${nodeId}`);
graph.addRelationship({
id: relId,
sourceId: fileId,
targetId: nodeId,
type: 'DEFINES',
confidence: 1.0,
reason: '',
});
if (propEnclosingClassId) {
graph.addRelationship({
id: generateId('HAS_PROPERTY', `${propEnclosingClassId}->${nodeId}`),
sourceId: propEnclosingClassId,
targetId: nodeId,
type: 'HAS_PROPERTY',
confidence: 1.0,
reason: '',
});
}
}
});
}
// ── Resolution loop: verify constructor bindings and resolve calls ──
// The accumulator (if present) is now fully populated from the preparation
// loop above, so verifyConstructorBindings sees all provider bindings
@ -933,7 +1119,13 @@ export const processCalls = async (
// Defer resolution: Ruby attr_accessor properties are registered during
// this same loop, so cross-file lookups fail if the declaring file hasn't
// been processed yet. Collect now, resolve after all files are done.
pendingWrites.push({ receiverTypeName, propertyName, filePath: file.path, srcId });
pendingWrites.push({
receiverTypeName,
propertyName,
filePath: file.path,
srcId,
line: captureMap['assignment'].startPosition.row + 1,
});
}
// Assignment-only capture (no @call sibling): skip the rest of this
// forEach iteration — this acts as a `continue` in the match loop.
@ -1053,47 +1245,8 @@ export const processCalls = async (
return;
case 'properties': {
const fileId = generateId('File', file.path);
const propEnclosingClassId = findEnclosingClassId(captureMap['call'], file.path);
for (const item of routed.items) {
const nodeId = generateId('Property', `${file.path}:${item.propName}`);
graph.addNode({
id: nodeId,
label: 'Property',
properties: {
name: item.propName,
filePath: file.path,
startLine: item.startLine,
endLine: item.endLine,
language,
isExported: true,
description: item.accessorType,
},
});
ctx.model.symbols.add(file.path, item.propName, nodeId, 'Property', {
...(propEnclosingClassId ? { ownerId: propEnclosingClassId } : {}),
...(item.declaredType ? { declaredType: item.declaredType } : {}),
});
const relId = generateId('DEFINES', `${fileId}->${nodeId}`);
graph.addRelationship({
id: relId,
sourceId: fileId,
targetId: nodeId,
type: 'DEFINES',
confidence: 1.0,
reason: '',
});
if (propEnclosingClassId) {
graph.addRelationship({
id: generateId('HAS_PROPERTY', `${propEnclosingClassId}->${nodeId}`),
sourceId: propEnclosingClassId,
targetId: nodeId,
type: 'HAS_PROPERTY',
confidence: 1.0,
reason: '',
});
}
}
// Properties already registered in the pre-pass above.
// Skip to avoid duplicate nodes/edges.
return;
}
@ -1382,7 +1535,10 @@ export const processCalls = async (
);
if (fieldOwner) {
graph.addRelationship({
id: generateId('ACCESSES', `${pw.srcId}:${fieldOwner.nodeId}:write`),
id: generateId(
'ACCESSES',
`${pw.srcId}:${fieldOwner.nodeId}:write${pw.line !== undefined ? `:${pw.line}` : ''}`,
),
sourceId: pw.srcId,
targetId: fieldOwner.nodeId,
type: 'ACCESSES',
@ -2979,7 +3135,10 @@ export const processAssignmentsFromExtracted = (
const fieldOwner = resolveFieldOwnership(receiverTypeName, asn.propertyName, asn.filePath, ctx);
if (!fieldOwner) continue;
graph.addRelationship({
id: generateId('ACCESSES', `${asn.sourceId}:${fieldOwner.nodeId}:write`),
id: generateId(
'ACCESSES',
`${asn.sourceId}:${fieldOwner.nodeId}:write${asn.line !== undefined ? `:${asn.line}` : ''}`,
),
sourceId: asn.sourceId,
targetId: fieldOwner.nodeId,
type: 'ACCESSES',

57
gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts
View file

@ -2,6 +2,40 @@
import { SupportedLanguages } from 'gitnexus-shared';
import type { ClassExtractionConfig } from '../../class-types.js';
import {
extractTemplateArguments,
stripTemplateArguments,
} from '../../utils/template-arguments.js';
function shouldSkipCppTemplateDuplicateCapture(
captureMap: Record<string, { text: string } | undefined>,
definitionName: string | undefined,
capturedName: string | undefined,
): boolean {
if (captureMap['template-arguments'] !== undefined) return false;
if (!definitionName) return false;
const argsFromDefinitionName = extractTemplateArguments(definitionName);
if (argsFromDefinitionName === undefined) return false;
const argsFromCaptureName = capturedName ? extractTemplateArguments(capturedName) : undefined;
// Generic class capture emits only `List`, while the specialization-aware
// capture emits `List` + `@declaration.template-arguments`. Skip the former
// when the declaration name itself is templated to avoid duplicate class defs.
return argsFromCaptureName === undefined;
}
function extractCppTemplateArgumentsWithFallback(
captureMap: Record<string, { text: string } | undefined>,
definitionName: string | undefined,
capturedName: string | undefined,
): string[] | undefined {
return (
(captureMap['template-arguments']
? extractTemplateArguments(captureMap['template-arguments'].text)
: undefined) ??
(definitionName ? extractTemplateArguments(definitionName) : undefined) ??
(capturedName ? extractTemplateArguments(capturedName) : undefined)
);
}
export const cClassConfig: ClassExtractionConfig = {
language: SupportedLanguages.C,
@ -12,4 +46,27 @@ export const cppClassConfig: ClassExtractionConfig = {
language: SupportedLanguages.CPlusPlus,
typeDeclarationNodes: ['class_specifier', 'struct_specifier', 'enum_specifier'],
ancestorScopeNodeTypes: ['namespace_definition', 'class_specifier', 'struct_specifier'],
extractName: (node) => {
const nameNode = node.childForFieldName?.('name');
if (!nameNode) return undefined;
if (nameNode.type !== 'template_type') return undefined;
return stripTemplateArguments(nameNode.text);
},
extractTemplateArguments: (node) => {
const nameNode = node.childForFieldName?.('name');
if (!nameNode || nameNode.type !== 'template_type') return undefined;
return extractTemplateArguments(nameNode.text);
},
shouldSkipClassCapture: ({ captureMap, definitionNode, nameNode }) =>
shouldSkipCppTemplateDuplicateCapture(
captureMap,
definitionNode?.childForFieldName?.('name')?.text,
nameNode?.text,
),
extractTemplateArgumentsFromCapture: ({ captureMap, definitionNode, nameNode }) =>
extractCppTemplateArgumentsWithFallback(
captureMap,
definitionNode?.childForFieldName?.('name')?.text,
nameNode?.text,
),
};

10
gitnexus/src/core/ingestion/class-extractors/generic.ts
View file

@ -154,10 +154,12 @@ export function createClassExtractor(config: ClassExtractionConfig): ClassExtrac
if (!name || !type) return null;
const templateArguments = config.extractTemplateArguments?.(node);
return {
name,
type,
qualifiedName: buildQualifiedName(node, name) || name,
...(templateArguments !== undefined ? { templateArguments } : {}),
};
};
@ -173,5 +175,13 @@ export function createClassExtractor(config: ClassExtractionConfig): ClassExtrac
extractQualifiedName(node: SyntaxNode, simpleName: string): string | null {
return extract(node, { name: simpleName })?.qualifiedName ?? null;
},
shouldSkipClassCapture(context): boolean {
return config.shouldSkipClassCapture?.(context) ?? false;
},
extractTemplateArgumentsFromCapture(context): string[] | undefined {
return config.extractTemplateArgumentsFromCapture?.(context);
},
};
}

16
gitnexus/src/core/ingestion/class-types.ts
View file

@ -10,6 +10,13 @@ export interface ExtractedClassSymbol {
name: string;
type: ClassLikeNodeLabel;
qualifiedName: string;
templateArguments?: string[];
}
export interface ClassCaptureContext {
captureMap: Record<string, SyntaxNode>;
definitionNode: SyntaxNode | null;
nameNode: SyntaxNode | undefined;
}
/**
@ -30,6 +37,10 @@ export interface ClassExtractor {
},
): ExtractedClassSymbol | null;
extractQualifiedName(node: SyntaxNode, simpleName: string): string | null;
shouldSkipClassCapture?(
context: ClassCaptureContext & { nodeLabel: ClassLikeNodeLabel },
): boolean;
extractTemplateArgumentsFromCapture?(context: ClassCaptureContext): string[] | undefined;
}
export interface ClassExtractionConfig {
@ -41,4 +52,9 @@ export interface ClassExtractionConfig {
extractName?: (node: SyntaxNode) => string | undefined;
extractType?: (node: SyntaxNode) => ClassLikeNodeLabel | undefined;
extractScopeSegments?: (node: SyntaxNode) => string[] | null | undefined;
extractTemplateArguments?: (node: SyntaxNode) => string[] | undefined;
shouldSkipClassCapture?(
context: ClassCaptureContext & { nodeLabel: ClassLikeNodeLabel },
): boolean;
extractTemplateArgumentsFromCapture?(context: ClassCaptureContext): string[] | undefined;
}

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

@ -41,6 +41,24 @@ interface LeidenDetailedResult {
modularity: number;
}
/**
* Deterministic PRNG (mulberry32) seed for the vendored Leiden algorithm.
* Vendored Leiden defaults `rng: Math.random`, which makes community
* assignment non-deterministic across runs. Passing a seeded RNG gives us
* reproducible community/modularity output, which is required for the
* incremental-indexing equivalence test (incremental ≡ full rebuild).
*/
const LEIDEN_SEED = 0xc0de;
function createSeededRng(seed: number): () => number {
let s = seed >>> 0;
return () => {
s = (s + 0x6d2b79f5) >>> 0;
let t = Math.imul(s ^ (s >>> 15), 1 | s);
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
// ============================================================================
// TYPES
// ============================================================================
@ -150,6 +168,7 @@ export const processCommunities = async (
leiden.detailed(graph, {
resolution: isLarge ? 2.0 : 1.0,
maxIterations: isLarge ? 3 : 0,
rng: createSeededRng(LEIDEN_SEED),
}),
),
new Promise<never>((_, reject) =>

36
gitnexus/src/core/ingestion/import-resolvers/standard.ts
View file

@ -72,6 +72,13 @@ export const resolveImportPath = (
const resolved = tryResolveWithExtensions(rewritten, allFiles);
if (resolved) return cache(resolved);
// ESM fallback: strip .js/.jsx/.mjs/.cjs and retry with TS equivalents
const strippedAlias = stripJsExtension(rewritten);
if (strippedAlias !== null) {
const esmResolved = tryResolveWithExtensions(strippedAlias, allFiles);
if (esmResolved) return cache(esmResolved);
}
// Try suffix matching as fallback
const parts = rewritten.split('/').filter(Boolean);
const suffixResult = suffixResolve(parts, normalizedFileList, allFileList, index);
@ -128,7 +135,18 @@ export const resolveImportPath = (
if (importPath.startsWith('.')) {
const resolved = tryResolveWithExtensions(basePath, allFiles);
return cache(resolved);
if (resolved) return cache(resolved);
// TypeScript ESM: imports use .js/.jsx/.mjs/.cjs but source files are
// .ts/.tsx/.mts/.cts. Strip the JS-family extension and re-resolve.
if (language === SupportedLanguages.TypeScript || language === SupportedLanguages.JavaScript) {
const stripped = stripJsExtension(basePath);
if (stripped !== null) {
return cache(tryResolveWithExtensions(stripped, allFiles));
}
}
return cache(null);
}
// ---- Generic package/absolute import resolution (suffix matching) ----
@ -182,3 +200,19 @@ export function resolveStandard(
export function createStandardStrategy(language: SupportedLanguages): ImportResolverStrategy {
return (raw, fp, ctx) => resolveStandard(raw, fp, ctx, language);
}
// ============================================================================
// ESM extension helpers
// ============================================================================
/** JS-family extensions that TypeScript ESM maps to TS equivalents. */
const JS_EXTENSION_PATTERN = /\.(js|jsx|mjs|cjs)$/;
/**
* Strip a JS-family extension from a path, returning the stem.
* Returns `null` if the path does not end with a JS-family extension.
*/
export function stripJsExtension(path: string): string | null {
const match = JS_EXTENSION_PATTERN.exec(path);
return match ? path.slice(0, -match[0].length) : null;
}

4
gitnexus/src/core/ingestion/import-resolvers/utils.ts
View file

@ -9,8 +9,12 @@ export const EXTENSIONS = [
// TypeScript/JavaScript
'.tsx',
'.ts',
'.mts',
'.cts',
'.jsx',
'.js',
'.mjs',
'.cjs',
'.vue',
'/index.tsx',
'/index.ts',

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

@ -210,6 +210,37 @@ interface LanguageProviderConfig {
ancestorNode: SyntaxNode,
) => { funcName: string; label: NodeLabel } | null;
// ── Template constraint extraction (SFINAE / `requires`) ────────────
/**
* Extract a per-language template-constraint payload for a templated
* function / method definition. Used by `parsing-processor` to
* disambiguate same-name same-arity overloads whose distinguishing
* signal is their template constraints rather than their parameter
* types — the canonical C++ SFINAE case (issue #1579):
*
* template<class T, std::enable_if_t<is_integral_v<T>, int> = 0>
* void process(T); // overload A
*
* template<class T, std::enable_if_t<is_floating_point_v<T>, int> = 0>
* void process(T); // overload B
*
* Both overloads' `parameterTypes` collapse to `['T']`, so without a
* constraint fingerprint in the graph node ID they merge into one
* Function node and the resolver only ever sees one candidate to
* narrow. The hook's return value is stamped onto the node's ID via
* `templateConstraintsIdTag()` AND stored on the node's
* `templateConstraints` property so `resolveDefGraphId` can look up
* the right overload by re-hashing the def's constraints at resolve
* time.
*
* Returns the opaque payload (any JSON-serializable shape — the
* producing adapter owns it; shared code MUST NOT inspect) or
* `undefined` when no constraints exist / the node isn't a templated
* function. Languages without SFINAE / concept semantics leave this
* undefined and the disambiguation is a pass-through.
*/
readonly extractTemplateConstraints?: (definitionNode: SyntaxNode) => unknown;
// ── Labels ────────────────────────────────────────────────────────
/** Override the default node label for definition.function captures.
* Return null to skip (C/C++ duplicate), a different label to reclassify

94
gitnexus/src/core/ingestion/languages/c-cpp.ts
View file

@ -46,6 +46,25 @@ import { createCallExtractor } from '../call-extractors/generic.js';
import { cCallConfig, cppCallConfig } from '../call-extractors/configs/c-cpp.js';
import { createHeritageExtractor } from '../heritage-extractors/generic.js';
import { stripUeMacros } from '../cpp-ue-preprocessor.js';
import {
emitCScopeCaptures,
interpretCImport,
interpretCTypeBinding,
cArityCompatibility,
cBindingScopeFor,
cImportOwningScope,
cReceiverBinding,
} from './c/index.js';
import {
emitCppScopeCaptures,
interpretCppImport,
interpretCppTypeBinding,
cppArityCompatibility,
cppBindingScopeFor,
cppImportOwningScope,
cppReceiverBinding,
} from './cpp/index.js';
import { extractCppTemplateConstraints } from './cpp/constraint-extractor.js';
const C_BUILT_INS: ReadonlySet<string> = new Set([
'printf',
@ -294,12 +313,19 @@ const cCppExtractFunctionName = (
return { funcName, label };
};
/** Check if a C/C++ function_definition is inside a class or struct body.
/** Check if a C/C++ function_definition is inside a class or struct body
* (and NOT a friend declaration).
* Used by cppLabelOverride to skip duplicate function captures
* that are already covered by definition.method queries. */
* that are already covered by definition.method queries.
* Friend functions are free functions defined inside class bodies —
* they must NOT be skipped (ISO C++ hidden-friend idiom). */
function isCppInsideClassOrStruct(functionNode: SyntaxNode): boolean {
let ancestor: SyntaxNode | null = functionNode?.parent ?? null;
while (ancestor) {
// Friend declarations: the function_definition is wrapped in
// `friend_declaration` → `field_declaration_list` → class_specifier.
// These are free functions, not methods — don't skip them.
if (ancestor.type === 'friend_declaration') return false;
if (ancestor.type === 'class_specifier' || ancestor.type === 'struct_specifier') return true;
ancestor = ancestor.parent;
}
@ -367,6 +393,16 @@ export const cProvider = defineLanguage({
heritageExtractor: createHeritageExtractor(SupportedLanguages.C),
labelOverride: cppLabelOverride,
builtInNames: C_BUILT_INS,
// ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
emitScopeCaptures: emitCScopeCaptures,
interpretImport: interpretCImport,
interpretTypeBinding: interpretCTypeBinding,
bindingScopeFor: cBindingScopeFor,
importOwningScope: cImportOwningScope,
receiverBinding: cReceiverBinding,
arityCompatibility: cArityCompatibility,
// mergeBindings + resolveImportTarget live on ScopeResolver (see c/scope-resolver.ts).
});
export const cppProvider = defineLanguage({
@ -428,4 +464,58 @@ export const cppProvider = defineLanguage({
heritageExtractor: createHeritageExtractor(SupportedLanguages.CPlusPlus),
labelOverride: cppLabelOverride,
builtInNames: C_BUILT_INS,
extractTemplateConstraints: extractCppTemplateConstraintsForProvider,
// ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
emitScopeCaptures: emitCppScopeCaptures,
interpretImport: interpretCppImport,
interpretTypeBinding: interpretCppTypeBinding,
bindingScopeFor: cppBindingScopeFor,
importOwningScope: cppImportOwningScope,
receiverBinding: cppReceiverBinding,
arityCompatibility: cppArityCompatibility,
// mergeBindings + resolveImportTarget live on ScopeResolver (see cpp/scope-resolver.ts).
});
/**
* LanguageProvider hook: walk from a function definition node up to its
* enclosing `template_declaration` and extract the SFINAE / `requires`-
* clause constraint payload. Used by `parsing-processor` to fingerprint
* the graph node ID so two SFINAE overloads with identical
* `parameterTypes` get distinct nodes (issue #1579).
*
* Returns `undefined` for non-templated functions and for templated
* functions whose constraints the extractor can't model — both cases
* result in no constraint suffix on the node ID.
*/
function extractCppTemplateConstraintsForProvider(definitionNode: SyntaxNode): unknown {
// Walk up to the enclosing template_declaration. Bound the walk so we
// can't accidentally land on a far-ancestor template_declaration that
// wraps an unrelated function.
let cur: SyntaxNode | null = definitionNode.parent;
let hops = 8;
let templateDecl: SyntaxNode | null = null;
while (cur !== null && hops-- > 0) {
if (cur.type === 'template_declaration') {
templateDecl = cur;
break;
}
if (cur.type === 'translation_unit') break;
cur = cur.parent;
}
if (templateDecl === null) return undefined;
// Find the function_declarator inside the function definition so the
// extractor can map template params to function-argument indices.
let declarator: SyntaxNode | null = definitionNode.childForFieldName('declarator');
let walk = 8;
while (declarator !== null && walk-- > 0) {
if (declarator.type === 'function_declarator') break;
if (declarator.type === 'pointer_declarator' || declarator.type === 'reference_declarator') {
declarator = declarator.childForFieldName('declarator');
continue;
}
break;
}
return extractCppTemplateConstraints(templateDecl, declarator);
}

102
gitnexus/src/core/ingestion/languages/c/arity-metadata.ts Normal file
View file

@ -0,0 +1,102 @@
import type { SyntaxNode } from '../../utils/ast-helpers.js';
export interface CArityInfo {
parameterCount?: number;
requiredParameterCount?: number;
parameterTypes?: string[];
}
/**
* Compute declaration arity from a C function definition or declaration node.
*/
export function computeCDeclarationArity(node: SyntaxNode): CArityInfo {
// Find the function_declarator child (may be wrapped in pointer_declarator)
const funcDecl = findFuncDeclarator(node);
if (funcDecl === null) return {};
const paramList = funcDecl.childForFieldName('parameters');
if (paramList === null) return {};
const params: SyntaxNode[] = [];
for (let i = 0; i < paramList.childCount; i++) {
const child = paramList.child(i);
if (child === null) continue;
if (child.type === 'parameter_declaration' || child.type === 'variadic_parameter') {
params.push(child);
}
}
// K&R old-style declaration: `int foo()` has an empty parameter_list with
// no parameter_declaration or variadic_parameter children. Per C89/C99,
// this means the function accepts an unspecified number/types of arguments —
// NOT zero arguments. Return unknown arity to avoid false 'incompatible'.
// `int foo(void)` is the explicit zero-parameter form and is handled below.
if (params.length === 0) return {};
// (void) means zero parameters
if (params.length === 1 && params[0].type === 'parameter_declaration') {
const typeNode = params[0].childForFieldName('type');
const hasDeclarator = params[0].childForFieldName('declarator') !== null;
if (typeNode !== null && typeNode.text === 'void' && !hasDeclarator) {
return { parameterCount: 0, requiredParameterCount: 0, parameterTypes: [] };
}
}
const isVariadic = params.some((p) => p.type === 'variadic_parameter');
const nonVariadicCount = params.filter((p) => p.type !== 'variadic_parameter').length;
const types: string[] = [];
for (const p of params) {
if (p.type === 'variadic_parameter') {
types.push('...');
} else {
const typeNode = p.childForFieldName('type');
types.push(typeNode?.text ?? 'unknown');
}
}
return {
parameterCount: isVariadic ? undefined : nonVariadicCount,
requiredParameterCount: nonVariadicCount,
parameterTypes: types,
};
}
/**
* Compute call-site arity from a call_expression node.
*/
export function computeCCallArity(node: SyntaxNode): number {
const argList = node.childForFieldName('arguments');
if (argList === null) return 0;
let count = 0;
for (let i = 0; i < argList.childCount; i++) {
const child = argList.child(i);
if (child === null) continue;
// Skip punctuation (commas, parens)
if (child.type !== ',' && child.type !== '(' && child.type !== ')') {
count++;
}
}
return count;
}
function findFuncDeclarator(node: SyntaxNode): SyntaxNode | null {
// Direct child
let decl = node.childForFieldName('declarator');
if (decl === null) {
for (let i = 0; i < node.childCount; i++) {
const c = node.child(i);
if (c?.type === 'function_declarator') return c;
}
return null;
}
// Unwrap pointer_declarator
while (decl.type === 'pointer_declarator') {
const next = decl.childForFieldName('declarator');
if (next === null) break;
decl = next;
}
if (decl.type === 'function_declarator') return decl;
return null;
}

20
gitnexus/src/core/ingestion/languages/c/arity.ts Normal file
View file

@ -0,0 +1,20 @@
import type { Callsite, SymbolDefinition } from 'gitnexus-shared';
/**
* C arity compatibility: no overloading. Variadic functions detected
* via '...' in parameterTypes. Otherwise exact match or unknown.
*/
export function cArityCompatibility(
def: SymbolDefinition,
callsite: Callsite,
): 'compatible' | 'unknown' | 'incompatible' {
const max = def.parameterCount;
const min = def.requiredParameterCount;
if (max === undefined && min === undefined) return 'unknown';
if (!Number.isFinite(callsite.arity) || callsite.arity < 0) return 'unknown';
const variadic = def.parameterTypes?.some((t) => t === '...') ?? false;
if (min !== undefined && callsite.arity < min) return 'incompatible';
if (max !== undefined && callsite.arity > max && !variadic) return 'incompatible';
return 'compatible';
}

142
gitnexus/src/core/ingestion/languages/c/captures.ts Normal file
View file

@ -0,0 +1,142 @@
import type { Capture, CaptureMatch } from 'gitnexus-shared';
import {
findNodeAtRange,
nodeToCapture,
syntheticCapture,
type SyntaxNode,
} from '../../utils/ast-helpers.js';
import { getCParser, getCScopeQuery } from './query.js';
import { getTreeSitterBufferSize } from '../../constants.js';
import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
import { splitCInclude } from './import-decomposer.js';
import { computeCDeclarationArity, computeCCallArity } from './arity-metadata.js';
import { markStaticName } from './static-linkage.js';
export function emitCScopeCaptures(
sourceText: string,
filePath: string,
cachedTree?: unknown,
): readonly CaptureMatch[] {
let tree = cachedTree as ReturnType<ReturnType<typeof getCParser>['parse']> | undefined;
if (tree === undefined) {
tree = parseSourceSafe(getCParser(), sourceText, undefined, {
bufferSize: getTreeSitterBufferSize(sourceText),
});
}
const rawMatches = getCScopeQuery().matches(tree.rootNode);
const out: CaptureMatch[] = [];
// Track ranges where typedef-struct/union was captured as @declaration.struct/union
// so we can suppress the duplicate @declaration.typedef match at the same range.
const structTypedefRanges = new Set<string>();
for (const m of rawMatches) {
const grouped: Record<string, Capture> = {};
for (const c of m.captures) {
const tag = '@' + c.name;
if (tag.startsWith('@_')) continue;
grouped[tag] = nodeToCapture(tag, c.node);
}
if (Object.keys(grouped).length === 0) continue;
// Handle #include statements
if (grouped['@import.statement'] !== undefined) {
const anchor = grouped['@import.statement']!;
const includeNode = findNodeAtRange(tree.rootNode, anchor.range, 'preproc_include');
if (includeNode !== null) {
const split = splitCInclude(includeNode);
if (split !== null) {
out.push(split);
continue;
}
}
}
// Track typedef-struct ranges to suppress duplicate typedef declarations
const structAnchor = grouped['@declaration.struct'] ?? grouped['@declaration.union'];
if (structAnchor !== undefined) {
const r = structAnchor.range;
structTypedefRanges.add(`${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}`);
}
// Suppress @declaration.typedef if the same range was already captured as struct/union
const typedefAnchor = grouped['@declaration.typedef'];
if (typedefAnchor !== undefined) {
const r = typedefAnchor.range;
const key = `${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}`;
if (structTypedefRanges.has(key)) continue;
}
// Enrich function declarations with arity metadata and detect static linkage
const declAnchor = grouped['@declaration.function'];
if (declAnchor !== undefined) {
const fnNode =
findNodeAtRange(tree.rootNode, declAnchor.range, 'function_definition') ??
findNodeAtRange(tree.rootNode, declAnchor.range, 'declaration');
if (fnNode !== null) {
const arity = computeCDeclarationArity(fnNode);
if (arity.parameterCount !== undefined) {
grouped['@declaration.parameter-count'] = syntheticCapture(
'@declaration.parameter-count',
fnNode,
String(arity.parameterCount),
);
}
if (arity.requiredParameterCount !== undefined) {
grouped['@declaration.required-parameter-count'] = syntheticCapture(
'@declaration.required-parameter-count',
fnNode,
String(arity.requiredParameterCount),
);
}
if (arity.parameterTypes !== undefined) {
grouped['@declaration.parameter-types'] = syntheticCapture(
'@declaration.parameter-types',
fnNode,
JSON.stringify(arity.parameterTypes),
);
}
// Detect static storage class (file-local linkage)
if (hasStaticStorageClass(fnNode)) {
const nameText = grouped['@declaration.name']?.text;
if (nameText !== undefined) {
markStaticName(filePath, nameText);
}
}
}
}
// Enrich call references with arity
const callAnchor = grouped['@reference.call.free'] ?? grouped['@reference.call.member'];
if (callAnchor !== undefined && grouped['@reference.arity'] === undefined) {
const callNode = findNodeAtRange(tree.rootNode, callAnchor.range, 'call_expression');
if (callNode !== null) {
grouped['@reference.arity'] = syntheticCapture(
'@reference.arity',
callNode,
String(computeCCallArity(callNode)),
);
}
}
out.push(grouped);
}
return out;
}
/**
* Check if a C function_definition or declaration has `static` storage class.
* Walks direct children for a `storage_class_specifier` node with text `static`.
*/
function hasStaticStorageClass(node: SyntaxNode): boolean {
for (let i = 0; i < node.childCount; i++) {
const child = node.child(i);
if (child !== null && child.type === 'storage_class_specifier' && child.text === 'static') {
return true;
}
}
return false;
}

58
gitnexus/src/core/ingestion/languages/c/header-scan.ts Normal file
View file

@ -0,0 +1,58 @@
import { readdirSync, type Dirent } from 'fs';
import { join, relative } from 'path';
/** C header extensions to scan for in the workspace. */
const HEADER_EXTENSIONS = new Set(['.h']);
/**
* Walk `repoPath` recursively and return relative paths of all `.h` files.
* Used by `loadResolutionConfig` so the C resolver can resolve `#include`
* targets that live in `.h` files (classified as C++ by language detection
* but importable from `.c` files).
*/
export function scanHeaderFiles(repoPath: string): ReadonlySet<string> {
const headers = new Set<string>();
walk(repoPath, repoPath, headers);
return headers;
}
function walk(dir: string, root: string, out: Set<string>): void {
let entries: Dirent[];
try {
entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf8' });
} catch {
return; // permission denied, etc.
}
for (const entry of entries) {
const name = entry.name;
const full = join(dir, name);
if (entry.isDirectory()) {
// Skip common non-source directories and build output dirs.
// Build dirs (dist, build, out, target, _build, .next, cmake-build-*)
// may contain generated headers that shadow source headers.
if (
name === 'node_modules' ||
name === '.git' ||
name === 'vendor' ||
name === 'dist' ||
name === 'build' ||
name === 'out' ||
name === 'target' ||
name === '_build' ||
name === '.next' ||
name.startsWith('cmake-build')
) {
continue;
}
walk(full, root, out);
} else if (entry.isFile()) {
const ext = name.slice(name.lastIndexOf('.'));
if (HEADER_EXTENSIONS.has(ext)) {
// Normalize to forward slashes for cross-platform consistency.
// path.relative() returns backslash-separated paths on Windows,
// but the scope-resolution pipeline uses forward slashes uniformly.
out.add(relative(root, full).replace(/\\/g, '/'));
}
}
}
}

55
gitnexus/src/core/ingestion/languages/c/import-decomposer.ts Normal file
View file

@ -0,0 +1,55 @@
import type { Capture, CaptureMatch } from 'gitnexus-shared';
import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js';
/**
* Decompose a `preproc_include` node into a CaptureMatch with structured
* import captures. C #include maps to a wildcard import (all symbols
* from the header are visible).
*/
export function splitCInclude(node: SyntaxNode): CaptureMatch | null {
// node.type === 'preproc_include'
// path field: (string_literal (string_content)) | (system_lib_string)
const pathNode = node.childForFieldName?.('path') ?? null;
if (pathNode === null) {
// Fallback: scan children
for (let i = 0; i < node.childCount; i++) {
const child = node.child(i);
if (child === null) continue;
if (child.type === 'string_literal' || child.type === 'system_lib_string') {
return buildIncludeCapture(node, child);
}
}
return null;
}
return buildIncludeCapture(node, pathNode);
}
function buildIncludeCapture(node: SyntaxNode, pathNode: SyntaxNode): CaptureMatch {
let raw: string;
if (pathNode.type === 'string_literal') {
// string_literal has children: `"`, string_content, `"`
// Use namedChildren to find the string_content node
const content = pathNode.namedChildren.find((c) => c.type === 'string_content');
raw = content?.text ?? pathNode.text.replace(/^"|"$/g, '');
} else {
// system_lib_string: <stdio.h> → strip angle brackets
raw = pathNode.text;
if (raw.startsWith('<') && raw.endsWith('>')) {
raw = raw.slice(1, -1);
}
}
const isSystem = pathNode.type === 'system_lib_string';
const result: Record<string, Capture> = {
'@import.statement': nodeToCapture('@import.statement', node),
'@import.kind': syntheticCapture('@import.kind', node, 'wildcard'),
'@import.source': syntheticCapture('@import.source', node, raw),
};
if (isSystem) {
result['@import.system'] = syntheticCapture('@import.system', node, 'true');
}
return result;
}

64
gitnexus/src/core/ingestion/languages/c/import-target.ts Normal file
View file

@ -0,0 +1,64 @@
import { dirname, join } from 'path';
/**
* Resolve a C #include path to a file in the workspace.
*
* Strategy:
* 1. Check for a same-directory sibling relative to the including file
* (matches C compiler `#include "…"` relative-lookup semantics).
* 2. Check for an exact match (path as-is in the workspace).
* 3. Fall back to suffix matching against all workspace file paths.
* Tie-breaking: prefer the match with the fewest path components
* (closest to root). On equal depth, break ties lexicographically
* by normalized path to ensure deterministic resolution regardless
* of filesystem iteration order.
*/
export function resolveCImportTarget(
targetRaw: string,
fromFile: string,
allFilePaths: ReadonlySet<string>,
): string | null {
if (!targetRaw) return null;
const normalizedTarget = targetRaw.replace(/\\/g, '/');
// Same-directory sibling first: mirrors the C compiler's #include "…"
// relative-lookup semantics where the directory of the including
// file is searched before the include-path list.
if (fromFile) {
const siblingRaw = join(dirname(fromFile), targetRaw);
const sibling = siblingRaw.replace(/\\/g, '/');
if (allFilePaths.has(sibling)) return sibling;
// When targetRaw contains backslashes, the normalized form may
// resolve to a different sibling path — try it as well.
if (targetRaw !== normalizedTarget) {
const siblingAlt = join(dirname(fromFile), normalizedTarget);
const siblingAltNorm = siblingAlt.replace(/\\/g, '/');
if (allFilePaths.has(siblingAltNorm)) return siblingAltNorm;
}
}
// Exact match (path as-is in the workspace)
if (allFilePaths.has(normalizedTarget)) return normalizedTarget;
// Suffix match: find files ending with /targetRaw or equal to targetRaw
const suffix = '/' + normalizedTarget;
let bestMatch: string | null = null;
let bestDepth = Infinity;
let bestNormalized = '';
for (const filePath of allFilePaths) {
const normalized = filePath.replace(/\\/g, '/');
if (normalized === normalizedTarget || normalized.endsWith(suffix)) {
// Prefer shortest path (closest match)
const depth = normalized.split('/').length;
if (depth < bestDepth || (depth === bestDepth && normalized < bestNormalized)) {
bestDepth = depth;
bestMatch = filePath;
bestNormalized = normalized;
}
}
}
return bestMatch;
}

16
gitnexus/src/core/ingestion/languages/c/index.ts Normal file
View file

@ -0,0 +1,16 @@
/**
* C scope-resolution hooks (RFC #909 Ring 3).
*/
export { emitCScopeCaptures } from './captures.js';
export { interpretCImport, interpretCTypeBinding, normalizeCTypeName } from './interpret.js';
export { splitCInclude } from './import-decomposer.js';
export { cArityCompatibility } from './arity.js';
export { cMergeBindings } from './merge-bindings.js';
export { cBindingScopeFor, cImportOwningScope, cReceiverBinding } from './simple-hooks.js';
export { resolveCImportTarget } from './import-target.js';
export {
markStaticName,
isStaticName,
clearStaticNames,
expandCWildcardNames,
} from './static-linkage.js';

51
gitnexus/src/core/ingestion/languages/c/interpret.ts Normal file
View file

@ -0,0 +1,51 @@
import type { CaptureMatch, ParsedImport, ParsedTypeBinding, TypeRef } from 'gitnexus-shared';
/**
* Interpret a C #include capture into a ParsedImport.
* C includes are always wildcard imports (all symbols from the header).
*/
export function interpretCImport(captures: CaptureMatch): ParsedImport | null {
const source = captures['@import.source']?.text;
if (source === undefined) return null;
// System headers (e.g. <stdio.h>) are not resolved to local files
if (captures['@import.system'] !== undefined) return null;
return { kind: 'wildcard', targetRaw: source };
}
/**
* Interpret a C type-binding capture into a ParsedTypeBinding.
*/
export function interpretCTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null {
const name = captures['@type-binding.name']?.text;
const type = captures['@type-binding.type']?.text;
if (name === undefined || type === undefined) return null;
let source: TypeRef['source'] = 'annotation';
if (captures['@type-binding.parameter'] !== undefined) {
source = 'parameter-annotation';
} else if (captures['@type-binding.assignment'] !== undefined) {
source = 'assignment-inferred';
}
return { boundName: name, rawTypeName: normalizeCTypeName(type), source };
}
/**
* Normalize a C type name: strip pointer/array syntax, qualifiers.
*/
export function normalizeCTypeName(text: string): string {
let t = text.trim();
// Strip const, volatile, restrict qualifiers
t = t.replace(/\b(const|volatile|restrict|static|extern|inline)\b/g, '').trim();
// Strip pointer stars
while (t.endsWith('*')) t = t.slice(0, -1).trim();
while (t.startsWith('*')) t = t.slice(1).trim();
// Strip array brackets
t = t.replace(/\[.*?\]/g, '').trim();
// Strip struct/union/enum prefixes
t = t.replace(/^(struct|union|enum)\s+/, '');
return t;
}

32
gitnexus/src/core/ingestion/languages/c/merge-bindings.ts Normal file
View file

@ -0,0 +1,32 @@
import type { BindingRef } from 'gitnexus-shared';
const TIER: Record<BindingRef['origin'], number> = {
local: 0,
namespace: 1,
import: 2,
reexport: 3,
wildcard: 4,
};
/**
* C merge bindings: simple first-wins by tier (local > import > wildcard).
* C has no namespaces or reexports, but the tiers are defined for
* compatibility with the shared infrastructure.
*/
export function cMergeBindings(
existing: readonly BindingRef[],
incoming: readonly BindingRef[],
_scopeId: string,
): BindingRef[] {
const seen = new Set<string>();
return [...existing, ...incoming]
.sort(
(a, b) =>
(TIER[a.origin] ?? 99) - (TIER[b.origin] ?? 99) || a.def.nodeId.localeCompare(b.def.nodeId),
)
.filter((binding) => {
if (seen.has(binding.def.nodeId)) return false;
seen.add(binding.def.nodeId);
return true;
});
}

165
gitnexus/src/core/ingestion/languages/c/query.ts Normal file
View file

@ -0,0 +1,165 @@
import Parser from 'tree-sitter';
import C from 'tree-sitter-c';
const C_SCOPE_QUERY = `
;; Scopes
(translation_unit) @scope.module
(struct_specifier) @scope.class
(union_specifier) @scope.class
(function_definition) @scope.function
(compound_statement) @scope.block
(if_statement) @scope.block
(for_statement) @scope.block
(while_statement) @scope.block
(do_statement) @scope.block
(switch_statement) @scope.block
(case_statement) @scope.block
;; Declarations — struct (named)
(struct_specifier
name: (type_identifier) @declaration.name
body: (field_declaration_list)) @declaration.struct
;; Declarations — struct (typedef struct { ... } Name)
(type_definition
type: (struct_specifier
body: (field_declaration_list))
declarator: (type_identifier) @declaration.name) @declaration.struct
;; Declarations — union (named)
(union_specifier
name: (type_identifier) @declaration.name
body: (field_declaration_list)) @declaration.union
;; Declarations — union (typedef union { ... } Name)
(type_definition
type: (union_specifier
body: (field_declaration_list))
declarator: (type_identifier) @declaration.name) @declaration.union
;; Declarations — enum
(enum_specifier
name: (type_identifier) @declaration.name) @declaration.enum
;; Declarations — function definition
(function_definition
declarator: (function_declarator
declarator: (identifier) @declaration.name)) @declaration.function
;; Declarations — function definition with pointer return
(function_definition
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (identifier) @declaration.name))) @declaration.function
;; Declarations — function declaration (prototype)
;; Note: Both prototypes and definitions are captured as @declaration.function.
;; This may produce duplicate Function nodes in the knowledge graph when a
;; function is declared in a header and defined in a .c file. CALLS edges
;; resolve correctly through scope-based wildcard import chains; the
;; duplication is a graph-quality concern only (no false edges).
(declaration
declarator: (function_declarator
declarator: (identifier) @declaration.name)) @declaration.function
;; Declarations — function declaration with pointer return (prototype)
(declaration
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (identifier) @declaration.name))) @declaration.function
;; Declarations — typedef
(type_definition
declarator: (type_identifier) @declaration.name) @declaration.typedef
;; Declarations — typedef for function pointers: typedef void (*callback)(int, int)
(type_definition
declarator: (function_declarator
declarator: (parenthesized_declarator
(pointer_declarator
declarator: (type_identifier) @declaration.name)))) @declaration.typedef
;; Declarations — struct fields
(field_declaration
declarator: (field_identifier) @declaration.name) @declaration.field
;; Declarations — struct fields (pointer)
(field_declaration
declarator: (pointer_declarator
declarator: (field_identifier) @declaration.name)) @declaration.field
;; Declarations — variables (with initializer)
(declaration
declarator: (init_declarator
declarator: (identifier) @declaration.name)) @declaration.variable
;; Declarations — macro definitions
(preproc_def
name: (identifier) @declaration.name) @declaration.macro
(preproc_function_def
name: (identifier) @declaration.name) @declaration.macro
;; Declarations — enum constants
(enumerator
name: (identifier) @declaration.name) @declaration.const
;; Imports
(preproc_include) @import.statement
;; Type bindings — parameter annotations
(parameter_declaration
type: (_) @type-binding.type
declarator: (identifier) @type-binding.name) @type-binding.parameter
;; Type bindings — variable with type (init_declarator)
(declaration
type: (_) @type-binding.type
declarator: (init_declarator
declarator: (identifier) @type-binding.name)) @type-binding.assignment
;; References — free calls
;; Note: This also captures calls through function pointer variables (e.g. fp(x))
;; since tree-sitter-c produces structurally identical AST nodes for both direct
;; function calls and function-pointer-variable calls. A type-based guard to
;; distinguish variable-calls from function-calls is not implemented — this is a
;; known architectural trade-off shared with the Go resolver. The uniqueness
;; constraint in pickUniqueGlobalCallable limits false edge exposure.
(call_expression
function: (identifier) @reference.name) @reference.call.free
;; References — member calls via pointer (ptr->func())
(call_expression
function: (field_expression
argument: (_) @reference.receiver
field: (field_identifier) @reference.name)) @reference.call.member
;; References — field reads
(field_expression
argument: (_) @reference.receiver
field: (field_identifier) @reference.name) @reference.read
;; References — field writes (assignment)
(assignment_expression
left: (field_expression
argument: (_) @reference.receiver
field: (field_identifier) @reference.name)) @reference.write
`;
let _parser: Parser | null = null;
let _query: Parser.Query | null = null;
export function getCParser(): Parser {
if (_parser === null) {
_parser = new Parser();
_parser.setLanguage(C as Parameters<Parser['setLanguage']>[0]);
}
return _parser;
}
export function getCScopeQuery(): Parser.Query {
if (_query === null) {
_query = new Parser.Query(C as Parameters<Parser['setLanguage']>[0], C_SCOPE_QUERY);
}
return _query;
}

73
gitnexus/src/core/ingestion/languages/c/scope-resolver.ts Normal file
View file

@ -0,0 +1,73 @@
import type { ParsedFile, SymbolDefinition } from 'gitnexus-shared';
import { SupportedLanguages } from 'gitnexus-shared';
import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
import { cProvider } from '../c-cpp.js';
import { cArityCompatibility, cMergeBindings, resolveCImportTarget } from './index.js';
import { scanHeaderFiles } from './header-scan.js';
import { expandCWildcardNames, isStaticName, clearStaticNames } from './static-linkage.js';
/**
* C `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
* the generic `runScopeResolution` orchestrator (RFC #909 Ring 3).
*
* C is a structurally simple language for scope resolution:
* - No classes (structs are value types, no method dispatch)
* - No inheritance (no MRO needed beyond the shared first-wins default)
* - No overloading (arity check is simple: variadic detection only)
* - `#include` is wildcard import (all symbols from header are visible)
* - `static` functions are file-local (not exported)
*/
export const cScopeResolver: ScopeResolver = {
language: SupportedLanguages.C,
languageProvider: cProvider,
importEdgeReason: 'c-scope: include',
loadResolutionConfig: (repoPath: string) => {
// Clear stale static-linkage data from any previous invocation to
// prevent cross-repo contamination in server-mode scenarios.
clearStaticNames();
return scanHeaderFiles(repoPath);
},
resolveImportTarget: (targetRaw, fromFile, allFilePaths, resolutionConfig) => {
// Augment allFilePaths with .h files discovered via loadResolutionConfig
// since the phase only passes .c files to the C resolver but #include
// targets .h files classified as C++ in language detection.
const headerPaths = resolutionConfig as ReadonlySet<string> | undefined;
if (headerPaths !== undefined && headerPaths.size > 0) {
const augmented = new Set(allFilePaths);
for (const h of headerPaths) augmented.add(h);
return resolveCImportTarget(targetRaw, fromFile, augmented);
}
return resolveCImportTarget(targetRaw, fromFile, allFilePaths);
},
expandsWildcardTo: (targetModuleScope, parsedFiles) =>
expandCWildcardNames(targetModuleScope, parsedFiles),
mergeBindings: (existing, incoming, scopeId) => cMergeBindings(existing, incoming, scopeId),
arityCompatibility: (callsite, def) => cArityCompatibility(def, callsite),
buildMro: (graph, parsedFiles, nodeLookup) =>
buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
populateOwners: (parsed: ParsedFile) => populateClassOwnedMembers(parsed),
isSuperReceiver: () => false,
// C is statically typed — disable field fallback heuristic
fieldFallbackOnMethodLookup: false,
// C has no method return types to propagate
propagatesReturnTypesAcrossImports: false,
// C #include brings in all symbols — enable global free call fallback
allowGlobalFreeCallFallback: true,
// C `static` functions have file-local (translation-unit) linkage —
// exclude them from global free-call fallback cross-file resolution.
isFileLocalDef: (def: SymbolDefinition) => {
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
return isStaticName(def.filePath, simple);
},
};

38
gitnexus/src/core/ingestion/languages/c/simple-hooks.ts Normal file
View file

@ -0,0 +1,38 @@
import type {
CaptureMatch,
ParsedImport,
Scope,
ScopeId,
ScopeTree,
TypeRef,
} from 'gitnexus-shared';
/**
* C binding scope: always use default auto-hoist (null).
* C has no self/receiver bindings that need special scoping.
*/
export function cBindingScopeFor(
_decl: CaptureMatch,
_innermost: Scope,
_tree: ScopeTree,
): ScopeId | null {
return null;
}
/**
* C import owning scope: always use default (null).
*/
export function cImportOwningScope(
_imp: ParsedImport,
_innermost: Scope,
_tree: ScopeTree,
): ScopeId | null {
return null;
}
/**
* C receiver binding: always null. C has no methods or receivers.
*/
export function cReceiverBinding(_functionScope: Scope): TypeRef | null {
return null;
}

64
gitnexus/src/core/ingestion/languages/c/static-linkage.ts Normal file
View file

@ -0,0 +1,64 @@
import type { ParsedFile, ScopeId, SymbolDefinition } from 'gitnexus-shared';
/**
* Per-file set of function names declared with `static` storage class.
* Populated during `emitCScopeCaptures` and consumed by `expandCWildcardNames`
* to exclude file-local symbols from cross-file wildcard import visibility.
*
* NOTE: module-level state, single-process-single-repo use only.
* For server-mode or multi-repo-in-one-process use cases, call
* `clearStaticNames()` at the start of each resolution pass to avoid
* stale static-linkage data from a previous invocation.
*
* Key: filePath, Value: Set of static function names.
*/
const staticNames = new Map<string, Set<string>>();
/** Record a symbol name as `static` (file-local linkage) for the given file. */
export function markStaticName(filePath: string, name: string): void {
let names = staticNames.get(filePath);
if (names === undefined) {
names = new Set<string>();
staticNames.set(filePath, names);
}
names.add(name);
}
/** Check whether a symbol name has `static` linkage in the given file. */
export function isStaticName(filePath: string, name: string): boolean {
return staticNames.get(filePath)?.has(name) ?? false;
}
/** Clear tracked static names (for testing). */
export function clearStaticNames(): void {
staticNames.clear();
}
/**
* Return the names visible through a C wildcard import (`#include`).
* All module-scope defs from the target file are visible EXCEPT those
* declared with `static` storage class (file-local linkage in C).
*/
export function expandCWildcardNames(
targetModuleScope: ScopeId,
parsedFiles: readonly ParsedFile[],
): readonly string[] {
const target = parsedFiles.find((p) => p.moduleScope === targetModuleScope);
if (target === undefined) return [];
const seen = new Set<string>();
const names: string[] = [];
for (const def of target.localDefs) {
const name = simpleName(def);
if (name === '') continue;
if (isStaticName(target.filePath, name)) continue;
if (seen.has(name)) continue;
seen.add(name);
names.push(name);
}
return names;
}
function simpleName(def: SymbolDefinition): string {
return def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
}

540
gitnexus/src/core/ingestion/languages/cpp/adl.ts Normal file
View file

@ -0,0 +1,540 @@
/**
* C++ argument-dependent lookup (ADL / Koenig lookup).
*
* When ordinary unqualified lookup fails for a free-call site, ADL also
* considers candidates declared in the **associated namespaces** of the
* call's argument types (ISO C++ `[basic.lookup.argdep]`). The canonical
* pattern V1 unlocks:
*
* namespace audit { struct Event; void record(Event); }
* namespace app { void run() { audit::Event e; record(e); } }
*
* Without ADL: `record(e)` is unresolved because `app::run` doesn't
* `using` anything. With V1 ADL: `audit::record` is discovered via
* `audit::Event`'s associated namespace.
*
* ## Current boundary
*
* The current implementation covers class-typed arguments (value, pointer,
* and reference) and template specializations with explicit type arguments:
* - `audit::Event e`, `audit::Event* p`, `audit::Event** pp`
* - `audit::Event& r`, `audit::Event&& rr`
* - `std::vector<audit::Event>` (template namespace + template-arg namespaces)
*
* V2 additionally walks class ancestors (via MRO), so base-class enclosing
* namespaces also contribute associated namespaces.
*
* **GitNexus approximation (not strict ISO C++ ADL):** passing a qualified
* function reference like `utils::worker` contributes `utils` to the associated
* set, enabling resolution of unqualified calls like `with_callback(utils::worker)`
* to `utils::with_callback`. Under ISO C++ `[basic.lookup.argdep]`, associated
* entities for function-type arguments come from the **parameter types and return
* type** of each function in the overload set — NOT the function's enclosing
* namespace. For `void worker()`, the standard-compliant associated set is empty.
* GitNexus instead contributes the enclosing namespace of any Function/Method
* def whose simple name matches, because it enables the dominant real-world ADL
* pattern at reasonable precision cost.
*
* For qualified refs (e.g. `utils::worker`) the namespace is confirmed via a
* workspace lookup (only contributed when a Function/Method named `worker` exists
* in `utils`). For unqualified refs the workspace is searched for any Function
* def with that simple name. Locally-declared function-pointer variables
* (e.g. `void (*g)()`) and function parameters are excluded from this path.
*
* ADL candidates are merged with ordinary unqualified-lookup candidates
* in the free-call fallback before overload narrowing.
*
* ## Parenthesized-name suppression
*
* `(f)(s)` MUST NOT trigger ADL — the parenthesized name forces ordinary
* lookup only. `captures.ts` records sites whose `function` child is a
* `parenthesized_expression` into `noAdlSites`; `pickCppAdlCandidates`
* short-circuits when the site key is present.
*
* ## State lifecycle
*
* Three module-level maps populated per pipeline invocation, cleared via
* `clearCppAdlState()` (called from `clearFileLocalNames`):
*
* - `argInfoBySite` — per-call-site argument shape (capture-time)
* - `noAdlSites` — call sites with parenthesized function (capture-time)
* - `classToNamespaceQualifiedName` — class def → its enclosing namespace
* qualified name (`populateCppAssociatedNamespaces` time)
*
* The class→namespace map uses qualified names (not scope IDs) because
* C++ namespaces are open: `namespace N { ... }` in file A and
* `namespace N { ... }` in file B produce two distinct Namespace scopes
* but logically share the same namespace. ADL must consider candidates
* declared in either file.
*/
import type { ParsedFile, ScopeId, SymbolDefinition } from 'gitnexus-shared';
import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
import { isCppInlineNamespaceScope } from './inline-namespaces.js';
/**
* Per-argument shape information collected at capture time. ADL fires for
* arguments where `simpleClassName !== ''`, including class pointers and
* references whose declarator chain resolves to a named class type.
* Free-function reference arguments use `functionRefText`.
*/
export interface CppAdlArgInfo {
/** Simple class-like type name (last segment of qualified name); empty
* for primitives, literals, function pointers, etc. */
readonly simpleClassName: string;
/** Template's own simple class-like name (e.g. `vector` for
* `std::vector<N::T>`), empty when arg type is not a template spec. */
readonly templateSimpleClassName: string;
/** Template's own enclosing namespace (dot-qualified, e.g. `std`), empty
* when unavailable / unqualified. */
readonly templateNamespace: string;
/** Class-like names extracted from explicit type template arguments,
* recursively bounded. */
readonly templateArgClassNames: readonly string[];
/** Enclosing namespaces extracted from explicit type template arguments,
* recursively bounded. */
readonly templateArgNamespaces: readonly string[];
/** When set, the arg is a potential free-function reference (not a locally-
* declared function-pointer variable or function parameter). Contains the
* identifier text as written in source (e.g. `"utils::worker"` or
* `"worker"`). GitNexus approximation: the function's enclosing namespace
* is contributed to the ADL associated set. For qualified refs a workspace
* lookup confirms a Function/Method with that simple name exists in the
* namespace before contributing; for unqualified refs every namespace
* containing a matching Function/Method def is contributed. */
readonly functionRefText?: string;
}
const argInfoBySite = new Map<string, readonly CppAdlArgInfo[]>();
const noAdlSites = new Set<string>();
const classToNamespaceQualifiedName = new Map<string, string>();
function siteKey(filePath: string, line: number, col: number): string {
return `${filePath}:${line}:${col}`;
}
/** Record per-call-site argument info. Called once per call site from
* `emitCppScopeCaptures`. */
export function markCppAdlSiteArgs(
filePath: string,
line: number,
col: number,
args: readonly CppAdlArgInfo[],
): void {
argInfoBySite.set(siteKey(filePath, line, col), args);
}
/** Mark a call site as ADL-suppressed (function child wrapped in
* `parenthesized_expression`, e.g. `(f)(s)`). */
export function markCppAdlSiteNoAdl(filePath: string, line: number, col: number): void {
noAdlSites.add(siteKey(filePath, line, col));
}
/** Clear ADL state. Called from `clearFileLocalNames` so all C++ resolver
* per-pipeline state is reset together. */
export function clearCppAdlState(): void {
argInfoBySite.clear();
noAdlSites.clear();
classToNamespaceQualifiedName.clear();
}
/**
* Walk `parsed.scopes` to record each Class def's enclosing namespace
* qualified name. Run from the cpp resolver's `populateOwners` hook so
* the index is available before any resolution pass consults it.
*
* Computes the namespace's qualified name by walking parent scope chain
* and looking up Namespace defs in each parent's `ownedDefs`. The
* resulting name is dot-joined (matching `populateClassOwnedMembers`'s
* dotted convention; conversion to `::` is consumer-internal).
*/
export function populateCppAssociatedNamespaces(parsed: ParsedFile): void {
const scopesById = new Map<ScopeId, (typeof parsed.scopes)[number]>();
for (const scope of parsed.scopes) scopesById.set(scope.id, scope);
for (const scope of parsed.scopes) {
if (scope.kind !== 'Class') continue;
const nsQName = computeEnclosingNamespaceQName(scope, scopesById);
if (nsQName === '') continue;
for (const def of scope.ownedDefs) {
if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface') continue;
classToNamespaceQualifiedName.set(def.nodeId, nsQName);
}
}
// Enum defs live in Namespace scopes directly (not inside Class scopes).
// Map each Enum def to its enclosing namespace so ADL on enum-typed
// arguments contributes the correct associated namespace.
for (const scope of parsed.scopes) {
if (scope.kind !== 'Namespace') continue;
const nsQName = computeNamespaceQName(scope, scopesById);
if (nsQName === '') continue;
for (const def of scope.ownedDefs) {
if (def.type !== 'Enum') continue;
classToNamespaceQualifiedName.set(def.nodeId, nsQName);
}
}
}
/**
* ADL candidate collector. Returns:
* - `readonly SymbolDefinition[]` — ADL candidates to merge with
* ordinary unqualified lookup candidates.
* - `undefined` — no ADL candidates.
*
* Fires only when:
* - the call site is not in `noAdlSites` (parenthesized form), AND
* - at least one argument resolves to a named class type (value,
* pointer, or reference; but not function pointer, literal, or primitive).
*/
export function pickCppAdlCandidates(
site: {
readonly name: string;
readonly atRange: { startLine: number; startCol: number };
},
callerParsed: ParsedFile,
scopes: ScopeResolutionIndexes,
parsedFiles: readonly ParsedFile[],
): readonly SymbolDefinition[] | undefined {
const key = siteKey(callerParsed.filePath, site.atRange.startLine, site.atRange.startCol);
if (noAdlSites.has(key)) return undefined;
const args = argInfoBySite.get(key);
if (args === undefined || args.length === 0) return undefined;
// Collect associated namespace QNames from every participating class-typed arg
// and from function-reference args.
const associatedNamespaces = new Set<string>();
for (const arg of args) {
collectAssociatedNamespacesForAdlArg(arg, scopes, associatedNamespaces);
if (arg.functionRefText !== undefined) {
collectFunctionRefNamespaces(arg.functionRefText, parsedFiles, associatedNamespaces);
}
}
if (associatedNamespaces.size === 0) return undefined;
// Walk every namespace scope in every parsed file; collect callable
// ownedDefs whose enclosing namespace matches one of the associated
// QNames AND whose simple name matches the call's name.
// ISO C++: inline namespaces are transparent — candidates in inline
// children of an associated namespace are also ADL-reachable.
const candidates: SymbolDefinition[] = [];
const seenKey = new Set<string>();
for (const parsed of parsedFiles) {
const scopesById = new Map<ScopeId, (typeof parsed.scopes)[number]>();
for (const sc of parsed.scopes) scopesById.set(sc.id, sc);
for (const scope of parsed.scopes) {
if (scope.kind !== 'Namespace') continue;
const qName = computeNamespaceQName(scope, scopesById);
if (!associatedNamespaces.has(qName)) {
// Check if this is an inline-namespace child of an associated NS.
// ISO C++ inline namespaces are transparent for ADL: if the outer
// namespace is in the associated set, candidates in the inline child
// are also reachable.
if (!isCppInlineNamespaceScope(scope.id)) continue;
const parentScope = scope.parent !== null ? scopesById.get(scope.parent) : undefined;
if (parentScope === undefined || parentScope.kind !== 'Namespace') continue;
const parentQName = computeNamespaceQName(parentScope, scopesById);
if (!associatedNamespaces.has(parentQName)) continue;
}
for (const def of scope.ownedDefs) {
if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor') {
continue;
}
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
if (simple !== site.name) continue;
// Dedup by nodeId — using normalized parameter-types as the key
// would collapse `process(int)`/`process(long)`-style overloads
// (both normalize to `['int']`) before
// `isOverloadAmbiguousAfterNormalization` can detect them.
if (seenKey.has(def.nodeId)) continue;
seenKey.add(def.nodeId);
candidates.push(def);
}
}
// ISO C++ `[basic.lookup.argdep]` §2: hidden friend functions declared
// inside a class body are visible via ADL when the class is an associated
// class. Scan Class scopes whose enclosing namespace is in the associated
// set for callable ownedDefs matching the call name. This enables the
// canonical "hidden friend" idiom:
// struct Foo { friend void swap(Foo&, Foo&) {} };
for (const scope of parsed.scopes) {
if (scope.kind !== 'Class') continue;
// Check if ANY class def in this scope has an associated namespace.
let isAssociatedClass = false;
for (const def of scope.ownedDefs) {
if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface') continue;
const nsQName = classToNamespaceQualifiedName.get(def.nodeId);
if (nsQName !== undefined && associatedNamespaces.has(nsQName)) {
isAssociatedClass = true;
break;
}
}
if (!isAssociatedClass) continue;
// Also scan Function scopes that are direct children of this class
// scope — friend function definitions create their own Function scope
// underneath the Class scope.
for (const childScope of parsed.scopes) {
if (childScope.parent !== scope.id) continue;
if (childScope.kind !== 'Function') continue;
for (const def of childScope.ownedDefs) {
if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor') {
continue;
}
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
if (simple !== site.name) continue;
if (seenKey.has(def.nodeId)) continue;
seenKey.add(def.nodeId);
candidates.push(def);
}
}
for (const def of scope.ownedDefs) {
if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor') {
continue;
}
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
if (simple !== site.name) continue;
if (seenKey.has(def.nodeId)) continue;
seenKey.add(def.nodeId);
candidates.push(def);
}
}
}
if (candidates.length === 0) return undefined;
return candidates;
}
function collectAssociatedNamespacesForAdlArg(
arg: CppAdlArgInfo,
scopes: ScopeResolutionIndexes,
associatedNamespaces: Set<string>,
): void {
// For template args this may be the template name itself (e.g. `vector`);
// simple-name lookup can match project classes with the same name (known
// V1/V2 simplification).
addAssociatedNamespaceForClassName(arg.simpleClassName, scopes, associatedNamespaces);
// Includes template-owner namespaces (e.g. `std` in std::vector<T>). If
// that surfaces extra candidates, merged-candidate overload narrowing in
// free-call-fallback suppresses arbitrary edge emission.
if (arg.templateNamespace.length > 0) associatedNamespaces.add(arg.templateNamespace);
for (const ns of arg.templateArgNamespaces) {
if (ns.length > 0) associatedNamespaces.add(ns);
}
for (const className of arg.templateArgClassNames) {
addAssociatedNamespaceForClassName(className, scopes, associatedNamespaces);
}
}
function addAssociatedNamespaceForClassName(
simpleClassName: string,
scopes: ScopeResolutionIndexes,
associatedNamespaces: Set<string>,
): void {
if (simpleClassName.length === 0) return;
const classLookup = findCppClassDefBySimpleName(simpleClassName, scopes);
if (classLookup === undefined) return;
const { classDef, ambiguous } = classLookup;
const nsQName = classToNamespaceQualifiedName.get(classDef.nodeId);
if (nsQName !== undefined) associatedNamespaces.add(nsQName);
// Preserve V1 collision behavior for the direct class namespace, but avoid
// amplifying a same-simple-name collision by walking an arbitrary class's
// full MRO chain.
if (ambiguous) return;
for (const ancestorDefId of scopes.methodDispatch.mroFor(classDef.nodeId)) {
const ancestorNsQName = classToNamespaceQualifiedName.get(ancestorDefId);
if (ancestorNsQName !== undefined) associatedNamespaces.add(ancestorNsQName);
}
}
/** Walk upward from a Class scope, finding the innermost enclosing
* Namespace scope, and return that namespace's qualified name (dot-
* joined, outermost-first). Returns '' when the class has no enclosing
* namespace (e.g., declared at translation-unit scope). */
function computeEnclosingNamespaceQName(
classScope: { readonly parent: ScopeId | null },
scopesById: ReadonlyMap<
ScopeId,
{
readonly parent: ScopeId | null;
readonly kind: string;
readonly ownedDefs: readonly SymbolDefinition[];
}
>,
): string {
let parentId: ScopeId | null = classScope.parent;
while (parentId !== null) {
const parent = scopesById.get(parentId);
if (parent === undefined) return '';
if (parent.kind === 'Namespace') {
return computeNamespaceQName(parent, scopesById);
}
parentId = parent.parent;
}
return '';
}
/** Walk upward from a Namespace scope collecting each enclosing
* Namespace's simple name (innermost last). Returns the dot-joined
* qualified name (e.g., `outer.inner`). The namespace's own def lives
* in its OWN scope's `ownedDefs` (the C++ extractor stamps the
* namespace-decl def into the namespace scope itself, not the parent
* module scope). */
function computeNamespaceQName(
nsScope: { readonly parent: ScopeId | null; readonly ownedDefs: readonly SymbolDefinition[] },
scopesById: ReadonlyMap<
ScopeId,
{
readonly parent: ScopeId | null;
readonly kind: string;
readonly ownedDefs: readonly SymbolDefinition[];
}
>,
): string {
const segments: string[] = [];
let currentId: ScopeId | null = nsScope.parent;
let current:
| { readonly parent: ScopeId | null; readonly ownedDefs: readonly SymbolDefinition[] }
| undefined = nsScope;
// Outer guard against pathological cycles in malformed scope trees.
let safety = 64;
while (current !== undefined && safety-- > 0) {
const nsDef = findNamespaceDefInScope(current);
if (nsDef === undefined) {
// No name found — bail out. Returning a partial QName would risk
// false ADL associations.
return '';
}
const simple = nsDef.qualifiedName?.split('.').pop() ?? nsDef.qualifiedName ?? '';
segments.unshift(simple);
// Walk up to next enclosing namespace (skipping non-namespace parents).
let nextId: ScopeId | null = currentId;
let nextNs: typeof current | undefined;
while (nextId !== null) {
const nx = scopesById.get(nextId);
if (nx === undefined) break;
if (nx.kind === 'Namespace') {
nextNs = nx;
currentId = nx.parent;
break;
}
nextId = nx.parent;
}
current = nextNs;
}
return segments.join('.');
}
/** Find the Namespace def attached to this scope (the namespace's own
* decl, stamped into its own `ownedDefs` by the C++ extractor). Returns
* the first Namespace-type def encountered — for normal C++ the scope
* carries exactly one Namespace-typed self def. */
function findNamespaceDefInScope(scope: {
readonly ownedDefs: readonly SymbolDefinition[];
}): SymbolDefinition | undefined {
for (const def of scope.ownedDefs) {
if (def.type === 'Namespace') return def;
}
return undefined;
}
/** Find a class-like or enum def by simple name across the workspace.
* V1 still arbitrary-picks the first match on collisions (multiple defs
* share the simple name), but reports the collision so callers can avoid
* amplifying that uncertainty (for example by skipping MRO expansion).
* C++ ADL strictness would require full type-driven lookup.
*
* ISO C++ `[basic.lookup.argdep]` §2: enumerations contribute their
* enclosing namespace to the associated set, just like class types. */
function findCppClassDefBySimpleName(
simpleName: string,
scopes: ScopeResolutionIndexes,
): { classDef: SymbolDefinition; ambiguous: boolean } | undefined {
let firstMatch: SymbolDefinition | undefined;
for (const def of scopes.defs.byId.values()) {
if (
def.type !== 'Class' &&
def.type !== 'Struct' &&
def.type !== 'Interface' &&
def.type !== 'Enum'
)
continue;
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
if (simple !== simpleName) continue;
if (firstMatch === undefined) {
firstMatch = def;
continue;
}
return { classDef: firstMatch, ambiguous: true };
}
if (firstMatch === undefined) return undefined;
return { classDef: firstMatch, ambiguous: false };
}
/**
* Contribute associated namespaces for a function-reference argument.
*
* - **Qualified refs** (`utils::worker`, `outer::inner::fn`): the namespace
* is extracted from the qualifier text (converting `::` to `.` for dot-joined
* QName matching). A workspace lookup then **verifies** that a Function or
* Method def named `worker` (the simple name after the last `::`) actually
* exists in the extracted namespace. This prevents false positives from
* namespace-qualified variables, enum values, and static data members, which
* also produce `qualified_identifier` AST nodes in tree-sitter-cpp (the
* AST node type alone does not distinguish functions from non-function names).
* - **Unqualified refs** (`worker`): the workspace is searched for any
* Function/Method def whose simple name matches. Every distinct enclosing
* namespace found is added — overloads across the same namespace produce
* a single entry; GitNexus does not select a specific overload at this stage.
*/
function collectFunctionRefNamespaces(
refText: string,
parsedFiles: readonly ParsedFile[],
out: Set<string>,
): void {
const colonIdx = refText.lastIndexOf('::');
if (colonIdx !== -1) {
// Qualified ref: extract namespace prefix and normalise :: → dot notation.
const nsText = refText.slice(0, colonIdx).replace(/::/g, '.');
if (nsText === '') return;
const simpleName = refText.slice(colonIdx + 2);
// Verify that a Function/Method named `simpleName` exists in `nsText`.
// Without this guard every `a::b` qualified_identifier arg (variable,
// enum value, static member, type alias) would blindly contribute `a`
// to the associated set and risk a false-positive CALLS edge.
for (const parsed of parsedFiles) {
const scopesById = new Map<ScopeId, (typeof parsed.scopes)[number]>();
for (const sc of parsed.scopes) scopesById.set(sc.id, sc);
for (const scope of parsed.scopes) {
if (scope.kind !== 'Namespace') continue;
if (computeNamespaceQName(scope, scopesById) !== nsText) continue;
for (const def of scope.ownedDefs) {
if (def.type !== 'Function' && def.type !== 'Method') continue;
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
if (simple === simpleName) {
out.add(nsText);
return; // Namespace confirmed; no need to scan further files.
}
}
}
}
return;
}
// Unqualified: search all namespace scopes for a Function def with this
// simple name and contribute its enclosing namespace.
for (const parsed of parsedFiles) {
const scopesById = new Map<ScopeId, (typeof parsed.scopes)[number]>();
for (const sc of parsed.scopes) scopesById.set(sc.id, sc);
for (const scope of parsed.scopes) {
if (scope.kind !== 'Namespace') continue;
for (const def of scope.ownedDefs) {
if (def.type !== 'Function' && def.type !== 'Method') continue;
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
if (simple !== refText) continue;
const nsQName = computeNamespaceQName(scope, scopesById);
if (nsQName !== '') out.add(nsQName);
}
}
}
}

185
gitnexus/src/core/ingestion/languages/cpp/arity-metadata.ts Normal file
View file

@ -0,0 +1,185 @@
import type { SyntaxNode } from '../../utils/ast-helpers.js';
export interface CppArityInfo {
parameterCount?: number;
requiredParameterCount?: number;
parameterTypes?: string[];
}
/**
* Compute declaration arity from a C++ function definition or declaration node.
* Extends the C arity computation with support for:
* - optional_parameter_declaration (default parameters)
* - variadic_parameter_declaration / parameter packs
* - (void) explicit zero-parameter form
*/
export function computeCppDeclarationArity(node: SyntaxNode): CppArityInfo {
const funcDecl = findFuncDeclarator(node);
if (funcDecl === null) return {};
const paramList = funcDecl.childForFieldName('parameters');
if (paramList === null) return {};
const params: SyntaxNode[] = [];
// Track whether a C-style variadic `...` anonymous token appears.
// tree-sitter-cpp emits `...` as an anonymous (non-named) child of
// parameter_list, not as `variadic_parameter`.
let hasEllipsis = false;
for (let i = 0; i < paramList.childCount; i++) {
const child = paramList.child(i);
if (child === null) continue;
if (
child.type === 'parameter_declaration' ||
child.type === 'optional_parameter_declaration' ||
child.type === 'variadic_parameter' ||
child.type === 'variadic_parameter_declaration'
) {
params.push(child);
} else if (child.type === '...' || (!child.isNamed && child.text === '...')) {
hasEllipsis = true;
}
}
// Empty parameter list: C++ `void foo()` means zero params (unlike C)
if (params.length === 0 && !hasEllipsis) {
return { parameterCount: 0, requiredParameterCount: 0, parameterTypes: [] };
}
// (void) means zero parameters
if (params.length === 1 && params[0].type === 'parameter_declaration') {
const typeNode = params[0].childForFieldName('type');
const hasDeclarator = params[0].childForFieldName('declarator') !== null;
if (typeNode !== null && typeNode.text === 'void' && !hasDeclarator) {
return { parameterCount: 0, requiredParameterCount: 0, parameterTypes: [] };
}
}
// C-style variadic: `void foo(int x, ...)` — the `...` is an anonymous
// token in tree-sitter-cpp, detected via `hasEllipsis` above.
// C++ parameter packs: `template<typename... Ts> void foo(Ts... args)` —
// detected as `variadic_parameter_declaration`.
const isVariadic =
hasEllipsis ||
params.some(
(p) => p.type === 'variadic_parameter' || p.type === 'variadic_parameter_declaration',
);
const optionalCount = params.filter((p) => p.type === 'optional_parameter_declaration').length;
const requiredCount = params.filter(
(p) =>
p.type === 'parameter_declaration' ||
// variadic_parameter_declaration with a name is a parameter pack — counts as one
p.type === 'variadic_parameter_declaration',
).length;
const totalNonVariadic = requiredCount + optionalCount;
const types: string[] = [];
for (const p of params) {
if (p.type === 'variadic_parameter') {
types.push('...');
} else if (p.type === 'variadic_parameter_declaration') {
// Parameter pack: treated as variadic
types.push('...');
} else {
const typeNode = p.childForFieldName('type');
types.push(normalizeCppParamType(typeNode?.text ?? 'unknown'));
}
}
// Append '...' for C-style variadic if not already in types
if (hasEllipsis && !types.includes('...')) {
types.push('...');
}
return {
parameterCount: isVariadic ? undefined : totalNonVariadic,
requiredParameterCount: requiredCount,
parameterTypes: types,
};
}
/**
* Compute call-site arity from a call_expression node.
*/
export function computeCppCallArity(node: SyntaxNode): number {
const argList = node.childForFieldName('arguments');
if (argList === null) return 0;
let count = 0;
for (let i = 0; i < argList.childCount; i++) {
const child = argList.child(i);
if (child === null) continue;
if (child.type !== ',' && child.type !== '(' && child.type !== ')') {
count++;
}
}
return count;
}
/**
* Normalize a C++ parameter type for overload disambiguation.
* Maps common qualified/aliased types to their canonical short forms
* so that `narrowOverloadCandidates` can match against literal-inferred
* argument types (e.g. `inferCppLiteralType` returns `'string'` for
* string literals, not `'std::string'`).
*/
export function normalizeCppParamType(raw: string): string {
let t = raw.trim();
// Strip const, volatile, etc.
t = t.replace(/\b(const|volatile|restrict|mutable|constexpr)\b/g, '').trim();
// Strip reference/pointer markers
t = t.replace(/[&*]+\s*$/, '').trim();
// Strip template parameters (loop handles nested: Map<List<int>> → Map)
while (t.includes('<')) {
const stripped = t.replace(/<[^<>]*>/g, '');
if (stripped === t) break; // avoid infinite loop on malformed input
t = stripped;
}
t = t.trim();
// Map std:: types to canonical short forms
const STD_MAP: Record<string, string> = {
'std::string': 'string',
'std::wstring': 'string',
'std::string_view': 'string',
string: 'string',
char: 'char',
int: 'int',
long: 'int',
short: 'int',
unsigned: 'int',
'unsigned int': 'int',
'long long': 'int',
size_t: 'int',
'std::size_t': 'int',
float: 'double',
double: 'double',
bool: 'bool',
nullptr_t: 'null',
'std::nullptr_t': 'null',
};
return STD_MAP[t] ?? t;
}
function findFuncDeclarator(node: SyntaxNode): SyntaxNode | null {
let decl = node.childForFieldName('declarator');
if (decl === null) {
for (let i = 0; i < node.childCount; i++) {
const c = node.child(i);
if (c?.type === 'function_declarator') return c;
}
return null;
}
// Unwrap pointer_declarator / reference_declarator
while (decl.type === 'pointer_declarator' || decl.type === 'reference_declarator') {
const next = decl.childForFieldName('declarator');
if (next === null) {
// reference_declarator may not use field name
for (let i = 0; i < decl.childCount; i++) {
const c = decl.child(i);
if (c?.type === 'function_declarator') return c;
}
break;
}
decl = next;
}
if (decl.type === 'function_declarator') return decl;
return null;
}

38
gitnexus/src/core/ingestion/languages/cpp/arity.ts Normal file
View file

@ -0,0 +1,38 @@
import type { Callsite, SymbolDefinition } from 'gitnexus-shared';
/**
* C++ arity compatibility: supports overloading and default parameters.
*
* Unlike C (no overloading, exact match only), C++ has:
* - Overloaded functions (same name, different signatures)
* - Default parameters (requiredParameterCount < parameterCount)
* - Variadic functions (C-style `...`)
* - Parameter packs (V1: treated as variadic)
* - Templates: arity check on non-template params; SFINAE / `requires`
* constraints are filtered separately via `constraintCompatibility`
* (see `constraint-filter.ts` and issue #1579). Type-argument generic
* substitution (`List<T>` ≡ `List<U>`) remains out of V1 scope.
*
* Verdict:
* - 'compatible': callsite.arity fits within [required, total] range
* - 'incompatible': callsite.arity is outside the valid range
* - 'unknown': insufficient metadata to determine
*/
export function cppArityCompatibility(
def: SymbolDefinition,
callsite: Callsite,
): 'compatible' | 'unknown' | 'incompatible' {
const max = def.parameterCount;
const min = def.requiredParameterCount;
if (max === undefined && min === undefined) return 'unknown';
if (!Number.isFinite(callsite.arity) || callsite.arity < 0) return 'unknown';
const variadic = def.parameterTypes?.some((t) => t === '...') ?? false;
// Too few arguments: less than the minimum required
if (min !== undefined && callsite.arity < min) return 'incompatible';
// Too many arguments: more than the maximum and not variadic
if (max !== undefined && callsite.arity > max && !variadic) return 'incompatible';
return 'compatible';
}

1278
gitnexus/src/core/ingestion/languages/cpp/captures.ts Normal file
View file

File diff suppressed because it is too large Load diff

335
gitnexus/src/core/ingestion/languages/cpp/constraint-extractor.ts Normal file
View file

@ -0,0 +1,335 @@
/**
* Extract C++ template constraint expressions for SFINAE-aware overload
* narrowing (issue #1579). Recognizes 3 AST shapes:
*
* F1 — unqualified non-type template param default:
* `template<class T, enable_if_t<P, int> = 0> void f(T);`
* F2 — `std::`-qualified variant (canonical ticket form):
* `template<class T, std::enable_if_t<P, int> = 0> void f(T);`
* F4 — C++20 leading requires-clause:
* `template<class T> requires P void f(T);`
*
* Deferred (return `{kind:'unknown'}`):
* F3 — void-default `typename = enable_if_t<P>` (cppref labels this
* `/* WRONG *\/` because adjacent overloads collapse to redeclarations)
* F5 — trailing requires (`void f(T) requires P;`)
* `requires_expression` blocks (`requires { typename T::U; }`)
* `decltype(...)`, fold-expressions, user-defined `_v` aliases.
*
* The output payload is opaque to shared code — only
* `constraint-filter.ts` consumes it. See ISO `[temp.constr.normal]` /
* `<https://en.cppreference.com/w/cpp/language/constraints>` for the
* normalization the Kleene 3-valued evaluator implements.
*/
import type { SyntaxNode } from '../../utils/ast-helpers.js';
export type ConstraintExpr =
| { readonly kind: 'atomic'; readonly name: string; readonly args: readonly string[] }
| { readonly kind: 'and'; readonly children: readonly ConstraintExpr[] }
| { readonly kind: 'or'; readonly children: readonly ConstraintExpr[] }
| { readonly kind: 'not'; readonly child: ConstraintExpr }
| { readonly kind: 'unknown' };
export interface CppConstraintPayload {
/** Ordered template parameter names (type-params only — non-type defaults
* carrying enable_if predicates are folded into `expr`). */
readonly templateParams: readonly string[];
/**
* Mapping from each template parameter name to the call-site argument
* index where its deduced type lives. Computed by scanning the function's
* parameter list for the first parameter whose type is the bare template
* parameter name (or template-typed by it). Missing entries → 'unknown'
* verdict at evaluation time.
*/
readonly paramArgIndex: { readonly [paramName: string]: number };
/** Root constraint expression. When multiple constraints (multiple
* enable_if defaults, requires clause, etc.) are present they are
* implicitly conjoined under a top-level `and` node. */
readonly expr: ConstraintExpr;
}
/**
* Walk a `template_declaration` AST node and extract its constraint
* payload. Caller is responsible for passing the OUTER `template_declaration`
* — for class-member template functions, that means the enclosing
* template_declaration of the class OR of the method, whichever
* directly precedes the function definition.
*
* Returns `undefined` when the template_declaration declares no
* constraints worth tracking (no enable_if default, no requires clause).
* Returns a payload whose `expr.kind === 'unknown'` when constraints are
* present but the extractor cannot model them — monotonicity guarantees
* the filter keeps the candidate in that case.
*/
export function extractCppTemplateConstraints(
templateDecl: SyntaxNode,
funcDeclarator: SyntaxNode | null,
): CppConstraintPayload | undefined {
const paramList = childOfType(templateDecl, 'template_parameter_list');
if (paramList === null) return undefined;
const templateParams: string[] = [];
const exprs: ConstraintExpr[] = [];
for (let i = 0; i < paramList.namedChildCount; i++) {
const param = paramList.namedChild(i);
if (param === null) continue;
if (
param.type === 'type_parameter_declaration' ||
param.type === 'optional_type_parameter_declaration' ||
param.type === 'variadic_type_parameter_declaration'
) {
const id = firstDescendantOfType(param, 'type_identifier');
if (id !== null) templateParams.push(id.text);
continue;
}
// Non-type parameter — F1 / F2 default-value carries the enable_if
// predicate. Shape: `optional_parameter_declaration` with field
// `default_value`, whose value is a `template_type` named
// `enable_if_t` (F1) or a qualified version (F2).
if (param.type === 'optional_parameter_declaration') {
const defaultVal = param.childForFieldName('default_value');
const typeNode = param.childForFieldName('type');
const candidate = extractEnableIfPredicate(typeNode);
if (candidate !== undefined) {
exprs.push(candidate);
} else if (defaultVal !== null) {
// Default-value-as-predicate not yet supported. Bail conservatively.
exprs.push({ kind: 'unknown' });
}
}
}
// F4 — C++20 leading `requires` clause. Tree-sitter-cpp exposes it as a
// `requires_clause` child of `template_declaration` (sibling of the
// template_parameter_list).
const requiresClause = childOfType(templateDecl, 'requires_clause');
if (requiresClause !== null) {
const parsed = parseRequiresClause(requiresClause);
if (parsed !== undefined) exprs.push(parsed);
}
if (templateParams.length === 0 && exprs.length === 0) return undefined;
const paramArgIndex = buildParamArgIndex(templateParams, funcDeclarator);
const expr: ConstraintExpr =
exprs.length === 0
? { kind: 'unknown' }
: exprs.length === 1
? exprs[0]
: { kind: 'and', children: exprs };
return { templateParams, paramArgIndex, expr };
}
/**
* Inspect a non-type template parameter's declared type to see whether
* it's `enable_if_t<P, T>` (F1) or `std::enable_if_t<P, T>` (F2). When
* matched, extract the predicate `P` and return it as a `ConstraintExpr`.
*
* Returns undefined when the parameter's type is not enable_if (so the
* caller can decide whether to bail or ignore).
*/
function extractEnableIfPredicate(typeNode: SyntaxNode | null): ConstraintExpr | undefined {
if (typeNode === null) return undefined;
// Unwrap a type_descriptor wrapper (when present).
let t: SyntaxNode | null = typeNode;
if (t.type === 'type_descriptor') {
t = t.childForFieldName('type') ?? firstDescendantOfType(t, 'template_type');
}
// F2 shape: tree-sitter-cpp models `std::enable_if_t<...>` as
// `qualified_identifier` whose `name` field is the `template_type`.
// F1 shape (unqualified `enable_if_t<...>`) is `template_type` directly.
if (t !== null && t.type === 'qualified_identifier') {
const inner = t.childForFieldName('name') ?? firstDescendantOfType(t, 'template_type');
if (inner !== null && inner.type === 'template_type') {
t = inner;
}
}
if (t === null || t.type !== 'template_type') return undefined;
const nameNode = t.childForFieldName('name');
if (nameNode === null) return undefined;
const tail = stripQualifiedPrefix(nameNode.text);
if (tail !== 'enable_if_t' && tail !== 'enable_if') return undefined;
// Predicate is the first template argument of enable_if_t.
const argList = t.childForFieldName('arguments') ?? childOfType(t, 'template_argument_list');
if (argList === null) return { kind: 'unknown' };
for (let i = 0; i < argList.namedChildCount; i++) {
const arg = argList.namedChild(i);
if (arg === null) continue;
if (arg.type !== 'type_descriptor') continue;
const inner = arg.childForFieldName('type') ?? arg.namedChild(0);
if (inner === null) continue;
return parseAtomicOrBoolean(inner);
}
return { kind: 'unknown' };
}
/** Parse a requires-clause body. The body is a binary or unary expression
* over atomic predicates (variable templates like `is_integral_v<T>`). */
function parseRequiresClause(requiresClause: SyntaxNode): ConstraintExpr | undefined {
// tree-sitter-cpp exposes the expression as a named child or via a
// `constraint` field. Probe both.
let expr: SyntaxNode | null = requiresClause.childForFieldName('constraint');
if (expr === null) {
for (let i = 0; i < requiresClause.namedChildCount; i++) {
const c = requiresClause.namedChild(i);
if (c === null) continue;
// Skip the `requires` keyword token.
if (c.type === 'requires') continue;
expr = c;
break;
}
}
if (expr === null) return undefined;
return parseAtomicOrBoolean(expr);
}
/**
* Recursively parse a constraint sub-expression. Recognizes:
* - `template_type` / `template_function` named `<predicate>_v` → atomic
* - binary_expression with `&&` / `||` → conjunction / disjunction
* - unary_expression with `!` → negation
* - parenthesized_expression → unwrap
* - anything else → `{kind:'unknown'}` (monotonicity-safe)
*
* `requires_expression` blocks intentionally fall through to 'unknown'
* — they need substitution semantics we don't model in V1.
*/
function parseAtomicOrBoolean(node: SyntaxNode): ConstraintExpr {
// Unwrap parentheses.
if (node.type === 'parenthesized_expression') {
const inner = node.namedChild(0);
return inner === null ? { kind: 'unknown' } : parseAtomicOrBoolean(inner);
}
// Boolean composition.
if (node.type === 'binary_expression') {
const left = node.childForFieldName('left');
const right = node.childForFieldName('right');
const opNode = node.childForFieldName('operator');
if (left !== null && right !== null && opNode !== null) {
const op = opNode.text;
const l = parseAtomicOrBoolean(left);
const r = parseAtomicOrBoolean(right);
if (op === '&&') return { kind: 'and', children: [l, r] };
if (op === '||') return { kind: 'or', children: [l, r] };
}
return { kind: 'unknown' };
}
if (node.type === 'unary_expression') {
const opNode = node.childForFieldName('operator') ?? node.namedChild(0);
const arg = node.childForFieldName('argument') ?? node.namedChild(1) ?? node.namedChild(0);
if (opNode !== null && opNode.text === '!' && arg !== null && arg !== opNode) {
return { kind: 'not', child: parseAtomicOrBoolean(arg) };
}
return { kind: 'unknown' };
}
// Atomic predicate — `template_type` is the typical shape for variable
// templates like `is_integral_v<T>`. Some grammar variants surface it as
// `template_function` or via a `qualified_identifier` wrapper.
if (node.type === 'template_type' || node.type === 'template_function') {
return parseAtomicTemplate(node);
}
if (node.type === 'qualified_identifier') {
// `std::is_integral_v<T>` shape (without template_type wrapping).
const inner = node.childForFieldName('name');
if (inner !== null && (inner.type === 'template_type' || inner.type === 'template_function')) {
return parseAtomicTemplate(inner);
}
return { kind: 'unknown' };
}
// `requires { typename T::U; }` blocks and decltype: out of V1 scope.
return { kind: 'unknown' };
}
function parseAtomicTemplate(t: SyntaxNode): ConstraintExpr {
const nameNode = t.childForFieldName('name');
if (nameNode === null) return { kind: 'unknown' };
const name = stripQualifiedPrefix(nameNode.text);
const argList = t.childForFieldName('arguments') ?? childOfType(t, 'template_argument_list');
const args: string[] = [];
if (argList !== null) {
for (let i = 0; i < argList.namedChildCount; i++) {
const arg = argList.namedChild(i);
if (arg === null) continue;
if (arg.type !== 'type_descriptor') continue;
const inner = arg.childForFieldName('type') ?? arg.namedChild(0);
if (inner === null) continue;
// For Tier-A predicates the args are bare template-parameter names
// (`T`, `U`). Anything more elaborate is bailed via 'unknown' at the
// top level if needed; here we just record the textual identifier.
const id =
inner.type === 'type_identifier' ? inner : firstDescendantOfType(inner, 'type_identifier');
args.push(id !== null ? id.text : inner.text);
}
}
return { kind: 'atomic', name, args };
}
/** Build a `paramName → call-site argument index` map by scanning the
* function's parameter list for parameters typed by each template param. */
function buildParamArgIndex(
templateParams: readonly string[],
funcDeclarator: SyntaxNode | null,
): { [paramName: string]: number } {
const out: { [paramName: string]: number } = {};
if (funcDeclarator === null || templateParams.length === 0) return out;
const paramList = funcDeclarator.childForFieldName('parameters');
if (paramList === null) return out;
let argIdx = 0;
for (let i = 0; i < paramList.childCount; i++) {
const p = paramList.child(i);
if (p === null) continue;
if (
p.type !== 'parameter_declaration' &&
p.type !== 'optional_parameter_declaration' &&
p.type !== 'variadic_parameter_declaration'
) {
continue;
}
const typeNode = p.childForFieldName('type');
if (typeNode !== null) {
const tname = bareTypeIdentifier(typeNode);
if (tname !== null && templateParams.includes(tname) && !(tname in out)) {
out[tname] = argIdx;
}
}
argIdx++;
}
return out;
}
function bareTypeIdentifier(typeNode: SyntaxNode): string | null {
if (typeNode.type === 'type_identifier') return typeNode.text;
// Allow `T const`, `T&`, `T*` shapes — the inner type_identifier still wins.
const id = firstDescendantOfType(typeNode, 'type_identifier');
return id !== null ? id.text : null;
}
function stripQualifiedPrefix(text: string): string {
const idx = text.lastIndexOf('::');
return idx >= 0 ? text.slice(idx + 2) : text;
}
function childOfType(node: SyntaxNode, type: string): SyntaxNode | null {
for (let i = 0; i < node.childCount; i++) {
const c = node.child(i);
if (c !== null && c.type === type) return c;
}
return null;
}
function firstDescendantOfType(node: SyntaxNode, type: string): SyntaxNode | null {
if (node.type === type) return node;
for (let i = 0; i < node.childCount; i++) {
const c = node.child(i);
if (c === null) continue;
const hit = firstDescendantOfType(c, type);
if (hit !== null) return hit;
}
return null;
}

147
gitnexus/src/core/ingestion/languages/cpp/constraint-filter.ts Normal file
View file

@ -0,0 +1,147 @@
/**
* Kleene 3-valued evaluator + curated 4-predicate registry +
* `cppConstraintCompatibility` hook export for SFINAE / `requires`-clause
* filtering (issue #1579).
*
* Semantics:
* - `'incompatible'` → predicate provably fails for these argumentTypes
* (ISO `[temp.constr.atomic]` "not satisfied")
* - `'compatible'` → predicate provably holds
* - `'unknown'` → cannot decide (missing arg-type info, predicate
* not in registry, AST shape bailed during extraction). The shared
* filter keeps the candidate on `'unknown'` — monotonicity guarantee.
*
* Kleene rules (extension of ISO's 2-valued short-circuit conjunction in
* `<https://en.cppreference.com/w/cpp/language/constraints>`):
* AND: incompatible if any child incompatible; compatible iff all
* children compatible; otherwise unknown.
* OR: compatible if any child compatible; incompatible iff all
* children incompatible; otherwise unknown.
* NOT: flip compatible↔incompatible; pass through unknown.
*/
import type { ArityVerdict, Callsite, ConstraintContext, SymbolDefinition } from 'gitnexus-shared';
import { classifyType, type TypeClass } from './type-classifier.js';
import type { ConstraintExpr, CppConstraintPayload } from './constraint-extractor.js';
type AtomicEvaluator = (argClasses: readonly TypeClass[]) => ArityVerdict;
/**
* Curated Tier-A predicate registry — the four canonical
* `<type_traits>` variable templates whose truth tables are closed-form
* over our coarse `TypeClass` enum.
*
* Deferred predicates that need a cv/ref/pointer sidecar on
* `normalizeCppParamType` (today the normalizer strips those markers
* before storage) live in #1579 as one-line follow-up adds.
*/
// ISO `<type_traits>` treats `bool`, `char`, and the signed/unsigned char
// variants as integral types (§21.3.4 Table 48), so `is_integral_v<bool>`
// and `is_integral_v<char>` must both yield `true`. We keep the `TypeClass`
// enum precise (separate `'bool'` / `'char'` buckets) so that
// `is_same_v<bool, int>` still resolves to `'incompatible'`; the integral-
// family widening lives here in the predicate evaluators instead.
function isIntegralClass(c: TypeClass | undefined): boolean {
return c === 'integral' || c === 'bool' || c === 'char';
}
const REGISTRY = new Map<string, AtomicEvaluator>([
['is_integral_v', (cls) => verdictFromBool(isIntegralClass(cls[0]), cls)],
['is_floating_point_v', (cls) => verdictFromBool(cls[0] === 'floating', cls)],
[
'is_arithmetic_v',
(cls) => verdictFromBool(isIntegralClass(cls[0]) || cls[0] === 'floating', cls),
],
// NOTE: cv-qualifiers are stripped by `normalizeCppParamType` before the
// type token reaches `classifyType`, so `is_same_v<const T, T>` returns
// `'compatible'` instead of the ISO-correct `false`. Tracked under the
// cv-sidecar refactor in #1579's "Out of scope" list; until that lands
// this approximation matches the common `is_same_v<T, ConcreteType>`
// dispatch idiom and silently degrades on cv-distinct compares.
[
'is_same_v',
(cls) => {
if (cls.length < 2 || cls[0] === 'unknown' || cls[1] === 'unknown') return 'unknown';
return cls[0] === cls[1] ? 'compatible' : 'incompatible';
},
],
]);
function verdictFromBool(predicate: boolean, cls: readonly TypeClass[]): ArityVerdict {
if (cls[0] === 'unknown') return 'unknown';
return predicate ? 'compatible' : 'incompatible';
}
/** Public surface — registered as `ScopeResolver.constraintCompatibility`. */
export function cppConstraintCompatibility(
_callsite: Callsite,
def: SymbolDefinition,
ctx: ConstraintContext,
): ArityVerdict {
const payload = def.templateConstraints as CppConstraintPayload | undefined;
if (payload === undefined) return 'unknown';
return evaluate(payload.expr, payload, ctx);
}
function evaluate(
expr: ConstraintExpr,
payload: CppConstraintPayload,
ctx: ConstraintContext,
): ArityVerdict {
switch (expr.kind) {
case 'unknown':
return 'unknown';
case 'atomic': {
const evaluator = REGISTRY.get(expr.name);
if (evaluator === undefined) return 'unknown';
const classes = expr.args.map((paramName) => {
const argIdx = payload.paramArgIndex[paramName];
if (argIdx === undefined) return 'unknown' as TypeClass;
const token = ctx.argumentTypes?.[argIdx];
if (token === undefined || token === '') return 'unknown' as TypeClass;
return classifyType(token);
});
return evaluator(classes);
}
case 'and': {
let result: ArityVerdict = 'compatible';
for (const child of expr.children) {
const v = evaluate(child, payload, ctx);
if (v === 'incompatible') return 'incompatible';
if (v === 'unknown') result = 'unknown';
}
return result;
}
case 'or': {
let result: ArityVerdict = 'incompatible';
for (const child of expr.children) {
const v = evaluate(child, payload, ctx);
if (v === 'compatible') return 'compatible';
if (v === 'unknown') result = 'unknown';
}
return result;
}
case 'not': {
const v = evaluate(expr.child, payload, ctx);
if (v === 'compatible') return 'incompatible';
if (v === 'incompatible') return 'compatible';
return 'unknown';
}
}
}
/** Exposed for unit tests — lets `cpp-constraint.test.ts` assert
* `expect(getRegistrySize()).toBe(4)` without exporting the Map itself. */
export function getRegistrySize(): number {
return REGISTRY.size;
}
/** Exposed for unit tests covering the Kleene 3-valued truth table
* directly, without an AST round-trip. */
export function evaluateForTest(
expr: ConstraintExpr,
payload: CppConstraintPayload,
ctx: ConstraintContext,
): ArityVerdict {
return evaluate(expr, payload, ctx);
}

47
gitnexus/src/core/ingestion/languages/cpp/conversion-rank.ts Normal file
View file

@ -0,0 +1,47 @@
/**
* C++ conversion-rank scoring for overload resolution (#1578).
*
* Operates on **normalized** type strings (output of
* `normalizeCppParamType` in `arity-metadata.ts`). After normalization:
* - int/long/short/unsigned → 'int'
* - float/double → 'double'
* - char → 'char', bool → 'bool'
*
* Because the normalizer collapses promotion pairs (int↔long,
* float↔double) to the same string, those promotions are invisible at
* this layer — they appear as exact matches (rank 0).
*
* Post-normalization ranking:
* - rank 0 — exact (same normalized type)
* - rank 1 — integral promotion (char→int, bool→int)
* - rank 2 — standard arithmetic conversion (int↔double, char→double,
* bool→double)
* - Infinity — mismatch (string↔int, user types, pointers, etc.)
*
* This function is intentionally C++-specific (issue #1578 pitfall:
* keep conversion-rank tables out of shared overload-narrowing). Other
* languages may define their own `ConversionRankFn` in the future.
*/
/** Set of normalized arithmetic types that support implicit conversion. */
const ARITHMETIC = new Set(['int', 'double', 'char', 'bool']);
/** Integral promotion targets: char→int and bool→int are rank 1. */
const INTEGRAL_PROMOTION = new Map([
['char', 'int'],
['bool', 'int'],
]);
/**
* Return the conversion rank from `argType` to `paramType`.
*
* @returns 0 for exact match, 1 for integral promotion (char/bool→int),
* 2 for standard arithmetic conversion, Infinity for mismatch.
*/
export function cppConversionRank(argType: string, paramType: string): number {
if (argType === paramType) return 0;
// Integral promotions: char→int, bool→int (ISO C++ [conv.prom])
if (INTEGRAL_PROMOTION.get(argType) === paramType) return 1;
if (ARITHMETIC.has(argType) && ARITHMETIC.has(paramType)) return 2;
return Infinity;
}

302
gitnexus/src/core/ingestion/languages/cpp/file-local-linkage.ts Normal file
View file

@ -0,0 +1,302 @@
import type { ParsedFile, Scope, ScopeId, SymbolDefinition } from 'gitnexus-shared';
import { isCppInlineNamespaceScope } from './inline-namespaces.js';
/**
* Per-file set of symbol names with file-local linkage.
* In C++ there are two sources of file-local linkage:
* 1. `static` storage class (same as C)
* 2. Anonymous namespace (`namespace { ... }`)
*
* Populated during `emitCppScopeCaptures` and consumed by
* `expandCppWildcardNames` to exclude file-local symbols from
* cross-file wildcard import visibility.
*
* NOTE: module-level state, single-process-single-repo use only.
* Call `clearFileLocalNames()` at the start of each resolution pass.
*
* Key: filePath, Value: Set of file-local symbol names.
*/
const fileLocalNames = new Map<string, Set<string>>();
/**
* Per-file set of `SymbolDefinition.nodeId`s that are NOT visible by
* unqualified lookup from outside the file — class-owned methods/fields
* and namespace-nested symbols. Populated by `populateCppNonGloballyVisible`
* during the per-file `populateOwners` hook; consumed by
* `isCppDefGloballyVisible` from both `expandCppWildcardNames` (wildcard
* propagation) and the global free-call fallback's `isFileLocalDef` hook.
*
* Tracked per filePath rather than as a single global set so cross-file
* lookup correctly compares the candidate's owning file's non-visible
* set without leaking across pipeline invocations (the global free-call
* fallback checks `def.filePath !== callerFilePath` and then asks "is
* this def visible from outside its own file?" — that's exactly what
* this set encodes).
*/
const nonGloballyVisibleNodeIds = new Map<string, Set<string>>();
/**
* Per-file set of source-range keys identifying `namespace { ... }` blocks.
* Resolved to `ScopeId`s in `populateCppAnonymousNamespaceScopes` and
* consumed via `isCppAnonymousNamespaceScope`.
*
* Anonymous namespaces have file-local linkage but, unlike `static`, their
* members propagate to any TU that `#include`s the declaring file — each
* including TU gets its own internal-linkage copy. So for wildcard import
* expansion (`expandCppWildcardNames`) we treat anonymous-namespace owned
* defs as if declared at the enclosing scope. Cross-file unqualified
* lookup that does NOT go through `#include` is still blocked by the
* `isFileLocal` mark recorded on the def's name.
*/
const anonymousNamespaceRangesByFile = new Map<string, Set<string>>();
const anonymousNamespaceScopeIds = new Set<ScopeId>();
interface RangeKeyShape {
readonly startLine: number;
readonly startCol: number;
readonly endLine: number;
readonly endCol: number;
}
function rangeKey(r: RangeKeyShape): string {
return `${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}`;
}
/** Record a symbol name as file-local (static or anonymous namespace). */
export function markFileLocal(filePath: string, name: string): void {
let names = fileLocalNames.get(filePath);
if (names === undefined) {
names = new Set<string>();
fileLocalNames.set(filePath, names);
}
names.add(name);
}
/** Check whether a symbol name has file-local linkage in the given file. */
export function isFileLocal(filePath: string, name: string): boolean {
return fileLocalNames.get(filePath)?.has(name) ?? false;
}
/** Capture-time: record an anonymous `namespace_definition` source range. */
export function markCppAnonymousNamespaceRange(filePath: string, range: RangeKeyShape): void {
let set = anonymousNamespaceRangesByFile.get(filePath);
if (set === undefined) {
set = new Set();
anonymousNamespaceRangesByFile.set(filePath, set);
}
set.add(rangeKey(range));
}
/** Predicate consumed by `populateCppNonGloballyVisible` and
* `expandCppWildcardNames` to exempt anonymous-namespace scopes from
* the cross-file unqualified-lookup exclusion that applies to ordinary
* named namespaces. */
export function isCppAnonymousNamespaceScope(scopeId: ScopeId): boolean {
return anonymousNamespaceScopeIds.has(scopeId);
}
/** Clear tracked file-local names (call at start of each resolution pass). */
export function clearFileLocalNames(): void {
fileLocalNames.clear();
nonGloballyVisibleNodeIds.clear();
anonymousNamespaceRangesByFile.clear();
anonymousNamespaceScopeIds.clear();
}
/** Resolve recorded anonymous-namespace source ranges to `ScopeId`s.
* Must run inside `populateOwners` BEFORE `populateCppNonGloballyVisible`
* consults the resolved set. */
export function populateCppAnonymousNamespaceScopes(parsed: {
readonly filePath: string;
readonly scopes: readonly {
readonly id: ScopeId;
readonly kind: string;
readonly range: RangeKeyShape;
}[];
}): void {
const ranges = anonymousNamespaceRangesByFile.get(parsed.filePath);
if (ranges === undefined || ranges.size === 0) return;
for (const scope of parsed.scopes) {
if (scope.kind !== 'Namespace') continue;
if (ranges.has(rangeKey(scope.range))) {
anonymousNamespaceScopeIds.add(scope.id);
}
}
}
/**
* Populate per-file "not globally visible" nodeIds by walking the parsed
* file's scopes. Run as part of the `populateOwners` hook so every C++
* scope is reflected before any cross-file resolution pass consults the
* set.
*
* A def is "not globally visible" when its nearest structurally enclosing
* scope is a `Namespace` or `Class` — those require qualification
* (`ns::name`, `Class::method`) for cross-file unqualified lookup.
* Module-scoped defs remain globally visible.
*/
export function populateCppNonGloballyVisible(parsed: {
readonly filePath: string;
readonly scopes: readonly {
readonly id: ScopeId;
readonly kind: string;
readonly ownedDefs: readonly { readonly nodeId: string }[];
}[];
}): void {
let set = nonGloballyVisibleNodeIds.get(parsed.filePath);
if (set === undefined) {
set = new Set<string>();
nonGloballyVisibleNodeIds.set(parsed.filePath, set);
}
for (const scope of parsed.scopes) {
if (scope.kind !== 'Namespace' && scope.kind !== 'Class') continue;
// Inline namespaces (`inline namespace v1 { ... }`) propagate their
// members to the enclosing namespace's unqualified-lookup scope per
// ISO C++ `[namespace.def]/p4`. Skip them here so cross-file
// unqualified lookup can still see their callable defs.
if (scope.kind === 'Namespace' && isCppInlineNamespaceScope(scope.id)) continue;
// Anonymous namespaces give internal linkage but their contents are
// visible at the enclosing scope within the same TU and propagate to
// any TU that `#include`s the declaring file. The `isFileLocal` mark
// (recorded on the def's name in this file) still blocks cross-file
// unqualified lookup that does not go through #include, so dropping
// the structural visibility exclusion here is safe.
if (scope.kind === 'Namespace' && anonymousNamespaceScopeIds.has(scope.id)) continue;
for (const def of scope.ownedDefs) {
set.add(def.nodeId);
}
}
}
/**
* Check whether a def is visible by unqualified lookup from outside its
* own file. Returns `false` for class-owned and namespace-nested defs.
*
* Used by the global free-call fallback's `isFileLocalDef` hook (which
* historically meant "static / anonymous-namespace" but semantically
* stands for "logically invisible cross-file"). Including class methods
* and namespace members under the same negative answer fixes the leak
* where unqualified `save()` resolved to `User::save` through a shared
* workspace registry walk.
*/
export function isCppDefGloballyVisible(filePath: string, nodeId: string): boolean {
return nonGloballyVisibleNodeIds.get(filePath)?.has(nodeId) !== true;
}
/**
* Return the names visible through a C++ wildcard import (`#include` or
* `using namespace`).
*
* ## Contract
*
* C++ unqualified name lookup only sees names at the importer's enclosing
* scope. Class members and namespace-nested symbols are NOT visible by
* unqualified lookup from a free function in an including TU — they must
* be reached via `Class::method`, `ns::name`, or a working `using`
* declaration. The filter below enforces that contract for header
* propagation: only defs whose nearest enclosing scope is the header's
* `Module` scope are emitted as wildcard-binding names.
*
* ## Why scope-aware and not predicate-on-qualifiedName
*
* A naive `def.qualifiedName.indexOf('.') === -1` check is unreliable
* because `populateClassOwnedMembers`
* (`gitnexus/src/core/ingestion/scope-resolution/scope/walkers.ts`)
* only dot-qualifies `qualifiedName` for `Class` scopes. Namespace-nested
* defs (`namespace ns { void foo(); }`) arrive in `localDefs` with
* `qualifiedName === 'foo'` and `ownerId === undefined`, indistinguishable
* from a top-level free function. The structural truth lives in
* `Scope.ownedDefs`: each scope lists what it structurally owns; the
* Module scope owns only top-level symbols. We look the def up by
* `nodeId` against the scope tree to identify its owning kind.
*
* ## `localDefs` consumer survey (recorded for future maintainers)
*
* Other consumers of `ParsedFile.localDefs` were audited at the time
* this filter was introduced (see PR #1520 / plan
* `docs/plans/2026-05-12-002-fix-cpp-resolver-followups-plan.md`):
*
* - `finalize-orchestrator.ts:113,163` — flattens defs into a workspace
* registry keyed by `ownerId` + `qualifiedName`; class-owned and
* namespace-owned symbols are registered under their owner, not as
* unqualified names. Not a leak surface.
* - `csharp/namespace-siblings.ts:307`, `go/expand-wildcards.ts:86`,
* `php/scope-resolver.ts:141,151`, `c/static-linkage.ts:51` — other
* languages' own wildcard / sibling expansions. Each owns its own
* visibility contract.
* - `receiver-bound-calls.ts:99`, `reconcile-ownership.ts:66,119`,
* `mro.ts:61` — keyed by `ownerId` for member lookup, never used
* as unqualified bindings.
* - `go/interface-impls.ts:40,53`, `go/package-siblings.ts:41` — Go-
* specific, sibling-package scoped.
*
* No other consumer treats `localDefs` as a flat unqualified-binding
* set the way this function did before the fix. If a future consumer
* does, mirror this filter or harden registration so class/namespace
* members never enter `localDefs` unqualified.
*/
export function expandCppWildcardNames(
targetModuleScope: ScopeId,
parsedFiles: readonly ParsedFile[],
): readonly string[] {
const target = parsedFiles.find((p) => p.moduleScope === targetModuleScope);
if (target === undefined) return [];
// Build nodeId → owning Scope map from the structural scope tree.
// `Scope.ownedDefs` is the canonical source of structural ownership;
// `localDefs` is its flattened union, which is why the original code
// leaked: walking only `localDefs` discards the owning-scope context.
const ownerScopeByNodeId = new Map<string, Scope>();
for (const scope of target.scopes) {
for (const ownedDef of scope.ownedDefs) {
ownerScopeByNodeId.set(ownedDef.nodeId, scope);
}
}
const seen = new Set<string>();
const names: string[] = [];
for (const def of target.localDefs) {
// Defense-in-depth: class methods carry a non-undefined ownerId after
// `populateClassOwnedMembers` runs. Skip them outright.
if (def.ownerId !== undefined) continue;
// Structural visibility check: exclude defs whose owning scope is a
// Namespace or Class — these require qualification (`ns::name`,
// `Class::method`) and are NOT reachable by unqualified lookup in an
// including TU. When the owning scope is unknown we default to
// include (preserves prior behavior for any def whose structural
// ownership wasn't recorded in `Scope.ownedDefs`).
//
// Anonymous namespaces are exempt: their members propagate to the
// enclosing scope of any TU that #includes the declaring file (each
// including TU gets its own internal-linkage copy per ISO C++).
const ownerScope = ownerScopeByNodeId.get(def.nodeId);
const ownerIsAnonymousNamespace =
ownerScope !== undefined &&
ownerScope.kind === 'Namespace' &&
anonymousNamespaceScopeIds.has(ownerScope.id);
if (
ownerScope !== undefined &&
!ownerIsAnonymousNamespace &&
(ownerScope.kind === 'Namespace' || ownerScope.kind === 'Class')
) {
continue;
}
const name = simpleName(def);
if (name === '') continue;
// Same exemption for the `isFileLocal` mark — anonymous-namespace
// names are recorded as file-local to suppress the global free-call
// fallback's cross-file leak, but they MUST still propagate through
// wildcard import expansion to including TUs.
if (!ownerIsAnonymousNamespace && isFileLocal(target.filePath, name)) continue;
if (seen.has(name)) continue;
seen.add(name);
names.push(name);
}
return names;
}
function simpleName(def: SymbolDefinition): string {
return def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
}

53
gitnexus/src/core/ingestion/languages/cpp/header-scan.ts Normal file
View file

@ -0,0 +1,53 @@
import { readdirSync, type Dirent } from 'fs';
import { join, relative } from 'path';
/** C++ header extensions to scan for in the workspace. */
const HEADER_EXTENSIONS = new Set(['.h', '.hpp', '.hxx', '.hh']);
/**
* Walk `repoPath` recursively and return relative paths of all C++ header files.
* Used by `loadResolutionConfig` so the C++ resolver can resolve `#include`
* targets that live in header files.
*
* Scans for: .h, .hpp, .hxx, .hh
*/
export function scanCppHeaderFiles(repoPath: string): ReadonlySet<string> {
const headers = new Set<string>();
walk(repoPath, repoPath, headers);
return headers;
}
function walk(dir: string, root: string, out: Set<string>): void {
let entries: Dirent[];
try {
entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf8' });
} catch {
return; // permission denied, etc.
}
for (const entry of entries) {
const name = entry.name;
const full = join(dir, name);
if (entry.isDirectory()) {
if (
name === 'node_modules' ||
name === '.git' ||
name === 'vendor' ||
name === 'dist' ||
name === 'build' ||
name === 'out' ||
name === 'target' ||
name === '_build' ||
name === '.next' ||
name.startsWith('cmake-build')
) {
continue;
}
walk(full, root, out);
} else if (entry.isFile()) {
const ext = name.slice(name.lastIndexOf('.'));
if (HEADER_EXTENSIONS.has(ext)) {
out.add(relative(root, full).replace(/\\/g, '/'));
}
}
}
}

120
gitnexus/src/core/ingestion/languages/cpp/import-decomposer.ts Normal file
View file

@ -0,0 +1,120 @@
import type { Capture, CaptureMatch } from 'gitnexus-shared';
import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js';
/**
* Decompose a `preproc_include` node into a CaptureMatch with structured
* import captures. C++ #include maps to a wildcard import (all symbols
* from the header are visible). Identical to C's splitCInclude.
*/
export function splitCppInclude(node: SyntaxNode): CaptureMatch | null {
const pathNode = node.childForFieldName?.('path') ?? null;
if (pathNode === null) {
for (let i = 0; i < node.childCount; i++) {
const child = node.child(i);
if (child === null) continue;
if (child.type === 'string_literal' || child.type === 'system_lib_string') {
return buildIncludeCapture(node, child);
}
}
return null;
}
return buildIncludeCapture(node, pathNode);
}
function buildIncludeCapture(node: SyntaxNode, pathNode: SyntaxNode): CaptureMatch {
let raw: string;
if (pathNode.type === 'string_literal') {
const content = pathNode.namedChildren.find((c) => c.type === 'string_content');
raw = content?.text ?? pathNode.text.replace(/^"|"$/g, '');
} else {
raw = pathNode.text;
if (raw.startsWith('<') && raw.endsWith('>')) {
raw = raw.slice(1, -1);
}
}
const isSystem = pathNode.type === 'system_lib_string';
const result: Record<string, Capture> = {
'@import.statement': nodeToCapture('@import.statement', node),
'@import.kind': syntheticCapture('@import.kind', node, 'wildcard'),
'@import.source': syntheticCapture('@import.source', node, raw),
};
if (isSystem) {
result['@import.system'] = syntheticCapture('@import.system', node, 'true');
}
return result;
}
/**
* Decompose a `using_declaration` node into a CaptureMatch.
*
* tree-sitter-cpp produces:
* using namespace std; → using_declaration { "using", "namespace", identifier("std"), ";" }
* using std::vector; → using_declaration { "using", qualified_identifier("std::vector"), ";" }
*
* The first form is a wildcard import (all names from namespace).
* The second form is a named import (single symbol).
*/
export function splitCppUsingDecl(node: SyntaxNode): CaptureMatch | null {
if (node.type !== 'using_declaration') return null;
// Check for "namespace" keyword among anonymous children
let hasNamespaceKeyword = false;
for (let i = 0; i < node.childCount; i++) {
const child = node.child(i);
if (child !== null && !child.isNamed && child.text === 'namespace') {
hasNamespaceKeyword = true;
break;
}
}
if (hasNamespaceKeyword) {
// using namespace <name>;
// The namespace name can be an identifier or qualified_identifier
let namespaceName: string | null = null;
for (let i = 0; i < node.namedChildCount; i++) {
const child = node.namedChild(i);
if (child === null) continue;
if (child.type === 'identifier' || child.type === 'qualified_identifier') {
namespaceName = child.text;
break;
}
}
if (namespaceName === null) return null;
return {
'@import.statement': nodeToCapture('@import.statement', node),
'@import.kind': syntheticCapture('@import.kind', node, 'wildcard'),
'@import.source': syntheticCapture('@import.source', node, namespaceName),
'@import.using-namespace': syntheticCapture('@import.using-namespace', node, 'true'),
};
}
// using <qualified_identifier>; (e.g. using std::vector)
let qualId: SyntaxNode | null = null;
for (let i = 0; i < node.namedChildCount; i++) {
const child = node.namedChild(i);
if (child !== null && child.type === 'qualified_identifier') {
qualId = child;
break;
}
}
if (qualId === null) return null;
// Extract the imported name (last identifier) and source (namespace part)
const nameNode = qualId.childForFieldName?.('name') ?? null;
const scopeNode = qualId.childForFieldName?.('scope') ?? null;
const importedName = nameNode?.text ?? qualId.text.split('::').pop() ?? '';
const source = scopeNode?.text ?? qualId.text.replace(new RegExp('::' + importedName + '$'), '');
return {
'@import.statement': nodeToCapture('@import.statement', node),
'@import.kind': syntheticCapture('@import.kind', node, 'named'),
'@import.source': syntheticCapture('@import.source', node, source),
'@import.name': syntheticCapture('@import.name', node, importedName),
};
}

18
gitnexus/src/core/ingestion/languages/cpp/import-target.ts Normal file
View file

@ -0,0 +1,18 @@
import { resolveCImportTarget } from '../c/import-target.js';
/**
* Resolve a C++ #include path to a file in the workspace.
* C++ #include path resolution is identical to C:
* 1. Same-directory sibling (relative lookup)
* 2. Exact match
* 3. Suffix match with depth + lexicographic tiebreak
*
* Re-exports the C implementation since the #include semantics are shared.
*/
export function resolveCppImportTarget(
targetRaw: string,
fromFile: string,
allFilePaths: ReadonlySet<string>,
): string | null {
return resolveCImportTarget(targetRaw, fromFile, allFilePaths);
}

16
gitnexus/src/core/ingestion/languages/cpp/index.ts Normal file
View file

@ -0,0 +1,16 @@
/**
* C++ scope-resolution hooks (RFC #909 Ring 3).
*/
export { emitCppScopeCaptures } from './captures.js';
export { interpretCppImport, interpretCppTypeBinding, normalizeCppTypeName } from './interpret.js';
export { splitCppInclude, splitCppUsingDecl } from './import-decomposer.js';
export { cppArityCompatibility } from './arity.js';
export { cppMergeBindings } from './merge-bindings.js';
export { cppBindingScopeFor, cppImportOwningScope, cppReceiverBinding } from './simple-hooks.js';
export { resolveCppImportTarget } from './import-target.js';
export {
markFileLocal,
isFileLocal,
clearFileLocalNames,
expandCppWildcardNames,
} from './file-local-linkage.js';

203
gitnexus/src/core/ingestion/languages/cpp/inline-namespaces.ts Normal file
View file

@ -0,0 +1,203 @@
/**
* C++ inline namespace support (U5 of plan 2026-05-13-001).
*
* `inline namespace v1 { void foo(); }` has two ISO C++ semantics that
* GitNexus must model:
*
* 1. **Transitive unqualified visibility.** Names declared in an inline
* namespace are reachable by unqualified lookup from the enclosing
* namespace's scope, as if they were declared directly there.
* `populateCppNonGloballyVisible` (file-local-linkage.ts) treats
* inline-namespace members as globally visible for cross-file
* unqualified lookup.
*
* 2. **Transitive qualified visibility.** `outer::foo()` resolves to
* `outer::v1::foo()` when `v1` is inline. The qualified-namespace
* receiver resolver (`resolveCppQualifiedNamespaceMember`) walks
* inline-namespace children transitively when collecting candidates.
*
* State lifecycle: capture-time `markCppInlineNamespaceRange` records each
* inline namespace's source range; `populateCppInlineNamespaceScopes`
* resolves ranges to `ScopeId`s during `populateOwners`. Cleared via
* `clearCppInlineNamespaces`, called from `clearFileLocalNames`.
*
* STL idiom this enables: `std::__1::vector` (libc++) and `std::__cxx11`
* (libstdc++) are inline namespaces of `std`. With this support,
* `std::vector` qualified calls resolve to the inline-namespace
* declaration transparently.
*/
import type { ParsedFile, ScopeId, SymbolDefinition } from 'gitnexus-shared';
import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
import {
isOverloadAmbiguousAfterNormalization,
narrowOverloadCandidates,
} from '../../scope-resolution/passes/overload-narrowing.js';
interface RangeKey {
readonly startLine: number;
readonly startCol: number;
readonly endLine: number;
readonly endCol: number;
}
const inlineNamespaceRangesByFile = new Map<string, Set<string>>();
const inlineNamespaceScopeIds = new Set<ScopeId>();
function rangeKey(r: RangeKey): string {
return `${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}`;
}
/** Capture-time: record a namespace_definition's range as inline.
* Called from `emitCppScopeCaptures` when the tree-sitter AST shows an
* `inline` keyword child on `namespace_definition`. */
export function markCppInlineNamespaceRange(filePath: string, range: RangeKey): void {
let set = inlineNamespaceRangesByFile.get(filePath);
if (set === undefined) {
set = new Set();
inlineNamespaceRangesByFile.set(filePath, set);
}
set.add(rangeKey(range));
}
/** Clear all inline-namespace state. Called from `clearFileLocalNames`. */
export function clearCppInlineNamespaces(): void {
inlineNamespaceRangesByFile.clear();
inlineNamespaceScopeIds.clear();
}
/** Resolve captured ranges to actual ScopeIds by matching scope ranges
* against the inline-namespace ranges recorded for this file. Run from
* the cpp resolver's `populateOwners` hook so the per-pipeline Set is
* populated before any resolution pass consults it. */
export function populateCppInlineNamespaceScopes(parsed: ParsedFile): void {
const ranges = inlineNamespaceRangesByFile.get(parsed.filePath);
if (ranges === undefined || ranges.size === 0) return;
for (const scope of parsed.scopes) {
if (scope.kind !== 'Namespace') continue;
if (ranges.has(rangeKey(scope.range))) {
inlineNamespaceScopeIds.add(scope.id);
}
}
}
/** Predicate consumed by `populateCppNonGloballyVisible` to exempt
* inline-namespace members from cross-file unqualified-lookup
* exclusion (they remain reachable as if declared at the enclosing
* namespace's level). */
export function isCppInlineNamespaceScope(scopeId: ScopeId): boolean {
return inlineNamespaceScopeIds.has(scopeId);
}
/**
* Walk every parsed file looking for a Namespace scope whose qualified
* name matches `receiverName`, collect its callable ownedDefs matching
* `memberName`, transitively descending into any inline-namespace
* children (since they're members of the enclosing namespace under ISO
* C++).
*
* Returns the most specific (innermost) match — for `outer::foo()`
* where `inline namespace v1` declares `foo`, returns `v1::foo`. When
* multiple inline-namespace children declare the same name, ISO C++
* leaves the call ambiguous; returns `'ambiguous'` so the caller
* suppresses edge emission rather than picking arbitrarily (#1564).
*/
export function resolveCppQualifiedNamespaceMember(
receiverName: string,
memberName: string,
parsedFiles: readonly ParsedFile[],
_scopes: ScopeResolutionIndexes,
): SymbolDefinition | 'ambiguous' | undefined {
const allHits: SymbolDefinition[] = [];
const seenNodeId = new Set<string>();
for (const parsed of parsedFiles) {
const scopesById = new Map<ScopeId, (typeof parsed.scopes)[number]>();
for (const sc of parsed.scopes) scopesById.set(sc.id, sc);
for (const scope of parsed.scopes) {
if (scope.kind !== 'Namespace') continue;
const nsDef = findNamespaceDefInScope(scope);
if (nsDef === undefined) continue;
const nsName = nsDef.qualifiedName?.split('.').pop() ?? nsDef.qualifiedName ?? '';
if (nsName !== receiverName) continue;
// Found a matching namespace scope in this file. Collect ALL
// members transitively through any inline-namespace children.
const hits = findMemberInNamespaceTransitive(scope, scopesById, memberName);
for (const hit of hits) {
if (seenNodeId.has(hit.nodeId)) continue;
seenNodeId.add(hit.nodeId);
allHits.push(hit);
}
}
}
if (allHits.length === 0) return undefined;
if (allHits.length === 1) return allHits[0];
// Multi-candidate: the `resolveQualifiedReceiverMember` hook has no
// access to call-site arity or argument types, so
// `narrowOverloadCandidates` cannot actually narrow here — the call
// with `(allHits, undefined, undefined)` is effectively a pass-through.
// We retain it so that `isOverloadAmbiguousAfterNormalization` can
// still detect int/long-style normalization collisions on this path,
// but for any multi-hit case where candidates have genuinely distinct
// signatures (e.g. `foo(int)` vs `foo(double)` in different inline
// children), we conservatively suppress rather than pick arbitrarily.
// A future enhancement could thread call-site argument info through
// the `resolveQualifiedReceiverMember` contract to enable real
// narrowing here.
const narrowed = narrowOverloadCandidates(allHits, undefined, undefined);
if (narrowed.length === 1) return narrowed[0];
if (narrowed.length === 0) return undefined;
if (isOverloadAmbiguousAfterNormalization(narrowed, undefined)) return 'ambiguous';
// Multiple surviving candidates (distinct signatures) — conservative
// suppress because we lack call-site info to disambiguate.
return 'ambiguous';
}
/** Recursively search a namespace scope and any inline-namespace
* descendants for callable defs with the given simple name. Non-inline
* nested namespaces are NOT traversed — they require explicit
* qualification (`outer::nested::foo`). Returns ALL matches so the
* caller can detect same-name ambiguity across inline children (#1564). */
function findMemberInNamespaceTransitive(
scope: {
readonly id: ScopeId;
readonly ownedDefs: readonly SymbolDefinition[];
readonly parent: ScopeId | null;
},
scopesById: ReadonlyMap<
ScopeId,
{
readonly id: ScopeId;
readonly kind: string;
readonly parent: ScopeId | null;
readonly ownedDefs: readonly SymbolDefinition[];
}
>,
memberName: string,
): SymbolDefinition[] {
const results: SymbolDefinition[] = [];
// Check this scope's own ownedDefs first.
for (const def of scope.ownedDefs) {
if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor') continue;
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
if (simple === memberName) results.push(def);
}
// Descend into inline-namespace children.
for (const childScope of scopesById.values()) {
if (childScope.parent !== scope.id) continue;
if (childScope.kind !== 'Namespace') continue;
if (!inlineNamespaceScopeIds.has(childScope.id)) continue;
const childHits = findMemberInNamespaceTransitive(childScope, scopesById, memberName);
for (const hit of childHits) results.push(hit);
}
return results;
}
function findNamespaceDefInScope(scope: {
readonly ownedDefs: readonly SymbolDefinition[];
}): SymbolDefinition | undefined {
for (const def of scope.ownedDefs) {
if (def.type === 'Namespace') return def;
}
return undefined;
}

110
gitnexus/src/core/ingestion/languages/cpp/interpret.ts Normal file
View file

@ -0,0 +1,110 @@
import type { CaptureMatch, ParsedImport, ParsedTypeBinding, TypeRef } from 'gitnexus-shared';
/**
* Interpret a C++ import capture into a ParsedImport.
*
* C++ has three import forms:
* 1. #include "file.h" → wildcard import (all symbols from header)
* 2. using namespace X; → wildcard import (all symbols from namespace X)
* 3. using X::name; → named import (single symbol from namespace X)
*
* System headers (#include <...>) are not resolved to local files.
*/
export function interpretCppImport(captures: CaptureMatch): ParsedImport | null {
const source = captures['@import.source']?.text;
if (source === undefined) return null;
// System headers are not resolved to local files
if (captures['@import.system'] !== undefined) return null;
const kind = captures['@import.kind']?.text;
if (kind === 'named') {
// using X::name — named import
const importedName = captures['@import.name']?.text;
if (importedName === undefined) return null;
return { kind: 'named', targetRaw: source, localName: importedName, importedName };
}
// #include or using namespace — wildcard import
return { kind: 'wildcard', targetRaw: source };
}
/**
* Interpret a C++ type-binding capture into a ParsedTypeBinding.
*
* Source classification (strongest → weakest):
* - `'parameter-annotation'` — function parameter type
* - `'annotation'` — explicit type declaration (`User user;`)
* - `'assignment-inferred'` — typed init (`User user = ...`)
* - `'constructor'` — constructor call (`auto u = User(...)` / `User{}`)
* - `'return'` — function return type
* - `'field'` — class field type
* - `'alias'` — `auto x = existingVar`
*/
export function interpretCppTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null {
const name = captures['@type-binding.name']?.text;
const type = captures['@type-binding.type']?.text;
if (name === undefined || type === undefined) return null;
let source: TypeRef['source'] = 'annotation';
if (captures['@type-binding.parameter'] !== undefined) {
source = 'parameter-annotation';
} else if (captures['@type-binding.constructor'] !== undefined) {
source = 'constructor-inferred';
} else if (captures['@type-binding.return'] !== undefined) {
source = 'return-annotation';
} else if (captures['@type-binding.field'] !== undefined) {
// Field types are structurally equivalent to annotations — the type
// is explicitly written, not inferred.
source = 'annotation';
} else if (captures['@type-binding.member-access'] !== undefined) {
// auto addr = user.address — the type is inferred from the member access.
// Synthesize a dotted rawName ("receiver.field") so compound-receiver
// can resolve the chain: look up receiver's class, then field's type.
const receiver = captures['@type-binding.member-access-receiver']?.text;
if (receiver !== undefined) {
return { boundName: name, rawTypeName: `${receiver}.${type}`, source: 'assignment-inferred' };
}
source = 'assignment-inferred';
} else if (captures['@type-binding.alias'] !== undefined) {
// auto alias = existingVar — the type is inferred from the RHS variable.
source = 'assignment-inferred';
} else if (captures['@type-binding.assignment'] !== undefined) {
source = 'assignment-inferred';
} else if (captures['@type-binding.annotation'] !== undefined) {
source = 'annotation';
}
return { boundName: name, rawTypeName: normalizeCppTypeName(type), source };
}
/**
* Normalize a C++ type name: strip pointer/array/reference syntax,
* qualifiers, while preserving template arguments for specialization-aware
* receiver binding (`List<User>` vs `List<Order>`).
*
* Keeping template arguments here allows receiver-bound fallback to match
* specialization-specific class defs first; non-template behavior is preserved
* by base-name fallback in resolveClassBindingForName.
*/
export function normalizeCppTypeName(text: string): string {
let t = text.trim();
// Strip const, volatile, restrict, static, extern, inline, mutable, constexpr
t = t
.replace(/\b(const|volatile|restrict|static|extern|inline|mutable|constexpr|consteval)\b/g, '')
.trim();
// Strip pointer stars
while (t.endsWith('*')) t = t.slice(0, -1).trim();
while (t.startsWith('*')) t = t.slice(1).trim();
// Strip reference markers
while (t.endsWith('&')) t = t.slice(0, -1).trim();
// Strip array brackets
t = t.replace(/\[.*?\]/g, '').trim();
// Strip struct/union/enum/class prefixes
t = t.replace(/^(struct|union|enum|class)\s+/, '');
// Strip leading :: (global namespace qualifier)
t = t.replace(/^::/, '');
return t;
}

38
gitnexus/src/core/ingestion/languages/cpp/merge-bindings.ts Normal file
View file

@ -0,0 +1,38 @@
import type { BindingRef } from 'gitnexus-shared';
const TIER: Record<BindingRef['origin'], number> = {
local: 0,
namespace: 1,
import: 2,
reexport: 3,
wildcard: 4,
};
/**
* C++ merge bindings: first-wins by tier.
*
* C++ tier precedence:
* local(0) > namespace(1) > import(2) > reexport(3) > wildcard(4)
*
* Unlike C (no namespaces), C++ uses the `namespace` tier for symbols
* brought in via `using namespace X;` that are then locally referenced.
* The tier ordering ensures local definitions shadow namespace imports,
* which in turn shadow wildcard #include imports.
*/
export function cppMergeBindings(
existing: readonly BindingRef[],
incoming: readonly BindingRef[],
_scopeId: string,
): BindingRef[] {
const seen = new Set<string>();
return [...existing, ...incoming]
.sort(
(a, b) =>
(TIER[a.origin] ?? 99) - (TIER[b.origin] ?? 99) || a.def.nodeId.localeCompare(b.def.nodeId),
)
.filter((binding) => {
if (seen.has(binding.def.nodeId)) return false;
seen.add(binding.def.nodeId);
return true;
});
}

512
gitnexus/src/core/ingestion/languages/cpp/query.ts Normal file
View file

@ -0,0 +1,512 @@
import Parser from 'tree-sitter';
import CPP from 'tree-sitter-cpp';
const CPP_SCOPE_QUERY = `
;; ─── Scopes ──────────────────────────────────────────────────────────
(translation_unit) @scope.module
(namespace_definition) @scope.namespace
(class_specifier) @scope.class
(struct_specifier) @scope.class
(function_definition) @scope.function
(lambda_expression) @scope.function
(compound_statement) @scope.block
(if_statement) @scope.block
(for_statement) @scope.block
(for_range_loop) @scope.block
(while_statement) @scope.block
(do_statement) @scope.block
(switch_statement) @scope.block
(case_statement) @scope.block
(try_statement) @scope.block
(catch_clause) @scope.block
;; ─── Declarations — namespace ────────────────────────────────────────
(namespace_definition
name: (namespace_identifier) @declaration.name) @declaration.namespace
;; Anonymous namespace (no name child) — captured as scope only, names
;; inside are marked file-local by captures.ts.
;; ─── Declarations — class / struct (named) ───────────────────────────
(class_specifier
name: (type_identifier) @declaration.name
body: (field_declaration_list)) @declaration.class
(class_specifier
name: (template_type
(type_identifier) @declaration.name
(template_argument_list) @declaration.template-arguments)
body: (field_declaration_list)) @declaration.class
(struct_specifier
name: (type_identifier) @declaration.name
body: (field_declaration_list)) @declaration.struct
(struct_specifier
name: (template_type
(type_identifier) @declaration.name
(template_argument_list) @declaration.template-arguments)
body: (field_declaration_list)) @declaration.struct
;; ─── Declarations — class / struct inside template_declaration ───────
(template_declaration
(class_specifier
name: (type_identifier) @declaration.name
body: (field_declaration_list)) @declaration.class)
(template_declaration
(class_specifier
name: (template_type
(type_identifier) @declaration.name
(template_argument_list) @declaration.template-arguments)
body: (field_declaration_list)) @declaration.class)
(template_declaration
(struct_specifier
name: (type_identifier) @declaration.name
body: (field_declaration_list)) @declaration.struct)
(template_declaration
(struct_specifier
name: (template_type
(type_identifier) @declaration.name
(template_argument_list) @declaration.template-arguments)
body: (field_declaration_list)) @declaration.struct)
;; ─── Declarations — enum ─────────────────────────────────────────────
(enum_specifier
name: (type_identifier) @declaration.name) @declaration.enum
;; ─── Declarations — enum constants ───────────────────────────────────
(enumerator
name: (identifier) @declaration.name) @declaration.const
;; ─── Declarations — function definition (plain identifier) ──────────
(function_definition
declarator: (function_declarator
declarator: (identifier) @declaration.name)) @declaration.function
;; ─── Declarations — function definition with pointer return ─────────
(function_definition
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (identifier) @declaration.name))) @declaration.function
;; ─── Declarations — out-of-class method (qualified_identifier) ──────
(function_definition
declarator: (function_declarator
declarator: (qualified_identifier
name: (identifier) @declaration.name))) @declaration.method
;; ─── Declarations — out-of-class method with pointer return ─────────
(function_definition
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (qualified_identifier
name: (identifier) @declaration.name)))) @declaration.method
;; ─── Declarations — out-of-class method (destructor_name) ───────────
(function_definition
declarator: (function_declarator
declarator: (qualified_identifier
name: (destructor_name) @declaration.name))) @declaration.method
;; ─── Declarations — template function definition ────────────────────
(template_declaration
(function_definition
declarator: (function_declarator
declarator: (identifier) @declaration.name)) @declaration.function)
;; ─── Declarations — template method (qualified) ─────────────────────
(template_declaration
(function_definition
declarator: (function_declarator
declarator: (qualified_identifier
name: (identifier) @declaration.name))) @declaration.method)
;; ─── Declarations — inline method in class body (field_identifier) ──
;; tree-sitter-cpp uses field_identifier for names inside class bodies
(function_definition
declarator: (function_declarator
declarator: (field_identifier) @declaration.name)) @declaration.method
;; ─── Declarations — inline method with pointer return (field_identifier) ──
;; Covers: User* lookup(int id) { ... } inside a class body
;; AST: function_definition > pointer_declarator > function_declarator > field_identifier
(function_definition
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (field_identifier) @declaration.name))) @declaration.method
;; ─── Declarations — inline method with reference return (field_identifier) ──
;; Covers: User& getRef() { ... } inside a class body
(function_definition
declarator: (reference_declarator
(function_declarator
declarator: (field_identifier) @declaration.name))) @declaration.method
;; ─── Declarations — function prototype (forward declaration) ────────
(declaration
declarator: (function_declarator
declarator: (identifier) @declaration.name)) @declaration.function
;; ─── Declarations — function prototype with pointer return ──────────
(declaration
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (identifier) @declaration.name))) @declaration.function
;; ─── Declarations — typedef ─────────────────────────────────────────
(type_definition
declarator: (type_identifier) @declaration.name) @declaration.typedef
;; ─── Declarations — type alias (using Name = Type) ──────────────────
(alias_declaration
name: (type_identifier) @declaration.name) @declaration.typedef
;; ─── Declarations — method prototype in class body (forward decl) ────
;; Covers: class User { void save(); std::string getName(); };
;; AST: field_declaration > function_declarator > field_identifier
(field_declaration
declarator: (function_declarator
declarator: (field_identifier) @declaration.name)) @declaration.method
;; Method prototype with pointer return: User* lookup(int id);
(field_declaration
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (field_identifier) @declaration.name))) @declaration.method
;; Method prototype with reference return: User& getRef();
(field_declaration
declarator: (reference_declarator
(function_declarator
declarator: (field_identifier) @declaration.name))) @declaration.method
;; ─── Declarations — fields ──────────────────────────────────────────
(field_declaration
declarator: (field_identifier) @declaration.name) @declaration.field
;; Declarations — fields (pointer)
(field_declaration
declarator: (pointer_declarator
declarator: (field_identifier) @declaration.name)) @declaration.field
;; Declarations — fields (reference)
(field_declaration
declarator: (reference_declarator
(field_identifier) @declaration.name)) @declaration.field
;; ─── Declarations — variables (with initializer) ────────────────────
(declaration
declarator: (init_declarator
declarator: (identifier) @declaration.name)) @declaration.variable
;; ─── Declarations — macro definitions ───────────────────────────────
(preproc_def
name: (identifier) @declaration.name) @declaration.macro
(preproc_function_def
name: (identifier) @declaration.name) @declaration.macro
;; ─── Imports — #include ─────────────────────────────────────────────
(preproc_include) @import.statement
;; ─── Imports — using declaration ─────────────────────────────────────
;; Both "using namespace std;" and "using std::vector;" are
;; using_declaration nodes in tree-sitter-cpp. The captures.ts
;; differentiates between them by checking for a "namespace" anonymous
;; child token.
(using_declaration) @import.using-decl
;; ─── Type bindings — parameter annotations ──────────────────────────
(parameter_declaration
type: (_) @type-binding.type
declarator: (identifier) @type-binding.name) @type-binding.parameter
;; Type bindings — reference parameter (const std::string& name)
(parameter_declaration
type: (_) @type-binding.type
declarator: (reference_declarator
(identifier) @type-binding.name)) @type-binding.parameter
;; Type bindings — pointer parameter (User* ptr)
(parameter_declaration
type: (_) @type-binding.type
declarator: (pointer_declarator
declarator: (identifier) @type-binding.name)) @type-binding.parameter
;; ─── Type bindings — variable with type (init_declarator) ───────────
;; Covers: User user("alice"), User user = ..., int x = 0
(declaration
type: (_) @type-binding.type
declarator: (init_declarator
declarator: (identifier) @type-binding.name)) @type-binding.assignment
;; ─── Type bindings — plain declaration (no initializer) ─────────────
;; Covers: User user;
(declaration
type: (type_identifier) @type-binding.type
declarator: (identifier) @type-binding.name) @type-binding.annotation
;; Covers: List<User> users;
(declaration
type: (template_type) @type-binding.type
declarator: (identifier) @type-binding.name) @type-binding.annotation
;; ─── Type bindings — pointer variable declaration ───────────────────
;; Covers: User* ptr = new User()
(declaration
type: (type_identifier) @type-binding.type
declarator: (init_declarator
declarator: (pointer_declarator
declarator: (identifier) @type-binding.name))) @type-binding.annotation
;; ─── Type bindings — auto + constructor call ────────────────────────
;; Covers: auto user = User("alice")
;; AST: declaration > placeholder_type_specifier/auto > init_declarator > identifier + call_expression > identifier
(declaration
type: (placeholder_type_specifier)
declarator: (init_declarator
declarator: (identifier) @type-binding.name
value: (call_expression
function: (identifier) @type-binding.type))) @type-binding.constructor
;; ─── Type bindings — auto + brace-init (compound_literal_expression) ─
;; Covers: auto user = User{}, auto user = User{args}
;; AST: declaration > placeholder_type_specifier/auto > init_declarator > identifier + compound_literal_expression > type_identifier
(declaration
type: (placeholder_type_specifier)
declarator: (init_declarator
declarator: (identifier) @type-binding.name
value: (compound_literal_expression
type: (type_identifier) @type-binding.type))) @type-binding.constructor
;; ─── Type bindings — auto + scoped brace-init (qualified) ───────────
;; Covers: auto client = ns::HttpClient{}
;; AST: compound_literal_expression > qualified_identifier > type_identifier
(declaration
type: (placeholder_type_specifier)
declarator: (init_declarator
declarator: (identifier) @type-binding.name
value: (compound_literal_expression
type: (qualified_identifier
name: (type_identifier) @type-binding.type)))) @type-binding.constructor
;; ─── Type bindings — auto + new expression ──────────────────────────
;; Covers: auto user = new User(name)
;; AST: declaration > placeholder_type_specifier/auto > init_declarator > identifier + new_expression > type_identifier
(declaration
type: (placeholder_type_specifier)
declarator: (init_declarator
declarator: (identifier) @type-binding.name
value: (new_expression
type: (type_identifier) @type-binding.type))) @type-binding.constructor
;; ─── Type bindings — auto + qualified template factory (std::make_shared<Dog>()) ─
;; AST: declaration(1 > placeholder_type_specifier(2)2 > init_declarator(3 >
;; identifier(4)4 > call_expression(5 > qualified_identifier(6 >
;; template_function(7 > template_argument_list(8 > type_descriptor(9 >
;; type_identifier(10)10 )9 )8 )7 )6 )5 )3 )1
(declaration
type: (placeholder_type_specifier)
declarator: (init_declarator
declarator: (identifier) @type-binding.name
value: (call_expression
function: (qualified_identifier
name: (template_function
arguments: (template_argument_list
(type_descriptor
type: (type_identifier) @type-binding.type))))))) @type-binding.constructor
;; ─── Type bindings — auto + bare template factory (make_shared<Dog>()) ───────
;; Same but without qualified_identifier wrapper — one fewer nesting level
(declaration
type: (placeholder_type_specifier)
declarator: (init_declarator
declarator: (identifier) @type-binding.name
value: (call_expression
function: (template_function
arguments: (template_argument_list
(type_descriptor
type: (type_identifier) @type-binding.type)))))) @type-binding.constructor
;; ─── Type bindings — auto alias assignment ──────────────────────────
;; Covers: auto alias = existingVar (RHS is a plain identifier)
;; AST: declaration > placeholder_type_specifier/auto > init_declarator > identifier + identifier
(declaration
type: (placeholder_type_specifier)
declarator: (init_declarator
declarator: (identifier) @type-binding.name
value: (identifier) @type-binding.type)) @type-binding.alias
;; ─── Type bindings — auto + member access (field_expression) ────────
;; Covers: auto addr = user.address (RHS is obj.field)
;; AST: declaration > placeholder_type_specifier > init_declarator > identifier + field_expression
;; We capture the field name as @type-binding.type so the compound-receiver
;; chain resolver can look it up on the receiver class scope.
;; The full obj.field text is synthesized by interpret.ts into a dotted
;; rawName for chain-follow resolution.
(declaration
type: (placeholder_type_specifier)
declarator: (init_declarator
declarator: (identifier) @type-binding.name
value: (field_expression
argument: (_) @type-binding.member-access-receiver
field: (field_identifier) @type-binding.type))) @type-binding.member-access
;; ─── Type bindings — function return type ───────────────────────────
;; Covers: User getUser() { ... }
;; AST: function_definition > type_identifier + function_declarator > identifier
(function_definition
type: (type_identifier) @type-binding.type
declarator: (function_declarator
declarator: (identifier) @type-binding.name)) @type-binding.return
;; Return type — out-of-class method: User Class::getUser() { ... }
(function_definition
type: (type_identifier) @type-binding.type
declarator: (function_declarator
declarator: (qualified_identifier
name: (identifier) @type-binding.name))) @type-binding.return
;; Return type — pointer return: User* getUser() { ... }
(function_definition
type: (type_identifier) @type-binding.type
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (identifier) @type-binding.name))) @type-binding.return
;; ─── Type bindings — inline method return type ──────────────────────
;; Covers: class Foo { User getUser() { ... } };
(function_definition
type: (type_identifier) @type-binding.type
declarator: (function_declarator
declarator: (field_identifier) @type-binding.name)) @type-binding.return
;; Inline method pointer return type: class Foo { User* lookup(int) { ... } };
(function_definition
type: (type_identifier) @type-binding.type
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (field_identifier) @type-binding.name))) @type-binding.return
;; ─── Type bindings — method prototype return type in class body ──────
;; Covers: class User { User* lookup(int); std::string getName(); };
;; AST: field_declaration > function_declarator > field_identifier
(field_declaration
type: (type_identifier) @type-binding.type
declarator: (function_declarator
declarator: (field_identifier) @type-binding.name)) @type-binding.return
;; Method prototype pointer return type: User* lookup(int id);
(field_declaration
type: (type_identifier) @type-binding.type
declarator: (pointer_declarator
declarator: (function_declarator
declarator: (field_identifier) @type-binding.name))) @type-binding.return
;; ─── Type bindings — field type declarations (class members) ────────
;; Covers: class User { Address address; };
(field_declaration
type: (type_identifier) @type-binding.type
declarator: (field_identifier) @type-binding.name) @type-binding.field
;; Field pointer type: Address* address;
(field_declaration
type: (type_identifier) @type-binding.type
declarator: (pointer_declarator
declarator: (field_identifier) @type-binding.name)) @type-binding.field
;; Field reference type: Address& address;
(field_declaration
type: (type_identifier) @type-binding.type
declarator: (reference_declarator
(field_identifier) @type-binding.name)) @type-binding.field
;; ─── References — constructor calls (new Foo()) ─────────────────────
(new_expression
type: (type_identifier) @reference.name) @reference.call.constructor
;; Constructor call with qualified type: new ns::Foo()
(new_expression
type: (qualified_identifier
name: (type_identifier) @reference.name)) @reference.call.constructor
;; ─── References — free calls ────────────────────────────────────────
(call_expression
function: (identifier) @reference.name) @reference.call.free
;; ─── References — qualified calls (Namespace func or Class method) ───
;; Capture the LHS of scope-resolution as the explicit receiver so
;; qualified static member calls route through receiver-bound-calls
;; Case 2 (class-name receiver) path. Without the receiver capture,
;; qualified calls have no explicit receiver and class methods cannot
;; resolve through receiver-bound paths.
(call_expression
function: (qualified_identifier
scope: (_) @reference.receiver
name: (identifier) @reference.name)) @reference.call.qualified
;; Nested qualified receiver: outer::v1::Base<T>::f()
;; tree-sitter-cpp nests this as qualified_identifier(name:
;; qualified_identifier(scope: qualified_identifier(...), name: identifier)).
;; Capturing the innermost receiver still gives isSuperReceiverInContext
;; enough text to strip qualifiers/template args down to Base.
(call_expression
function: (qualified_identifier
name: (qualified_identifier
scope: (_) @reference.receiver
name: (identifier) @reference.name))) @reference.call.qualified
;; Double-nested qualified receiver: outer::v1::Base<T>::f()
(call_expression
function: (qualified_identifier
name: (qualified_identifier
name: (qualified_identifier
scope: (_) @reference.receiver
name: (identifier) @reference.name)))) @reference.call.qualified
;; ─── References — member calls (obj.method() / ptr->method()) ───────
(call_expression
function: (field_expression
argument: (_) @reference.receiver
field: (field_identifier) @reference.name)) @reference.call.member
;; ─── References — template calls (func<T>()) ────────────────────────
(call_expression
function: (template_function
name: (identifier) @reference.name)) @reference.call.free
;; Note: Ns::func<T>() is parsed as qualified_identifier by tree-sitter-cpp,
;; already captured by the qualified calls pattern above.
;; ─── References — field reads ───────────────────────────────────────
(field_expression
argument: (_) @reference.receiver
field: (field_identifier) @reference.name) @reference.read
;; ─── References — field writes (assignment) ─────────────────────────
(assignment_expression
left: (field_expression
argument: (_) @reference.receiver
field: (field_identifier) @reference.name)) @reference.write
`;
let _parser: Parser | null = null;
let _query: Parser.Query | null = null;
export function getCppParser(): Parser {
if (_parser === null) {
_parser = new Parser();
_parser.setLanguage(CPP as Parameters<Parser['setLanguage']>[0]);
}
return _parser;
}
export function getCppScopeQuery(): Parser.Query {
if (_query === null) {
_query = new Parser.Query(CPP as Parameters<Parser['setLanguage']>[0], CPP_SCOPE_QUERY);
}
return _query;
}

255
gitnexus/src/core/ingestion/languages/cpp/range-bindings.ts Normal file
View file

@ -0,0 +1,255 @@
import type { ParsedFile, Scope, TypeRef } from 'gitnexus-shared';
import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
import { getCppParser } from './query.js';
import { getTreeSitterBufferSize } from '../../constants.js';
import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
/**
* Populate range-for loop variable type bindings for C++.
*
* Handles three patterns:
* 1. `for (auto& user : users)` — simple range-for
* 2. `for (auto& [key, user] : userMap)` — structured binding
* 3. `for (auto& user : *usersPtr)` — dereference range-for
*
* Strategy: look up the range source variable's type in scope
* typeBindings, extract the last template argument as the element
* type, and inject a typeBinding for the loop variable.
*/
export function populateCppRangeBindings(
parsedFiles: readonly ParsedFile[],
_indexes: ScopeResolutionIndexes,
ctx: {
readonly fileContents: ReadonlyMap<string, string>;
readonly treeCache?: { get(filePath: string): unknown };
},
): void {
const parser = getCppParser();
for (const parsed of parsedFiles) {
const sourceText = ctx.fileContents.get(parsed.filePath);
if (sourceText === undefined) continue;
const cachedTree = ctx.treeCache?.get(parsed.filePath);
const tree =
(cachedTree as ReturnType<typeof parser.parse> | undefined) ??
parseSourceSafe(parser, sourceText, undefined, {
bufferSize: getTreeSitterBufferSize(sourceText),
});
const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');
if (moduleScope === undefined) continue;
const scopeMap = new Map(parsed.scopes.map((s) => [s.id, s]));
// Build a map from parameter name → AST parameter_declaration node
// so we can extract the un-normalized template type from the AST.
const paramTypeMap = buildParamTemplateMap(tree.rootNode);
for (const rangeNode of tree.rootNode.descendantsOfType('for_range_loop')) {
// Get the declarator (loop variable)
const declarator = rangeNode.childForFieldName('declarator');
if (declarator === null) continue;
// Get the range source expression (right side of ':')
const right = rangeNode.childForFieldName('right');
if (right === null) continue;
// Determine the loop variable name(s) and whether this is a structured binding
const varNames = extractLoopVarNames(declarator);
if (varNames.length === 0) continue;
// Determine the range source variable name (handle dereference)
const sourceVarName = extractSourceVarName(right);
if (sourceVarName === null) continue;
// Look up the source variable's full template type from the AST
// (scope typeBindings have been normalized and lost template params)
const fullType = paramTypeMap.get(sourceVarName);
if (fullType === undefined) continue;
// Extract element type from the container type
const elementType = extractCppElementType(fullType);
if (elementType === null) continue;
// Find the enclosing function scope
const functionScope = findEnclosingFunctionScope(rangeNode, scopeMap);
const targetScope = functionScope ?? moduleScope;
const mutable = targetScope.typeBindings as Map<string, TypeRef>;
// For structured binding [key, user], bind the last identifier to the element type
// For simple range-for, bind the single variable
const bindVar = varNames[varNames.length - 1];
mutable.set(bindVar, {
rawName: elementType,
declaredAtScope: targetScope.id,
source: 'annotation',
});
}
}
}
/** Minimal tree-sitter node shape needed by range-binding helpers. */
interface TsNode {
readonly type: string;
readonly text: string;
readonly childCount: number;
child(index: number): TsNode | null;
descendantsOfType(type: string): readonly TsNode[];
childForFieldName(name: string): TsNode | null;
}
/**
* Build a map from parameter name → full (un-normalized) type text
* by walking the AST for all `parameter_declaration` nodes.
*
* This bypasses `normalizeCppTypeName` which strips template params,
* giving us the raw `std::vector<User>` text needed for element-type
* extraction.
*/
function buildParamTemplateMap(rootNode: TsNode): Map<string, string> {
const map = new Map<string, string>();
for (const paramNode of rootNode.descendantsOfType('parameter_declaration')) {
const typeNode = paramNode.childForFieldName('type');
if (typeNode === null) continue;
// Extract the parameter name from the declarator subtree.
// The declarator may be: identifier, reference_declarator > identifier,
// or pointer_declarator > identifier.
const declNode = paramNode.childForFieldName('declarator');
if (declNode === null) continue;
const idents = declNode.descendantsOfType('identifier');
if (idents.length === 0) continue;
const paramName = idents[idents.length - 1].text;
// Use the full type node text (preserving template params)
map.set(paramName, typeNode.text);
}
return map;
}
/**
* Extract loop variable name(s) from the declarator node.
* Handles both simple `identifier` and `structured_binding_declarator`.
*/
function extractLoopVarNames(declarator: TsNode): string[] {
// The declarator is typically reference_declarator or pointer_declarator wrapping
// either an identifier or a structured_binding_declarator.
const structBindings = declarator.descendantsOfType('structured_binding_declarator');
if (structBindings.length > 0) {
// structured_binding_declarator contains identifiers like [key, user]
const idents = structBindings[0].descendantsOfType('identifier');
return idents.map((id) => id.text).filter((t) => t !== '_');
}
// Simple case: reference_declarator > identifier or just identifier
const idents = declarator.descendantsOfType('identifier');
if (idents.length > 0) {
return [idents[idents.length - 1].text];
}
return [];
}
/**
* Extract the source variable name from the range expression.
* Handles plain identifiers and dereference expressions (*ptr).
*/
function extractSourceVarName(right: TsNode): string | null {
if (right.type === 'identifier') {
return right.text;
}
if (right.type === 'pointer_expression') {
// *usersPtr → get the argument (usersPtr)
const arg = right.childForFieldName('argument');
if (arg !== null) return arg.text;
}
return null;
}
/**
* Extract the element type from a C++ container type string.
*
* Examples:
* - `vector<User>` → `User`
* - `std::vector<User>` → `User`
* - `map<std::string, User>` → `User` (last template arg)
* - `map<string, User>` → `User`
*
* For structured bindings with maps, the last template arg is the value type.
* For vectors/sets, the first (and only) template arg is the element type.
*/
function extractCppElementType(rawType: string): string | null {
// Find the outermost template argument list
const ltIdx = rawType.indexOf('<');
if (ltIdx === -1) return null;
// Extract the template argument string (handle nested templates)
let depth = 0;
let lastCommaOrStart = ltIdx + 1;
let lastArg = '';
for (let i = ltIdx; i < rawType.length; i++) {
const ch = rawType[i];
if (ch === '<') {
depth++;
} else if (ch === '>') {
depth--;
if (depth === 0) {
lastArg = rawType.slice(lastCommaOrStart, i).trim();
break;
}
} else if (ch === ',' && depth === 1) {
lastCommaOrStart = i + 1;
}
}
if (lastArg === '') return null;
// Strip pointer/reference qualifiers and const
let elementType = lastArg
.replace(/^const\s+/, '')
.replace(/\s*[*&]+\s*$/, '')
.trim();
// Strip namespace prefix (std::string → string)
const lastColon = elementType.lastIndexOf('::');
if (lastColon !== -1) {
elementType = elementType.slice(lastColon + 2);
}
return elementType || null;
}
/**
* Find the enclosing Function scope for a tree-sitter node by
* walking up the AST and matching source positions.
*/
function findEnclosingFunctionScope(
node: unknown,
scopeMap: ReadonlyMap<string, Scope>,
): Scope | null {
const tsNode = node as {
readonly parent: unknown;
readonly type: string;
readonly startPosition: { readonly row: number; readonly column: number };
};
let current: typeof tsNode | null = tsNode;
while (current !== null) {
if (current.type === 'function_definition') {
for (const scope of scopeMap.values()) {
if (
scope.kind === 'Function' &&
scope.range.startLine === current.startPosition.row &&
scope.range.startCol === current.startPosition.column
) {
return scope;
}
}
break;
}
current = (current.parent as typeof tsNode) ?? null;
}
return null;
}

280
gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts Normal file
View file

@ -0,0 +1,280 @@
import type { ParsedFile, SymbolDefinition } from 'gitnexus-shared';
import {
findClassBindingInScope,
findEnclosingClassDef,
} from '../../scope-resolution/scope/walkers.js';
import { SupportedLanguages } from 'gitnexus-shared';
import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
import { cppProvider } from '../c-cpp.js';
import { cppArityCompatibility } from './arity.js';
import { cppConversionRank } from './conversion-rank.js';
import { cppMergeBindings } from './merge-bindings.js';
import { resolveCppImportTarget } from './import-target.js';
import { scanCppHeaderFiles } from './header-scan.js';
import {
expandCppWildcardNames,
isFileLocal,
clearFileLocalNames,
populateCppAnonymousNamespaceScopes,
populateCppNonGloballyVisible,
isCppDefGloballyVisible,
} from './file-local-linkage.js';
import {
populateCppDependentBases,
clearCppDependentBases,
isCppDependentBaseMember,
} from './two-phase-lookup.js';
import { populateCppAssociatedNamespaces, clearCppAdlState, pickCppAdlCandidates } from './adl.js';
import {
clearCppInlineNamespaces,
populateCppInlineNamespaceScopes,
resolveCppQualifiedNamespaceMember,
} from './inline-namespaces.js';
import { populateCppRangeBindings } from './range-bindings.js';
import { cppConstraintCompatibility } from './constraint-filter.js';
/**
* C++ `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
* the generic `runScopeResolution` orchestrator (RFC #909 Ring 3).
*
* C++ extends C's scope resolution with:
* - Namespaces (`namespace foo { ... }`)
* - Classes with methods and multiple inheritance
* - `using namespace` (wildcard import from namespace)
* - `using X::name` (named import from namespace)
* - Anonymous namespace (file-local linkage, like C `static`)
* - Default parameters (requiredParameterCount < parameterCount)
* - Overloading (arity-based disambiguation)
* - Templates (V1: generic-ignored, `List<User>` ≡ `List`)
* - Leftmost-base MRO for multiple inheritance
*/
export const cppScopeResolver: ScopeResolver = {
language: SupportedLanguages.CPlusPlus,
languageProvider: cppProvider,
importEdgeReason: 'cpp-scope: include',
loadResolutionConfig: (repoPath: string) => {
// Clear stale per-pipeline state from any previous invocation.
clearFileLocalNames();
clearCppDependentBases();
clearCppAdlState();
clearCppInlineNamespaces();
return scanCppHeaderFiles(repoPath);
},
resolveImportTarget: (targetRaw, fromFile, allFilePaths, resolutionConfig) => {
// Augment allFilePaths with header files discovered via loadResolutionConfig.
// C++ .h/.hpp/.hxx/.hh files may be classified differently by language
// detection but are importable from .cpp files via #include.
const headerPaths = resolutionConfig as ReadonlySet<string> | undefined;
if (headerPaths !== undefined && headerPaths.size > 0) {
const augmented = new Set(allFilePaths);
for (const h of headerPaths) augmented.add(h);
return resolveCppImportTarget(targetRaw, fromFile, augmented);
}
return resolveCppImportTarget(targetRaw, fromFile, allFilePaths);
},
expandsWildcardTo: (targetModuleScope, parsedFiles) =>
expandCppWildcardNames(targetModuleScope, parsedFiles),
mergeBindings: (existing, incoming, scopeId) => cppMergeBindings(existing, incoming, scopeId),
// Adapter: cppArityCompatibility predates ScopeResolver and uses
// (def, callsite). ScopeResolver contract is (callsite, def).
arityCompatibility: (callsite, def) => cppArityCompatibility(def, callsite),
// SFINAE / `requires`-clause aware overload filter (issue #1579).
// Drops candidates whose template constraints (`enable_if_t<P, T>`,
// C++20 `requires P`) provably fail at the call site. Three-valued —
// `'unknown'` keeps the candidate, preserving "degrade not lie".
constraintCompatibility: cppConstraintCompatibility,
buildMro: (graph, parsedFiles, nodeLookup) =>
buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
populateOwners: (parsed: ParsedFile) => {
populateClassOwnedMembers(parsed);
// Resolve inline- and anonymous-namespace ranges (recorded at capture
// time) to ScopeIds BEFORE `populateCppNonGloballyVisible` runs, so
// both exemptions see the populated Sets.
populateCppInlineNamespaceScopes(parsed);
populateCppAnonymousNamespaceScopes(parsed);
// Track namespace-nested and class-nested defs so the global free-call
// fallback and wildcard expansion can suppress them as unqualified
// cross-file callables.
populateCppNonGloballyVisible(parsed);
// Build the class-def → enclosing-namespace-qualified-name map used
// by ADL (U2 of plan 2026-05-13-001) to identify each argument type's
// associated namespace for Koenig lookup.
populateCppAssociatedNamespaces(parsed);
},
// Resolve recorded template-class → dependent-base simple names to
// class nodeIds for two-phase template lookup (U3 of plan
// 2026-05-13-001). Runs AFTER all files have had `populateOwners`
// applied so that cross-file base classes (e.g. Base in base.h,
// Derived in derived.h) are reachable in the workspace index.
populateWorkspaceOwners: (parsedFiles: readonly ParsedFile[]) => {
populateCppDependentBases(parsedFiles);
},
// Simple `isSuperReceiver` returns false for C++. Real super
// classification is caller-context-dependent and lives in
// `isSuperReceiverInContext` below — without scope context the
// previous regex `/^[A-Z]\w*::/` misclassified namespace-qualified
// calls (e.g., `Singleton::getInstance()`) as super calls and routed
// them through the wrong resolution branch.
isSuperReceiver: () => false,
isSuperReceiverInContext: (text, callerScope, scopes) => {
// The receiver text comes from the LHS of `::` in `qualified_identifier`
// (e.g., for `Base<T>::method()`, text is `Base<T>`). Strip template
// arguments (V1: name-only matching, generics ignored) and any leading
// namespace qualifier so the lookup matches the bare class def's
// simple name. `Base<T>::method()` → `Base`; `outer::v1::Base<T>` →
// `Base`. This handles the Phase 5 cross-unit composition where
// qualified base-method calls appear inside template bodies.
let lhs = text;
const sepIdx = lhs.indexOf('::');
if (sepIdx > 0) lhs = lhs.slice(0, sepIdx).trim();
// Strip trailing template-argument list (greedy: drop everything from
// the first `<` onward — V1 ignores generics).
const lt = lhs.indexOf('<');
if (lt > 0) lhs = lhs.slice(0, lt).trim();
// Strip nested namespace prefix from the receiver text itself (the
// `outer::v1::Base` shape that appears in derived-list `base_class_clause`).
const lastDoubleColon = lhs.lastIndexOf('::');
if (lastDoubleColon >= 0) lhs = lhs.slice(lastDoubleColon + 2).trim();
if (lhs.length === 0) return false;
// Resolve the LHS in the caller's scope chain. Only class-like
// resolutions can be super receivers; Namespace and unresolved
// names are not super calls.
const lhsDef = findClassBindingInScope(callerScope, lhs, scopes);
if (lhsDef === undefined) return false;
// The caller must have an enclosing class — super calls only make
// sense inside a class body. Free functions can use `ClassName::`
// for namespace-qualified calls but those are not super.
const enclosing = findEnclosingClassDef(callerScope, scopes);
if (enclosing === undefined) return false;
// `lhsDef` must be in the caller's MRO (i.e., the caller's enclosing
// class derives from it). The class itself counts as its own MRO
// root — `Self::method()` is a qualified self-call, not a super
// call, so exclude the caller's own class.
if (lhsDef.nodeId === enclosing.nodeId) return false;
const mro = scopes.methodDispatch.mroFor(enclosing.nodeId);
return mro.includes(lhsDef.nodeId);
},
// C++ is statically typed — disable field fallback heuristic
fieldFallbackOnMethodLookup: false,
// C++ needs return type propagation across #include boundaries
propagatesReturnTypesAcrossImports: true,
// C++ #include brings in all symbols — enable global free call fallback
allowGlobalFreeCallFallback: true,
// C++ standard-conversion-sequence ranking for overload resolution (#1578).
// Disambiguates `f(int)` vs `f(double)` called with `f(2.5)` by scoring
// each candidate's conversion cost; exact match wins over standard conversion.
conversionRankFn: cppConversionRank,
// Range-for element type inference: for (auto& user : users) → bind user to User
populateRangeBindings: populateCppRangeBindings,
// C++ method return-type bindings need to be visible from module scope
// for cross-file propagation and compound-receiver chain resolution.
// cppBindingScopeFor hoists @type-binding.return to Module scope.
hoistTypeBindingsToModule: true,
// Enable receiver-bound explicit-`this` fallback only for C++.
resolveThisViaEnclosingClass: true,
// The `isFileLocalDef` hook on the global free-call fallback names
// file-local linkage historically, but semantically gates "logically
// invisible cross-file" defs. C++ extends this to also reject class-
// owned methods/fields and namespace-nested symbols — an unqualified
// call from a free function MUST NOT resolve to `User::save` or
// `ns::foo` (Cppreference, "Unqualified name lookup"). Without this
// gate, the global fallback walks every callable in the workspace
// registry and matches any class method or namespace function by
// simple name.
isFileLocalDef: (def: SymbolDefinition) => {
const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? '';
if (isFileLocal(def.filePath, simple)) return true;
// Class-owned (Method/Field) — `populateClassOwnedMembers` already
// stamps `ownerId`; cheap fast-path before consulting the scope map.
if (def.ownerId !== undefined) return true;
// Namespace-nested defs — require qualification cross-file. Scope-
// walked at `populateOwners` time into a per-file nodeId set.
if (!isCppDefGloballyVisible(def.filePath, def.nodeId)) return true;
return false;
},
// C++ two-phase template lookup: inside a class template body,
// unqualified calls MUST NOT bind to members of a dependent base
// class. The standard requires `this->name()` or `Base<T>::name()`
// forms to make the lookup dependent. Without this gate the global
// free-call fallback walks the workspace registry and silently binds
// unqualified calls to dependent-base members, producing CALLS edges
// the compiler would reject. See plan 2026-05-13-001 U3.
isCallableVisibleFromCaller: ({ candidate, callerScope, scopes }) => {
if (callerScope === undefined || scopes === undefined) return true;
// Reject when the candidate is a member of a dependent base of the
// caller's enclosing template class. Otherwise allow.
return !isCppDependentBaseMember(callerScope, candidate, scopes);
},
// C++ argument-dependent / Koenig lookup (U2 of plan 2026-05-13-001).
// Contributes candidates from associated namespaces of class-typed
// arguments; caller merges with ordinary unqualified lookup candidates.
// Current boundary: class-typed value/pointer/reference args and template
// specializations with explicit type arguments contribute associated
// namespaces. Function-pointer args and full conversion-ranking remain
// excluded.
resolveAdlCandidates: (site, callerParsed, scopes, parsedFiles) => {
// `using ns::name;` introduces `name` into ordinary unqualified lookup.
// For template-class method bodies, lexical scope walks can miss this
// named-using visibility; recover by resolving the imported namespace
// member directly when the local call name matches a named using import.
const usingNamedHits: SymbolDefinition[] = [];
const seenUsing = new Set<string>();
for (const imp of callerParsed.parsedImports) {
if (imp.kind !== 'named') continue;
if (imp.localName !== site.name) continue;
const member = resolveCppQualifiedNamespaceMember(
imp.targetRaw,
imp.importedName,
parsedFiles,
scopes,
);
if (member === undefined || member === 'ambiguous') continue;
if (seenUsing.has(member.nodeId)) continue;
seenUsing.add(member.nodeId);
usingNamedHits.push(member);
}
const adlHits = pickCppAdlCandidates(site, callerParsed, scopes, parsedFiles);
if (usingNamedHits.length === 0) return adlHits;
if (adlHits === undefined || adlHits.length === 0) return usingNamedHits;
const merged: SymbolDefinition[] = [];
const seen = new Set<string>();
for (const hit of usingNamedHits) {
seen.add(hit.nodeId);
merged.push(hit);
}
for (const hit of adlHits) {
if (seen.has(hit.nodeId)) continue;
seen.add(hit.nodeId);
merged.push(hit);
}
return merged;
},
// C++ qualified namespace-member resolution (U5 of plan 2026-05-13-001).
// Handles `outer::foo()` where `outer` is a namespace (not a class).
// Walks each parsed file's namespace scopes by simple name, then
// descends transitively through inline-namespace children when
// searching for the called member. Returns undefined for non-namespace
// receivers so receiver-bound-calls Case 2 still gets a chance.
resolveQualifiedReceiverMember: (receiverName, memberName, _callerScope, scopes, parsedFiles) =>
resolveCppQualifiedNamespaceMember(receiverName, memberName, parsedFiles, scopes),
};

79
gitnexus/src/core/ingestion/languages/cpp/simple-hooks.ts Normal file
View file

@ -0,0 +1,79 @@
import type {
CaptureMatch,
ParsedImport,
Scope,
ScopeId,
ScopeTree,
TypeRef,
} from 'gitnexus-shared';
/**
* C++ binding scope: default auto-hoist (null) for most declarations.
*
* For `for` statement init-scope variables (e.g. `for (int i = 0; ...)`),
* the variable is scoped to the for-block, not the enclosing function.
* The tree-sitter scope query already captures for_statement as @scope.block,
* so tree-sitter's scope nesting handles this automatically — we return null
* to let the default auto-hoist apply.
*/
export function cppBindingScopeFor(
decl: CaptureMatch,
innermost: Scope,
tree: ScopeTree,
): ScopeId | null {
// Hoist return-type bindings to Module scope so:
// 1. propagateImportedReturnTypes can mirror them across files
// 2. compound-receiver can find method return types via hoistTypeBindingsToModule
if (decl['@type-binding.return'] !== undefined) {
let cur: Scope | undefined = innermost;
while (cur !== undefined && cur.kind !== 'Module') {
const parentId: ScopeId | null = cur.parent ?? null;
if (parentId === null) break;
cur = tree.getScope(parentId);
}
if (cur !== undefined && cur.kind === 'Module') return cur.id;
}
return null; // default auto-hoist for other bindings
}
/**
* C++ import owning scope: default (null).
* #include and using declarations are file-scoped in C++.
*/
export function cppImportOwningScope(
_imp: ParsedImport,
_innermost: Scope,
_tree: ScopeTree,
): ScopeId | null {
return null;
}
/**
* C++ receiver binding: return `this` TypeRef for methods inside a class.
*
* When a function scope is inside a class scope, the implicit `this` pointer
* refers to the enclosing class. This enables `this->method()` and implicit
* `this` member access resolution.
*/
export function cppReceiverBinding(functionScope: Scope): TypeRef | null {
// Walk up the scope tree to find an enclosing class scope
if (functionScope.parent === null) return null;
// The scope tree structure nests function scopes inside class scopes.
// The orchestrator provides the function scope; we need to check if
// its parent chain contains a class scope.
//
// However, the ScopeResolver.receiverBinding contract receives only
// the function Scope (not the full ScopeTree), and the Scope type
// includes `parent` (a ScopeId) but not a reference to the parent
// Scope object.
//
// The orchestrator already handles this by looking up the class owner
// via populateOwners. We return null here and let the shared infra
// handle receiver resolution through the class-ownership mechanism.
//
// This is consistent with how C# and Go handle it — the receiver
// binding is established through populateOwners + the MRO chain,
// not through this hook.
return null;
}

205
gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts Normal file
View file

@ -0,0 +1,205 @@
/**
* C++ two-phase template lookup support.
*
* Inside a class template body, names from a dependent base class are NOT
* found by ordinary unqualified lookup. The standard requires the
* `this->name` or `Base<T>::name` forms to make the lookup dependent.
* GitNexus's global free-call fallback otherwise binds such names to the
* dependent base's members, producing CALLS edges the compiler would
* reject.
*
* This module records — during `emitCppScopeCaptures` — which template
* class declarations have which dependent base class names (per file).
* `populateCppDependentBases` then resolves those names to class nodeIds
* using a workspace-wide registry, building the per-class set the
* `isCppDependentBaseMember` predicate consumes.
*
* Cross-file resolution: `Base<T>` may be declared in a different header
* than `Derived<T>`. `populateCppDependentBases` therefore runs as a
* workspace-wide pass (`populateWorkspaceOwners` hook) after every file
* has had `populateOwners` applied, so all class defs are reachable.
*
* Namespace disambiguation: when multiple classes share a simple name
* (e.g., `Box` in two namespaces), the resolver prefers the candidate
* whose qualified-name prefix (namespace path) matches the deriving
* class's prefix. If no namespace match is found, a unique simple-name
* match is accepted; ambiguous matches (multiple candidates, no
* namespace winner) are skipped conservatively.
*
* NOTE: module-level state, single-process-single-repo use only.
* `clearFileLocalNames()` clears this state alongside file-local linkage
* (see `file-local-linkage.ts`).
*/
import type { ParsedFile, ScopeId, SymbolDefinition } from 'gitnexus-shared';
import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
import { findEnclosingClassDef } from '../../scope-resolution/scope/walkers.js';
/**
* Capture-time record: for each template class declaration in a file,
* the simple names of its dependent base classes.
*
* Key: filePath
* Value: Map<className, Set<dependentBaseSimpleName>>
*/
const dependentBasesByFile = new Map<string, Map<string, Set<string>>>();
/**
* Post-`populateOwners` resolution: per-class-nodeId, the set of
* dependent-base-class nodeIds. Built by `populateCppDependentBases`
* from `dependentBasesByFile` + the workspace registry.
*/
const dependentBaseNodeIds = new Map<string, Set<string>>();
/**
* Record a dependent-base relationship discovered during scope-capture
* emission. `className` is the simple name of the template class;
* `baseName` is the simple name of the dependent base class.
*
* The capture-time recorder uses simple names because the registry
* resolution that maps names → nodeIds runs later (in
* `populateCppDependentBases`).
*/
export function markCppDependentBase(filePath: string, className: string, baseName: string): void {
let perFile = dependentBasesByFile.get(filePath);
if (perFile === undefined) {
perFile = new Map();
dependentBasesByFile.set(filePath, perFile);
}
let bases = perFile.get(className);
if (bases === undefined) {
bases = new Set();
perFile.set(className, bases);
}
bases.add(baseName);
}
/** Clear two-phase-lookup state. Called from `clearFileLocalNames`. */
export function clearCppDependentBases(): void {
dependentBasesByFile.clear();
dependentBaseNodeIds.clear();
}
/**
* Resolve recorded dependent-base simple names to class nodeIds using a
* workspace-wide index. Run as `populateWorkspaceOwners` after every
* file has had `populateOwners` applied, so class defs from ALL files
* are reachable.
*
* Disambiguation strategy (multiple classes sharing a simple name):
* 1. Prefer the candidate whose qualified-name namespace prefix matches
* the deriving class's namespace prefix (same-namespace bias).
* 2. Fall back to accepting a unique simple-name match.
* 3. Skip when multiple candidates exist and no namespace match is
* found (conservative: avoids false associations).
*/
export function populateCppDependentBases(parsedFiles: readonly ParsedFile[]): void {
if (dependentBasesByFile.size === 0) return;
// Build workspace-wide index: simpleName → {nodeId, nsPrefix}[]
// nsPrefix is the dot-joined namespace path (qualifiedName without the
// last segment). Classes at global scope have nsPrefix = ''.
const classesBySimpleName = new Map<string, { nodeId: string; nsPrefix: string }[]>();
for (const parsed of parsedFiles) {
for (const def of parsed.localDefs) {
if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface') continue;
const qn = def.qualifiedName ?? '';
const lastDot = qn.lastIndexOf('.');
const simple = lastDot >= 0 ? qn.slice(lastDot + 1) : qn;
if (simple === '') continue;
const nsPrefix = lastDot >= 0 ? qn.slice(0, lastDot) : '';
let entries = classesBySimpleName.get(simple);
if (entries === undefined) {
entries = [];
classesBySimpleName.set(simple, entries);
}
entries.push({ nodeId: def.nodeId, nsPrefix });
}
}
// Build a filePath → ParsedFile lookup for fast per-file access.
const parsedByFile = new Map<string, ParsedFile>();
for (const parsed of parsedFiles) parsedByFile.set(parsed.filePath, parsed);
for (const [filePath, perFile] of dependentBasesByFile) {
const parsed = parsedByFile.get(filePath);
if (parsed === undefined) continue;
// Build a simple-name → {nodeId, nsPrefix} map for THIS file's
// class-like defs so we can identify each template class precisely
// (avoids cross-file name collisions for the deriving class itself).
const localClassByName = new Map<string, { nodeId: string; nsPrefix: string }>();
for (const def of parsed.localDefs) {
if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface') continue;
const qn = def.qualifiedName ?? '';
const lastDot = qn.lastIndexOf('.');
const simple = lastDot >= 0 ? qn.slice(lastDot + 1) : qn;
if (simple === '') continue;
const nsPrefix = lastDot >= 0 ? qn.slice(0, lastDot) : '';
localClassByName.set(simple, { nodeId: def.nodeId, nsPrefix });
}
for (const [className, baseNames] of perFile) {
const classEntry = localClassByName.get(className);
if (classEntry === undefined) continue;
let bases = dependentBaseNodeIds.get(classEntry.nodeId);
if (bases === undefined) {
bases = new Set();
dependentBaseNodeIds.set(classEntry.nodeId, bases);
}
for (const baseName of baseNames) {
const candidates = classesBySimpleName.get(baseName);
if (candidates === undefined || candidates.length === 0) continue;
if (candidates.length === 1) {
// Unique simple-name match — accept regardless of namespace.
bases.add(candidates[0].nodeId);
continue;
}
// Multiple classes share the same simple name — prefer the one
// whose namespace matches the deriving class's namespace.
// V1: exact dot-prefix match only. Cross-namespace inheritance
// (e.g., `ns::outer::Derived` extending bare `Inner` defined in
// `ns::outer::inner`) and inline-namespace cases are deferred to
// V2; the conservative skip-on-ambiguity below avoids false
// associations in those edge cases.
const nsMatch = candidates.find((c) => c.nsPrefix === classEntry.nsPrefix);
if (nsMatch !== undefined) {
bases.add(nsMatch.nodeId);
}
// else: ambiguous (multiple candidates, no namespace match) → skip.
}
}
}
}
/**
* Two-phase lookup predicate: is the candidate def a member of a
* dependent base of the caller's enclosing template class?
*
* Used as an additional reject-filter in `pickUniqueGlobalCallable` and
* the receiver-bound member chain walk. ONLY apply for unqualified
* call forms — `this->name` and `Base<T>::name` are dependent lookup
* forms that the standard allows.
*
* Conservative bias: when the caller's enclosing class can't be
* identified, return `false` (let normal resolution proceed). Over-
* rejection is acceptable for the template case because the standard
* itself requires `this->` or qualified forms for dependent base
* access; missing edges here match the compiler's diagnostic shape.
*/
export function isCppDependentBaseMember(
callerScopeId: ScopeId,
candidateDef: SymbolDefinition,
scopes: ScopeResolutionIndexes,
): boolean {
if (candidateDef.ownerId === undefined) return false;
const enclosing = findEnclosingClassDef(callerScopeId, scopes);
if (enclosing === undefined) return false;
const bases = dependentBaseNodeIds.get(enclosing.nodeId);
if (bases === undefined) return false;
return bases.has(candidateDef.ownerId);
}

59
gitnexus/src/core/ingestion/languages/cpp/type-classifier.ts Normal file
View file

@ -0,0 +1,59 @@
/**
* Coarse-grained type classifier for C++ constraint evaluation
* (`<https://en.cppreference.com/w/cpp/types/is_integral>`,
* `<https://en.cppreference.com/w/cpp/types/is_floating_point>`).
*
* Maps a normalized type token (as produced by `normalizeCppParamType` /
* the call-site inference in `captures.ts`) to one of the categories
* the `<type_traits>` predicate registry uses for SFINAE filtering.
*
* Intentionally coarse: cv / pointer / reference qualifiers are stripped
* upstream by `normalizeCppParamType`. Tier-A predicates
* (`is_integral_v`, `is_floating_point_v`, `is_arithmetic_v`, `is_same_v`)
* are insensitive to those modifiers per ISO `<type_traits>` semantics
* ("including any cv-qualified variants").
*/
export type TypeClass =
| 'integral'
| 'floating'
| 'bool'
| 'char'
| 'string'
| 'null'
| 'class'
| 'unknown';
/**
* Classify a normalized C++ type token. The mapping mirrors the literal-
* inference table in `captures.ts:inferCppLiteralType` plus the std::
* normalization in `arity-metadata.ts:normalizeCppParamType`.
*
* Caller note: token must already be normalized (no `const`, no `&` / `*`,
* no `std::` prefix). Tokens passed via `ConstraintContext.argumentTypes`
* coming from `inferCppCallArgTypes` satisfy this.
*/
export function classifyType(token: string): TypeClass {
if (token.length === 0) return 'unknown';
switch (token) {
case 'int':
return 'integral';
case 'double':
case 'float':
return 'floating';
case 'bool':
return 'bool';
case 'char':
return 'char';
case 'string':
return 'string';
case 'null':
return 'null';
default:
// After normalization, anything that isn't a recognized primitive
// is assumed to be a class-like type. The Tier-A predicate registry
// doesn't introspect class types — `is_integral_v` etc. simply
// returns `false` for `'class'`, matching ISO behavior.
return 'class';
}
}

22
gitnexus/src/core/ingestion/languages/java.ts
View file

@ -27,6 +27,17 @@ import { javaMethodConfig } from '../method-extractors/configs/jvm.js';
import { createVariableExtractor } from '../variable-extractors/generic.js';
import { javaVariableConfig } from '../variable-extractors/configs/jvm.js';
import { createHeritageExtractor } from '../heritage-extractors/generic.js';
import {
emitJavaScopeCaptures,
interpretJavaImport,
interpretJavaTypeBinding,
javaBindingScopeFor,
javaImportOwningScope,
javaMergeBindings,
javaReceiverBinding,
javaArityCompatibility,
resolveJavaImportTarget,
} from './java/index.js';
export const javaProvider = defineLanguage({
id: SupportedLanguages.Java,
@ -65,4 +76,15 @@ export const javaProvider = defineLanguage({
variableExtractor: createVariableExtractor(javaVariableConfig),
classExtractor: createClassExtractor(javaClassConfig),
heritageExtractor: createHeritageExtractor(SupportedLanguages.Java),
// ── RFC #909 Ring 3: scope-based resolution hooks ──
emitScopeCaptures: emitJavaScopeCaptures,
interpretImport: interpretJavaImport,
interpretTypeBinding: interpretJavaTypeBinding,
bindingScopeFor: javaBindingScopeFor,
importOwningScope: javaImportOwningScope,
mergeBindings: (_scope, bindings) => javaMergeBindings(bindings),
receiverBinding: javaReceiverBinding,
arityCompatibility: javaArityCompatibility,
resolveImportTarget: resolveJavaImportTarget,
});

49
gitnexus/src/core/ingestion/languages/java/arity-metadata.ts Normal file
View file

@ -0,0 +1,49 @@
/**
* Extract Java arity metadata from a method-like tree-sitter node —
* `method_declaration` or `constructor_declaration`.
*
* Reuses `javaMethodConfig.extractParameters` so scope-extracted defs
* carry the same arity semantics as the legacy parse-worker path:
* - varargs (`...`) collapses `parameterCount` to `undefined`
* - `parameterTypes` collects declared type names; a literal
* `'varargs'` marker is appended for variadic methods so
* `javaArityCompatibility` can detect them.
*/
import type { SyntaxNode } from '../../utils/ast-helpers.js';
import { javaMethodConfig } from '../../method-extractors/configs/jvm.js';
export interface JavaArityMetadata {
readonly parameterCount: number | undefined;
readonly requiredParameterCount: number | undefined;
readonly parameterTypes: readonly string[] | undefined;
}
export function computeJavaArityMetadata(fnNode: SyntaxNode): JavaArityMetadata {
const params = javaMethodConfig.extractParameters?.(fnNode) ?? [];
let hasVariadic = false;
const types: string[] = [];
for (const p of params) {
if (p.isVariadic) hasVariadic = true;
if (p.type !== null) types.push(p.type);
}
if (hasVariadic) types.push('varargs');
const total = params.length;
// For varargs methods, `parameterCount` (max) is unknown — any number of
// trailing arguments is valid. But the fixed-prefix parameters (everything
// before the variadic `...` param) are still required, so we preserve that
// count in `requiredParameterCount` so `javaArityCompatibility` can reject
// calls that undersupply the fixed prefix (e.g. `f(int x, String... args)`
// called with 0 args).
const fixedCount = params.filter((p) => !p.isVariadic).length;
const parameterCount = hasVariadic ? undefined : total;
const requiredParameterCount = hasVariadic ? fixedCount : total;
return {
parameterCount,
requiredParameterCount,
parameterTypes: types.length > 0 ? types : undefined,
};
}

31
gitnexus/src/core/ingestion/languages/java/arity.ts Normal file
View file

@ -0,0 +1,31 @@
/**
* Java arity check, accommodating varargs (`...`).
*
* Verdicts:
* - `'compatible'` — argCount matches parameterCount, OR varargs present.
* - `'incompatible'` — argCount mismatches with no varargs.
* - `'unknown'` — metadata absent / incomplete.
*/
import type { Callsite, SymbolDefinition } from 'gitnexus-shared';
export function javaArityCompatibility(
def: SymbolDefinition,
callsite: Callsite,
): 'compatible' | 'unknown' | 'incompatible' {
const max = def.parameterCount;
const min = def.requiredParameterCount;
if (max === undefined && min === undefined) return 'unknown';
const argCount = callsite.arity;
if (!Number.isFinite(argCount) || argCount < 0) return 'unknown';
const hasVarArgs =
def.parameterTypes !== undefined &&
def.parameterTypes.some((t) => t === 'varargs' || t.includes('...'));
if (min !== undefined && argCount < min) return 'incompatible';
if (max !== undefined && argCount > max && !hasVarArgs) return 'incompatible';
return 'compatible';
}

30
gitnexus/src/core/ingestion/languages/java/cache-stats.ts Normal file
View file

@ -0,0 +1,30 @@
/**
* Dev-mode counters for the cross-phase scope-captures parse cache
* (Java mirror of `languages/csharp/cache-stats.ts`).
*
* Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
* increment into dead code via the module-level `PROF` constant, so
* the hot path in `captures.ts` stays branch-free.
*/
const PROF = process.env.PROF_SCOPE_RESOLUTION === '1';
let CACHE_HITS = 0;
let CACHE_MISSES = 0;
export function recordCacheHit(): void {
if (PROF) CACHE_HITS++;
}
export function recordCacheMiss(): void {
if (PROF) CACHE_MISSES++;
}
export function getJavaCaptureCacheStats(): { hits: number; misses: number } {
return { hits: CACHE_HITS, misses: CACHE_MISSES };
}
export function resetJavaCaptureCacheStats(): void {
CACHE_HITS = 0;
CACHE_MISSES = 0;
}

235
gitnexus/src/core/ingestion/languages/java/captures.ts Normal file
View file

@ -0,0 +1,235 @@
/**
* `emitScopeCaptures` for Java.
*
* Drives the Java scope query against tree-sitter-java and groups raw
* matches into `CaptureMatch[]` for the central extractor. Layers:
*
* 1. **Decomposed import declarations** — each `import_declaration`
* is re-emitted with `@import.kind/source/name` markers.
* 2. **Receiver binding synthesis** — `this`/`super` type-bindings
* on instance methods.
* 3. **Arity metadata** on method/constructor declarations.
* 4. **Reference arity** on call sites.
*
* Pure given the input source text. No I/O, no globals consulted.
*/
import type { Capture, CaptureMatch } from 'gitnexus-shared';
import { findNodeAtRange, nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
import { splitImportDeclaration } from './import-decomposer.js';
import { computeJavaArityMetadata } from './arity-metadata.js';
import { synthesizeJavaReceiverBinding } from './receiver-binding.js';
import { getJavaParser, getJavaScopeQuery } from './query.js';
import { recordCacheHit, recordCacheMiss } from './cache-stats.js';
import { getTreeSitterBufferSize } from '../../constants.js';
import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
/** Declaration anchors that carry function-like arity metadata. */
const FUNCTION_DECL_TAGS = ['@declaration.method', '@declaration.constructor'] as const;
/** tree-sitter-java node types that the method extractor accepts. */
const FUNCTION_NODE_TYPES = ['method_declaration', 'constructor_declaration'] as const;
/** Suppress read.member emissions when the field_access is already
* covered by a method_invocation (object of a call) or an
* assignment_expression (write target). */
function shouldEmitReadMember(memberNode: SyntaxNode): boolean {
const parent = memberNode.parent;
if (parent === null) return true;
switch (parent.type) {
case 'method_invocation':
// Don't emit read.member when the field_access is the object of a method_invocation
// (the method call already handles this relationship)
return parent.childForFieldName('object')?.id !== memberNode.id;
case 'assignment_expression':
return parent.childForFieldName('left')?.id !== memberNode.id;
default:
return true;
}
}
export function emitJavaScopeCaptures(
sourceText: string,
_filePath: string,
cachedTree?: unknown,
): readonly CaptureMatch[] {
let tree = cachedTree as ReturnType<ReturnType<typeof getJavaParser>['parse']> | undefined;
if (tree === undefined) {
tree = parseSourceSafe(getJavaParser(), sourceText, undefined, {
bufferSize: getTreeSitterBufferSize(sourceText),
});
recordCacheMiss();
} else {
recordCacheHit();
}
const rawMatches = getJavaScopeQuery().matches(tree.rootNode);
const out: CaptureMatch[] = [];
for (const m of rawMatches) {
const grouped: Record<string, Capture> = {};
for (const c of m.captures) {
const tag = '@' + c.name;
grouped[tag] = nodeToCapture(tag, c.node);
}
if (Object.keys(grouped).length === 0) continue;
// Decompose each `import_declaration`.
if (grouped['@import.statement'] !== undefined) {
const stmtCapture = grouped['@import.statement'];
const stmtNode = findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_declaration');
if (stmtNode !== null) {
const decomposed = splitImportDeclaration(stmtNode);
if (decomposed !== null) {
out.push(decomposed);
continue;
}
}
out.push(grouped);
continue;
}
// Skip free-call matches that are actually member calls. The query
// matches ALL method_invocations as @reference.call.free (without
// negation) because tree-sitter-java's query engine drops !object
// patterns when a positive object: pattern exists for the same node
// type. Filter here: if the match has @reference.call.free but also
// has @reference.receiver, it's a member call — skip the free match
// (the separate @reference.call.member match covers it).
if (
grouped['@reference.call.free'] !== undefined &&
grouped['@reference.receiver'] !== undefined
) {
continue;
}
// Filter read.member when it's a child of method_invocation or assignment.
if (grouped['@reference.read.member'] !== undefined) {
const anchor = grouped['@reference.read.member'];
const memberNode = findNodeAtRange(tree.rootNode, anchor.range, 'field_access');
if (memberNode === null || !shouldEmitReadMember(memberNode)) {
continue;
}
}
// Synthesize `this` / `super` receiver type-bindings on every
// instance method-like.
if (grouped['@scope.function'] !== undefined) {
out.push(grouped);
const anchor = grouped['@scope.function']!;
const fnNode = findFunctionNode(tree.rootNode, anchor.range);
if (fnNode !== null) {
for (const synth of synthesizeJavaReceiverBinding(fnNode)) {
out.push(synth);
}
}
continue;
}
// Synthesize arity metadata on function-like declarations.
const declTag = FUNCTION_DECL_TAGS.find((t) => grouped[t] !== undefined);
if (declTag !== undefined) {
const anchor = grouped[declTag]!;
const fnNode = findFunctionNode(tree.rootNode, anchor.range);
if (fnNode !== null) {
const arity = computeJavaArityMetadata(fnNode);
if (arity.parameterCount !== undefined) {
grouped['@declaration.parameter-count'] = syntheticCapture(
'@declaration.parameter-count',
fnNode,
String(arity.parameterCount),
);
}
if (arity.requiredParameterCount !== undefined) {
grouped['@declaration.required-parameter-count'] = syntheticCapture(
'@declaration.required-parameter-count',
fnNode,
String(arity.requiredParameterCount),
);
}
if (arity.parameterTypes !== undefined) {
grouped['@declaration.parameter-types'] = syntheticCapture(
'@declaration.parameter-types',
fnNode,
JSON.stringify(arity.parameterTypes),
);
}
}
}
// Synthesize `@reference.arity` on every callsite.
const callTag = (
['@reference.call.free', '@reference.call.member', '@reference.call.constructor'] as const
).find((t) => grouped[t] !== undefined);
if (callTag !== undefined && grouped['@reference.arity'] === undefined) {
const anchor = grouped[callTag]!;
const callNode =
findNodeAtRange(tree.rootNode, anchor.range, 'method_invocation') ??
findNodeAtRange(tree.rootNode, anchor.range, 'object_creation_expression');
if (callNode !== null) {
const argList = callNode.childForFieldName('arguments');
const args =
argList === null
? []
: argList.namedChildren.filter((c) => c !== null && c.type !== 'comment');
grouped['@reference.arity'] = syntheticCapture(
'@reference.arity',
callNode,
String(args.length),
);
const argTypes = args.map((arg) => inferArgType(arg!));
grouped['@reference.parameter-types'] = syntheticCapture(
'@reference.parameter-types',
callNode,
JSON.stringify(argTypes),
);
}
}
out.push(grouped);
}
return out;
}
type SyntaxNode = ReturnType<ReturnType<typeof getJavaParser>['parse']>['rootNode'];
/** Infer a Java argument's static type from literal patterns. */
function inferArgType(argNode: SyntaxNode): string {
switch (argNode.type) {
case 'decimal_integer_literal':
case 'hex_integer_literal':
case 'octal_integer_literal':
case 'binary_integer_literal':
return 'int';
case 'decimal_floating_point_literal':
case 'hex_floating_point_literal':
return 'double';
case 'string_literal':
return 'String';
case 'character_literal':
return 'char';
case 'true':
case 'false':
return 'boolean';
case 'null_literal':
return 'null';
case 'object_creation_expression': {
const typeNode = argNode.childForFieldName('type');
return typeNode?.text ?? '';
}
default:
return '';
}
}
/** Find the first Java function-like node at the given range. */
function findFunctionNode(rootNode: SyntaxNode, range: Capture['range']): SyntaxNode | null {
for (const nodeType of FUNCTION_NODE_TYPES) {
const n = findNodeAtRange(rootNode, range, nodeType);
if (n !== null) return n as SyntaxNode;
}
return null;
}

104
gitnexus/src/core/ingestion/languages/java/import-decomposer.ts Normal file
View file

@ -0,0 +1,104 @@
/**
* Decompose a Java `import_declaration` into a `CaptureMatch` carrying
* the synthesized markers `@import.kind` / `@import.source` /
* `@import.name` that `interpretJavaImport` consumes.
*
* Unlike C#'s using-directive decomposer, Java has four import forms:
*
* import com.example.User; → named
* import com.example.*; → wildcard
* import static com.example.Utils.format; → static
* import static com.example.Utils.*; → static-wildcard
*
* Each produces exactly one import. The decomposer inspects the raw
* source text and tree-sitter children to determine the flavor.
*/
import type { Capture, CaptureMatch } from 'gitnexus-shared';
import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js';
type ImportKind = 'named' | 'wildcard' | 'static' | 'static-wildcard';
interface ImportSpec {
readonly kind: ImportKind;
/** Full dotted path: `com.example.User`. */
readonly source: string;
/** Local binding name — last path segment for named/static,
* `'*'` for wildcard/static-wildcard. */
readonly name: string;
/** Node to anchor the synthesized captures (range-wise). */
readonly atNode: SyntaxNode;
}
export function splitImportDeclaration(stmtNode: SyntaxNode): CaptureMatch | null {
if (stmtNode.type !== 'import_declaration') return null;
const spec = parseImportDeclaration(stmtNode);
if (spec === null) return null;
return buildImportMatch(stmtNode, spec);
}
function parseImportDeclaration(node: SyntaxNode): ImportSpec | null {
// Detect `static` by checking for an anonymous `static` token child.
let isStatic = false;
for (let i = 0; i < node.childCount; i++) {
const child = node.child(i);
if (child !== null && child.type === 'static') {
isStatic = true;
break;
}
}
// Detect wildcard by checking for `asterisk` named child.
let isWildcard = false;
for (let i = 0; i < node.namedChildCount; i++) {
const child = node.namedChild(i);
if (child !== null && child.type === 'asterisk') {
isWildcard = true;
break;
}
}
// Find the scoped_identifier (or identifier for single-segment imports).
let pathNode: SyntaxNode | null = null;
for (let i = 0; i < node.namedChildCount; i++) {
const child = node.namedChild(i);
if (child !== null && (child.type === 'scoped_identifier' || child.type === 'identifier')) {
pathNode = child;
break;
}
}
if (pathNode === null) return null;
const fullPath = pathNode.text;
if (fullPath === '') return null;
if (isStatic && isWildcard) {
// `import static com.example.Utils.*;`
return { kind: 'static-wildcard', source: fullPath, name: '*', atNode: node };
}
if (isStatic) {
// `import static com.example.Utils.format;`
const lastDot = fullPath.lastIndexOf('.');
const name = lastDot >= 0 ? fullPath.slice(lastDot + 1) : fullPath;
return { kind: 'static', source: fullPath, name, atNode: node };
}
if (isWildcard) {
// `import com.example.*;`
return { kind: 'wildcard', source: fullPath, name: '*', atNode: node };
}
// `import com.example.User;`
const lastDot = fullPath.lastIndexOf('.');
const name = lastDot >= 0 ? fullPath.slice(lastDot + 1) : fullPath;
return { kind: 'named', source: fullPath, name, atNode: node };
}
function buildImportMatch(stmtNode: SyntaxNode, spec: ImportSpec): CaptureMatch {
const m: Record<string, Capture> = {
'@import.statement': nodeToCapture('@import.statement', stmtNode),
'@import.kind': syntheticCapture('@import.kind', spec.atNode, spec.kind),
'@import.source': syntheticCapture('@import.source', spec.atNode, spec.source),
'@import.name': syntheticCapture('@import.name', spec.atNode, spec.name),
};
return m;
}

108
gitnexus/src/core/ingestion/languages/java/import-target.ts Normal file
View file

@ -0,0 +1,108 @@
/**
* Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
*
* Converts Java package paths (dots → slashes) and tries:
* 1. Exact file match: `com/example/User.java`
* 2. Suffix match for nested layouts
* 3. Directory match (wildcard imports)
* 4. Progressive prefix stripping for non-standard layouts
*
* Returns `null` for unresolvable / JDK imports.
*/
import type { ParsedImport, WorkspaceIndex } from 'gitnexus-shared';
export interface JavaResolveContext {
readonly fromFile: string;
readonly allFilePaths: ReadonlySet<string>;
}
export function resolveJavaImportTarget(
parsedImport: ParsedImport,
workspaceIndex: WorkspaceIndex,
): string | null {
const ctx = workspaceIndex as JavaResolveContext | undefined;
if (
ctx === undefined ||
typeof (ctx as { fromFile?: unknown }).fromFile !== 'string' ||
!((ctx as { allFilePaths?: unknown }).allFilePaths instanceof Set)
) {
return null;
}
if (parsedImport.kind === 'dynamic-unresolved') return null;
if (parsedImport.targetRaw === null || parsedImport.targetRaw === '') return null;
// Strip trailing `.*` for wildcard imports: `com.example.*` → `com.example`
let target = parsedImport.targetRaw;
if (target.endsWith('.*')) {
target = target.slice(0, -2);
}
// Package path: `com.example.User` → `com/example/User`
const pathLike = target.replace(/\./g, '/');
const suffix = `/${pathLike}`;
let exactFile: string | null = null;
let suffixFile: string | null = null;
let directoryChild: string | null = null;
const dirPrefix = `${pathLike}/`;
const suffixDirPrefix = `/${dirPrefix}`;
for (const raw of ctx.allFilePaths) {
const f = raw.replace(/\\/g, '/');
if (!f.endsWith('.java')) continue;
if (f === `${pathLike}.java`) {
exactFile = raw;
break;
}
if (suffixFile === null && f.endsWith(`${suffix}.java`)) {
suffixFile = raw;
}
if (directoryChild === null) {
const atRoot = f.startsWith(dirPrefix);
const atNested = f.includes(suffixDirPrefix);
if (atRoot || atNested) {
const idx = atRoot ? 0 : f.indexOf(suffixDirPrefix) + 1;
const after = f.slice(idx + dirPrefix.length);
if (after.length > 0 && !after.includes('/')) {
directoryChild = raw;
}
}
}
}
if (exactFile !== null) return exactFile;
if (suffixFile !== null) return suffixFile;
if (directoryChild !== null) return directoryChild;
// Progressive prefix stripping — handles `import com.example.User;`
// in a repo laid out `User.java` (no `com/example/` prefix).
const segments = pathLike.split('/').filter(Boolean);
for (let skip = 1; skip < segments.length; skip++) {
const tail = segments.slice(skip).join('/');
if (tail === '') continue;
const tailFile = `${tail}.java`;
const tailSuffix = `/${tailFile}`;
const tailDir = `${tail}/`;
const tailSuffixDir = `/${tailDir}`;
let tailDirectChild: string | null = null;
for (const raw of ctx.allFilePaths) {
const f = raw.replace(/\\/g, '/');
if (!f.endsWith('.java')) continue;
if (f === tailFile) return raw;
if (f.endsWith(tailSuffix)) return raw;
if (tailDirectChild === null) {
const atRoot = f.startsWith(tailDir);
const atNested = f.includes(tailSuffixDir);
if (atRoot || atNested) {
const idx = atRoot ? 0 : f.indexOf(tailSuffixDir) + 1;
const after = f.slice(idx + tailDir.length);
if (after.length > 0 && !after.includes('/')) tailDirectChild = raw;
}
}
}
if (tailDirectChild !== null) return tailDirectChild;
}
return null;
}

30
gitnexus/src/core/ingestion/languages/java/index.ts Normal file
View file

@ -0,0 +1,30 @@
/**
* Java scope-resolution hooks (RFC #909 Ring 3).
*
* Public API barrel. Consumers should import from this file rather than
* the individual modules.
*
* Module layout:
*
* - `query.ts` — tree-sitter query + lazy parser/query singletons
* - `captures.ts` — `emitJavaScopeCaptures` orchestrator
* - `import-decomposer.ts` — each `import` → ParsedImport-shaped captures
* - `interpret.ts` — capture-match → `ParsedImport` / `ParsedTypeBinding`
* - `simple-hooks.ts` — small hooks made explicit
* - `receiver-binding.ts` — synthesize `this`/`super` type-bindings on
* instance-method entry
* - `merge-bindings.ts` — Java import precedence
* - `arity.ts` — Java arity compatibility (varargs)
* - `arity-metadata.ts` — synthesize arity metadata from declarations
* - `import-target.ts` — `(ParsedImport, WorkspaceIndex) → file path` adapter
* - `scope-resolver.ts` — `ScopeResolver` registered in `SCOPE_RESOLVERS`
* - `cache-stats.ts` — PROF_SCOPE_RESOLUTION cache hit/miss counters
*/
export { emitJavaScopeCaptures } from './captures.js';
export { getJavaCaptureCacheStats, resetJavaCaptureCacheStats } from './cache-stats.js';
export { interpretJavaImport, interpretJavaTypeBinding } from './interpret.js';
export { javaMergeBindings } from './merge-bindings.js';
export { javaArityCompatibility } from './arity.js';
export { resolveJavaImportTarget, type JavaResolveContext } from './import-target.js';
export { javaBindingScopeFor, javaImportOwningScope, javaReceiverBinding } from './simple-hooks.js';

141
gitnexus/src/core/ingestion/languages/java/interpret.ts Normal file
View file

@ -0,0 +1,141 @@
/**
* Capture-match → semantic-shape interpreters for Java.
*
* - `interpretJavaImport` → `ParsedImport`
* - `interpretJavaTypeBinding` → `ParsedTypeBinding`
*
* Import matches arrive pre-decomposed by `emitJavaScopeCaptures`
* (one import per match, with synthesized `@import.kind/source/name`
* markers). Type-binding matches arrive from the raw query captures.
*/
import type { CaptureMatch, ParsedImport, ParsedTypeBinding, TypeRef } from 'gitnexus-shared';
// ─── interpretImport ──────────────────────────────────────────────────────
export function interpretJavaImport(captures: CaptureMatch): ParsedImport | null {
const kindCap = captures['@import.kind'];
const sourceCap = captures['@import.source'];
const nameCap = captures['@import.name'];
const kind = kindCap?.text;
if (kind === undefined || sourceCap === undefined) return null;
switch (kind) {
case 'named': {
// `import com.example.User;`
return {
kind: 'named',
localName: nameCap?.text ?? sourceCap.text.split('.').pop() ?? sourceCap.text,
importedName: sourceCap.text,
targetRaw: sourceCap.text,
};
}
case 'wildcard': {
// `import com.example.*;`
return {
kind: 'wildcard',
targetRaw: sourceCap.text + '.*',
};
}
case 'static': {
// `import static com.example.Utils.format;`
// The source contains the full path including the member name
// (e.g. `com.example.Utils.format`). For file resolution we need
// the class path (`com.example.Utils`), so strip the final member
// segment. The local binding name is the member itself.
const fullSource = sourceCap.text;
const lastDot = fullSource.lastIndexOf('.');
const classPath = lastDot >= 0 ? fullSource.slice(0, lastDot) : fullSource;
return {
kind: 'named',
localName: nameCap?.text ?? (lastDot >= 0 ? fullSource.slice(lastDot + 1) : fullSource),
importedName: fullSource,
targetRaw: classPath,
};
}
case 'static-wildcard': {
// `import static com.example.Utils.*;`
// The source is the class path (e.g. `com.example.Utils`).
// Resolution should target the class file, not a wildcard directory
// scan — `Utils.java` is the file that contains the static members.
return {
kind: 'wildcard',
targetRaw: sourceCap.text + '.*',
};
}
default:
return null;
}
}
// ─── interpretTypeBinding ─────────────────────────────────────────────────
export function interpretJavaTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null {
const nameCap = captures['@type-binding.name'];
const typeCap = captures['@type-binding.type'];
if (nameCap === undefined || typeCap === undefined) return null;
// Strip qualifier first so that `com.example.BaseModel<T>` becomes
// `BaseModel<T>` before stripGeneric — the JVM-erasure fallback pattern
// requires an unqualified identifier at the start of the string.
const rawType = stripGeneric(stripQualifier(typeCap.text.trim()));
// Skip `var` — tree-sitter-java parses `var` as type_identifier with
// text "var". When used without a constructor initializer, there's no
// concrete type to bind.
if (rawType === 'var') return null;
let source: TypeRef['source'] = 'parameter-annotation';
if (captures['@type-binding.self'] !== undefined) source = 'self';
else if (captures['@type-binding.constructor'] !== undefined) source = 'constructor-inferred';
else if (captures['@type-binding.annotation'] !== undefined) source = 'annotation';
else if (captures['@type-binding.return'] !== undefined) source = 'return-annotation';
return { boundName: nameCap.text, rawTypeName: rawType, source };
}
/**
* Unwrap generic type parameters from Java types.
*
* Three tiers, checked in order:
* 1. Known single-arg collection wrappers → extract the element type
* (`List<User>` → `User`, `Optional<User>` → `User`).
* 2. Known two-arg map/container types → extract the value type
* (`Map<String, User>` → `User`).
* 3. **Fallback (JVM type erasure):** any other generic type →
* strip the generic parameters and keep the raw class name
* (`BaseModel<T>` → `BaseModel`, `CustomList<Foo>` → `CustomList`).
* This ensures receiver bindings (`this`/`super`) on classes with
* generic superclasses resolve to the correct class file.
*/
function stripGeneric(text: string): string {
// Single-type-argument containers — extract the element type.
const single = text.match(
/^(?:[A-Za-z_][A-Za-z0-9_.]*\.)?(?:List|ArrayList|LinkedList|Set|HashSet|TreeSet|SortedSet|LinkedHashSet|Collection|Iterable|Iterator|Optional|Stream|CompletableFuture|Future|Queue|Deque|ArrayDeque|PriorityQueue|Vector|Stack|Supplier|Consumer|Predicate|Function)<([^,<>]+)>$/,
);
if (single !== null) return single[1].trim();
// Two-type-argument map/container types — extract the value type (second arg).
const twoArg = text.match(
/^(?:[A-Za-z_][A-Za-z0-9_.]*\.)?(?:Map|HashMap|TreeMap|LinkedHashMap|ConcurrentHashMap|ConcurrentMap|SortedMap|NavigableMap|Hashtable|EnumMap|WeakHashMap|IdentityHashMap|BiFunction|BiConsumer|BiPredicate|Pair|Entry)<[^,<>]+,\s*([^,<>]+)>$/,
);
if (twoArg !== null) return twoArg[1].trim();
// Fallback: strip generic parameters from any unrecognized generic type.
// `BaseModel<T>` → `BaseModel`, `Builder<Self>` → `Builder`.
// This mirrors JVM type erasure — the raw class name is the resolvable symbol.
// The pattern matches up to the first `<` to handle nested generics safely
// (e.g. `BaseModel<List<String>>` → `BaseModel`).
const fallback = text.match(/^([A-Za-z_$][A-Za-z0-9_$]*)<.+>$/s);
if (fallback !== null) return fallback[1].trim();
return text;
}
/** `com.example.User` → `User`. */
function stripQualifier(text: string): string {
const lastDot = text.lastIndexOf('.');
if (lastDot === -1) return text;
return text.slice(lastDot + 1);
}

44
gitnexus/src/core/ingestion/languages/java/merge-bindings.ts Normal file
View file

@ -0,0 +1,44 @@
/**
* Java shadowing precedence for the `mergeBindings` hook.
*
* Tier ranking (lower wins):
* - 0: `local` — class member, method, local variable, parameter
* - 1: `import` / `namespace` / `reexport` — explicit imports
* - 2: `wildcard` — wildcard imports (`import x.y.*`)
*
* Within a surviving tier: de-dup by DefId, last-write-wins.
*/
import type { BindingRef } from 'gitnexus-shared';
const TIER_LOCAL = 0;
const TIER_IMPORT = 1;
const TIER_WILDCARD = 2;
const TIER_UNKNOWN = 3;
function tierOf(b: BindingRef): number {
switch (b.origin) {
case 'local':
return TIER_LOCAL;
case 'reexport':
case 'import':
case 'namespace':
return TIER_IMPORT;
case 'wildcard':
return TIER_WILDCARD;
default:
return TIER_UNKNOWN;
}
}
export function javaMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[] {
if (bindings.length === 0) return bindings;
let bestTier = Number.POSITIVE_INFINITY;
for (const b of bindings) bestTier = Math.min(bestTier, tierOf(b));
const survivors = bindings.filter((b) => tierOf(b) === bestTier);
const seen = new Map<string, BindingRef>();
for (const b of survivors) seen.set(b.def.nodeId, b);
return [...seen.values()];
}

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