Merge branch 'main' into fix/lbug-0.21.2-scan-duplicate-rows

This commit is contained in:
Gergő Magyar 2026-10-24 18:36:06 +01:00 • committed by GitHub
commit f66cebae7a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1007 changed files with 243963 additions and 175418 deletions

View file

@ -17,7 +17,8 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
A root cause traced in the wrong repository is a wrong root cause.
Call `list_repos {}` before the first tool call. With one indexed repository,
Bind once using a confirmed registry name/path or configured MCP default. Call
`list_repos {}` if the target is not yet known; reuse that binding across calls. With one indexed repository,
use the examples below as written. With more than one, pass `repo` on every
call: an omitted `repo` normally errors, but under an MCP policy with a
configured default it resolves to that default silently. If you cannot tell
@ -34,10 +35,10 @@ diagnosis.
## Workflow
```
0. list_repos {} → Bind repo
1. query({search_query: "<error or symptom>"}) → Find related execution flows
0. Bind the repo once (list_repos only if not already known)
1. If the suspect is unknown, query for the error/symptom with small result limits
2. context({name: "<suspect>"}) → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
3. Read a process resource only if its trace resolves an open question
4. cypher({statement: "MATCH path..."}) → Custom traces if needed
```
@ -47,7 +48,7 @@ diagnosis.
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Once per session: bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
@ -58,6 +59,28 @@ diagnosis.
- [ ] State the repository and index freshness with the diagnosis
```
## Keep investigations focused
Start with a known symbol's `context`, or a small `query` (`limit: 3`,
`max_symbols: 3`, `include_content: false`, `chain_depth: 0`) to discover one.
When the server advertises these single-repository filters, request only the
needed evidence:
```text
context({uid: "<suspect id>", repo: "my-app", include_content: true,
response_sections: ["outgoing"], relationTypes: ["CALLS"]})
trace({from_uid: "<suspect id>", to_uid: "<failure id>", repo: "my-app"})
```
`symbol` and completeness/staleness diagnostics remain in a filtered context.
`relationTypes` filters the returned incoming/outgoing categories only; it does
not expand their existing bounded window or filter an explicitly requested chain.
For callback registration, include `USES`; for imports or inheritance, request
those relation types or omit the filter. Omitted references are not absent
references. Broaden when the hypothesis needs it, and preserve UNKNOWN/partial
warnings. Confirm source and tests before claiming a root cause. A useful 2–3
call investigation is a goal, not a reason to skip verification or pre-edit impact.
## Debugging Patterns
| Symptom | GitNexus Approach |

View file

@ -15,9 +15,10 @@ description: "Use when the user asks how code works, wants to understand archite
## Bind the repository first
Step 1 discovers what is indexed; every call after it must say which of those
it means. With one indexed repository, use the examples below as written. With
more than one, pass `repo` on every call: an omitted `repo` normally errors,
Bind once per session using a confirmed registry name/path or configured MCP
default; reuse it. Call `list_repos {}` when the target is not yet known, not before
every question. Never guess the registry name from the checkout directory. With
one indexed repository, use the examples below as written. With more than one, pass `repo` on every call: an omitted `repo` normally errors,
but under an MCP policy with a configured default it resolves to that default
silently. If you cannot tell which repository is meant, stop and ask. Report
the bound repository and index freshness alongside your explanation.
@ -28,26 +29,64 @@ the bound repository and index freshness alongside your explanation.
## Workflow
```
1. list_repos {} or READ gitnexus://repos → Discover indexed repos
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
3. query({search_query: "<what you want to understand>"}) → Find related execution flows
4. context({name: "<symbol>"}) → Deep dive on specific symbol
5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow
1. Bind the repository once; use hot-tool staleness on subsequent calls
2. If no symbol is known: query({search_query: "<concept>", limit: 3, max_symbols: 3})
3. context({uid: "<returned id>"}) → Inspect the selected symbol
4. Read a process resource only when its full trace answers an unresolved question
```
> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
> If the index is stale → run `node .gitnexus/run.cjs analyze` in terminal.
> Hot-tool `staleness` names which index answered (`branch`/`lastCommit`) and how fresh it is (`status`). Re-analyze only for `behind` or `diverged` — `current` is identity, `unknown` is unmeasurable.
## Ask for only the evidence needed
Use options advertised by the connected server. `response_sections` and context
`relationTypes` are opt-in views for a single repository, not `@group` routing.
On an older server, use the existing limits and content/chain options instead.
Use filters when unwanted sections are bulky; their omission metadata can make
an already-small response slightly larger.
Aim for 2–3 focused calls after repository binding; stop when the question is
answered, but expand if evidence or a required safety check is still missing.
```text
query({search_query: "payment retry", repo: "my-app", limit: 3, max_symbols: 3,
include_content: false, chain_depth: 0,
response_sections: ["process_symbols", "definitions"]})
context({uid: "<id from query>", repo: "my-app", include_content: true,
response_sections: ["incoming", "outgoing"], relationTypes: ["CALLS"]})
// Before editing, assess impact using the normal traversal and risk calculation:
impact({target: "<same id>", repo: "my-app", direction: "upstream", summaryOnly: true})
```
If the symbol is already known, start with `context`; use `uid`, or `name` plus
`file_path`/`kind`, to avoid ambiguous results. To answer only “who calls it?”,
request `response_sections: ["incoming"]`, `relationTypes: ["CALLS"]` and leave
`include_content` false. Keep `processes` in a query when the question is about
flows, rather than requesting a symbols-only view.
Do not request source and multi-hop chains for every search hit. Fetch source
for the selected symbol only; for a large class/file, prefer `read_file` with
a small 0-based `startLine`/`endLine` window (subtract 1 from graph line numbers),
or `maxLines` for a whole-file read, if that tool is available. Use
`trace` for a known A→B path instead of repeatedly expanding `context`.
Filters retain requested sections/categories and hide the others; they do not prove other references
are absent or make the existing bounded search exhaustive. Read `response_filter`,
`warning`, `partial`, `truncated`, `epistemic` and `staleness`. Remove filters when
broader evidence is needed. `maxTokens` is a last-resort byte cutoff that can cut
JSON: narrow the request rather than treating a cut response as complete. Never
use a filtered caller view to waive the required impact check or an UNKNOWN risk.
## Checklist
```
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] READ gitnexus://repo/{name}/context
- [ ] query for the concept you want to understand
- [ ] Review returned processes (execution flows)
- [ ] context on key symbols for callers/callees
- [ ] READ process resource for full execution traces
- [ ] Read source files for implementation details
- [ ] Once per session: bind repo; explicit repo when >1 indexed, ask if ambiguous
- [ ] Check hot-tool staleness; read the overview only if needed
- [ ] Query for the concept only if the relevant symbol is not already known
- [ ] Review returned symbols; include processes when execution flow matters
- [ ] context on selected symbols; request only relevant sections/relations
- [ ] Read a process resource only if its full trace is needed
- [ ] Read targeted source only when implementation details are needed
- [ ] State the repository and index freshness with the explanation
```
@ -84,18 +123,16 @@ with a single one.
## Example: "How does payment processing work?"
```
1. list_repos {} → total: 1 (my-app) — bind it
READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
2. query({search_query: "payment processing"})
→ CheckoutFlow: processPayment → validateCard → chargeStripe
→ RefundFlow: initiateRefund → calculateRefund → processRefund
3. context({name: "processPayment"})
→ Incoming: checkoutHandler, webhookHandler
→ Outgoing: validateCard, chargeStripe, saveTransaction
4. Read src/payments/processor.ts for implementation details
5. Answer, noting: Repository my-app, index current
With `my-app` already bound and the index current:
```text
1. query({search_query: "payment processing", repo: "my-app", limit: 3, max_symbols: 3})
→ CheckoutFlow and RefundFlow, with symbol IDs and locations
2. context({uid: "<processPayment id>", repo: "my-app", include_content: true,
response_sections: ["outgoing", "processes"]})
→ Selected source, callees, process participation and completeness diagnostics
3. Answer from that evidence; read one process resource only if its trace is still needed
```
Had step 1 returned two repositories, every call above would carry
`repo: "my-app"`.
Report the repository and index freshness with the explanation. If `my-app`
had not yet been bound, discover it once with `list_repos` first.

View file

@ -11,7 +11,7 @@ Quick reference for all GitNexus MCP tools, resources, and the knowledge graph s
For any task involving code understanding, debugging, impact analysis, or refactoring:
1. **Read `gitnexus://repo/{name}/context`** — codebase overview + check index freshness
1. **Bind the repository once** — use a confirmed registry name/path or configured default; call `list_repos` if unknown. Read hot-tool `staleness`; use `gitnexus://repo/{name}/context` when an overview is needed.
2. **Match your task to a skill below** and **read that skill file**
3. **Follow the skill's workflow and checklist**
@ -38,7 +38,7 @@ For any task involving code understanding, debugging, impact analysis, or refact
| `impact` | Symbol blast radius — what breaks at depth 1/2/3 with confidence |
| `trace` | Shortest path between two symbols — "how does A reach B?" in one call |
| `detect_changes` | Git-diff impact — what do your current changes affect |
| `rename` | Semantic rename: previews by default (`dry_run` omitted/true), applies with `dry_run: false`; inspect application status and failures |
| `rename` | Semantic rename: previews by default (`dry_run` omitted/true), applies with `dry_run: false` and the preview's `plan_token`; inspect application status and failures |
| `cypher` | Raw graph queries (read `gitnexus://repo/{name}/schema` first) |
| `explain` | Persisted taint findings — source→sink data flows (needs `analyze --pdg`) |
| `pdg_query` | Control/data dependence — what gates X (CDG) / where Y flows (REACHING_DEF); needs `analyze --pdg` |
@ -51,6 +51,39 @@ For any task involving code understanding, debugging, impact analysis, or refact
| `group_sync` | Rebuild a group's Contract Registry (cross-repo HTTP contract links); run after `group.yaml` changes or member re-index |
| `list_repos` | Discover indexed repos (paginated — `limit`/`offset`) |
### Choose a focused response
Use the connected server's schema; older servers may not advertise the new
filters. All options below are explicit: omitting them preserves existing output.
Use filters for bulky unwanted sections; on an already-small response, omission
metadata can outweigh the bytes saved.
| Question | Options |
| --- | --- |
| Which symbols implement this? | `query`: `limit: 3`, `max_symbols: 3`, `include_content: false`, `chain_depth: 0`, `response_sections: ["process_symbols", "definitions"]` |
| Which execution flows match? | `query`: keep `processes` in `response_sections`; join its `id` to `process_symbols[].process_id` |
| Who calls this exact symbol? | `context`: `uid`, `response_sections: ["incoming"]`, `relationTypes: ["CALLS"]` |
| What does it call, with source? | `context`: `uid`, `include_content: true`, `response_sections: ["outgoing"]`, `relationTypes: ["CALLS"]` |
| What is the impact summary? | `impact`: `direction: "upstream"`, `summaryOnly: true`; risk calculation and totals are retained |
| Which affected symbols need inspection? | `impact`: `limit: 10`, `offset: 0`; page as indicated by the response |
| How does A reach B? | `trace`: `from_uid`, `to_uid` |
`response_sections` selects data sections for single-repository MCP `query` or
`context` (not `@group` routes). Query choices: `processes`, `process_symbols`,
`definitions`. Context choices: `incoming`, `outgoing`, `processes`, `chain`,
`routes`, `typed_properties`; the selected symbol always remains. Context
`relationTypes` accepts uppercase relationship names advertised by its schema
and filters only the existing incoming/outgoing categories. It does not change
ranking, traversal, source retention or the bounded candidate/reference windows.
Filters add `response_filter` with the selection and omitted fields/categories.
Warnings, ambiguity, staleness and completeness metadata always remain. An empty
filtered view is not proof of absence. Omit filters to expand, and never waive
impact checks because a selected category is empty. `maxTokens` is a byte cutoff,
not pagination: it can cut JSON. Prefer these filters, small result counts, and
source/chain expansion for a selected symbol rather than a large search result.
Stop once enough evidence answers the question; do not run every tool by default.
### Paginating `list_repos`
`list_repos` is paginated so a large registry is not truncated by MCP/LLM token limits. It takes optional `limit` (default **50**, max **200**) and `offset`, and returns:

View file

@ -57,7 +57,7 @@ checkout and reports nothing changed, which reads as a verified refactor.
- [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview semantic edits (omitting dry_run also previews)
- [ ] Confirm the previewed file paths are in the bound repository/worktree
- [ ] Review exact graph-backed semantic spans, coverage, and limitations
- [ ] If satisfied: rename({..., dry_run: false}) — apply edits
- [ ] If satisfied: rename({..., dry_run: false, plan_token: "<token from preview>"}) — apply exactly the reviewed edits
- [ ] detect_changes() — verify only expected files changed
- [ ] Run tests for affected processes
```
@ -98,10 +98,15 @@ rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app
→ changes: [{file_path, edits: [{start, length, line, old_text, new_text, confidence: "semantic"}]}]
```
`dry_run` omitted or `true` previews and never writes; `dry_run: false` applies.
`dry_run` omitted or `true` previews and never writes; `dry_run: false` requires
the successful preview's `plan_token`. Keep the same repository, selected symbol,
and destination name. Tokens are single-use, expire after 15 minutes or a server
restart, and may be evicted when retained previews reach 16 plans or 64 MiB.
Any apply attempt consumes the token; request and review a fresh preview to retry.
An MCP server started with `GITNEXUS_MCP_READ_ONLY=1` still lists `rename`, but
as preview-only: it rejects any `dry_run` other than omitted or `true`, so apply
from a client that is not read-only.
through a server that permits writes. Request and review a fresh preview there;
tokens belong to the process that issued them.
Rename uses the indexed graph and GitNexus's own semantic layer. Language
providers resolve current source through scopes and bindings; no compiler or
@ -116,8 +121,12 @@ limits, including class renames requiring a file move, remain explicit in result
There is no regex fallback: legacy `graph_edits` and `text_search_edits` are zero.
Comments, strings, and unrelated same-spelled symbols are not replacements.
Preview and apply use the same planner. Results use `result_version: 2`;
`total_edits` counts occurrences, not matching lines. Exact replacements are shown in `new_text`. Separate preview and apply calls recompute the plan.
Preview captures the exact semantic plan, source hashes and physical file targets.
Apply validates that plan and executes its edits without replanning. Changes to
indexed targets, source bytes or paths (including newly added untracked source
files) reject the plan before writing. Unindexed files remain outside semantic
coverage; analyze first when they need refactoring. Results use `result_version: 2`;
`total_edits` counts occurrences, not matching lines. Exact replacements are shown in `new_text`.
Check `planning_status`, `application_status`, and `applied`. A completed apply
has `status: "success"`, `application_status: "applied"`, and `applied: true`.
A successful preview has not written files. `rename` does not accept `branch`:
@ -130,6 +139,9 @@ result carries `code` and `error`; nothing was written unless the last row appli
| --- | --- |
| `stale_graph` | Re-analyze the bound repository, then preview again with `rename` (`dry_run` omitted or `true`). |
| `source_changed` | Preview again against the current source and review it. If it appears during an apply, see the `partial` row. |
| `plan_required`, `invalid_plan`, `plan_mismatch` | Apply needs the successful preview's token and identical repository, symbol and new name. Expired, consumed or evicted plans require a fresh reviewed preview. |
| `source_set_changed` | Source paths changed, including untracked files. Re-analyze and review a fresh preview. |
| `plan_too_large` | The captured plan exceeds the 64 MiB retention budget. Narrow the indexed repository before previewing again. |
| `unsupported_*` | Stop automated rename and inspect the reported limitation. Use a language-aware manual refactor if needed. |
| Ambiguous target (`status: "ambiguous"` with candidates) | Inspect the returned candidates or `context`, then preview with the chosen `symbol_uid`. |
| `ambiguous_reference`, `incomplete_semantics` | The planner could not prove a reference, import, or declaration is covered. Stop automated rename; resolve the named location by hand or pick a different symbol. |
@ -199,7 +211,7 @@ RETURN caller.name, caller.filePath ORDER BY caller.filePath
2. Review semantic spans and provider coverage; inspect dynamic references separately
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: false})
3. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: false, plan_token: "<token from step 1>"})
→ Applied 12 edits across 8 files
4. detect_changes({scope: "all", repo: "my-app"})

View file

@ -125,12 +125,14 @@ and do not claim a complete graph-backed review.
from `NODE_SCHEMA_QUERIES` + `REL_SCHEMA_QUERIES` and moves on its own;
the check there is whether the diff changed any string in those arrays,
and, if it added a new DDL array, whether that array was folded into the
fingerprint. The hand-maintained ritual still applies where no
declarative artifact describes the invalidated set: the parse-store
`SCHEMA_BUMP` and both bench fingerprint sets still need an explicit
bump, re-checked against the base branch right before merge. Semantic
changes that leave the DDL untouched are outside the fingerprint; they
rely on the analyzer runner-identity receipt in the index metadata.
fingerprint. Parser compatibility is also automatic: review the base/PDG
ownership boundaries in `gitnexus/src/core/parse-cache-identity.ts`, the
import/asset coverage audit, and real cold → warm replay tests. New parser
dependencies outside those boundaries need explicit coverage; contributors
do not allocate a semantic counter. Both benchmark fingerprint sets still
need deliberate review before re-baselining: automatic invalidation does
not establish semantic correctness. Other semantic changes that leave DDL
untouched rely on the analyzer runner-identity receipt in index metadata.
## Expert lenses

View file

@ -141,10 +141,12 @@ finding is NOT proof of safety.
`taint/path-codec.ts`. Two hand-rolled copies of a wire format drift — never
fork it. New metadata extends the format WITHIN the version when writer +
reader ship together.
- **Cache versioning.** A worker-harvest shape change bumps the parse-cache pdg
NAMESPACE (`pdg:N`), NOT `SCHEMA_BUMP` (which cold-invalidates every user).
Persisted-graph/config changes ride `RepoMeta.pdg`'s key-union mismatch →
full writeback. Model content rides `taintModelVersion`.
- **Cache compatibility.** Worker-harvest changes invalidate automatically
through the PDG artifact identity. Keep extraction-only dependencies in the
PDG ownership boundary and verify that ordinary parse keys remain stable.
Shared parser changes belong to the base identity. Persisted-graph/config
changes ride `RepoMeta.pdg`'s key-union mismatch → full writeback.
Model content rides `taintModelVersion`.
## Adding a source / sink / sanitizer

View file

@ -14,21 +14,26 @@
# `@devcontainers/cli` / the VS Code Dev Containers resolver. That resolver's
# image-name parser rejects the combined `name:tag@sha256:...` form.
#
# The digest below is for the `1-22-bookworm` tag. It is the multi-arch
# manifest-list digest, so it still picks the right platform. To refresh it when
# bumping the readable tag, run:
# The digest below is for `5.2.3-22-bookworm` (Node 22.23.3). Workspace
# dependencies require at least Node 22.22.2 on the Node 22 line. It is the
# multi-arch manifest-list digest, so it still picks the right platform.
# To refresh it when bumping the readable tag, run:
# docker buildx imagetools inspect \
# mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm \
# mcr.microsoft.com/devcontainers/typescript-node:5.2.3-22-bookworm \
# --format '{{json .Manifest.Digest}}'
FROM mcr.microsoft.com/devcontainers/typescript-node@sha256:7c2e711a4f7b02f32d2da16192d5e05aa7c95279be4ce889cff5df316f251c1d
FROM mcr.microsoft.com/devcontainers/typescript-node@sha256:0cb6b4bfcb0458a6c1d2345934fb9de35da7b9d32343f47e49d9bd66feeac780
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
# Bun is installed via the official remote script (bun.sh/install), pinned by
# version. Claude Code and Cursor also use official install scripts (no version
# to pin). To harden Bun: switch to a pinned tarball + per-arch sha256
# version. Claude Code, Codex, and Cursor also use official install scripts.
# To harden Bun: switch to a pinned tarball + per-arch sha256
# (release artifacts at github.com/oven-sh/bun/releases).
ARG BUN_VERSION
ARG TZ=UTC
ARG USERNAME=node
ARG INSTALL_BROWSER_DEPS=false
ARG PLAYWRIGHT_VERSION
# Copy the build-only ARGs into runtime ENV so shells and lifecycle scripts can
# read them. We deliberately do not set CLAUDE_CONFIG_DIR here. Its one true
@ -38,25 +43,35 @@ ENV BUN_VERSION=${BUN_VERSION} \
BUN_INSTALL=/home/${USERNAME}/.bun \
TZ=${TZ} \
DEVCONTAINER=true \
NODE_OPTIONS=--max-old-space-size=4096 \
GITNEXUS_AUTO_HEAP=0 \
POWERLEVEL9K_DISABLE_GITSTATUS=true
# Native build toolchain that gitnexus/postinstall needs. It compiles
# tree-sitter native bindings, the vendored Dart/Proto/Swift grammars, and the
# @ladybugdb/core N-API addon (a native Node add-on). python3, make, and g++ are
# required. This mirrors the apt block in the existing Dockerfile.cli /
# required. util-linux supplies findmnt/mount for the 9p helper; the remaining
# diagnostic tools support investigating process, memory and filesystem delays.
# This mirrors the apt block in the existing Dockerfile.cli /
# gitnexus/Dockerfile.test images.
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
python3 make g++ git curl ca-certificates bash unzip \
python3 make g++ git curl ca-certificates bash unzip util-linux procps lsof strace time jq ripgrep \
&& rm -rf /var/lib/apt/lists/*
# UI profile: install OS dependencies at image-build time as root. Runtime
# browser downloads use the project's locked Playwright and a persistent volume.
RUN --mount=type=cache,target=/root/.npm \
if [ "${INSTALL_BROWSER_DEPS}" = true ]; then \
test -n "${PLAYWRIGHT_VERSION}" \
&& npm exec --yes --package="@playwright/test@${PLAYWRIGHT_VERSION}" -- playwright install-deps chromium \
&& rm -rf /var/lib/apt/lists/*; \
fi
COPY bootstrap-native.cjs /usr/local/share/gitnexus-devcontainer/bootstrap-native.cjs
# Create and chown the named-volume mount points (~/.npm, ~/.local,
# /commandhistory) up front. That way an empty volume inherits `node:node`
# ownership the first time it is mounted. The three CLI config dirs (~/.claude,
# ~/.codex, ~/.cursor) are bind-mounted from the host instead. A bind mount
# completely hides the image-side ownership, so those paths need no chown here.
# ownership the first time it is mounted. post-create.sh handles ownership on
# the CLI config volumes (~/.claude, ~/.codex, ~/.cursor), including reused ones.
RUN mkdir -p \
/home/${USERNAME}/.npm \
/home/${USERNAME}/.local/bin \
@ -68,36 +83,38 @@ RUN mkdir -p \
USER ${USERNAME}
# Native CLI installers use this directory for their launchers.
ENV PATH=/home/${USERNAME}/.local/bin:${BUN_INSTALL}/bin:${PATH}
# Install Claude Code via the official native installer. Downloads the latest
# self-contained binary for the running platform and places it at
# ~/.local/bin/claude — no Node.js runtime dependency, no version to pin.
RUN curl -fsSL https://claude.ai/install.sh | bash
RUN curl -fsSL --retry 3 --max-time 120 https://claude.ai/install.sh | bash \
&& /home/${USERNAME}/.local/bin/claude --version
# Install the Codex CLI globally via npm. No version pinned — @latest at build
# time. (Codex has no native binary installer; npm is the canonical method.)
RUN npm install -g @openai/codex
# Install standalone Codex without npm or interactive onboarding. Keep a seed
# outside ~/.codex: its runtime config volume can hide image-installed packages
# on rebuild. post-create.sh restores the seed only if Codex cannot run.
RUN curl -fsSL --retry 3 --max-time 120 https://chatgpt.com/codex/install.sh -o /tmp/install-codex.sh \
&& CODEX_NON_INTERACTIVE=1 sh /tmp/install-codex.sh \
&& /home/${USERNAME}/.local/bin/codex --version \
&& mkdir -p /home/${USERNAME}/.local/share \
&& mv /home/${USERNAME}/.codex/packages/standalone /home/${USERNAME}/.local/share/codex-standalone \
&& rm /tmp/install-codex.sh
# Install the Cursor agent CLI via the official install script. Downloads the
# latest agent-cli-package for the running platform and places `cursor-agent`
# and `agent` into ~/.local/bin — no version or hash to pin.
RUN curl -fsSL https://cursor.com/install | bash
RUN curl -fsSL --retry 3 --max-time 120 https://cursor.com/install | bash \
&& /home/${USERNAME}/.local/bin/cursor-agent --version
# Install Bun via the official remote installer, pinned by version. The first
# positional arg to `bash` is the release tag (`bun-vX.Y.Z`), so a specific
# version is fetched even though the install script itself is downloaded fresh
# on every build. NOTE: this is the ONE remote script we run unverified in
# this image — Cursor and the base image are pinned by sha256/digest. Hardening
# path: switch to a pinned tarball + per-arch sha256 in the Cursor style
# (artifacts at github.com/oven-sh/bun/releases). `BUN_INSTALL` is set in ENV
# above so the binary lands at a known path regardless of any rc-file edits
# on every build. The installer script itself is not pinned. `BUN_INSTALL` is
# set in ENV above so the binary lands at a known path regardless of rc-file edits
# the installer makes (which we ignore — we own the shell rc files).
RUN set -eux; \
curl -fsSL --retry 3 --max-time 120 https://bun.sh/install \
| bash -s "bun-v${BUN_VERSION}"; \
test -x "${BUN_INSTALL}/bin/bun"
# Put ~/.local/bin and Bun's bin dir on PATH for interactive shells and
# lifecycle scripts. ~/.local/bin is where Cursor's installer drops the `agent`
# and `cursor-agent` symlinks; ${BUN_INSTALL}/bin is where the Bun installer
# drops `bun` / `bunx`.
ENV PATH=/home/${USERNAME}/.local/bin:${BUN_INSTALL}/bin:${PATH}

View file

@ -4,7 +4,9 @@ A cross-platform Dev Container that pre-installs Claude Code, OpenAI Codex CLI,
> ### ⚠️ Read this before using it on a work machine
>
> This devcontainer **does not write to your host AI-CLI config.** Your skills, agents, commands, plugins, memory, prompts, and rules are **copied once** from a read-only host stage into a per-container volume on first create; the container edits its own copy and can never write back. So a compromised workspace dependency running in the container **cannot** drop a malicious agent, command, skill, or plugin onto your host for your next host CLI session to load — the write-through vector earlier versions had is closed. Your **credentials** (Claude/Codex/Cursor logins, plus `gh`) likewise stay in per-container volumes and are never written back, and `~/.ssh`, `~/.aws`, `~/.azure`, and `~/.docker` are mounted **read-only**.
> **The default 9p setup grants `SYS_ADMIN`, which can weaken read-only mount protections.** Remove that capability and disable tuning as described below to restore the boundary assumed in the following security notes.
>
> **With `SYS_ADMIN` removed**, this devcontainer **does not write to your host AI-CLI config.** Your skills, agents, commands, plugins, memory, prompts, and rules are **copied once** from a read-only host stage into a per-container volume on first create; the container edits its own copy and can never write back. So a compromised workspace dependency running in the container **cannot** drop a malicious agent, command, skill, or plugin onto your host for your next host CLI session to load — the write-through vector earlier versions had is closed. Your **credentials** (Claude/Codex/Cursor logins, plus `gh`) likewise stay in per-container volumes and are never written back, and `~/.ssh`, `~/.aws`, `~/.azure`, and `~/.docker` are mounted **read-only**.
>
> What is **still** exposed: the read-only host stages (`/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`) and the read-only credential mounts are all **readable** inside the container. A compromised dependency can therefore READ your host CLI config, memory, SSH/cloud credentials, and GitHub token — and there is **no egress firewall yet**, so it has the network to exfiltrate what it reads. Read-only protects you from tampering and write-back, not from disclosure.
>
@ -18,7 +20,7 @@ A cross-platform Dev Container that pre-installs Claude Code, OpenAI Codex CLI,
2. Install [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
3. Install [Node.js](https://nodejs.org/) on the **host** (Node 18+). This is the only host-side toolchain dependency beyond Docker and VS Code — the devcontainer's `initializeCommand` runs `node .devcontainer/ensure-host-config-dirs.cjs` to set up the bind-mount source directories before container create. If you already use Claude Code or another Node-based CLI on the host, you're already set.
4. Open the repo in VS Code → Command Palette → **Dev Containers: Reopen in Container**.
5. Wait for the first build (~3–6 minutes) and `postCreateCommand` to finish installing workspace dependencies.
5. Wait for the image build and lifecycle commands to finish preparing dependencies and AI CLI configuration.
6. Authenticate the three CLIs once — see [First-time CLI authentication](#first-time-cli-authentication) below.
## Windows 11 setup
@ -48,7 +50,7 @@ Windows-native works, but Docker Desktop's Windows bind-mount layer has rough ed
- **File watchers can miss events.** Vite / jest `--watch` running inside the container watching workspace files mounted from `D:\...` may miss changes — chokidar polling (`CHOKIDAR_USEPOLLING=true`) is the usual workaround.
- **`npm install` is 3-5× slower** through the Windows-to-Linux bind-mount translation than on a WSL2-native filesystem.
- **Permission edge cases.** The husky `.husky/_/h` EPERM class we hit earlier in this PR is specific to Windows-side bind mounts changing UID ownership between container runs. `post-create.sh` clears the cache defensively to keep this from being fatal, but it's still a real source of friction.
- **Permission edge cases.** The husky `.husky/_/h` EPERM class we hit earlier in this PR is specific to Windows-side bind mounts changing UID ownership between container runs. `install-deps.sh` rebuilds the generated cache and verifies the pre-commit hook, but it's still a real source of friction.
If you hit any of those and want to migrate to WSL2 later, the steps are below.
@ -84,11 +86,92 @@ Open the repo folder in VS Code → **Reopen in Container**. The image is multi-
Same as macOS — open in VS Code and reopen in container. `updateRemoteUserUID: true` (default) shifts the container's `node` user UID/GID to match your host user, so bind-mounted files stay writable without extra setup.
## Workspace and image profiles
The main configuration keeps your existing host checkout bind-mounted at `/workspace`. For Windows hosts, the WSL2 filesystem setup above avoids the Windows filesystem translation. Additional profiles are generated from the main configuration, using host Node.js with no npm installation required:
```bash
# A separate checkout in a Docker-managed native filesystem volume.
node .devcontainer/profile.cjs native --ref main
# Bind-mounted checkout with Chromium system dependencies and browser cache.
node .devcontainer/profile.cjs ui
# Combine the native workspace and UI support.
node .devcontainer/profile.cjs native --ui --ref main
# Work on a branch pushed to your own fork (HTTPS or Git SSH).
node .devcontainer/profile.cjs native --url https://github.com/YOUR-NAME/GitNexus.git --ref your-branch
# Pull a published toolchain image instead of building locally.
node .devcontainer/profile.cjs prebuilt
node .devcontainer/profile.cjs prebuilt --ui
```
These commands overwrite the ignored `.devcontainer/generated/devcontainer.json`. Select that configuration when reopening the folder in Dev Containers, or pass `--config .devcontainer/generated/devcontainer.json` to the Dev Container CLI. Regenerate after changing the main configuration. Existing containers need recreation when switching workspace mounts.
The native profile clones the selected **remote branch** of GitNexus into its volume before dependency setup. It does not copy uncommitted host edits. Push your branch first and use `--ref your-branch` to work on it; contributors using a fork must also pass `--url` for that fork. HTTPS, `git@host:owner/repo.git`, and `ssh://git@host/owner/repo.git` URLs are supported without embedded HTTPS credentials. Fresh checkouts track their remote branch, so ordinary `git pull` and `git push` work. Reused volumes keep their current branch and local changes; the bootstrap neither resets nor automatically pulls an existing checkout. The volume is the authoritative checkout: use Git to export changes before removing it. Host credentials/configuration still use the existing read-only staging mounts.
`--ref` and `--url` apply only to `native`. `--image` selects an existing image for consumer profiles and preserves the configured Features, including GitHub CLI, so custom images need not bundle `gh`. Dev Containers applies those Features to the selected image. `image-build` accepts only `--ui`, since its build output is named by the publishing command.
UI profiles install OS dependencies during the image build using the Playwright version in `gitnexus-web/package-lock.json`. Setup installs matching Chromium binaries into a persistent browser-cache volume. They also allocate 1 GiB of private shared memory. Prebuilt UI profiles require the `main-ui` image variant; explicit images passed with `--image` must include those OS dependencies.
## Dependency reuse, storage and diagnostics
Setup records completed installations inside each dependency volume. Fingerprints cover package manifests, lockfiles, local file-dependency manifests, Node version/ABI, npm version, architecture, and tracked native grammar/build inputs. The CLI receipt also includes the effective `GITNEXUS_SKIP_OPTIONAL_GRAMMARS` setting. A matching receipt with all direct dependencies present skips `npm ci`. Missing dependencies or changed inputs cause a clean reinstall, with lifecycle scripts enabled. Failed installs leave no valid receipt.
Husky preparation and verification **always run**, including cached setup. Shared and CLI source builds run independently of dependency reuse, so pulling source changes still refreshes compiled output. After pulling changes in a running container, run:
```bash
bash .devcontainer/install-deps.sh
# Repair nested dependency damage, new untracked native build inputs, or
# changed npm installation settings that are outside the fingerprint.
GITNEXUS_FORCE_DEPS=1 bash .devcontainer/install-deps.sh
```
The shared GitNexus store and registry persist under `GITNEXUS_HOME=/home/node/.gitnexus` in a native named volume, retaining worktree sharing. Existing checkout-local `.gitnexus` directories stay in place; a new mount does not hide or replace them. The native workspace profile also places checkout-local indexes on its native filesystem. If moving an existing container whose shared store lives only in its writable layer, export that store before deleting the old container.
Setup prints timings for ownership repair, dependency installation/reuse, builds, and browser provisioning. Inspect the environment at any time with:
```bash
node .devcontainer/doctor.cjs
node .devcontainer/dev-test.cjs core test/unit/resolve-invocation.test.ts
node .devcontainer/dev-test.cjs web
GITNEXUS_DEV_TEST_WORKERS=2 node .devcontainer/dev-test.cjs core --watch
```
The diagnostic command reports CPU/memory allowance, cgroup memory events, memory/I/O pressure, disk space/inodes, file-descriptor and watcher limits, filesystem options, and hook status. The development test runner chooses up to four workers, respecting cgroup v2 CPU/memory limits and leaving interactive headroom. Its explicit override accepts 1–99 workers. The ordinary package test commands and CI test configuration remain available. Ownership repair still checks nested entries on each setup; timings can establish whether a more aggressive cache is worthwhile.
## Prebuilt images
`.github/workflows/devcontainer-publish.yml` verifies the tooling and publishes amd64/arm64 core and UI images to GHCR on relevant `main` pushes or manual dispatch on `main`. Pull requests do not publish images. Registry build caches are separate for the two variants. Consumers supply runtime mounts and lifecycle commands; published toolchain metadata excludes those settings to avoid duplicate lifecycle execution.
The rolling tags are `ghcr.io/abhigyanpatwari/gitnexus-devcontainer:main` and `:main-ui`, available **after the first successful publication**. A fork publishes under its own repository-derived name. Each publication also records a unique `sha-COMMIT-run-RUN-ATTEMPT` tag in the workflow summary (with `-ui` for UI images). Pass that full reference or an image digest with `--image` to select a fixed build. Combine `native --image IMAGE` to use a prebuilt image with a native workspace. Local builds remain the default while the publishing workflow is reviewed and merged. New GHCR packages are [private by default](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry); a maintainer must enable public visibility for anonymous pulls, or developers must authenticate to GHCR. The workflow links the package to this repository using its OCI source label.
## 9p workspace tuning
`.devcontainer/tune-9p.sh` can attempt a larger 9p `msize` on each container start. It is **enabled by default**, with `SYS_ADMIN` granted to permit the remount attempt, and applies only when `/workspace` itself is a 9p mount. **Rebuild** an existing container to apply the capability. Check inside the container with:
```bash
findmnt -rn --mountpoint /workspace -o FSTYPE,OPTIONS
```
To disable the remount attempts, set `containerEnv.WORKSPACE_9P_TUNE` to `"0"` in `.devcontainer/devcontainer.json`. To also remove the broad mount privileges, remove `"SYS_ADMIN"` from `capAdd` and **rebuild**. Setting the flag alone does not remove the capability. The default target is 1 MiB (`1048576` bytes); change `containerEnv.WORKSPACE_9P_MSIZE` to choose another size. The existing defaults also accept these two variables from the host environment when creating the container.
The helper uses `sudo -n` with a five-second timeout, skips other filesystems and mounts already at or above the target, and never fails startup. It reads the mount options again after a remount and distinguishes a verified target value from an unchanged or unknown value. To retry manually:
```bash
WORKSPACE_9P_TUNE=1 bash .devcontainer/tune-9p.sh /workspace
```
This is an experiment, with no measured speedup claimed. [`msize` sets the 9p packet payload size](https://www.kernel.org/doc/html/latest/filesystems/9p.html), but [upstream Linux's 9p implementation](https://github.com/torvalds/linux/blob/master/fs/9p/vfs_super.c) has no reconfigure handler to apply a new value. A successful remount command can therefore leave `msize` unchanged; Docker Desktop's kernel and server may also limit it. Increasing privileges alone does not guarantee tuning will work. For Windows development, keeping the checkout on the WSL2 filesystem remains the documented setup above.
## How CLI state flows from your host
### AI CLIs (Claude Code, Codex, Cursor): copy-once from a read-only host stage + per-container credentials
The three AI CLIs use a **copy-from-read-only-stage topology**: the host's `~/.<cli>` folders (and `~/.claude-mem`) are mounted **read-only** at `/host/.<cli>`, and `post-create.sh` copies out of them into per-container named volumes. Credentials, identity, and single config files are copied on **every** create; the shareable subdirs (plugins, skills, agents, memory, commands, prompts, rules) are copied **once** on first create and then owned by the container. Nothing is bind-mounted read-write into the host's CLI config, so the container can never modify your host setup. Session sub-paths overlay the config volume via their own named volumes (Docker mount precedence — more specific path wins).
The three AI CLIs use a **copy-from-read-only-stage topology**: the host's `~/.<cli>` folders (and `~/.claude-mem`) are mounted **read-only** at `/host/.<cli>`, and `post-create.sh` copies out of them into per-container named volumes. Credentials, identity, and single config files are copied on **every** create; the shareable subdirs (plugins, skills, agents, memory, commands, prompts, rules) are copied **once** on first create and then owned by the container. Lifecycle scripts and CLI tools edit the container copies. The default `SYS_ADMIN` capability means the read-only mounts are not a security boundary against privileged container code. Session sub-paths overlay the config volume via their own named volumes (Docker mount precedence — more specific path wins).
| Mount | Source | Target | Mode | Purpose |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
@ -133,7 +216,7 @@ On the **first** container-create, `post-create.sh` copies each of these out of
**Why CLAUDE_CONFIG_DIR is intentionally NOT set:** Claude's default `~/.claude` matches the named-volume mount target, so the env var added no behavior — but setting it changed which file Claude reads `hasCompletedOnboarding` from. With it set, Claude reads `$CLAUDE_CONFIG_DIR/.claude.json` (the small identity-only file) and re-onboards every container; without it, Claude reads `$HOME/.claude.json` (copied from the read-only `/host/.claude.json` stage on container-create via `seed-claude-config.cjs`, with `hasCompletedOnboarding: true`).
**Host CLI config is protected from write-through.** The shareable dirs are copied out of a **read-only** stage into the container's own volume, so a compromised npm package in the workspace dep tree — running inside the container — **cannot** write a malicious agent, command, skill, or plugin back to `~/.claude/`, `~/.codex/`, or `~/.cursor/` on the host. The earlier design bind-mounted these read-write and accepted that write-through as the cost of live sync; this design closes it. An even earlier alternative (read-only stage + symlinks) made `/plugin marketplace add` inside the container fail with EROFS; copying into a writable volume avoids that, because the container writes to its own copy rather than a read-only mount. What a compromised dependency can still do is **read** the read-only host stages (`/host/.<cli>`, `/host/.claude-mem`) and the read-only credential mounts and exfiltrate them — there is [no egress firewall yet](#whats-not-included-yet). The cost of the copy model is **divergence**: host edits made after first create don't reach the container until you wipe the config volume and rebuild.
**With `SYS_ADMIN` removed, host CLI config is protected from write-through.** The shareable dirs are copied out of a **read-only** stage into the container's own volume, so a compromised npm package in the workspace dep tree — running inside the container — **cannot** write a malicious agent, command, skill, or plugin back to `~/.claude/`, `~/.codex/`, or `~/.cursor/` on the host. The earlier design bind-mounted these read-write and accepted that write-through as the cost of live sync; this design closes it. An even earlier alternative (read-only stage + symlinks) made `/plugin marketplace add` inside the container fail with EROFS; copying into a writable volume avoids that, because the container writes to its own copy rather than a read-only mount. What a compromised dependency can still do is **read** the read-only host stages (`/host/.<cli>`, `/host/.claude-mem`) and the read-only credential mounts and exfiltrate them — there is [no egress firewall yet](#whats-not-included-yet). The cost of the copy model is **divergence**: host edits made after first create don't reach the container until you wipe the config volume and rebuild.
**Refresh-token divergence between rebuilds.** Container's credentials match host's at container-create time; after that, container manages its own refresh until the next rebuild. Anthropic rotates refresh tokens on every use, so an unattended container that hasn't talked to the API in weeks can hit a silent 401 if the host has refreshed since. Re-run `claude login` inside the container, or rebuild, to recover.
@ -214,7 +297,7 @@ The bind mount source directories are guaranteed to exist by the `initializeComm
Host and container share a single trust boundary by design — fine for personal-dev, but the consequence is concrete. Any malicious npm package or `postinstall` script in the workspace dep tree, running inside the container, has direct **read** access to:
- **Host AI CLI state** — the read-only stage at `/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`, which exposes your **entire** host `~/.<cli>` tree (credentials, identity, AND the shareable skills/agents/plugins/memory/commands) for _reading_. The container copies what it needs out of this stage; a compromised dep can read all of it. It is read-only, so none of it can be written back
- **Host AI CLI state** — the read-only stage at `/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`, which exposes your **entire** host `~/.<cli>` tree (credentials, identity, AND the shareable skills/agents/plugins/memory/commands) for _reading_. The container copies what it needs out of this stage; a compromised dep can read all of it. It is mounted read-only; default `SYS_ADMIN` can weaken that protection
- The **container's own credential snapshots** at `/home/node/.claude/.credentials.json` etc. (copied from host on container-create)
- `~/.claude/memory/` / per-project memory (which may contain user-stored secrets if you've used the `/remember` skill)
- The **current container's own session transcripts** (`~/.claude/projects`, `~/.codex/sessions`, `~/.cursor/chats`/`projects` — the group-6 volumes), which can hold anything pasted into or read during a session. These are container-private (see one-way note below), so this is read access to _this_ container's sessions only, not the host's or other projects'
@ -223,9 +306,9 @@ Host and container share a single trust boundary by design — fine for personal
- Docker registry tokens in **`~/.docker/config.json`** (if you've `docker login`-ed)
- AWS/Azure CLI credentials if you've populated `~/.aws/` or `~/.azure/`
It does **not** have write-through to the host's CLI config. The shareable dirs are copied out of the read-only stage into the container's own volume, so a compromised in-container dep **cannot** write into your host `~/.claude/{plugins,agents,skills,commands,memory}/`, `~/.codex/{plugins,prompts,memories,skills}/`, or `~/.cursor/{plugins,rules,commands,agents,skills}/`. The persistence vector earlier versions had — drop a malicious auto-loaded agent/command/skill/rule onto the host, have it run in your next **host** session — is closed: there is no writable path from the container to those host folders. (Cursor's `hooks.json` is still additionally withheld from even the _container's_ copy, because hooks fire without an agent invoking them.) The boundary is now one-way for **all** of the host CLI config, not just credentials.
**With `SYS_ADMIN` removed**, it does **not** have write-through to the host's CLI config. The shareable dirs are copied out of the read-only stage into the container's own volume, so a compromised in-container dep **cannot** write into your host `~/.claude/{plugins,agents,skills,commands,memory}/`, `~/.codex/{plugins,prompts,memories,skills}/`, or `~/.cursor/{plugins,rules,commands,agents,skills}/`. The persistence vector earlier versions had — drop a malicious auto-loaded agent/command/skill/rule onto the host, have it run in your next **host** session — is closed: there is no writable path from the container to those host folders. (Cursor's `hooks.json` is still additionally withheld from even the _container's_ copy, because hooks fire without an agent invoking them.) The boundary is now one-way for **all** of the host CLI config, not just credentials.
**What stays one-way (genuinely protected):** everything. Credentials never flow back to host — `.credentials.json` / `auth.json` / `cli-config.json` live only in the per-container named volumes, and the `/host/.<cli>` stage they're copied from is mounted **read-only**, so the snapshot can't be overwritten back. The shareable AI-CLI dirs (skills/agents/plugins/memory/commands/prompts/rules) are now copy-on-create from that same read-only stage, so they have the one-way property too — readable for the copy, never writable back. `~/.ssh`, `~/.config/git`, `~/.aws`, `~/.azure`, and **`~/.docker`** are read-only binds with the same property — a compromised dep can _read_ your registry tokens but cannot _rewrite_ them to hijack your future host auth. **`~/.config/gh`** is now a read-only _stage_ copied into a per-container volume, so it keeps that same one-way property: the container reads it once to seed its own writable copy, and the read-only stage means an in-container `gh auth login` can never overwrite your host token. **Session transcripts** live in per-workspace named volumes (mount group 6) and are never seeded from or written back to the host, and the container can't see any _other_ project's transcripts. The opt-in host-bind block in `devcontainer.json` reverses that for sessions only — enable it only if you accept transcripts on host disk; see [Session resume across container recreation](#session-resume-across-container-recreation).
**With `SYS_ADMIN` removed, what stays one-way:** everything. Credentials never flow back to host — `.credentials.json` / `auth.json` / `cli-config.json` live only in the per-container named volumes, and the `/host/.<cli>` stage they're copied from is mounted **read-only**, so the snapshot can't be overwritten back. The shareable AI-CLI dirs (skills/agents/plugins/memory/commands/prompts/rules) are now copy-on-create from that same read-only stage, so they have the one-way property too — readable for the copy, never writable back. `~/.ssh`, `~/.config/git`, `~/.aws`, `~/.azure`, and **`~/.docker`** are read-only binds with the same property — a compromised dep can _read_ your registry tokens but cannot _rewrite_ them to hijack your future host auth. **`~/.config/gh`** is now a read-only _stage_ copied into a per-container volume, so it keeps that same one-way property: the container reads it once to seed its own writable copy, and the read-only stage means an in-container `gh auth login` can never overwrite your host token. **Session transcripts** live in per-workspace named volumes (mount group 6) and are never seeded from or written back to the host, and the container can't see any _other_ project's transcripts. The opt-in host-bind block in `devcontainer.json` reverses that for sessions only — enable it only if you accept transcripts on host disk; see [Session resume across container recreation](#session-resume-across-container-recreation).
**The egress firewall is the key compensating control that is still missing.** It's deferred (see "What's not included (yet)" below), so a compromised package currently has unrestricted outbound network to exfiltrate anything in the read list above. Until it lands, treat that read surface as exposed to any code you run in the container — don't use this devcontainer on a machine whose host credentials you couldn't afford to rotate. The isolated-volume setup below removes host AI-CLI config/credentials from that surface entirely.
@ -310,12 +393,15 @@ VS Code's Ports panel shows forwarded ports once their listener starts.
## Known gotchas
- **Warm installs reuse the npm cache.** Lifecycle installs prefer cached packages and skip audit requests and funding notices; cache misses still download normally, and native addon/prepare scripts still run. Run `npm audit` in each package when checking vulnerabilities. Volume ownership repair changes only entries whose owner or group differs from `node`.
- **VS Code skips generated indexes, build output, dependencies, and nested worktrees when watching/searching.** Open a sibling worktree as its own window when developing there. These exclusions do not change Vite or Vitest watchers.
- **Memory follows the running workload.** The image leaves `NODE_OPTIONS` unset, so Node uses its defaults and `gitnexus analyze` uses its RAM-aware sizing. For a specific indexing run, use `gitnexus analyze --memory-budget 4096` to set a 4 GiB heap budget. Docker Desktop's VM memory allocation still bounds the container.
- **LadybugDB integration tests may fail in containers** (file-locking, `AGENTS.md` § Testing). Default to `npm run test:unit` inside the container; run integration tests on the host. Tracking issue: documented as a known limitation.
- **Single-writer LadybugDB constraint** (`GUARDRAILS.md` § LadybugDB lock). Don't run `gitnexus analyze` on the host and inside the container against the same `.gitnexus/` directory simultaneously — the second writer will get `database busy`.
- **Native grammar builds add ~30s to first install.** Tree-sitter Dart/Proto/Swift/Kotlin are all vendored uniformly: `node-gyp-build` picks a committed GitNexus-built prebuilt `.node` at install time (no compile), and only falls back to compiling from the vendored source during `postinstall` if no prebuild matches the host (then a toolchain is needed). Set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` (in your shell or `remoteEnv`, then rebuild) to skip all four; each loses parsing for the affected language(s), and the install still succeeds.
- **Native grammar builds add ~30s to first install.** Tree-sitter Dart/Proto/Swift/Kotlin/Zig are all vendored uniformly: `node-gyp-build` picks a committed GitNexus-built prebuilt `.node` at install time (no compile), and only falls back to compiling from the vendored source during `postinstall` if no prebuild matches the host (then a toolchain is needed). Set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` (in your shell or `remoteEnv`, then rebuild) to skip these optional grammars; each loses parsing for the affected language(s), and the install still succeeds. Changing this setting invalidates the CLI dependency receipt, including when it is removed to restore parsing.
- **`tree-sitter-kotlin`/`tree-sitter-swift` warnings on install** only appear when no prebuild matches the platform-arch (per `AGENTS.md`); they are non-fatal — parsing for that language is simply unavailable.
- **`.mcp.json` works inside the container**: `npx -y gitnexus@latest mcp` resolves cleanly because npm registry is reachable and the workspace bind mount exposes the same `.mcp.json` the host sees.
- **Husky pre-commit fires inside the container** without extra setup. The root `npm install` (run automatically in `postCreateCommand`) installs the hook via `package.json` `prepare`.
- **Husky pre-commit is verified during setup.** Root preparation always installs the hook, including cached dependency runs. Only its generated `.husky/_` cache is cleared for stale Windows permissions; the tracked `.husky/pre-commit` stays intact. Setup fails if the hook is missing, Git points elsewhere, or the environment or Husky's `init.sh` disables or skips it. Verification runs the installed Husky helper against a temporary sentinel hook without running the real formatter or changing staged files. Run `npm run prepare` at the repository root to restore the hook, and keep Husky enabled in its startup configuration.
## Rebuild / reset
@ -341,22 +427,26 @@ VS Code's Ports panel shows forwarded ports once their listener starts.
## Bumping CLI versions
Bump the version pins in `.devcontainer/devcontainer.json` `build.args` and rebuild — all three are real, fail-loud pins. Claude Code installs via `npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}` and Codex via `npm install -g @openai/codex@${CODEX_VERSION}`. **Cursor is pinned too:** bump `CURSOR_VERSION` **and** both `CURSOR_SHA256_X64` / `CURSOR_SHA256_ARM64` together — the Dockerfile downloads the pinned `downloads.cursor.com/lab/<version>/linux/<arch>/agent-cli-package.tar.gz` artifact directly (no remote install script) and fails the build on a sha256 mismatch. Re-hash each arch with `curl -fSL <url> | sha256sum`. To stop Cursor from auto-updating in the running container, don't call `cursor-agent update`.
Claude Code, Codex, and Cursor install the latest available release at image build time using their official shell installers. Rebuild without the Docker cache to refresh those image layers. Bun's version is pinned by `BUN_VERSION` in `.devcontainer/devcontainer.json` `build.args`; the Node base image is pinned by digest in the Dockerfile.
Codex uses the [official standalone installer](https://developers.openai.com/codex/cli/) (`curl -fsSL https://chatgpt.com/codex/install.sh | sh`) rather than npm. The build runs it non-interactively and checks `codex --version`. Its native packages normally live under `~/.codex/packages/standalone`, inside the persistent config volume. The image keeps a package seed outside that mount; `post-create.sh` restores it when Codex cannot run, including when rebuilding with a config volume created by the previous npm-based image. A working standalone release already in the volume is kept. This avoids another download during setup and leaves credentials, configuration, and sessions intact.
## What's not included (yet)
- **Egress firewall — the most important hardening still outstanding.** The original plan included an opt-in iptables/ipset firewall adapted from Anthropic's reference devcontainer. It was deferred to a follow-up PR — `runArgs` is static in `devcontainer.json`, so toggling NET_ADMIN/NET_RAW capabilities cleanly requires either a separate `devcontainer-firewall.json` profile or an `initializeCommand`-generated overlay. Until it lands, the read surface in [§ Trust boundary](#trust-boundary-concretely) has no network containment — anything readable can be exfiltrated. Track at the project's issue tracker if you need this.
- **Codespaces tuning.** The current config works in Codespaces incidentally (no privileged capabilities, no host-mount assumptions), but isn't actively tested there.
- **Playwright e2e support.** `gitnexus-web`'s `npm run test:e2e` needs Chromium libs that the base image doesn't ship. Use the host for e2e until a Playwright layer is added.
- **Codespaces tuning.** Host configuration mounts and `SYS_ADMIN` support are not actively tested there.
- **Non-Chromium browsers.** The UI profile provisions Chromium. Firefox/WebKit need their own browser binaries and system dependencies.
## Troubleshooting
If `[install-deps]` prints `npm warn EBADENGINE` with Node 22.16.0, run **Dev Containers: Rebuild Container** from the Command Palette after updating this checkout. The image now pins Node 22.23.3; workspace dependencies require at least 22.22.2 on the Node 22 line. Re-running `npm install` in the old container does not update its Node runtime.
| Symptom | Likely cause | Fix |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GitNexus devcontainer one-time Windows setup` banner from `initializeCommand` | First-time Windows-native Reopen-in-Container; `HOME` env var was missing | The script just ran `setx HOME "%USERPROFILE%"` for you. Close ALL VS Code windows (File → Exit) and reopen — see [Windows 11 setup](#windows-11-setup) |
| `bind source path does not exist: /.claude` (or similar) from Docker | Windows-native `HOME` env var is still missing even after one rebuild — `setx` may have failed or VS Code wasn't fully restarted | Run `setx HOME "%USERPROFILE%"` in a Windows shell manually, fully exit VS Code (check Task Manager that no `Code.exe` remains), reopen |
| `EACCES` / `EPERM` writing into `~/.claude`, `~/.codex`, or `~/.cursor` inside the container | Stale state from a previous container with a different effective UID | Move the affected dir aside and let the CLI rebuild it (`mv ~/.claude ~/.claude.bak` and log in again). Long-term: WSL2 setup, which doesn't hit this class of issue |
| `EPERM: operation not permitted, copyfile ... '.husky/_/h'` in `postCreateCommand` | Leftover `.husky/_/` from a previous container run on a Windows-side bind mount | `post-create.sh` already runs `rm -rf .husky/_` defensively. If you hit this on an older config, delete `.husky/_/` on the host and rebuild. Long-term: clone in WSL2 |
| `EPERM: operation not permitted, copyfile ... '.husky/_/h'` in `postCreateCommand` | Leftover `.husky/_/` from a previous container run on a Windows-side bind mount | `install-deps.sh` regenerates `.husky/_` and verifies the active hook. If you hit this on an older config, delete `.husky/_/` on the host and rebuild. Long-term: clone in WSL2 |
| Vite never hot-reloads | Repo cloned on Windows side, not WSL2 | Re-clone inside WSL2 |
| `gitnexus-web` can't reach the backend | `4747` was remapped or backend isn't running | Verify the Ports panel shows `4747` forwarded with no remap; start the backend with `cd gitnexus && npx gitnexus serve` |
| `npm install` fails on tree-sitter-swift / proto / dart | Native build toolchain missing | This shouldn't happen in the devcontainer — verify the apt layer installed `python3 make g++`. If iterating, set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` to skip the vendored grammars |

View file

@ -0,0 +1,71 @@
'use strict';
// Runs from the image before any workspace lifecycle script exists in the
// fresh volume. Never reset or overwrite a populated checkout.
const fs = require('node:fs');
const path = require('node:path');
const { execFileSync } = require('node:child_process');
function bootstrap(root, url, ref) {
if (!url || !ref || ref.startsWith('-')) throw new Error('A clone URL and branch are required');
fs.mkdirSync(root, { recursive: true });
const git = (...args) =>
execFileSync('git', args, {
cwd: root,
stdio: ['ignore', 'pipe', 'pipe'],
encoding: 'utf8',
}).trim();
git('check-ref-format', '--branch', ref);
if (!fs.existsSync(path.join(root, '.git'))) git('init');
let origin;
try {
origin = git('remote', 'get-url', 'origin');
} catch {
git('remote', 'add', 'origin', url);
origin = url;
}
if (origin !== url) throw new Error('Workspace volume has another origin; refusing to modify it');
try {
git('rev-parse', '--verify', 'HEAD');
return;
} catch {
/* Resume an interrupted initial fetch. */
}
const upstream = `refs/remotes/origin/${ref}`;
git('fetch', 'origin', `refs/heads/${ref}:${upstream}`);
git('checkout', '--no-overwrite-ignore', '--track', '-b', ref, upstream);
}
module.exports = { bootstrap };
if (require.main === module) {
const root = path.resolve(process.argv[2] || '/workspace');
// Repair UID changes on a reused workspace volume without following symlinks
// or descending into the separately mounted dependency volumes.
const uid = String(process.getuid());
const gid = String(process.getgid());
execFileSync(
'sudo',
[
'-n',
'find',
root,
'-xdev',
'(',
'!',
'-uid',
uid,
'-o',
'!',
'-gid',
gid,
')',
'-exec',
'chown',
'-h',
`${uid}:${gid}`,
'{}',
'+',
],
{ stdio: 'inherit' },
);
bootstrap(root, process.env.GITNEXUS_CLONE_URL, process.env.GITNEXUS_CLONE_REF);
}

View file

@ -0,0 +1,139 @@
'use strict';
const fs = require('node:fs');
const path = require('node:path');
const crypto = require('node:crypto');
const { execFileSync } = require('node:child_process');
const markerName = '.gitnexus-devcontainer-install.json';
const nativeInputs = [
'vendor',
'prebuilds/bundled',
'scripts/build-tree-sitter-grammars.cjs',
'scripts/prepare-tree-sitter-bundle.cjs',
'scripts/arm64-prebuild.cjs',
];
function fingerprint(directory, runtime = process) {
const hash = crypto.createHash('sha256');
hash.update(
JSON.stringify([
3,
runtime.version,
runtime.versions.modules,
runtime.platform,
runtime.arch,
runtime.npmVersion,
]),
);
for (const file of ['package.json', 'package-lock.json']) {
hash.update(file);
hash.update(fs.readFileSync(path.join(directory, file)));
}
const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json')));
for (const dependency of Object.values({
...manifest.dependencies,
...manifest.devDependencies,
...manifest.optionalDependencies,
})) {
if (typeof dependency !== 'string' || !dependency.startsWith('file:')) continue;
const sibling = path.resolve(directory, dependency.slice(5), 'package.json');
hash.update(fs.readFileSync(sibling));
}
if (fs.existsSync(path.join(directory, 'scripts/build-tree-sitter-grammars.cjs'))) {
hash.update(
JSON.stringify({ skipOptionalGrammars: process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS === '1' }),
);
// Blob IDs cover committed native inputs; the diff covers local tracked
// edits. Do not read npm credential files or hash large unchanged prebuilds.
for (const args of [
['ls-files', '-s', '--', ...nativeInputs],
['diff', 'HEAD', '--', ...nativeInputs],
]) {
hash.update(execFileSync('git', args, { cwd: directory, maxBuffer: 32 * 1024 * 1024 }));
}
}
return hash.digest('hex');
}
function ensureDependencies(directory, { run = runNpm, force = false, runtime = process } = {}) {
const expected = fingerprint(directory, runtime);
const marker = path.join(directory, 'node_modules', markerName);
const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json')));
const packages = Object.keys({ ...manifest.dependencies, ...manifest.devDependencies });
let saved;
try {
saved = JSON.parse(fs.readFileSync(marker, 'utf8'));
} catch {
/* First or interrupted install. */
}
const present = packages.every((name) =>
fs.existsSync(path.join(directory, 'node_modules', name, 'package.json')),
);
if (!force && present && saved?.fingerprint === expected) {
console.log(
`[install-deps] ${path.basename(directory)} dependencies unchanged; reusing volume`,
);
return false;
}
// Invalidate before installing: a failed attempt must never leave a reusable receipt.
fs.rmSync(marker, { force: true });
run(directory, ['ci']);
fs.mkdirSync(path.dirname(marker), { recursive: true });
const temporary = `${marker}.tmp`;
fs.writeFileSync(temporary, JSON.stringify({ fingerprint: fingerprint(directory, runtime) }));
fs.renameSync(temporary, marker);
return true;
}
function runNpm(directory, args) {
execFileSync('npm', args, { cwd: directory, stdio: 'inherit' });
}
function timed(label, action) {
const start = performance.now();
try {
return action();
} finally {
console.log(`[install-deps] ${label}: ${((performance.now() - start) / 1000).toFixed(2)}s`);
}
}
module.exports = { fingerprint, ensureDependencies, markerName };
if (require.main === module) {
const root = path.resolve(process.argv[2] || '/workspace');
const runtime = {
version: process.version,
versions: process.versions,
platform: process.platform,
arch: process.arch,
npmVersion: execFileSync('npm', ['--version'], { encoding: 'utf8' }).trim(),
};
const ensure = (directory) =>
timed(`dependencies ${path.basename(directory)}`, () =>
ensureDependencies(directory, { force: process.env.GITNEXUS_FORCE_DEPS === '1', runtime }),
);
ensure(root);
// Always restore and verify hooks, including the cached-install path.
runNpm(root, ['run', 'prepare']);
require('./verify-git-hooks.cjs').verifyGitHooks(root);
console.log('[install-deps] Husky hooks verified');
const shared = path.join(root, 'gitnexus-shared');
ensure(shared);
timed('shared build', () => runNpm(shared, ['run', 'build']));
const web = path.join(root, 'gitnexus-web');
ensure(web);
const core = path.join(root, 'gitnexus');
// A fresh npm ci already builds via prepare. A reused install still needs
// source compilation, even when manifests and lockfiles have not changed.
if (!ensure(core)) timed('CLI source build', () => runNpm(core, ['run', 'build']));
if (process.env.GITNEXUS_DEV_UI === '1') {
timed('Chromium provisioning', () =>
execFileSync(path.join(web, 'node_modules/.bin/playwright'), ['install', 'chromium'], {
cwd: web,
stdio: 'inherit',
}),
);
}
}

View file

@ -0,0 +1,252 @@
'use strict';
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { execFileSync, spawnSync } = require('node:child_process');
const { ensureDependencies, markerName } = require('./dependencies.cjs');
function fixture(t) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-dependencies-'));
t.after(() => fs.rmSync(root, { recursive: true, force: true }));
fs.writeFileSync(
path.join(root, 'package.json'),
JSON.stringify({ dependencies: { example: '1.0.0' } }),
);
fs.writeFileSync(path.join(root, 'package-lock.json'), '{}');
let installs = 0;
const run = () => {
installs++;
fs.mkdirSync(path.join(root, 'node_modules/example'), { recursive: true });
fs.writeFileSync(path.join(root, 'node_modules/example/package.json'), '{}');
};
return { root, run, count: () => installs };
}
test('reuses completed dependency volumes and reinstalls after lockfile changes', (t) => {
const f = fixture(t);
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
assert.equal(ensureDependencies(f.root, { run: f.run }), false);
fs.writeFileSync(path.join(f.root, 'package-lock.json'), '{"lockfileVersion":3}');
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
assert.equal(f.count(), 2);
});
test('repairs a missing direct dependency even if the receipt matches', (t) => {
const f = fixture(t);
ensureDependencies(f.root, { run: f.run });
fs.rmSync(path.join(f.root, 'node_modules/example'), { recursive: true });
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
});
test('runtime ABI changes and explicit repair invalidate reuse', (t) => {
const f = fixture(t);
ensureDependencies(f.root, { run: f.run });
const runtime = {
version: 'v22.23.3',
versions: { modules: 'different' },
platform: 'linux',
arch: 'arm64',
};
assert.equal(ensureDependencies(f.root, { run: f.run, runtime }), true);
assert.equal(ensureDependencies(f.root, { run: f.run, runtime, force: true }), true);
});
for (const group of ['dependencies', 'devDependencies', 'optionalDependencies']) {
test(`local file-dependency manifest changes in ${group} invalidate reuse`, (t) => {
const f = fixture(t);
const local = path.join(f.root, 'local');
fs.mkdirSync(local);
fs.writeFileSync(path.join(local, 'package.json'), '{"version":"1.0.0"}');
const manifest = { dependencies: { example: '1.0.0' } };
manifest[group] ??= {};
manifest[group].local = 'file:./local';
fs.writeFileSync(path.join(f.root, 'package.json'), JSON.stringify(manifest));
const run = () => {
f.run();
fs.mkdirSync(path.join(f.root, 'node_modules/local'), { recursive: true });
fs.copyFileSync(
path.join(local, 'package.json'),
path.join(f.root, 'node_modules/local/package.json'),
);
};
ensureDependencies(f.root, { run });
assert.equal(ensureDependencies(f.root, { run }), false);
fs.writeFileSync(path.join(local, 'package.json'), '{"version":"1.0.1"}');
assert.equal(ensureDependencies(f.root, { run }), true);
assert.equal(ensureDependencies(f.root, { run }), false);
assert.equal(f.count(), 2);
});
}
test('tracked native source and installer edits invalidate reuse', (t) => {
const f = fixture(t);
fs.mkdirSync(path.join(f.root, 'scripts'));
fs.mkdirSync(path.join(f.root, 'vendor'));
fs.mkdirSync(path.join(f.root, 'prebuilds/bundled'), { recursive: true });
fs.writeFileSync(path.join(f.root, 'scripts/build-tree-sitter-grammars.cjs'), '// original');
fs.writeFileSync(path.join(f.root, 'scripts/arm64-prebuild.cjs'), '// original validator');
fs.writeFileSync(path.join(f.root, 'prebuilds/bundled/manifest.json'), '{"schemaVersion":1}');
fs.writeFileSync(path.join(f.root, 'prebuilds/bundled/grammar.node'), Buffer.from([1, 2, 3]));
fs.writeFileSync(path.join(f.root, 'vendor/grammar.c'), '// original');
const git = (...args) =>
execFileSync(
'git',
[
'-c',
'core.hooksPath=/dev/null',
'-c',
'commit.gpgsign=false',
'-c',
'user.name=Fixture',
'-c',
'user.email=fixture@example.invalid',
...args,
],
{ cwd: f.root, stdio: 'pipe' },
);
git('init');
git(
'add',
'package.json',
'package-lock.json',
'scripts/build-tree-sitter-grammars.cjs',
'scripts/arm64-prebuild.cjs',
'prebuilds/bundled',
'vendor/grammar.c',
);
git('commit', '-m', 'fixture');
ensureDependencies(f.root, { run: f.run });
assert.equal(ensureDependencies(f.root, { run: f.run }), false);
fs.writeFileSync(path.join(f.root, 'vendor/grammar.c'), '// changed grammar');
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
fs.writeFileSync(
path.join(f.root, 'scripts/build-tree-sitter-grammars.cjs'),
'// changed installer',
);
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
for (const [file, content] of [
['scripts/arm64-prebuild.cjs', '// changed validator'],
['prebuilds/bundled/manifest.json', '{"schemaVersion":2}'],
['prebuilds/bundled/grammar.node', Buffer.from([4, 5, 6])],
]) {
fs.writeFileSync(path.join(f.root, file), content);
assert.equal(ensureDependencies(f.root, { run: f.run }), true, file);
assert.equal(ensureDependencies(f.root, { run: f.run }), false, file);
}
});
test('failed reinstall removes its receipt and is retried', (t) => {
const f = fixture(t);
ensureDependencies(f.root, { run: f.run });
assert.throws(
() =>
ensureDependencies(f.root, {
force: true,
run: () => {
throw new Error('install failed');
},
}),
/install failed/,
);
assert.equal(fs.existsSync(path.join(f.root, 'node_modules', markerName)), false);
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
});
test('changing optional-grammar policy invalidates the core install receipt', (t) => {
const f = fixture(t);
const previous = process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS;
t.after(() => {
if (previous === undefined) delete process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS;
else process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS = previous;
});
fs.mkdirSync(path.join(f.root, 'scripts'));
fs.writeFileSync(path.join(f.root, 'scripts/build-tree-sitter-grammars.cjs'), '// fixture');
execFileSync('git', ['init', '-q'], { cwd: f.root });
execFileSync(
'git',
[
'-c',
'core.hooksPath=/dev/null',
'-c',
'commit.gpgsign=false',
'-c',
'user.name=Fixture',
'-c',
'user.email=fixture@example.invalid',
'commit',
'--allow-empty',
'-m',
'fixture',
],
{ cwd: f.root, stdio: 'pipe' },
);
process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS = '1';
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
assert.equal(ensureDependencies(f.root, { run: f.run }), false);
delete process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS;
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS = '0';
assert.equal(ensureDependencies(f.root, { run: f.run }), false);
process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS = '1';
assert.equal(ensureDependencies(f.root, { run: f.run }), true);
assert.equal(f.count(), 3);
});
test('cached lifecycle restores real Husky and rebuilds changed sources', (t) => {
const f = fixture(t);
fs.writeFileSync(path.join(f.root, 'package.json'), '{}');
for (const name of ['gitnexus', 'gitnexus-web', 'gitnexus-shared']) {
fs.mkdirSync(path.join(f.root, name));
fs.writeFileSync(path.join(f.root, name, 'package.json'), '{}');
fs.writeFileSync(path.join(f.root, name, 'package-lock.json'), '{}');
}
fs.mkdirSync(path.join(f.root, '.husky'));
fs.writeFileSync(path.join(f.root, '.husky/pre-commit'), 'exit 0\n');
const global = path.join(f.root, 'gitconfig');
fs.writeFileSync(global, '');
const env = {
...process.env,
PATH: `${f.root}:${process.env.PATH}`,
HUSKY: '',
GIT_CONFIG_GLOBAL: global,
GIT_CONFIG_NOSYSTEM: '1',
GIT_CONFIG_COUNT: '0',
GITNEXUS_FORCE_DEPS: '0',
GITNEXUS_DEV_UI: '0',
};
for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'])
delete env[key];
execFileSync('git', ['init', '-q'], { cwd: f.root, env });
const husky = path.resolve(__dirname, '../node_modules/husky/bin.js');
fs.writeFileSync(
path.join(f.root, 'npm'),
`#!${process.execPath}
const fs = require('node:fs');
const path = require('node:path');
const args = process.argv.slice(2);
if (args[0] === '--version') { console.log('10.9.2'); process.exit(0); }
fs.appendFileSync(${JSON.stringify(path.join(f.root, 'calls'))}, path.basename(process.cwd()) + ':' + args.join(' ') + '\\n');
if (args[0] === 'ci') fs.mkdirSync('node_modules', { recursive: true });
if (args.join(' ') === 'run prepare') require('node:child_process').execFileSync(process.execPath, [${JSON.stringify(husky)}], { stdio: 'inherit' });
`,
{ mode: 0o755 },
);
const invoke = () => {
const result = spawnSync(process.execPath, [path.join(__dirname, 'dependencies.cjs'), f.root], {
env,
encoding: 'utf8',
});
assert.equal(result.status, 0, result.stderr);
};
invoke();
fs.rmSync(path.join(f.root, '.husky/_'), { recursive: true });
fs.writeFileSync(path.join(f.root, 'calls'), '');
invoke();
const calls = fs.readFileSync(path.join(f.root, 'calls'), 'utf8');
assert.doesNotMatch(calls, /:ci/);
assert.match(calls, /:run prepare/);
assert.match(calls, /gitnexus:run build/);
assert.ok(fs.existsSync(path.join(f.root, '.husky/_/pre-commit')));
});

View file

@ -0,0 +1,23 @@
'use strict';
const path = require('node:path');
const { spawnSync } = require('node:child_process');
const { workerBudget } = require('./resources.cjs');
const [target, ...args] = process.argv.slice(2);
if (!['core', 'web'].includes(target))
throw new Error('Usage: node .devcontainer/dev-test.cjs core|web [Vitest arguments]');
const root = path.resolve(__dirname, '..', target === 'core' ? 'gitnexus' : 'gitnexus-web');
const workers = workerBudget();
console.log(`[dev-test] ${target}: ${workers} workers (override with GITNEXUS_DEV_TEST_WORKERS)`);
const result = spawnSync(
process.execPath,
[
path.join(root, 'node_modules/vitest/vitest.mjs'),
...(args.includes('--watch') ? [] : ['run']),
...args,
`--maxWorkers=${workers}`,
],
{ cwd: root, stdio: 'inherit' },
);
if (result.error) console.error(result.error.message);
process.exitCode = result.status ?? 1;

View file

@ -43,6 +43,11 @@
"remoteUser": "node",
"updateRemoteUserUID": true,
// Reap orphaned subprocesses from CLI workers and test runs.
"init": true,
// Allow the startup helper to attempt a 9p remount. See README for the
// effect on read-only mount protections and how to disable it.
"capAdd": ["SYS_ADMIN"],
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated",
"workspaceFolder": "/workspace",
@ -54,13 +59,11 @@
// single config files (always), plus the shareable subfolders (Claude
// plugins/skills/agents/memory/commands; Codex plugins/prompts/memories/
// skills; Cursor plugins/rules/commands/agents/skills) ONCE on first create.
// Everything copied lands in the per-container named volume (role 2). It is
// read-only so a container process can NEVER write back to the host — there
// is no read-write bind into the host's CLI config at all. This protects the
// host's on-disk setup: a compromised in-container dependency cannot drop a
// skill, agent, command, or plugin onto the host for the next host session
// to load. The cost is that host and container DIVERGE after the first
// create — host edits don't reach the container until you wipe the config
// Everything copied lands in the per-container named volume (role 2).
// The host stage is read-only; lifecycle scripts write to container copies.
// SYS_ADMIN is enabled for 9p tuning, so read-only flags are not a security
// boundary against privileged container code. Host and container DIVERGE
// after first create — host edits don't reach it until you wipe the config
// volume and rebuild. See README § "Trust boundary, concretely".
//
// 2. AI CLI container config — one named volume per devcontainer. CODEX_HOME
@ -202,19 +205,19 @@
// "source=${localEnv:HOME}/.cursor/projects,target=/home/node/.cursor/projects,type=bind",
// Read-only host stage that post-create.sh copies FROM on container-create.
// It is read-only so a container process can never write back to host CLI
// state — that write-back is the attack vector we block. post-create.sh
// Lifecycle scripts do not write back to host CLI state. The default
// SYS_ADMIN capability can weaken read-only mount protections. post-create.sh
// reads two kinds of thing from here: (a) the credential + identity files
// (copied into the volume always), and (b) the shareable dirs — skills,
// agents, plugins, memory, commands, prompts, rules — which it copies into
// the volume ONCE on first create (see step 3/4). Nothing here is bound
// read-write into the container, so the host's on-disk setup is protected.
// read-write into the container by this configuration.
"source=${localEnv:HOME}/.claude,target=/host/.claude,type=bind,readonly",
"source=${localEnv:HOME}/.codex,target=/host/.codex,type=bind,readonly",
"source=${localEnv:HOME}/.cursor,target=/host/.cursor,type=bind,readonly",
// Read-only host stage for the claude-mem store. post-create.sh COPIES it
// into the claude-mem named volume on first create (seed-once). Read-only so
// the container can never write back to the host's live DB — the seed is a
// the seed script does not write back to the host's live DB — the seed is a
// one-way snapshot. ensure-host-config-dirs.cjs creates ~/.claude-mem on the
// host so this bind resolves even when claude-mem was never installed there.
"source=${localEnv:HOME}/.claude-mem,target=/host/.claude-mem,type=bind,readonly",
@ -229,8 +232,8 @@
// now COPIED once from the read-only /host/.<cli> stage into the per-container
// named volume by post-create.sh (step 3/4), exactly like claude-mem and the
// session volumes. Trade-offs of the copy model:
// - The container gets its OWN writable copy and can never write back to
// the host. Host setup is protected.
// - CLI edits use the container's OWN writable copy. SYS_ADMIN can bypass
// read-only protections; see README for the trust boundary.
// - It is seed-ONCE: host edits made after first create don't reach the
// container until you remove the config volume and rebuild. Container
// edits persist across rebuilds. (See README § Rebuild/reset to re-seed.)
@ -277,6 +280,7 @@
"source=${localEnv:HOME}/.azure,target=/home/node/.azure,type=bind,readonly",
"source=commandhistory-${devcontainerId},target=/commandhistory,type=volume",
"source=npm-cache-${devcontainerId},target=/home/node/.npm,type=volume",
"source=gitnexus-store-${devcontainerId},target=/home/node/.gitnexus,type=volume",
"source=${localWorkspaceFolderBasename}-root-node-modules-${devcontainerId},target=/workspace/node_modules,type=volume",
"source=${localWorkspaceFolderBasename}-gitnexus-node-modules-${devcontainerId},target=/workspace/gitnexus/node_modules,type=volume",
"source=${localWorkspaceFolderBasename}-gitnexus-web-node-modules-${devcontainerId},target=/workspace/gitnexus-web/node_modules,type=volume",
@ -314,7 +318,10 @@
// dependency explicit instead of silently following the default.
"containerEnv": {
"CODEX_HOME": "/home/node/.codex",
"HISTFILE": "/commandhistory/.zsh_history"
"HISTFILE": "/commandhistory/.zsh_history",
"GITNEXUS_HOME": "/home/node/.gitnexus",
"WORKSPACE_9P_TUNE": "${localEnv:WORKSPACE_9P_TUNE:1}",
"WORKSPACE_9P_MSIZE": "${localEnv:WORKSPACE_9P_MSIZE:1048576}"
},
"customizations": {
@ -332,6 +339,26 @@
"source.fixAll.eslint": "explicit"
},
"files.eol": "\n",
// Generated indexes and sibling worktrees can dwarf the source tree.
// These exclusions affect VS Code only; Vite and test watchers keep
// their own configuration.
"files.watcherExclude": {
"**/node_modules/**": true,
"**/.gitnexus/**": true,
"**/.worktrees/**": true,
"**/.claude/worktrees/**": true,
"**/dist/**": true,
"**/coverage/**": true
},
"search.exclude": {
"**/node_modules": true,
"**/.gitnexus": true,
"**/.worktrees": true,
"**/.claude/worktrees": true,
"**/dist": true,
"**/coverage": true
},
"git.autoRepositoryDetection": "openEditors",
"terminal.integrated.defaultProfile.linux": "zsh",
"terminal.integrated.profiles.linux": {
"bash": { "path": "bash", "icon": "terminal-bash" },
@ -361,15 +388,18 @@
},
// Lifecycle split (from the Dev Container spec):
// - `updateContentCommand` runs on container-create AND whenever the
// workspace content changes, such as a lockfile update. It owns installing
// the workspace dependencies. Re-installing on every container-create
// wastes time when nothing changed, but it must re-run when deps change.
// - `updateContentCommand` prepares dependencies after workspace content is
// available during creation/prebuild refresh. It reuses successful installs
// when inputs match. In a running container, explicitly run install-deps.sh
// after pulling dependency changes; this hook is not a lockfile watcher.
// - `postCreateCommand` runs once on container-create. It owns syncing the
// AI CLI credentials and identity from the host. That work should happen
// exactly once per container instance, not on every content update.
// Run both with an explicit `bash` so they don't depend on the script's
// - `postStartCommand` attempts 9p tuning on every start unless disabled; failure
// never blocks startup.
// Run lifecycle scripts with an explicit `bash` so they don't depend on the script's
// executable bit surviving the workspace bind mount.
"updateContentCommand": "bash .devcontainer/install-deps.sh",
"postCreateCommand": "bash .devcontainer/post-create.sh"
"postCreateCommand": "bash .devcontainer/post-create.sh",
"postStartCommand": "bash .devcontainer/tune-9p.sh || true"
}

39
.devcontainer/doctor.cjs Normal file
View file

@ -0,0 +1,39 @@
'use strict';
const path = require('node:path');
const os = require('node:os');
const { execFileSync } = require('node:child_process');
const { read, workerBudget } = require('./resources.cjs');
const root = path.resolve(process.argv[2] || '/workspace');
console.log(
`[doctor] Node ${process.version}; ${os.availableParallelism()} available CPUs; suggested dev test workers ${workerBudget()}`,
);
for (const file of [
'/sys/fs/cgroup/memory.max',
'/sys/fs/cgroup/memory.current',
'/sys/fs/cgroup/memory.events',
'/sys/fs/cgroup/cpu.max',
'/proc/pressure/memory',
'/proc/pressure/io',
'/proc/sys/fs/inotify/max_user_watches',
'/proc/sys/fs/inotify/max_user_instances',
])
console.log(`[doctor] ${file}: ${read(file)}`);
for (const [command, args] of [
['findmnt', ['-rn', '-T', root, '-o', 'FSTYPE,OPTIONS']],
['df', ['-h', root]],
['df', ['-i', root]],
['bash', ['-c', 'ulimit -n']],
]) {
try {
console.log(execFileSync(command, args, { encoding: 'utf8', timeout: 5000 }).trim());
} catch {
console.log(`[doctor] ${command}: unavailable`);
}
}
try {
require('./verify-git-hooks.cjs').verifyGitHooks(root);
console.log('[doctor] Husky hooks verified');
} catch (error) {
console.log(`[doctor] Husky: ${error.message}`);
}

View file

@ -1,25 +1,26 @@
#!/usr/bin/env bash
# Devcontainer updateContentCommand. The Dev Container spec runs this when the
# container is created AND whenever workspace content changes (for example a
# lockfile update). This script installs workspace dependencies only. Syncing AI
# Devcontainer updateContentCommand. Runs during container creation after
# workspace content is available. Run this script explicitly after pulling
# dependency changes into an already-running container. Syncing AI
# CLI state lives in post-create.sh, which runs once right after this.
#
# Why the split: updateContentCommand re-runs on content changes, but
# postCreateCommand runs only at container-create. Keeping `npm install` here
# means a rebuild after pulling new dependencies refreshes them. The AI CLI
# Why the split: updateContentCommand handles dependency readiness, while
# postCreateCommand handles AI CLI state. Installation receipts reuse unchanged
# dependency volumes and refresh them when inputs change. The AI CLI
# credential and path-translation work does not re-run each time.
set -euo pipefail
cd /workspace
echo "[install-deps] 1/4: chown workspace node_modules + npm cache mount points"
ownership_start=$SECONDS
# The named volumes (workspace/*/node_modules and ~/.npm) are created at first
# mount. They inherit ownership from the image's UID before realignment. Then
# `updateRemoteUserUID: true` shifts the `node` user's UID. Now the volumes are
# owned by the old, stale UID and npm install cannot write to them. So we chown
# again here, after realignment. Running it again later changes nothing.
#
# We use `find -xdev -exec chown -h` (the same idiom as post-create.sh) instead
# We use `find -xdev` with `chown -h` (the same idiom as post-create.sh) instead
# of a plain `chown -R`. There are two separate guards. First, `-xdev` stops
# find from descending past each volume's own filesystem, so it won't recurse
# into a host folder mounted underneath. Second, `-h` makes chown change the
@ -28,41 +29,41 @@ echo "[install-deps] 1/4: chown workspace node_modules + npm cache mount points"
# node_modules/.bin link) would either send the chown onto a target on another
# filesystem, or fail to follow and abort the whole script under `set -e`. For
# regular files and directories `-h` does nothing, so the ownership fix is the
# same.
# same. Only change entries with the wrong owner or group: carried-over volumes
# can contain hundreds of thousands of files that already have correct ownership.
for d in /workspace/node_modules \
/workspace/gitnexus/node_modules \
/workspace/gitnexus-web/node_modules \
/workspace/gitnexus-shared/node_modules \
/home/node/.npm; do
sudo find "$d" -xdev -exec chown -h node:node {} +
/home/node/.npm \
/home/node/.gitnexus \
/home/node/.cache/ms-playwright; do
[ -d "$d" ] || continue
sudo find "$d" -xdev \( ! -user node -o ! -group node \) -exec chown -h node:node {} +
done
echo "[install-deps] ownership repair: $((SECONDS - ownership_start))s"
# Reuse the persistent npm cache without waiting for metadata freshness checks.
# Cache misses still use the registry. Keep install lifecycle scripts enabled for
# native addons and prepare builds; audits remain available via `npm audit`.
export npm_config_prefer_offline=true
export npm_config_audit=false
export npm_config_fund=false
echo "[install-deps] 2/4: clear stale .husky/_ runtime cache"
# On Docker Desktop for Windows, the bind-mount permission translation won't let
# the new container's `node` user overwrite a `.husky/_/h` file that an earlier
# container wrote under a different UID. So we delete it. `.husky/_` is a
# gitignored runtime cache, and husky rebuilds it during the root `npm install`.
# The tracked .husky/pre-commit is preserved. Verification below fails setup if
# regeneration was skipped or failed, so this cleanup cannot silently disable it.
# Husky upstream has no fix for this UID clash.
rm -rf .husky/_
echo "[install-deps] 3/4: npm install at root, then gitnexus-shared (build required)"
# Install order matters. Root goes first, for lint-staged, husky, and prettier.
# Then gitnexus-shared, which must be built before installing gitnexus-web or
# gitnexus. Both of those depend on it via `file:../gitnexus-shared`.
npm install
cd /workspace/gitnexus-shared
npm install
npm run build
echo "[install-deps] 3/4: restore dependencies, verify Husky, and build sources"
node .devcontainer/dependencies.cjs /workspace
echo "[install-deps] 4/4: npm install gitnexus-web, then gitnexus"
# gitnexus-web goes before gitnexus. The gitnexus `prepare` script runs
# scripts/build.js, which compiles gitnexus-web when that directory is present.
# In the devcontainer the whole workspace is bind-mounted, so gitnexus-web/ is
# present when gitnexus installs. The production Dockerfiles COPY only selected
# files, so the directory is not present there.
cd /workspace/gitnexus-web
npm install
cd /workspace/gitnexus
npm install
echo "[install-deps] 4/4: environment summary"
node .devcontainer/doctor.cjs /workspace
echo "[install-deps] done"

View file

@ -3,8 +3,8 @@
# created. devcontainer.json wires it up via `postCreateCommand`. Workspace
# dependencies are installed elsewhere, in install-deps.sh (`updateContentCommand`).
# That script runs BEFORE this one — that is the order the devcontainer spec
# defines. This script does one job: sync the AI CLI credentials and identity
# from the host.
# defines. This script prepares AI CLI binaries and syncs configuration from
# the host into the container's own volumes.
set -euo pipefail
@ -67,9 +67,15 @@ for d in "${DIRS[@]}"; do
# devcontainer.json without its matching DIRS entry being removed too — then
# provisioning skips it instead of failing before credentials ever sync.
[ -d "$d" ] || continue
sudo find "$d" -xdev -exec chown -h node:node {} +
# Avoid chown syscalls for the already-correct entries on reused volumes.
sudo find "$d" -xdev \( ! -user node -o ! -group node \) -exec chown -h node:node {} +
done
# The standalone installer stores Codex under ~/.codex, which a reused config
# volume hides. Restore the image's native package without downloading it again
# or overwriting a working standalone installation already in that volume.
bash "$SCRIPT_DIR/seed-codex.sh"
echo "[post-create] 2/4: sync AI CLI credentials + identity from host"
# Clean up after an older devcontainer design (Option B). Back then these paths
# were symlinks pointing into the read-only host stage

163
.devcontainer/profile.cjs Normal file
View file

@ -0,0 +1,163 @@
'use strict';
const fs = require('node:fs');
const path = require('node:path');
function replaceOnce(text, pattern, replacement) {
const matches = text.match(new RegExp(pattern.source, 'g'));
if (matches?.length !== 1) throw new Error(`Canonical devcontainer layout changed: ${pattern}`);
return text.replace(pattern, () => replacement);
}
function profile(
source,
{
native = false,
ui = false,
image,
imageOnly = false,
ref = 'main',
playwright,
url = 'https://github.com/abhigyanpatwari/GitNexus.git',
} = {},
) {
if (imageOnly && image) throw new Error('--image cannot be used with image-build');
if (
typeof ref !== 'string' ||
!/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(ref) ||
ref === 'HEAD' ||
ref.includes('..') ||
ref.endsWith('.') ||
ref.split('/').some((part) => !part || part.startsWith('.') || part.endsWith('.lock'))
)
throw new Error('Invalid clone branch');
// Character safety check only; Docker validates the image reference grammar.
if (image && !/^[a-zA-Z0-9][a-zA-Z0-9./:_@-]*$/.test(image))
throw new Error('Invalid image reference');
if (
native &&
!/^(?:https:\/\/[a-zA-Z0-9.-]+(?::[0-9]+)?\/|ssh:\/\/git@[a-zA-Z0-9.-]+(?::[0-9]+)?\/|git@[a-zA-Z0-9.-]+:)[a-zA-Z0-9._/-]+$/.test(
url,
)
)
throw new Error('Invalid clone URL; use HTTPS or Git SSH without embedded credentials');
let result = source;
if (image) {
const start = result.indexOf(' "build": {');
const end = result.indexOf('\n // Runs on the HOST', start);
if (start < 0 || end < 0) throw new Error('Canonical build block changed');
result = result.slice(0, start) + ` "image": ${JSON.stringify(image)},\n` + result.slice(end);
} else {
result = replaceOnce(result, /"dockerfile": "Dockerfile"/, '"dockerfile": "../Dockerfile"');
result = replaceOnce(result, /"context": "\."/, '"context": ".."');
if (ui) {
if (!/^[0-9]+\.[0-9]+\.[0-9]+$/.test(playwright))
throw new Error('Locked Playwright version required');
result = replaceOnce(
result,
/"BUN_VERSION":/,
`"INSTALL_BROWSER_DEPS": "true",\n "PLAYWRIGHT_VERSION": ${JSON.stringify(playwright)},\n "BUN_VERSION":`,
);
}
}
if (native) {
result = replaceOnce(
result,
/"workspaceMount": "[^"\n]+"/,
'"workspaceMount": "source=gitnexus-workspace-${devcontainerId},target=/workspace,type=volume"',
);
result = replaceOnce(
result,
/"CODEX_HOME":/,
`"GITNEXUS_CLONE_URL": ${JSON.stringify(url)},\n ` +
`"GITNEXUS_CLONE_REF": ${JSON.stringify(ref)},\n "CODEX_HOME":`,
);
result = replaceOnce(
result,
/"updateContentCommand":/,
'"onCreateCommand": "node /usr/local/share/gitnexus-devcontainer/bootstrap-native.cjs",\n "updateContentCommand":',
);
}
if (imageOnly) {
const start = result.indexOf(' "build": {');
const end = result.indexOf('\n // Runs on the HOST', start);
const features = result.match(/"features": \{[\s\S]*?\n \},/);
if (start < 0 || end < 0 || !features)
throw new Error('Image build requires the canonical build and feature blocks');
// Publish toolchain metadata only. Lifecycle hooks and host mounts belong
// to the consuming profile, avoiding duplicate hook execution on attach.
return '{\n' + result.slice(start, end) + '\n ' + features[0].slice(0, -1) + '\n}\n';
}
if (ui) {
result = replaceOnce(
result,
/"CODEX_HOME":/,
'"GITNEXUS_DEV_UI": "1",\n "PLAYWRIGHT_BROWSERS_PATH": "/home/node/.cache/ms-playwright",\n "CODEX_HOME":',
);
result = replaceOnce(
result,
/"source=npm-cache-/,
'"source=playwright-cache-${devcontainerId},target=/home/node/.cache/ms-playwright,type=volume",\n "source=npm-cache-',
);
result = replaceOnce(
result,
/"workspaceMount":/,
'"runArgs": ["--shm-size=1g"],\n "workspaceMount":',
);
}
return result;
}
module.exports = { profile };
if (require.main === module) {
const [mode, ...args] = process.argv.slice(2);
if (!['native', 'ui', 'prebuilt', 'image-build'].includes(mode))
throw new Error(
'Usage: node .devcontainer/profile.cjs native [--ui] [--image IMAGE] [--ref BRANCH] [--url URL]\n' +
' node .devcontainer/profile.cjs ui [--image IMAGE]\n' +
' node .devcontainer/profile.cjs prebuilt [--ui] [--image IMAGE]\n' +
' node .devcontainer/profile.cjs image-build [--ui]',
);
const options = new Map();
for (let i = 0; i < args.length; i++) {
const flag = args[i];
if (!['--ui', '--image', '--ref', '--url'].includes(flag))
throw new Error(`Unknown profile argument: ${flag}`);
if (options.has(flag)) throw new Error(`Duplicate profile argument: ${flag}`);
if (flag === '--ui') options.set(flag, true);
else {
const value = args[++i];
if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
options.set(flag, value);
}
}
if (mode === 'image-build' && options.has('--image'))
throw new Error('--image cannot be used with image-build');
if (mode !== 'native' && (options.has('--ref') || options.has('--url')))
throw new Error('--ref and --url require the native profile');
const lock = JSON.parse(
fs.readFileSync(path.join(__dirname, '../gitnexus-web/package-lock.json')),
);
const output = path.join(__dirname, 'generated');
const contents = profile(fs.readFileSync(path.join(__dirname, 'devcontainer.json'), 'utf8'), {
native: mode === 'native',
ui: mode === 'ui' || options.has('--ui'),
image:
options.get('--image') ||
(mode === 'prebuilt'
? `ghcr.io/abhigyanpatwari/gitnexus-devcontainer:main${options.has('--ui') ? '-ui' : ''}`
: undefined),
imageOnly: mode === 'image-build',
ref: options.get('--ref'),
url: options.get('--url'),
playwright: lock.packages['node_modules/@playwright/test'].version,
});
fs.mkdirSync(output, { recursive: true });
fs.writeFileSync(path.join(output, 'devcontainer.json'), contents);
fs.copyFileSync(
path.join(__dirname, 'devcontainer-lock.json'),
path.join(output, 'devcontainer-lock.json'),
);
console.log(
'Generated .devcontainer/generated/devcontainer.json; select it when reopening in container. Regenerate after updating the main configuration.',
);
}

View file

@ -0,0 +1,286 @@
'use strict';
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { execFileSync, spawnSync } = require('node:child_process');
const ts = require('typescript');
const { profile } = require('./profile.cjs');
const { bootstrap } = require('./bootstrap-native.cjs');
const source = fs.readFileSync(path.join(__dirname, 'devcontainer.json'), 'utf8');
const parse = (text) => {
const result = ts.parseConfigFileTextToJson('devcontainer.json', text);
assert.equal(result.error, undefined);
return result.config;
};
test('native/UI profile inherits hooks, storage and defaults while changing workspace and browser setup', () => {
const c = parse(
profile(source, { native: true, ui: true, playwright: '1.63.0', ref: 'feature/test' }),
);
assert.match(c.workspaceMount, /type=volume/);
assert.match(c.onCreateCommand, /bootstrap-native/);
assert.equal(c.containerEnv.GITNEXUS_CLONE_REF, 'feature/test');
assert.equal(c.build.args.PLAYWRIGHT_VERSION, '1.63.0');
assert.equal(c.containerEnv.GITNEXUS_DEV_UI, '1');
assert.ok(c.mounts.some((m) => m.includes('ms-playwright')));
assert.ok(c.mounts.some((m) => m.includes('/home/node/.gitnexus')));
assert.deepEqual(c.capAdd, ['SYS_ADMIN']);
assert.equal(c.updateContentCommand, 'bash .devcontainer/install-deps.sh');
});
test('image consumers retain configured features and runtime lifecycle', () => {
for (const options of [{}, { native: true }, { ui: true }, { native: true, ui: true }]) {
const image = 'ghcr.io/example/devcontainer@sha256:abcd';
const c = parse(profile(source, { ...options, image }));
assert.equal(c.build, undefined);
assert.equal(c.image, image);
assert.deepEqual(c.features, parse(source).features);
assert.ok(c.features['ghcr.io/devcontainers/features/github-cli:1']);
assert.equal(c.postCreateCommand, 'bash .devcontainer/post-create.sh');
}
});
test('image selection accepts short names, uppercase tags, ports and digests', () => {
for (const image of [
'a',
'a:RC',
'ghcr.io/example/image:ReleaseCandidate',
'localhost:5000/example/image:ReleaseCandidate',
`ghcr.io/example/image@sha256:${'a'.repeat(64)}`,
`ghcr.io/example/image:RC@sha256:${'a'.repeat(64)}`,
]) {
assert.equal(parse(profile(source, { image })).image, image);
}
for (const image of [
'--privileged',
'image;bad',
'image name',
'image\nname',
'$(id)',
'"image"',
])
assert.throws(() => profile(source, { image }), /Invalid image reference/);
});
test('published toolchain metadata excludes host mounts and lifecycle hooks', () => {
const c = parse(profile(source, { imageOnly: true, ui: true, playwright: '1.63.0' }));
assert.equal(c.mounts, undefined);
assert.equal(c.updateContentCommand, undefined);
assert.equal(c.containerEnv, undefined);
assert.equal(c.build.args.INSTALL_BROWSER_DEPS, 'true');
assert.ok(c.features['ghcr.io/devcontainers/features/github-cli:1']);
});
test('profile generator rejects unsafe values and changed canonical layout', () => {
assert.throws(() => profile(source, { ref: '--upload-pack=bad' }), /Invalid/);
assert.throws(() => profile(source, { image: 'image;bad' }), /Invalid/);
assert.throws(
() => profile(source, { imageOnly: true, image: 'ghcr.io/example/image' }),
/--image cannot/,
);
for (const url of ['--upload-pack=bad', 'ext::command', 'https://token@github.com/user/repo.git'])
assert.throws(() => profile(source, { native: true, url }), /Invalid clone URL/);
assert.throws(
() => profile(source.replace('"context": "."', '"context": "elsewhere"')),
/layout changed/,
);
});
test('native branch validation rejects invalid Git refs before generation', () => {
for (const ref of [
'foo..',
'topic/.hidden',
'topic/name.lock',
'topic/name.lock/child',
'topic//child',
'topic/name.',
'topic/',
'HEAD',
]) {
assert.notEqual(spawnSync('git', ['check-ref-format', '--branch', ref]).status, 0);
assert.throws(() => profile(source, { native: true, ref }), /Invalid clone branch/);
}
for (const ref of [
'main',
'feature/fix-123',
'release/v1.2.3',
'topic/name.locked',
'topic/name.LOCK',
]) {
assert.equal(spawnSync('git', ['check-ref-format', '--branch', ref]).status, 0);
assert.equal(
parse(profile(source, { native: true, ref })).containerEnv.GITNEXUS_CLONE_REF,
ref,
);
}
});
test('UI variants preserve empty, custom, and absent capability selections', () => {
for (const capabilities of [[], ['SYS_PTRACE'], undefined]) {
const customized = source.replace(
' "capAdd": ["SYS_ADMIN"],',
capabilities === undefined ? '' : ` "capAdd": ${JSON.stringify(capabilities)},`,
);
for (const options of [{}, { native: true }, { image: 'ghcr.io/example/devcontainer:ui' }]) {
const c = parse(profile(customized, { ...options, ui: true, playwright: '1.63.0' }));
assert.deepEqual(c.capAdd, capabilities);
assert.deepEqual(c.runArgs, ['--shm-size=1g']);
}
}
});
test('native profiles accept fork remotes over HTTPS and Git SSH', () => {
for (const url of [
'https://github.com/contributor/GitNexus.git',
'git@github.com:contributor/GitNexus.git',
'ssh://git@example.com:2222/contributor/GitNexus.git',
]) {
const c = parse(profile(source, { native: true, url, ref: 'feature/fork-only' }));
assert.equal(c.containerEnv.GITNEXUS_CLONE_URL, url);
assert.equal(c.containerEnv.GITNEXUS_CLONE_REF, 'feature/fork-only');
}
});
test('profile CLI validates combinations before writing and generates fork configuration', (t) => {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-profile-cli-'));
t.after(() => fs.rmSync(root, { recursive: true, force: true }));
const config = path.join(root, '.devcontainer');
fs.mkdirSync(config);
for (const file of ['profile.cjs', 'devcontainer.json', 'devcontainer-lock.json'])
fs.copyFileSync(path.join(__dirname, file), path.join(config, file));
fs.mkdirSync(path.join(root, 'gitnexus-web'));
fs.writeFileSync(
path.join(root, 'gitnexus-web/package-lock.json'),
JSON.stringify({
packages: { 'node_modules/@playwright/test': { version: '1.63.0' } },
}),
);
const run = (...args) =>
spawnSync(process.execPath, [path.join(config, 'profile.cjs'), ...args], {
cwd: root,
encoding: 'utf8',
});
for (const [args, error] of [
[
['image-build', '--image', 'ghcr.io/example/image'],
/--image cannot be used with image-build/,
],
[['native', '--url'], /--url requires a value/],
[['native', '--ref', '--ui'], /--ref requires a value/],
[['prebuilt', '--url', 'https://github.com/user/repo.git'], /require the native profile/],
[['native', '--ref', 'main', '--ref', 'other'], /Duplicate profile argument/],
[['native', '--ref', 'foo..'], /Invalid clone branch/],
]) {
const result = run(...args);
assert.notEqual(result.status, 0);
assert.match(result.stderr, error);
assert.equal(fs.existsSync(path.join(config, 'generated')), false);
}
const result = run(
'native',
'--url',
'https://github.com/contributor/GitNexus.git',
'--ref',
'feature/fork-only',
);
assert.equal(result.status, 0, result.stderr);
const c = parse(fs.readFileSync(path.join(config, 'generated/devcontainer.json'), 'utf8'));
assert.equal(c.containerEnv.GITNEXUS_CLONE_URL, 'https://github.com/contributor/GitNexus.git');
assert.equal(c.containerEnv.GITNEXUS_CLONE_REF, 'feature/fork-only');
for (const args of [
['prebuilt'],
['prebuilt', '--ui'],
['native', '--image', 'a'],
['ui', '--image', 'ghcr.io/example/image:ReleaseCandidate'],
]) {
const result = run(...args);
assert.equal(result.status, 0, result.stderr);
const generated = parse(
fs.readFileSync(path.join(config, 'generated/devcontainer.json'), 'utf8'),
);
assert.deepEqual(generated.features, parse(source).features);
if (args.includes('--image')) assert.equal(generated.image, args.at(-1));
}
});
test('native workspace preserves edits, rejects a different origin and resumes interrupted fetches', (t) => {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-native-profile-'));
t.after(() => fs.rmSync(root, { recursive: true, force: true }));
const origin = path.join(root, 'origin');
fs.mkdirSync(origin);
const git = (...args) => execFileSync('git', args, { cwd: origin, stdio: 'pipe' });
git('init', '-b', 'main');
git('config', 'user.name', 'Profile test');
git('config', 'user.email', 'profile@example.invalid');
git('config', 'commit.gpgsign', 'false');
git('config', 'core.hooksPath', '/dev/null');
fs.writeFileSync(path.join(origin, 'file'), 'source');
git('add', 'file');
git('commit', '-m', 'fixture');
const checkout = path.join(root, 'checkout');
fs.mkdirSync(path.join(checkout, 'node_modules'), { recursive: true });
const bin = path.join(root, 'bin');
fs.mkdirSync(bin);
const ownershipLog = path.join(root, 'ownership.json');
fs.writeFileSync(
path.join(bin, 'sudo'),
`#!${process.execPath}\nrequire('node:fs').writeFileSync(${JSON.stringify(ownershipLog)}, JSON.stringify(process.argv.slice(2)));\n`,
{ mode: 0o755 },
);
const result = spawnSync(
process.execPath,
[path.join(__dirname, 'bootstrap-native.cjs'), checkout],
{
encoding: 'utf8',
env: {
...process.env,
PATH: `${bin}:${process.env.PATH}`,
GITNEXUS_CLONE_URL: origin,
GITNEXUS_CLONE_REF: 'main',
},
},
);
assert.equal(result.status, 0, result.stderr);
const ownership = JSON.parse(fs.readFileSync(ownershipLog, 'utf8'));
assert.deepEqual(ownership.slice(0, 4), ['-n', 'find', checkout, '-xdev']);
assert.ok(ownership.includes('-h'));
const checkoutGit = (...args) =>
execFileSync('git', args, { cwd: checkout, encoding: 'utf8' }).trim();
assert.equal(checkoutGit('rev-parse', '--abbrev-ref', '@{upstream}'), 'origin/main');
assert.match(checkoutGit('pull'), /Already up to date/);
fs.writeFileSync(path.join(checkout, 'file'), 'local edits');
bootstrap(checkout, origin, 'main');
assert.equal(fs.readFileSync(path.join(checkout, 'file'), 'utf8'), 'local edits');
assert.throws(() => bootstrap(checkout, path.join(root, 'other'), 'main'), /another origin/);
const retry = path.join(root, 'retry');
assert.throws(() => bootstrap(retry, origin, 'new-branch'));
git('branch', 'new-branch');
bootstrap(retry, origin, 'new-branch');
assert.equal(fs.readFileSync(path.join(retry, 'file'), 'utf8'), 'source');
assert.equal(
execFileSync('git', ['rev-parse', '--abbrev-ref', '@{upstream}'], {
cwd: retry,
encoding: 'utf8',
}).trim(),
'origin/new-branch',
);
const conflict = path.join(root, 'conflict');
fs.mkdirSync(conflict);
fs.writeFileSync(path.join(conflict, 'file'), 'pre-existing user file');
assert.throws(() => bootstrap(conflict, origin, 'main'));
assert.equal(fs.readFileSync(path.join(conflict, 'file'), 'utf8'), 'pre-existing user file');
const ignored = path.join(root, 'ignored-conflict');
fs.mkdirSync(ignored);
execFileSync('git', ['init', '-q'], { cwd: ignored });
fs.writeFileSync(path.join(ignored, '.git/info/exclude'), 'file\n');
fs.writeFileSync(path.join(ignored, 'file'), 'ignored user file');
assert.throws(() => bootstrap(ignored, origin, 'main'));
assert.equal(fs.readFileSync(path.join(ignored, 'file'), 'utf8'), 'ignored user file');
// Preserve the user's file elsewhere, then verify the same checkout can resume.
fs.renameSync(path.join(ignored, 'file'), path.join(ignored, 'saved-user-file'));
bootstrap(ignored, origin, 'main');
assert.equal(fs.readFileSync(path.join(ignored, 'file'), 'utf8'), 'source');
assert.equal(fs.readFileSync(path.join(ignored, 'saved-user-file'), 'utf8'), 'ignored user file');
});

View file

@ -0,0 +1,33 @@
'use strict';
const fs = require('node:fs');
const os = require('node:os');
function read(file) {
try {
return fs.readFileSync(file, 'utf8').trim();
} catch {
return 'unavailable';
}
}
function workerBudget({
memory = os.totalmem(),
parallelism = os.availableParallelism(),
memoryMax = read('/sys/fs/cgroup/memory.max'),
cpuMax = read('/sys/fs/cgroup/cpu.max'),
override = process.env.GITNEXUS_DEV_TEST_WORKERS,
} = {}) {
if (override !== undefined && override !== '') {
if (!/^[1-9][0-9]?$/.test(override))
throw new Error('GITNEXUS_DEV_TEST_WORKERS must be an integer from 1 to 99');
return Number(override);
}
if (/^[0-9]+$/.test(memoryMax)) memory = Math.min(memory, Number(memoryMax));
const [quota, period] = cpuMax.split(' ').map(Number);
if (Number.isFinite(quota) && quota > 0 && period > 0)
parallelism = Math.min(parallelism, Math.max(1, Math.floor(quota / period)));
// Leave room for the editor/API and native allocations outside Node's heap.
return Math.max(1, Math.min(4, parallelism - 1, Math.floor(memory / 2 ** 30) - 1));
}
module.exports = { read, workerBudget };

View file

@ -0,0 +1,25 @@
'use strict';
const test = require('node:test');
const assert = require('node:assert/strict');
const { workerBudget } = require('./resources.cjs');
test('worker budget respects CPU quota, memory allowance and interactive headroom', () => {
const limits = {
memory: 32 * 2 ** 30,
parallelism: 32,
override: '',
memoryMax: 'max',
cpuMax: 'max 100000',
};
assert.equal(workerBudget(limits), 4);
assert.equal(workerBudget({ ...limits, cpuMax: '200000 100000' }), 1);
assert.equal(workerBudget({ ...limits, memoryMax: String(3 * 2 ** 30) }), 2);
assert.equal(workerBudget({ ...limits, memoryMax: '100000000', cpuMax: '50000 100000' }), 1);
assert.equal(workerBudget({ ...limits, memoryMax: 'unavailable', cpuMax: 'unavailable' }), 4);
});
test('worker override is explicit and validated', () => {
assert.equal(workerBudget({ override: '2' }), 2);
for (const override of ['0', '-1', 'abc', '1;bad', '100'])
assert.throws(() => workerBudget({ override }), /integer/);
});

View file

@ -0,0 +1,25 @@
#!/usr/bin/env bash
# Restore the image's standalone Codex package into its mounted config volume.
# Optional paths allow migration tests to use isolated temporary directories.
set -euo pipefail
seed=${1:-/home/node/.local/share/codex-standalone}
standalone=${2:-/home/node/.codex/packages/standalone}
command=${3:-/home/node/.local/bin/codex}
if [ -x "$command" ] && "$command" --version >/dev/null 2>&1; then
exit 0
fi
echo "[post-create] restoring standalone Codex into its config volume"
test -d "$seed/releases"
test -L "$seed/current"
mkdir -p "$standalone/releases"
# Copy only packages; credentials, sessions and user configuration stay intact.
# Publish `current` after copying so an interrupted copy can be retried.
cp -r "$seed/releases/." "$standalone/releases/"
if [ -f "$seed/auto-update-version" ]; then
cp "$seed/auto-update-version" "$standalone/auto-update-version"
fi
ln -sfn "$(readlink "$seed/current")" "$standalone/current"
"$command" --version

View file

@ -0,0 +1,88 @@
'use strict';
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { spawnSync } = require('node:child_process');
function fixture(t) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-codex-seed-'));
t.after(() => fs.rmSync(root, { recursive: true, force: true }));
const seed = path.join(root, 'image-seed');
const config = path.join(root, 'config-volume');
const standalone = path.join(config, 'packages/standalone');
const command = path.join(root, 'codex');
const release = 'image-release';
const bin = path.join(seed, 'releases', release, 'bin/codex');
fs.mkdirSync(path.dirname(bin), { recursive: true });
fs.writeFileSync(bin, '#!/bin/sh\necho codex-image\n', { mode: 0o755 });
fs.writeFileSync(path.join(seed, 'auto-update-version'), release);
// Match the official installer's absolute symlinks, including the launcher
// that becomes dangling when Docker mounts an existing config volume.
fs.symlinkSync(path.join(standalone, 'releases', release), path.join(seed, 'current'));
fs.symlinkSync(path.join(standalone, 'current/bin/codex'), command);
const run = () =>
spawnSync('bash', [path.join(__dirname, 'seed-codex.sh'), seed, standalone, command], {
encoding: 'utf8',
});
return { root, seed, config, standalone, command, bin, run };
}
test('restores native Codex into an empty mounted config volume', (t) => {
const f = fixture(t);
const result = f.run();
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /codex-image/);
assert.equal(fs.statSync(f.command).mode & 0o111, 0o111);
assert.equal(
fs.readFileSync(path.join(f.standalone, 'auto-update-version'), 'utf8'),
'image-release',
);
});
test('migrates a reused config volume without changing its state', (t) => {
const f = fixture(t);
fs.mkdirSync(path.join(f.config, 'sessions'), { recursive: true });
for (const file of ['auth.json', 'config.toml', 'sessions/rollout.jsonl'])
fs.writeFileSync(path.join(f.config, file), `fixture-${file}`);
const result = f.run();
assert.equal(result.status, 0, result.stderr);
for (const file of ['auth.json', 'config.toml', 'sessions/rollout.jsonl'])
assert.equal(fs.readFileSync(path.join(f.config, file), 'utf8'), `fixture-${file}`);
});
test('keeps a working container-managed release without reading the image seed', (t) => {
const f = fixture(t);
assert.equal(f.run().status, 0);
const custom = path.join(f.standalone, 'releases/custom/bin');
fs.mkdirSync(custom, { recursive: true });
fs.writeFileSync(path.join(custom, 'codex'), '#!/bin/sh\necho codex-custom\n', { mode: 0o755 });
fs.unlinkSync(path.join(f.standalone, 'current'));
fs.symlinkSync(path.dirname(custom), path.join(f.standalone, 'current'));
fs.rmSync(f.seed, { recursive: true });
const result = f.run();
assert.equal(result.status, 0, result.stderr);
assert.equal(fs.readlinkSync(path.join(f.standalone, 'current')), path.dirname(custom));
assert.equal(result.stdout, '');
});
test('repairs an installed release that fails its version check', (t) => {
const f = fixture(t);
assert.equal(f.run().status, 0);
fs.writeFileSync(path.join(f.standalone, 'current/bin/codex'), '#!/bin/sh\nexit 1\n');
const result = f.run();
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /codex-image/);
});
test('fails for an incomplete seed and succeeds after it is repaired', (t) => {
const f = fixture(t);
fs.unlinkSync(f.bin);
assert.notEqual(f.run().status, 0);
fs.writeFileSync(f.bin, '#!/bin/sh\necho codex-image\n', { mode: 0o755 });
const result = f.run();
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /codex-image/);
});

64
.devcontainer/tune-9p.sh Normal file
View file

@ -0,0 +1,64 @@
#!/usr/bin/env bash
# Best-effort 9p remount, enabled by default. Requires SYS_ADMIN; failures never
# block startup. A successful mount command does not prove msize changed.
set -u
if [ "${WORKSPACE_9P_TUNE:-1}" != "1" ]; then
exit 0
fi
TARGET_MSIZE="${WORKSPACE_9P_MSIZE:-1048576}"
MOUNTPOINT="${1:-/workspace}"
if ! [[ "$TARGET_MSIZE" =~ ^[1-9][0-9]{0,9}$ ]] || (( TARGET_MSIZE > 2147483647 )); then
echo "[tune-9p] invalid WORKSPACE_9P_MSIZE; use an integer from 1 to 2147483647"
exit 0
fi
if ! command -v findmnt >/dev/null 2>&1; then
echo "[tune-9p] findmnt unavailable; skipping"
exit 0
fi
# Match the mountpoint itself, not the containing filesystem for an arbitrary
# directory. This avoids attempting a remount of the container root.
fstype=$(findmnt -rn --first-only --mountpoint "$MOUNTPOINT" -o FSTYPE 2>/dev/null || true)
if [ "$fstype" != "9p" ]; then
echo "[tune-9p] ${MOUNTPOINT} is ${fstype:-unknown}, not 9p; nothing to do"
exit 0
fi
if ! opts=$(findmnt -rn --first-only --mountpoint "$MOUNTPOINT" -o OPTIONS 2>/dev/null); then
echo "[tune-9p] cannot read mount options; skipping"
exit 0
fi
current=""
if [[ ",$opts," =~ ,msize=([1-9][0-9]{0,9}), ]]; then
current="${BASH_REMATCH[1]}"
fi
echo "[tune-9p] ${MOUNTPOINT} 9p msize=${current:-unknown} (target ${TARGET_MSIZE})"
if [ -n "$current" ] && (( current >= TARGET_MSIZE )); then
echo "[tune-9p] already at or above target"
exit 0
fi
if ! command -v sudo >/dev/null 2>&1 || ! command -v timeout >/dev/null 2>&1; then
echo "[tune-9p] sudo or timeout unavailable; skipping"
exit 0
fi
if ! timeout --kill-after=1s 5s sudo -n mount -o "remount,msize=${TARGET_MSIZE}" "$MOUNTPOINT"; then
echo "[tune-9p] remount failed or timed out; SYS_ADMIN may be missing, or the kernel/server rejected it"
echo "[tune-9p] rebuild the devcontainer to apply its capAdd: [SYS_ADMIN] setting"
exit 0
fi
newopts=$(findmnt -rn --first-only --mountpoint "$MOUNTPOINT" -o OPTIONS 2>/dev/null || true)
new=""
if [[ ",$newopts," =~ ,msize=([1-9][0-9]{0,9}), ]]; then
new="${BASH_REMATCH[1]}"
fi
echo "[tune-9p] after remount msize=${new:-unknown}"
if [ -n "$new" ] && (( new >= TARGET_MSIZE )); then
echo "[tune-9p] verified at or above target"
else
echo "[tune-9p] remount returned success but no increase to the target was verified; the kernel or server may ignore or limit msize"
fi
exit 0

View file

@ -0,0 +1,163 @@
'use strict';
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { spawnSync } = require('node:child_process');
function fixture(t, overrides = {}) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-tune-9p-'));
t.after(() => fs.rmSync(root, { recursive: true, force: true }));
const log = path.join(root, 'mount-args');
fs.writeFileSync(
path.join(root, 'findmnt'),
`#!/bin/bash
printf '%s\\n' "$@" >> "$TUNE_TEST_ROOT/findmnt-args"
[ "$MOCK_FINDMNT_FAIL" = 0 ] || exit 1
case "$*" in
*FSTYPE) printf '%s\\n' "$MOCK_FSTYPE" ;;
*OPTIONS)
[ "$MOCK_OPTIONS_FAIL" = 0 ] || exit 1
if [ -f "$TUNE_TEST_ROOT/remounted" ]; then
printf '%s\\n' "$MOCK_AFTER_OPTIONS"
else
printf '%s\\n' "$MOCK_OPTIONS"
fi ;;
esac
`,
{ mode: 0o755 },
);
// Never execute mount: record argv and simulate its result, even if tests
// happen to run with SYS_ADMIN on a developer's machine.
fs.writeFileSync(
path.join(root, 'sudo'),
`#!/bin/bash
printf '%s\\n' "$@" > "$TUNE_TEST_ROOT/mount-args"
if [ "$MOCK_HANG" = 1 ]; then sleep 30; fi
[ "$MOCK_REMOUNT_EXIT" = 0 ] || exit "$MOCK_REMOUNT_EXIT"
touch "$TUNE_TEST_ROOT/remounted"
`,
{ mode: 0o755 },
);
const env = {
...process.env,
PATH: `${root}:${process.env.PATH}`,
TUNE_TEST_ROOT: root,
WORKSPACE_9P_TUNE: '1',
WORKSPACE_9P_MSIZE: '1048576',
MOCK_FSTYPE: '9p',
MOCK_OPTIONS: 'rw,relatime,msize=65536,trans=virtio',
MOCK_AFTER_OPTIONS: 'rw,msize=1048576,trans=virtio',
MOCK_REMOUNT_EXIT: '0',
MOCK_FINDMNT_FAIL: '0',
MOCK_OPTIONS_FAIL: '0',
MOCK_HANG: '0',
...overrides,
};
const run = (...args) => {
const result = spawnSync('/bin/bash', [path.join(__dirname, 'tune-9p.sh'), ...args], {
env,
encoding: 'utf8',
timeout: 10000,
});
assert.equal(result.error, undefined, String(result.error));
assert.equal(result.status, 0, result.stderr);
return result.stdout;
};
return { root, log, run };
}
test('tuning is enabled when WORKSPACE_9P_TUNE is unset', (t) => {
const f = fixture(t, { WORKSPACE_9P_TUNE: undefined });
assert.match(f.run(), /verified at or above target/);
assert.ok(fs.existsSync(f.log));
});
test('disabled tuning does not inspect or remount anything', (t) => {
const f = fixture(t, { WORKSPACE_9P_TUNE: '0' });
assert.equal(f.run(), '');
assert.equal(fs.existsSync(path.join(f.root, 'findmnt-args')), false);
assert.equal(fs.existsSync(f.log), false);
});
for (const fstype of ['ext4', 'virtiofs', 'overlay']) {
test(`skips a ${fstype} workspace without remounting`, (t) => {
const f = fixture(t, { MOCK_FSTYPE: fstype });
assert.match(f.run(), /not 9p/);
assert.equal(fs.existsSync(f.log), false);
});
}
test('failed mount lookup does not block startup or remount a containing filesystem', (t) => {
const f = fixture(t, { MOCK_FINDMNT_FAIL: '1' });
assert.match(f.run('/workspace/subdirectory'), /unknown/);
assert.equal(fs.existsSync(f.log), false);
const args = fs.readFileSync(path.join(f.root, 'findmnt-args'), 'utf8');
assert.match(args, /--mountpoint\n\/workspace\/subdirectory\n/);
});
for (const msize of ['1048576', '2097152']) {
test(`keeps an existing msize of ${msize}`, (t) => {
const f = fixture(t, { MOCK_OPTIONS: `rw,msize=${msize}` });
assert.match(f.run(), /already at or above target/);
assert.equal(fs.existsSync(f.log), false);
});
}
test('uses non-interactive sudo, honors custom size/path and verifies the result', (t) => {
const f = fixture(t, {
WORKSPACE_9P_MSIZE: '2097152',
MOCK_AFTER_OPTIONS: 'rw,msize=2097152',
});
assert.match(f.run('/workspace/project with spaces'), /verified at or above target/);
assert.deepEqual(fs.readFileSync(f.log, 'utf8').trimEnd().split('\n'), [
'-n',
'mount',
'-o',
'remount,msize=2097152',
'/workspace/project with spaces',
]);
});
test('a denied remount is non-fatal and explains capability/recreation requirements', (t) => {
const f = fixture(t, { MOCK_REMOUNT_EXIT: '1' });
const output = f.run();
assert.match(output, /remount failed/);
assert.match(output, /SYS_ADMIN/);
assert.match(output, /rebuild the devcontainer/);
});
test('successful remount with unchanged msize does not claim a verified increase', (t) => {
const f = fixture(t, { MOCK_AFTER_OPTIONS: 'rw,msize=65536' });
const output = f.run();
assert.match(output, /no increase to the target was verified/);
assert.doesNotMatch(output, /verified at or above target/);
});
test('unreadable mount options skip remounting', (t) => {
const f = fixture(t, { MOCK_OPTIONS_FAIL: '1' });
assert.match(f.run(), /cannot read mount options/);
assert.equal(fs.existsSync(f.log), false);
});
test('missing msize is reported as unknown without breaking startup', (t) => {
const f = fixture(t, { MOCK_OPTIONS: 'rw', MOCK_AFTER_OPTIONS: 'rw' });
assert.match(f.run(), /after remount msize=unknown/);
});
for (const msize of ['0', '-1', 'abc', '1;exit 1', '999999999999999999999999']) {
test(`invalid msize ${JSON.stringify(msize)} is non-fatal and never reaches mount`, (t) => {
const f = fixture(t, { WORKSPACE_9P_MSIZE: msize });
assert.match(f.run(), /invalid WORKSPACE_9P_MSIZE/);
assert.equal(fs.existsSync(f.log), false);
});
}
test('a hanging remount times out without blocking startup', (t) => {
const f = fixture(t, { MOCK_HANG: '1' });
const start = Date.now();
assert.match(f.run(), /remount failed or timed out/);
assert.ok(Date.now() - start < 9000, 'remount should be bounded by timeout');
});

View file

@ -0,0 +1,63 @@
'use strict';
const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');
const { randomUUID } = require('node:crypto');
const { execFileSync } = require('node:child_process');
function verifyGitHooks(root = process.cwd()) {
root = path.resolve(root);
if (process.env.HUSKY === '0') throw new Error('HUSKY=0 disables pre-commit hooks.');
const hooksPath = execFileSync('git', ['config', '--get', 'core.hooksPath'], {
cwd: root,
encoding: 'utf8',
stdio: ['ignore', 'pipe', 'pipe'],
}).trim();
if (path.resolve(root, hooksPath) !== path.join(root, '.husky', '_')) {
throw new Error('core.hooksPath must point to .husky/_.');
}
for (const [file, mode] of [
['.husky/pre-commit', fs.constants.R_OK],
['.husky/_/h', fs.constants.R_OK],
['.husky/_/pre-commit', fs.constants.R_OK | fs.constants.X_OK],
]) {
const target = path.join(root, file);
if (!fs.statSync(target).isFile()) throw new Error(`${file} must be a file.`);
fs.accessSync(target, mode);
}
// Exercise the installed Husky helper, including its init.sh, against a
// temporary sentinel hook. Never run the real pre-commit or touch the index.
const probe = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-hook-probe-'));
try {
const token = randomUUID();
fs.mkdirSync(path.join(probe, '_'));
fs.writeFileSync(path.join(probe, 'pre-commit'), `printf '%s\\n' '${token}'\n`);
const output = execFileSync(
'sh',
['-c', '. "$1"', path.join(probe, '_/pre-commit'), path.join(root, '.husky/_/h')],
{ cwd: root, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'] },
);
if (!output.includes(token)) {
throw new Error('Husky startup configuration disables or skips pre-commit hooks.');
}
} finally {
fs.rmSync(probe, { recursive: true, force: true });
}
}
module.exports = { verifyGitHooks };
if (require.main === module) {
try {
verifyGitHooks();
console.log('[install-deps] Husky pre-commit hook is installed and enabled');
} catch (error) {
console.error(`[install-deps] Husky verification failed: ${error.message}`);
console.error('Run npm run prepare at the repository root and keep HUSKY enabled.');
process.exitCode = 1;
}
}

View file

@ -0,0 +1,158 @@
'use strict';
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { execFileSync, spawnSync } = require('node:child_process');
const verifier = path.join(__dirname, 'verify-git-hooks.cjs');
const husky = path.resolve(__dirname, '../node_modules/husky/bin.js');
function fixture(t, install = true) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-husky-'));
t.after(() => fs.rmSync(root, { recursive: true, force: true }));
const globalConfig = path.join(root, 'global-gitconfig');
fs.writeFileSync(globalConfig, '');
const env = {
...process.env,
HUSKY: '',
GIT_CONFIG_GLOBAL: globalConfig,
GIT_CONFIG_NOSYSTEM: '1',
GIT_CONFIG_COUNT: '0',
XDG_CONFIG_HOME: path.join(root, 'xdg'),
};
for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'])
delete env[key];
const options = { cwd: root, env, encoding: 'utf8' };
const git = (...args) => execFileSync('git', args, options);
git('init', '-q');
git('config', 'user.name', 'Husky test');
git('config', 'user.email', 'husky-test@example.invalid');
fs.mkdirSync(path.join(root, '.husky'));
fs.copyFileSync(
path.resolve(__dirname, '../.husky/pre-commit'),
path.join(root, '.husky/pre-commit'),
);
if (install) execFileSync(process.execPath, [husky], options);
const verify = (overrides = {}) =>
spawnSync(process.execPath, [verifier], { ...options, env: { ...env, ...overrides } });
const commit = () => spawnSync('git', ['commit', '--allow-empty', '-m', 'hook test'], options);
const tool = (file, status) => {
const target = path.join(root, file);
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, `#!/bin/sh\nprintf called > "$0.called"\nexit ${status}\n`, {
mode: 0o755,
});
return `${target}.called`;
};
return { root, git, verify, commit, tool };
}
test('Husky verification accepts a real installation', (t) => {
const repo = fixture(t);
const result = repo.verify();
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /installed and enabled/);
});
test('Husky verification rejects missing Git hook configuration', (t) => {
const repo = fixture(t, false);
assert.equal(repo.verify().status, 1);
});
test('Husky verification rejects a cleared cache without removing the tracked hook', (t) => {
const repo = fixture(t);
fs.rmSync(path.join(repo.root, '.husky/_'), { recursive: true });
assert.equal(repo.verify().status, 1);
assert.ok(fs.existsSync(path.join(repo.root, '.husky/pre-commit')));
});
test('Husky verification rejects hooks redirected elsewhere', (t) => {
const repo = fixture(t);
repo.git('config', 'core.hooksPath', 'other-hooks');
assert.equal(repo.verify().status, 1);
});
test('Husky verification rejects a missing tracked pre-commit script', (t) => {
const repo = fixture(t);
fs.rmSync(path.join(repo.root, '.husky/pre-commit'));
assert.equal(repo.verify().status, 1);
});
test('Husky verification rejects a non-executable Git hook', (t) => {
const repo = fixture(t);
fs.chmodSync(path.join(repo.root, '.husky/_/pre-commit'), 0o644);
assert.equal(repo.verify().status, 1);
});
test('Husky verification rejects an explicitly disabled hook', (t) => {
const repo = fixture(t);
const result = repo.verify({ HUSKY: '0' });
assert.equal(result.status, 1);
assert.match(result.stderr, /HUSKY=0 disables/);
});
for (const init of ['export HUSKY=0\n', 'exit 0\n']) {
test(`Husky verification rejects startup configuration ${init.trim()}`, (t) => {
const repo = fixture(t);
const marker = repo.tool('node_modules/.bin/lint-staged', 1);
fs.mkdirSync(path.join(repo.root, 'xdg/husky'), { recursive: true });
fs.writeFileSync(path.join(repo.root, 'xdg/husky/init.sh'), init);
const result = repo.verify();
assert.equal(result.status, 1);
assert.match(result.stderr, /startup configuration disables or skips/);
// Demonstrate why the verifier must fail: real Git would skip the formatter.
assert.equal(repo.commit().status, 0);
assert.equal(fs.existsSync(marker), false);
});
}
test('Husky probe accepts enabled startup configuration without running the tracked hook', (t) => {
const repo = fixture(t);
const marker = repo.tool('node_modules/.bin/lint-staged', 1);
fs.mkdirSync(path.join(repo.root, 'xdg/husky'), { recursive: true });
fs.writeFileSync(path.join(repo.root, 'xdg/husky/init.sh'), 'export HUSKY=1\nprintf startup\n');
assert.equal(repo.verify().status, 0);
assert.equal(fs.existsSync(marker), false);
assert.equal(repo.commit().status, 1);
assert.equal(fs.existsSync(marker), true);
});
test('Git rejects a commit when the actual pre-commit formatter fails', (t) => {
const repo = fixture(t);
const marker = repo.tool('node_modules/.bin/lint-staged', 1);
assert.equal(repo.verify().status, 0);
const result = repo.commit();
assert.equal(result.status, 1, result.stderr);
assert.match(result.stdout + result.stderr, /pre-commit: formatting staged files/);
assert.equal(fs.readFileSync(marker, 'utf8'), 'called');
assert.throws(() => repo.git('rev-parse', '--verify', 'HEAD'));
});
for (const pkg of ['gitnexus', 'gitnexus-web']) {
test(`Git rejects a commit when the actual ${pkg} pre-commit typecheck fails`, (t) => {
const repo = fixture(t);
repo.tool('node_modules/.bin/lint-staged', 0);
const marker = repo.tool(`${pkg}/node_modules/.bin/tsc`, 1);
fs.writeFileSync(path.join(repo.root, pkg, 'change.ts'), 'export const value = 1;\n');
repo.git('add', `${pkg}/change.ts`);
assert.equal(repo.verify().status, 0);
const result = repo.commit();
assert.equal(result.status, 1, result.stderr);
assert.match(result.stdout + result.stderr, new RegExp(`pre-commit: typechecking ${pkg}`));
assert.equal(fs.readFileSync(marker, 'utf8'), 'called');
assert.throws(() => repo.git('rev-parse', '--verify', 'HEAD'));
});
}
test('Git accepts a commit when the actual pre-commit checks pass', (t) => {
const repo = fixture(t);
repo.tool('node_modules/.bin/lint-staged', 0);
assert.equal(repo.verify().status, 0);
const result = repo.commit();
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout + result.stderr, /pre-commit: all checks passed/);
assert.ok(repo.git('rev-parse', '--verify', 'HEAD').trim());
});

View file

@ -14,6 +14,12 @@ WEB_CONTAINER_NAME=gitnexus-web
SERVER_HOST_PORT=4747
WEB_HOST_PORT=4173
# Where the browser reaches the API. Unset: http://localhost:4747. An absolute
# URL for a server on another host; `/` behind a reverse proxy that serves the
# API on the same origin as the UI (see README, "Same-origin API behind a
# reverse proxy").
# GITNEXUS_BACKEND_URL=/
# Optional read-only mount, exposed to the server as /workspace.
# Override with the directory that contains the repos you want to index.
WORKSPACE_DIR=./

View file

@ -369,7 +369,7 @@ jobs:
- name: Upload fork PR meta
if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true && steps.decide.outputs.any == 'true'
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: pr-meta
path: ${{ runner.temp }}/pr-meta/metadata.json
@ -395,7 +395,7 @@ jobs:
with:
persist-credentials: false # this job uploads artifacts (artipacked)
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
@ -523,7 +523,7 @@ jobs:
'
- name: Upload prebuild artifact
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: ts-prebuild-${{ matrix.grammar }}-${{ matrix.platform_arch }}
path: ${{ steps.build.outputs.stage }}/${{ matrix.name }}.node
@ -556,7 +556,7 @@ jobs:
steps:
- name: Mint GitHub App token
id: app-token
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
app-id: ${{ secrets.RELEASE_APP_ID }}
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
@ -571,7 +571,7 @@ jobs:
persist-credentials: false
- name: Download all prebuild artifacts
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
path: ${{ runner.temp }}/dl
pattern: ts-prebuild-*

View file

@ -1,10 +1,9 @@
name: Devcontainer Smoke
# Smoke-tests .devcontainer/ whenever it changes. Two things happen here.
# First, unit tests run on the pure host->container config transforms: the
# plugin-registry path translation, and the strip of the machine field from
# $HOME/.claude.json. Second, the devcontainer image is built through the
# standard @devcontainers/cli path. That CLI reads build.args from
# First, unit tests cover host->container config transforms and actual Husky
# pre-commit enforcement in temporary repositories. Second, the image is built
# through the standard @devcontainers/cli path. That CLI reads build.args from
# devcontainer.json, so the version pin there stays the single source of truth.
on:
push:
@ -12,10 +11,12 @@ on:
paths:
- '.devcontainer/**'
- '.github/workflows/ci-devcontainer.yml'
- 'gitnexus-web/package-lock.json'
pull_request:
paths:
- '.devcontainer/**'
- '.github/workflows/ci-devcontainer.yml'
- 'gitnexus-web/package-lock.json'
permissions:
contents: read
@ -39,20 +40,31 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
- name: Unit-test the host->container config transforms
run: node --test .devcontainer/translate-plugin-registries.test.cjs
# Hook tests install real Husky in temporary repositories.
- name: Install hook test tooling
run: |
npm ci --no-audit --no-fund
node .devcontainer/verify-git-hooks.cjs
- name: Unit-test devcontainer setup and hooks
run: node --test .devcontainer/*.test.cjs
- name: Syntax-check the lifecycle shell scripts
run: |
bash -n .devcontainer/install-deps.sh
bash -n .devcontainer/post-create.sh
bash -n .devcontainer/seed-codex.sh
bash -n .devcontainer/tune-9p.sh
build:
name: Build devcontainer image
name: Build devcontainer image (${{ matrix.profile }})
runs-on: ubuntu-latest
timeout-minutes: 30
timeout-minutes: 45
strategy:
fail-fast: false
matrix:
profile: [default, ui]
steps:
# persist-credentials: false — this is a read-only build smoke that
# never pushes. The setting keeps GITHUB_TOKEN out of .git/config,
@ -60,24 +72,22 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
- name: Generate UI profile
if: matrix.profile == 'ui'
run: node .devcontainer/profile.cjs ui
# Builds the image the same way a developer's "Reopen in Container" does.
# @devcontainers/cli reads devcontainer.json (jsonc format), resolves
# build.args (the CLAUDE_CODE_VERSION / CODEX_VERSION pins), and runs the
# Dockerfile. This smoke catches Dockerfile regressions and any drift from
# the canonical version pins. The lifecycle hooks (post-create.sh) do not
# build.args (including BUN_VERSION), and runs the Dockerfile. This smoke
# catches Dockerfile regressions, including native CLI installation.
# The lifecycle hooks (post-create.sh) do not
# run here. They need the host config mounts, and CI has none.
#
# ARCH COVERAGE: this runs on an x64 runner with no --platform or QEMU, so
# it builds only the amd64 Cursor branch (CURSOR_SHA256_X64). The arm64
# branch (CURSOR_SHA256_ARM64 plus the arm64 tarball URL) is pinned by a
# sha256 checked against the published artifact, but it is not BUILT here.
# Cursor's extract-and-symlink step does not depend on the architecture, so
# the only remaining gap is a stale arm64 URL or hash. If that becomes a
# concern, add a linux/arm64 matrix leg (docker/setup-qemu-action plus
# `--platform`).
# it builds only amd64. Native CLI installers also support arm64, but that
# path is not built here. Add QEMU and a linux/arm64 matrix leg if needed.
#
# The @devcontainers/cli version is pinned on purpose. A bare
# `npx --yes @devcontainers/cli` would resolve @latest at run time. A
@ -109,10 +119,12 @@ jobs:
echo "::warning::failed to pre-pull ${img} after 3 attempts; continuing — build step may still succeed"
exit 1
- name: Build devcontainer via @devcontainers/cli
env:
DEVCONTAINER_CONFIG: ${{ matrix.profile == 'ui' && '.devcontainer/generated/devcontainer.json' || '.devcontainer/devcontainer.json' }}
run: |
set -euo pipefail
for attempt in 1 2; do
if npx --yes @devcontainers/cli@0.87.0 build --workspace-folder .; then
if npx --yes @devcontainers/cli@0.87.0 build --workspace-folder . --config "$DEVCONTAINER_CONFIG" --frozen-lockfile; then
if [ "$attempt" -eq 2 ]; then
echo "::notice::devcontainer build retry succeeded (attempt 2); investigate if this recurs across runs."
fi

View file

@ -92,7 +92,7 @@ jobs:
- name: Upload test results
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: e2e-results
path: |

View file

@ -16,7 +16,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
cache: npm
@ -31,7 +31,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
cache: npm

View file

@ -29,7 +29,7 @@ jobs:
fi
- name: Upload release accuracy evidence
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: release-tool-accuracy
path: |
@ -108,7 +108,7 @@ jobs:
working-directory: gitnexus
- name: Upload coverage blob
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: coverage-blob-${{ matrix.shard }}
path: gitnexus/.vitest/blob/
@ -138,7 +138,7 @@ jobs:
with:
build: 'true'
- name: Download coverage blobs
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
with:
pattern: coverage-blob-*
path: gitnexus/.vitest/blob
@ -171,7 +171,7 @@ jobs:
run: node --test docker-server.test.mjs
- name: Upload test reports
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: coverage-reports
path: |
@ -195,8 +195,13 @@ jobs:
steps:
- id: gen
run: |
TOTAL=8 # cross-platform (windows/macOS) shards per OS
COV_TOTAL=4 # ubuntu coverage shards (merged before thresholds)
# Refreshed Windows timings leave eight shards too close to the
# 20-minute watchdog. Ten preserve headroom for runner variation.
TOTAL=10 # cross-platform (windows/macOS) shards per OS
# Four coverage shards exceeded the 25-minute job limit while tests
# were still passing. Split the full suite further; keep the timeout
# and merged coverage thresholds unchanged.
COV_TOTAL=8 # ubuntu coverage shards (merged before thresholds)
if [ "$TOTAL" -lt 1 ] || [ "$COV_TOTAL" -lt 1 ]; then
echo "shard totals must be >= 1" >&2; exit 1
fi
@ -292,7 +297,7 @@ jobs:
working-directory: gitnexus
- name: Upload platform execution report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: execution-${{ matrix.os }}-${{ matrix.shard }}
path: gitnexus/${{ matrix.os }}-${{ matrix.shard }}.json
@ -375,12 +380,13 @@ jobs:
# (#836) plus native grammar loading from the bundled runtime. Runs on windows-latest because that is the platform the fix
# targets; the in-repo `npm ci` job above only exercises the dev-tree path
# and skips the tarball reify step where the historical EPERM occurred.
# Native Linux ARM64 also verifies the corrected bundled prebuilds (#3599).
packaged-install-smoke:
name: packaged install smoke (${{ matrix.os }})
strategy:
fail-fast: false
matrix:
os: [windows-latest, ubuntu-latest]
os: [windows-latest, ubuntu-latest, ubuntu-24.04-arm]
runs-on: ${{ matrix.os }}
# Windows pack + web install regularly exceeds 15 minutes when setup also
# runs prepare/postinstall/build before prepack compiles the same tree again.
@ -399,6 +405,18 @@ jobs:
with:
lifecycle-scripts: 'false'
# Reproduce #3599's runtime after the shared action selects Node 22.x.
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
if: matrix.os == 'ubuntu-24.04-arm'
with:
node-version: '22.23.1'
package-manager-cache: false
- name: Assert native ARM64 runtime
if: matrix.os == 'ubuntu-24.04-arm'
shell: bash
run: |
node -e "const assert = require('node:assert/strict'); assert.equal(process.platform, 'linux'); assert.equal(process.arch, 'arm64'); assert.equal(process.version, 'v22.23.1'); console.log(process.platform, process.arch, process.version)"
# `npm pack` runs prepack, which builds the web UI into gitnexus/web/
# so the tarball matches what `npm publish` ships. Install those deps
# here, in their own visible step, rather than letting build.js do it
@ -413,6 +431,43 @@ jobs:
run: npm pack
working-directory: gitnexus
# Block native compilation only in the consumer phase. A correct bundle
# must install using prebuilds even when the runner has a toolchain.
- name: Reject ARM64 consumer compilation
if: matrix.os == 'ubuntu-24.04-arm'
shell: bash
run: |
set -euo pipefail
TOOLS="$RUNNER_TEMP/gitnexus-no-compile"
mkdir -p "$TOOLS"
export GITNEXUS_COMPILER_SENTINEL_LOG="$RUNNER_TEMP/gitnexus-compile-attempts.log"
cat > "$TOOLS/cc" <<'EOF'
#!/usr/bin/env bash
echo "Unexpected native compilation: $0 $*" >&2
printf '%s\n' "$0 $*" >> "${GITNEXUS_COMPILER_SENTINEL_LOG:?}"
exit 97
EOF
chmod +x "$TOOLS/cc"
for tool in c++ gcc g++ clang clang++ make gmake; do
cp "$TOOLS/cc" "$TOOLS/$tool"
done
# Prove the guard fails before relying on it, then clear its probe.
if "$TOOLS/cc" --version; then
echo 'Compiler sentinel unexpectedly succeeded' >&2
exit 1
else
test "$?" -eq 97
fi
test -s "$GITNEXUS_COMPILER_SENTINEL_LOG"
: > "$GITNEXUS_COMPILER_SENTINEL_LOG"
echo "$TOOLS" >> "$GITHUB_PATH"
{
echo "GITNEXUS_COMPILER_SENTINEL_LOG=$GITNEXUS_COMPILER_SENTINEL_LOG"
echo "CC=$TOOLS/cc"
echo "CXX=$TOOLS/c++"
echo "MAKE=$TOOLS/make"
} >> "$GITHUB_ENV"
# Global installs do not exercise npm's bundled-dependency lockfile path
# (#3563). Keep npm 10 here: newer npm can mask unresolved override refs.
- name: Lock and install tarball in a fresh consumer project
@ -457,6 +512,23 @@ jobs:
echo "PREFIX=$PREFIX" >> "$GITHUB_ENV"
working-directory: gitnexus
# npm can ignore failed optional-dependency scripts, so also inspect the
# sentinel log after both installs rather than trusting exit status alone.
- name: Assert no consumer compilation attempts
if: always() && matrix.os == 'ubuntu-24.04-arm'
shell: bash
run: |
set -euo pipefail
if [ -z "${GITNEXUS_COMPILER_SENTINEL_LOG:-}" ] || [ ! -f "$GITNEXUS_COMPILER_SENTINEL_LOG" ]; then
echo 'Compiler sentinel was not initialized' >&2
exit 1
fi
if [ -s "$GITNEXUS_COMPILER_SENTINEL_LOG" ]; then
echo 'Unexpected native compilation during consumer installation:' >&2
cat "$GITNEXUS_COMPILER_SENTINEL_LOG" >&2
exit 1
fi
- name: Assert no junctions or vendor build artifacts
shell: bash
run: |
@ -538,7 +610,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22'
cache: npm
@ -553,7 +625,7 @@ jobs:
# Switch to the engines-floor Node AFTER building — native deps built on
# 22.x load across the whole 22.x ABI line, and nothing installs after this
# (so no package-manager cache is needed).
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22.18.0'
package-manager-cache: false
@ -576,6 +648,24 @@ jobs:
done
working-directory: gitnexus
# Native embedding replacement measures real COPY, writes and cold reopens.
# Keep it outside the 25-minute language benchmark job: four trials at each
# size take several minutes even on the development baseline machine.
embedding-identity-benchmark:
name: embedding identity persistence benchmark
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: ./.github/actions/setup-gitnexus
with:
build: 'true'
- name: Embedding identity persistence / scaling guards (#3569)
run: node --import tsx bench/embedding-identities/measure.cjs --check
working-directory: gitnexus
# ── Dedicated benchmark gate ─────────────────────────────────────
# The cross-language `*-pipeline-benchmark.test.ts` suites are gated behind
# GITNEXUS_BENCH (they generate synthetic codebases at scale), so the main
@ -654,6 +744,11 @@ jobs:
run: node --import tsx bench/rename/measure.mjs --check
working-directory: gitnexus
- name: Generated embedding input budget / scaling guards (#3607)
if: ${{ !cancelled() }}
run: node --import tsx bench/embedding-inputs/measure.cjs --check
working-directory: gitnexus
- name: Callable-value-flow target-index guards (#2693)
if: ${{ !cancelled() }}
# Build-free: asserts buildGraphTargetIndex resolves an unchanged target
@ -738,7 +833,7 @@ jobs:
if: ${{ !cancelled() }}
# Build-free: same baseline approach as parse-dispatch-rounds —
# exact declared/SDK/undeclared floors plus a fingerprint, then
# ratio timing only (resolveSwiftImportTarget, swiftPackageStrategy,
# ratio timing only (resolveSwiftImportTarget,
# parseSwiftPackageManifest 4n/n). Pins declaration-only resolve,
# https:// factory survival, and #2931 segment-boundary membership.
# See bench/swift-package-imports/measure.mjs.
@ -961,6 +1056,18 @@ jobs:
run: node --expose-gc --import tsx bench/cfg/measure.mjs --check
working-directory: gitnexus
- name: Inline handler capture / visibility guards (#3489)
if: ${{ !cancelled() }}
# Build-free: pins inline/returned definitions and private-name refusals,
# then guards capture and fallback-cache scaling.
run: node --import tsx bench/inline-taint/measure.cjs --check
working-directory: gitnexus
- name: Staged publication durability / scaling guards (#3591)
if: ${{ !cancelled() }}
run: node --import tsx bench/staged-publication/measure.cjs --check
working-directory: gitnexus
- name: Emit-persistence throughput / byte-identity guards (#2203)
if: ${{ !cancelled() }}
# Build-free: asserts streamAllCSVsToDisk output is byte-identical
@ -981,6 +1088,11 @@ jobs:
run: node --import tsx bench/emit-persistence/measure-streaming.mjs --check
working-directory: gitnexus
- name: Directory symlink coverage / scaling guards (#3608)
if: ${{ !cancelled() }}
run: node --import tsx bench/symlink-coverage/measure.cjs --check
working-directory: gitnexus
- name: Cross-language pipeline benchmarks (GITNEXUS_BENCH, serial)
if: ${{ !cancelled() }}
env:
@ -989,7 +1101,7 @@ jobs:
working-directory: gitnexus
- name: Upload benchmark execution report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: execution-benchmarks
path: gitnexus/benchmarks.json
@ -1007,7 +1119,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
version: '0.11.23'
python-version: '3.13'
@ -1017,7 +1129,7 @@ jobs:
working-directory: eval
- name: Upload pytest execution report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: execution-pytest-locked
path: eval/pytest-locked.xml
@ -1034,7 +1146,7 @@ jobs:
working-directory: gitnexus
- name: Upload preflight execution report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: execution-preflight
path: gitnexus/preflight.json
@ -1062,12 +1174,12 @@ jobs:
persist-credentials: false
- uses: ./.github/actions/setup-gitnexus
- name: Download coverage and web reports
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
with:
name: coverage-reports
- name: Download all execution receipts
if: ${{ !cancelled() }}
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
with:
pattern: execution-*
path: execution-reports
@ -1084,7 +1196,7 @@ jobs:
run: python3 eval/check_test_execution.py execution-reports eval/pytest-results.json
- name: Upload complete test reports
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: test-reports
path: |
@ -1116,14 +1228,14 @@ jobs:
persist-credentials: false
# Oracle controls replay the immutable historical task sources.
fetch-depth: 0
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22.18.0'
cache: npm
cache-dependency-path: |
gitnexus/package-lock.json
gitnexus-shared/package-lock.json
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
version: '0.11.23'
python-version: '3.13'
@ -1195,7 +1307,7 @@ jobs:
working-directory: eval
- name: Upload pytest execution report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: execution-pytest-ubuntu
path: eval/pytest-ubuntu.xml
@ -1212,7 +1324,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
version: '0.11.23'
python-version: '3.13'
@ -1226,7 +1338,7 @@ jobs:
working-directory: eval
- name: Upload pytest execution report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: execution-pytest-windows
path: eval/pytest-windows.xml

View file

@ -85,7 +85,7 @@ jobs:
cp pr-meta/e2e_result pr-meta/e2e-result
- name: Upload PR metadata
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: pr-meta
path: pr-meta/

View file

@ -48,7 +48,7 @@ jobs:
persist-credentials: false
- name: Initialize CodeQL
uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
uses: github/codeql-action/init@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
languages: ${{ matrix.language }}
queries: security-and-quality
@ -91,6 +91,6 @@ jobs:
- '.github/scripts/fetch-lbug-fts-artifacts.mjs'
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
uses: github/codeql-action/analyze@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
category: '/language:${{ matrix.language }}'

View file

@ -58,7 +58,7 @@ jobs:
steps:
# Pinned to v8.0.1 (same SHA used across this repo's workflows).
- name: Download prebuild artifacts
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
continue-on-error: true
with:
run-id: ${{ github.event.workflow_run.id }}
@ -67,7 +67,7 @@ jobs:
path: prebuilds-in
- name: Download PR meta
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
continue-on-error: true
with:
name: pr-meta

View file

@ -0,0 +1,75 @@
name: Publish Development Images
on:
push:
branches: [main]
paths:
- '.devcontainer/**'
- 'gitnexus-web/package-lock.json'
- '.github/workflows/devcontainer-publish.yml'
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
publish:
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
timeout-minutes: 60
permissions:
contents: read
packages: write
strategy:
fail-fast: false
matrix:
profile: [core, ui]
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
- name: Verify development tooling before publishing
run: |
npm ci --no-audit --no-fund
node --test .devcontainer/*.test.cjs
- uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
- uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
- uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Generate toolchain-only configuration
env:
PROFILE: ${{ matrix.profile }}
run: |
if [ "$PROFILE" = ui ]; then
node .devcontainer/profile.cjs image-build --ui
else
node .devcontainer/profile.cjs image-build
fi
- name: Build both architectures, cache and publish
env:
PROFILE: ${{ matrix.profile }}
run: |
set -euo pipefail
image="ghcr.io/${GITHUB_REPOSITORY,,}-devcontainer"
suffix=""
if [ "$PROFILE" = ui ]; then suffix="-ui"; fi
tag="${image}:sha-${GITHUB_SHA}-run-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}${suffix}"
cache="${image}:buildcache-${PROFILE}"
npx --yes @devcontainers/cli@0.87.0 build \
--workspace-folder . --config .devcontainer/generated/devcontainer.json \
--frozen-lockfile --platform linux/amd64,linux/arm64 \
--image-name "$tag" --push true \
--label "org.opencontainers.image.source=https://github.com/${GITHUB_REPOSITORY}" \
--cache-from "$cache" --cache-to "type=registry,ref=${cache},mode=max"
docker buildx imagetools create --tag "${image}:main${suffix}" "$tag"
echo "Published ${tag}" >> "$GITHUB_STEP_SUMMARY"

View file

@ -361,7 +361,7 @@ jobs:
- name: Set up pinned Node.js
id: setup-node
if: steps.context.outputs.ready == 'true'
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22.18.0'
@ -1294,7 +1294,7 @@ jobs:
steps.claude-recheck.outcome == 'success'
# Use the low-level base action: the high-level GitHub action can restore
# project configuration from a moving base branch before invoking Claude.
uses: anthropics/claude-code-action/base-action@cab360f6565aa35a51d6ce9e43f1f4287c0a32ea # v1
uses: anthropics/claude-code-action/base-action@374f254f5efaf968abfe15d399fd90972e8138b9 # v1
env:
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: '1'
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '0'
@ -1447,7 +1447,7 @@ jobs:
if: >-
steps.precheck.outputs.repair_reason != '' &&
steps.repair-recheck.outcome == 'success'
uses: anthropics/claude-code-action/base-action@cab360f6565aa35a51d6ce9e43f1f4287c0a32ea # v1
uses: anthropics/claude-code-action/base-action@374f254f5efaf968abfe15d399fd90972e8138b9 # v1
env:
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: '1'
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '0'
@ -2353,7 +2353,7 @@ jobs:
- name: Upload bounded review artifact
id: upload
if: always() && steps.context.outputs.authorized == 'true' && steps.context.outputs.pr_number != ''
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: ${{ steps.artifact.outputs.name }}
path: ${{ runner.temp }}/gitnexus-review-artifact/review.json
@ -2398,7 +2398,7 @@ jobs:
needs.analyze.outputs.authorized == 'true' &&
needs.analyze.outputs.pr_number != ''
continue-on-error: true
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: ${{ needs.analyze.outputs.artifact_name }}
path: ${{ runner.temp }}/gitnexus-review-publish

View file

@ -402,7 +402,7 @@ jobs:
persist-credentials: false
fetch-depth: 0
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22.18.0'
cache: npm
@ -410,7 +410,7 @@ jobs:
gitnexus/package-lock.json
gitnexus-shared/package-lock.json
- uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
version: '0.11.23'
python-version: '3.13'
@ -647,7 +647,7 @@ jobs:
# goes, so a killed or failed generation still has evidence worth
# keeping — and that is exactly the run whose evidence is needed.
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: gitnexus-evolution-${{ github.run_id }}-${{ github.run_attempt }}
# Addressed directly rather than carried from the sweep step: that is
@ -701,7 +701,7 @@ jobs:
- name: Mint GitHub App token
id: app-token
if: steps.promotion.outputs.promoted == 'true'
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
# `client-id` supersedes the deprecated `app-id` in v3.x (the action
# accepts the numeric App ID here, as publish.yml does). Request only

View file

@ -48,7 +48,7 @@ jobs:
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
@ -62,7 +62,7 @@ jobs:
- name: Mint GitHub App token
id: app-token
if: steps.relapp.outputs.configured == 'true'
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
with:
app-id: ${{ secrets.RELEASE_APP_ID }}
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}

View file

@ -64,7 +64,7 @@ jobs:
- name: Upload mutation report
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: impact-pdg-mutation-report
path: gitnexus/mutation-report.json

View file

@ -315,7 +315,7 @@ jobs:
# expired) from "patch file zero bytes" (genuinely empty patch).
- name: Download autofix artifact
if: steps.locate.outputs.found == 'true'
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
continue-on-error: true
with:
name: autofix

View file

@ -56,7 +56,7 @@ jobs:
# Pinned to v8.0.1. Verify SHA via:
# gh api repos/actions/download-artifact/git/refs/tags/v8.0.1
- name: Download autofix artifact
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: autofix
run-id: ${{ github.event.workflow_run.id }}

View file

@ -59,7 +59,7 @@ jobs:
repository: ${{ github.event.pull_request.head.repo.full_name }}
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: 22
cache: npm
@ -138,7 +138,7 @@ jobs:
# Pinned to v7.0.1. Verify SHA via:
# gh api repos/actions/upload-artifact/git/refs/tags/v7.0.1
- name: Upload autofix artifact
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: autofix
path: autofix-out/

View file

@ -0,0 +1,66 @@
name: PR cost evaluation request
on:
pull_request_target:
types: [labeled]
branches: [main]
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
cancel-in-progress: false
permissions: {}
jobs:
request:
if: >-
github.repository == 'abhigyanpatwari/GitNexus' &&
github.event.label.name == 'run-cost-evaluation' &&
github.run_attempt == 1
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
pull-requests: read
actions: read
outputs:
pr: ${{ steps.request.outputs.pr }}
sha: ${{ steps.request.outputs.sha }}
comparison_run_id: ${{ steps.request.outputs.comparison_run_id }}
run_attempt: ${{ steps.request.outputs.run_attempt }}
steps:
# pull_request_target uses trusted base code; never check out the PR here.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.sha }}
persist-credentials: false
- name: Request one pinned comparison from trusted main
id: request
working-directory: eval
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
python3 -m workflow_bench.pr_evaluation dispatch-label \
--repo "$GITHUB_REPOSITORY" --event "$GITHUB_EVENT_PATH" >> "$GITHUB_OUTPUT"
echo "run_attempt=$GITHUB_RUN_ATTEMPT" >> "$GITHUB_OUTPUT"
evaluate:
needs: [request]
if: needs.request.outputs.run_attempt == github.run_attempt
permissions:
contents: read
pull-requests: read
actions: write
id-token: write
uses: ./.github/workflows/release-evaluation.yml
# Named forwarding also binds the callee's environment-only secrets.
secrets:
GITNEXUS_EVOLUTION_AWS_ROLE_ARN: ${{ secrets.GITNEXUS_EVOLUTION_AWS_ROLE_ARN }}
GITNEXUS_EVOLUTION_EC2_INSTANCE_ID: ${{ secrets.GITNEXUS_EVOLUTION_EC2_INSTANCE_ID }}
GITNEXUS_BENCH_OPENAI_API_KEY: ${{ secrets.GITNEXUS_BENCH_OPENAI_API_KEY }}
GITNEXUS_BENCH_ANTHROPIC_API_KEY: ${{ secrets.GITNEXUS_BENCH_ANTHROPIC_API_KEY }}
with:
candidate_pr: ${{ needs.request.outputs.pr }}
expected_pr_sha: ${{ needs.request.outputs.sha }}
comparison_run_id: ${{ needs.request.outputs.comparison_run_id }}

View file

@ -108,7 +108,7 @@ jobs:
# Pinned to v7.2.0. Verify SHA via:
# gh api repos/release-drafter/release-drafter/git/refs/tags/v7.2.0
# v7 removed `disable-releaser`; use `dry-run: true` to only autolabel.
- uses: release-drafter/release-drafter@72967cdc98ddd3160f1fc3dff619de365e137dd0 # v7.9.0
- uses: release-drafter/release-drafter@978bb0b30c5ee8cdd332ced253758157150d43f0 # v7.10.0
with:
config-name: release-drafter.yml
dry-run: true

View file

@ -315,7 +315,7 @@ jobs:
- 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
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.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
@ -370,7 +370,7 @@ jobs:
exit 1
fi
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
# Node 24 ships with npm >= 11.5.x, which is the minimum that
# supports npm Trusted Publishing OIDC. Node 22 ships with npm
@ -541,20 +541,29 @@ jobs:
fi
fi
# 4. Counter: 1 + max existing N for `${BASE}-rc.*`, else 1.
# 4. Counter: reserve versions present in either npm or Git.
# npm can accept a publish while its metadata still omits that
# version ("Your package is being processed"). Checkout fetched
# all tags, including detached release commits, so those tags
# keep the next run from allocating an already-used version.
GIT_RC_TAGS="$(git tag --list "v${BASE}-rc.*")"
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
const tagged = process.env.GIT_RC_TAGS.split("\n")
.filter(Boolean).map(tag => tag.slice(1));
const ns = [...v, ...tagged]
.filter(s => typeof s === "string" && s.startsWith(prefix))
.map(s => parseInt(s.slice(prefix.length), 10))
.map(s => s.slice(prefix.length))
.filter(s => /^\d+$/.test(s))
.map(Number)
.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)"
NEXT_N="$(BASE="$BASE" VERSIONS_JSON="$VERSIONS_JSON" GIT_RC_TAGS="$GIT_RC_TAGS" node /tmp/next_rc.mjs)"
RC_VERSION="${BASE}-rc.${NEXT_N}"
echo "Computed rc: $RC_VERSION"
@ -618,7 +627,7 @@ jobs:
# Every release carries this run's fixed-answer accuracy. Paid paired
# agent runs gate only stable releases; RCs are measured on a schedule.
- name: Download this release's tool accuracy
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
with:
name: release-tool-accuracy
path: ${{ runner.temp }}/release-evidence

View file

@ -30,6 +30,34 @@ on:
type: choice
default: xhigh
options: [low, medium, high, xhigh, max]
# PR preview inputs are available only to the maintainer-authorized label
# workflow. Manual dispatch cannot select an unmerged PR runtime.
workflow_call:
secrets:
GITNEXUS_EVOLUTION_AWS_ROLE_ARN:
required: true
GITNEXUS_EVOLUTION_EC2_INSTANCE_ID:
required: true
GITNEXUS_BENCH_OPENAI_API_KEY:
required: true
GITNEXUS_BENCH_ANTHROPIC_API_KEY:
required: false
inputs:
candidate_pr:
type: string
required: true
expected_pr_sha:
type: string
required: true
comparison_run_id:
type: string
required: true
model:
type: string
default: gpt-5.6-sol
effort:
type: string
default: xhigh
concurrency:
group: gitnexus-evolution-runner
@ -44,6 +72,7 @@ jobs:
github.repository == 'abhigyanpatwari/GitNexus' &&
github.ref == 'refs/heads/main' &&
(github.event_name == 'workflow_dispatch' ||
(github.event_name == 'pull_request_target' && inputs.candidate_pr != '') ||
(vars.GITNEXUS_EVOLUTION_ENABLED == 'true' && vars.GITNEXUS_EVOLUTION_WORKERS == '3'))
runs-on: ubuntu-latest
environment: gitnexus-evolution
@ -75,6 +104,7 @@ jobs:
github.repository == 'abhigyanpatwari/GitNexus' &&
github.ref == 'refs/heads/main' &&
(github.event_name == 'workflow_dispatch' ||
(github.event_name == 'pull_request_target' && inputs.candidate_pr != '') ||
(vars.GITNEXUS_EVOLUTION_ENABLED == 'true' && vars.GITNEXUS_EVOLUTION_WORKERS == '3'))
runs-on: ubuntu-latest
environment: gitnexus-evolution
@ -106,6 +136,7 @@ jobs:
github.repository == 'abhigyanpatwari/GitNexus' &&
github.ref == 'refs/heads/main' &&
(github.event_name == 'workflow_dispatch' ||
(github.event_name == 'pull_request_target' && inputs.candidate_pr != '') ||
(vars.GITNEXUS_EVOLUTION_ENABLED == 'true' && vars.GITNEXUS_EVOLUTION_WORKERS == '3'))
# Partial reruns reuse successful startup outputs after cleanup stopped EC2.
runs-on: ${{ fromJSON(needs.start-runner.outputs.run_attempt == github.run_attempt && '["self-hosted", "linux", "x64", "gitnexus-evolution"]' || '["ubuntu-latest"]') }}
@ -158,6 +189,7 @@ jobs:
github.ref == 'refs/heads/main' &&
inputs.runner_only != true &&
(github.event_name == 'workflow_dispatch' ||
(github.event_name == 'pull_request_target' && inputs.candidate_pr != '') ||
(vars.GITNEXUS_EVOLUTION_ENABLED == 'true' && vars.GITNEXUS_EVOLUTION_WORKERS == '3'))
runs-on: ${{ fromJSON(needs.start-runner.outputs.run_attempt == github.run_attempt && '["self-hosted", "linux", "x64", "gitnexus-evolution"]' || '["ubuntu-latest"]') }}
# Reuse the main-only protected model-secret environment. No tag/fork code
@ -166,8 +198,13 @@ jobs:
timeout-minutes: 1260
permissions:
contents: read
actions: read # Authenticate and download the explicitly selected historical measurement.
pull-requests: read
env:
INPUT_REF: ${{ inputs.candidate_ref || 'latest-rc' }}
INPUT_PR: ${{ inputs.candidate_pr }}
INPUT_PR_SHA: ${{ inputs.expected_pr_sha }}
COMPARISON_RUN_ID: ${{ inputs.comparison_run_id }}
MODEL: ${{ inputs.model || 'gpt-5.6-sol' }}
EFFORT: ${{ inputs.effort || 'xhigh' }}
steps:
@ -184,10 +221,18 @@ jobs:
fetch-depth: 0
- name: Resolve immutable runtime revision
id: resolve
working-directory: eval
env:
GH_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
if [[ -n "$INPUT_PR" ]]; then
[[ "$COMPARISON_RUN_ID" =~ ^[1-9][0-9]*$ ]] || { echo '::error::PR preview requires comparison_run_id.'; exit 1; }
python3 -m workflow_bench.pr_evaluation resolve \
--repo "$GITHUB_REPOSITORY" --pr "$INPUT_PR" --sha "$INPUT_PR_SHA" >> "$GITHUB_OUTPUT"
exit 0
fi
[[ -z "$INPUT_PR_SHA" && -z "$COMPARISON_RUN_ID" ]] || { echo '::error::PR preview inputs require candidate_pr.'; exit 1; }
# Resolve last stable once; both runtimes use the same trusted tasks.
stable="$(gh api "repos/$GITHUB_REPOSITORY/releases/latest" --jq '.tag_name')"
[[ "$stable" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo '::error::No stable release found.'; exit 1; }
@ -220,6 +265,7 @@ jobs:
persist-credentials: false
fetch-depth: 0
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
if: inputs.candidate_pr == ''
with:
ref: ${{ steps.resolve.outputs.stable_sha }}
path: stable
@ -229,17 +275,27 @@ jobs:
run: |
rm -rf "$RUNNER_TEMP/release-evaluation"
mkdir -p "$RUNNER_TEMP/release-evaluation/public"
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22.18.0'
cache: npm
cache-dependency-path: candidate/gitnexus/package-lock.json
- uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
version: '0.11.23'
python-version: '3.13'
enable-cache: true
cache-dependency-glob: eval/uv.lock
- name: Authenticate historical PR comparison evidence
if: inputs.candidate_pr != ''
working-directory: eval
env:
GH_TOKEN: ${{ github.token }}
run: |
uv run --locked --extra dev python -m workflow_bench.pr_evaluation baseline \
--repo "$GITHUB_REPOSITORY" --run-id "$COMPARISON_RUN_ID" \
--harness-sha "$GITHUB_SHA" --model "$MODEL" --effort "$EFFORT" \
--out "$RUNNER_TEMP/release-evaluation/previous.json"
# Both runtimes grade the pinned task source against one dependency tree
# built from that commit's lockfile, never the runtime under test's.
- name: Resolve pinned task revision
@ -275,6 +331,7 @@ jobs:
run: |
set -euo pipefail
for checkout in tasks-base stable candidate; do
if [[ -n "$INPUT_PR" && "$checkout" == stable ]]; then continue; fi
uv run --locked --extra dev python -m workflow_bench.release_build \
--repo "$GITHUB_WORKSPACE/$checkout"
done
@ -283,29 +340,48 @@ jobs:
run: |
set -euo pipefail
for runtime in stable candidate; do
if [[ -n "$INPUT_PR" && "$runtime" == stable ]]; then continue; fi
uv run --locked --extra dev python -m workflow_bench.release_report prepare \
--repo "$GITHUB_WORKSPACE/$runtime" --task-repo "$GITHUB_WORKSPACE/tasks-base" \
--out "$RUNNER_TEMP/release-evaluation/$runtime" \
--model "$MODEL" --effort "$EFFORT" --runs 3
done
- name: Require historical task dependencies before paid PR sessions
if: inputs.candidate_pr != ''
working-directory: eval
run: |
uv run --locked --extra dev python -m workflow_bench.pr_evaluation dependencies \
--tasks "$RUNNER_TEMP/release-evaluation/candidate/tasks.yaml" \
--baseline "$RUNNER_TEMP/release-evaluation/previous.json"
- name: Require real containment before paid sessions
working-directory: eval
env:
GITNEXUS_REQUIRE_BWRAP_CANARY: '1'
GITNEXUS_REQUIRE_CLAUDE_CANARY: '1'
CLAUDE_CANARY_BIN: ${{ runner.temp }}/claude-canary/node_modules/@anthropic-ai/claude-code-linux-x64/claude
run: uv run --locked --extra dev python -m pytest tests/test_proposer_sandbox.py -q
run: >-
uv run --locked --extra dev python -m pytest tests/test_proposer_sandbox.py
tests/test_workflow_bench_sessions.py::test_real_cli_background_completion_is_one_complete_measurement -q
- name: Materialize both release graphs before paid sessions
timeout-minutes: 120
working-directory: eval
run: |
set -euo pipefail
for runtime in stable candidate; do
if [[ -n "$INPUT_PR" && "$runtime" == stable ]]; then continue; fi
uv run --locked --extra dev python -m workflow_bench.release_preflight \
--tasks "$RUNNER_TEMP/release-evaluation/$runtime/tasks.yaml" \
--gitnexus-root "$GITHUB_WORKSPACE/$runtime" \
--claude-bin "$RUNNER_TEMP/claude-canary/node_modules/@anthropic-ai/claude-code-linux-x64/claude"
done
- name: Recheck PR opt-in and pinned head immediately before paid sessions
if: inputs.candidate_pr != ''
working-directory: eval
env:
GH_TOKEN: ${{ github.token }}
run: |
python3 -m workflow_bench.pr_evaluation resolve \
--repo "$GITHUB_REPOSITORY" --pr "$INPUT_PR" --sha "$INPUT_PR_SHA"
- name: Run repeated paired agent sessions
timeout-minutes: 1140
working-directory: eval
@ -314,15 +390,18 @@ jobs:
GITNEXUS_BENCH_ANTHROPIC_API_KEY: ${{ secrets.GITNEXUS_BENCH_ANTHROPIC_API_KEY }}
run: |
set -euo pipefail
arms=(baseline_nomcp baseline)
if [[ -n "$INPUT_PR" ]]; then arms=(baseline); fi
for runtime in stable candidate; do
if [[ -n "$INPUT_PR" && "$runtime" == stable ]]; then continue; fi
remaining=$(( ${{ needs.start-runner.outputs.stop_deadline_epoch }} - $(date +%s) - 5400 ))
(( remaining > 0 )) || { echo '::error::No time remains before the stop and evidence reserve.'; exit 1; }
timeout --signal=TERM --kill-after=60 "${remaining}s" \
uv run --locked --extra dev python -m workflow_bench.runner \
--tasks "$RUNNER_TEMP/release-evaluation/$runtime/tasks.yaml" \
--gitnexus-root "$GITHUB_WORKSPACE/$runtime" \
--arms baseline_nomcp baseline --runs 3 --include-expensive \
--workers 3 --timeout 1800 --model "$MODEL" --effort "$EFFORT" \
--arms "${arms[@]}" --runs 3 --include-expensive \
--workers 3 --timeout 3600 --model "$MODEL" --effort "$EFFORT" \
--claude-bin "$RUNNER_TEMP/claude-canary/node_modules/@anthropic-ai/claude-code-linux-x64/claude" \
--out "$RUNNER_TEMP/release-evaluation/$runtime/raw"
done
@ -330,6 +409,15 @@ jobs:
if: ${{ always() && steps.resolve.outputs.sha != '' }}
working-directory: eval
run: |
if [[ -n "$INPUT_PR" ]]; then
uv run --locked --extra dev python -m workflow_bench.pr_evaluation summarize \
--results "$RUNNER_TEMP/release-evaluation/candidate/raw/results.jsonl" \
--metadata "$RUNNER_TEMP/release-evaluation/candidate/metadata.json" \
--baseline "$RUNNER_TEMP/release-evaluation/previous.json" \
--sha '${{ steps.resolve.outputs.sha }}' --pr "$INPUT_PR" --run-id "$COMPARISON_RUN_ID" \
--out "$RUNNER_TEMP/release-evaluation/public"
exit 0
fi
failed=0
for runtime in stable candidate; do
if [[ -f "$RUNNER_TEMP/release-evaluation/$runtime/metadata.json" ]]; then
@ -344,7 +432,7 @@ jobs:
done
exit "$failed"
- name: Require complete paired evidence and no task regression
if: ${{ always() && steps.resolve.outputs.sha != '' }}
if: ${{ always() && steps.resolve.outputs.sha != '' && inputs.candidate_pr == '' }}
working-directory: eval
run: |
uv run --locked --extra dev python -m workflow_bench.release_gate \
@ -359,6 +447,10 @@ jobs:
set -euo pipefail
public="$RUNNER_TEMP/release-evaluation/public"
mkdir -p "$public"
if [[ -n "$INPUT_PR" ]]; then
if [[ -f "$public/pr-cost-comparison.md" ]]; then cat "$public/pr-cost-comparison.md" >> "$GITHUB_STEP_SUMMARY"; fi
exit 0
fi
for extension in json md; do
candidate="$RUNNER_TEMP/release-evaluation/candidate/public/agent-evaluation.$extension"
stable="$RUNNER_TEMP/release-evaluation/stable/public/agent-evaluation.$extension"
@ -369,8 +461,8 @@ jobs:
if [[ -f "$public/$report.md" ]]; then cat "$public/$report.md" >> "$GITHUB_STEP_SUMMARY"; fi
done
- name: Upload sanitized release evidence
if: ${{ always() && steps.resolve.outputs.sha != '' }}
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
if: ${{ always() && steps.resolve.outputs.sha != '' && inputs.candidate_pr == '' }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: release-agent-evaluation-${{ steps.resolve.outputs.sha }}
path: |
@ -382,6 +474,16 @@ jobs:
${{ runner.temp }}/release-evaluation/public/release-quality-gate.md
if-no-files-found: error
retention-days: 30
- name: Upload sanitized PR cost comparison
if: ${{ always() && steps.resolve.outputs.sha != '' && inputs.candidate_pr != '' }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: pr-cost-comparison-${{ steps.resolve.outputs.sha }}
path: |
${{ runner.temp }}/release-evaluation/public/pr-cost-comparison.json
${{ runner.temp }}/release-evaluation/public/pr-cost-comparison.md
if-no-files-found: error
retention-days: 30
stop-runner:
name: Stop and verify the dedicated EC2 runner

View file

@ -38,7 +38,7 @@ jobs:
persist-credentials: false
- name: Run Scorecard
uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
with:
results_file: results.sarif
results_format: sarif
@ -46,13 +46,13 @@ jobs:
publish_results: true
- name: Upload artifact
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: SARIF file
path: results.sarif
retention-days: 5
- name: Upload to Security tab
uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
sarif_file: results.sarif

View file

@ -50,7 +50,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '22'
cache: npm

View file

@ -76,7 +76,7 @@ jobs:
exit-code: '0'
- name: Upload to Security tab
uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
sarif_file: trivy-${{ matrix.image.name }}.sarif
category: trivy-${{ matrix.image.name }}

View file

@ -76,7 +76,7 @@ jobs:
continue-on-error: true
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
with:
sarif_file: zizmor.sarif
category: zizmor

10
.github/zizmor.yml vendored
View file

@ -51,6 +51,16 @@ rules:
# context) holds no write permissions. Header comment documents.
- pr-labeler.yml
# pull_request_target is required for a label request on fork PRs to
# call the protected evaluator on main. This hosted handler checks
# out only github.sha (the trusted base commit), never PR code, and
# verifies the labeling actor's Maintain/Admin role plus the live
# label/head. Its token is read-only. The evaluator job calls trusted
# reusable workflow code under the existing main-only protected
# environment; no PR source is executed by this request handler.
# Tests lock down base checkout, maintainer gate and changed-head denial.
- pr-cost-evaluation.yml
# Note: cache-poisoning is NOT exempted. The two prior findings in
# publish.yml and the former release-candidate.yml were fixed structurally
# by dropping `cache: npm` from those workflows (matches the pattern used

1
.gitignore vendored
View file

@ -87,6 +87,7 @@ gitnexus/test/fixtures/lang-resolution/**/bin
GitNexus.sln
# Git worktrees
.worktrees/
.devcontainer/generated/
# Vendored tree-sitter grammar build artifacts (created at install time,
# never committed). See docs/plans/2026-04-15-002-fix-tree-sitter-proto-vendor-deps-plan.md

View file

@ -2,6 +2,8 @@ dist/
coverage/
gitnexus/vendor/
gitnexus/test/fixtures/
# Line/column-sensitive callable identity and taint regression.
gitnexus/test/integration/cfg/fixtures/inline-taint-repo/
gitnexus-web/test/fixtures/
gitnexus-web/playwright-report/
gitnexus-web/test-results/

View file

@ -1,7 +1,7 @@
<!-- version: 1.17.0 -->
<!-- Last updated: 2026-09-24 -->
<!-- version: 1.18.0 -->
<!-- Last updated: 2026-10-17 -->
Last reviewed: 2026-09-24
Last reviewed: 2026-10-17
**Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
@ -92,6 +92,7 @@ mirror. `gitnexus/test/unit/shipped-skills-sync.test.ts` guards the copies. Toke
| Date | Version | Change |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-10-17 | 1.18.0 | Require the reviewed preview's single-use `plan_token` when applying semantic rename (#2973). |
| 2026-09-24 | 1.17.0 | Clones with the same `origin` URL now share a store automatically; `--no-share` records a lasting opt-out (#3352). |
| 2026-09-24 | 1.16.0 | Documented the shared worktree index store (`<GITNEXUS_HOME>/stores/`, `analyze --share-with`, `GITNEXUS_SHARED_STORE=off`) in the storage notes (#3352). |
| 2026-09-07 | 1.15.0 | Added the Objective-C provider guide as the required reference before changing Objective-C parsing or resolution. |
@ -136,7 +137,7 @@ This project is indexed by GitNexus as **GitNexus** (248612 symbols, 565510 rela
- NEVER edit a function, class, or method before MCP/CLI impact analysis.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read `UNKNOWN` as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
- NEVER rename symbols with find-and-replace — use `rename` with `dry_run: true` first, review the graph-backed semantic spans and coverage, then apply with `dry_run: false`.
- NEVER rename symbols with find-and-replace — use `rename` with `dry_run: true` first, review the graph-backed semantic spans and coverage, then apply with `dry_run: false` and that preview's `plan_token`.
- NEVER commit before MCP/CLI graph change analysis.
## Resources

View file

@ -36,7 +36,7 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
| `context` | Callers, callees, processes for one symbol |
| `impact` | Blast radius (upstream/downstream) with risk summary |
| `detect_changes` | Map git diffs to affected symbols and processes |
| `rename` | Semantic rename: previews by default (`dry_run` omitted/true), applies with `dry_run: false` |
| `rename` | Semantic rename: previews by default (`dry_run` omitted/true), applies with `dry_run: false` and the preview's `plan_token` |
| `api_impact` | Pre-change impact report for an API route handler |
| `trace` | Shortest directed path between two symbols (call + class-member edges); group-aware (`repo: "@<group>"`) for cross-repo traces |
| `route_map` | API route → handler → consumer mappings |
@ -69,7 +69,7 @@ Group-mode `trace` (`gitnexus/src/core/group/cross-trace.ts`) stitches a path th
| Embeddings | `src/core/embeddings/` + `src/core/run-analyze.ts` |
| Wiki generation | `src/core/wiki/` |
| Language support | `src/core/ingestion/languages/` + `tree-sitter-queries.ts` + `gitnexus-shared/src/languages.ts` |
| Import resolution | `src/core/ingestion/import-processor.ts` + `import-resolvers/configs/` + `model/resolution-context.ts` |
| Import resolution | `src/core/ingestion/scope-resolution/pipeline/run.ts` + per-language `ScopeResolver.resolveImportTarget` hooks |
| Call resolution/inheritance/MRO | `src/core/ingestion/scope-resolution/` (pipeline, passes, graph-bridge) |
| Type extraction | `src/core/ingestion/type-extractors/` |
| Worker pool | `src/core/ingestion/workers/` |
@ -166,7 +166,7 @@ export const myPhase: PipelinePhase<MyPhaseOutput> = {
### Where routes come from
`route-extractors/` holds four independent ways a route can be discovered, all
`route-extractors/` holds five independent ways a route can be discovered, all
converging on the routes phase's `(method, url)` registry:
| Source | Shape | Examples |
@ -175,8 +175,9 @@ converging on the routes phase's `(method, url)` registry:
| Single-file framework route | `isRouteFile` + worker extraction | Laravel `routes/*.php` |
| Cross-file framework route | `discoverRootRouteFiles` + `extractRoutes` | Django `urlpatterns` |
| AST-level route in a normal file | `extractDecoratorRoutes` | Spring, FastAPI, NestJS (`@Controller` + `@Get`/`@Post`/…; URLs are controller-relative — `setGlobalPrefix` and URI versioning live in the bootstrap file and are not applied), **JS/TS dispatch guards and static data route tables** |
| Cross-file AST route facts | `extractRouteFacts` + `resolveRouteFacts` | Express apps/routers and their mount paths; directly proven Hono registrations |
The last row is the one whose name undersells it. A route is DECLARED by a
The AST-level route hook is the one whose name undersells it. A route is DECLARED by a
decorator, but it can also be **inferred** from a raw `node:http` server's own
dispatch — `if (req.method === 'GET' && pathname === '/api/x')` is a route with
a path, a verb and a handler, and nothing else in the pipeline could see it.
@ -198,6 +199,51 @@ That extractor is deliberately **precision-weighted**: `route_map` presents its
output as fact, so a `startsWith` namespace test, a bare `pathname === '/'`
without a verb, and any regex it cannot translate exactly are all dropped rather
than guessed at. A missing route is a coverage limit; an invented one is a lie.
Express `app.get(RegExp, handler)` registrations are likewise omitted: a regex
matcher does not have one finite URL to use as a Route node key.
Express `app.use(path, middleware)` does not itself create a Route node. When
both receivers are proven Express instances, mounting a router joins the literal
prefix to its registered paths before handler selection. Nested and repeated
mounts, literal path arrays, and middleware arrays share this composition.
Express receiver facts reuse the existing AST and `ParsedFile` lexical identities.
They follow explicit ESM/CommonJS imports and exports through the configured
`ScopeResolver`, including stable aliases and barrels. An object named `app` or
`router` is not evidence; type-only imports, shadowed bindings, conflicting writes,
and unproven factories do not establish a receiver. Directly proven Hono verb
registrations remain supported, without applying Express mounting semantics.
A registration whose receiver, literal path or mounted router is a parameter of a
named function (`mountSSEProgress(app, '/p', jobs)` → `app.get(routePath, …)`)
resolves through each call site of that function, once per site and in the
helper's file. This is one hop only: a site argument that is itself a parameter,
an unproven argument, or a reassigned parameter establishes nothing, and a helper
with no recorded call site is read as written, so an unknown mount path still
suppresses its router's standalone paths.
Fetch-wrapper facts use the same lexical identities. The shared resolver in
`route-extractors/fetch-wrapper-index.ts` names no language, but it applies
ECMAScript `ResolveExport` rules to the re-export facts it receives: only
providers whose modules link that way implement the re-export hook. A file that
passes a route's URL to a callee not proven to be a wrapper is counted on the
Route as `unverifiedConsumers` (proven consumers and the route's own file
excluded), and `api_impact` then reports its consumer count as a lower bound.
An inline Express handler resolves to the anonymous Function node the capture
layer names by position, so its Route carries a `handlerSymbolId`. In a file
with several routes, response keys come from that handler's lines rather than
the whole file (middleware stays file-level), and flows link only where they
start at that handler.
A standalone router retains its local paths. A known dynamic mount suppresses
that fallback, while independently proven static mounts remain available. Cycles
terminate, and exceeding the expansion budget omits the affected mount component
rather than publishing a partial set of paths. Per-file facts are cached, but
cross-file paths are recomputed each run. Group HTTP contracts use the same
resolver and composition, including in source-only mode.
Dispatch-guard inference also ignores stored `route.routePath` metadata:
comparing a recorded route name with a literal does not prove that the request
path is being dispatched.
Two rules there need more than one comparison to decide, and are worth knowing
about before changing either:
@ -219,36 +265,94 @@ about before changing either:
## Semantic model
`SemanticModel` (`gitnexus/src/core/ingestion/model/semantic-model.ts`) is the authoritative store for every symbol-indexed lookup (by `nodeId`, `simpleName`, `qualifiedName`, or `filePath`). The scope-resolution pipeline reads from here: `findOwnedMember`, `pickOverload`, and `findExportedDefByName` all consult `model.methods` / `model.fields` / `model.symbols`.
`SemanticModel` is the active declaration store used by the ingestion pipeline.
Its `symbols`, `types`, `methods` and `fields` registries supply symbol and
owner-oriented lookups. Scope resolution consumes this model; it does not replace
it with a second symbol store.
`ParsedFile` (`gitnexus-shared/src/scope-resolution/parsed-file.ts`) is the single per-file artifact the scope-resolution pipeline consumes. Scope-resolution passes MUST NOT build a parallel parse representation. If a per-language hook needs AST-level facts that `ParsedFile` doesn't expose, it should reuse the orchestrator's `treeCache` (`RunScopeResolutionInput.treeCache`) rather than re-invoking `parser.parse(...)` on its own — the C# `populateNamespaceSiblings` hook is the reference implementation of this pattern.
### Type facts and resolution responsibilities
The scope-resolution pipeline additionally carries `WorkspaceResolutionIndex` for `Scope`-valued lookups (`classScopeByDefId`, `moduleScopeByFile`) that `SemanticModel` structurally cannot hold. No symbol-indexed duplicates exist outside `SemanticModel`.
| Layer | Responsibility |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `LanguageProvider` and parse workers | Extract declarations, type annotations, imports and reference facts using language-owned rules. |
| `TypeEnvironment` (`type-env.ts`) | Collect temporary per-file hints used by extraction and exported-type metadata. |
| `ParsedFile` | Carry declarations, scopes, imports, type bindings and reference sites into workspace resolution. |
| `SemanticModel` | Keep authoritative declaration registries and member ownership. |
| `ScopeResolver` and shared passes | Apply language rules, visibility, type propagation, receiver folding and dispatch to emit graph edges. |
**Write / read phase contract.** The model is mutable during three ordered phases and read-only afterward:
```text
Language providers + parse workers
├── symbol registration ───────► SemanticModel
├── scope/type/reference facts ► ParsedFile
└── TypeEnv hints ─────────────► extraction / exported-type metadata
```
Phase 1: parse ──► symbolTable.add fans into types/methods/fields
Phase 2: scope-resolution ──► reconcileOwnership() registers corrected ownerIds
Phase 3: finalize ──► model.attachScopeIndexes(bundle) — one-shot freeze
─────────────────────────── phase boundary ───────────────────────────
Read phase: all resolution passes + MCP + HTTP + embeddings see
SemanticModel (read-only handle); writes are type-errors.
SemanticModel + ParsedFile + ScopeResolver hooks
└──► finalize scopes/imports → propagate types → resolve → emit graph edges
```
`runScopeResolution` narrows `MutableSemanticModel` → `SemanticModel` at the phase boundary so downstream passes physically cannot mutate the model even accidentally.
Type handling occurs during both extraction and resolution. The worker builds
TypeEnv without a global model or imported-binding inputs. Only file-scope
TypeEnv bindings are serialized into `BindingAccumulator` for exported-type
metadata enrichment; function-local maps are not a second workspace resolver.
The current `crossFile` phase only disposes that accumulator. The legacy
cross-file call re-resolution and call-resolution DAG were removed in #942.
**Reconciliation pass.** `reconcileOwnership` (`scope-resolution/pipeline/reconcile-ownership.ts`) is a shim for languages whose parse-time extractor doesn't resolve `enclosingClassId` at parse time (Python class-body methods are the canonical case). It walks `parsed.localDefs[i].ownerId` after `populateOwners` and registers any missed methods/fields into the model. Idempotent — safe to re-run, safe alongside languages whose extractor already carries `ownerId` (C#).
`ParsedFile` (`gitnexus-shared/src/scope-resolution/parsed-file.ts`) is the per-file
artifact the scope-resolution pipeline consumes. Passes must reuse it rather
than build parallel parse representations. If a provider needs additional AST
facts, it can reuse the orchestrator's `treeCache`; ordinary worker-pool runs
consume serialized facts because native Trees cannot cross MessageChannels.
The architectural end state is for every language's parse-time extractor to emit the correct `ownerId` directly, making reconciliation a no-op (tracked as a follow-up refactor). The dev-mode validator `validateOwnershipParity` surfaces any drift via `onWarn` under `NODE_ENV !== 'production' && VALIDATE_SEMANTIC_MODEL !== '0'`.
`WorkspaceResolutionIndex` supplies derived scope and return-fact lookups, such as
`classScopeByDefId` and `moduleScopeByFile`. These caches complement the model's
authoritative declaration registries.
References: `semantic-model.ts` file-head (full write/read contract); `contract/scope-resolver.ts` Contract Invariant I9 (scope-resolution-side rule).
### Write and read lifecycle
1. Parsing calls `model.symbols.add`, which registers declarations with the
appropriate type, method or field registry.
2. The per-language scope pipeline populates ownership and calls
`reconcileOwnership` to register corrections before reference resolution.
3. The orchestrator narrows the model to the read-only `SemanticModel` interface
for downstream resolution passes. `finalizeScopeModel` returns the scope/index
bundle that the orchestrator consumes directly.
This read-only model handle restricts registry writes. It does not freeze every
scope map: imported-return propagation and precise call-result binding deliberately
refine `Scope.typeBindings` in ordered passes. Graph-query MCP and HTTP endpoints read the
persisted graph/index rather than a live parse-time model handle.
The model also exports optional `scopes` / `attachScopeIndexes` APIs. No production
attachment call is present in the reviewed source, so callers must not assume
`model.scopes` is populated. Similarly, the shared `resolveTypeRef` helper is
exported and unit-tested, while current registry lookup resolves receiver owners
directly. These are API-audit candidates, not reasons to label the whole model or
typing layer obsolete.
`reconcileOwnership` is an active compatibility pass for providers whose parse-time
owner differs from their scope-resolution owner. The dev validator
`validateOwnershipParity` reports drift under
`NODE_ENV !== 'production' && VALIDATE_SEMANTIC_MODEL !== '0'`. Retiring reconciliation
requires provider ownership parity first.
See [Type Resolution System](type-resolution-system.md) for execution details and
[Type Resolution Roadmap](type-resolution-roadmap.md) for planned work and
acceptance criteria.
---
## Scope-Resolution Pipeline (RFC #909 Ring 3)
Language-agnostic scope-resolution resolver. This is the resolution path for every language — it owns CALLS/ACCESSES/USES emission and inheritance edges. Adding a language is one interface implementation (`ScopeResolver`) plus one registration in the `SCOPE_RESOLVERS` map — no changes to shared code, no new pipeline phase. (RING4-1 #942 removed the legacy call-resolution DAG and the per-language `MIGRATED_LANGUAGES` flag, so `SCOPE_RESOLVERS` registration is all that's needed.)
The shared scope-resolution pipeline handles ordinary source-language references
using `ParsedFile`, `SemanticModel` and provider hooks. It emits resolved calls,
accesses, value uses and inheritance edges. Register a `ScopeResolver` in
`SCOPE_RESOLVERS` to participate; the old per-language migration flag and parallel
call-resolution DAG were removed in RING4-1 #942.
A provider can explicitly restrict its edge mode. COBOL currently uses
`callable-flow-only`: its established processor retains structural CALLS/IMPORTS,
and scope resolution contributes procedure-pointer calls. Registration alone is
not a claim that every language feature uses identical resolution rules.
### Pipeline stages
@ -278,7 +382,7 @@ Pipeline phase: `scopeResolutionPhase` in `scope-resolution/pipeline/phase.ts`
### Semantic rename
`rename` plans through the graph-backed planner in `mcp/local/rename/graph-rename.ts`; `dry_run` (omitted or `true`) stops after planning, `dry_run: false` also applies. In MCP read-only mode the same tool is listed preview-only and any other `dry_run` is rejected before backend dispatch (`mcp/read-only-policy.ts`). The selected graph declaration must match the current source. Each language's `LanguageProvider.rename` supplies original-source name spans, spelling rules, declaration families, and syntax-specific rewrites. Embedded and standalone providers retain their own parsing strategy; shared planning does not classify language syntax or invoke compiler/language-service APIs.
`rename` plans through the graph-backed planner in `mcp/local/rename/graph-rename.ts`; `dry_run` (omitted or `true`) stops after planning and returns a single-use `plan_token`. Public apply requires that token with `dry_run: false`, validates the captured repository, declaration inventory, stable symbol identity, source-file set, source hashes and approved physical paths, and executes exactly the captured edits without replanning. The process-local cache retains edited-file snapshots and targets, hash/target evidence for unedited semantic sources, and an immutable provider-resolution configuration value, with a 15-minute lifetime and bounded plan-count and memory budgets. Provider-owned fresh configuration hooks bypass workspace memoization; configuration semantics are checked at capability validation and once after staging, before the first installation, independently of edited-file count. Source bytes and approved targets are checked before each replacement. These cooperative-workspace checks are not an atomic filesystem snapshot. An unedited source aliasing an edited target blocks preview. In MCP read-only mode the same tool is listed preview-only and any other `dry_run` is rejected before backend dispatch (`mcp/read-only-policy.ts`). The selected graph declaration must match the current source. Each language's `LanguageProvider.rename` supplies original-source name spans, spelling rules, declaration families, and syntax-specific rewrites. Embedded and standalone providers retain their own parsing strategy; shared planning does not classify language syntax or invoke compiler/language-service APIs.
The planner runs the existing scope-resolution pipeline before and after the proposed edits. An opt-in source-binding observer records the declaration selected for a written name, separately from runtime dispatch expansion. Provider capture metadata travels with each parsed file, so both passes retain ordinary import and ownership evidence. Provider-proven declaration families use the existing inheritance, implementation, and declaration relationships. Re-resolution checks edited references, untouched bindings, collisions, and changes in those families.
@ -286,7 +390,7 @@ Application validates all captured source snapshots before each per-file replace
### Callable-value flow
First-class callable values use a language-neutral inclusion analysis in `passes/callable-value-flow.ts`. Providers recognize their own syntax and emit JSON-safe `CallableFlowSite` facts (`seed`, `copy`, `alias`, `address`, `load`, `store`, `formal`, `argument`, and `invoke`) into `ParsedFile`; shared ingestion never branches on a language name. These always-on facts cross workers and the durable parse store, whose schema is bumped whenever their semantic shape changes.
First-class callable values use a language-neutral inclusion analysis in `passes/callable-value-flow.ts`. Providers recognize their own syntax and emit JSON-safe `CallableFlowSite` facts (`seed`, `copy`, `alias`, `address`, `load`, `store`, `formal`, `argument`, and `invoke`) into `ParsedFile`; shared ingestion never branches on a language name. These always-on facts cross workers and the durable parse store. Changes to their producers or shared contracts automatically change the base parser identity used by both caches.
The emit stage defers only invocation sites proven to reference a flow cell. Ordinary receiver/free/reference passes still resolve direct callees first and record exact callee IDs by file/line/column. Property dispatch then runs before callable flow because a property-dispatched wrapper call can seed actual-to-formal propagation. The callable solver consumes those direct targets, propagates callable sets through lexical cells and formals, and emits `CALLS` at the real indirect invocation site with reason `callable-value-flow` (confidence 0.8 for a singleton, 0.7 for a bounded multi-target set).
@ -306,7 +410,7 @@ Standalone (regex-based) providers such as COBOL participate via `ScopeResolver.
A compound receiver (`svc.getUser().address.save()`) is captured as a compact string on `ReferenceSite.receiverChain`. `utils/receiver-chain-codec.ts` is the ONE encoder/decoder — capture emitters, the scope-resolution fold, and the durable ParsedFile store all import it rather than hand-rolling the format.
Wire format is **v2**: `2|<base>|<step>|<step>…`, one-character version prefix, then base-first steps, each a one-character kind sigil plus the member name (`c` = call, `f` = field). `a` (await) and `i` (index) are **name-free** and encode as a bare sigil — an awaited call's name already lives on its `c` step, and a subscript key is a value, not a lookup-able identifier. The version went 1 → 2 when those two kinds were added, and a decoder REFUSES a foreign version rather than decoding the prefix it understands: a chain missing its await/index hop decodes cleanly as a different, shorter chain and would type the receiver against the wrong member. The format is unescaped (`|` and `~` cannot occur in an identifier), so an unencodable name is refused rather than escaped, and the payload is capped at `MAX_RECEIVER_CHAIN_BYTES` / `MAX_CHAIN_DEPTH` steps. Because these strings live in the incremental parse cache and the durable ParsedFile store, a format change requires a `PARSE_CACHE_VERSION` schema bump — a stale cache would otherwise replay v1 chains this build discards.
Wire format is **v2**: `2|<base>|<step>|<step>…`, one-character version prefix, then base-first steps, each a one-character kind sigil plus the member name (`c` = call, `f` = field). `a` (await) and `i` (index) are **name-free** and encode as a bare sigil — an awaited call's name already lives on its `c` step, and a subscript key is a value, not a lookup-able identifier. The version went 1 → 2 when those two kinds were added, and a decoder REFUSES a foreign version rather than decoding the prefix it understands: a chain missing its await/index hop decodes cleanly as a different, shorter chain and would type the receiver against the wrong member. The format is unescaped (`|` and `~` cannot occur in an identifier), so an unencodable name is refused rather than escaped, and the payload is capped at `MAX_RECEIVER_CHAIN_BYTES` / `MAX_CHAIN_DEPTH` steps. These strings live in both parse stores. Codec and capture changes automatically invalidate their caches through the base parser identity; the explicit receiver-chain wire version and foreign-version rejection still govern decoding.
Receivers the resolver could not type are not silently dropped. Each records a `ResolutionOutcome` (`scope-resolution/resolution-outcome.ts`) carrying the receiver's *shape* (`classifyReceiverShape`: `chain-call` / `chain-field` / `chain-mixed` / `chain-unwrap` / `no-chain` — the bench censuses these) and its *origin* (`in-program` / `external` / `unknown`). `scope-resolution/unresolved-receivers.ts` aggregates them per member name into the index-persisted `unresolvedReceiverMembers` summary, keeping in-program and external counts under separate keys. Only in-program drops make a count short: an external-rooted call (`System.out.println`, `fetch(...)`) has no in-graph node an edge could have reached, so it is reported but does not hedge. `impact` / `context` read that summary and publish `epistemic: 'exact' | 'lower-bound'`, prose `boundaries`, and the machine-readable `causes` split (`EpistemicCauses` in `mcp/local/local-backend.ts`).
@ -343,12 +447,17 @@ Single interface a language implements to plug into the pipeline. Contract fully
| `fieldFallbackOnMethodLookup?` | Statically-typed languages turn this OFF — the heuristic over-connects (default on) |
| `elementTypeOf?` | `(containerType, via: {kind:'index'} \| {kind:'accessor',name}) → elementType \| undefined` — element type of a container, reached by subscript (`repos[0]`) or by a property-style collection view (`data.Values`). ONE hook for both routes (it replaced the split `unwrapCollectionAccessor` / `unwrapCollectionElement`, where implementing one silently answered nothing for the other). Consulted only where the source actually performed the access — never as a general type-name normalizer |
| `stripTypePreservingDecoration?` | `(typeName) → strippedName \| undefined` — strip ONE layer of TYPE-PRESERVING decoration (pointer, reference, `const`, nullable, borrow, sigil) so a receiver declared `*Host` still finds the `Host` binding (#2766). Never a container: unwrapping `Repo[]` here would fold `repos.find(x)` to `Repo.find` — that is `elementTypeOf`'s job, and only after a real subscript. Consulted only after every undecorated lookup fails, and only by receiver-chain base/step resolution — default off |
| `qualifiedTypeLookupSpelling?` | `(typeRef, scopes?) → 'pkg.Type' \| null \| undefined` — the namespace-qualified spelling of a declared type whose qualifier capture cut from `rawName` (`*models.User` stored as `User`), recovered from `declaredSpelling`. Receiver typing tries it first, grounded on the qualifier's import (no unique-name guess). A failed written-qualified lookup stops instead of falling back to a bare type name. The optional scope indexes also let a provider expand a visible namespace alias; `null` refuses the written lookup and its fallback. The binding is not rewritten — default off |
| `collapseMemberCallsByCallerTarget?` | One CALLS edge per (caller, target) instead of per-site — default off |
| `populateNamespaceSiblings?` | Cross-file implicit visibility (compiler-implicit namespace sharing) — default off; ctx carries `treeCache` |
| `resolveImplicitInheritanceBase?` | Fallback for a bare inheritance base the shared chain left unbound, bound by the implicit namespace rule (siblings exist only after the pre-pass); Java, Kotlin, C# opt in |
| `hoistTypeBindingsToModule?` | Walk up to Module scope when looking up a method's return-type typeBinding — default off; enable only when bindings are stored at module level |
| `hasFileLocalCallableLinkage?` | Precise internal-linkage predicate used only when joining callable declarations/prototypes to cross-file definitions; C/C++ use it for `static` free functions |
| `constructorCallTargetsClass?` | A constructor-form call `Type(...)` links to the Class def rather than its explicit Constructor def — default off; Swift and Dart opt in |
| `constructionSyntax?` | How the language spells construction, so an INLINE constructor receiver (`Service(db).m()`, `new Service(db).m()`, `Service.new.m()`) can be typed — `bare` / `keyword` / `selector`; default off, opt in per language only where measured to be needed (#2708) |
| `resolveQualifiedCallee?` | `(calleeText, inScope, …) → callable \| undefined` — resolve a qualified callee only the language can read (Rust `rp::make` in `x = rp::make()` / `rp::make().m()`, Kotlin package path `com.acme.mod.make`) so chain-follow types the call from its return annotation; default off |
| `resolveQualifiedTypeSpellings?` | A receiver's declared or return type written QUALIFIED (`rp::C x`, `f(a::Config c)`) that binds nothing through the scope chain resolves through `resolveQualifiedInheritanceBase` — qualifier matched against the candidate's namespace, refuse on a tie — instead of by its tail, which binds the nearer same-named class. Runs after every existing lookup and after the template-argument match; default off, C++ opts in |
| `splitQualifiedCallee?` | `(callee, callerScope?, scopes?, position?) → { receiver, member } \| undefined` — map a qualified callee spelling (`rp::make`) onto a receiver/member pair that retains the full written namespace qualifier, so a factory result (`auto x = rp::make(); x.m()`, `rp::make().m()`) is typed from the definition `resolveQualifiedReceiverMember` returns and that definition's own declared return type. Caller scope, indexes and source position let a provider reject shadowed or aliased namespace qualifiers only when visible at the factory expression. Shared code never splits on a separator; default off, C++ implements it |
### Per-language registration
@ -408,7 +517,6 @@ Each language implements `LanguageProvider` (`language-provider.ts`). Key fields
| `id`, `extensions` | Language identity and file matching |
| `treeSitterQueries` | S-expression queries for AST extraction |
| `importSemantics` | `named` / `wildcard-leaf` / `wildcard-transitive` / `namespace` |
| `importResolver` | Language-specific path → file resolution |
| `exportChecker` | Public/exported symbol detection |
| `typeConfig` | Type annotation extraction rules |
| `mroStrategy` | `first-wins` / `c3` / `none` |
@ -423,22 +531,9 @@ Per-language tree-sitter queries use different AST node names but produce the **
### Import resolution
Per-language import resolution uses the **configs + factory** pattern (like call/method/class extractors). Each language declares an `ImportResolutionConfig` in `import-resolvers/configs/`, listing an ordered chain of `ImportResolverStrategy` functions. `createImportResolver()` (in `resolver-factory.ts`) composes them: first non-null result wins. Low-level helpers shared across strategies live alongside the configs in `import-resolvers/` (e.g. `go.ts`, `rust.ts`, `python.ts`).
Per-language import resolution runs through `ScopeResolver.resolveImportTarget`, registered in `SCOPE_RESOLVERS`. The shared orchestrator (`scope-resolution/pipeline/run.ts`) passes each language's workspace configuration to the resolver hook. The hook maps a parsed import to its target file or files; finalization links imports and materializes bindings for scope lookup.
Unified 3-tier algorithm (`model/resolution-context.ts`), per-language `importSemantics` controls which tier activates:
| Tier | Confidence | Mechanism |
| ----------------- | ---------- | ---------------------------------------------------------------------- |
| 1 — same-file | 0.95 | Symbol table for caller's file |
| 2 — import-scoped | 0.9 | `NamedImportMap` chains (named) or all files in `importMap` (wildcard) |
| 3 — global | 0.5 | O(1) index lookups: class, impl, callable. Fallback only |
| Import strategy | Languages | Behavior |
| --------------------- | ----------------------------------- | ---------------------------------------------- |
| `named` | TS, JS, Java, C#, Rust, PHP, Kotlin | Only explicitly imported names visible |
| `wildcard-leaf` | Go, Ruby, Swift, Dart | Whole-package import, no transitive re-exports |
| `wildcard-transitive` | C, C++ | `#include` closure chains through re-exports |
| `namespace` | Python | Module aliases resolved at call site |
Language-specific import helpers and namespace rules live beside each resolver in `languages/<language>/`. Language-neutral package-directory and suffix indexes, workspace indexes, and per-file-set caches live in `ingestion/utils/`; suffix lookups receive their ordered extension candidates from callers. The dormant `LanguageProvider.importResolver` field, adapter, and strategy factory have been removed; new languages implement the `ScopeResolver` hook.
### Chunked parse-and-resolve
@ -458,7 +553,7 @@ Workers: `workers/worker-pool.ts`, `workers/parse-worker.ts`.
### Inheritance and MRO
Inheritance is captured by the `@reference.inherits` tag and emitted by the scope-resolution phase: `preEmitInheritanceEdges` resolves each base in scope, then `emitHeritageEdges` writes the `EXTENDS`/`IMPLEMENTS` edges. The phase then computes method resolution order via each `ScopeResolver`'s `buildMro` hook, feeding a `MethodDispatchIndex` used for owner-scoped lookups. Per-language strategy:
Inheritance is captured by the `@reference.inherits` tag and emitted by the scope-resolution phase: `preEmitInheritanceEdges` resolves each base in scope, then `emitHeritageEdges` writes the `EXTENDS`/`IMPLEMENTS` edges. A bare base the shared chain cannot bind falls back to `ScopeResolver.resolveImplicitInheritanceBase`, because same-namespace sibling bindings (`populateNamespaceSiblings`) are populated only after this pre-pass; without it a Java `class C extends B` with no import loses its edge whenever another package also declares a `B`. The phase then computes method resolution order via each `ScopeResolver`'s `buildMro` hook, feeding a `MethodDispatchIndex` used for owner-scoped lookups. Per-language strategy:
- **`first-wins`** — Java, C#, C++, TS, Ruby, Go
- **`c3`** — Python (C3 linearization)
@ -525,6 +620,60 @@ the read-only open is retried — see `sidecar-recovery.ts`
Managed by `repo-manager.ts`.
### Automatic parse-cache identity
`core/parse-cache-identity.ts` derives full SHA-256 base and PDG identities
from sorted, framed logical paths and raw artifact bytes. It needs no Git
history, branch name, timestamp, network access, or contributor-assigned
semantic version. The boundary is intentionally conservative:
| Component | Owned inputs |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base | `core/ingestion/**` except the PDG-only paths below, `core/tree-sitter/**`, `lib/**`, `core/graph/**`, and the audited support/storage files listed in `PARSE_CACHE_BASE_FILES` |
| PDG | `core/ingestion/cfg/**` and the classified COBOL extraction helpers `languages/cobol/flow.ts` and `flow-harvest.ts`; the shared COBOL tokenizer remains in base |
| Runtime and dependencies | The actual selected worker, shared source/compiled runtime or packaged `dist/_shared`, grammar/parser/native/loader dependency closure, and effective runtime/loader options |
Source execution covers both source inputs and the compiled worker when that
is the selected entry. Editing source invalidates identity immediately; it
does not compile that worker. Run `npm run build` before expecting changed
worker facts. Installed packages derive identity from their shipped runtime
without requiring source, Git metadata, or a development compiler. Native
binary bytes and loader fallback candidates are covered even when package
versions stay the same. Unsupported resolution modes such as
`--preserve-symlinks` cannot be verified and disable persistent cache reuse.
Raw bytes mean comments and formatting inside owned roots can invalidate
reuse. Repository documentation, UI, unrelated CLI files, and unrelated
dependencies do not change this parser identity; broader analyzer freshness
rules still apply. New files inside an owned root are included automatically.
Inputs outside that boundary require an ownership decision and an update to
`test/unit/parse-cache-input-coverage.test.ts`, which audits imports, dynamic
loaders, runtime assets, and shared dependencies.
Both the worker-result index and durable `ParsedFile` index validate the base
identity before workers can be skipped. Physical chunk keys bind that identity
and sorted source path/content hashes; PDG-enabled chunks additionally bind
the PDG identity and resolved function-line cap. A CFG-only change therefore
does not invalidate ordinary chunks. Legacy numeric, missing, malformed, or
foreign identities miss; a concurrently pruned shard is also a miss.
`RepoMeta.parseCacheIdentity` records the effective parser identity for
unchanged-analysis and shared-current adoption checks. Analysis resolves it
once, stages fresh cache writes, and verifies artifacts again before
publication. A changed build rejects publication; failed staging or build
verification keeps the published cache pair. Cache-write failures after graph
publication warn without rolling back the successful graph. If identity is
unverifiable, the run uses bounded transient `ParsedFile` storage without
persistent cache reads or writes.
`--no-parse-cache` instead requests a cold parse and publishes its fresh cache
generation on success. FTS-only maintenance retains the old parser receipt.
These checks complement graph `SCHEMA_FINGERPRINT`, the analyzer runner
receipt, embedding preservation, and explicit wire-format checks such as the
V8 envelope and receiver-chain version. Benchmark semantic goldens still
require review of changed facts and pack membership; automatic compatibility
does not approve a new baseline.
## LadybugDB schema
Defined in `lbug/schema.ts`. Separate node tables per type, single `CodeRelation` table.

View file

@ -1,10 +1,10 @@
<!-- version: 1.8.0 -->
<!-- version: 1.9.0 -->
<!--
Metadata: version, last reviewed, scope, model policy, reference docs, changelog.
Last updated: 2026-07-16
Last updated: 2026-10-17
-->
Last reviewed: 2026-07-16
Last reviewed: 2026-10-17
**Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
@ -43,6 +43,7 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
| Date | Version | Change |
| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-10-17 | 1.9.0 | Require the reviewed preview's `plan_token` when applying semantic rename (#2973). |
| 2026-07-20 | 1.8.0 | The CI review agent runs `gitnexus-review` as a coordinated swarm — six `ci-personas/` lanes dispatched via the `Agent` tool with a bounded critic gate. |
| 2026-07-16 | 1.7.0 | `/gitnexus-plan` asks depth up front in interactive runs; `/gitnexus-lfg` gate slimmed to proceed/stop. |
| 2026-07-16 | 1.6.0 | Renamed `/gitnexus-pr-review` to `/gitnexus-review` and added PR, branch/range, and local-change targets. |
@ -82,7 +83,7 @@ This project is indexed by GitNexus as **GitNexus** (248612 symbols, 565510 rela
- NEVER edit a function, class, or method before MCP/CLI impact analysis.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read `UNKNOWN` as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
- NEVER rename symbols with find-and-replace — use `rename` with `dry_run: true` first, review the graph-backed semantic spans and coverage, then apply with `dry_run: false`.
- NEVER rename symbols with find-and-replace — use `rename` with `dry_run: true` first, review the graph-backed semantic spans and coverage, then apply with `dry_run: false` and that preview's `plan_token`.
- NEVER commit before MCP/CLI graph change analysis.
## Resources

View file

@ -85,6 +85,48 @@ Commits within a PR may use any style — only the **merged PR title** shows up
Maintainers may request changes for correctness, tests, performance, or consistency with existing patterns. Keeping diffs focused makes review faster.
### Parser changes and cache compatibility
Parser compatibility is derived automatically from the parser artifacts and
effective options. There is no semantic counter to allocate, reconcile with
the base branch, or regenerate as a checked-in digest. Parallel parser changes
under the same package version produce different identities from their bytes.
The ownership boundary is declared in
`gitnexus/src/core/parse-cache-identity.ts`: ingestion, Tree-sitter, `lib`, graph
helpers, audited support/storage files, the selected worker, shared runtime,
and parser/native/loader dependencies. CFG extraction and the classified COBOL
flow helpers have a separate PDG identity. See
[Architecture](ARCHITECTURE.md#automatic-parse-cache-identity) for the boundary
and publication safeguards. Raw bytes are covered, so formatting or comments
inside these roots can conservatively invalidate caches. Repository docs, UI,
unrelated CLI files, and unrelated dependencies are outside this boundary.
For a parser change:
1. Check that every new import, loader, runtime asset, and effective option is
covered. A new boundary needs an explicit ownership/classification decision
and coverage-audit update; a new provider inside an owned root is included
automatically.
2. Run `npm run build` from `gitnexus/` before validating changed parser facts.
A source edit invalidates source-mode cache identity immediately, but does
not compile the selected worker: an old `dist` worker can still emit old
facts until rebuilt.
3. Verify a real cold parse followed by warm reuse of both worker results and
durable `ParsedFile` shards, asserting graph facts as well as cache metrics.
For extraction-only PDG changes, verify ordinary chunks remain reusable.
Run the focused identity and coverage guards from `gitnexus/`:
`npm test -- test/unit/parse-cache-identity.test.ts test/unit/parse-cache-input-coverage.test.ts`.
4. Review benchmark golden/fingerprint changes explicitly. Explain changed
output or pack membership and why the new baseline is intended, then run
the exact benchmark check. Automatic invalidation does not establish that
a semantic or performance change is correct.
Graph DDL still has its own automatic `SCHEMA_FINGERPRINT`, and analyzer
freshness still has its runner-identity receipt. Intentional wire-format
versions, including the V8 envelope and receiver-chain codec, retain their
own compatibility rules. Preserve those checks when changing a format.
## GitHub Actions — Concurrency Convention
Every workflow under `.github/workflows/` MUST declare a top-level `concurrency:` block using this convention:
@ -165,10 +207,14 @@ peers against their original ranges even when an override is configured. The
lockfile therefore pins the same eight audited peers to exactly `0.25.1`.
`gitnexus/scripts/prepare-tree-sitter-bundle.cjs` runs during `postinstall`
and `prepack` to keep installed dependency manifests consistent with that lockfile
and the published bundle. It leaves grammar sources and native binaries unchanged
and rejects unexpected versions, peer ranges, or dependency layouts before writing
any manifests. The upstream ranges remain in the script only as validation inputs;
installed and published audited manifests require exactly `0.25.1`.
and the published bundle. It leaves grammar sources unchanged and replaces the
incorrect `linux-arm64` prebuilds in five exact npm releases with audited AArch64
binaries. It validates package versions, peer ranges, dependency layouts, and
replacement checksums and architecture before writing manifests or binaries.
The upstream ranges remain in the script only as validation inputs; installed and
published audited manifests require exactly `0.25.1`. See
[`gitnexus/prebuilds/bundled/README.md`](gitnexus/prebuilds/bundled/README.md) for
the affected releases, provenance, and regeneration instructions.
When upgrading these packages, update the exact pins, lockfile, and audited peer
list together. If regenerating the lockfile restores upstream's older peer ranges,
@ -226,7 +272,8 @@ routes between two modes based on the triggering event:
from `latest`. Dispatching with `bump: patch|minor|major` **resets**
the cycle from `latest`.
- `N` is auto-incremented against existing `X.Y.Z-rc.*` entries on the
registry. First rc for a given base is `rc.1`.
registry and `vX.Y.Z-rc.*` Git tags, so delayed npm visibility cannot
reuse an allocated version. First rc for a given base is `rc.1`.
- The RC is gated by CI, including the fixed-answer tool-accuracy check
(`gitnexus/bench/tool-accuracy/`); its report is attached to every
release. RCs do not wait for a paid agent evaluation.

View file

@ -83,31 +83,18 @@ COPY --from=builder --chown=node:node /app/gitnexus/vendor ./gitnexus/vendor
# unreachable from $PATH.
RUN ln -s /app/gitnexus/dist/cli/index.js /usr/local/bin/gitnexus
# Bake the LadybugDB FTS extension into the image so BM25 keyword search works
# at runtime. The server runs the default `load-only` extension policy (the read
# pool pins `{ policy: 'load-only' }`), so a runtime `LOAD EXTENSION fts` never
# INSTALLs — the extension must already exist in the runtime user's HOME
# extension dir, or every keyword search silently degrades (no FTS indexes are
# written and ranking falls back to vector-only with only a `warning` field).
# Run the installer as the `node` user with the SAME HOME the server runs under,
# so `INSTALL fts` materializes the extension under `$HOME/.lbdb/extension` where
# the runtime `LOAD` resolves it offline. `ENV HOME` is pinned because Docker
# does not derive HOME from `USER`, so without it build-install and runtime-load
# would resolve different paths. Requires network egress for the one-time
# INSTALL; the build fails loudly if it cannot fetch the extension. The DB-size
# default comes from GITNEXUS_LBUG_MAX_DB_SIZE (single source of truth, matches
# the runtime) — it only sizes the throwaway scratch DB used to run INSTALL.
# The second `--verify-only` step re-LOADs the extension in a FRESH process
# under the same HOME, so a HOME/extension-dir mismatch fails the build here
# rather than silently degrading keyword search to vector-only at runtime.
# Verify the packaged FTS binary under the runtime user. ExtensionManager loads
# this same vendored path before trying HOME, including under load-only policy.
# The CDN can replace a versioned artifact with an ABI-incompatible rebuild;
# downloading it here would bypass the binary pinned and tested in this tree.
# A missing or unloadable packaged extension must still fail the build.
ENV HOME=/home/node \
GITNEXUS_LBUG_MAX_DB_SIZE=17179869184
RUN su node -s /bin/sh -c "HOME=/home/node node /app/gitnexus/scripts/install-duckdb-extension.mjs fts" \
&& su node -s /bin/sh -c "HOME=/home/node node /app/gitnexus/scripts/install-duckdb-extension.mjs fts --verify-only"
RUN su node -s /bin/sh -c "HOME=/home/node node /app/gitnexus/scripts/install-duckdb-extension.mjs fts --verify-bundled"
# Published runtime assets (in package.json `files`). Placed AFTER the DuckDB
# FTS-extension RUN above so editing hook/skill content does not invalidate that
# network-fetching cache layer; they have no input dependency on it.
# FTS verification above so editing hook/skill content does not invalidate that
# cache layer; they have no input dependency on it.
# `hooks/`: dist/cli/resolve-invocation.js does
# `require('../../hooks/claude/resolve-analyze-cmd.cjs')` at module load — the
# single source of truth for the npm-11 npx-crash invocation decision (#1939).

View file

@ -16,7 +16,7 @@ Maintainer may widen scope per task.
## Non-negotiables
1. **Never commit secrets** — API keys, tokens, real `.env` values, private URLs, session cookies. Use `.env.example` with placeholders.
2. **Never rename with find-and-replace** in GitNexus-indexed projects — use `rename` with `dry_run: true` first (omitting `dry_run` also previews), review exact graph-backed semantic spans and coverage, then apply with `rename` and `dry_run: false`. Unsupported targets fail closed; inspect and refactor them manually with language-aware tools. No separate `gitnexus rename` CLI exists.
2. **Never rename with find-and-replace** in GitNexus-indexed projects — use `rename` with `dry_run: true` first (omitting `dry_run` also previews), review exact graph-backed semantic spans and coverage, then apply with `rename`, `dry_run: false`, and that preview's `plan_token`. Unsupported targets fail closed; inspect and refactor them manually with language-aware tools. No separate `gitnexus rename` CLI exists.
3. **Run impact analysis before editing shared symbols** — `impact` (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
4. **Run `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.
5. **Preserve embeddings** — plain `npx gitnexus analyze` now preserves any embeddings recorded in the index metadata (`.gitnexus/gitnexus.json`, mirrored to the legacy `meta.json`) — the previous behavior wiped them. Use `--embeddings` to also generate vectors for new/changed nodes; use `--drop-embeddings` only when an explicit wipe is intended (e.g., model swap).

View file

@ -1,5 +1,41 @@
# Migration Guide
## Automatic parser cache identities
Parser caches now use artifact-derived base and PDG identities instead of
manually assigned semantic version numbers. The worker-result cache and
durable `ParsedFile` store both validate the base identity, and their physical
chunk keys include it. PDG-enabled chunks also include the PDG identity and
resolved function-line cap. CFG-only changes therefore leave ordinary parse
chunks eligible for reuse.
### Do I need to migrate?
**No.** Run `npx gitnexus analyze` as usual. Legacy numeric caches and indexes
without the parser receipt miss once; successful analysis writes the new
identities. Plan for a cold parse on the first run after upgrading. Missing,
malformed, or foreign identities are also misses, including in shared stores.
Plain analysis continues to preserve existing embeddings.
`--force` rebuilds the graph and may reuse compatible parser output.
`--no-parse-cache` forces a cold parse and publishes a fresh cache generation
after successful analysis. If parser identity cannot be verified, analysis
uses a bounded transient store without persistent cache reads or writes.
Failed staging or build verification leaves the previously published cache
pair intact. Cache-write failures after graph publication are reported as
warnings and do not roll back the successful graph.
### What changes for contributors?
There is no semantic counter or generated digest file to update. Check input
coverage and cold/warm behavior instead; see
[Contributing](CONTRIBUTING.md#parser-changes-and-cache-compatibility).
When running from source, edits invalidate identity immediately but do not
rebuild compiled workers: run `npm run build` in `gitnexus/` before expecting
new parser facts.
Graph DDL fingerprints, analyzer freshness receipts, and intentional
wire-format versions remain separate safeguards.
## `impact` tool may now return `{ status: 'ambiguous' }` (PR #888, issue #470)
Before this change the `impact` MCP tool silently picked the first match

1202
README.md

File diff suppressed because it is too large Load diff

View file

@ -34,6 +34,9 @@ services:
# (http://localhost:4747) works when both containers run locally.
# Set GITNEXUS_BACKEND_URL in your .env or shell for remote/custom setups:
# GITNEXUS_BACKEND_URL=http://<server-ip>:4747
# Behind a reverse proxy that routes /api/* next to the UI, set it to `/`:
# the browser then calls the API on whichever hostname served the page
# (see "Same-origin API behind a reverse proxy" in the README).
environment:
- GITNEXUS_BACKEND_URL=${GITNEXUS_BACKEND_URL:-}
depends_on:

View file

@ -78,12 +78,26 @@ function numberFromEnv(label, fallback, min = 0) {
return n;
}
// A root-relative value — `/`, or `/prefix` when the API is mounted under a
// path — names no host at all: the browser resolves it against the origin that
// served the page, so one deployment answers on every hostname a reverse proxy
// gives it (#3593). Not a URL, so it is read before validHttpUrl would warn.
// `//host` is protocol-relative, an origin change, and is left to the URL check;
// so is `/\host`, since the URL parser reads a backslash as a slash.
function sameOriginPath(value) {
if (typeof value !== 'string' || !/^\/(?![/\\])/.test(value)) return null;
// A base for `${base}/api/...`: no query, fragment, backslash, whitespace or
// control char.
if (/[?#\\\s\x00-\x1f\x7f]/.test(value)) return null;
return value.replace(/\/+$/, '') || '/';
}
// Falls back to RENDER_EXTERNAL_URL so a Render web service hands the browser
// its own public origin — same-origin API calls via the proxy below, no config.
const backendUrlVar =
process.env.GITNEXUS_BACKEND_URL !== undefined ? 'GITNEXUS_BACKEND_URL' : 'RENDER_EXTERNAL_URL';
const rawBackendUrl = process.env.GITNEXUS_BACKEND_URL ?? process.env.RENDER_EXTERNAL_URL ?? null;
const backendUrl = validHttpUrl(backendUrlVar, rawBackendUrl);
const backendUrl = sameOriginPath(rawBackendUrl) ?? validHttpUrl(backendUrlVar, rawBackendUrl);
const configScript = backendUrl
? `<script>window.__GITNEXUS_CONFIG__=${jsonForScriptTag({ backendUrl })};</script>`
: '';

View file

@ -199,6 +199,47 @@ it('injects __GITNEXUS_CONFIG__ into SPA fallback routes', async () => {
});
});
it('injects a same-origin path when GITNEXUS_BACKEND_URL is /', async () => {
await withInjectionServer({ GITNEXUS_BACKEND_URL: '/' }, async (port) => {
const res = await rawGet(port, '/');
assert.equal(res.status, 200);
assert.ok(res.body.includes('"backendUrl":"/"'), 'Expected the root path as the backend URL');
});
});
it('injects a same-origin prefix without its trailing slash', async () => {
await withInjectionServer({ GITNEXUS_BACKEND_URL: '/gitnexus/' }, async (port) => {
const res = await rawGet(port, '/');
assert.equal(res.status, 200);
assert.ok(
res.body.includes('"backendUrl":"/gitnexus"'),
'Expected the prefix as the backend URL',
);
});
});
it('does not inject a protocol-relative GITNEXUS_BACKEND_URL', async () => {
await withInjectionServer({ GITNEXUS_BACKEND_URL: '//evil.example' }, async (port) => {
const res = await rawGet(port, '/');
assert.equal(res.status, 200);
assert.ok(
!res.body.includes('__GITNEXUS_CONFIG__'),
'Expected no __GITNEXUS_CONFIG__ for a protocol-relative value',
);
});
});
it('does not inject a backslash-prefixed GITNEXUS_BACKEND_URL, which a URL parser reads as a host', async () => {
await withInjectionServer({ GITNEXUS_BACKEND_URL: '/\\evil.example' }, async (port) => {
const res = await rawGet(port, '/');
assert.equal(res.status, 200);
assert.ok(
!res.body.includes('__GITNEXUS_CONFIG__'),
'Expected no __GITNEXUS_CONFIG__ for a backslash-prefixed value',
);
});
});
it('does not inject when GITNEXUS_BACKEND_URL is not set', async () => {
await withInjectionServer({}, async (port) => {
const res = await rawGet(port, '/');

346
docs/cli-reference.md Normal file
View file

@ -0,0 +1,346 @@
# CLI reference
[Back to GitNexus](../README.md)
## Commands
Everyday commands:
```bash
gitnexus setup # Configure MCP for detected editors (one-time; -c to select)
gitnexus analyze [path] # Index a repository (or update a stale index)
gitnexus analyze [path] --watch # Watch local files and serialize incremental refreshes
gitnexus mcp # Start MCP server (stdio; one server PER CLIENT) — all indexed repos
gitnexus mcp --http # Start MCP server (Streamable HTTP + SSE) — ONE server, many clients
gitnexus serve # Start local HTTP server (multi-repo) for web UI connection
gitnexus eval-server # Start lightweight evaluation HTTP tools (loopback by default)
gitnexus list # List all indexed repositories
gitnexus status # Show index status for current repo
gitnexus clean # Delete index for current repo
gitnexus wiki [path] # Generate repository wiki from knowledge graph
gitnexus uninstall # Preview removal of GitNexus MCP/skills/hooks (--force to apply)
```
### Multi-client setups: use `--http`, not stdio
MCP-over-stdio is **one server process per client** by protocol design — every client
spawns its own `gitnexus mcp` child, with its own copy of the loaded index. If you run N
concurrent agents/workers, that is N full index servers.
`gitnexus mcp --http` starts **one** server (Streamable HTTP at `POST /mcp`, legacy SSE at
`GET /sse` + `POST /messages`) that any number of clients can connect to:
```bash
gitnexus mcp --http --host 127.0.0.1 --port 3111
```
Point clients at `http://127.0.0.1:3111/mcp`. A non-loopback bind (`--host 0.0.0.0`)
requires `--auth-token` (or `GITNEXUS_MCP_AUTH_TOKEN`) and refuses to start without it.
Measured on a 5-core host with 3 indexed repos, 5 concurrent clients issuing the same
query: shared `--http` ran the batch in 7.7 s at a flat 517 MB, versus 30.0 s and
+514 MB (~103 MB per extra client) for per-client stdio — with identical results.
You can also query the graph directly from the terminal — `gitnexus query`, `context`, `impact`, `trace`, `cypher`, `detect-changes`, and `check` mirror the MCP tools of the same names, and `gitnexus doctor` prints runtime platform capabilities.
`gitnexus analyze --watch` requires a Git repository. It runs one initial
analysis, then debounces scanner-admitted working-tree changes for 300 ms by
default and applies serialized incremental refreshes. Events arriving during a
refresh remain queued, and retryable failures retain the same batch with bounded
backoff. Invalid `.gitnexusrc` or ignore-file reloads pause ordinary refreshes
until the control file is fixed. Stop the watcher with Ctrl+C.
Watch mode accepts `--debounce`, `--workers`, `--worker-timeout`,
`--max-file-size`, `--max-processes`, `--max-process-branching`,
`--max-process-trace-depth`, `--max-entry-point-candidates`, `--branch`, `--pdg`, `--skip-fts`, `--name`, `--allow-duplicate-name`, and
`--verbose`. Explicit one-shot options such as `--force`, `--repair-fts`,
embedding flags, `--skills`, `--self-commit`, `--index-only`, and `--skip-git`
are rejected. Unsupported defaults from `.gitnexusrc` are ignored with a
warning rather than making an otherwise valid repository unwatchable.
POSIX requests clone-first copy-and-swap publication when the live index has no
orphan sidecars. Windows and sidecar fallback runs update in place: failures
known to occur before writes are retried, while a failure that may have mutated
the live index stops the watcher. Watch mode does not pull remotes. Running MCP
and `serve` processes reopen a newly published index automatically; MCP observes
the replacement on its next tool call, typically within five seconds, so no
restart is required.
## Authenticated eval-server binding
`gitnexus eval-server` binds to `127.0.0.1` by default. Loopback bindings do not require authentication. Any non-loopback bind, including `0.0.0.0`, a LAN address, or a hostname that resolves to a LAN IPv4 address, requires `GITNEXUS_AUTH_TOKEN`. Every endpoint then requires an exact `Authorization: Bearer <token>` header.
```bash
GITNEXUS_AUTH_TOKEN='replace-me' gitnexus eval-server --host 0.0.0.0
```
The token may be set in the shell, `.env.local`, or `.env` in the working directory. Precedence is shell > `.env.local` > `.env`. Only `GITNEXUS_AUTH_TOKEN` is read from those files; their other values are not added to the process environment. Keep token files uncommitted.
## All analyze flags
```bash
gitnexus analyze --force # Full graph + FTS rebuild (reuses unchanged parser output)
gitnexus analyze --no-parse-cache # Full rebuild that re-parses every source file
gitnexus analyze --repair-fts # Fast path: rebuild/verify only FTS indexes on existing index data
gitnexus analyze --skip-fts # Index graph/embeddings without loading FTS or building keyword indexes
gitnexus analyze --skills # Generate repo-specific skill files from detected communities
gitnexus analyze --skip-embeddings # Skip embedding generation (faster)
gitnexus analyze --embeddings [limit] # Enable embedding generation (slower, better search)
gitnexus analyze --skip-agents-md # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
gitnexus analyze --skip-skills # Skip installing standard skill files under .claude/skills/ and .agents/skills/
gitnexus analyze --skip-git # Index folders that are not Git repositories
gitnexus analyze --default-branch develop # Branch used in the generated regression-compare example (base_ref)
gitnexus analyze --verbose # Log skipped files when parsers are unavailable
gitnexus analyze --worker-timeout 60 # Increase worker idle timeout for slow parses
gitnexus analyze --workers <n> # Parse worker pool size (>=1; default: cores-1, capped at 16,
# auto-sized to the repo). 0 is rejected — there is no sequential mode.
gitnexus analyze --max-processes <n> # Process-detection process cap (replaces dynamic max(20, round(symbols/10)))
gitnexus analyze --max-entry-point-candidates <n> # Ranked entry-point pool (default 200; raise when the warning names it)
gitnexus analyze --spring-actuator ./actuator # Enrich with local Spring Boot Actuator JSON snapshots
gitnexus analyze --asyncapi-spec ./docs/asyncapi # Resolve broker addresses from AsyncAPI 3.x documents
gitnexus analyze --memory-budget 3000 # Main-thread V8 heap in MB (>= 200); overrides the auto-sizer and --max-old-space-size
gitnexus analyze --wal-checkpoint-threshold 67108864 # LadybugDB WAL auto-checkpoint threshold in bytes
# (default 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB)
```
`--skip-fts` (or `GITNEXUS_SKIP_FTS=1`) disables FTS extension loading and keyword-index construction for this analysis. Graph queries, communities, processes, and existing embeddings remain available. Status and search report "FTS disabled for this index". Remove both the flag and environment setting and run `analyze` again to restore keyword search, even at the same commit. Only the exact environment value `1` enables the opt-out; the flag takes precedence. It cannot be combined with `--repair-fts`. Disabling an existing FTS index may require one graph-store rebuild to avoid unsafe writes through native indexes.
`--spring-actuator` is explicitly opt-in and accepts either a JSON bundle keyed by `mappings`, `beans`, `conditions`, `configprops`, and/or `env`, or a directory containing endpoint-named JSON files. It confirms matching static nodes and adds conservative runtime-only routes, beans, and property keys. The configured input is excluded from source scanning; only normalized repository-relative exclusions are retained for future scans, never absolute paths. Env/configprops values, origins, condition messages, and source names are never persisted or printed. Because snapshots are external runtime state, an enabled run always rebuilds; the first later run without the option rebuilds once to remove runtime evidence. The same path can be set as `springActuator` in `.gitnexusrc`.
`--asyncapi-spec` is explicitly opt-in and accepts a directory of AsyncAPI documents or a single document; the path is resolved against the repository root, so a committed `docs/asyncapi` and an absolute cache written by something else both work. Each `operations[]` entry of an **AsyncAPI 3.x** document can contribute a `Destination` node keyed by broker and address, with `action: send` emitting `PUBLISHES_TO` and `action: receive` emitting `CONSUMES_FROM`, so a document and source code that name one address on one broker land on the same node. Edges start at the document, not at a callable — a document states that the service talks to an address, not which method does — and no address a document names is ever attached to an unresolved source site.
An operation must name a protocol, either through its own `bindings` or through the `servers[].protocol` of the servers its channel resolves to (a channel that lists no `servers` resolves to all of them); operations that name none are refused, as are operations whose two readings name different brokers, and channels that inherit a multi-protocol server set without choosing. HTTP and WebSocket documents are refused for destination minting: there the host rather than the address names the place, and an HTTP endpoint is already modelled as a `Route`. A parameterized address — a channel declaring `parameters`, or an address containing `{` — is refused rather than keyed: two services publishing `{env}.orders` share a pattern, not a queue. AsyncAPI **2.x is refused** under its own counted reason and never mapped, because its `publish`/`subscribe` are inverted relative to 3.x `send`/`receive` and a naive mapping would reverse the async graph while leaving it connected. Every refusal is counted, and a configured path that yields nothing is reported rather than passed over in silence.
Like Actuator snapshots, documents are external to git freshness — replacing one moves no commit and dirties no file — so an enabled run always rebuilds, and the first later run without the option rebuilds once to remove document-derived evidence. There is no glob-based auto-discovery, and the option is unsupported with `--watch`.
If `analyze` reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use `--worker-timeout 60` or set `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000`. For very large files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget.
**Embeddings node limit** — `gitnexus analyze --embeddings` generates semantic search vectors with a default 50,000-node safety cap to protect memory on large repositories:
```bash
gitnexus analyze --embeddings # default 50,000 node safety cap
gitnexus analyze --embeddings 0 # disable the cap entirely
gitnexus analyze --embeddings 100000 # custom cap
```
If embeddings are skipped on a large repository, the indexed graph likely exceeds the default cap — re-run with `--embeddings 0` or a higher limit.
## Keep remote repositories indexed with gitnexus auto-sync
`gitnexus auto-sync` clones or pulls configured repositories, analyzes new commits, and optionally syncs their group. It runs once immediately, then repeats on the configured interval. It runs in the foreground; use your process manager if it must survive a shell session. `gitnexus watch` is reserved and prints this split; it does not start auto-sync or local file watching.
```bash
# 1. Create the config once. It never overwrites an existing file.
gitnexus auto-sync init
# 2. Edit $GITNEXUS_HOME/watch_config.yml, then start it.
gitnexus auto-sync start # `gitnexus auto-sync` is equivalent
gitnexus auto-sync status
gitnexus auto-sync restart # Required after config changes
gitnexus auto-sync stop
gitnexus auto-sync reset # Clear failure state; leaves clones and indexes intact
```
`GITNEXUS_HOME` defaults to `~/.gitnexus`. A minimal configuration:
```yaml
sync_interval_minutes: 10
analyze_timeout: 5m
# Extra hosts beyond github.com, gitlab.com, and gitee.com. Exact names only.
# allowed_hosts: [gitlab.mycompany.com]
projects:
- local_path: /absolute/path/to/clones
branches: [main, master]
# pdg: omit = preserve live index mode; true = keep PDG current;
# false = init default (warns, then strips PDG on the next successful rebuild).
# Do not paste pdg: false onto an existing watch file unless you intend to drop PDG.
pdg: false
overwrite_local_changes: false
remote_urls:
- git@github.com:owner/repo.git
```
- `sync_interval_minutes` must be at least `5`; `local_path` must be an absolute path. Clones are stored below it as `host/namespace/repo`.
- Remote URLs may use SSH SCP or HTTPS. Hosts are github.com, gitlab.com, and gitee.com unless listed in top-level `allowed_hosts` (exact DNS names, no wildcards). The CLI image includes OpenSSH; mount keys yourself. Invalid `watch_config.yml` skips auto-sync immediately. Auto-sync honors `.gitnexusrc` embeddings (HTTP embeddings env still required in the image).
- `branches` are tried in order. The legacy `branch` field is supported, but do not set both.
- Set per-project `pdg: true` to keep the full control-flow, control/data-dependence, and taint layers current. Untouched configs that omit `pdg` preserve an existing index's mode and cannot silently strip PDG data. Do not paste `pdg: false` from this example onto an existing watch file unless you intend to drop PDG; an explicit `false` opt-out logs a warning before removing existing PDG data. Auto-sync requests atomic incremental publication where supported, so readers keep using the previous graph until a successful update is ready and a failed staged analysis leaves it intact; unsupported paths retain the analyzer's existing in-place behavior.
- Analysis runs in an isolated worker; `analyze_timeout` defaults to half of `sync_interval_minutes`, but may be longer (for example, a `30m` analysis timeout with `5` minute polling) up to Node's timer limit. If a polling tick arrives while analysis is active, it is coalesced into one immediate follow-up run using the newest commit. If the parent times out and leaves that worker running, the follow-up is deferred to the next interval so a leftover lock holder is not counted as a hard analyze failure. Timeout and `auto-sync stop` request safe cancellation; a worker in native work exits after reaching a JS-visible safe point. Until then, auto-sync reports `cancelling` or `stopping` and retains ownership so another auto-sync cannot take over, for up to 5 seconds — after that the parent stops waiting and leaves the worker to exit on its own rather than killing it mid-write. This behavior is the same on macOS and Windows. `overwrite_local_changes` defaults to `false`, so a dirty local clone is skipped rather than overwritten; setting it to `true` also deletes untracked files in the clone, while keeping ignored paths.
- Add `group_name` only after creating that group with `gitnexus group create <name>`. Partial clone output is isolated and removed after 14 days.
See the [full auto-sync configuration and runtime reference](../gitnexus/README.md#gitnexus-auto-sync) for concurrency, timeouts, failure thresholds, and runtime files.
## Repository groups (multi-repo / monorepo service tracking)
```bash
gitnexus group create <name> # Create a repository group
gitnexus group add <group> <groupPath> <registryName> # Add a repo. <groupPath> is a hierarchy path
# (e.g. hr/hiring/backend); <registryName> is the
# repo's name from the registry (see `gitnexus list`)
gitnexus group remove <group> <groupPath> # Remove a repo by its hierarchy path
gitnexus group list [name] # List groups, or show one group's config
gitnexus group sync <name> # Extract contracts and match across repos/services
gitnexus group contracts <name> # Inspect extracted contracts and cross-links
gitnexus group query <name> <q> # Search execution flows across all repos in a group
gitnexus group status <name> # Check staleness of repos in a group
gitnexus group impact <name> --target <symbol> --repo <groupPath> # Cross-repo blast radius
```
## Project config (.gitnexusrc)
Commit a `.gitnexusrc` JSON file at the repo root to preconfigure recurring `analyze` options per project, instead of re-passing the same flags every run. It is read from the resolved repo root (not `.gitnexus/`, which is gitignored index storage). **CLI flags always override `.gitnexusrc`.**
```jsonc
{
// Default branch used in the generated regression-compare example (base_ref).
// Use this so a project on `develop`/`master` doesn't get "main" rewritten
// over its fix on every analyze. (Alias: "branch".)
"defaultBranch": "develop",
"skipContextFiles": true, // alias of skipAgentsMd: keep your own AGENTS.md/CLAUDE.md
"skipSkills": true, // don't install standard skill files under .claude/skills/ and .agents/skills/
"embeddings": true, // generate embeddings by default
"springActuator": "./actuator", // optional local runtime snapshot directory or bundle
"workerTimeout": 60,
}
```
A nested `analyze` block is also accepted (and overrides flat keys for the same option):
```json
{ "analyze": { "defaultBranch": "develop", "skipSkills": true } }
```
Notes:
- The default branch is resolved as: `--default-branch` > `.gitnexusrc` `defaultBranch`/`branch` > auto-detected `origin/HEAD` > `main`.
- `skipContextFiles` / `skipAiContext` are aliases for `skipAgentsMd` — they skip the `AGENTS.md` / `CLAUDE.md` block only. They do **not** imply `skipSkills`. `indexOnly` is the stronger option that skips all file injection.
- Supported keys: `defaultBranch` (`branch`), `skipAgentsMd` (`skipContextFiles`, `skipAiContext`), `skipSkills`, `indexOnly`, `stats`/`noStats`, `embeddings`, `dropEmbeddings`, `name`, `allowDuplicateName`, `maxFileSize`, `workerTimeout`, `walCheckpointThreshold`, `workers`, `maxProcesses`, `maxProcessBranching`, `maxProcessTraceDepth`, `maxEntryPointCandidates`, `springActuator`, `embeddingThreads`, `embeddingBatchSize`, `embeddingSubBatchSize`, `embeddingDevice`.
- The file is JSON only. Unknown keys and wrong JSON types fail fast with an actionable error before analysis starts. Process-detection knobs (`maxProcesses`, `maxProcessBranching`, `maxProcessTraceDepth`, `maxEntryPointCandidates`) that are not a positive integer warn and fall through to env, then the built-in default.
## Environment variables
Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max-file-size`, `--verbose`). Use the env-var form when you'd otherwise repeat the same flag every run, or when invoking GitNexus from a long-running host (MCP server, eval-server, CI shell) that already manages its own environment. CLI flags take precedence over `.gitnexusrc`, which takes precedence over env vars, which take precedence over built-in defaults.
| Variable | Default | Effect | Tune when… |
| ----------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GITNEXUS_TEST_REPORT` | unset | Write a JSON execution receipt from `scripts/run-cross-platform.ts`; accepts a basename ending in `.json`. | CI platform shards use distinct filenames so the completeness check can require every report. |
| `GITNEXUS_WORKER_POOL_SIZE` | `cores - 1`, capped at 16 | Parse worker pool size (must be ≥ 1). Equivalent to `--workers <n>`. The worker pool is the sole parse path — there is no sequential parser, so `0` is rejected with an actionable error (the pool self-heals via quarantine + respawn). | Constrained containers (cgroup CPU limits) or CI runners with explicit quotas. To narrow down a worker crash set `1` for a single-worker pool — not `0`. |
| `GITNEXUS_PARSE_CHUNK_CONCURRENCY` | `2` | Number of chunks whose file contents may be read into memory in parallel while the pool dispatches the current chunk. Worker dispatch itself stays serial. | Repos large enough to chunk (multi-MB total source) where disk I/O is a measurable fraction of analyze wall-clock. |
| `GITNEXUS_VERBOSE` | unset | When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`. | Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput. |
| `GITNEXUS_EMBEDDING_RETRY_TIMEOUTS` | unset | When truthy (`1`/`true`/`yes`), per-attempt HTTP embedding timeouts (`TimeoutError` on fetch or body read) go through the bounded `GITNEXUS_EMBEDDING_MAX_ATTEMPTS` retry loop instead of failing the job. Any other value leaves it off, so cloud/default timeouts remain terminal. | Local accelerators that drop a device lock when the client disconnects and succeed on the next request (observed with FastFlowLM on Ryzen AI). |
| `GITNEXUS_EMBEDDING_SIDECAR_TIMEOUT_MS` | `180000` (3 minutes) | Per-request IPC timeout for local embedding sidecar embed batches. On overrun the parent SIGKILLs the sidecar child and rejects the batch. Init still uses the HF download budget (`HF_DOWNLOAD_TIMEOUT_MS` × attempts), not this knob. | Large embed batches or slow local ONNX inference cause sidecar request timeouts during `analyze --embeddings`, `embeddings sync`, serve, or MCP. |
| `GITNEXUS_VECTOR_MAX_DISTANCE` | `0.6` for CLI/MCP `query`; `0.5` for standalone semantic search | Maximum cosine distance for vector hits, applied to both indexed search and exact-scan fallback. Hits must have `distance < cutoff`. Unset/blank uses the default; non-numeric, non-finite, zero, or negative values warn and use the default; finite values above `2` warn and clamp to `2`. | Paraphrased queries have weak semantic recall with your embedding model. See [Vector cutoff tuning](#vector-cutoff-tuning). |
| `GITNEXUS_ANALYZER_IDENTITY_IN_PROCESS_GUARDS` | unset | When truthy (`1`/`true`/`yes`), forces in-process cache-guard validation once a batch has ≥128 requests. In-process mode also auto-selects when `packageRoot`/`buildRoot` fail `W_OK` with `EACCES`/`EROFS`. Otherwise those large batches use a Node subprocess probe. Batches under 128 always stay in-process. | Trusted or read-only installs where two identity subprocess spawns per analyze dominate wall time; leave unset to keep the default isolation path on writable trees. |
| `GITNEXUS_RESOLVE_DEF_GRAPH_ID_MEMO` | on (unset) | Memoizes `resolveDefGraphId` per `nodeLookup` instance (WeakMap). Enabled by default. Set to `0`/`false`/`off`/`no` to disable and recompute on every call (debug / bisect memo bugs). | Suspecting stale graph-id resolution after a lookup rebuild, or comparing memo vs uncached cost on a large index. |
| `GITNEXUS_AUTH_TOKEN` | unset | Bearer token required when `eval-server` binds beyond loopback. May also be read from `.env.local` or `.env`; shell values take precedence. | Exposing the evaluation HTTP tools to a container, VM, or LAN. |
| `GITNEXUS_MCP_AUTH_TOKEN` | unset | Bearer token for the dedicated `gitnexus mcp --http` server, for a **directly reachable** `gitnexus serve` `/api/mcp` route, and for the `docker-server` / web proxy in front of one. A non-loopback dedicated MCP bind requires it; `serve` enables protocol-layer MCP auth when it is set. Behind a proxy, set the **same** value on both services: the proxy spends the edge `GITNEXUS_SERVE_AUTH_TOKEN`, then replaces `Authorization` with this token on `/api/mcp` only. | Dedicated MCP, a `serve` the client can reach directly, or a proxied deploy (Render Blueprint) where the backend runs protocol-layer MCP auth — configure it on the proxy too. |
| `GITNEXUS_PROFILE_DEFERRED` | unset | When `1`, emits `[deferred-profile]` timing/progress logs for the post-chunk deferred resolution band (imports → heritage → buildHeritageMap → legacy call resolution). Implied by `GITNEXUS_VERBOSE`. | Diagnosing analyze stalls in "Resolving calls (all chunks)" on large Java/Kotlin repos (issue #1741) without the full verbose ingestion noise. |
| `GITNEXUS_PROFILE_DEFERRED_SLOW_MS` | `3000` (verbose) / `5000` | Per-file threshold in ms above which `processCallsFromExtracted` emits a `slow file …` log line. Parsed via `Number()`: accepts integers (`5000`), scientific notation (`2.5e3`), decimals (`.5`), and hex (`0x10`). Non-finite or non-positive values fall back to the default. | Hunting a few outlier files dominating the deferred call-resolution stage; lower to surface more, raise to focus only on the worst. |
| `PROF_LBUG_LOAD` | unset | When `1`, emits one `[lbug-load prof]` summary line per `loadGraphToLbug` call breaking the graph-DB persistence wall into stages (`csv-emit` / `copy-nodes` / `copy-rels` / `fallback` / `total`) plus node & edge counts. Zero-cost when unset. | Attributing large-repo analyze wall time across CSV generation vs. LadybugDB `COPY` (issue #2203) — the analyze "emit" timing is the scope-resolution bucket, not this DB-write path. |
| `GITNEXUS_MAX_FILE_SIZE` | `512` (KB) | Walker skip threshold in KB. Hard cap is `32768` (tree-sitter buffer ceiling). Equivalent to `--max-file-size <kb>`. | Indexing repos with intentionally-large source files (generated parsers, vendored bundles) that should still be parsed. |
| `GITNEXUS_MAX_PROCESSES` | dynamic (`max(20, round(symbols/10))`) | Analyze-time process-detection process cap. Equivalent to `--max-processes <n>` / `.gitnexusrc` `maxProcesses`. Explicit values replace the dynamic formula (not a multiplier). `0` is invalid, not unlimited. Changing this re-detects flows on the next analyze without `--force`. Distinct from query-time `IMPACT_MAX_CHUNKS`. | `[processes] … whole flows are MISSING` names `--max-processes` after entry points were never traced or flows were dropped. Tracing does not start the next entry once collected traces already reach `maxProcesses * 2`; a started entry can still emit every trace that entry produces. |
| `GITNEXUS_MAX_PROCESS_BRANCHING` | `4` | Analyze-time per-node branching cap during flow tracing. Equivalent to `--max-process-branching <n>`. Shape-only: raising it shortens fewer traces; it does not restore whole missing flows. | A flow is present but `calleesDropped` is high at debug. |
| `GITNEXUS_MAX_PROCESS_TRACE_DEPTH` | `10` | Analyze-time DFS depth cap during flow tracing. Equivalent to `--max-process-trace-depth <n>`. Shape-only. | A reported flow is shorter than the code path (`tracesDepthCapped` at debug). |
| `GITNEXUS_MAX_ENTRY_POINT_CANDIDATES` | `200` | Ranked entry-point candidate pool. Equivalent to `--max-entry-point-candidates <n>`. Raising `--max-processes` alone does not clear `entryPointCandidatesDropped`. Doubling the current cap is the usual first raise; setting it to the full remaining candidate count can exhaust CPU and memory. | The `[processes]` warning reports candidate entry points that never ranked in. |
| `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS` | `30000` | Worker idle timeout in milliseconds before retry/fallback. Equivalent to `--worker-timeout <seconds>` × 1000. | Slow-parsing files (large minified JS, deeply-nested TS types) that legitimately need more than 30s. |
| `GITNEXUS_WORKER_READY_TIMEOUT_MS` | `5000` | Startup budget in milliseconds for a parse worker to load its grammar bindings and report `{type:'ready'}`. Slots that miss it are treated as startup crashes. | Slow or heavily loaded hosts where a full pool cold-starting concurrently needs more than 5s, and analyze aborts with "did not report ready within 5000ms". |
| `GITNEXUS_FTS_STEMMER` | `porter` | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` for matching repository comments. Re-run `gitnexus analyze --repair-fts` after changing it. | Keyword search quality is poor for non-English comments or identifiers under English stemming. |
| `GITNEXUS_STORAGE_PATH` | unset (`<repo>/.gitnexus/`) | Complete external index directory. This preserves the existing configuration semantics and takes precedence over `GITNEXUS_STORAGE_ROOT` when both are set. | You already keep one repository index outside its checkout or need one explicit index location. |
| `GITNEXUS_STORAGE_ROOT` | unset | Absolute root directory for external indexes. GitNexus creates an isolated `<repo-basename>-<canonical-path-hash>/` slot beneath it for each repository, then registers the resolved slot so `status`, MCP, and `serve` can reopen it later. | You want to manage multiple repository indexes centrally or keep generated data outside source checkouts. |
| `GITNEXUS_SHARED_STORE` | unset (on) | Set to `off` (or `0`, `false`, `no`) to turn off shared index stores for both linked git worktrees and sibling clones; every checkout then indexes into its own `.gitnexus/`. Sharing is also off whenever `GITNEXUS_STORAGE_PATH` or `GITNEXUS_STORAGE_ROOT` is set. | Disk or memory is not a concern, or you want each worktree's index fully independent. |
| `GITNEXUS_CONTENT_RETENTION` | `full` | Source-text retention profile: `full` keeps file and symbol text, `symbol` keeps symbol snippets without full file content, and `none` keeps the structural graph without source body text. | You need to reduce persisted source text while preserving graph structure. |
| `GITNEXUS_SKIP_FTS` | unset | When exactly `1`, skips FTS extension loading and keyword index creation during analyze. Equivalent to `--skip-fts`; a later analyze without either option restores FTS. | Graph-only consumers with their own retrieval, or short-lived indexes that do not need keyword search. |
| `GITNEXUS_WAL_CHECKPOINT_THRESHOLD` | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold in bytes. Equivalent to `--wal-checkpoint-threshold <bytes>`. `-1` keeps LadybugDB's stock threshold (~16 MiB). Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments. | You need a larger or smaller WAL auto-checkpoint threshold for your analyze workload. |
| `GITNEXUS_LBUG_BUFFER_POOL_SIZE` | min(2 GiB, 80% RAM) | LadybugDB buffer-pool ceiling in bytes for every GitNexus database (analyze, MCP server, serve, group bridges). `0` restores LadybugDB's native unbounded default of 80% of system RAM; invalid values warn and fall back to the default (#2557). During `analyze` the pool is right-sized to the graph, scaled on non-4 KiB-page hosts by the page-size granule ratio up to min(2 GiB × pageSize/4 KiB, 80% RAM) (#2631); this env var overrides all of that as an absolute value. | A long-lived `gitnexus mcp` or a big incremental `analyze` uses too much memory, or a huge repo's working set genuinely needs a pool larger than 2 GiB. |
| `GITNEXUS_LBUG_MAX_DB_SIZE` | `17179869184` (16 GiB) | Maximum size in bytes of a single LadybugDB database file — an mmap/disk-address-space ceiling, not a memory limit (it does not constrain the buffer pool). The native engine requires a power of two: any other positive integer is rounded up to the next power of two with a warning, and invalid values silently fall back to the default. | Indexing a genuinely huge monorepo whose on-disk graph index approaches 16 GiB. |
| `GITNEXUS_ATOMIC_INCREMENTAL` | unset (the caller's choice) | `1` stages an incremental analyze into a copy of the index and swaps it in at the end, so a failed run leaves the live index untouched. `0` turns that off even for callers that request it (watch mode, auto-sync); the run logs a line when it overrides one. The cost: a failed in-place write can leave the live index partly written, and the next run then rebuilds it in full. A full rebuild, and an incremental run that escalates to a staged rebuild, still stage. POSIX only. | A staged incremental analyze fails (see _Troubleshooting_ in the package README), or you need in-place writes. |
| `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` | `8388608` (8 MB) | Per-job byte budget the pool will send to a worker in one `postMessage`. | Very large individual files; mostly diagnostic — bumping past 8 MB risks structured-clone memory pressure. |
| `GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT` | `3` | Max replacement spawns per worker slot before the slot is dropped from the active rotation. Bounds respawn loops on a chronically-crashing slot. | Hosts where a flaky worker should retry more (raise) or fail-fast (lower) before the slot is dropped. |
| `GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS` | `5 × subBatchTimeoutMs` | Total retry wall-time budget per job before quarantining. Combined with `timeoutBackoffFactor`, prevents exponentially-growing retries from stalling for hours. | Slow files that legitimately need long total retry windows; lower to fail-fast on stalls. |
| `GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD` | `max(3, poolSize)` | Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, every subsequent dispatch rejects until a fresh pool is created. | Hosts where a SIGSEGV-prone native grammar should trip the breaker sooner; CI runners that should fail loudly. |
| `GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS` | `30000` | Max wait at pool shutdown for a retired worker still inside native code. The worker is terminated at its next JS-safe point instead of mid-native-call (which aborts the whole process with `Napi::Error`, #2432); on expiry it is left running, unref'd, and terminated when it surfaces. | Shutdown latency matters more than draining a wedged worker (lower), or a legitimately-slow native grammar needs longer to surface (raise). |
| `GITNEXUS_CPP_CAPTURE_BUDGET_MS` | `20000` | Per-file wall-clock budget for C++ capture extraction. On breach the file keeps the captures accumulated so far and logs a warning — the worker returns to JS instead of stalling in native-heavy loops (#2432). `0` expires immediately. | Pathological generated C++ that still exceeds the budget after the indexed lookups; raise for completeness, lower to fail-fast. |
| `GITNEXUS_CHUNK_BYTE_BUDGET` | `2097152` (2 MB) | Per-bucket byte budget for parse-cache packing. Files are grouped by `(language, hash(path) mod 128)`; packs inside a bucket are cut at this limit. Smaller = finer-grained invalidation and more dispatch. Default is always 2 MiB and no longer scales with worker count. | Tuning incremental-analyze cache invalidation on monorepos without changing `--workers`. |
| `GITNEXUS_NO_GITIGNORE` | unset | When set, skips `.gitignore` parsing. `.gitnexusignore` is still honored. | Indexing a repo whose `.gitignore` excludes files you actually want indexed (e.g., generated code committed for cross-repo lookup). |
| `GITNEXUS_SKIP_OPTIONAL_GRAMMARS` | unset | When exactly `1`, skips optional vendored Dart, Proto, Swift, Kotlin and Zig grammar setup. The C grammar and other native dependencies remain required. | Skipping optional language parsers when their prebuilds are unavailable and no source-build toolchain is installed. |
| `GITNEXUS_MCP_READ_ONLY` | unset | Set to `1` to expose only proven single-repository read tools and resources; `0` disables the policy and any other value fails startup. | The MCP server runs in an environment where graph mutation, raw Cypher, and cross-repository group routing must be unavailable. |
| `GITNEXUS_MCP_ALLOWED_REPOS` | unset | Comma-separated allowlist of canonical indexed repository names or absolute paths. Invalid, ambiguous, or blank entries fail startup. | One MCP process must expose only a bounded subset of the repositories in the global registry. |
| `GITNEXUS_MCP_DEFAULT_REPO` | unset | Canonical indexed repository name or absolute path used when a tool or resource omits its repository. Must belong to the allowlist when one is set. | Several repositories are available but unqualified MCP calls should resolve deterministically. |
| `GITNEXUS_MCP_DEFAULT_MAX_TOKENS` | unset | Default positive-integer response budget for MCP `query`, `context`, and `impact`, estimated at four UTF-8 bytes per token. Explicit `maxTokens` wins. | Long MCP responses consume too much model context and callers cannot reliably add a per-request budget. |
| `GITNEXUS_PUBLIC_ORIGIN` | unset | The single browser origin `serve` is reached through, added to the CORS allowlist and to the write-route origin guard. A wildcard bind (`0.0.0.0`) has no host identity, so without this the server's own UI is refused. **Setting it currently refuses to start:** `serve` has no authentication, requests carrying no `Origin` header already reach `POST /api/analyze` and `DELETE /api/repo`, and this is the setting that would admit browser writes on top of that. Matching rules for when the gate lifts: the hostname must match exactly, and so must the scheme. A value with no scheme (`app.example.com`) means `https`, since a bare host comes from platform service discovery and those terminate TLS; spell out `http://app.example.com` for plain HTTP. An explicit port must match; with no port, any port on that hostname is accepted. Anything that is not one reachable host (a list, `*`, a bare port number, a `:0` port, a trailing dot) warns at startup and allows nothing. | `gitnexus serve` runs behind a reverse proxy or on a wildcard bind, and the UI's index/delete requests return `origin_not_allowed`. |
| `GITNEXUS_TRUST_PROXY` | `loopback, linklocal, uniquelocal` | Express `trust proxy` value — which upstream hops may set `X-Forwarded-*`, and so what the per-IP rate limiter reads as the client IP. Set it to the exact number of proxies you control. Every hop past that is one more entry of the chain the caller gets to write. `false`/`no`/`off` (and a `0` hop count) trust no hop; a proxy list Express can compile (`loopback`, `10.0.0.0/8, 127.0.0.1`) names them instead. `true`/`yes`/`on` is **rejected**: it reads the client-controlled leftmost `X-Forwarded-For` entry, so a spoofed chain earns a fresh rate-limit key per request, and express-rate-limit rejects it too (`ERR_ERL_PERMISSIVE_TRUST_PROXY`). Counts above `16` are rejected as well, as a sanity ceiling rather than a safety boundary. Any invalid value warns and falls back to the default. Bind non-loopback with this unset and `serve` warns: a load balancer outside the private ranges is untrusted, so every request keys to the balancer and the per-IP limit becomes one shared limit. | `serve` sits behind a load balancer outside the private ranges (AWS ALB, Cloudflare, CGNAT), where every request otherwise collapses to the proxy hop and rate limiting goes global. |
### Vector cutoff tuning
`GITNEXUS_VECTOR_MAX_DISTANCE` controls which vector candidates enter hybrid search. Cosine distance is lower for more similar vectors; the appropriate cutoff depends on the embedding model and repository. A higher cutoff can recover useful semantic matches, but can also admit less relevant hits and change the fused ranking. The default is `0.6` for CLI and MCP `query`, and `0.5` for the standalone semantic-search function.
For an index that already has embeddings, compare the default with `0.8` and `1.0` on representative queries, including paraphrases, exact symbol names, and queries that should have no relevant result:
```bash
GITNEXUS_VECTOR_MAX_DISTANCE=0.8 gitnexus query "how are expired sessions removed" --limit 10
```
Check both whether the expected symbols appear and where they rank. In [#3457](https://github.com/abhigyanpatwari/GitNexus/issues/3457), the reporter's `voyage-code-4` sample found 20 of 32 paraphrased targets at `0.6`, 25 at `0.8`, and 28 at `1.0`. Those values are a tuning starting point for that model, not universal recommendations: one paraphrased target fell from first to twelfth at `1.0`. The sample covered eight repositories, recorded no raw distances, used agent-written queries after reading the code, and did not send Voyage's `input_type`.
Set the variable in the process that runs the search. For MCP, add it to the server's launch environment and restart the server; for `gitnexus serve`, set it in that process's environment and restart it. Setting it only during `analyze`, or exporting it in another shell, does not configure an existing server. Changing the cutoff requires no reindex.
The cutoff only filters available vector candidates. It cannot add missing embeddings or repair a mismatch between the indexing and query-time embedding configuration; see the [embeddings runbook](../RUNBOOK.md#embeddings). A cutoff of `2` is very permissive, but still rejects distance exactly `2` and retains the search candidate limits.
## gitnexus uninstall
`gitnexus uninstall` reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove.
## Publishing to understand-quickly (opt-in)
[`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly) is a public registry of code-knowledge graphs that lists `gitnexus@1` as a first-class format. After registering your repo once (`npx @understand-quickly/cli add` or the [wizard](https://looptech-ai.github.io/understand-quickly/add.html)), `gitnexus publish` fires a single `repository_dispatch` event so the registry resyncs your entry on demand instead of waiting for the nightly job.
It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained GitHub PAT with `Repository dispatches: write` on the registry repo. Nothing else happens; no graph file is uploaded. See the [protocol spec](https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md) for the full contract.
## Index storage and multiple repositories
GitNexus uses a **global registry** so one MCP server can serve multiple indexed repos. No per-project MCP config needed — set it up once and it works everywhere.
Each `gitnexus analyze` stores the index in `.gitnexus/` inside the repo by default (portable, gitignored). `GITNEXUS_STORAGE_PATH` selects one complete external index directory and preserves the established configuration behavior. To manage multiple repositories under one external directory, set `GITNEXUS_STORAGE_ROOT`; GitNexus derives an isolated `<repo-basename>-<canonical-path-hash>/` slot beneath it for each repository. If both variables are set, `GITNEXUS_STORAGE_PATH` takes precedence. GitNexus registers the resolved slot in `~/.gitnexus/registry.json`, allowing later `status`, MCP, and `serve` commands to reopen the index without repeating the environment variable. LadybugDB connections are opened lazily on first query and evicted after 5 minutes of inactivity (max 5 concurrent). Read-only tools can omit `repo` when only one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing into an unindexed nested Git checkout. Outside those paths—and for mutating tools with multiple indexed repos and no MCP default—pass `repo` explicitly.
**Worktrees share one index store.** When a repository has linked worktrees (`git worktree add`), the main checkout and every worktree index into one store at `~/.gitnexus/stores/<repo>/` instead of each keeping a full `.gitnexus/`. Checkouts at the same commit with no local changes read one shared, read-only graph: one copy on disk and one open database in MCP. A checkout with uncommitted changes gets its own graph, copied from the nearest shared graph and updated incrementally rather than rebuilt. Parse caches are shared too. Each worktree keeps a small `.gitnexus/store.json` pointer, and an index it had before sharing is left in place; `gitnexus status` reports it and `gitnexus clean --local-index --force` removes it. `gitnexus clean` in one worktree removes only that worktree's slot and any shared graph no other checkout uses; `gitnexus clean --gc` also drops slots whose worktree was deleted. Independent clones of one repository share too: when another registered clone has the same `origin` URL, `gitnexus analyze` in a clone joins that clone's store (or starts one the other clone joins on its next analyze). A lone clone keeps its own `.gitnexus/`. `gitnexus analyze --share-with <name-or-path>` joins a specific checkout's store after checking the `origin` URLs match, and `--no-share` moves a clone back to its own `.gitnexus/` and keeps it out until `--share-with`. On filesystems with copy-on-write clones (APFS, btrfs, XFS) a checkout's private graph shares its unchanged pages with the shared graph on disk; elsewhere it is a full copy, and `gitnexus status` says which. Queries cannot combine two graphs, because LadybugDB reads one database per query, so a checkout with edits always has a complete graph of its own. Set `GITNEXUS_SHARED_STORE=off` (or `0`, `false`, `no`) to turn sharing off for worktrees and clones alike.
## Architecture diagram
```mermaid
flowchart TD
subgraph CLI [CLI Commands]
Setup["gitnexus setup"]
Analyze["gitnexus analyze"]
Clean["gitnexus clean"]
List["gitnexus list"]
end
subgraph Registry ["~/.gitnexus/"]
RegFile["registry.json"]
end
subgraph Repos [Project Repos]
RepoA[".gitnexus/ in repo A"]
RepoB[".gitnexus/ in repo B"]
end
subgraph MCP [MCP Server]
Server["server.ts"]
Backend["LocalBackend"]
Pool["Connection Pool"]
ConnA["LadybugDB conn A"]
ConnB["LadybugDB conn B"]
end
Setup -->|"writes global MCP config"| CursorConfig["~/.cursor/mcp.json"]
Analyze -->|"registers repo"| RegFile
Analyze -->|"stores index"| RepoA
Clean -->|"unregisters repo"| RegFile
List -->|"reads"| RegFile
Server -->|"reads registry"| RegFile
Server --> Backend
Backend --> Pool
Pool -->|"lazy open"| ConnA
Pool -->|"lazy open"| ConnB
ConnA -->|"queries"| RepoA
ConnB -->|"queries"| RepoB
```

182
docs/deployment.md Normal file
View file

@ -0,0 +1,182 @@
# Deployment
[Back to GitNexus](../README.md)
## Deploy to Render
Deploy GitNexus in one click:
[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/abhigyanpatwari/GitNexus)
The Blueprint creates two services. `gitnexus-server` runs `gitnexus serve` as a private service: no public URL, reachable only over Render's private network, with a persistent disk for indexes and cloned repos. `gitnexus-web` is the public one. It serves the UI and reverse-proxies `/api/*` to the server, so the browser talks to a single origin.
At the Blueprint's defaults this runs about **$35/month**: $25 for the server's `standard` instance, $7 for the web service's `starter` instance, and $2.50 for the 10 GB disk. See [Render's pricing](https://render.com/pricing) for other plans.
The deploy generates an access token, and the UI asks for it on first use:
1. Open the `gitnexus-web` service in your [Render dashboard](https://dashboard.render.com/).
2. Copy `GITNEXUS_SERVE_AUTH_TOKEN` from its **Environment** tab.
3. Load the site and paste the token into the prompt (or the settings panel).
Every `/api/*` request carries that token as a header, and the proxy answers `401` without it. The browser keeps it in `sessionStorage`, so a new tab asks again. To rotate it, edit the environment variable and redeploy.
The proxy strips `Origin` before forwarding, so the server's CSRF guard does nothing for proxied traffic; it passes `Origin`-less requests through by design. The token is the only control on this deploy, not a second layer behind the guard. Anyone holding it can read every indexed repo. See [SECURITY.md](../SECURITY.md#hosted-deploys-on-render).
Indexing is memory-bound. If `gitnexus-server` runs out of memory on a large repo, raise its `plan`, which sets available RAM: `standard` is 2 GB, `pro` is 4 GB. Raise `sizeGB` only if the disk fills with clones and indexes.
## Deploy to RepoCloud
[![Deploy on RepoCloud](https://d16t0pc4846x52.cloudfront.net/deploylobe.svg)](https://repocloud.io/details/gitnexus/)
## Docker
Run Compose commands from the repository root.
```bash
docker compose up -d
```
This starts the server on `http://localhost:4747` and the web UI on `http://localhost:4173`. The UI auto-detects the server because the browser runs on the host and reaches the container via the mapped port.
The official setup ships **two signed images**, published identically to **GitHub Container Registry** (GHCR) and **Docker Hub** — same build, same digest, same Cosign signature:
| Purpose | GHCR (default in `docker-compose.yaml`) | Docker Hub mirror |
| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------ |
| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest` | `akonlabs/gitnexus:latest` |
| Static web UI (port `4173`) | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest` |
A named volume (`gitnexus-data`) persists the global registry, indexes, and cloned repos at `/data/gitnexus` inside the server container. To make repos on your host machine indexable, set `WORKSPACE_DIR` before bringing the stack up:
```bash
WORKSPACE_DIR=$HOME/code docker compose up -d
# Inside the server container the directory is mounted read-only at /workspace.
docker compose exec gitnexus-server gitnexus index /workspace/my-repo
```
> **Heads-up — image rename.** Earlier releases published the web UI under `ghcr.io/abhigyanpatwari/gitnexus`. That slug now hosts the CLI/server image and the UI moved to `ghcr.io/abhigyanpatwari/gitnexus-web`. Previous tags remain pullable, but new versions are only published under the new slugs — update your `docker run` / compose files (or just adopt the bundled compose).
## Direct docker run & env file
```bash
# Server
docker run --rm -d \
--name gitnexus-server \
-p 4747:4747 \
-v gitnexus-data:/data/gitnexus \
ghcr.io/abhigyanpatwari/gitnexus:latest
# Web UI
docker run --rm -d \
--name gitnexus-web \
-p 4173:4173 \
ghcr.io/abhigyanpatwari/gitnexus-web:latest
```
Optional env file (override image tags, container names, ports, workspace dir):
```bash
cp .env.example .env
docker compose --env-file .env up -d
```
<details>
<summary><strong>Same-origin API behind a reverse proxy</strong></summary>
`GITNEXUS_BACKEND_URL` is normally an absolute URL, which ties the UI to one API hostname. Set it to `/` instead and the browser calls the API on the origin that served the page — so one `gitnexus-web` container can be reached on several hostnames (an internal `*.localhost` name and a public one, say) as long as `/api/*` is served next to the UI on each of them. A path such as `/gitnexus` works the same way for an API mounted under a prefix.
`/api/*` goes through the web container's own proxy: give `gitnexus-web` `GITNEXUS_UPSTREAM_URL=http://gitnexus-server:4747` and a `GITNEXUS_SERVE_AUTH_TOKEN`; it forwards `/api/*` to the server and ends the browser origin there, so the server's CORS allowlist never sees the public hostnames. The UI asks for the token once. With Traefik, one router for the whole UI is enough:
```yaml
services:
gitnexus-web:
environment:
- GITNEXUS_BACKEND_URL=/
- GITNEXUS_UPSTREAM_URL=http://gitnexus-server:4747
- GITNEXUS_SERVE_AUTH_TOKEN=${GITNEXUS_SERVE_AUTH_TOKEN}
labels:
- traefik.http.routers.gitnexus.rule=Host(`gitnexus.example.com`) || Host(`gitnexus.localhost`)
- traefik.http.services.gitnexus.loadbalancer.server.port=4173
```
Routing `/api/*` straight to `gitnexus serve` on a public hostname is not supported: `serve` has no authentication of its own yet, and it refuses to start with `GITNEXUS_PUBLIC_ORIGIN` set until it does. Reach it through the proxy above.
</details>
Files:
- [Dockerfile.web](../Dockerfile.web) — builds `gitnexus-shared` and `gitnexus-web`, then serves the production frontend.
- [Dockerfile.cli](../Dockerfile.cli) — builds the CLI/server (with its native deps) and runs `gitnexus serve --host 0.0.0.0`. Local embeddings are **not** in the image (`onnxruntime-node` is opt-in; runtime npm is stripped). Bind-mount a prefix or set `GITNEXUS_EMBEDDING_URL`.
- [docker-compose.yaml](../docker-compose.yaml) — starts both signed images side by side.
- [.env.example](../.env.example) — overrides for image names, container names, ports, and the workspace mount.
## Versioning & supply-chain protection (Cosign signatures, provenance, Kubernetes admission policy)
The Docker images are version-locked to the npm package:
- Stable images are **only published from `vX.Y.Z` git tags** (via `docker.yml` triggered directly by the tag push), and the workflow refuses to build unless the tag exactly matches `gitnexus/package.json`'s version. So `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` (and its Docker Hub mirror `akonlabs/gitnexus:1.6.2`) is byte-for-byte the same release as `npm install gitnexus@1.6.2` — no drift, no floating builds from `main`. 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 `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.
Both images are signed with [Cosign keyless signing][cosign-keyless] using the workflow's GitHub OIDC identity, and shipped with build provenance and SBOM attestations. **This is your protection against supply-chain attacks**: even if an attacker republishes a same-named image elsewhere (or somehow pushes to a typo-squatted registry), they cannot forge a Cosign signature tied to `abhigyanpatwari/GitNexus`'s `docker.yml`. Always verify before pulling into sensitive environments.
**Stable releases** — signed from the `v*` tag ref:
```bash
cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
--certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
# Same signature verifies the Docker Hub mirror (identical digest):
cosign verify docker.io/akonlabs/gitnexus:1.6.2 \
--certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
```
The regex pins the certificate identity to this repo's `docker.yml` workflow **run from a `v*` tag** — rejecting unsigned images, images signed by other workflows, and images signed from unprotected refs. It is identical for both 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 `publish.yml` invokes `docker.yml` as a reusable workflow):
```bash
cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
--certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
```
You can also inspect the build provenance and SBOM:
```bash
cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
--predicate-type https://slsa.dev/provenance/v1
```
**Kubernetes: enforce signatures at admission.** Ship the bundled [`ClusterImagePolicy`](../deploy/kubernetes/cluster-image-policy.yaml) so the [Sigstore policy-controller][policy-controller] rejects any GitNexus pod whose image is not signed by this repo's `docker.yml` running from a `vX.Y.Z` tag — the same identity the `cosign verify` snippet above pins.
```bash
# 1. Install the controller (one-time, cluster-wide)
helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update
helm install policy-controller -n cosign-system --create-namespace \
sigstore/policy-controller
# 2. Opt your namespace in
kubectl label namespace <your-ns> policy.sigstore.dev/include=true
# 3. Apply the policy
kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml
```
After this, attempting to deploy an unsigned image — or one signed by anything other than `abhigyanpatwari/GitNexus`'s `docker.yml` at a `v*` tag — fails the admission webhook before a pod is ever created. This turns the verifiable signature into an enforced policy, which is the supply-chain control most clusters actually need.
[cosign-keyless]: https://docs.sigstore.dev/cosign/signing/overview/
[policy-controller]: https://docs.sigstore.dev/policy-controller/overview/
## Run the frontend locally
```bash
git clone https://github.com/abhigyanpatwari/gitnexus.git
cd gitnexus/gitnexus-web && npm install
# Compile sibling gitnexus-shared with this package's TypeScript 7 (do not npm ci shared).
cd ../gitnexus-shared && node ../gitnexus-web/node_modules/typescript/lib/tsc.js
cd ../gitnexus-web && npm run dev
# Then in another terminal, start the backend the frontend connects to:
npx gitnexus@latest serve
```

162
docs/editor-setup.md Normal file
View file

@ -0,0 +1,162 @@
# Editor setup
[Back to GitNexus](../README.md)
## Automatic setup
`gitnexus setup` auto-detects your editors and writes the correct global MCP config. Run it once. To configure only selected integrations, pass `--coding-agent`/`-c` with a comma-separated list, e.g. `gitnexus setup -c cursor,codex`.
| Editor | MCP | Skills | Hooks (auto-augment) | Support |
| ------------------------ | --- | ------ | ----------------------------------------------------------------------------------------------------------------- | ------------ |
| **Claude Code** | Yes | Yes | Yes (PreToolUse + PostToolUse) | **Full** |
| **Cursor** | Yes | Yes | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full** |
| **Antigravity** (Google) | Yes | Yes | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))[¹](#fn-antigravity-hooks) | **Full** |
| **Codex** | Yes | Yes | Yes (PreToolUse + PostToolUse, [Codex hooks](https://developers.openai.com/codex/hooks)) | **Full** |
| **Factory** (Droid) | Yes | Yes | Yes (PostToolUse, [plugin](../gitnexus-factory-plugin/)) | **Full** |
| **OpenCode** | Yes | Yes | — | MCP + Skills |
| **CodeBuddy** (Tencent) | Yes | Yes | — | MCP + Skills |
| **Qoder** (Alibaba) | Yes | Yes | — | MCP + Skills |
| **Windsurf** | Yes | — | — | MCP |
> **Full** means MCP tools + agent skills + hooks that enrich searches with graph context. **Claude Code** and **Codex** go deepest: their PreToolUse hooks enrich the search before it runs, and their PostToolUse hooks also detect a stale index after commits and prompt the agent to reindex. **Cursor**, **Antigravity**, and **Factory** augment from a post-tool hook only, so they enrich the result rather than the query and do not carry the stale-index hint.
<a id="fn-antigravity-hooks"></a>
> ¹ **Antigravity hooks** follow the [Gemini CLI hooks reference](https://geminicli.com/docs/hooks/reference/) (Antigravity 2.0 is the documented successor to Gemini CLI). Augmentation runs in `AfterTool` because `BeforeTool` has no context-injection channel in the Gemini contract — the agent sees graph context appended to the tool result via `hookSpecificOutput.additionalContext`. Stale-index hints land in the same channel after a successful `git commit/merge/rebase/cherry-pick/pull`. The schema may evolve if Antigravity-specific hook docs diverge from Gemini CLI's; the implementation will track those changes.
## Manual MCP configuration (if you prefer not to run gitnexus setup)
**Claude Code** (full support — MCP + skills + hooks):
```bash
# macOS / Linux
claude mcp add gitnexus -- npx -y gitnexus@latest mcp
# Windows
claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp
```
**Codex** (full support — MCP + skills + hooks):
```bash
codex mcp add gitnexus -- npx -y gitnexus@latest mcp
```
Or via `~/.codex/config.toml` (system scope) / `.codex/config.toml` (project scope):
```toml
[mcp_servers.gitnexus]
command = "npx"
args = ["-y", "gitnexus@latest", "mcp"]
```
Codex hooks (PreToolUse graph enrichment + PostToolUse stale-index detection in `~/.codex/hooks.json`, [same schema as Claude Code](https://developers.openai.com/codex/hooks)) need the bundled adapter script, so they are installed by `gitnexus setup -c codex` rather than manually.
Alternatively, install everything as a [Codex plugin](https://developers.openai.com/codex/plugins/build) (MCP + skills + hooks in one step):
```bash
codex plugin marketplace add abhigyanpatwari/GitNexus
# then inside Codex: /plugins → install "GitNexus"
```
> **Codex notes:** SessionStart is intentionally not registered — Codex reads [AGENTS.md natively](https://developers.openai.com/codex/guides/agents-md), which already carries the GitNexus context block. Newly installed hooks need a one-time approval in Codex via `/hooks` before they run. Pick **one** install route (`gitnexus setup -c codex` **or** the plugin): plugin hooks load alongside `~/.codex/hooks.json`, so installing both can fire duplicate hooks per tool call.
**Factory** (Droid) — MCP + skills via `gitnexus setup -c droid`, or add the server manually to `~/.factory/mcp.json` ([user scope](https://docs.factory.ai/cli/configuration/mcp), applies to all projects):
```json
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
```
`gitnexus setup -c droid` also installs skills to `~/.factory/skills/`. For the PostToolUse search-augment hook, install the bundled [`gitnexus-factory-plugin/`](../gitnexus-factory-plugin/) — from a marketplace that includes this repo, run `droid plugin install gitnexus@<marketplace>`, or point Droid at it via `extraKnownMarketplaces` in `.factory/settings.json`. Factory reads [`AGENTS.md` natively](https://docs.factory.ai/), which already carries the GitNexus context block.
**Cursor** (`~/.cursor/mcp.json` — global, works for all projects):
```json
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
```
**Antigravity** (Google) — `~/.gemini/antigravity/mcp_config.json`:
```json
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
```
> `gitnexus setup` also merges an `AfterTool` entry into `~/.gemini/settings.json` (under the canonical [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/)) and installs skills to `~/.gemini/antigravity/skills/`. Existing user hooks are preserved. The hook adapter's path is rewritten at install time, so run `gitnexus setup` rather than hand-editing.
**OpenCode** (`~/.config/opencode/config.json`):
```json
{
"mcp": {
"gitnexus": {
"type": "local",
"command": ["gitnexus", "mcp"]
}
}
}
```
**CodeBuddy** (Tencent) — priority chain, edit the **first non-empty file that exists**: `~/.codebuddy/.mcp.json` (recommended) → `~/.codebuddy/mcp.json` (deprecated) → `~/.codebuddy.json` (legacy). CodeBuddy reads only the first existing file, so adding servers to a higher-priority file than the one currently in use would hide the servers below it. Create `~/.codebuddy/.mcp.json` only if none exist:
```json
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
```
**Qoder** (Alibaba) — `~/.qoder.json`:
```json
{
"mcpServers": {
"gitnexus": {
"command": "npx",
"args": ["-y", "gitnexus@latest", "mcp"]
}
}
}
```
## Install problems? npm 11 crash · slow cold install · no C++ toolchain
> **On npm 11.x?** `npx` can crash during install with `Cannot destructure property 'package' of 'node.target'` (an npm/arborist bug, before GitNexus runs). Use pnpm instead — it builds the native deps explicitly:
>
> ```bash
> pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze
> ```
>
> Or install globally (`npm install -g gitnexus@latest`) and run `gitnexus analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).
> **Fastest MCP startup:** install globally (`npm i -g gitnexus`) before running `gitnexus setup` — this writes an absolute-path MCP config that bypasses `npx` entirely. On a cold cache, an `npx`-based MCP install can exceed Claude Code's `MCP_TIMEOUT` default (~30s).
> **No C++ toolchain?** Vendored grammars use committed prebuilds when one matches the platform. Source-build fallback needs `python3`, `make` and `g++`. Set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before `npm install -g gitnexus` to skip Dart, Proto, Swift, Kotlin and Zig grammar setup. The C grammar remains required. Only the exact value `1` enables this option; it does not skip other native dependencies.
> **Local embeddings are opt-in.** Default `npm install` does not fetch `@huggingface/transformers` or `onnxruntime-node`. Run `gitnexus embeddings install` (or `gitnexus analyze --embeddings`, which auto-heals) to fetch the stack through your npm registry config into `~/.gitnexus/embedding-runtime`. CUDA GPU binaries still use NuGet via `--cuda` ([#2370](https://github.com/abhigyanpatwari/GitNexus/issues/2370)). The prefix needs Node with `module.registerHooks` (≥ 22.15 on 22.x, ≥ 23.5 on 23.x). A leftover 1.6.12 package-first tree is residual until a clean reinstall; `--force` only refreshes prefix overrides.
> **About `tree-sitter-kotlin`:** like Dart/Proto/Swift, Kotlin is a **vendored** grammar (under `gitnexus/vendor/tree-sitter-kotlin`). Upstream ships **source only** (no prebuilt binaries), so GitNexus cross-builds the platform prebuilds itself (via the `build-tree-sitter-prebuilds` GitHub Actions workflow) and vendors them — the same uniform pipeline used for Dart, Proto, and Swift. `node-gyp-build` selects the right `.node` at require time, so **no C/C++ toolchain is needed**. If no prebuild matches your platform-arch, only Kotlin (`.kt`/`.kts`) parsing is unavailable; the rest of `gitnexus` is unaffected.

93
docs/languages/README.md Normal file
View file

@ -0,0 +1,93 @@
# Language Ingestion Gap Inventories
These inventories are the starting point for language-specific plans. There is one
`<language>-ingestion-gaps.md` file for each of the 18 languages in
[SCOPE_RESOLVERS](../../gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts).
Names match provider directories; `jvm` is shared infrastructure, not another language.
Freshly audited on 2026-10-23 with production sources at `c35806d24` and the
accompanying benchmark changes. The [measurement receipt](receiver-resolution-audit.md)
records the commands, exact-target checks, newly executed exclusions and test limits.
The [baseline](../../gitnexus/bench/receiver-resolution/baseline.json) now covers
110 executable cases and 58 explicit N/A declarations. Parsing, imports, visibility,
inheritance and incremental behavior still need separate evidence; these fixed
receiver examples do not establish whole-language, CFG/PDG or rename completeness.
## Inventories
| Language | First planning candidate |
| -------------------------------------------- | ------------------------------------------------------------------------ |
| [C](c-ingestion-gaps.md) | Reproduce header ownership separately from pointer dispatch. |
| [COBOL](cobol-ingestion-gaps.md) | Measure procedure-pointer and structural-call paths separately. |
| [C++](cpp-ingestion-gaps.md) | Substitute explicit template arguments into proven return types. |
| [C#](csharp-ingestion-gaps.md) | Trace typed array receivers and qualified nullable fields. |
| [Dart](dart-ingestion-gaps.md) | Correct awaited-call ownership; trace indexed and generic receivers. |
| [Go](go-ingestion-gaps.md) | Expand ownership coverage beyond the passing receiver matrix. |
| [Java](java-ingestion-gaps.md) | Trace array-element receiver typing. |
| [JavaScript](javascript-ingestion-gaps.md) | Preserve JSDoc container evidence for indexed receivers. |
| [Kotlin](kotlin-ingestion-gaps.md) | Inventory companion and inherited-receiver limits. |
| [Objective-C](objective-c-ingestion-gaps.md) | Add receiver measurements without weakening dynamic-dispatch boundaries. |
| [PHP](php-ingestion-gaps.md) | Retain PHPDoc container types and establish namespace owners. |
| [Python](python-ingestion-gaps.md) | Audit constructor-field and module ownership coverage. |
| [Ruby](ruby-ingestion-gaps.md) | Isolate YARD parameter bindings before adding recall. |
| [Rust](rust-ingestion-gaps.md) | Measure conservative smart-pointer limits before widening them. |
| [Swift](swift-ingestion-gaps.md) | Type indexed receivers, then revalidate historical reports. |
| [TypeScript](typescript-ingestion-gaps.md) | Revalidate deferred narrowing contracts. |
| [Vue](vue-ingestion-gaps.md) | Type indexed receivers in SFC script blocks. |
| [Zig](zig-ingestion-gaps.md) | Add matrix coverage for the delivered receiver forms. |
## Reading the evidence
| Label | Meaning |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Measured gap | A checked-in receiver cell lacks its call edge. Reproduce on the chosen base before fixing it. |
| Recorded gap / boundary | The baseline notes, source contract or dedicated tests describe a limitation; it may be outside the shape matrix. |
| Negative control / deliberate limit | An unresolved result protects precision. Do not make it resolve without new evidence of the exact target. |
| Coverage gap / audit | A measurement is absent or coverage needs inventory. This does not establish a product bug. |
| Historical reports | Older claims still need current positive and negative reproductions. |
The receiver harness has separate states:
- **RESOLVES:** the terminal call reaches its full expected declaration ID, with no same-named edge to a different owner. This proves only the supplied fixture.
- **WRONG-TARGET:** at least one same-named call reaches another declaration, including any guessed edge from an untyped control.
- **VISIBLE-GAP:** no matching edge, with a recorded receiver-unresolved drop. Some cells intentionally represent untyped negative controls.
- **INVISIBLE-GAP:** neither the edge nor the receiver drop is recorded; drop counts cannot reveal this loss.
- **N/A:** the harness declares this spelling inapplicable to its measurement. Read its reason before interpreting language support.
- **GRAMMAR-UNAVAILABLE:** the parser did not load. No behavior was measured; this is not a product-gap verdict.
An all-N/A row (C or COBOL) does not mean complete ingestion. Vue now has an executable SFC row. Zig and
Objective-C have dedicated tests but no row in this shape arm. A fully resolving
row also proves only its fixed examples. The baseline's count arm includes
external and unknown receivers, so total drops are not an actionable bug count.
## Turning an inventory into a plan
1. Select a stable gap ID and pin the implementation base. Record a minimal source
example, expected full target identity, observed edge/drop and relevant tests.
2. Add a meaningful negative: a same-name decoy, unknown type, shadowed import or
ambiguous owner. Keep intentional untyped controls unresolved.
3. Locate the missing fact: parsing/capture, type extraction, declaration ownership,
import binding, receiver folding or dispatch. Keep language rules in providers
and shared resolution algorithms language-agnostic.
4. Write the plan under `docs/plans/`, linking back to the gap ID. Define the smallest
contract change, affected tests and corpus/benchmark comparisons. Follow the
repository's impact-analysis and pre-commit change-analysis requirements.
5. Run focused regressions and the receiver check before updating expectations.
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) documents build
and cache requirements. Record grammar skips and measurement limits explicitly.
6. Update the inventory with the merged PR, verified source revision and evidence.
Close the specific item without marking the whole language complete.
Keep historical reports separate from measured gaps. When adding a registered
language, add its inventory here; when refreshing a snapshot, update its source pin
and explain intended baseline changes. Do not copy old green results as fresh runs.
## Related documentation
- [Receiver measurement audit](receiver-resolution-audit.md): fresh results and corrected classifications.
- [Type Resolution System](../../type-resolution-system.md): active layers and lifecycle.
- [Type Resolution Roadmap](../../type-resolution-roadmap.md): planned work and acceptance criteria.
- [Architecture](../../ARCHITECTURE.md#scope-resolution-pipeline-rfc-909-ring-3): provider contract and shared pipeline.
- [Objective-C provider guide](objective-c-provider.md): supported static behavior and runtime limits.
- [Local import scoping](local-import-scoping.md) and [Jupyter notebooks](jupyter-notebook.md).

View file

@ -0,0 +1,47 @@
# C Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | -------------------------------------------------------------------------------------------------- |
| `plainChain` | N/A | C has no method call on a returned value; dispatch is through struct function-pointer fields only. |
| `plainDeepChain` | N/A | `u->address->save()`: dispatch through a function-pointer field has no static callee in the graph. |
| `optionalChain` | N/A | C has no optional-chaining operator. |
| `nonNullAssert` | N/A | C has no non-null assertion operator. |
| `awaitParen` | N/A | C has no await expression. |
| `explicitTypeArgs` | N/A | C has no generics. |
| `indexElement` | N/A | `repos[0].save()`: dispatch through a function-pointer field has no static callee in the graph. |
| `fieldReceiverCall` | N/A | `u->save()`: dispatch through a function-pointer field has no static callee in the graph. |
| `decoratedReceiverBase` | N/A | C has no method receiver, so there is no receiver decoration. |
| `decoratedFieldType` | N/A | A C struct field is a function pointer, not a typed receiver whose decoration could be stripped. |
All receiver-shape cells are N/A. The benchmark calls through function-pointer fields with no static callee node; moving the structs into `main.c` did not create a named dispatch target. This does not measure ordinary C calls or establish complete C ingestion.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ---- | ------------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C-01 | Recorded gap | The baseline reports C structs in `.h` files being owned by the C++ provider. | Reproduce with a C translation unit and header, then define ownership using source context. Preserve C++ and Objective-C header classification controls. |
| C-02 | Coverage gap | The all-N/A receiver row does not exercise direct calls, linkage or header imports. | Add language-appropriate cases with exact targets and duplicate static names across files. Specify a callable-value target contract before attempting function-pointer field dispatch. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/c/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/c/scope-resolver.ts).
- [c-coverage.test.ts](../../gitnexus/test/integration/resolvers/c-coverage.test.ts).
- [c-header-scan.test.ts](../../gitnexus/test/unit/scope-resolution/c/c-header-scan.test.ts).
- [c-static-linkage-side-channel.test.ts](../../gitnexus/test/unit/c-static-linkage-side-channel.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,47 @@
# COBOL Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plainChain` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `plainDeepChain` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `optionalChain` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `nonNullAssert` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `awaitParen` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `explicitTypeArgs` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `indexElement` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `fieldReceiverCall` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `decoratedReceiverBase` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
| `decoratedFieldType` | N/A | The COBOL provider models structural/procedure-pointer calls, not object-oriented receiver chains; those calls have separate integration coverage. |
The receiver benchmark marks COBOL N/A because its emitter has no method-call receiver chains. The registered resolver uses `scopeResolutionEdgeMode: callable-flow-only`: it contributes procedure-pointer CALLS while the established COBOL processor owns structural CALLS and IMPORTS.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| -------- | -------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| COBOL-01 | Coverage gap | OO receiver shapes do not measure COBOL call resolution. | Inventory direct CALL, procedure-pointer, PERFORM and COPY cases against the existing suites; add a measurement only where coverage is missing. |
| COBOL-02 | Boundary audit | Structural and callable-flow edges have separate production owners. | Compare exact target identities, qualified data names and duplicate program names. Assert neither path introduces duplicate or unjustified call edges. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/cobol/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/cobol/scope-resolver.ts).
- [cobol-scope.test.ts](../../gitnexus/test/integration/resolvers/cobol-scope.test.ts).
- [cobol-parsing-coverage.test.ts](../../gitnexus/test/integration/resolvers/cobol-parsing-coverage.test.ts).
- [cobol-pipeline-benchmark.test.ts](../../gitnexus/test/integration/cobol-pipeline-benchmark.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,50 @@
# C++ Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------- |
| `pointerArrowChain` | RESOLVES | `svc->getUser()->save();` |
| `valueDotChain` | RESOLVES | `svc2.getUser()->save();` |
| `plainChain` | RESOLVES | `svc->getUser()->save();` |
| `plainDeepChain` | RESOLVES | `svc->getUser()->addr.save();` |
| `optionalChain` | N/A | C++ has no optional-chaining operator. |
| `nonNullAssert` | N/A | C++ has no non-null assertion operator. |
| `awaitParen` | VISIBLE-GAP | `(co_await getUserAsync()).save();` |
| `explicitTypeArgs` | VISIBLE-GAP | `svc->getTyped<User>()->save();` |
| `indexElement` | RESOLVES | `repos[0].save();` |
| `fieldReceiverCall` | RESOLVES | `this->repo.save();` |
| `decoratedReceiverBase` | N/A | C++ `this` is implicitly a pointer with no written decoration; the pointer base is measured by pointerArrowChain. |
| `decoratedFieldType` | RESOLVES | `this->repo->save();` |
The canonical `plainChain` now executes `svc->getUser()->save()` and resolves to `User.save`; the separate pointer-arrow and value-dot controls also resolve. The old N/A meant duplicate coverage, not a failed plain chain. Deep-chain, indexed and field-receiver cases also reach their exact expected owners. `explicitTypeArgs` remains a visible gap: reading `getTyped<User>()` does not generally substitute its declared return type `T` with `User`.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------ | -------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CPP-01 | Measured gap | `explicitTypeArgs` has no call edge and records a receiver drop. | Tie substitutions to the selected declaration and explicit arguments. Test exact owners, ambiguous overloads and unknown mappings; preserve conversion-only suppression. |
| CPP-02 | Boundary audit | Qualified factories, aliases and headers have dedicated regression suites beyond this matrix. | Retain namespace and alias ownership checks while extending templates. Evaluate header classification jointly with C rather than treating the C all-N/A row as success. |
| CPP-03 | Measured gap | `(co_await getUserAsync()).save()` is VISIBLE-GAP despite an awaiter declaring `User await_resume()`. | Trace coroutine result typing; require User.save and retain an unknown awaiter negative. The minimal C++20 probe passed a compiler syntax check. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/cpp/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts).
- [cpp-qualified-template-review.test.ts](../../gitnexus/test/integration/cpp-qualified-template-review.test.ts).
- [cpp-qualified-factory-review.test.ts](../../gitnexus/test/integration/cpp-qualified-factory-review.test.ts).
- [cpp-qualified-receiver-boundaries.test.ts](../../gitnexus/test/integration/cpp-qualified-receiver-boundaries.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,47 @@
# C# Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ------------------------------------- |
| `plainChain` | RESOLVES | `svc.GetUser().Save();` |
| `plainDeepChain` | RESOLVES | `svc.GetUser().Address.Save();` |
| `optionalChain` | RESOLVES | `svc?.GetUser().Save();` |
| `nonNullAssert` | RESOLVES | `svc!.GetUser().Save();` |
| `awaitParen` | RESOLVES | `(await svc.GetUserAsync()).Save();` |
| `explicitTypeArgs` | RESOLVES | `svc.GetTyped<User>().Save();` |
| `indexElement` | VISIBLE-GAP | `repos[0].Save();` |
| `fieldReceiverCall` | RESOLVES | `this.repo.Save();` |
| `decoratedReceiverBase` | N/A | C# `this` carries no type decoration. |
| `decoratedFieldType` | RESOLVES | `this.repo.Save();` |
The matrix resolves local nullable fields and the tested chain wrappers. It still loses `repos[0].Save()` with a `User[]` parameter. The resolver already registers an `elementTypeOf` hook, so this gap needs a full capture-to-resolution trace, not an assumption that the hook is absent.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| --------- | ------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CSHARP-01 | Measured gap | `indexElement` remains VISIBLE-GAP for a typed array. | Locate the lost array/type-owner evidence, then assert the exact User.Save target with a same-name decoy and an untyped/unsupported negative. |
| CSHARP-02 | Documented boundary | Qualified nullable fields, including `Custom.List<User>?`, are refused until their written owner can be proven. | Establish namespace-aware ownership before adding support. Keep wrapper types distinct from element types and preserve external and workspace-tail collision negatives. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/csharp/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/csharp/scope-resolver.ts).
- [csharp-nullable-field-isolated-ownership.test.ts](../../gitnexus/test/integration/csharp-nullable-field-isolated-ownership.test.ts).
- [csharp-nullable-field-generic-arguments.test.ts](../../gitnexus/test/integration/csharp-nullable-field-generic-arguments.test.ts).
- [csharp-namespace-precedence-boundaries.test.ts](../../gitnexus/test/integration/csharp-namespace-precedence-boundaries.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,53 @@
# Dart Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | --------------------------------------- |
| `plainChain` | RESOLVES | `svc.getUser().save();` |
| `plainDeepChain` | RESOLVES | `svc.getUser().address.save();` |
| `optionalChain` | RESOLVES | `svc.getUser().address?.save();` |
| `nonNullAssert` | VISIBLE-GAP | `svc.getUser().address!.save();` |
| `awaitParen` | WRONG-TARGET | `(await svc.getUserAsync()).save();` |
| `explicitTypeArgs` | VISIBLE-GAP | `svc.getTyped<User>().save();` |
| `indexElement` | INVISIBLE-GAP | `repos[0].save();` |
| `fieldReceiverCall` | RESOLVES | `this.repo.save();` |
| `decoratedReceiverBase` | N/A | Dart `this` carries no type decoration. |
| `decoratedFieldType` | RESOLVES | `this.repo?.save();` |
Typed plain, deep, optional and field chains resolve. The awaited case is WRONG-TARGET: `getUserAsync()` declares `Future<User>`, but the call reaches `Address.save` instead of `User.save`. The previous member-name-only gate incorrectly labeled this RESOLVES. The failing assertion spelling is `svc.getUser().address!.save()`; indexed access uses `List<User> repos`. The recorded statuses identify missing behavior but do not by themselves establish a root cause.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------- | --------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DART-01 | Measured gap | `indexElement` is INVISIBLE-GAP: neither a call edge nor a receiver drop is recorded. | Trace reference-site capture, chain extraction and element typing separately. Add both a diagnostic assertion and an exact target assertion before selecting the implementation slice. |
| DART-02 | Measured gap | `nonNullAssert` is VISIBLE-GAP. | Trace the postfix assertion through the typed field chain. Preserve working optional access and nullable-field controls; track awaited-call ownership separately in DART-04. |
| DART-03 | Recorded boundary | Callable-return/tear-off invocation is a separate roadmap follow-up. | Create a positive case for the primary tear-off expression and an ambiguous callable negative; fixture-local direct calls alone do not prove support. |
| DART-04 | Measured wrong target | `(await svc.getUserAsync()).save()` reaches Address.save instead of User.save. | Trace awaited return ownership before increasing recall. Assert the full User.save ID and reject the Address.save decoy; the baseline now exposes this precision defect. |
| DART-05 | Measured gap | `svc.getTyped<User>().save()` is VISIBLE-GAP even when getTyped declares a concrete User return. | Trace explicit type-argument call capture and receiver folding. This fixture tests the call spelling, not substitution of a generic return type. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/dart/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/dart/scope-resolver.ts).
- [dart-coverage.test.ts](../../gitnexus/test/integration/resolvers/dart-coverage.test.ts).
- [dart.test.ts](../../gitnexus/test/integration/resolvers/dart.test.ts).
- [dart-type-extractor.test.ts](../../gitnexus/test/unit/dart-type-extractor.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).
Dart permits explicit method type arguments; inference does not make this shape N/A.
See the [Dart type-system reference](https://dart.dev/language/type-system#type-argument-inference).

View file

@ -0,0 +1,46 @@
# Go Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `plainChain` | RESOLVES | `svc.GetUser().Save()` |
| `plainDeepChain` | RESOLVES | `svc.GetUser().Address.Save()` |
| `optionalChain` | N/A | Go has no optional-chaining operator. |
| `nonNullAssert` | N/A | Go has no non-null assertion operator. |
| `awaitParen` | N/A | Go has no await expression; concurrency is channel-based. |
| `explicitTypeArgs` | N/A | Go methods cannot declare type parameters, so there is no call-site type-argument spelling on a method. |
| `indexElement` | RESOLVES | `repos[0].Save()` |
| `fieldReceiverCall` | RESOLVES | `h.f.ValM()` |
| `decoratedReceiverBase` | RESOLVES | `h.f.ValM()` |
| `decoratedFieldType` | RESOLVES | `h.f.PtrM()` |
Every applicable cell in the checked-in row resolves, including slice indexing and decorated receiver/field types. This is a bounded receiver snapshot, not proof that every package, build variant or import-qualified spelling resolves.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ----- | -------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GO-01 | Coverage audit | No failing shape is recorded in this row; package ownership is exercised by separate tests. | Map those tests to package-qualified receivers, cross-file struct ownership and build variants. Add missing exact-owner cases before proposing a fix; independent modules with matching type names must remain isolated. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/go/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/go/scope-resolver.ts).
- [go-build-variant-owners.test.ts](../../gitnexus/test/integration/go-build-variant-owners.test.ts).
- [go-cross-file-struct-owner.test.ts](../../gitnexus/test/integration/go-cross-file-struct-owner.test.ts).
- [go-external-test-package.test.ts](../../gitnexus/test/integration/resolvers/go-external-test-package.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,47 @@
# Java Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plainChain` | RESOLVES | `svc.getUser().save();` |
| `plainDeepChain` | RESOLVES | `svc.getUser().address.save();` |
| `optionalChain` | N/A | Java has no optional-chaining operator. |
| `nonNullAssert` | N/A | Java has no non-null assertion operator. |
| `awaitParen` | N/A | Java has no await expression in the core language. |
| `explicitTypeArgs` | RESOLVES | `svc.<User>getTyped().save();` |
| `indexElement` | VISIBLE-GAP | `repos[0].save();` |
| `fieldReceiverCall` | RESOLVES | `this.repo.save();` |
| `decoratedReceiverBase` | N/A | Java `this` carries no type decoration. |
| `decoratedFieldType` | N/A | Java's only field-type decorations are containers (arrays, generics), which change the member set and are measured by indexElement rather than by a type-preserving strip. |
The matrix resolves plain/deep chains, explicit type arguments and field receivers. `repos[0].save()` with a `User[]` parameter is a visible gap. The explicit-type-argument fixture declares a concrete User return regardless of its type parameter. Its exact target passes, but it does not prove generic return substitution.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------- | -------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| JAVA-01 | Measured gap | `indexElement` has no call edge and records a receiver drop. | Trace the array annotation through type bindings and receiver folding. Assert the exact User.save declaration and retain ambiguous/import-shadowed negatives. |
| JAVA-02 | Coverage audit | Receiver aliases and local types have separate regression coverage. | Include those ownership boundaries in the array plan; document any classpath/source-root assumptions instead of inferring compiler-grade lookup from a passing cell. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/java/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/java/scope-resolver.ts).
- [java-receiver-alias-boundaries-review.test.ts](../../gitnexus/test/integration/java-receiver-alias-boundaries-review.test.ts).
- [java-javac-local-types.test.ts](../../gitnexus/test/integration/resolvers/java-javac-local-types.test.ts).
- [java.test.ts](../../gitnexus/test/integration/resolvers/java.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,48 @@
# JavaScript Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ----------------------------------------------------------------------------- |
| `plainChain` | RESOLVES | `svc.getUser().save();` |
| `untypedChain` | VISIBLE-GAP | `svc.getUser().save();` (intentional untyped control) |
| `plainDeepChain` | RESOLVES | `svc.getUser().address.save();` |
| `optionalChain` | RESOLVES | `svc?.getUser().save();` |
| `nonNullAssert` | N/A | JavaScript has no non-null assertion operator. |
| `awaitParen` | RESOLVES | `(await svc.getUserAsync()).save();` |
| `explicitTypeArgs` | N/A | JavaScript has no type-argument syntax. |
| `indexElement` | VISIBLE-GAP | `repos[0].save();` |
| `fieldReceiverCall` | RESOLVES | `this.repo.save();` |
| `decoratedReceiverBase` | N/A | JavaScript method receivers carry no type decoration. |
| `decoratedFieldType` | N/A | JavaScript fields carry no declared type, so there is no decoration to strip. |
JSDoc supplies the types in the passing plain, deep, optional and awaited chains. `indexElement` remains a visible gap with `@param {User[]} repos`; JavaScript has no `ScopeResolver.elementTypeOf` hook. `untypedChain` is an intentional negative control, not a request to guess a target from its method name.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------------- | ---------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| JAVASCRIPT-01 | Measured gap | A typed array does not establish the receiver type for `repos[0].save()`. | Preserve the container/element distinction and add a provider-owned element route. Require the exact User.save target, a same-name decoy and unsupported-container negatives. |
| JAVASCRIPT-02 | Negative control | `untypedChain` remains VISIBLE-GAP by design. | Keep the untyped receiver unresolved while adding typed coverage; resolving a same-named method elsewhere is a precision regression. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/javascript/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/javascript/scope-resolver.ts).
- [javascript.test.ts](../../gitnexus/test/integration/resolvers/javascript.test.ts).
- [javascript-object-properties.test.ts](../../gitnexus/test/integration/resolvers/javascript-object-properties.test.ts).
- [javascript-captures.test.ts](../../gitnexus/test/unit/scope-resolution/javascript/javascript-captures.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,47 @@
# Kotlin Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ----------------------------------------- |
| `plainChain` | RESOLVES | `svc.getUser().save()` |
| `plainDeepChain` | RESOLVES | `svc.getUser().address.save()` |
| `optionalChain` | RESOLVES | `svc?.getUser()?.save()` |
| `nonNullAssert` | RESOLVES | `svc!!.getUser().save()` |
| `awaitParen` | RESOLVES | `(svc.getUserAsync()).save()` |
| `explicitTypeArgs` | RESOLVES | `svc.getTyped<User>().save()` |
| `indexElement` | RESOLVES | `repos[0].save()` |
| `fieldReceiverCall` | RESOLVES | `this.repo.save()` |
| `decoratedReceiverBase` | N/A | Kotlin `this` carries no type decoration. |
| `decoratedFieldType` | RESOLVES | `this.repo?.save()` |
Every applicable shape in this row resolves. Separate qualified-factory controls retain conservative ownership boundaries: inherited receivers need re-established bases and canonical MRO evidence; companion fallback requires captured proof that the companion header has no supertype. This is not a complete build-system classpath model.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| --------- | ------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| KOTLIN-01 | Documented boundary | Complete companion inheritance is outside the delivered factory fallback. | Reproduce a bounded inherited-companion case before extending it. Keep unknown bases and shadowed factories unresolved and preserve worker/cache ownership evidence. |
| KOTLIN-02 | Coverage audit | The passing matrix does not measure every package-qualified factory spelling. | Retain the identifier, implicit-receiver and shadow-boundary suites; identify a concrete missing case before proposing broader inference. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/kotlin/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/kotlin/scope-resolver.ts).
- [kotlin-qualified-factory-implicit-receivers.test.ts](../../gitnexus/test/integration/kotlin-qualified-factory-implicit-receivers.test.ts).
- [kotlin-qualified-factory-type-ownership.test.ts](../../gitnexus/test/integration/kotlin-qualified-factory-type-ownership.test.ts).
- [kotlin-qualified-factory-identifier-review.test.ts](../../gitnexus/test/integration/kotlin-qualified-factory-identifier-review.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -18,13 +18,21 @@ Calls, constructors, receiver/type inference, inheritance, namespace lookup, and
fallback consumers use these ownership facts rather than independently choosing a
same-named symbol.
Ownership and inferred type facts are separate. For providers that mark their
name claims complete, an `assignment-inferred` or `constructor-inferred` fact
does not declare a name. Lookup continues to the actual declaration, import, or
shadowing barrier. Providers without complete claims retain their existing
ownership rules.
The [shared records](../../gitnexus-shared/src/scope-resolution/types.ts) carry
ownership, activation positions, directive destinations, and lookup purpose as
serializable data. They retain declaration identity and ambiguity; they contain
no AST nodes or callbacks. `declaredAtScope` describes ownership, while
`runsOnlyWhenCalled` describes deferred execution. A function-local Rust `use` or
C `#include` is not deferred merely because of its position; Python and Ruby
loading can be. The
no AST nodes or callbacks. For imports, `declaredAtScope` records lexical location
independently of `runsOnlyWhenCalled`, which describes deferred execution. On a
`TypeRef`, `declaredAtScope` anchors type-name lookup where the annotation or
inference was written; it can differ from the binding's owner. A function-local
Rust `use` or C `#include` is not deferred merely because of its position; Python
and Ruby loading can be. The
[function-local import chain tests](../../gitnexus/test/unit/scope-resolution/function-local-import-chain.test.ts)
pin that distinction.
@ -88,6 +96,104 @@ namespace aliases. Computed specifiers, indirect loader/Promise chains, and
unsupported destructuring remain unresolved; see the
[loader regressions](../../gitnexus/test/unit/scope-resolution/typescript/local-loader-imports.test.ts).
#### Receiver type precedence
A constructor assignment inside a closure does not make that closure the owner
of the assigned name. Lookup may retain the nearest constructor fact on its path
to the owner when the owner has no type fact or only an inferred or propagated
fact. It keeps the complete selected `TypeRef`, including the scope, position,
and namespace in which its type name must resolve.
The owner's annotation, parameter annotation, return annotation, `self`, or
decorator fact takes precedence. For example, assigning `new Foo()` to a
parameter annotated `Base` inside a closure leaves receiver lookup anchored to
`Base`, including its inherited methods. Same-scope precedence and
`METHOD_OVERRIDES` relationships retain their existing rules. A nested write is
not promoted into an unconditional type fact for reads outside that closure.
These are static inference rules, not control-flow narrowing or a prediction of
the receiver's runtime class. The
[type ownership regressions](../../gitnexus/test/unit/scope-resolution/typescript/lexical-type-ownership.test.ts)
and [shared lookup regressions](../../gitnexus/test/unit/scope-resolution/lexical-name-claims.test.ts)
cover declaration ownership, fact precedence, and retained lookup anchors.
#### HTTP provenance
Express route receivers and fetch-wrapper analysis share
[per-file lexical bindings](../../gitnexus/src/core/ingestion/route-extractors/lexical-bindings.ts).
They track declaration identity across closures and check identity at each use;
an unrelated same-named declaration in a sibling scope does not invalidate a
binding. Writes to the tracked binding do invalidate its provenance. For a
forwarded Express parameter, an initialized `var` redeclaration or a body
function declaration is a write, while an uninitialized `var` declaration alone
preserves the parameter value. See the
[route provenance regressions](../../gitnexus/test/unit/framework-route-provenance.test.ts).
Automatic fetch-wrapper detection requires evidence of platform fetch. Bare
`fetch` must be unshadowed; `globalThis.fetch`, `window.fetch`, and `self.fetch`
require an unshadowed global root. Unresolved or blocked local names are not
globals. An injected `fetch` parameter alone is not evidence. A default such as
`fetch = globalThis.fetch` supplies potential platform evidence, not a guarantee
that callers use that default. A self-referential
`fetch = fetch` default or a locally shadowed `globalThis` does not supply it.
Stable aliases retain this provenance by binding identity.
Nested callable bodies contribute only when reachable from the function's
evaluated code through resolved binding references. Unused self-recursive or
mutually recursive helpers do not prove a wrapper. IIFEs, inline callbacks, and
directly escaping anonymous functions participate; a named stored helper needs
a reachable reference. Class heritage, computed keys, static fields, and static
blocks participate during class evaluation. Methods and instance fields remain
deferred until the class binding is referenced from reachable code. This is a
conservative approximation of potential execution: reading or returning a
function does not execute its body, and referencing a class does not establish
that every method runs. The
[wrapper provenance cases](../../gitnexus/test/unit/fetch-wrapper-provenance.test.ts)
cover these boundaries.
Bare wrapper calls and forwarded calls resolve declaration or import identity
before using name fallback. Relative imports, renamed imports, tsconfig aliases,
and workspace imports use the project module resolver. A known local
non-wrapper, a different resolved target, or an ambiguous target blocks fallback.
An unresolved name can fall back only when exactly one distinct definition can
be the target, including non-wrappers, and that definition is a proven wrapper.
For an import the resolver cannot follow, the candidates are module-level
functions exported under the imported name; for an undeclared global, they are
top-level functions of that name. Nested and unexported helpers are never
candidates. This fallback is an analyzer recovery heuristic; it does not prove
lexical identity. A function whose binding is reassigned in its file, including
through `export { request as send }; request = other;` or a later
`var request = …` initializer, proves no wrapper in importing files either. Explicit `fetchWrappers` configuration takes precedence
over automatic inference, including for names shadowed by local parameters; member
calls retain their existing matching rules. See the
[wrapper consumer integration tests](../../gitnexus/test/integration/resolvers/fetch-wrapper-consumers.test.ts)
and [configured wrapper tests](../../gitnexus/test/integration/resolvers/configurable-fetch-wrapper.test.ts).
The scope model does not represent separate parameter and body environments.
When formals contain expressions, including nested defaults or computed pattern
keys, HTTP inference therefore declines an affected binding if a body `var` or
function declaration shares a parameter's name or a binding referenced by a
parameter expression. Declarations inside nested functions do not count as outer
body declarations; a rest parameter alone is not a parameter expression. The
[lexical binding tests](../../gitnexus/test/unit/route-lexical-bindings.test.ts)
pin this conservative boundary. If scope extraction fails, scope-dependent HTTP
facts are omitted and the existing scope-extraction failure remains visible;
unrelated structural extraction continues. A failing HTTP hook drops only that
file's HTTP facts. Either way the file's function names are still recorded, so
name fallback elsewhere declines instead of treating another definition as
unique.
Barrels follow ECMAScript `ResolveExport`. A local or named export shadows
`export *`, star exports never carry `default`, and a name that two star-exported
modules export as different bindings is ambiguous, whether or not either is a
wrapper. Two export names of one declaration are one binding.
Some recall is given up deliberately. A helper that conditionally rebinds its
parameter, as in `if (!app) { var app = express(); }`, loses that parameter's
provenance: the initialized `var` is a write. A dynamic-import shim such as
`(...args) => import('node-fetch').then(...)` is not platform fetch evidence. A
write to the URL parameter clears URL forwarding. Calls inside recovered syntax
are still resolved, but nothing else inside an `ERROR` node is trusted.
Vue's explicit JS/JSX script requires an additional bounded semantic parse because
the worker's structural tree uses TypeScript. That parse runs inside the real
worker. The [parity test](../../gitnexus/test/integration/local-import-worker-parity.test.ts)
@ -148,17 +254,29 @@ exact call-site positions are missing.
## Cache migration and verification evidence
[Parse-cache schema 136](../../gitnexus/src/storage/parse-cache.ts) replaces 133,
134, and 135. It invalidates overly broad Python/TS/JS binding barriers,
incorrect parameter-annotation lookup ownership, and embedded Vue grammar and
source positions. The same version gate applies to the
[durable ParsedFile store](../../gitnexus/src/storage/parsedfile-store.ts).
Incompatible records are rejected and rebuilt on the next analysis; unchanged
records can then be reused. The
[schema regression](../../gitnexus/test/unit/incremental-parse-cache.test.ts)
explicitly rejects valid schema-133, schema-134, and schema-135 records in both stores.
PDG-mode chunk keys also advance to `pdg:6`, so embedded-script CFGs with
incorrect call anchors are rebuilt before the resolved-callee join.
Parser compatibility uses
[automatic artifact-derived identities](../../MIGRATION.md#automatic-parser-cache-identities),
not manually assigned semantic counters. The
[worker-result cache](../../gitnexus/src/storage/parse-cache.ts) and
[durable ParsedFile store](../../gitnexus/src/storage/parsedfile-store.ts)
validate the same base identity and include it in their chunk keys. PDG-enabled
chunks also include the PDG identity and resolved function-line cap. Legacy
numeric, missing, malformed, or foreign identities cause a cache miss and rebuild;
compatible records remain eligible for reuse. If identity verification fails,
analysis uses a transient store without persistent cache reads or writes.
Parser contributors update no counter or generated digest. The
[identity tests](../../gitnexus/test/unit/parse-cache-identity.test.ts),
[input-coverage tests](../../gitnexus/test/unit/parse-cache-input-coverage.test.ts),
and [lifecycle tests](../../gitnexus/test/integration/parse-cache-identity-lifecycle.test.ts)
cover the compatibility gates. Source changes invalidate identity immediately,
but compiled workers still need `npm run build` in `gitnexus/` before verification.
Cached wrapper import facts retain raw specifiers and imported names. Each
analysis resolves them against the current project configuration, including on
warm runs, so a changed tsconfig alias does not retain a stale wrapper target.
The [wrapper persistence tests](../../gitnexus/test/integration/resolvers/fetch-wrapper-persistence.test.ts)
cover raw cache transport, warm reuse, and alias changes.
The [real-worker parity suite](../../gitnexus/test/integration/local-import-worker-parity.test.ts)
witnesses worker boot, dispatch, and returned ParsedFiles, then compares complete
@ -179,13 +297,10 @@ ensures each is selected exactly once across the four Windows/macOS shards.
Ubuntu's full suite discovers the tests normally. These are focused evidence
boundaries, not a statement that the final full suite or every platform has passed.
## Relationship to main and issue #3499
## Related Python ownership behavior
The integrated main baseline `50aa4be3` already includes #3502's nested Python
declaration ownership fix for the original #3499 case and #3504's aliased package
re-export fix. Their [Python integration coverage](../../gitnexus/test/integration/resolvers/python.test.ts)
The nested declaration ownership fix in #3502 for the original #3499 case and
the aliased package re-export fix in #3504 remain part of Python's provider rules.
Their [Python integration coverage](../../gitnexus/test/integration/resolvers/python.test.ts)
and [module namespace coverage](../../gitnexus/test/unit/scope-resolution/python/python-module-namespace-construction.test.ts)
remain relevant. This branch extends that base with the lexical claims, provider
semantics, and persistence evidence described above. Issue coverage is **Related
#3499**; this document does not assert that all dynamic Python behavior is solved
or make an issue-status claim.
remain relevant. Lexical ownership does not model all dynamic Python behavior.

View file

@ -0,0 +1,44 @@
# Objective-C Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
No row exists in the checked-in receiver shape arm. Add a measurement contract before comparing this language with measured rows.
Objective-C is registered but has no row in this receiver benchmark. Its dedicated [provider guide](objective-c-provider.md#current-implementation-coverage) documents implemented static message sends, selectors, imports, categories and incremental checks. Runtime dispatch remains deliberately conservative.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| -------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OBJECTIVE-C-01 | Coverage gap | No shape-arm measurements exist for Objective-C. | Define message-send cases for typed locals, self/super, class methods and protocol receivers. Assert full selectors and owners; include category collisions and unknown id receivers as negatives. |
| OBJECTIVE-C-02 | Documented boundary | Objective-C++ `.mm` uses the Objective-C grammar path; deep C++ semantics are outside the MVP. | Inventory a minimal mixed-language example before choosing a provider contract. Preserve shared `.h` classification and incremental/full-rebuild parity. |
| OBJECTIVE-C-03 | Deliberate limit | Swizzling, dynamic selectors, arbitrary macro expansion and id-flow inference are not resolved as certain calls. | Keep unresolved/candidate evidence explicit. Any future slice needs a statically justified target rather than a guessed runtime winner. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/objective-c/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/objective-c/scope-resolver.ts).
- [objective-c-provider.test.ts](../../gitnexus/test/integration/objective-c-provider.test.ts).
- [objective-c-provider.test.ts](../../gitnexus/test/unit/objective-c-provider.test.ts).
- [objective-c-pipeline-benchmark.test.ts](../../gitnexus/test/integration/objective-c-pipeline-benchmark.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).
## Additional validation
The focused provider suite passed its static ingestion checks. One persisted
query/context and incremental-versus-force test timed out at 180 seconds in the
combined run and passed on an isolated retry, as recorded in the audit receipt. This
is separate from the absent receiver shape row.

View file

@ -0,0 +1,50 @@
# PHP Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ------------------------------------------------------------ |
| `arrowCallChain` | VISIBLE-GAP | `$svc->getUser()->save();` (intentional untyped control) |
| `arrowPropertyPath` | RESOLVES | `$this->repo->save();` |
| `plainChain` | RESOLVES | `$svc->getUserTyped()->save();` |
| `plainDeepChain` | RESOLVES | `$svc->getUserTyped()->address->save();` |
| `optionalChain` | RESOLVES | `$svc?->getUserTyped()->save();` |
| `nonNullAssert` | N/A | PHP has no non-null assertion operator. |
| `awaitParen` | N/A | PHP has no await expression in the core language. |
| `explicitTypeArgs` | N/A | PHP has no generic type-argument syntax at a call site. |
| `indexElement` | VISIBLE-GAP | `$repos[0]->save();` |
| `fieldReceiverCall` | RESOLVES | `$this->repo->save();` |
| `decoratedReceiverBase` | N/A | PHP `$this` carries no type decoration on a method receiver. |
| `decoratedFieldType` | RESOLVES | `$this->repo->save();` |
Typed return annotations make the plain/deep/nullsafe chains resolve. `indexElement` stays visible: PHPDoc `User[]` is normalized to `User`, losing container evidence, and PHP has no `elementTypeOf` hook. `arrowCallChain` deliberately calls an unannotated producer and remains a negative control.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PHP-01 | Measured gap | `$repos[0]->save()` cannot use the PHPDoc element type. | Preserve both the container and its element type, then add provider-owned element resolution. Check the exact target plus untyped arrays and same-name decoys. |
| PHP-02 | Documented boundary | Functions in multi-namespace files remain ambiguity evidence but are refused as qualified call targets, function imports and factory producers while ownership is unproven. | Capture declaration-local namespace ownership before increasing recall. Preserve single-namespace positives and cross-namespace collision negatives. |
| PHP-03 | Negative control | `arrowCallChain` is VISIBLE-GAP for an unannotated return. | Keep this control unresolved; a member-name match is not evidence of a receiver type. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/php/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/php/scope-resolver.ts).
- [php-qualified-factory-review.test.ts](../../gitnexus/test/integration/php-qualified-factory-review.test.ts).
- [php-coverage.test.ts](../../gitnexus/test/integration/resolvers/php-coverage.test.ts).
- [php-scope-capture-tripwire.test.ts](../../gitnexus/test/integration/php-scope-capture-tripwire.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,46 @@
# Python Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | --------------------------------------------- |
| `plainChain` | RESOLVES | `svc.get_user().save()` |
| `plainDeepChain` | RESOLVES | `svc.get_user().address.save()` |
| `optionalChain` | N/A | Python has no optional-chaining operator. |
| `nonNullAssert` | N/A | Python has no non-null assertion operator. |
| `awaitParen` | RESOLVES | `(await svc.get_user_async()).save()` |
| `explicitTypeArgs` | N/A | Python has no call-site type-argument syntax. |
| `indexElement` | RESOLVES | `repos[0].save()` |
| `fieldReceiverCall` | RESOLVES | `self.repo.save()` |
| `decoratedReceiverBase` | N/A | Python `self` carries no type decoration. |
| `decoratedFieldType` | RESOLVES | `self.repo.save()` |
All applicable measured cells resolve, including awaited, indexed and decorated-field receivers. The row does not establish support for every dynamic Python expression or every cross-module binding.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| --------- | -------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PYTHON-01 | Coverage audit | No failing cell is recorded; constructor-field receivers and module semantics have separate tests. | Map those suites to the language inventory, then add any missing exact-owner and import-shadowing cases. Require a current reproduction before labeling dynamic or cross-module behavior a product gap. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/python/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/python/scope-resolver.ts).
- [python-constructor-field-receiver.test.ts](../../gitnexus/test/integration/resolvers/python-constructor-field-receiver.test.ts).
- [python-namespace-semantics.test.ts](../../gitnexus/test/integration/resolvers/python-namespace-semantics.test.ts).
- [python-module-accessors.test.ts](../../gitnexus/test/integration/resolvers/python-module-accessors.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,131 @@
# Receiver Resolution Measurement Audit
Measured on 2026-10-23. Production sources are pinned to `c35806d2447dda6642448948e53c7c1ac8c3482a`;
this change updates the benchmark, tests and documentation, not the resolver.
The original 167-cell snapshot and count arm reproduced exactly after a fresh
build. That did not establish correctness: its classifier accepted any same-named
callee. Independent full-target checks found one false positive, and reviewing
all 72 original N/A entries found executable cases hidden among the exclusions.
## Results
The expanded matrix has **110 executed cases**: 93 reach their exact expected
declaration, 14 expose gaps, and three intentionally untyped controls remain
unresolved. The other **58 entries are N/A declarations**, not successful runtime
tests. No active shape corpus reported GRAMMAR-UNAVAILABLE.
| Language | Exact target | Visible gap | Invisible gap | Wrong target | N/A |
| ------------------------------------------ | ------------ | ----------- | ------------- | ------------ | --- |
| [c](c-ingestion-gaps.md) | 0 | 0 | 0 | 0 | 10 |
| [cobol](cobol-ingestion-gaps.md) | 0 | 0 | 0 | 0 | 10 |
| [cpp](cpp-ingestion-gaps.md) | 7 | 2 | 0 | 0 | 3 |
| [csharp](csharp-ingestion-gaps.md) | 8 | 1 | 0 | 0 | 1 |
| [dart](dart-ingestion-gaps.md) | 5 | 2 | 1 | 1 | 1 |
| [go](go-ingestion-gaps.md) | 6 | 0 | 0 | 0 | 4 |
| [java](java-ingestion-gaps.md) | 4 | 1 | 0 | 0 | 5 |
| [javascript](javascript-ingestion-gaps.md) | 5 | 2 | 0 | 0 | 4 |
| [kotlin](kotlin-ingestion-gaps.md) | 9 | 0 | 0 | 0 | 1 |
| [php](php-ingestion-gaps.md) | 6 | 2 | 0 | 0 | 4 |
| [python](python-ingestion-gaps.md) | 6 | 0 | 0 | 0 | 4 |
| [ruby](ruby-ingestion-gaps.md) | 3 | 3 | 0 | 0 | 5 |
| [rust](rust-ingestion-gaps.md) | 8 | 0 | 0 | 0 | 2 |
| [swift](swift-ingestion-gaps.md) | 7 | 1 | 0 | 0 | 2 |
| [typescript](typescript-ingestion-gaps.md) | 10 | 0 | 0 | 0 | 1 |
| [vue](vue-ingestion-gaps.md) | 9 | 1 | 0 | 0 | 1 |
The visible-gap counts include the three deliberate controls: JavaScript and
Ruby `untypedChain`, and PHP `arrowCallChain`. They must remain unresolved.
Zig and Objective-C still lack shape-arm rows; their dedicated suites were run
separately. C and COBOL's all-N/A rows do not measure their ordinary call paths;
their focused integration suites were also run.
The count arm is unchanged: **138 call drops, 168 total drops, 30 reads, no writes**.
Its origin breakdown is 57 in-program, 49 unknown, 30 external and two unclassified.
These diagnostic totals are not an actionable bug count.
## Corrected classifications
| Case | Previous | Fresh result | Interpretation |
| --------------------- | -------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C++ plainChain | N/A | RESOLVES | The old entry delegated to pointerArrowChain/valueDotChain. A canonical plain-chain fixture now also reaches User.save; there was no plain/deep contradiction. |
| C++ awaitParen | N/A | VISIBLE-GAP | A valid C++20 awaiter declares User await_resume(), but the terminal call does not resolve. The minimal probe passes `g++ -std=c++20 -fsyntax-only main.cpp`. |
| PHP fieldReceiverCall | N/A | RESOLVES | A real `$this->repo->save()` fixture replaces the alias to arrowPropertyPath. |
| Rust awaitParen | N/A | RESOLVES | `(svc.get_user_async().await).save()` reaches User.save. |
| Dart awaitParen | RESOLVES | WRONG-TARGET | Future<User> requires User.save, but the emitted edge reaches Address.save. Matching only `save` concealed the error. |
| Dart explicitTypeArgs | N/A | VISIBLE-GAP | A generic method with a concrete User return still loses `svc.getTyped<User>().save()`. |
| Vue script shapes | All N/A | Nine RESOLVES, one VISIBLE-GAP, one N/A | A real typed SFC exposes working chains and an indexed-receiver gap. The new fourHopChain cell matches the TypeScript control. |
Dart explicitly supports type arguments on generic method invocations; inference
was not a valid N/A reason. See the [Dart reference](https://dart.dev/language/type-system#type-argument-inference).
Rust await expressions are documented in the [Rust reference](https://doc.rust-lang.org/reference/expressions/await-expr.html).
These changes reclassify 15 existing cells and add Vue's four-hop cell. The
remaining original classifications are unchanged. The harness now records full
expected and actual node IDs, rejects extra wrong targets, and matches receiver
drops to call sites in the generated main file. A property-read drop or a drop in
a support file can no longer make a missing call look observable.
## Additional probes and tests
- **Ruby sibling parameters:** using `svc` for both the typed and untyped functions
reproduces an incorrect User.save edge from the untyped function in both
declaration orders. This independently confirms RUBY-01; the normal shape corpus
uses distinct parameter names to avoid contaminating its measurements.
- **Classifier regression tests:** five assertions failed against the previous
classifier. All seven tests pass after the change, including wrong-owner edges,
mixed correct/incorrect targets, untyped controls and unrelated drop records.
- **Five language suites:** 225 unique tests passed across C coverage, COBOL scope,
Vue scope, Zig and Objective-C provider tests; the runner also reported one skip.
The Objective-C persisted query/context and incremental-versus-force test timed
out at 180 seconds in the combined run, then passed in isolation. The retry's ten
name-filtered skips are not additional coverage.
- **Build, production/test typechecks and focused lint:** passed. The benchmark
source and its unit test parse and format cleanly. No full-suite or performance
claim is made from these focused checks.
## Reproduce
Run from `gitnexus/` with the checkout's own freshly built workers and shared
package. This audit used Node 22.23.3 on Linux x64, TypeScript 7.0.2, Vitest 5.0.4
and LadybugDB 0.21.1. All measured optional grammars loaded.
```sh
npm run build
npx tsc --noEmit
npx tsc --noEmit -p tsconfig.test.json
GITNEXUS_WORKER_POOL_SIZE=2 GITNEXUS_WORKER_READY_TIMEOUT_MS=60000 \
node --import tsx bench/receiver-resolution/measure.mjs --check
npm test -- test/unit/receiver-resolution-measurement.test.ts --maxWorkers=1
GITNEXUS_WORKER_POOL_SIZE=2 GITNEXUS_WORKER_READY_TIMEOUT_MS=60000 \
npx vitest run test/integration/resolvers/c-coverage.test.ts \
test/integration/resolvers/cobol-scope.test.ts \
test/integration/resolvers/vue-scope.test.ts \
test/integration/resolvers/zig.test.ts \
test/integration/objective-c-provider.test.ts --maxWorkers=2
```
A direct startup probe took about 20 seconds on this filesystem. The first run
hit the default five-second worker deadline before measuring any language; the
60-second setting above changes only that local deadline. An initial diagnostic
runner also inherited an invalid `--input-type` worker flag; rerunning from an
ordinary `.mjs` file removed that runner error. Neither failed attempt is counted
as language evidence. Each language corpus uses a fresh temporary directory;
its shapes share one generated main file and support files, so cells can interact
(see the Ruby parameter-name note above). The worktree's parse caches were cleared
before the original run.
The full JSON evidence command is the same harness with
`--shapes --corpus test/fixtures/lang-resolution`; it includes each expression,
expected target, actual targets, state and N/A reason. Compare its count projection
with the baseline before making any intentional update.
## Evidence identities
- Production source: `c35806d2447dda6642448948e53c7c1ac8c3482a` (no production changes in this audit).
- `measure.mjs` SHA-256: `73367935b50116a03d79342006569001a4265318ea351ca5793a4338f44d0785`.
- `baseline.json` SHA-256: `8416509491c9b684a2440bb46395295e2031fd60512c9806b3fd1b542948e71c`.
The benchmark preserves known gaps so future fixes cause an explicit baseline
change. This audit does not implement Dart ownership, indexed receiver typing,
C++ awaiter typing, Ruby scope isolation or the remaining historical backlog.

View file

@ -0,0 +1,49 @@
# Ruby Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------- |
| `plainChain` | RESOLVES | `plain_svc.get_user.save` |
| `untypedChain` | VISIBLE-GAP | `untyped_svc.get_user.save` (intentional untyped control) |
| `plainDeepChain` | VISIBLE-GAP | `deep_svc.get_user.address.save` |
| `optionalChain` | RESOLVES | `opt_svc&.get_user.save` |
| `nonNullAssert` | N/A | Ruby has no non-null assertion operator. |
| `awaitParen` | N/A | Ruby has no await expression in the core language. |
| `explicitTypeArgs` | N/A | Ruby has no type-argument syntax. |
| `indexElement` | VISIBLE-GAP | `idx_repos[0].save` |
| `fieldReceiverCall` | RESOLVES | `@repo.save` |
| `decoratedReceiverBase` | N/A | Ruby method receivers carry no type decoration. |
| `decoratedFieldType` | N/A | Ruby instance variables carry no declared type, so there is no decoration to strip. |
The typed plain and safe-navigation chains resolve. The baseline records YARD parameter bindings landing on Module scope: a typed sibling can lend its type to an untyped parameter with the same name, in either declaration order. The benchmark avoids the collision with distinct parameter names; that workaround does not fix the product. Fresh probes using the same `svc` parameter reproduced the wrong `User.save` edge from the untyped sibling in both declaration orders; see the audit receipt.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------- | ------------ | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RUBY-01 | Recorded gap | YARD parameter types can leak between sibling functions. | Bind annotations to the declaring function. Test typed/untyped siblings with the same parameter name in both orders; the typed call must hit its exact owner and the untyped call must remain unresolved. |
| RUBY-02 | Measured gap | `plainDeepChain` reaches an attr_reader property whose type is unavailable. | Reproduce the property-type loss before choosing a propagation rule. Preserve accessor dispatch and same-name owner boundaries. |
| RUBY-03 | Measured gap | `indexElement` is visible after the walker learned element_reference, but there is no elementTypeOf hook. | Carry YARD Array<User> element evidence into a provider route. Keep unsupported arrays and the intentional untypedChain control unresolved. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/ruby/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/ruby/scope-resolver.ts).
- [ruby-accessor-dispatch.test.ts](../../gitnexus/test/integration/resolvers/ruby-accessor-dispatch.test.ts).
- [ruby-scope.test.ts](../../gitnexus/test/integration/resolvers/ruby-scope.test.ts).
- [ruby-captures-golden.test.ts](../../gitnexus/test/unit/scope-resolution/ruby/ruby-captures-golden.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,47 @@
# Rust Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ------------------------------------------------------------------- |
| `plainChain` | RESOLVES | `svc.get_user().save();` |
| `plainDeepChain` | RESOLVES | `svc.get_user().address.save();` |
| `optionalChain` | N/A | Rust `?` is error propagation, not optional chaining on a receiver. |
| `nonNullAssert` | N/A | Rust has no non-null assertion operator. |
| `awaitParen` | RESOLVES | `(svc.get_user_async().await).save();` |
| `explicitTypeArgs` | RESOLVES | `svc.get_typed::<User>().save();` |
| `indexElement` | RESOLVES | `repos[0].save();` |
| `fieldReceiverCall` | RESOLVES | `self.repo.save();` |
| `decoratedReceiverBase` | RESOLVES | `self.repo.save();` |
| `decoratedFieldType` | RESOLVES | `self.repo.save();` |
Every applicable shape resolves, including the bounded Box/Rc/Arc field case and the newly executed `(svc.get_user_async().await).save()` fixture. The prior await N/A was an untested exclusion, not a syntax restriction. The delivered pointer normalization is conservative: local pointer/trait methods, qualified pointees and opaque implementations can prevent unwrapping. The baseline also records workspace-wide suppression for unresolved non-standard imports or macro_rules definitions.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RUST-01 | Documented boundary | A conservative dispatch guard can suppress otherwise useful pointer-field resolution in another file. | Measure recall on a fixed crate and identify the exact missing proof before narrowing the guard. Preserve pointer-owned and local-trait method negatives. |
| RUST-02 | Documented boundary | Qualified pointees, projections and opaque/macro-generated dispatch are outside the proven field-unwrapping slice. | Take one owner-provable form at a time with exact targets; do not infer full Rust autoderef or macro expansion from the passing decoratedFieldType cell. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/rust/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/rust/scope-resolver.ts).
- [rust-pointer-expansion-dispatch.test.ts](../../gitnexus/test/integration/rust-pointer-expansion-dispatch.test.ts).
- [rust-pointer-opaque-dispatch.test.ts](../../gitnexus/test/integration/rust-pointer-opaque-dispatch.test.ts).
- [rust-qualified-factory-boundaries.test.ts](../../gitnexus/test/integration/rust-qualified-factory-boundaries.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,150 @@
# Swift Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `plainChain` | RESOLVES | `svc.getUser().save()` |
| `plainDeepChain` | RESOLVES | `svc.getUser().address.save()` |
| `optionalChain` | RESOLVES | `svc.getUser().optionalAddress?.save()` |
| `nonNullAssert` | RESOLVES | `svc.getUser().optionalAddress!.save()` |
| `awaitParen` | RESOLVES | `(await svc.getUserAsync()).save()` |
| `explicitTypeArgs` | N/A | Swift infers generic parameters; there is no call-site type-argument spelling on a method. |
| `indexElement` | VISIBLE-GAP | `repos[0].save()` |
| `fieldReceiverCall` | RESOLVES | `self.repo.save()` |
| `decoratedReceiverBase` | N/A | Swift `self` carries no type decoration. |
| `decoratedFieldType` | RESOLVES | `self.repo?.save()` |
## Verified receiver coverage
Swift is registered in `SCOPE_RESOLVERS`. Optional grammar availability is an
environment condition, not a global Node 22 blocker.
The combined #3666/#3667 implementation resolves the typed Swift benchmark cells
`plainChain`, `plainDeepChain`, `optionalChain`, `nonNullAssert` and `awaitParen`.
Hoisted return lookup checks declaration ownership. Exact captured fixed/variadic
Swift override replay has positive regression controls; this does not establish
argument-label or generic-aware overload completeness.
`indexElement` is now a VISIBLE-GAP: the walker reads the subscript spelling, but
Swift has no `elementTypeOf` hook. Argument-aware inherited-overload selection and
associated/generic type handling remain bounded follow-up work.
Sources: [receiver baseline](../../gitnexus/bench/receiver-resolution/BASELINE.md),
[Swift resolver](../../gitnexus/src/core/ingestion/languages/swift/scope-resolver.ts),
[override replay tests](../../gitnexus/test/integration/swift-parameterized-override-replay.test.ts).
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| SWIFT-01 | Measured gap | `indexElement` is visible but Swift has no elementTypeOf hook. | Carry a proven element type through the provider and assert its exact member owner; preserve unsupported-container and same-name negatives. |
| SWIFT-02 | Recorded boundary | Inherited overload selection is bounded; fixed/variadic positives do not prove argument-label or generic-aware dispatch. | Specify one callable identity rule at a time and retain the current override replay positives and owner-mismatch negatives. |
| SWIFT-03 | Historical reports | The extraction, inheritance and module items below have not all been revalidated. | Reproduce each item on a pinned base before assigning implementation priority. Record both reference resolution and extraction evidence. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/swift/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/swift/scope-resolver.ts).
- [swift-hoisted-return-ownership.test.ts](../../gitnexus/test/integration/swift-hoisted-return-ownership.test.ts).
- [swift-parameterized-override-replay.test.ts](../../gitnexus/test/integration/swift-parameterized-override-replay.test.ts).
- [swift.test.ts](../../gitnexus/test/integration/resolvers/swift.test.ts).
## Historical reports requiring revalidation
The older backlog below is not a fresh feature matrix. Reproduce each item through
the current scope-resolution pipeline before treating it as open or resolved.
TypeEnv extraction support alone does not prove reference resolution.
## 🔴 High Priority
### Type Inference
| Gap | Description | Impact |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| Optional bindings inside for-loop bodies | Re-test capture ownership and scope type bindings; the old call-processor re-parse diagnosis no longer applies | Requires a current positive/negative fixture |
| `while let` binding | `while let x = iter.next()` not in `DECLARATION_NODE_TYPES` | Uncommon but valid Swift pattern |
### Call Resolution
| Gap | Description | Impact |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `await expr` / `try expr` as call wrappers | `await_expression` and `try_expression` wrap `call_expression` — call extraction queries match but the outer wrapper can interfere with receiver resolution in some paths | Most cases work via `unwrapSwiftExpression` but edge cases remain |
| Trailing closures | `items.map { $0.save() }` — `$0` type not inferrable | Functional-style Swift code |
## 🟡 Medium Priority
### Symbol Extraction
| Gap | Description | Impact |
| ----------------------- | ----------------------------------------------------------------------- | ------------------------------------- |
| Enum `case` as callable | `MyEnum.case` calls are member-form, not caught by constructor fallback | Enum-heavy code (Result, State enums) |
| Subscript declarations | `subscript(i:) -> T` not captured | Protocol conformance tracking |
| Operator overloads | `static func + (lhs:, rhs:)` not captured | Mathematical types |
| `deinit` | `deinit {}` not captured | Minor — rarely called explicitly |
| Macro declarations | `@macro` / `#macro` (Swift 5.9+) not captured | Swift macro ecosystem is growing |
### Heritage / Inheritance
| Gap | Description | Impact |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Multiple inheritance specifiers | Verify all parent/protocol captures and emitted edges for `class Foo: Bar, P1, P2` on the current provider | Historical first-specifier report needs revalidation |
| Generic constraints | `class Foo<T: Equatable>` — bounds not tracked | Advanced generics |
| Conditional conformance | `extension Array: P where Element: Q` — `where` clause not processed | Cross-platform code |
| Protocol composition | `typealias Codable = Encodable & Decodable` — not expanded | Type alias resolution |
### Export / Visibility
| Gap | Description | Impact |
| ---------------------------- | --------------------------------------------------- | ---------------------------------------------------- |
| Nested function declarations | Inner `func` marked as exported — should be private | Conservative resolution still correct (over-exports) |
### Module / Import
| Gap | Description | Impact |
| ------------------------- | ------------------------------------- | -------------------------------- |
| `@testable import` | Test target imports treated as opaque | Test file cross-references |
| Cross-package SPM imports | External package symbols not resolved | Only affects multi-package repos |
| `@_exported import` | Module re-exports not tracked | Framework wrapper patterns |
## 🟢 Low Priority
### Type Inference
| Gap | Description | Impact |
| ------------------------------------- | ---------------------------------------------------- | ------------------------------- |
| `switch` / `case` pattern binding | `case let x as Foo:` not tracked | Enum pattern matching |
| Tuple destructuring | `let (a, b) = fn()` not handled | Uncommon pattern |
| `@Environment` / `@EnvironmentObject` | SwiftUI dependency injection — no AST representation | Would need heuristic resolution |
| `@Query` (SwiftData) | Property wrapper types not inferrable from AST | SwiftData-specific |
| `#if canImport(...)` | Conditional compilation not evaluated | Cross-platform projects |
## ✅ Historical extraction fixes
These entries record earlier fixes. They are not proof that every corresponding
receiver or cross-file form is covered by the current pipeline.
| Gap | Resolution | Commit |
| --------------------------------- | -------------------------------------------------------------------------------------------------------- | --------- |
| Cross-chunk implicit imports | `addSwiftImplicitImports` now uses `allFileList` instead of chunk-only `files` | `956dfd0` |
| `private(set)` false positive | Regex excludes `private(set)` / `fileprivate(set)` from unexported check | `0a3cdce` |
| `if let` / `guard let` binding | `extractIfGuardBinding` handles optional bindings | `16b1a63` |
| `await` / `try` unwrapping | `unwrapSwiftExpression` strips wrappers before RHS analysis | `16b1a63` |
| For-loop element type extraction | `extractForLoopBinding` + `extractSwiftElementTypeFromTypeNode` + type_annotation population in type-env | `956dfd0` |
| `self` / `super` resolution | `lookupInEnv` handles `self`/`super` via AST walk | `16b1a63` |
| Optional chaining `obj?.method()` | Handled via `optional_chaining_expression` | `16b1a63` |
| Initial inheritance capture | First-specifier capture was added; this does not establish complete protocol-list coverage | `16b1a63` |
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,48 @@
# TypeScript Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `plainChain` | RESOLVES | `svc.getUser().save();` |
| `plainDeepChain` | RESOLVES | `svc.getUser().address.save();` |
| `optionalChain` | RESOLVES | `svc?.getUser().save();` |
| `nonNullAssert` | RESOLVES | `svc!.getUser().save();` |
| `awaitParen` | RESOLVES | `(await svc.getUserAsync()).save();` |
| `explicitTypeArgs` | RESOLVES | `svc.getTyped<User>().save();` |
| `indexElement` | RESOLVES | `repos[0].save();` |
| `fourHopChain` | RESOLVES | `root.getSvc().getUser().address.getCity().save();` |
| `fieldReceiverCall` | RESOLVES | `this.repo.save();` |
| `decoratedReceiverBase` | N/A | TypeScript `this` carries no type decoration — there is no pointer/reference spelling on a method receiver. |
| `decoratedFieldType` | RESOLVES | `this.repo!.save();` |
Every applicable shape resolves, including four-hop chains, indexed receivers and explicit type arguments. These are fixed examples, not a complete type-checker contract. The roadmap still lists type predicates, positional destructuring and discriminated-union narrowing as historical candidates requiring current reproductions.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TYPESCRIPT-01 | Historical reports | The deferred narrowing/destructuring items are not marked complete by the receiver series. | Audit each against current tests and pin a failing example before planning code. Define what metadata crosses extraction, ParsedFile and scope resolution. |
| TYPESCRIPT-02 | Coverage audit | Passing fixed shapes do not prove complete generic substitution or callable ownership. | Retain type-parameter, callable-alternative and workspace-package boundaries. Require full target identities and ambiguous/shadowed negatives for new inference. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/typescript/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/typescript/scope-resolver.ts).
- [typescript-type-parameters.test.ts](../../gitnexus/test/integration/resolvers/typescript-type-parameters.test.ts).
- [typescript-callable-alternatives.test.ts](../../gitnexus/test/integration/resolvers/typescript-callable-alternatives.test.ts).
- [typescript-workspace-packages.test.ts](../../gitnexus/test/integration/resolvers/typescript-workspace-packages.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,48 @@
# Vue Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
| Shape | Recorded state | Expression or exclusion |
| ----------------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `plainChain` | RESOLVES | `svc.getUser().save();` |
| `plainDeepChain` | RESOLVES | `svc.getUser().address.save();` |
| `optionalChain` | RESOLVES | `svc?.getUser().save();` |
| `nonNullAssert` | RESOLVES | `svc!.getUser().save();` |
| `awaitParen` | RESOLVES | `(await svc.getUserAsync()).save();` |
| `explicitTypeArgs` | RESOLVES | `svc.getTyped<User>().save();` |
| `indexElement` | VISIBLE-GAP | `repos[0].save();` |
| `fourHopChain` | RESOLVES | `root.getSvc().getUser().address.getCity().save();` |
| `fieldReceiverCall` | RESOLVES | `this.repo.save();` |
| `decoratedReceiverBase` | N/A | TypeScript `this` carries no type decoration — there is no pointer/reference spelling on a method receiver. |
| `decoratedFieldType` | RESOLVES | `this.repo!.save();` |
The row now runs a real `<script lang="ts">` SFC against the same typed declarations used by TypeScript. Nine shapes reach their exact expected owners. `repos[0].save()` is VISIBLE-GAP even though the corresponding TypeScript fixture resolves. The former all-N/A row hid both working behavior and this gap. Template expressions and `<script setup>` remain separate coverage surfaces.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------ | -------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| VUE-01 | Measured gap | Typed SFC `repos[0].save()` remains VISIBLE-GAP. | Compare SFC capture/type bindings and element folding with the resolving TypeScript control. Assert User.save and preserve same-name and untyped negatives. |
| VUE-02 | Coverage audit | Script, template and cross-file import behavior need distinct evidence. | Inventory existing SFC tests before adding cases; keep same-named component imports and compiler macros separate from real callable declarations. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/vue/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/vue/scope-resolver.ts).
- [vue-scope.test.ts](../../gitnexus/test/integration/resolvers/vue-scope.test.ts).
- [vue-pipeline-benchmark.test.ts](../../gitnexus/test/integration/vue-pipeline-benchmark.test.ts).
- [vue-sfc-extractor.test.ts](../../gitnexus/test/unit/vue-sfc-extractor.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

View file

@ -0,0 +1,36 @@
# Zig Ingestion Gaps
Audited on 2026-10-23 with freshly built production sources at `c35806d24` and
the accompanying benchmark changes. See the [measurement audit](receiver-resolution-audit.md)
for commands, target checks, exclusions and test limits. Historical reports below
remain separate from freshly measured receiver cases; broader ingestion is not
exhaustively assessed.
## Receiver shape snapshot
States below come from [baseline.json](../../gitnexus/bench/receiver-resolution/baseline.json).
The [harness](../../gitnexus/bench/receiver-resolution/measure.mjs) defines each
spelling and its N/A reason. RESOLVES requires the exact expected declaration ID
and no same-named call to a different owner. WRONG-TARGET records incorrect edges.
No row exists in the checked-in receiver shape arm. Add a measurement contract before comparing this language with measured rows.
Zig is registered but absent from the receiver shape arm. The merged series covers import aliases, forwarding constructors, anonymous containers and type applications through dedicated fixtures/tests. Absence from this benchmark is a measurement gap, not proof those features are missing.
## Planning candidates
| ID | Evidence | Gap or boundary | Next planning step and acceptance |
| ------ | -------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ZIG-01 | Coverage gap | Delivered Zig receiver forms have no row in baseline.json. | Define applicable Zig shapes and explicit N/A reasons, reusing import-alias and factory cases. Check exact declaration identities plus unknown and ambiguous receivers. |
| ZIG-02 | Coverage audit | Local imports and build-module/static-gating behavior live in separate suites. | Keep these boundaries in the measurement plan and distinguish unsupported compile-time evaluation from a missing static binding. |
## Code and regression entry points
- [Language provider directory](../../gitnexus/src/core/ingestion/languages/zig/).
- [Scope resolver](../../gitnexus/src/core/ingestion/languages/zig/scope-resolver.ts).
- [zig.test.ts](../../gitnexus/test/integration/resolvers/zig.test.ts).
- [zig-local-imports.test.ts](../../gitnexus/test/integration/resolvers/zig-local-imports.test.ts).
- [zig-build-modules.test.ts](../../gitnexus/test/integration/resolvers/zig-build-modules.test.ts).
Evidence details: [receiver baseline notes](../../gitnexus/bench/receiver-resolution/BASELINE.md) and
[current roadmap](../../type-resolution-roadmap.md#current-backlog).

276
docs/mcp-reference.md Normal file
View file

@ -0,0 +1,276 @@
# MCP reference
[Back to GitNexus](../README.md)
## Tools, resources and skills
### 19 MCP tools (17 per-repo + 2 group)
| Tool | What It Does |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `list_repos` | Discover all indexed repositories (paginated — `limit`/`offset`) |
| `query` | Process-grouped hybrid search (BM25 + semantic + RRF) |
| `context` | 360-degree symbol view — categorized refs, process participation |
| `impact` | Blast radius analysis with depth grouping and confidence |
| `trace` | Shortest directed path between two symbols (call + class-member edges) |
| `detect_changes` | Git-diff impact — maps changed lines to affected processes |
| `check` | Read-only structural checks against the indexed graph |
| `rename` | Semantic rename — previews by default, `dry_run: false` with the preview's `plan_token` applies its exact reviewed edits |
| `cypher` | Raw Cypher graph queries |
| `route_map` | API route map — which components fetch which endpoints, and handlers |
| `tool_map` | MCP/RPC tool definitions — where they're defined and handled |
| `shape_check` | Validate API response shapes against consumers' property accesses |
| `api_impact` | Pre-change impact report for an API route handler |
| `explain` | Explain persisted taint findings (source→sink flows, `--pdg` indexes) |
| `pdg_query` | Query control/data dependence at statement level (`--pdg` indexes) |
| `read_file` | Read a checkout file (optional 0-indexed slice; `maxLines` cap) |
| `grep` | Regex search of the working tree for indexed files (1-based hits) |
| `group_list` | List configured repository groups |
| `group_sync` | Rebuild a group's Contract Registry and cross-repo links |
> Per-repo read-only tools take an optional `repo` parameter. Omit it when only one repo is indexed, an MCP default is configured, or the GitNexus process cwd is inside a registered path without crossing into an unindexed nested Git checkout; otherwise pass it explicitly. Mutating tools require `repo` when multiple repos are indexed and no MCP default exists. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`, except `read_file` and `grep`, which read the checkout and do not accept `branch`. Omitting `branch` queries the workspace index, which follows your checked-out working tree — switching branches and re-running `gitnexus analyze` updates it incrementally. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
### Resources for instant context
| Resource | Purpose |
| --------------------------------------- | ---------------------------------------------------- |
| `gitnexus://repos` | List all indexed repositories (read this first) |
| `gitnexus://setup` | Setup and usage guidance for agents |
| `gitnexus://repo/{name}/context` | Codebase stats, staleness check, and available tools |
| `gitnexus://repo/{name}/clusters` | All functional clusters with cohesion scores |
| `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details |
| `gitnexus://repo/{name}/processes` | All execution flows |
| `gitnexus://repo/{name}/process/{name}` | Full process trace with steps |
| `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |
| `gitnexus://group/{name}/contracts` | A group's extracted contracts and cross-links |
| `gitnexus://group/{name}/status` | Staleness of repos in a group |
### 2 MCP prompts for guided workflows
| Prompt | What It Does |
| --------------- | ------------------------------------------------------------------------- |
| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level |
| `generate_map` | Architecture documentation from the knowledge graph with mermaid diagrams |
### Agent skills installed to `.claude/skills/` and `.agents/skills/` (if `.agents/` exists) automatically
- **Exploring** — navigate unfamiliar code using the knowledge graph
- **Debugging** — trace bugs through call chains
- **Impact Analysis** — analyze blast radius before changes
- **Refactoring** — plan safe refactors using dependency mapping
- **Guide** — GitNexus tool/resource/schema reference for the agent
- **CLI** — run analyze/status/clean/wiki commands on request
- **PDG Query** — statement-level control/data dependence queries (`--pdg` index)
- **Taint Analysis** — source→sink data-flow findings (`--pdg` index)
- **Plan** (`/gitnexus-plan`) — implementation-ready engineering plans backed by the graph and PDG slices
- **Work** (`/gitnexus-work`) — executes a plan as impact-checked, `detect_changes`-gated atomic commits
- **Review** (`/gitnexus-review`) — graph-backed review of a PR, branch, range, or local diff, with taint pass and per-domain expert lenses
- **LFG** (`/gitnexus-lfg`) — the full pipeline: plan → user gate → work → review
**Repo-specific skills** — run `gitnexus analyze --skills` and GitNexus detects the functional areas of your codebase (via Leiden community detection) and generates each one as a direct project skill under `.claude/skills/gitnexus-area-<name>/`. Each skill describes a module's key files, entry points, execution flows, and cross-area connections, and is regenerated on each `--skills` run to stay current.
When a repo contains an `.agents/` directory, the standard and generated skills are also mirrored to `.agents/skills/` (e.g. `.agents/skills/gitnexus-cli/`, `.agents/skills/gitnexus-area-<name>/`) so agents that read repo-local `.agents/skills/` (like Codex) stay in sync.
## MCP read-only mode
Set `GITNEXUS_MCP_READ_ONLY=1` before starting the MCP server to expose only the proven single-repository read surface. `rename` stays available as a preview-only tool: its `dry_run` must be omitted or `true`, and any other value is rejected before backend dispatch. Raw `cypher`, group tools, group routing, and group resources are omitted from discovery and rejected before backend dispatch. Tool descriptions and generated setup/context resources are scrubbed so they do not recommend unavailable routes.
The default is unchanged when the variable is unset or `0`. Any other value fails server startup rather than silently weakening the policy.
## MCP repository policy
Set `GITNEXUS_MCP_ALLOWED_REPOS` to a comma-separated list of canonical registry names or absolute indexed paths. Entries are trimmed, resolved against the registry, and deduplicated at startup. When exactly one repository is allowed it becomes the implicit default; when several are allowed, callers must select one unless `GITNEXUS_MCP_DEFAULT_REPO` is also set.
The default repository must resolve to an allowed repository. Invalid, ambiguous, blank, or mismatched configuration fails startup before stdio or HTTP begins serving. The allowlist applies to tools, aliases, discovery, resources, templates, implicit resolution, and embedded HTTP; hidden repository details are not included in selection errors. Setting only `GITNEXUS_MCP_DEFAULT_REPO` chooses a default without restricting explicit repository selections. An allowed repository whose name is duplicated in the registry must be configured by path, and its context resource is only served for the unique name form.
## MCP response budgets
Prefer explicit response filters before a byte cutoff. Single-repository MCP
`query` and `context` accept `response_sections`: choose query sections
(`processes`, `process_symbols`, `definitions`) or context sections (`incoming`,
`outgoing`, `processes`, `chain`, `routes`, `typed_properties`). Context always
keeps the selected symbol and also accepts `relationTypes: ["CALLS"]` to show
only that category in the existing incoming/outgoing reference window. These
options do not change graph search, ranking or traversal. They are not supported
for `@group` routing; use a member's indexed repository name/path instead.
For example, `context({uid: "<returned symbol id>", response_sections: ["incoming"],
relationTypes: ["CALLS"]})` returns the symbol, its returned callers, and all
completeness/staleness diagnostics. The `response_filter` field identifies omitted
data; omission does not mean absence. Remove filters for a broader view. For
impact, existing `summaryOnly`, `limit` and `offset` already provide focused views.
Omitting these filters preserves the existing response.
The `query`, `context`, and `impact` tools accept an optional positive-integer `maxTokens` argument. It bounds the complete formatted MCP response, including hints and error text, using a deterministic four-UTF-8-bytes-per-token estimate. When truncation is required, the response ends with `…` and remains valid UTF-8.
Set `GITNEXUS_MCP_DEFAULT_MAX_TOKENS` to apply the same guardrail when callers do not send `maxTokens`. An explicit tool argument takes precedence. Leaving both unset preserves the existing response byte-for-byte; this is a transport guardrail, not semantic pagination or an exact model-specific tokenizer limit.
## Tool Examples
### Impact Analysis
```
impact({target: "UserService", direction: "upstream", minConfidence: 0.8})
TARGET: Class UserService (src/services/user.ts)
UPSTREAM (what depends on this):
Depth 1 (WILL BREAK):
handleLogin [CALLS 90%] -> src/api/auth.ts:45
handleRegister [CALLS 90%] -> src/api/auth.ts:78
UserController [CALLS 85%] -> src/controllers/user.ts:12
Depth 2 (LIKELY AFFECTED):
authRouter [IMPORTS] -> src/routes/auth.ts
```
Options: `maxDepth`, `minConfidence`, `relationTypes` (`CALLS`, `IMPORTS`, `EXTENDS`, `IMPLEMENTS`), `includeTests`, `limit` (max symbols per depth, default 100), `offset` (pagination start per depth), `summaryOnly` (counts and risk only, omits symbol list)
**Disambiguation** — when several symbols share the target name, `impact` returns a ranked `ambiguous` candidate list instead of guessing. Narrow it with `target_uid` (exact, zero-ambiguity), `file_path`, or `kind` (`Function`, `Class`, `Method`, …). From the CLI these are `--uid`, `--file`, and `--kind`, matching `gitnexus context`:
```bash
gitnexus impact get_embeddings # → ambiguous: lists ranked candidates
gitnexus impact get_embeddings --file src/embed.py # → resolves to the one in that file
gitnexus impact get_embeddings --uid "Function:src/embed.py:get_embeddings" # exact
```
## More examples: search · context · detect_changes · rename · Cypher
### Process-Grouped Search
```
query({search_query: "authentication middleware"})
processes:
- summary: "LoginFlow"
priority: 0.042
symbol_count: 4
process_type: cross_community
step_count: 7
process_symbols:
- name: validateUser
type: Function
filePath: src/auth/validate.ts
process_id: proc_login
step_index: 2
definitions:
- name: AuthConfig
type: Interface
filePath: src/types/auth.ts
```
### Context (360-degree Symbol View)
```
context({name: "validateUser"})
symbol:
uid: "Function:validateUser"
kind: Function
filePath: src/auth/validate.ts
startLine: 15
incoming:
calls: [handleLogin, handleRegister, UserController]
imports: [authRouter]
outgoing:
calls: [checkPassword, createSession]
processes:
- name: LoginFlow (step 2/7)
- name: RegistrationFlow (step 3/5)
```
### Detect Changes (Pre-Commit)
```
detect_changes({scope: "all"})
summary:
changed_count: 12
affected_count: 3
changed_files: 4
risk_level: medium
changed_symbols: [validateUser, AuthService, ...]
affected_processes: [LoginFlow, RegistrationFlow, ...]
```
### Rename (Graph and Semantic Layer)
```js
rename({symbol_name: "validateUser", new_name: "verifyUser", repo: "my-app", dry_run: true})
// Omitting dry_run also previews. For an ambiguous name, repeat with the symbol_uid from context().
```
```text
result_version: 2
status: success
planning_status: ready
application_status: not_requested
applied: false
files_affected: 5
total_edits: 8
semantic_edits: 8
graph_edits: 0
text_search_edits: 0
text_search: not_used
coverage: {name: "gitnexus-semantic", scope: "indexed-repository", languages: [...], limitations: [...], ...}
changes: [{file_path, edits: [{start, length, old_text, new_text, line, confidence: "semantic"}]}]
```
Review the exact UTF-16 spans and coverage, then call `rename` with the same
selectors, `dry_run: false`, and its returned `plan_token` to apply exactly those edits.
Tokens are single-use, expire after 15 minutes or a server restart, and may be
evicted by the bounded retained-plan cache. Changed source contents, physical
targets, indexed declarations, provider resolution configuration or source-file sets (including untracked additions)
require a fresh reviewed preview. Omitting `dry_run` also previews.
Configuration is compared by provider resolution semantics; comment-only changes
that preserve those semantics are accepted. Unedited source aliases of an edited
physical file block preview. Apply checks configuration before the first write
and source contents and approved targets before each replacement; these checks
assume a cooperative checkout and do not form a filesystem transaction.
Counts describe occurrences, including multiple edits on one line. The graph
selects indexed declarations and files; GitNexus's language providers rebuild
semantic scopes from the current source and resolve exact name spans.
Rename does not load a compiler or language service. Comments, strings, and
unrelated same-spelled symbols are preserved. Unsupported syntax, ambiguous
bindings, stale declarations, and incomplete occurrence coverage block writes.
Coverage includes indexed files accepted by the selected language provider,
including its supported embedded-language sources, and excludes unindexed files
and external consumers. Each registered source-language provider supplies rename
rules. Constructor, destructor, inheritance, and interface families require
complete provider evidence. Dynamic or computed references block a rename when
the provider cannot prove their binding or exclude them from the selected family.
`rename` operates on the current checkout and rejects `branch`.
Language-specific limits remain explicit in the result. For example, PHP handles
case-insensitive function/class names separately from case-sensitive constants
and properties, but refuses class renames that require moving a PSR-4 file.
Java also refuses public top-level type renames that require a source-file move.
Rename edits source spans; it does not move files or rewrite dynamic string names.
Apply revalidates the reviewed plan and source snapshots before writing. The
single-use preview token does not make the filesystem operation transactional.
The final destination check and replacement are separate
operations, so another process can still change a file between them. Avoid
concurrent source writes during application. On a write failure, `status: partial` and `failed_files`
report the failed file and `unattempted_files` lists the later files that were never touched;
`applied`, counts, and `changes` describe only landed edits.
Inspect failures before retrying, and run type checking, tests, and
`detect_changes` after applying. A valid identifier is not a guarantee against
new-name collisions.
### Cypher Queries
```cypher
-- Find what calls auth functions with high confidence
MATCH (c:Community {heuristicLabel: 'Authentication'})<-[:CodeRelation {type: 'MEMBER_OF'}]-(fn)
MATCH (caller)-[r:CodeRelation {type: 'CALLS'}]->(fn)
WHERE r.confidence > 0.8
RETURN caller.name, fn.name, r.confidence
ORDER BY r.confidence DESC
```

View file

@ -0,0 +1,123 @@
# Guard-aware taint collection optimization
Measured 2026-10-24 for PR #3703. The corrected final implementation meets the planned **<=5% guard-free CFG collection-time overhead** target on all three measured workloads. Against the original PR implementation, the selection workload is **12.55% faster** and the transitive-alias holdout is **18.38% faster**. No proof rule or budget was weakened.
## Confirmed results
Each row compares two revisions in one process with 15 alternating paired samples. Negative overhead means faster collection. Compare timings within a row: this shared host also ran tests, and load changed between comparisons. These are ratios of sample medians, not averages of per-pair ratios. [Raw samples and source hashes](guard-taint-overhead-results.json) accompany this report.
| Reference | Workload | Reference median (ms) | Optimized median (ms) | Change |
| ------------------- | ---------- | --------------------: | --------------------: | ------: |
| Pre-feature f3fa67b | arguments | 926.98 | 916.33 | -1.15% |
| Pre-feature f3fa67b | transitive | 1319.92 | 1370.44 | 3.83% |
| Pre-feature f3fa67b | direct | 548.73 | 540.19 | -1.56% |
| Original PR 6ee7ce1 | arguments | 801.44 | 700.84 | -12.55% |
| Original PR 6ee7ce1 | transitive | 1167.84 | 953.23 | -18.38% |
Every consecutive five-pair block also meets the target against the pre-feature reference:
| Workload | Pairs 1–5 | Pairs 6–10 | Pairs 11–15 |
| ---------- | --------: | ---------: | ----------: |
| arguments | 1.39% | -0.07% | -0.34% |
| transitive | 0.62% | -2.35% | -0.95% |
| direct | 0.17% | 0.74% | -2.62% |
The integrated savings against the original PR are 100.59 ms on argument forwarding and 214.61 ms on transitive aliases. The final confirmation includes the malformed-AST correction discovered during review. Earlier five-pair selection batches varied enough to cross the target; 15 pairs were specified before final confirmation. All inputs, timing boundaries, correctness gates and thresholds stayed fixed. This establishes the target for the measured workloads and run, not a statistical guarantee for every host or source program.
## What changed
Only the TypeScript/JavaScript fact harvester changes at runtime. It now:
- Reuses known parent and parameter scopes during declaration scanning.
- Records nearest scopes for identifiers, avoiding native ID reads and map entries for structural nodes.
- Reuses adjacent resolution results and captured call-argument bindings while still recording ordinary call-frame occurrences.
- Reads native child counts and source positions once where the AST is immutable.
- Skips well-formed string/regex internals. Malformed literals retain full traversal; template substitutions, qualified identifiers and unsafe-name checks remain covered.
- Constructs each statement fact record once and allocates predicate-site maps only when predicates can be recognized.
There is no new dependency, solver, persistent cache or wire format. Declaration order, shadowing, synthetic binding identity, call frames, shape/proof limits and conservative fallback behavior remain unchanged.
## Reproduce the measurements
The portable harness is [compare-guard-overhead.mjs](../../gitnexus/bench/cfg/compare-guard-overhead.mjs). Both source checkouts need dependencies installed. From the optimized checkout's gitnexus package:
```bash
node --expose-gc --import tsx bench/cfg/compare-guard-overhead.mjs \
--baseline /path/to/reference/gitnexus \
--workload arguments --pairs 15 --check --out result.json
```
Repeat with transitive and direct. Use CPU affinity on a suitable quiet core when available. The measured run pinned both versions to CPU 23. Reference revisions:
- Pre-feature target: f3fa67b1445b8e8eeb23ae253fd3110044dc3624.
- Original PR implementation: 6ee7ce1cc463a8ad55cbdf2aea8325e0eb0396e0.
- Integration head: 09d2ebdb1f6d1571fded04ea917fb1935c4787e1. The main merge introduced no CFG/taint changes.
- Final harvester SHA-256: 19b0ca87758a18009b1f740ed4a22c81ccbc12ee756ba53f2d7fc823090e78ff.
Each workload contains 4,000 functions. Parsing occurs once, outside collection timing. Three warmup repetitions precede alternating reference/candidate samples, with explicit GC before each sample. Timed work is collectFunctionCfgs through the production visitor. Serialization and correctness checks occur outside timing; prior CFG outputs are not deliberately retained while timing the next sample. Every final sample exceeded 100 ms.
The harness always requires exact legacy CFG equality, all 4,000 functions, and all 4,000 helper argument effects with the exact prefix/input/suffix composition and ordinary-shell contract. Its --check additionally requires at least five pairs, >=100 ms samples and <=5% median overhead. An empty-output probe of the original harness failed all correctness gates. No CI wiring or existing benchmark allowance changes are part of this optimization.
Function bodies use unique function and consumer names:
```ts
// arguments: selection workload
function f(x: string) {
const y = 'prefix ' + x;
return consume(y);
}
// transitive: separate confirmation workload
function f(x: string) {
const a = 'prefix ' + x;
const b = a + ' suffix';
return consume(b);
}
// direct: additional guard-free check
function f(x: string) {
return consume('prefix ' + x);
}
```
## Correctness and validation
- Ad hoc full-output comparison against the original PR: 633 fixture files plus 30 explicit edge cases, **1,140 CFGs with zero differences**, including refinement data and skip counts. Corpus output SHA-256: 0d663493b85105b8cd3f4eeb15dad0061473aef785a342344c6db1f511385cd0.
- A separate **2,520 malformed-input mutation corpus** produced 1,651 CFGs with zero differences. Forty malformed literal nodes exercised parser recovery.
- Independent adversarial review identified a possible literal-recovery omission. Real parser reproductions made two new tests fail; requiring !node.hasError fixed both. Seven new cases cover recovery, repeated arguments, capture caps and nested declaration scope fallback. All **177 CFG/refinement tests** pass.
- Corrected-source default unit project: **900 files, 20,696 passed, 47 skipped, zero failures**. Corrected-source CFG integration: **13 files, 141 passed**.
- Corrected-source CLI build, source and test typechecks pass. Changed-file ESLint reports zero errors; warning-level diagnostics remain.
- Corrected-source persisted tool accuracy: **32/32 fixed answers pass** with the existing oracle.
- Corrected-source CFG benchmark: **15/15 scenarios pass**, including existing time, serialized-size, retained-heap, fingerprint, reaching-definition and taint budgets.
- Graph analysis: the optimization changes six files and 77 symbols across three observed processes (**MEDIUM** risk). The entire PR against merge base 11a49a15c6befbe4d5de1cebe74b5456aeb44b99 changes 42 files and 399 symbols across 16 observed processes (**CRITICAL**, covered by the prior shared-taint approval). Neither result carries a partial/truncated flag. Process counts are bounded graph observations; this refreshed index does not include the PDG layer.
- Four-shard full suite: **1,338 files, 28,267 passed, 88 skipped, zero failures**.
The full-suite snapshot was frozen before the final malformed-literal correction. It covers all other optimized code at the integration head. The corrected source was separately rebuilt and checked by the unit, CFG integration, differential, scaling and accuracy runs above.
The focused review combined a local correctness read with an independent Claude CLI adversarial read. The peer receipt verifies claude-opus-5-5; requested effort was high and actual effort is unverified. The peer reviewed the runtime optimization before the correction; local follow-up verified the fix, added tests and portable harness. The public harness reproduces timing and synthetic correctness checks; the broader ad hoc corpus comparisons are local validation evidence, not a new CI gate.
## Limits and remaining costs
The <=5% target concerns collection time on these guard-free workloads. It is not an end-to-end latency or peak-memory guarantee. Existing guarded, capped, time, payload and retained-heap scaling budgets remain unchanged. This run makes no peak-heap improvement claim.
Serialized size is identical to the original PR's normalized proof facts. Argument forwarding remains 5,118,249 bytes versus 4,030,249 before the feature (**+27.00%**); transitive aliases remain +37.40%, direct arguments +23.69%. Removing the value facts loses forwarding precision. A compact wire format is a separate tradeoff and was not introduced here.
The initial profile attributed substantial cost to declaration scanning, name resolution and duplicate value traversal. The retained changes target that work. No fresh profile establishes the remaining bottleneck; broader parser rewrites or a new cache framework are not justified by these results.
## Experiment accounting
Twelve bounded experiments ran serially: seven component experiments remain in the final implementation and five were rejected. There were no deferred dependency requests, unselected parallel candidates, censored experiments, runner errors or timeouts. A malformed-input correctness fix followed selection; it was not a new optimization experiment.
The table preserves the original component forecasts and contemporaneous five-pair results. Forecasts estimated savings against the original or preceding candidate; measurements compared the accumulated candidate against the pre-feature revision. **Those references differ, so the results do not validate individual forecasts.** They also show the timing variance that motivated final 15-pair confirmation. Do not add component percentages; only the original-to-final paired comparisons establish the integrated gain.
| Retained component | Forecast savings | Accumulated candidate vs pre-feature during selection |
| ------------------------------------ | ---------------: | ----------------------------------------------------: |
| Parameter scope reuse | 4–8 pp | 575.61 → 551.19 ms (-4.24%) |
| Identifier-only scope cache | 5–12 pp | 487.28 → 520.21 ms (6.76%) |
| Reuse call argument reads | 3–6 pp | 544.05 → 569.75 ms (4.72%) |
| Reuse native loop bounds/positions | 2–6 pp | 479.96 → 507.24 ms (5.68%) |
| Reuse last resolved name | 2–5 pp | 574.21 → 581.69 ms (1.30%) |
| Skip well-formed literal internals | 2–6 pp | 516.22 → 533.60 ms (3.37%) |
| Reuse scope parent; build facts once | 3–7 pp | 554.10 → 496.07 ms (-10.47%) |
Early leaf shortcuts, bulk child enumeration, a per-node resolution map and standalone allocation changes did not show a reliable win. A generic identifier-leaf shortcut was also rejected because qualified identifier nodes have children. The final literal shortcut explicitly preserves parser recovery.
Stopping reason: the corrected final candidate meets the target and all synthetic correctness gates, including the original-to-final holdout. Optimization began at 10:35 UTC and corrected performance confirmation finished at 11:46 UTC (about 71 minutes); validation and publication continued afterward. No paid judge was used for timing. Compute and review spend were not metered, so whole-run cost is unrecorded. The local audit ledger and specification remain under .context/compound-engineering/ce-optimize/guard-taint-overhead/; this tracked report, raw results and portable harness are the shared evidence.

View file

@ -0,0 +1,380 @@
{
"measured_at": "2026-10-24T11:46:01.733Z",
"references": {
"target": "f3fa67b1445b8e8eeb23ae253fd3110044dc3624",
"original": "6ee7ce1cc463a8ad55cbdf2aea8325e0eb0396e0",
"integration": "09d2ebdb1f6d1571fded04ea917fb1935c4787e1"
},
"candidate_source_sha256": "19b0ca87758a18009b1f740ed4a22c81ccbc12ee756ba53f2d7fc823090e78ff",
"environment": {
"node": "v22.23.3",
"v8": "12.4.254.21-node.57",
"platform": "linux",
"arch": "x64",
"cpu": "12th Gen Intel(R) Core(TM) i9-12900K",
"affinity_cpu": 23,
"shared_host": true
},
"protocol": {
"functions": 4000,
"warmup_repetitions": 3,
"pairs": 15,
"sample_order": "baseline/candidate, then candidate/baseline, alternating",
"parse": "once outside timing",
"gc": "before each timed sample",
"metric": "ratio of candidate and baseline sample medians minus one",
"serialization": "outside timing",
"target_percent": 5,
"correctness_gates": ["legacy_equal", "functions_complete", "forwarding_complete"],
"heap_diagnostic": "after-collection heap growth; not peak heap"
},
"comparisons": [
{
"baseline": "target",
"kind": "selection",
"iteration": 12,
"final": true,
"post_review_fix": true,
"exit_code": 0,
"blocks": [
{
"medians_ms": [926.980541, 939.893447],
"time_overhead_pct": 1.393007234657806
},
{
"medians_ms": [874.998572, 874.380178],
"time_overhead_pct": -0.07067371533949762
},
{
"medians_ms": [936.643365, 933.451269],
"time_overhead_pct": -0.3408016454587326
}
],
"workload": "arguments",
"pairs": 15,
"time_overhead_pct": -1.1486265923677075,
"serialized_overhead_pct": 26.995850628583984,
"legacy_equal": 1,
"functions_complete": 1,
"forwarding_complete": 1,
"samples_ms": [
[
991.636407, 926.980541, 1052.223997, 874.353997, 814.005086, 846.39417, 939.310542,
968.675534, 850.55565, 874.998572, 924.263215, 816.897822, 936.643365, 960.946203,
952.875645
],
[
939.893447, 835.342256, 1062.366743, 980.586552, 785.881103, 819.862887, 1108.397972,
916.332996, 874.380178, 863.18481, 874.130014, 873.202115, 1027.155567, 1014.473391,
933.451269
]
],
"medians_ms": [926.980541, 916.332996],
"bytes": [4030249, 5118249],
"heap_growth_medians": [22076336, 21050152],
"base_hash": "0ceb296402cd3a89e3d9141152bd56d9584a50634fe2b718cabb5ee0e9aeab15",
"source_hashes": [
"eb5449241b235c26ed92d6f629a89868d5b3612c47095f96d3eb20b474cb85aa",
"19b0ca87758a18009b1f740ed4a22c81ccbc12ee756ba53f2d7fc823090e78ff"
]
},
{
"baseline": "target",
"kind": "holdout",
"iteration": 12,
"final": true,
"post_review_fix": true,
"exit_code": 0,
"blocks": [
{
"medians_ms": [1282.768951, 1290.729238],
"time_overhead_pct": 0.6205550106115565
},
{
"medians_ms": [1417.752374, 1384.478543],
"time_overhead_pct": -2.3469423582146653
},
{
"medians_ms": [1383.63807, 1370.441898],
"time_overhead_pct": -0.9537300458927089
}
],
"workload": "transitive",
"pairs": 15,
"time_overhead_pct": 3.8279811568370237,
"serialized_overhead_pct": 37.40160977949929,
"legacy_equal": 1,
"functions_complete": 1,
"forwarding_complete": 1,
"samples_ms": [
[
1319.915771, 1288.475793, 1236.561698, 1282.768951, 1255.029194, 1430.325594, 1478.997302,
1351.424832, 1317.151013, 1417.752374, 1394.826591, 1299.54403, 1287.726552, 1383.63807,
1483.755553
],
[
1290.729238, 1222.891716, 1303.250259, 1270.870905, 1489.054094, 1433.201519, 1567.401177,
1384.478543, 1383.860575, 1334.753843, 1386.789066, 1346.508798, 1370.441898, 1413.529929,
1272.542746
]
],
"medians_ms": [1319.915771, 1370.441898],
"bytes": [4502480, 6186480],
"heap_growth_medians": [30367416, 33670488],
"base_hash": "e9e120d2c163949405ae52dc5cd4d08a8d0c8647302f3fb1fafd3b431ab76930",
"source_hashes": [
"eb5449241b235c26ed92d6f629a89868d5b3612c47095f96d3eb20b474cb85aa",
"19b0ca87758a18009b1f740ed4a22c81ccbc12ee756ba53f2d7fc823090e78ff"
]
},
{
"baseline": "target",
"kind": "selection",
"iteration": 12,
"final": true,
"post_review_fix": true,
"exit_code": 0,
"blocks": [
{
"medians_ms": [546.287538, 547.190939],
"time_overhead_pct": 0.16537096989386324
},
{
"medians_ms": [548.729001, 552.784326],
"time_overhead_pct": 0.7390396703307989
},
{
"medians_ms": [554.717647, 540.177424],
"time_overhead_pct": -2.6211935168523826
}
],
"workload": "direct",
"pairs": 15,
"time_overhead_pct": -1.5555201172974042,
"serialized_overhead_pct": 23.685278087842153,
"legacy_equal": 1,
"functions_complete": 1,
"forwarding_complete": 1,
"samples_ms": [
[
585.832439, 604.653849, 508.324025, 528.45936, 546.287538, 590.143343, 542.103699,
506.672531, 548.729001, 653.093038, 566.802297, 554.717647, 556.273056, 510.102922,
519.793483
],
[
576.02371, 637.452543, 547.190939, 530.045111, 524.659083, 539.414348, 572.697724,
511.161353, 552.784326, 558.685312, 532.658077, 501.323318, 540.193411, 560.527328,
540.177424
]
],
"medians_ms": [548.729001, 540.193411],
"bytes": [3174968, 3926968],
"heap_growth_medians": [11372208, 18987256],
"base_hash": "e32fa1876c674740fa2d85a0e1b9bc263799c704f4d537694427da2dd197f264",
"source_hashes": [
"eb5449241b235c26ed92d6f629a89868d5b3612c47095f96d3eb20b474cb85aa",
"19b0ca87758a18009b1f740ed4a22c81ccbc12ee756ba53f2d7fc823090e78ff"
]
},
{
"baseline": "original",
"kind": "selection",
"iteration": 12,
"final": true,
"post_review_fix": true,
"exit_code": 0,
"blocks": [
{
"medians_ms": [839.997564, 715.49347],
"time_overhead_pct": -14.821958936061863
},
{
"medians_ms": [800.101563, 720.123923],
"time_overhead_pct": -9.995935978442782
},
{
"medians_ms": [801.435984, 675.281283],
"time_overhead_pct": -15.741082696381635
}
],
"workload": "arguments",
"pairs": 15,
"time_overhead_pct": -12.551510290059543,
"serialized_overhead_pct": 0,
"legacy_equal": 1,
"functions_complete": 1,
"forwarding_complete": 1,
"samples_ms": [
[
839.997564, 738.463058, 857.906524, 842.421851, 799.280266, 960.616255, 902.391745,
782.451825, 800.101563, 792.380063, 801.435984, 770.546193, 862.753015, 757.292758,
802.344464
],
[
659.721701, 715.49347, 700.843664, 742.920449, 842.665567, 751.378898, 864.312785,
694.810253, 682.495461, 720.123923, 635.26501, 668.832835, 705.642196, 687.253768,
675.281283
]
],
"medians_ms": [801.435984, 700.843664],
"bytes": [5118249, 5118249],
"heap_growth_medians": [30844760, 20766944],
"base_hash": "0ceb296402cd3a89e3d9141152bd56d9584a50634fe2b718cabb5ee0e9aeab15",
"source_hashes": [
"3b2a2bccf8254b61fd0ab1b8ab9423f89b29073afc402ad078189a31d67e0748",
"19b0ca87758a18009b1f740ed4a22c81ccbc12ee756ba53f2d7fc823090e78ff"
]
},
{
"baseline": "original",
"kind": "holdout",
"iteration": 12,
"final": true,
"post_review_fix": true,
"exit_code": 0,
"blocks": [
{
"medians_ms": [1022.240662, 943.977474],
"time_overhead_pct": -7.656043328082762
},
{
"medians_ms": [1074.679531, 1071.170551],
"time_overhead_pct": -0.3265140815266965
},
{
"medians_ms": [1214.845854, 953.230029],
"time_overhead_pct": -21.53489878066456
}
],
"workload": "transitive",
"pairs": 15,
"time_overhead_pct": -18.376410863434145,
"serialized_overhead_pct": 0,
"legacy_equal": 1,
"functions_complete": 1,
"forwarding_complete": 1,
"samples_ms": [
[
991.262411, 1022.240662, 954.091735, 1211.352262, 1328.408798, 994.117618, 1074.679531,
1113.739816, 1417.601299, 1056.288179, 1204.450932, 1214.845854, 1325.823707, 1225.401996,
1167.836454
],
[
855.369854, 899.467318, 944.243232, 1123.037271, 943.977474, 944.358269, 1071.170551,
1109.569003, 1180.041345, 1034.802502, 904.834811, 910.174455, 1218.088988, 1315.290326,
953.230029
]
],
"medians_ms": [1167.836454, 953.230029],
"bytes": [6186480, 6186480],
"heap_growth_medians": [22416784, 33734328],
"base_hash": "e9e120d2c163949405ae52dc5cd4d08a8d0c8647302f3fb1fafd3b431ab76930",
"source_hashes": [
"3b2a2bccf8254b61fd0ab1b8ab9423f89b29073afc402ad078189a31d67e0748",
"19b0ca87758a18009b1f740ed4a22c81ccbc12ee756ba53f2d7fc823090e78ff"
]
}
],
"validation": {
"corrected_source_sha256": "19b0ca87758a18009b1f740ed4a22c81ccbc12ee756ba53f2d7fc823090e78ff",
"default_units": {
"files": 900,
"passed": 20696,
"skipped": 47,
"failed": 0
},
"cfg_integration": {
"files": 13,
"passed": 141,
"failed": 0
},
"cfg_scaling": {
"scenarios": 15,
"passed": 15
},
"tool_accuracy": {
"checks": 32,
"passed": 32
},
"build": true,
"source_typecheck": true,
"test_typecheck": true,
"changed_file_lint_errors": 0,
"fixture_equivalence": {
"files": 633,
"custom_cases": 30,
"cfgs": 1140,
"mismatches": 0,
"sha256": "0d663493b85105b8cd3f4eeb15dad0061473aef785a342344c6db1f511385cd0"
},
"malformed_equivalence": {
"cases": 2520,
"cfgs": 1651,
"malformed_literal_nodes": 40,
"mismatches": 0
},
"graph": {
"base": "11a49a15c6befbe4d5de1cebe74b5456aeb44b99",
"optimization": {
"changed_count": 77,
"affected_count": 3,
"changed_files": 6,
"risk_level": "medium"
},
"whole_pr": {
"changed_count": 399,
"affected_count": 16,
"changed_files": 42,
"risk_level": "critical"
},
"partial_flag": false,
"truncated_flag": false,
"pdg_layer": false
},
"full_suite": {
"source_sha256": "37624680cb858fddfab7f7dcd167606b62f91b89cca7694091e5ac827bf7279c",
"revision_note": "Frozen candidate before !node.hasError correction. Corrected source separately validated as detailed above.",
"shards": [
{
"shard": 1,
"files": 334,
"passed": 7835,
"skipped": 10,
"failed": 0,
"total": 7845
},
{
"shard": 2,
"files": 335,
"passed": 7030,
"skipped": 8,
"failed": 0,
"total": 7038
},
{
"shard": 3,
"files": 335,
"passed": 6410,
"skipped": 14,
"failed": 0,
"total": 6424
},
{
"shard": 4,
"files": 334,
"passed": 6992,
"skipped": 56,
"failed": 0,
"total": 7048
}
],
"totals": {
"files": 1338,
"passed": 28267,
"skipped": 88,
"failed": 0,
"total": 28355
}
}
}
}

View file

@ -0,0 +1,260 @@
---
title: "fix: Preserve lexical binding ownership and HTTP provenance"
date: 2026-10-18
type: fix
artifact_contract: ce-unified-plan/v1
artifact_readiness: implementation-ready
product_contract_source: legacy-requirements
origin: https://github.com/abhigyanpatwari/GitNexus/issues/3630
execution: code
baseline_commit: 565e50276dc9aa4e3b6e36dfabe8a92571b0d699
---
# Preserve lexical binding ownership and HTTP provenance
## Goal Capsule
**Objective:** GitNexus users receive HTTP routes, fetch consumers and member targets that respect the declarations their code actually refers to.
**Means:** Declaration-based lexical ownership and binding-based HTTP provenance (KTD1–KTD4).
**Authority:** The user request and issue #3630, including both revision-5 plan comments, govern behavior. The user's linear-scaling requirement supersedes the comment's suggestion to leave the repeated wrapper closure scan unchanged.
**Execution profile:** Implement and verify all units, with regression-first coverage and rebuilt workers. Apply SOLID, KISS, DRY, YAGNI and clean code; keep language policy in providers.
**Tail ownership:** LFG owns simplification, code review, fixes, shipping and CI. Create the PR through the authenticated GitHub browser; do not merge it.
**Stop conditions:** A genuine access blocker or evidence that the required behavior cannot be achieved within the stated scope must be reported with preserved work. Routine implementation decisions remain autonomous.
---
## Product Contract
### Summary
Correct assignment ownership, remove compensating text heuristics, and resolve Express and fetch-wrapper provenance using the existing scope model. Preserve declared-type precedence, configured wrappers, unrelated ingestion and other language providers.
### Problem Frame
A closure's inferred constructor fact can currently make it appear to declare an outer variable. HTTP analysis invalidates the wrong binding, rename compensates with a walk-past workaround, and wrapper analysis confuses unrelated same-named values. Repeated scans also make wrapper chains and large files vulnerable to quadratic work.
### Requirements
**Ownership and type information**
- R1. When a provider sets `nameClaimsComplete`, assignment-derived facts cannot establish lexical ownership. Genuine declarations and shadowing retain ownership; providers without that policy retain current behavior.
- R2. Carry the nearest eligible skipped constructor fact only when the owner has no stronger fact. Return the complete selected `TypeRef`, preserving its scope, position and namespace. Keep same-scope tie rules unchanged and never propagate a nested write into an unconditional outer fact.
- R3. Remove the imported-receiver rename walk-past workaround after real indexing/rename coverage proves the core fix suffices.
**HTTP provenance**
- R4. Share lexical ownership, binding IDs, global checks and ambiguity checks between route and wrapper analysis. Invalidate initialized `var` redeclarations of forwarded parameters; keep uninitialized redeclarations. Remove `written` and `shadowedBetween`.
- R5. Bare platform `fetch` and platform-global member access require unshadowed global identity. Unknown injected parameters provide no evidence. Valid platform defaults provide potential evidence; self-referential defaults and shadowed platform globals do not.
- R6. Determine nested callable reachability from evaluated outer code and resolved binding references. Unrooted recursive cycles remain excluded. IIFEs, inline callbacks and directly escaping anonymous values participate. Named stored helpers require a reachable binding reference. Class heritage, computed keys, static fields and static blocks are evaluated independently of class-name references; methods and instance fields remain deferred until a reachable class reference. Supported decorator expression/application/initializer behavior follows the provider dialect.
- R7. Resolve bare callees to declaration/import identity before automatic fallback. Use project import resolution for relative, tsconfig and workspace specifiers. Known local non-wrappers, different resolved targets and ambiguity prevent name fallback. Fallback requires exactly one distinct same-named definition, including non-wrappers in the collision universe, and that definition must be proven. Apply the same rule to forwarding. Preserve existing member-call behavior and explicit configured wrapper-name overrides, including through local parameters.
- R8. Fail closed for collapsed parameter/body environments: if formals contain expressions, including nested defaults or computed pattern keys, a body `var`/function name also declared as a parameter or referenced in a parameter expression is ambiguous. Do not treat declarations in nested functions as outer body declarations. Rest alone is not an expression. Missing `ParsedFile` skips scope-dependent HTTP analysis only and retains existing scope-failure accounting.
**Verification and delivery**
- R9. Compare every `CALLS` edge at call-site/target identity level on the identical TS/JS fixture corpus and pinned rebuilt baseline/candidate builds; inspect every change. Receiver changes must be explained by restored owner declarations. Preserve `METHOD_OVERRIDES` and ancestor dispatch. Keep route/FETCHES, rename, import ownership, inheritance and taint suites green, including the existing seven fetch-base-url-wrapper edges, receiver-resolution and tool-accuracy checks.
- R10. Provide repeatable warmed scaling benchmarks with multiple sizes, repetitions, statistics, semantic fingerprints and explicit linear-factor checks. Include reversed forwarding chains, name collisions, concentrated declarations/reads, nested helper reachability and fresh per-file index construction. Report measured bounds and limitations honestly.
- R11. Update `docs/languages/local-import-scoping.md` for ownership versus facts, type precedence, provenance, ambiguity and automatic cache identities. Rebuild workers before validation; prove cold/warm cache transport. Open a reviewable PR with the validation and benchmark evidence.
### Scope Boundaries
Do not implement full control-flow narrowing, factory-call narrowing, capture-time binding storage, other-language ownership changes, separate parameter environments, SvelteKit fetch injection, or unrelated refactors. Do not manually bump parser cache counters or alter CI/release/security configuration.
### Sources
- [Issue body](https://github.com/abhigyanpatwari/GitNexus/issues/3630).
- [Plan sections 1–10](https://github.com/abhigyanpatwari/GitNexus/issues/3630#issuecomment-6255593894).
- [Plan sections 11–13](https://github.com/abhigyanpatwari/GitNexus/issues/3630#issuecomment-6255594141).
- `docs/languages/local-import-scoping.md`, `MIGRATION.md`, `AGENTS.md`, `GUARDRAILS.md`, `CONTRIBUTING.md`.
---
## Planning Contract
### Key Technical Decisions
- KTD1. **Honor complete declaration claims in shared lookup.** Change `name-claims.ts` without naming languages. Preserve whole facts and their existing strength policy; `scope-extractor.ts` provides the precedence reference.
- KTD2. **One per-file lexical analysis context.** Extract `createLexicalBindings` and pass the existing AST root explicitly alongside `ParsedFile` and line offset. `ParsedFile` does not retain parameter expression syntax, so the extra AST input is necessary for R8 without expanding the persisted scope model. Cache ownership by node/use and index ambiguity once. Avoid repeated linear scope-position scans in affected hot paths.
- KTD3. **Provider-owned wrapper analysis.** Replace the worker's language-name branch with an optional provider hook/context. Build shared context once per file and reuse it for facts/call sites. Keep new serializable identity metadata in parser-owned result shapes so automatic identities invalidate old cache entries.
- KTD4. **Resolve imports before route classification.** Reuse `resolveRouteModuleTargets` in `parse-impl.ts`, including wrapper-only files when loading project configs. Preserve unresolved, blocked and resolved target states. Index all relevant distinct definitions by binding identity and module/name; do not infer uniqueness from seed-only definitions.
- KTD5. **Work queues instead of repeated closure scans.** Build dependency edges once, propagate wrapper status through reverse dependencies, and index reachable callable regions once. Use mutable collision buckets instead of repeated array copying. Scaling checks include fresh context construction and adversarial ordering.
- KTD6. **Pinned semantic comparison plus separate timing.** Retain an untouched checkout/build at the baseline SHA. Export sorted full call-site edges and override edges from real pipelines before/after; exact fingerprints and positive result counts prevent fast empty answers. Follow `bench/go-route-resolution/measure.cjs` for reproducibility, adding mean/median/deviation and at least three workload sizes.
### High-Level Technical Design
```mermaid
flowchart TD
P["Provider: AST and ParsedFile"] --> L["Per-file lexical context"]
L --> F["Route and wrapper facts"]
F --> I["Project import resolution"]
I --> D["Definition and dependency indexes"]
D --> W["Wrapper work queue"]
W --> H["HTTP graph edges"]
```
### Assumptions and Risks
- The baseline is current `main` with both prerequisite PRs merged. Issue line numbers are navigation hints; current source is authoritative.
- A lookup cache alone does not prove linearity: position-index scans, deep repeated AST traversals and long dependency chains need direct measurement. Optimize only demonstrated hot paths required by R10.
- Runtime allocation and timing vary on this host. Use warmed repeated samples and generous normalized ratio gates; treat timing evidence as empirical, backed by traversal structure and semantic checks.
- No GitNexus MCP or existing checkout index is available. Attempt the documented CLI impact/change commands and record any unavailable graph evidence; source caller tracing supplements unresolved results.
- No new dependency is expected. No behavior of unsupported parameter environments is claimed beyond fail-closed HTTP inference.
---
## Implementation Units
### U1. Declaration ownership and rename
**Goal:** Restore lexical ownership while preserving receiver facts under R1–R3.
**Dependencies:** Baseline capture in U5 before production edits.
**Files:** `gitnexus-shared/src/scope-resolution/name-claims.ts`; `gitnexus/src/core/ingestion/languages/typescript/rename.ts`; `gitnexus/test/unit/scope-resolution/lexical-name-claims.test.ts`; `gitnexus/test/unit/scope-resolution/typescript/lexical-type-ownership.test.ts`; relevant receiver/rename integration fixtures.
**Approach:** Apply KTD1, then remove the workaround once ownership tests pass. Avoid changing method dispatch.
**Test scenarios:**
- Direct and chained constructor writes in closures resolve to outer parameters/module bindings for TS and JS.
- Owner annotations and parameter annotations, including JSDoc, return the complete owner fact; untyped owners retain the nearest eligible carried fact.
- Real local shadowing remains local and incomplete-claims providers retain prior ownership.
- A nested write does not type an outer read; same-scope and closure annotated receivers target `Base.m` with unchanged override edges.
- Existing imported receiver reassignment remains rejected by real rename tests.
**Verification:** Focused ownership and rename tests, full edge comparison and receiver check.
### U2. Shared bindings and Express invalidation
**Goal:** Satisfy R4/R8 using KTD2.
**Dependencies:** U1.
**Files:** `gitnexus/src/core/ingestion/route-extractors/lexical-bindings.ts`; `framework-route-facts.ts` in that directory; `gitnexus/test/unit/framework-route-provenance.test.ts`; `gitnexus/test/unit/group/express-provider-provenance.test.ts`; a focused lexical-helper test if needed.
**Approach:** Extract the existing ownership mechanism, index parameter/body ambiguity from the AST, add initialized-parameter redeclaration invalidation, then remove text guards.
**Test scenarios:**
- Module `let app` reassigned in a closure produces no `/let-closure` route.
- Initialized `var app` overwrites forwarding with and without other defaults; bare `var app` retains forwarding in supported simple-formal cases.
- Nested same-named parameter writes do not invalidate the outer parameter; destructuring writes and block shadowing remain correct.
- Nested destructuring defaults/computed keys trigger ambiguity; rest alone does not; body function declarations count, nested-function declarations do not.
**Verification:** Route provenance/group suites and rebuilt real Express integration.
### U3. Scope-aware wrapper extraction
**Goal:** Satisfy R5/R6/R8 using KTD2/KTD3.
**Dependencies:** U2 helper interface.
**Files:** `gitnexus/src/core/ingestion/route-extractors/fetch-wrapper.ts`; `gitnexus/src/core/ingestion/language-provider.ts`; `gitnexus/src/core/ingestion/languages/typescript.ts`; `gitnexus/src/core/ingestion/workers/parse-worker.ts`; `gitnexus/test/unit/fetch-wrapper-calls.test.ts`; targeted worker/integration fixtures.
**Approach:** Use binding IDs for URL parameters, aliases and nested references. Reuse file-level region indexing; no conflicting/localNames/referenced text sets. Preserve full declaration inventory for U4.
**Test scenarios:**
- All four platform-fetch/default rows from the issue, plus sibling block shadowing and alias shadowing.
- Self-recursive and mutually recursive unused helpers remain excluded; rooted chains/cycles participate.
- IIFE, inline callback, escaping anonymous function, unused named arrow helper and referenced helper are distinguished.
- Class declaration/expression heritage, computed keys, static blocks/static fields participate; methods/instance fields defer until referenced; supported decorators follow evaluation boundaries.
- Missing scope skips wrapper facts/call sites, retains unrelated definitions and reports scope failure; Vue line offsets remain correct.
**Verification:** Data-driven facts tests plus real worker/cache transport and unchanged seven-edge integration fixture.
### U4. Target identity and linear propagation
**Goal:** Satisfy R7/R10 using KTD4/KTD5.
**Dependencies:** U3 serialized identity contract; implementation can prepare independent resolution helpers after that contract is fixed.
**Files:** `gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts`; `gitnexus/src/core/ingestion/pipeline-phases/routes.ts`; provider-owned wrapper resolver helper if extraction and classification need a focused boundary; `gitnexus/test/unit/fetch-wrapper-calls.test.ts`; `gitnexus/test/integration/resolvers/fetch-wrapper-consumers.test.ts` and fixtures.
**Approach:** Resolve specifiers with the existing project resolver, classify known targets directly, enforce unique fallback across all definitions and propagate through a work queue. Configured names match first.
**Test scenarios:**
- Relative renamed imports, tsconfig path aliases and workspace imports target the actual wrapper.
- A different resolved target, local parameter, nested local or blocked claim cannot inherit same-name wrapper status.
- One wrapper plus one plain non-wrapper and two wrappers both prevent fallback; duplicate captures of one definition do not create false ambiguity.
- Unique unresolved fallback succeeds; forwarding uses the same rule.
- Configured local-parameter calls succeed, identical unconfigured calls decline; member behavior remains covered.
- Reversed long chains terminate with correct results; unrooted cycles remain excluded.
**Verification:** Extraction/classifier tests, pipeline FETCHES fixtures and scaling checks.
### U5. Semantic comparison and scaling evidence
**Goal:** Establish R9/R10 with KTD6.
**Dependencies:** Baseline capture precedes U1; candidate runs follow U1–U4.
**Files:** `gitnexus/bench/lexical-binding-provenance/measure.cjs`; `baseline.json` and `README.md` in that directory; a reusable call-site export/comparison runner there if no existing runner preserves all required identities; targeted comparison fixtures.
**Approach:** Use the identical baseline/candidate fixture corpus and pinned builds. Record all CALLS and METHOD_OVERRIDES edges, classify every delta, and measure fresh-context workloads over N/2N/4N or wider scales with warmups and at least 15 samples. Report environment, min/mean/median/deviation, normalized ratios, exact fingerprints and positive counts. Benchmark extraction separately from wrapper closure. Include aliases, nested helpers, concentrated reads following many completed scopes, collisions and reversed chains. Set a normalized linear-factor ceiling before checking the candidate; investigate any failure rather than widening it to fit.
**Test scenarios:**
- Semantic changes in annotated closure receivers are explained at their exact sites; other call categories remain unchanged.
- Baseline/candidate exports preserve source/target identity and multiplicity; override edge sets remain identical.
- Incorrect empty output fails correctness gates even if fast; reversed order exposes repeated scans.
**Verification:** Reproducible `--check` benchmark and saved edge-diff report in the PR evidence.
### U6. Contract and full validation
**Goal:** Complete R9/R11.
**Dependencies:** U1–U5.
**Files:** `docs/languages/local-import-scoping.md`; benchmark evidence documentation; only justified receiver baseline updates if exact edge review warrants them.
**Approach:** Document analysis policy versus runtime semantics, supported ownership guarantees and fail-closed limits. Replace stale numeric cache gate text with automatic identity references. Run mandatory regression, accuracy and cache gates on rebuilt code.
**Test scenarios:** Existing suites provide behavioral coverage; documentation adds no new executable behavior.
**Verification:** All required commands below pass or any concrete environment failure is isolated against the pinned baseline and explicitly reported.
---
## Verification Contract
Run from `gitnexus/`; use `GITNEXUS_WORKER_READY_TIMEOUT_MS=180000` for worker-based commands on this host.
| Gate | Command or evidence | Units |
| --- | --- | --- |
| Build | `npm run build` before worker verification | All |
| Types | `npx tsc --noEmit` and test typecheck when tests change | All |
| Focused regressions | Ownership, wrapper, route, rename, taint lexical imports and group unit suites | U1–U4 |
| Real integration | `npm run test:integration -- test/integration/resolvers/ test/integration/rename-provider-matrix.test.ts test/integration/local-import-worker-parity.test.ts` | U1–U4 |
| Receiver accuracy | `node --import tsx bench/receiver-resolution/measure.mjs --check` | U1/U5 |
| Tool accuracy | `node --import tsx bench/tool-accuracy/run.ts --check` | U5/U6 |
| Scaling | `node --import tsx bench/lexical-binding-provenance/measure.cjs --check` | U5 |
| Cache identities | `npm test -- test/unit/parse-cache-identity.test.ts test/unit/parse-cache-input-coverage.test.ts` plus cold/warm transport | U3/U6 |
| Full suite | `npm test` as required before commit; bound workers for host resources | All |
| Semantic parity | Sorted call-site/target export diff and unchanged override/ancestor behavior | U1/U5 |
---
## Definition of Done
Every requirement and issue acceptance table is covered, no unjustified call-target difference remains, required accuracy checks and regression suites pass, and scaling is measured with semantic identity guards. The production diff contains no abandoned experiments, unrelated cleanup or text-based scope heuristics. The contract is updated, work is reviewed and committed, and an open PR created through the authenticated browser contains benchmark results and any material validation limitations.
## Execution checkpoint
- U1 committed as `f791aae2`; declaration-ownership regressions and the imported-receiver rename regression pass. The write lookup explicitly preserves source order across deferred scopes so it sees the import before the write's blocker.
- U2 committed as `a18f9faa`; 154 focused tests, production/test types, and scoped lint pass. Deterministic comparison-count regressions justified replacing the position index's expired-prefix scan with a maximum-end tree.
- U3/U4 committed as `685e8189`. Regression-first evidence includes 42 extraction failures and real pipeline false positives/missed imports. The rebuilt pipeline preserves the seven existing base-URL edges, passes six new identity-based edges and configured overrides, and passes cold/warm cache reuse with alias retargeting. All 503 focused tests passed, including a real-worker scope-extraction failure that retains structural ingestion while omitting HTTP facts.
- U5 captured the original baseline before production changes. Formatting the standalone ownership probe required a second fixed corpus; the original remains retained. The final baseline is still immutable `565e50276dc9aa4e3b6e36dfabe8a92571b0d699`, with 432 files, 432 `CALLS`, 11 `METHOD_OVERRIDES`, and corpus fingerprint `88be1faf45e9aec145f9d168b8959d67f31ec3b09b5455e9c8d8b2b1681ade5a`. Clean candidate `685e8189` changes exactly one target: `declaredOwner.writeAndRead` at callsite line 14, column 4 now calls `Base.m` instead of `Foo.m`. The other 431 CALLS and all 11 override edges are unchanged; the exact diff is committed under the benchmark results.
- The quiet baseline scaling run completed with the fixed 5 warmups, 15 samples, and 1.8 normalized ceiling. A loaded candidate diagnostic exposed two native AST costs: parent lookup descends from the root, and indexed child lookup rescans siblings. Three deterministic regressions failed with semantic controls passing (parent work 66,564 and 265,092 versus 4,096; sibling work 69,906 versus 8,192). U2/U3 now record traversal parents and use one bulk child array per node; the three complexity cases and 376 semantic tests pass, as do the build, test typecheck, and scoped lint (warnings only). Earlier broad/full candidate runs were canceled before changing production code; none is reported as complete.
- U6 documentation is updated. Receiver accuracy passes; tool accuracy exactly matches the baseline (29/32 answers, three documented gaps, regression gate passes).
- Review and simplification fixes are committed as `67c268e88`, `6f28dd6c7`, `a8bbc00ec`, `fe67b0856`, `205787b2c` and `47d09da4a`: wrapped assignment targets are writes, wrappers resolve through overloads, declarator lists, barrels, HOCs, CommonJS exports, object keys and fetch packages, and per-file HTTP contexts are released after use. `c41ad6ea9` replaces recursion in the new traversals with explicit stacks.
- Profiling the 512-unit wrapper arm showed native node construction (`namedChildren`, `childForFieldName`, `id`) dominating context construction. `7fcf3506c` limits the lexical-binding walk to functions whose formals contain an expression; `6061ca71b` collects wrapper evidence in one tree-cursor walk that materializes only inspected nodes and keys declarations by start offset. On the 512-unit wrapper workload, context construction fell from 58 to 48 ms.
- Review of `61de364ff` found that star exports reaching two export names of one declaration (`export { request, request as send }` behind two barrels) were counted as conflicting, which blocked the import and dropped its FETCHES edge. `4d62bd045` keys star-export candidates by the declaration each name refers to; distinct declarations stay ambiguous. A unit diamond and a real-parser fixture pair cover both cases; with the fix reverted only the diamond edge disappears.
- A multi-lane review of `5c179994c` (review 5575463241) found two recall regressions and several smaller gaps; `3c00b9f32` and `d3c357276` fix them. CommonJS wrappers captured as their assignment produce facts again. Name-only fallback considers only definitions that can be the target (module-level exports for an unresolvable import, top-level functions for an undeclared global). Only possible wrappers and module-level functions are emitted, and the index is built only with routes and candidate calls. Rebound bindings prove no wrapper across files; `(<T>x) = …` is a write; calls inside recovered syntax and instance-field initializers resolve; local exports make star-export conflicts visible; resolved barrel frames are shared; HTTP hooks are guarded per file and failed files still record their function names; an undeclared constructor write keeps its type for reads in the writing scope. Each behavior row fails on the previous source. The receiver baseline counts one new dropped write from the added CommonJS fixture (`9c4821106`).
- A behavior-preserving simplification pass (`3db8657ba`) shares the CommonJS `module`/`exports` checks, derives `LEXICAL_FUNCTION_TYPES` from the TypeScript `FUNCTION_NODE_TYPES`, reads each node's type once in the route-facts loop, and returns the latest-starting scope from the position index before the max-end search when it already contains the point. Focused suites (5019 tests), build, typechecks and lint pass; the resolver integration files that timed out at 30 s on the 9p checkout pass with a 120 s limit.
- Review fixes in `c263c4f72` retain fetch evidence from destructuring defaults (shorthand, renamed, array and local forms), count each binding initialization once, and record parenthesized default exports. JS/TS/TSX regression rows fail against the previous source, and two fixture consumers cover imported wrappers. The commit also clarifies failed-extraction fallback records and the collapsed parameter/body environment test boundary. All 73 CI checks pass for this revision; the refreshed receiver check matches the existing baseline.
- Final semantic comparison at `c263c4f72` (export fingerprint `4db24f57…`, clean tree, unchanged since `6061ca71b`) keeps the single expected CALLS change; the other 431 CALLS and all 11 override edges match the baseline export `3e00ca5b…`. Both exports use the same frozen 432-file corpus (`88be1faf…`).
- Final scaling at `c263c4f72` against baseline `565e50276` ran back to back on CPU 23; the host's 1-minute load, sampled every 30 s in an uncommitted log, had a median of 1.50 and peaked at 4.53. The largest candidate factor is 1.245 (rounded), below the 1.8 ceiling. The baseline fails six of nine arms: `position-index`, `position-deep-completed`, `nested-helpers`, `nested-helper-chain`, `reverse-chain` and `name-collisions`. Workload fingerprints match except `name-collisions`, where the baseline's false positive is recorded as `known-baseline-failure`. For the three arms that were already linear, candidate median times relative to baseline at the largest input are 1.07x spread aliases, 1.00x completed scopes and 0.99x wrapper aliases (between 1.01x and 1.24x across earlier pairs; run-to-run noise on this host is about 0.1x).
- The full suite passed in CI at `61de364ff` (1269 files passed and 12 skipped; 27194 tests passed, 83 skipped, none failed) and again at `5c179994c` (73 checks green). A local full run on the 9p checkout was stopped after four hours in the serial database lane, where real-analysis tests hit their timeouts; it is not recorded as a pass. At `528ea1478`, focused suites (5019 tests), HTTP integration (56), build, test typecheck, lint and formatting pass; receiver accuracy matches the updated baseline and tool accuracy matches (29/32).
- Graph impact/change checks remain unavailable: neither repository-wide indexing attempt published an index. Source caller tracing supplements this unknown result; no clean or low-risk graph result is claimed.

34
docs/wiki-generation.md Normal file
View file

@ -0,0 +1,34 @@
# Wiki generation
[Back to GitNexus](../README.md)
Generate LLM-powered documentation from your knowledge graph:
```bash
# Requires an LLM API key (OPENAI_API_KEY, etc.)
gitnexus wiki
# Use a custom model or provider (default model: minimax/minimax-m2.5)
gitnexus wiki --model gpt-4o
gitnexus wiki --base-url https://api.anthropic.com/v1
gitnexus wiki --provider grok # local Grok Build CLI (uses `grok login`, no API key)
# Force full regeneration
gitnexus wiki --force
# Increase the timeout or retries for large codebases or slow LLM providers
gitnexus wiki --timeout <seconds> # LLM request timeout in seconds (default: disabled)
gitnexus wiki --retries <n> # Max LLM retry attempts per request (default: 3)
# Allow a specific LAN/self-hosted HTTP LLM host (HTTPS is preferred for remote endpoints)
gitnexus wiki --base-url http://llama-box.local:8080/v1 --allow-insecure-connection llama-box.local
# Or set a comma-separated host allowlist:
GITNEXUS_ALLOW_INSECURE_CONNECTION=llama-box.local,192.168.1.23
# Change the output language
gitnexus wiki --lang <lang> # e.g. english, chinese, spanish, japanese
```
For safety, `http://` LLM base URLs are allowed by default only for loopback hosts (`localhost`, `127.0.0.1`, `::1`). `--allow-insecure-connection` and `GITNEXUS_ALLOW_INSECURE_CONNECTION` accept exact hostnames or IP addresses only; do not include schemes, ports, paths, credentials, or wildcards.
The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.

View file

@ -6,6 +6,7 @@ import os
import re
import subprocess
import sys
import time
import yaml
import pytest
@ -87,7 +88,7 @@ def test_pickup_watchdog_names_the_paid_job_it_bounds(name, paid, watch):
def test_release_comparison_is_scheduled_or_manual_and_gates_outcomes():
document = workflow("release-evaluation.yml")
# PyYAML parses the bare `on` key as True.
assert set(document[True]) == {"schedule", "workflow_dispatch"}
assert set(document[True]) == {"schedule", "workflow_dispatch", "workflow_call"}
steps = document["jobs"]["evaluate"]["steps"]
scripts = "\n".join(step.get("run", "") for step in steps)
assert "releases/latest" in scripts
@ -95,6 +96,130 @@ def test_release_comparison_is_scheduled_or_manual_and_gates_outcomes():
assert "--stable-sha" in scripts and "--candidate-sha" in scripts
def test_pr_preview_uses_trusted_main_and_authenticates_history_before_paid_sessions():
document = workflow("release-evaluation.yml")
inputs = document[True]["workflow_dispatch"]["inputs"]
preview_inputs = {"candidate_pr", "expected_pr_sha", "comparison_run_id"}
assert preview_inputs.isdisjoint(inputs)
call_inputs = document[True]["workflow_call"]["inputs"]
assert preview_inputs <= call_inputs.keys()
assert all(call_inputs[key]["required"] for key in preview_inputs)
job = document["jobs"]["evaluate"]
assert "refs/heads/main" in job["if"]
assert job["environment"] == "gitnexus-evolution"
assert job["permissions"] == {"contents": "read", "actions": "read", "pull-requests": "read"}
steps = job["steps"]
resolve = next(step for step in steps if step.get("id") == "resolve")
assert "workflow_bench.pr_evaluation resolve" in resolve["run"]
assert '--sha "$INPUT_PR_SHA"' in resolve["run"]
# Standard release candidates still require reviewed main ancestry.
assert 'git merge-base --is-ancestor "$sha" HEAD' in resolve["run"]
baseline = next(step for step in steps if "workflow_bench.pr_evaluation baseline" in step.get("run", ""))
paid = next(step for step in steps if "workflow_bench.runner" in step.get("run", ""))
assert steps.index(baseline) < steps.index(paid)
assert "inputs.candidate_pr != ''" in baseline["if"]
assert 'arms=(baseline)' in paid["run"]
dependencies = next(step for step in steps if "workflow_bench.pr_evaluation dependencies" in step.get("run", ""))
assert steps.index(dependencies) < steps.index(paid)
assert "inputs.candidate_pr != ''" in dependencies["if"]
opt_in = next(step for step in steps if step.get("name", "").startswith("Recheck PR opt-in"))
assert steps.index(opt_in) + 1 == steps.index(paid)
assert 'workflow_bench.pr_evaluation resolve' in opt_in["run"]
assert "inputs.candidate_pr != ''" in opt_in["if"]
def test_cost_request_is_label_only_and_executes_trusted_base_code():
document = workflow("pr-cost-evaluation.yml")
assert document[True] == {"pull_request_target": {"types": ["labeled"], "branches": ["main"]}}
assert document["permissions"] == {}
job = document["jobs"]["request"]
assert "github.event.label.name == 'run-cost-evaluation'" in job["if"]
assert "github.run_attempt == 1" in job["if"]
assert job["runs-on"] == "ubuntu-latest" and "environment" not in job
assert job["permissions"] == {"contents": "read", "pull-requests": "read", "actions": "read"}
checkout, dispatch = job["steps"]
assert checkout["with"] == {"ref": "${{ github.sha }}", "persist-credentials": False}
assert "dispatch-label" in dispatch["run"] and '"$GITHUB_EVENT_PATH"' in dispatch["run"]
assert "${{ github.event." not in dispatch["run"]
assert '"$GITHUB_OUTPUT"' in dispatch["run"]
evaluate = document["jobs"]["evaluate"]
assert evaluate["needs"] == ["request"]
assert evaluate["if"] == "needs.request.outputs.run_attempt == github.run_attempt"
assert evaluate["uses"] == "./.github/workflows/release-evaluation.yml"
expected_secrets = {
"GITNEXUS_EVOLUTION_AWS_ROLE_ARN", "GITNEXUS_EVOLUTION_EC2_INSTANCE_ID",
"GITNEXUS_BENCH_OPENAI_API_KEY", "GITNEXUS_BENCH_ANTHROPIC_API_KEY",
}
assert evaluate["secrets"] == {key: "${{ secrets." + key + " }}" for key in expected_secrets}
assert set(workflow("release-evaluation.yml")[True]["workflow_call"]["secrets"]) == expected_secrets
assert evaluate["with"] == {
"candidate_pr": "${{ needs.request.outputs.pr }}",
"expected_pr_sha": "${{ needs.request.outputs.sha }}",
"comparison_run_id": "${{ needs.request.outputs.comparison_run_id }}",
}
def test_pr_preview_cannot_publish_release_approval_evidence():
steps = workflow("release-evaluation.yml")["jobs"]["evaluate"]["steps"]
gate = next(step for step in steps if "workflow_bench.release_gate" in step.get("run", ""))
assert "inputs.candidate_pr == ''" in gate["if"]
uploads = [step for step in steps if step.get("uses", "").startswith("actions/upload-artifact@")]
release = next(step for step in uploads if step["with"]["name"].startswith("release-agent-evaluation-"))
preview = next(step for step in uploads if step["with"]["name"].startswith("pr-cost-comparison-"))
assert "inputs.candidate_pr == ''" in release["if"]
assert "inputs.candidate_pr != ''" in preview["if"]
assert "agent-evaluation.json" not in preview["with"]["path"]
assert "pr-cost-comparison.json" in preview["with"]["path"]
@pytest.mark.parametrize("pr,runtimes,arms", [
("3621", ["candidate"], ["baseline"]),
("", ["stable", "candidate"], ["baseline_nomcp", "baseline"]),
])
def test_real_paid_step_selects_only_the_requested_runtime_and_arms(tmp_path, pr, runtimes, arms):
steps = workflow("release-evaluation.yml")["jobs"]["evaluate"]["steps"]
script = next(step["run"] for step in steps if "workflow_bench.runner" in step.get("run", ""))
script = re.sub(r"\$\{\{.*?\}\}", str(int(time.time()) + 7200), script)
# Exercise the real shell branching without running a model or a timeout.
binary = tmp_path / "uv"
binary.write_text(
f"#!{sys.executable}\n"
"import json, os, sys\n"
"with open(os.environ['CAPTURE_ARGS'], 'a') as output:\n"
" output.write(json.dumps(sys.argv[1:]) + '\\n')\n"
)
binary.chmod(0o755)
log = tmp_path / "arguments.jsonl"
subprocess.run(
["bash", "--noprofile", "--norc", "-c", script], check=True, capture_output=True,
env={**os.environ, "PATH": f"{tmp_path}:{os.defpath}", "CAPTURE_ARGS": str(log),
"INPUT_PR": pr, "MODEL": "gpt-5.6-sol", "EFFORT": "xhigh",
"GITHUB_WORKSPACE": str(tmp_path), "RUNNER_TEMP": str(tmp_path)},
)
calls = [json.loads(line) for line in log.read_text().splitlines()]
assert len(calls) == len(runtimes)
for arguments, runtime in zip(calls, runtimes, strict=True):
assert arguments[arguments.index("--gitnexus-root") + 1] == str(tmp_path / runtime)
assert arguments[arguments.index("--arms") + 1:arguments.index("--runs")] == arms
assert arguments[arguments.index("--runs") + 1] == "3"
def test_release_session_headroom_keeps_the_global_stop_reserve():
steps = workflow("release-evaluation.yml")["jobs"]["evaluate"]["steps"]
paid = next(step for step in steps if "workflow_bench.runner" in step.get("run", ""))
script = paid["run"]
assert "--timeout 3600" in script
assert "for runtime in stable candidate; do" in script
assert "stop_deadline_epoch }} - $(date +%s) - 5400" in script
assert 'timeout --signal=TERM --kill-after=60 "${remaining}s"' in script
assert paid["timeout-minutes"] == 1140
canary = next(step for step in steps if "tests/test_proposer_sandbox.py" in step.get("run", ""))
assert "test_real_cli_background_completion_is_one_complete_measurement" in canary["run"]
assert canary["env"]["GITNEXUS_REQUIRE_CLAUDE_CANARY"] == "1"
assert steps.index(canary) < steps.index(paid)
assert not canary.get("continue-on-error", False)
def test_both_runtimes_grade_tasks_against_one_pinned_task_dependency_checkout():
steps = workflow("release-evaluation.yml")["jobs"]["evaluate"]["steps"]
names = [step.get("name", step.get("uses", "")) for step in steps]
@ -191,6 +316,10 @@ def test_shared_lifecycle_jobs_stay_identical_across_both_ec2_workflows():
renamed = {"watch-evaluate-pickup": "watch-evolve-pickup", "evaluate": "evolve"}
for job in ("start-runner", "check-runner", "runner-ready", "stop-runner"):
expected = {key: value for key, value in evaluation[job].items() if key != "name"}
if job != "stop-runner":
preview = "(github.event_name == 'pull_request_target' && inputs.candidate_pr != '') ||\n "
assert expected["if"].count(preview) == 1
expected["if"] = expected["if"].replace(preview, "", 1)
expected["needs"] = [renamed.get(need, need) for need in expected.get("needs", [])]
actual = {key: value for key, value in evolution[job].items() if key != "name"}
actual["needs"] = actual.get("needs", [])

View file

@ -5,6 +5,7 @@ from __future__ import annotations
import argparse
import hashlib
import os
import re
import shutil
import subprocess
import sys
@ -589,6 +590,9 @@ def scenario_control_base(tmp_path_factory: pytest.TempPathFactory) -> tuple[Pat
ref,
"gitnexus/src",
"gitnexus/vendor",
"gitnexus/test",
"gitnexus/tsconfig.json",
"gitnexus/vitest.config.ts",
"gitnexus/package.json",
"gitnexus-shared/package.json",
],
@ -607,7 +611,7 @@ def scenario_control_base(tmp_path_factory: pytest.TempPathFactory) -> tuple[Pat
pytest.skip("oracle controls need tarfile extraction filters (Python 3.11.4+)")
with tarfile.open(archive) as source:
source.extractall(base, filter="data")
for relative in ("node_modules", "gitnexus/node_modules", "gitnexus-shared/dist"):
for relative in ("node_modules", "gitnexus/node_modules", "gitnexus-shared/node_modules", "gitnexus-shared/dist"):
(base / relative).symlink_to(dependencies / relative, target_is_directory=True)
subprocess.run(["git", "init", "--quiet", str(base)], check=True, capture_output=True)
return base, {task["id"]: task for task in tasks}
@ -633,12 +637,82 @@ def _verify_shipped_oracle(candidate: Path, task: dict[str, object]) -> subproce
)
def _assert_behavioral_rejection(completed: subprocess.CompletedProcess[str], assertion: str = "") -> None:
output = completed.stdout + completed.stderr
assert completed.returncode == 1, output
assert "AssertionError" in output, output
assert assertion in output, output
# An import/setup crash is not evidence that a behavioral control worked.
assert "Failed Suites" not in output, output
assert "Unhandled Errors" not in output, output
def _check_c_provenance_mutants(candidate: Path, base: Path, task: dict[str, object]) -> None:
"""Reject broken behavior, and distinguish module-load errors from evidence."""
interpret = Path("gitnexus/src/core/ingestion/languages/c/interpret.ts")
resolver = Path("gitnexus/src/core/ingestion/languages/c/scope-resolver.ts")
valid_interpret = (candidate / interpret).read_text()
valid_resolver = (candidate / resolver).read_text()
system_guards = re.findall(
r"\bconst\s+parsedImport\s*=\s*context\s*\?\.\s*parsedImport\s*;\s*"
r"if\s*\(\s*parsedImport\s*\?\.\s*kind\s*===\s*'wildcard'\s*&&\s*"
r"'isSystem'\s+in\s+parsedImport\s*&&\s*parsedImport\s*\.\s*isSystem\s*===\s*true\s*\)\s*"
r"\{\s*return\s+null\s*;\s*\}",
valid_resolver,
)
fallbacks = re.findall(
r"\breturn\s+resolveCImportTarget\s*\(\s*targetRaw\s*,\s*fromFile\s*,\s*allFilePaths\s*,?\s*\)\s*;",
valid_resolver,
)
assert len(system_guards) == 1, "expected exactly one C system-include guard"
assert len(fallbacks) == 1, "expected exactly one C resolver fallback"
system_guard, fallback = system_guards[0], fallbacks[0]
late_guard_resolver = valid_resolver.replace(system_guard, "").replace(fallback, system_guard + "\n " + fallback)
assert valid_interpret.count("return parsedImport;") == 1
assert valid_interpret.count("targetRaw: source,") == 1
mutants = [
(interpret, (base / interpret).read_text(), "literal include <stdio.h> must be retained"),
(
interpret,
valid_interpret.replace("return parsedImport;", "return null;"),
'literal include "stdio.h" must be retained',
),
(interpret, valid_interpret.replace("targetRaw: source,", "targetRaw: '',"), "retained header identity"),
(resolver, (base / resolver).read_text(), "include <stdio.h> resolution"),
(resolver, late_guard_resolver, "include <stdio.h> resolution"),
]
for relative, broken, assertion in mutants:
path = candidate / relative
original = path.read_text()
assert broken != original
path.write_text(broken)
try:
_assert_behavioral_rejection(_verify_shipped_oracle(candidate, task), assertion)
finally:
path.write_text(original)
# A missing native-parser module must fail setup, never satisfy a negative
# behavioral control just because Vitest exits nonzero.
parser = candidate / "gitnexus/src/core/ingestion/languages/c/query.ts"
original_parser = parser.read_bytes()
parser.unlink()
try:
broken_setup = _verify_shipped_oracle(candidate, task)
assert "Failed Suites" in broken_setup.stdout + broken_setup.stderr
with pytest.raises(AssertionError):
_assert_behavioral_rejection(broken_setup, "literal include <stdio.h> must be retained")
finally:
parser.write_bytes(original_parser)
@pytest.mark.skipif(os.name == "nt", reason="oracle controls use POSIX dependency symlinks and shell commands")
@pytest.mark.parametrize(
("task_id", "reference"),
[
("trivial-status-json-alias", "trivial-status-json-alias"),
("inv-bug-c-system-include", "inv-bug-c-system-include"),
("inv-feature-c-include-provenance", "inv-feature-c-include-provenance-flag"),
("inv-feature-c-include-provenance", "inv-feature-c-include-provenance-delimiter"),
("inv-feature-list-repos-filter", "inv-feature-list-repos-filter"),
("cross-module-parse-retry", "cross-module-parse-retry"),
("cross-module-parse-retry", "cross-module-parse-retry-pool"),
@ -653,13 +727,37 @@ def test_shipped_oracles_reject_task_base_and_accept_reference_fixes(
base, tasks = scenario_control_base
candidate = _oracle_control_candidate(base, tmp_path / "candidate")
negative = _verify_shipped_oracle(candidate, tasks[task_id])
assert negative.returncode == 1, negative.stdout + negative.stderr
assert "AssertionError" in negative.stdout + negative.stderr
_assert_behavioral_rejection(
negative,
"literal include <stdio.h> must be retained" if task_id == "inv-feature-c-include-provenance" else "",
)
patches = Path(__file__).resolve().parents[1] / "workflow_bench/oracles/reference"
subprocess.run(["git", "apply", str(patches / f"{reference}.patch")], cwd=candidate, check=True)
positive = _verify_shipped_oracle(candidate, tasks[task_id])
assert positive.returncode == 0, positive.stdout + positive.stderr
if task_id == "inv-feature-c-include-provenance":
# A reference passing transpile-only Vitest is not enough: use the same
# typed, authored verification that an evaluated repair must satisfy.
authored = subprocess.run(
["/bin/sh", "-c", str(tasks[task_id]["verify"])],
cwd=candidate,
capture_output=True,
text=True,
check=False,
timeout=180,
)
assert authored.returncode == 0, authored.stdout + authored.stderr
if reference == "inv-feature-c-include-provenance-flag":
# This entry point is already selected by native CI; keep every C
# validity control reachable without changing workflow selection.
# Indent every existing code line differently without matching the
# reference's formatting; the behavioral controls must still work.
resolver = candidate / "gitnexus/src/core/ingestion/languages/c/scope-resolver.ts"
resolver.write_text(re.sub(r"(?m)^([ \t]+)", r"\t\1", resolver.read_text()))
positive = _verify_shipped_oracle(candidate, tasks[task_id])
assert positive.returncode == 0, positive.stdout + positive.stderr
_check_c_provenance_mutants(candidate, base, tasks[task_id])
@pytest.mark.skipif(os.name == "nt", reason="oracle controls use POSIX dependency symlinks and shell commands")

View file

@ -0,0 +1,601 @@
"""PR cost measurements retain the historical task pins and quality floor."""
import json
from copy import deepcopy
from datetime import UTC, datetime
import pytest
import yaml
from workflow_bench import pr_evaluation
from workflow_bench.release_report import build_report, validate_report
NOW = datetime.now(UTC)
OLD = "a" * 40
NEW = "b" * 40
HARNESS = "c" * 40
REPO = "owner/repo"
@pytest.fixture
def evidence():
metadata = {
"runtime_sha": OLD,
"harness_sha": OLD,
"task_set_digest": "d" * 64,
"model": "gpt-5.6-sol",
"effort": "xhigh",
"runs": 3,
"tasks": {name: {"sha": "e" * 40, "oracle_digest": "f" * 64} for name in ("one", "two")},
}
rows = [
{
"task": task,
"run": run,
"arm": arm,
"model": metadata["model"],
"effort": "xhigh",
"task_base_sha": "e" * 40,
"oracle_digest": "f" * 64,
"sandbox_backend": "bwrap",
"sandbox_dependency_content_digest": "9" * 64,
"ok": True,
"resolved": True,
"authored_tests_passed": True,
"oracle_passed": True,
"error_kind": None,
"transcript_missing": False,
"cost_usd": 1.0,
"duration_s": 60.0,
}
for task in metadata["tasks"]
for run in range(3)
for arm in ("baseline_nomcp", "baseline")
]
previous = build_report(rows, metadata, now=NOW)
candidate = [
{**row, "cost_usd": 0.8, "internal_path": "/private/transcript"} for row in rows if row["arm"] == "baseline"
]
return previous, candidate, {**metadata, "runtime_sha": NEW, "harness_sha": HARNESS}
def compare(evidence):
previous, rows, metadata = evidence
return pr_evaluation.compare_candidate(
rows, metadata, previous, candidate_sha=NEW, pr=3621, baseline_run=39039452570, now=NOW
)
def test_comparison_measures_only_new_mcp_cells_and_preserves_historical_cost(evidence):
before = deepcopy(evidence)
report = compare(evidence)
assert report["complete"] and report["quality_preserved"] and report["improved"]
assert report["previous"]["total_cost_usd"] == 6
assert report["candidate"]["total_cost_usd"] == pytest.approx(4.8)
assert report["cost_reduction_pct"] == pytest.approx(20)
assert report["candidate"]["solved"] == report["previous"]["solved"] == 6
assert len(report["per_run"]) == 6
assert all(row["arm"] == "baseline" and "internal_path" not in row for row in report["per_run"])
assert evidence == before
assert "not release approval" in pr_evaluation.render_markdown(report)
with pytest.raises(ValueError, match="unsupported"):
validate_report(report, runtime_sha=NEW, task_set_digest=evidence[0]["task_set_digest"], now=NOW)
@pytest.mark.parametrize(
"change",
[
lambda rows: rows.pop(),
lambda rows: rows.append(dict(rows[0])),
lambda rows: rows[0].update(cost_usd=None),
lambda rows: rows[0].update(cost_usd=float("nan")),
lambda rows: rows[0].update(cost_usd=10**1000),
lambda rows: rows[0].update(duration_s=-1),
lambda rows: rows[0].update(model="other-model"),
lambda rows: rows[0].update(task_base_sha="0" * 40),
lambda rows: rows[0].update(oracle_digest="0" * 64),
lambda rows: rows[0].update(sandbox_dependency_content_digest="0" * 64),
lambda rows: rows[0].update(sandbox_backend="host-unsafe"),
lambda rows: rows[0].update(error_kind="session-error", ok=False),
lambda rows: rows[0].update(transcript_missing=True),
lambda rows: rows[0].update(arm="baseline_nomcp"),
lambda rows: rows[0].update(resolved="true"),
lambda rows: rows[0].update(oracle_passed=False),
lambda rows: rows.append(None),
],
)
def test_incomplete_or_mismatched_cells_cannot_claim_savings(evidence, change):
change(evidence[1])
report = compare(evidence)
assert not report["complete"] and not report["improved"]
assert report["problems"]
assert report["cost_reduction_pct"] is None
json.dumps(report, allow_nan=False)
def test_lower_cost_with_a_per_task_solve_regression_is_not_an_improvement(evidence):
evidence[1][0].update(resolved=False, oracle_passed=False, error_kind="oracle-failed")
report = compare(evidence)
assert report["complete"] and not report["quality_preserved"] and not report["improved"]
assert report["tasks"]["one"]["solve_delta"] == -1
@pytest.mark.parametrize(
"field,value",
[
("runtime_sha", OLD),
("model", "other"),
("effort", "high"),
("runs", 1),
("task_set_digest", "0" * 64),
("tasks", {}),
],
)
def test_candidate_metadata_must_match_the_requested_revision_and_previous_protocol(evidence, field, value):
evidence[2][field] = value
assert not compare(evidence)["complete"]
def test_cost_regression_remains_a_valid_measurement(evidence):
for row in evidence[1]:
row["cost_usd"] = 1.1
report = compare(evidence)
assert report["complete"] and report["quality_preserved"] and not report["improved"]
assert report["cost_reduction_pct"] == pytest.approx(-10)
def pr_payload():
return {
"state": "open",
"head": {"sha": NEW},
"base": {"ref": "main", "repo": {"full_name": REPO}},
"labels": [{"name": pr_evaluation.COST_LABEL}],
}
def test_pr_resolution_is_bound_to_the_explicit_reviewed_sha(monkeypatch):
monkeypatch.setattr(pr_evaluation, "_gh_json", lambda endpoint: pr_payload())
assert pr_evaluation.resolve_pr(REPO, 3621, NEW) == NEW
@pytest.mark.parametrize(
"mutation",
[
lambda pr: pr.update(state="closed"),
lambda pr: pr["head"].update(sha=OLD),
lambda pr: pr["base"].update(ref="feature"),
lambda pr: pr["base"]["repo"].update(full_name="other/repo"),
lambda pr: pr.update(labels=[]),
lambda pr: pr.pop("labels"),
],
)
def test_moved_or_wrong_target_pr_is_rejected_before_paid_work(monkeypatch, mutation):
payload = pr_payload()
mutation(payload)
monkeypatch.setattr(pr_evaluation, "_gh_json", lambda endpoint: payload)
with pytest.raises(ValueError):
pr_evaluation.resolve_pr(REPO, 3621, NEW)
@pytest.fixture
def label_request(monkeypatch):
event = {
"repository": {"full_name": REPO},
"action": "labeled",
"label": {"name": pr_evaluation.COST_LABEL},
"sender": {"login": "maintainer"},
"number": 3621,
"pull_request": pr_payload(),
}
run = {
"id": 90,
"conclusion": "success",
"head_branch": "main",
"event": "workflow_dispatch",
"head_repository": {"full_name": REPO},
"head_sha": OLD,
}
payloads = {
f"repos/{REPO}/collaborators/maintainer/permission": {"permission": "write", "role_name": "maintain"},
f"repos/{REPO}/pulls/3621": pr_payload(),
f"repos/{REPO}/actions/workflows/release-evaluation.yml/runs?branch=main&status=success&per_page=100": {
"workflow_runs": [run],
},
f"repos/{REPO}/actions/runs/90/artifacts?per_page=100": {
"total_count": 1,
"artifacts": [{"name": f"release-agent-evaluation-{OLD}", "expired": False}],
},
}
calls = []
monkeypatch.setattr(pr_evaluation, "_gh_json", payloads.__getitem__)
monkeypatch.setattr(pr_evaluation, "_gh", lambda args: calls.append(args))
return event, payloads, calls
def test_label_dispatch_pins_head_main_baseline_and_model(label_request):
event, _, calls = label_request
assert pr_evaluation.dispatch_labeled_pr(REPO, event) == 90
assert not calls # Requests emit outputs for a reusable job, never manual dispatch.
@pytest.mark.parametrize("permission", ["write", "read", "triage", "none", "custom-role", ""])
def test_label_requires_repository_write_permission(label_request, permission):
event, payloads, calls = label_request
payloads[f"repos/{REPO}/collaborators/maintainer/permission"]["role_name"] = permission
with pytest.raises(ValueError, match="repository maintainers or administrators"):
pr_evaluation.dispatch_labeled_pr(REPO, event)
assert not calls
@pytest.mark.parametrize("role,permission", [("maintain", "write"), ("admin", "admin")])
def test_maintain_and_admin_roles_may_request_comparison(label_request, role, permission):
event, payloads, calls = label_request
payloads[f"repos/{REPO}/collaborators/maintainer/permission"].update(role_name=role, permission=permission)
assert pr_evaluation.dispatch_labeled_pr(REPO, event) == 90
assert not calls
def test_missing_role_does_not_grant_maintainer_authority(label_request):
event, payloads, calls = label_request
payloads[f"repos/{REPO}/collaborators/maintainer/permission"].pop("role_name")
with pytest.raises(ValueError, match="maintainers"):
pr_evaluation.dispatch_labeled_pr(REPO, event)
assert not calls
def test_label_cli_emits_validated_reusable_workflow_outputs(label_request, monkeypatch, tmp_path, capsys):
event, _, calls = label_request
source = tmp_path / "event.json"
source.write_text(json.dumps(event))
monkeypatch.setattr("sys.argv", ["pr_evaluation", "dispatch-label", "--repo", REPO, "--event", str(source)])
pr_evaluation.main()
assert capsys.readouterr().out == f"pr=3621\nsha={NEW}\ncomparison_run_id=90\n"
assert not calls
@pytest.mark.parametrize(
"mutation",
[
lambda event: event.update(action="synchronize"),
lambda event: event["label"].update(name="run-ci"),
lambda event: event["repository"].update(full_name="other/repo"),
lambda event: event["sender"].update(login="name/permission"),
],
)
def test_unrelated_events_never_dispatch(label_request, mutation):
event, _, calls = label_request
mutation(event)
with pytest.raises(ValueError):
pr_evaluation.dispatch_labeled_pr(REPO, event)
assert not calls
@pytest.mark.parametrize(
"mutation",
[
lambda pr: pr.update(labels=[]),
lambda pr: pr["head"].update(sha=OLD),
],
)
def test_label_or_head_changed_during_discovery_never_dispatches(label_request, monkeypatch, mutation):
event, payloads, calls = label_request
reads = 0
def api(endpoint):
nonlocal reads
if endpoint == f"repos/{REPO}/pulls/3621":
reads += 1
if reads == 2:
mutation(payloads[endpoint])
return payloads[endpoint]
monkeypatch.setattr(pr_evaluation, "_gh_json", api)
with pytest.raises(ValueError):
pr_evaluation.dispatch_labeled_pr(REPO, event)
assert reads == 2 and not calls
@pytest.mark.parametrize(
"artifact",
[
{"name": f"pr-cost-comparison-{NEW}", "expired": False},
{"name": f"release-agent-evaluation-{OLD}", "expired": True},
None,
],
)
def test_label_skips_preview_expired_and_probe_runs(label_request, artifact):
event, payloads, calls = label_request
runs = next(value["workflow_runs"] for value in payloads.values() if "workflow_runs" in value)
runs.insert(0, {**runs[0], "id": 91})
payloads[f"repos/{REPO}/actions/runs/91/artifacts?per_page=100"] = {
"total_count": int(artifact is not None),
"artifacts": [] if artifact is None else [artifact],
}
assert pr_evaluation.dispatch_labeled_pr(REPO, event) == 90
assert not calls
def test_label_without_a_full_baseline_does_not_dispatch(label_request):
event, payloads, calls = label_request
payloads[f"repos/{REPO}/actions/runs/90/artifacts?per_page=100"]["artifacts"] = []
with pytest.raises(ValueError, match="no full successful"):
pr_evaluation.dispatch_labeled_pr(REPO, event)
assert not calls
def test_previous_measurement_accepts_only_preview_orchestration_changes(monkeypatch):
monkeypatch.setattr(
pr_evaluation,
"_gh_json",
lambda endpoint: {"status": "ahead", "files": [{"filename": "eval/workflow_bench/pr_evaluation.py"}]},
)
pr_evaluation.require_comparable_harness(REPO, OLD, HARNESS)
@pytest.fixture
def workflow_protocol_pair():
old = {
"jobs": {
"evaluate": {
"runs-on": "self-hosted",
"environment": "gitnexus-evolution",
"timeout-minutes": 1260,
"env": {"MODEL": "gpt-5.6-sol", "EFFORT": "xhigh"},
"steps": [
{"uses": "setup-node@abc", "with": {"node-version": "22"}},
{"name": "Prepare", "run": "uv run prepare --runs 3\n"},
{
"name": "Run",
"timeout-minutes": 1140,
"run": (
"set -euo pipefail\nfor runtime in stable candidate; do\n"
" uv run --locked --extra dev python -m workflow_bench.runner "
"--arms baseline_nomcp baseline --runs 3 --include-expensive "
"--workers 3 --timeout 3600\ndone\n"
),
},
],
}
},
}
new = deepcopy(old)
job = new["jobs"]["evaluate"]
job["env"].update(INPUT_PR="3621", INPUT_PR_SHA=NEW, COMPARISON_RUN_ID="42")
job["steps"][-1]["run"] = (
"set -euo pipefail\narms=(baseline_nomcp baseline)\n"
'if [[ -n "$INPUT_PR" ]]; then arms=(baseline); fi\n'
"for runtime in stable candidate; do\n"
' if [[ -n "$INPUT_PR" && "$runtime" == stable ]]; then continue; fi\n'
" uv run --locked --extra dev python -m workflow_bench.runner "
'--arms "${arms[@]}" --runs 3 --include-expensive '
"--workers 3 --timeout 3600\ndone\n"
)
return old, new
def test_changed_workflow_requires_matching_measurement_protocol(monkeypatch, workflow_protocol_pair):
old, new = workflow_protocol_pair
monkeypatch.setattr(
pr_evaluation,
"_gh_json",
lambda endpoint: {
"status": "ahead",
"files": [{"filename": pr_evaluation.EVALUATION_WORKFLOW}],
},
)
calls = []
def api(args):
calls.append(args)
return yaml.safe_dump(old if f"ref={OLD}" in args[1] else new)
monkeypatch.setattr(pr_evaluation, "_gh", api)
pr_evaluation.require_comparable_harness(REPO, OLD, HARNESS)
assert len(calls) == 2 and all("Accept: application/vnd.github.raw+json" in call for call in calls)
new["jobs"]["evaluate"]["steps"][-1]["run"] += "echo changed measurement\n"
with pytest.raises(ValueError, match="measurement protocol changed"):
pr_evaluation.require_comparable_harness(REPO, OLD, HARNESS)
@pytest.mark.parametrize(
"before,after",
[
("--workers 3", "--workers 1"),
("--timeout 3600", "--timeout 60"),
("--runs 3", "--runs 2"),
(" --include-expensive", ""),
("arms=(baseline);", "arms=(baseline_nomcp);"),
],
)
def test_workflow_protocol_rejects_changed_paid_settings(workflow_protocol_pair, before, after):
old, new = workflow_protocol_pair
step = new["jobs"]["evaluate"]["steps"][-1]
step["run"] = step["run"].replace(before, after)
assert pr_evaluation.measurement_protocol(yaml.safe_dump(old)) != pr_evaluation.measurement_protocol(
yaml.safe_dump(new)
)
@pytest.mark.parametrize(
"mutation",
[
lambda job: job["steps"][0]["with"].update({"node-version": "24"}),
lambda job: job["steps"][-1].update({"timeout-minutes": 1200}),
lambda job: job["env"].update(MODEL="another-model"),
lambda job: job["env"].update(ANTHROPIC_BASE_URL="another-provider"),
lambda job: job["steps"][1].update(run="uv run prepare --runs 2\n"),
],
)
def test_workflow_protocol_rejects_changed_setup_or_environment(workflow_protocol_pair, mutation):
old, new = workflow_protocol_pair
mutation(new["jobs"]["evaluate"])
assert pr_evaluation.measurement_protocol(yaml.safe_dump(old)) != pr_evaluation.measurement_protocol(
yaml.safe_dump(new)
)
def test_workflow_protocol_rejects_extra_paid_invocations(workflow_protocol_pair):
_, new = workflow_protocol_pair
new["jobs"]["evaluate"]["steps"].append({"run": "python -m workflow_bench.runner"})
with pytest.raises(ValueError, match="one paid"):
pr_evaluation.measurement_protocol(yaml.safe_dump(new))
@pytest.mark.parametrize(
"comparison",
[
{"status": "diverged", "files": []},
{"status": "ahead"},
{"status": "ahead", "files": [{"filename": "eval/workflow_bench/runner.py"}]},
{"status": "ahead", "files": [{"filename": ".github/claude-canary-runtime/package-lock.json"}]},
{"status": "ahead", "files": [{"filename": "other.py", "previous_filename": "eval/workflow_bench/runner.py"}]},
{"status": "ahead", "files": [{"filename": "other.py"}] * 300},
],
)
def test_changed_measurement_inputs_or_unknown_history_reject_previous_evidence(monkeypatch, comparison):
monkeypatch.setattr(pr_evaluation, "_gh_json", lambda endpoint: comparison)
with pytest.raises(ValueError):
pr_evaluation.require_comparable_harness(REPO, OLD, HARNESS)
@pytest.fixture
def github(evidence, monkeypatch):
from workflow_bench import release_report
previous = evidence[0]
payload = {
"run": {
"id": 42,
"path": ".github/workflows/release-evaluation.yml",
"conclusion": "success",
"head_branch": "main",
"head_sha": OLD,
"event": "workflow_dispatch",
"head_repository": {"full_name": REPO},
},
"artifacts": {"total_count": 1, "artifacts": [{"name": f"release-agent-evaluation-{OLD}", "expired": False}]},
"report": previous,
}
def api(endpoint):
if "/artifacts?" in endpoint:
return payload["artifacts"]
if "/compare/" in endpoint:
return {"status": "ahead", "files": []}
return payload["run"]
def download(arguments):
from pathlib import Path
assert arguments[:4] == ["run", "download", "42", "--repo"]
assert arguments[4] == REPO
(Path(arguments[-1]) / "agent-evaluation.json").write_text(json.dumps(payload["report"]))
return ""
monkeypatch.setattr(pr_evaluation, "_gh_json", api)
monkeypatch.setattr(pr_evaluation, "_gh", download)
monkeypatch.setattr(release_report, "suite_binding", lambda: ([], previous["task_set_digest"], previous["tasks"]))
return payload
def test_baseline_download_authenticates_run_artifact_and_recomputes_report(github):
assert pr_evaluation.fetch_baseline(REPO, 42, HARNESS, "gpt-5.6-sol", "xhigh") == github["report"]
@pytest.mark.parametrize(
"mutation",
[
lambda g: g["run"].update(conclusion="failure"),
lambda g: g["run"].update(head_branch="feature"),
lambda g: g["run"].update(path=".github/workflows/other.yml"),
lambda g: g["run"].update(id=99),
lambda g: g["run"]["head_repository"].update(full_name="fork/repo"),
lambda g: g["artifacts"].update(total_count=101),
lambda g: g["artifacts"]["artifacts"][0].update(expired=True),
lambda g: g["artifacts"]["artifacts"][0].update(name=f"pr-cost-comparison-{OLD}"),
lambda g: g["report"].update(runtime_sha=NEW),
lambda g: g["report"].update(harness_sha=HARNESS),
lambda g: g["report"].update(complete=False),
lambda g: g["report"]["arms"]["baseline"].update(mean_cost_usd=0),
],
)
def test_untrusted_or_tampered_historical_evidence_is_rejected_before_paid_work(github, mutation):
mutation(github)
with pytest.raises(ValueError):
pr_evaluation.fetch_baseline(REPO, 42, HARNESS, "gpt-5.6-sol", "xhigh")
def test_cli_writes_sanitized_candidate_report_and_marks_missing_measurements_incomplete(
evidence, tmp_path, monkeypatch
):
previous, rows, metadata = evidence
baseline, results, meta, out = (tmp_path / name for name in ("previous.json", "rows.jsonl", "metadata.json", "out"))
baseline.write_text(json.dumps(previous))
meta.write_text(json.dumps(metadata))
results.write_text("\n".join(json.dumps(row) for row in rows))
monkeypatch.setattr(
"sys.argv",
[
"pr-evaluation",
"summarize",
"--results",
str(results),
"--metadata",
str(meta),
"--baseline",
str(baseline),
"--out",
str(out),
"--sha",
NEW,
"--pr",
"3621",
"--run-id",
"42",
],
)
pr_evaluation.main()
text = (out / "pr-cost-comparison.json").read_text()
assert json.loads(text)["improved"]
assert "/private/transcript" not in text
results.unlink()
with pytest.raises(SystemExit) as exc:
pr_evaluation.main()
assert exc.value.code == 1
assert not json.loads((out / "pr-cost-comparison.json").read_text())["complete"]
assert "Incomplete evidence" in (out / "pr-cost-comparison.md").read_text()
def bindings(previous):
return [
{
"id": task,
"resolved_sha": pin["sha"],
"oracle_digest": pin["oracle_digest"],
"sandbox_dependency_content_digest": "9" * 64,
}
for task, pin in previous["tasks"].items()
]
def test_dependency_preflight_accepts_identical_prepared_task_bytes(evidence):
previous = evidence[0]
pr_evaluation.check_dependency_bindings(bindings(previous), previous)
@pytest.mark.parametrize(
"mutation",
[
lambda bs: bs.pop(),
lambda bs: bs.append(dict(bs[0])),
lambda bs: bs[0].update(resolved_sha=NEW),
lambda bs: bs[0].update(oracle_digest="0" * 64),
lambda bs: bs[0].update(sandbox_dependency_content_digest="0" * 64),
],
)
def test_dependency_preflight_rejects_incompatible_bytes_before_paid_sessions(evidence, mutation):
previous = evidence[0]
prepared = bindings(previous)
mutation(prepared)
with pytest.raises(ValueError):
pr_evaluation.check_dependency_bindings(prepared, previous)

View file

@ -63,8 +63,11 @@ def test_signal_cancels_active_wave_before_assets_are_released(tmp_path, signum)
ready = tmp_path / "child-pid"
assets = tmp_path / "assets"
assets.write_text("shared")
# Publish readiness only after the complete PID is visible to the parent.
command = (
f"import os,time; from pathlib import Path; Path({str(ready)!r}).write_text(str(os.getpid())); time.sleep(60)"
f"import os,time; from pathlib import Path; ready=Path({str(ready)!r}); "
"staged=ready.with_suffix('.tmp'); staged.write_text(str(os.getpid())); "
"staged.replace(ready); time.sleep(60)"
)
script = f"""
import json,sys

View file

@ -164,6 +164,31 @@ def test_runner_requires_a_named_model_and_supports_expensive_opt_in():
normalized_model_identifier(" ")
def test_default_sweep_includes_no_gitnexus_comparison_and_repeated_measurements():
args = build_parser().parse_args(["--tasks", "tasks.yaml", "--model", "pinned-model"])
assert args.runs == 3
assert args.arms == ["workflow", "workflow_direct", "baseline", "baseline_nomcp"]
assert args.include_expensive is False
def test_explicit_smoke_sweep_can_limit_the_model_budget():
args = build_parser().parse_args(
[
"--tasks",
"tasks.yaml",
"--model",
"pinned-model",
"--runs",
"1",
"--arms",
"baseline_nomcp",
"baseline",
]
)
assert args.runs == 1
assert args.arms == ["baseline_nomcp", "baseline"]
@pytest.mark.parametrize(
"alias",
["Auto", "AUTO", "latest", "provider/latest", "provider:Latest", "provider@LATEST"],
@ -185,7 +210,7 @@ def test_eval_ci_uses_locked_uv_and_blocking_native_containment_jobs():
step for step in containment["steps"] if str(step.get("uses", "")).startswith("actions/setup-node@")
)
claude_lock = json.loads((repo_root / ".github" / "claude-canary-runtime" / "package-lock.json").read_text())
setup_uv = "astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7"
setup_uv = "astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884"
assert workflow.count(setup_uv) >= 3
assert workflow.count("version: '0.11.23'") >= 3
assert workflow.count("uv run --locked --extra dev python -m pytest") >= 3
@ -347,11 +372,18 @@ def test_shipped_scenarios_opt_out_the_cross_module_cell_and_rebuild_graph_asset
selected, skipped = select_tasks(tasks, include_expensive=False)
assert [task["id"] for task in selected] == [
"trivial-status-json-alias",
"inv-bug-c-system-include",
"inv-feature-c-include-provenance",
"inv-feature-list-repos-filter",
]
assert skipped == ["cross-module-parse-retry"]
# v1.6.12 predates all four fixes, including the C fix already on main.
assert len(tasks) == 4
c_task = next(task for task in tasks if task["id"] == "inv-feature-c-include-provenance")
assert c_task["class"] == "investigation-feature"
assert "npx tsc --noEmit" in c_task["verify"]
assert "test/unit/scope-resolution/c/c-include-provenance.test.ts" in c_task["verify"]
assert "test/unit/scope-resolution/external-import-conformance.test.ts" in c_task["verify"]
assert not c_task.get("setup")
# v1.6.12 lacks all four requested behaviors, including retained C include provenance.
assert {task["ref"] for task in tasks} == {"c4ecf398de637cf779ab2238e69958cfd5d601ce"}
assert all(not task.get("sandbox_copy") for task in tasks)
assert all(task["sandbox_dependencies"] for task in tasks)

View file

@ -7,6 +7,7 @@ import os
import shutil
import subprocess
import sys
import threading
from contextlib import nullcontext
from dataclasses import replace
from pathlib import Path
@ -1295,6 +1296,255 @@ def test_final_result_event_must_be_last(monkeypatch, tmp_path):
assert "not the last event" in rec["error_detail"]["event_stream_error"]
def background_completion_events():
first = json.loads(report_variant(uuid="first", subtype="success", is_error=False))
last = json.loads(report_variant(uuid="last", subtype="success", is_error=False, total_cost_usd=0.15))
return [
first,
{"type": "system", "subtype": "task_notification", "session_id": "s"},
{"type": "system", "subtype": "init", "session_id": "s"},
{"type": "assistant", "message": {"content": [{"type": "text", "text": "Task finished"}]}},
last,
]
def test_background_completion_sums_turn_usage_but_not_cumulative_cost(monkeypatch, tmp_path):
events = background_completion_events()
proc = replace(fake_cli_result("\n".join(map(json.dumps, events))), duration_s=12.5)
monkeypatch.setattr(runner_sessions, "run_managed", lambda *a, **k: proc)
rec = runner.run_claude("task", tmp_path, claude_bin="claude", timeout=30)
assert rec["ok"] is True, rec["error_detail"]
assert rec["cost_usd"] == 0.15 # The second result includes the first turn's $0.10.
assert rec["num_turns"] == 6
assert [rec[field] for field in runner_sessions.USAGE_FIELDS] == [2, 4, 6, 8]
assert rec["duration_s"] == 12.5 # Include background wait, not just the two 1s turns.
@pytest.mark.parametrize(
"mutate",
[
lambda es: es[-1].update(session_id="different"),
lambda es: es[-1].update(uuid="first"),
lambda es: es[-1].update(total_cost_usd=0.05),
lambda es: es[0].update(is_error=True),
lambda es: es[0].update(subtype="error_max_turns"),
lambda es: es[0]["usage"].pop("input_tokens"),
lambda es: es[-1]["usage"].update(output_tokens=-1),
lambda es: es[-1]["usage"].update(output_tokens=True),
lambda es: es[-1].update(num_turns=-1),
lambda es: es[-1].update(total_cost_usd=None),
lambda es: es.pop(1), # No background completion to explain another turn.
lambda es: es.pop(3), # A second result without a new assistant turn is a replay.
lambda es: es[2].update(session_id="different"),
lambda es: es.append({"type": "assistant", "message": {"content": []}}),
],
)
def test_unverifiable_background_continuation_stays_excluded(monkeypatch, tmp_path, mutate):
events = background_completion_events()
mutate(events)
monkeypatch.setattr(
runner_sessions, "run_managed", lambda *a, **k: fake_cli_result("\n".join(map(json.dumps, events)))
)
rec = runner.run_claude("task", tmp_path, claude_bin="claude", timeout=30, transcript_output_dir=tmp_path)
assert rec["ok"] is False
assert rec["error_kind"] == "session-error"
assert rec["cost_usd"] is None
assert rec["transcript_missing"] is True
def test_background_notification_before_first_result_remains_pending(monkeypatch, tmp_path):
events = background_completion_events()
events.insert(0, events.pop(1))
proc = replace(fake_cli_result("\n".join(map(json.dumps, events))), duration_s=12.5)
monkeypatch.setattr(runner_sessions, "run_managed", lambda *a, **k: proc)
rec = runner.run_claude("task", tmp_path, claude_bin="claude", timeout=30, transcript_output_dir=tmp_path)
assert rec["ok"] is True, rec["error_detail"]
assert rec["transcript_missing"] is False
assert rec["cost_usd"] == 0.15
assert rec["num_turns"] == 6
assert [rec[field] for field in runner_sessions.USAGE_FIELDS] == [2, 4, 6, 8]
assert rec["duration_s"] == 12.5
def test_background_notification_cannot_authorize_two_continuations(monkeypatch, tmp_path):
events = background_completion_events()
events.insert(0, events.pop(1))
events += [
{"type": "system", "subtype": "init", "session_id": "s"},
{"type": "assistant", "message": {"content": [{"type": "text", "text": "Another reply"}]}},
json.loads(report_variant(uuid="extra", subtype="success", is_error=False, total_cost_usd=0.2)),
]
monkeypatch.setattr(
runner_sessions, "run_managed", lambda *a, **k: fake_cli_result("\n".join(map(json.dumps, events)))
)
rec = runner.run_claude("task", tmp_path, claude_bin="claude", timeout=30, transcript_output_dir=tmp_path)
assert rec["ok"] is False
assert rec["error_kind"] == "session-error"
assert rec["transcript_missing"] is True
assert rec["cost_usd"] is None
def test_real_cli_notification_before_first_result_is_complete_evidence(monkeypatch, tmp_path):
from workflow_bench.mock_provider import MockProvider, Reply
claude = os.environ.get("CLAUDE_CANARY_BIN")
if not claude or not Path(claude).is_file():
if os.environ.get("GITNEXUS_REQUIRE_CLAUDE_CANARY") == "1":
pytest.fail("required pinned CLAUDE_CANARY_BIN is missing")
pytest.skip("the containment job supplies the pinned CLAUDE_CANARY_BIN")
home = tmp_path / "home"
home.mkdir()
notification_seen = threading.Event()
observe_line = runner_sessions.SessionProgress._observe_line
captured = []
def observe_notification(self, line):
observe_line(self, line)
event = json.loads(line)
captured.append(event)
if event.get("type") == "system" and event.get("subtype") == "task_notification":
notification_seen.set()
class BoundaryProvider(MockProvider):
def next_reply(self):
if len(self.requests) == 2:
# Finish the real background command while the first foreground
# response is pending, and wait for its notification to arrive.
(home / "completion-ready").touch()
if not notification_seen.wait(10):
raise AssertionError("CLI did not emit the background completion notification")
return super().next_reply()
monkeypatch.setattr(runner_sessions.SessionProgress, "_observe_line", observe_notification)
replies = [
Reply(
tools=[
{
"name": "Bash",
"input": {
"command": "while [ ! -f completion-ready ]; do sleep 0.01; done; printf done",
"run_in_background": True,
},
}
],
input_tokens=101,
output_tokens=11,
),
Reply(text="First completion", input_tokens=102, output_tokens=12),
Reply(text="Background completion acknowledged", input_tokens=103, output_tokens=13),
]
with BoundaryProvider(replies) as provider:
rec = runner.run_claude(
"Run the command",
home,
claude_bin=claude,
timeout=40,
env={
"PATH": os.environ["PATH"],
"HOME": str(home),
"ANTHROPIC_API_KEY": "offline-probe",
"ANTHROPIC_BASE_URL": provider.base_url,
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"DISABLE_AUTOUPDATER": "1",
"HTTPS_PROXY": "http://127.0.0.1:9",
"HTTP_PROXY": "http://127.0.0.1:9",
"NO_PROXY": "127.0.0.1,localhost",
},
allowed_tools=["Bash"],
strict_mcp_config=True,
transcript_output_dir=tmp_path,
progress_label="offline-notification-boundary",
)
notification = next(i for i, e in enumerate(captured) if e.get("subtype") == "task_notification")
results = [i for i, e in enumerate(captured) if e.get("type") == "result"]
assert len(results) == 2 and notification < results[0]
assert rec["ok"] is True, rec["error_detail"]
assert rec["transcript_missing"] is False
assert len(provider.requests) == 3
assert rec["input_tokens"] == 306 and rec["output_tokens"] == 36
assert rec["num_turns"] == 3
assert rec["cost_usd"] == captured[results[-1]]["total_cost_usd"]
def test_real_cli_background_completion_is_one_complete_measurement(monkeypatch, tmp_path):
"""Only the provider is scripted; the pinned CLI performs a real background Bash task."""
from workflow_bench.mock_provider import MockProvider, Reply
claude = os.environ.get("CLAUDE_CANARY_BIN")
if not claude or not Path(claude).is_file():
if os.environ.get("GITNEXUS_REQUIRE_CLAUDE_CANARY") == "1":
pytest.fail("required pinned CLAUDE_CANARY_BIN is missing")
pytest.skip("the containment job supplies the pinned CLAUDE_CANARY_BIN")
home = tmp_path / "home"
home.mkdir()
# Release the real background command only after the first result. A fixed
# sleep could finish before that result on a loaded runner and miss the bug.
observe_line = runner_sessions.SessionProgress._observe_line
def release_background_task(self, line):
observe_line(self, line)
if json.loads(line).get("type") == "result":
(home / "completion-ready").touch()
monkeypatch.setattr(runner_sessions.SessionProgress, "_observe_line", release_background_task)
replies = [
Reply(
tools=[
{
"name": "Bash",
"input": {
"command": "while [ ! -f completion-ready ]; do sleep 0.01; done; printf done",
"run_in_background": True,
},
}
],
input_tokens=101,
output_tokens=11,
),
Reply(text="First completion", input_tokens=102, output_tokens=12),
Reply(text="Background completion acknowledged", input_tokens=103, output_tokens=13),
]
with MockProvider(replies) as provider:
rec = runner.run_claude(
"Run the command",
home,
claude_bin=claude,
timeout=40,
env={
"PATH": os.environ["PATH"],
"HOME": str(home),
"ANTHROPIC_API_KEY": "offline-probe",
"ANTHROPIC_BASE_URL": provider.base_url,
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"DISABLE_AUTOUPDATER": "1",
# Only loopback may be contacted; even CLI startup traffic
# cannot reach an external provider. No host credentials inherit.
"HTTPS_PROXY": "http://127.0.0.1:9",
"HTTP_PROXY": "http://127.0.0.1:9",
"NO_PROXY": "127.0.0.1,localhost",
},
allowed_tools=["Bash"],
strict_mcp_config=True,
transcript_output_dir=tmp_path,
progress_label="offline-background-completion",
)
assert rec["ok"] is True, rec["error_detail"]
assert len(provider.requests) == 3
assert rec["input_tokens"] == 306 and rec["output_tokens"] == 36
assert rec["num_turns"] == 3
artifacts = list((tmp_path / "transcripts").glob("*.jsonl"))
assert len(artifacts) == 1
results = [e for line in artifacts[0].read_text().splitlines() if (e := json.loads(line))["type"] == "result"]
assert len(results) == 2
assert rec["cost_usd"] == results[-1]["total_cost_usd"] > results[0]["total_cost_usd"]
def test_background_task_teardown_after_the_result_stays_valid_evidence(monkeypatch, tmp_path):
# Claude Code drains background-task bookkeeping after the final result
# event. Those `system` events carry no tool or usage payload, so they must

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