29 commits

Author	SHA1	Message	Date
Gergő Magyar	66b44afe8c	fix(group): make degraded links, sync warnings and UID-only impact actually work (#3113) ... * feat(group-surface): impact selector pass-through + degraded links + sync hygiene - @group impact forwards target_uid/file_path/kind through service port and cross-impact impactParams (was dead-wired: params accepted at MCP boundary then dropped at validation). - crossLinks with unresolved provider symbols carry degraded: true, derived at the persistence boundary after merge/dedupe; sync reports 'degraded links: N' and per-repo extraction failures instead of swallowing them; bridge write failures surface as sync warnings; contracts.json passes through dedupeContracts. - Absolute-URL branch restores %7B/%7D around {param} after URL parsing. - tests: consumer matrix + wildcard folding + degraded pins (261 new); SCHEMA_BUMP pin 47 -> 48 (wildcardImports cache shape); sync.ts NUL byte rewritten as text escape (no longer binary to git). Co-Authored-By: Claude <noreply@anthropic.com> * fix(group): impact selector pass-through, degraded links, sync failure hygiene - @group impact forwards target_uid/file_path/kind through the service port into cross-impact impactParams. These were accepted at the MCP boundary and then dropped in validation — a dead wire: disambiguating an ambiguous impact target never actually reached the per-member impact. - Cross-links whose provider endpoint never resolves to a graph symbol are marked degraded: true at the single persistence boundary (post merge/dedupe, before re-export), counted as SyncResult.degradedLinks, and surfaced by the sync summary ('degraded links: N') — the remedy (re-analyze the provider repo) is documented on the field. - Sync failure hygiene: a repo whose per-repo extraction throws records its reason in SyncResult.failedRepos (still lands in missingRepos, so downstream semantics are unchanged) instead of the old silent swallow that could persist half a repo's contracts; operator warnings accumulate in SyncResult.warnings. Tests: cross-impact selector threading, degraded-link marking, per-repo failure reporting. * style: prettier * fix(group): make degraded links, sync warnings and UID-only impact actually work The three fixes this branch claims were wired at the type and payload level but never at the boundary that produces the values: - `degraded` was only ever cleared by the exported `dedupeCrossLinks`, which the sync path does not use, so `degradedLinks` was always 0. Derivation now lives in one exported `applyDegradedFlag` that both the sync finalize and the post-merge re-derivation call. - The bridge-write catch logged an operator warning and dropped it, leaving `warnings` permanently `[]`. - `@group impact` rejected a UID-only call before it parsed `target_uid`, so the documented "re-call with target_uid" disambiguation loop was unreachable in group mode even though the selectors were forwarded. - `failedRepos[].repo` reported the registry display name while the repo landed in `unreadableRepos` under its group path, so the two lists could not be joined; the JSDoc also pointed at the wrong list. - Restored the truncated `READ THE RESULT:` heading in the group_sync tool description and documented degradedLinks / failedRepos / warnings. Tests pin each value at the boundary that produces it, including the exact group_sync wire shape, which previously omitted all three new fields. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: l.cx <l.cx@winning.com.cn> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: ChunxueLi <mecoloud@users.noreply.gitee.com> Co-authored-by: Gergo Magyar <gergomagyar0@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-31 20:03:53 +00:00
简律纯	5bad2d8b0b	fix(mcp): resolve omitted repo from cwd (#3085) ... * fix(mcp): resolve omitted repo from cwd * test(mcp): cover cwd repository routing gaps * fix(mcp): harden cwd repository routing * docs(mcp): clarify cwd repository boundary * fix(mcp): preserve resolver compatibility * fix(mcp): align restricted repository routing --------- Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>	2026-08-29 21:07:43 +00:00
Gergő Magyar	54f97c86c7	fix(impact): make File risk comparable via shared axes (#3075) (#3082) ... * docs(plans): add impact file risk plan Capture the evidence, constraints, and verification path for fixing incomparable File and symbol impact risk. Co-authored-by: Cursor <cursoragent@cursor.com> * refactor(impact): centralize risk scoring Keep the existing thresholds in one shared scorer and expose a common-axis comparison for targets with unavailable enrichment axes. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(impact): expose incomparable file risk scale Mark File impact results when process and module axes are unavailable, and provide a common-axis score for honest cross-kind comparisons. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(impact): explain cross-kind risk comparisons Surface the common-axis score in CLI and agent guidance while reusing the shared threshold ladder in the web impact tool. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(impact): fail closed when enrichment is incomplete Preserve proved HIGH/CRITICAL process counts, treat failed queries as UNKNOWN, and surface riskScale metadata on MCP, group, CLI, and Graph-RAG File walks. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Gergo Magyar <gergomagyar0@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-29 11:58:15 +00:00
DuduPhudu	2c0fb7753c	fix(group): stop reporting what could not be measured as a measurement of zero (#3012) ... * fix: surface unreadable group indexes and escape raw NUL bytes in source Two independent diagnostics failures, both of which turn a real error into a confident, benign-looking answer. **Unreadable member repos (#3011).** `syncGroup` wrapped `initLbug` plus all contract extraction for each member in a bare `catch {}` that pushed the repo onto `missingRepos` and discarded the error. A LadybugDB storage-version mismatch therefore surfaced as "repo not found", `group sync` printed `0 contracts, 0 cross-links` and exited 0, and the existing contracts.json was overwritten with an empty registry. The two states need different answers from the operator — a missing repo must be indexed, an unreadable one is usually version skew or a lock — so they are now separate: - the caught error is logged with the repo, group path and lbug path - `unreadableRepos` is tracked alongside `missingRepos` on `SyncResult`, persisted (optionally, so older registries still parse) on `ContractRegistry`, and threaded through `GroupService` sync/status - `group sync` reports both before the cascade counts, since an unread repo is the likely explanation for a small or empty count - `group status` reports unreadable repos separately; calling them "missing" actively misdescribed them - when EVERY configured repo fails to open, the write is skipped: an extraction that read nothing is not evidence the group has no contracts, and replacing a good registry with an empty one loses data while reporting success **Raw NUL bytes (#3010).** `sync.ts` and `free-call-fallback.ts` each used a NUL as a join delimiter, written as a literal 0x00 instead of `\0`. Identical at runtime, but it makes the file test as binary: `file(1)` reports `data`, ugrep returns empty with exit 1 — indistinguishable from "no match", with no message — and BSD grep replaces matching lines with "Binary file ... matches". A search that should hit comes back as a confident "not present". Both now use the escape, and a unit test fails on any raw control byte in src/ so it cannot silently return. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(hygiene): guard every tracked source file against a raw NUL, not just src/ The guard added with the NUL escapes only scanned gitnexus/src for .ts/.tsx. Neither prior recurrence of this defect in this repo was in that scope: b620773b1 was gitnexus/bench/cpp-qualified-ns/measure.mjs and 38d737bb5 was a fixture under gitnexus/test. A guard that cannot see where the bug has actually landed twice is not a guard. Drive the file list from `git ls-files` at the repository root over .ts/.tsx/.js/.jsx/.mjs/.cjs/.mts/.cts — 2483 files instead of 828 — and split the byte class, which is the part that matters: - 0x00 is a hard failure repo-wide. It is the byte git's binary heuristic keys on, so it is the one that costs a file its diff (and, on the base side of a PR, its inline-comment anchors and its three-way merge). - The wider C0 class stays scoped to gitnexus/src. A repo-wide scan finds exactly one hit, test/unit/logger.test.ts:146, and that 0x1b is a legitimate ANSI-escape fixture that is the subject of the test. Widening this half would go red on day one. Read Buffers and scan bytes instead of decoding each file to latin1, through a bounded read pool: 1.5 s for 2483 files, against 8-21 s previously for 828. Add a negative fixture — a planted 0x00 and 0x1b run through the same scanning helper — so a future refactor of the collector cannot leave a permanently green guard, plus an assertion that the collected set still reaches bench/, test/ and .mjs, which goes red if the scope is ever narrowed back. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * fix(group): report a cross-repo impact built from an incomplete bridge as truncated When a sync cannot read a member repo, that repo's contracts and every cross-link touching them are simply absent from bridge.lbug. Nothing in the impact walk could notice: the only incompleteness channel on a GroupImpactResult is truncationFields(), which is driven by fan-out state (truncatedRepos / localPartial / fanoutTimedOut), and a repo missing from the bridge sets none of them. So `group impact` on a symbol whose one downstream consumer lives in an unreadable repo returned `{ cross: [], truncated: false }` — "complete: nothing in another repo depends on this". That is a wrong answer, not an empty one, for a tool an agent uses to license a delete or a rename. BridgeMeta now records unreadableRepos alongside missingRepos, writeBridge persists it when non-empty, and runGroupImpact folds a non-empty unreadableRepos ∪ missingRepos into truncated / riskEpistemic: 'lower-bound', naming the repos in truncatedRepos. The reason is a new 'incomplete-sync' rather than the existing 'partial' because the remedy differs: 'timeout' and 'partial' are runtime limits the same query can clear on a retry, while this one clears only when `gitnexus group sync` succeeds. Runtime limits still take precedence when both apply, since those are what the caller can act on immediately. The risk VALUE is never clamped down — mergeRisk is monotone in the traversed crossing count, so an incomplete bridge can only under-report. Marking the floor is what makes that legible. Both shape changes are additive and optional, so a bridge written before this still reads. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * fix(group): say truthfully what a sync did to contracts.json Review follow-ups to the unreadable-repo diagnostics. Every item below is a place where the code still answered a question it could not answer. 1. The CLI announced a write it did not perform. `group sync` printed "Wrote contracts.json (0 contracts, 0 cross-links)" unconditionally, including on the path that deliberately left the file alone. SyncResult now carries registryOutcome ('written' | 'preserved' | 'not-attempted'), the CLI prints from it, and group_sync returns it so an agent that calls group_sync then group_contracts can tell why the counts disagree. 2. Refusing to write anything on total failure threw away the diagnostic describing the run that just happened. `group status` reads contracts.json from disk, so the operator who saw the sync fail and ran status to find out why read the PREVIOUS sync's file: no unreadable list, an old lastSync, a healthy-looking group — or worse, the previous run's unreadable list presented as this one's. The skip is now targeted: contracts, crossLinks, repoSnapshots and generatedAt carry forward verbatim, only missingRepos and unreadableRepos are refreshed. generatedAt stays put because it dates the contracts, which are still the previous run's. With no prior file, or an unparseable one, nothing is written at all. 3. Per-repo extraction is now all-or-nothing. Extractors run in sequence and any one can throw; appending each one's results straight to autoContracts meant a repo whose HTTP extractor succeeded and whose gRPC extractor then failed contributed a partial set to the registry, while the same run told the operator that repo's "contracts are omitted from this sync". 4. readRegistry gains an opt-in strict mode, and syncGroup uses it. The lenient `catch { return []; }` converted "I could not read the registry" into "no repo is registered": every configured repo then resolved to MISSING, the total-failure guard stayed off (it needs a load error), and a good contracts.json was replaced by an empty one at exit 0. That is an unreadable condition reported as missing, one frame above the code this branch fixes. The default stays lenient for the other nine callers; ENOENT stays lenient in both modes. 5. Absence of unreadableRepos keeps meaning "not recorded". The loader spreads the key in only when present instead of defaulting to [], and getStatus passes undefined through, so a legacy registry no longer reads as "the last sync found none unreadable". getStatus also gates both list fields on Array.isArray: it reads through readContractRegistry, which is a bare JSON.parse cast, so a corrupt string in either slot used to reach cli/group.ts and die in .join(', ') — the command whose job is explaining an unreadable thing, crashing on one. 6. Smaller, same theme: the per-repo warning passes the Error itself rather than err.message, so pino keeps the stack; the total-failure warning no longer fires on a dry run, where it described a file the call was never going to touch and which need not exist; the status table's MISSING legend stops re-conflating the two states; the sync warning drops its GITNEXUS_LOG_LEVEL=warn hint, which would only have suppressed output (pino emits warn at the default info level, so the reason was already printed); and the group_sync tool description and its idempotency comment now describe what the tool actually does. Testing. The original four cases could not see the change they were named after. Mutation testing showed two survivors: dropping the === configuredRepoCount conjunct, which turns "every repo failed" into "any repo failed" and would silently freeze contracts.json for a group where one of five repos is skewed; and deleting both logger.warn calls, the stated purpose of the change. Both survived because every case configured exactly one repo and nothing read the log. There is now a two-repo case running the real per-repo loop, an all-missing case, a _captureLogger assertion on the level 40 record, partial-extraction cases, and strict-read cases. All five mutants are killed, each by exactly one test. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * fix(group): tighten the registry list gates and stop naming a truncation reason on complete results Three follow-ups from the check bot's pass over the previous commits. 1. `detect.includes` was missing from both group-sync test fixtures, so they did not satisfy the `GroupConfig` they claim to construct. It went unnoticed because `tsconfig.json` is src-only; `tsconfig.test.json` reports it. The older of the two fixtures carried the gap in from the original commit. 2. `runGroupImpact` named its truncation reason in a variable computed before the truncated check, so on a fully complete result the variable read 'incomplete-sync'. `truncationFields` discards the reason when `truncated` is false, so nothing surfaced — but a value that is wrong whenever it is unused is a trap for the next reader. Computed inline at the one call site that can consult it, which is also how the neighbouring call sites are written. 3. `Array.isArray` alone let a corrupt registry through. `['app/backend']` and `[{repo:'x'}]` are both arrays, and only the second reaches `cli/group.ts`'s `.join(', ')` — as `[object Object]`, a measurement the operator can read but cannot act on. Both readers now go through one `recordedRepoList` helper that requires an array of strings; anything else is "not recorded", the same as absent. Two more rows in the corrupt-value table cover it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * fix(group): keep readRegistry's signature, and stop describing unreadableRepos as index-only Two items from the check bot's blocking pass. 1. `readRegistry` gained an optional `opts` parameter last commit. That is source-compatible — every zero-argument call still compiles and behaves identically — but the contract check treats any parameter-list change on a symbol with outside callers as a break, and it is right that the safest version of this change touches that signature not at all. The strict read is now its own export, `readRegistryStrict()`, over a shared private body. `readRegistry()` is byte-identical to what it was; `syncGroup` is the only caller of the strict one, and the mode is legible at the call site instead of hiding in an options bag. 2. `unreadableRepos` is described everywhere as "the index could not be opened". That was accurate before this branch and is not now: making per-repo extraction all-or-nothing means a repo also lands there when an extractor throws partway with the index open fine. The two belong in one bucket because the consequence is one thing — none of that repo's contracts are in this sync — but the docs have to say so, or an operator reads `unreadableRepos` as a storage diagnosis and goes looking at LadybugDB for an extractor bug. Corrected on `ContractRegistry`, `BridgeMeta`, `SyncResult`, the `group_sync` tool description, and the `group sync` console output, which now says "Could not extract contracts from" rather than "Could not read the index for". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * fix(cli): stop calling an unreadable registry an old one in group status `getStatus` reports `unreadableRepos` as `undefined` for two different reasons: the field is genuinely absent, or it held something that was not a list of repo paths and the shape gate declined to guess. The status line named only the first — "registry predates this field" — so a corrupt value read as a merely old registry. That is the same shape of wrong answer this command exists to stop giving: a condition we could not read, presented as a benign one we understand. The line now names both, and asks for a sync either way, which is the fix in both cases. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * fix(group): close the three fail-open paths left on the safety boundaries Follow-ups from the re-review of 31c2b6e81. All three of its blocking findings reproduce; each is a place where unknown state still resolved to a confident benign answer, which is the one thing this branch exists to stop. 1. Strict registry reading accepted malformed rows. `[{}]` is a JSON array, so it passed the shape check: every configured repo then failed to resolve into `missingRepos`, none produced a load ERROR, the total-failure guard stayed off, and a good contracts.json was replaced with an empty one at exit 0 — the same fail-open the strict mode was added to close, one level down from the file to the rows inside it. Strict mode now requires `name`, `path` and `storagePath` on every row and rejects the WHOLE registry if any row fails. Rejecting rather than filtering is the point: dropping bad rows would report the repos they name as unregistered, which is the same wrong answer again. `indexedAt` / `lastCommit` are deliberately not required — callers already default them, so demanding them would trade a fail-open for a fail-shut on a legitimate legacy registry. 2. A failed bridge publication could make impact look complete. `writeBridge` swaps `bridge.lbug` and writes `meta.json` as two operations, and this branch made that meta load-bearing: `runGroupImpact` derives its truncation fields from it. A sync interrupted between the two steps therefore left a NEW bridge beside the PREVIOUS sync's metadata, and an impact query read that as "complete". Fixed from both ends. The write path removes the old meta before the swap, so the window leaves metadata ABSENT rather than stale. The read path treats absent-or-unparseable meta (`version: 0`) as unknown provenance and reports a floor, which also covers the caught `writeBridge` failure in `syncGroup`. Over-reporting truncation on a bridge that is actually fine is the safe direction, and the next successful sync clears it. 3. `preserved` was returned when there was nothing to preserve. On a group's first all-unreadable sync the outcome was set before the prior registry was read, so the CLI told an operator "the contracts from the previous sync are preserved" about a file that had never existed. Split out as `no-prior-registry`, with its own console message. Also widened the NUL guard to the source languages it claimed to cover. The commit that added it said "every tracked source file" while the collector stopped at the JS/TS family, so a raw NUL in tracked Python, Java, Go, Rust, C/C++, Ruby, PHP, Kotlin, Swift, C# or shell would still have turned those files binary unnoticed. Measured before widening: 2315 non-JS tracked source files, zero hits, so this was an unforced gap rather than a tradeoff. A planted `.py` fixture and a collector-coverage assertion keep it honest. Every fix is mutation-verified: reverting each one individually turns its own tests red (3, 2, 2, 1 and 1 failures respectively), and all pass together. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * fix(group): record the empty unreadable measurement instead of dropping it Both writers omitted `unreadableRepos` when it was empty, which made the tri-state this branch introduced unreachable in its most common case. `ContractRegistry.unreadableRepos` is optional on the TYPE so a registry written before the field existed still parses, and absence there means "not recorded". But a sync that read every repo successfully HAS measured it, and `[]` is that measurement. Dropping it collapsed "measured, none" into "never recorded", so after every clean sync `gitnexus group status` printed Last sync unreadable repos: not recorded (the registry predates this field, or its value could not be read) Re-run `gitnexus group sync` to record it. about the sync that had just succeeded. The distinction is only worth having if the writer commits to it, so both `contracts.json` and the bridge's `meta.json` now record the field whenever the sync supplied it, `[]` included. The check bot found this on the bridge writer and attributed the consequence to `group status`. The consequence is real but it is not the bridge's: `getStatus` reads `contracts.json` and never touches `BridgeMeta`, whose only consumer is `runGroupImpact` — where absent and empty are already equivalent. So the user-visible half was in the registry writer, one file over from where it was reported, and both are fixed. Also fills in `DetectConfig.includes` (and `workspace_deps`) across the group test fixtures that predate those fields. These are pre-existing on main and are a no-op at runtime — `undefined` and `false` are both falsy at the gate — but they are the same defect the bot flagged as an error in the new fixtures, and `tsconfig.test.json` reported eleven of them. That file is not in CI, which is why they survived; the group tree is now clean of them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * test(group): stop two bridge-metadata tests claiming coverage they do not have Both were named for the swap window and neither injects a swap failure. "drops the previous meta.json before swapping the database file" runs two successful writeBridge calls. Its assertions hold with the removal in either position, because writeBridge overwrites meta.json at the end regardless — so it cannot pin the ordering it is named for. Renamed to what it does cover, the successful-rebuild replacement, with the limit stated in the body rather than left for the next reader to discover. "leaves NO meta.json when the swap fails partway" removes the file by hand after a successful write, so it exercises readBridgeMeta's missing-file contract, not writeBridge. That contract is worth pinning on its own — version 0 is the signal runGroupImpact fails closed on — so the test stays, under a name that says so. The ordering itself is pinned in bridge-meta-swap-window.test.ts, which mocks retryRename to throw on the bridge.lbug swap and asserts the previous sync's metadata cannot survive it. Both renamed tests now point there, so the coverage is findable from the place someone would look for it. No production code changes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * fix(group): pair bridge metadata to its database instead of deleting it The previous commit closed the swap/metadata window by removing meta.json before the database swap, so the window would fail to "absent" rather than "stale". That was the wrong trade, and it destroyed recoverable state. The old database's move to `.bak` sits inside a catch that swallows failures, not just "no existing db". When that rename fails — a held read-only handle does this on Windows, and a long-lived MCP server holds one — the failure is swallowed, the following `tmp -> bridge.lbug` throws, and writeBridge exits with the OLD database still in place and perfectly valid. Its metadata was already deleted. Cross-repo impact then answers "we cannot say" for that group until some future sync succeeds, and if the cause is a held handle or permissions there is no such sync. A working feature, destroyed permanently to close a narrow window. Deleting also only chose which way the window failed; it never closed it. So destroy nothing, and make the pair self-describing instead: writeBridge stamps the database's size and mtime into the metadata it writes, and `bridgeMetaMatchesFile` lets a reader ask whether the two still belong together. `runGroupImpact` treats a mismatch the same as absent metadata — provenance unknown, report a floor. A metadata file left over from an earlier sync cannot match a freshly renamed database, and a sync that fails before the swap leaves a matching pair untouched. Metadata written before the stamp existed is unverifiable rather than stale, and is accepted: failing those closed would mark every pre-existing bridge incomplete, trading a narrow window for a repo-wide regression. The swap-window test now distinguishes the two failure shapes, because they want different answers. When every rename fails the old database never moves, so the surviving metadata still matches it and impact keeps answering from it. When only the final rename fails the old database has already reached `.bak` and no database is in place, so the metadata correctly matches nothing — and `ensureBridgeReady` fails loudly on the absent file, which beats a silent floor. Mutation-verified: reinstating the delete, neutering the pairing check, and dropping the stamp each turn 2, 3 and 3 tests red respectively. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014g48u4WcRZy543Wqp5NhpV * chore: keep TypeScript diffs readable after a NUL leaves the tree Git decides a pair is binary when EITHER blob carries a NUL, and it only sniffs the first 8000 bytes. `gitnexus/src/core/group/sync.ts` carried one at byte 5132 on main. This branch removes it, but the base side still has it, so the file renders as "Binary files differ" in the pull request: no hunks, no inline comments, and no three-way merge — however clean the head side is. A head-side byte guard cannot detect that, by construction, since it only ever sees the working tree. Setting the `diff` attribute stops the heuristic from hiding the change. It does not mark the files binary, does not imply `text`, and does not change how blobs are stored, normalized, or checked out — the root `* text=auto eol=lf` still governs all of that. It affects diff generation and rendering only. Locally this turns the branch's own sync.ts diff from `Bin 17612 -> 25346 bytes` into 154 insertions and 16 deletions. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): answer "provenance unknown" for malformed bridge metadata `readBridgeMeta` guarded the read and the parse but not the SHAPE of what it parsed, then cast the result. `runGroupImpact` spread both repo lists straight into a Set, so a `meta.json` whose `missingRepos` held an object threw a TypeError out of the entire cross-repo query — and threw it from a point after `ensureBridgeReady` had taken the bridge lease and before the `try` whose `finally` releases it, so every such query also leaked a refcount the cached handle could never get back. A malformed file is a reason to answer "we cannot say", never a reason to crash the question. The shape gate now lives where the metadata is read, mirroring the one `service.ts` already applies to the registry's copies of these same two lists. Each list is judged independently: a garbage `unreadableRepos` no longer discards a `missingRepos` that was genuinely measured. A list that was present but unusable is dropped rather than normalized to `[]`, because an unreadable value is not a measurement of zero — the new reader-side `repoListsUnreadable` carries that distinction, and `runGroupImpact` folds it into the same provenance-unknown verdict it already reaches for `version: 0` and for metadata that does not pair with the database beside it. A root that is not an object is closed too. `JSON.parse` succeeds on `null`, `7` and `[]`; the first threw on `.version`, and the other two read `undefined` and sailed through the version gate as if the bridge had been vouched for. Both provenance values moved inside the protected region and are initialized fail-closed, so a future throw between the lease and the walk releases rather than wedges. `repoListsUnreadable` is reader-side only: the sole `writeBridgeMeta` call site builds a fresh literal, so nothing persists it and no schema version moves. Mutation-verified: reverting the shape gate alone turns 4 tests red — the three malformed-list scenarios plus the handle-release regression. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(storage): reject registry rows that cannot identify a repo The strict read's row gate gave `typeof v === 'string'`, and `typeof '' === 'string'`. A row whose `name` was blank therefore passed as resolvable, then matched nothing in `defaultResolveHandle` — putting every configured repo in `missingRepos` and presenting an unusable registry as a clean answer about an empty one. That is the same unreadable-as-missing fail-open the strict mode exists to close, one level further in. A blank `storagePath` is worse than useless: it joins to a relative `lbug` under the current directory, so the sync opens an index that is not the repo's. Both now have to be non-blank after trimming. `path` stays at the bare string check, on the same reasoning that already exempts `indexedAt`/`lastCommit`: require only what resolution depends on to IDENTIFY the repo. This gate rejects the whole registry and the registry is machine-wide, so a field tightened past what identification needs would let one blank value in one row break every group sync on the machine — including groups whose repos all resolve. A blank `path` still yields a working handle; `defaultResolveHandle` does read it, but only for the pool id and `repoPath`, neither of which decides whether the row names a repo. The error now says what is actually wrong instead of naming three fields that are all present. Mutation-verified in both directions: dropping the trim turns the three rejection tests red, and applying the wider fix that was considered and declined — tightening `path` too — turns exactly the counter-case red, so that test genuinely pins the narrow reading rather than passing either way. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): bound the per-repo contract staging append `autoContracts.push(...repoContracts)` passes every staged contract as a separate argument, and the engine caps how many arguments one call may take. That cap is a function of the host's available stack, so it is a different number on every machine — this one accepts a 125k-element spread and dies at 150k. The spread itself is not new; what it carries is. Before staging, this line appended a single extractor's output as it came back. Staging made it carry the whole repo's, which is enough for a large repo to raise `RangeError: Maximum call stack size exceeded` on the one line whose job is to commit work that just succeeded. The throw lands in the catch below, so the sync reports a repo whose extractors all ran cleanly as one whose index could not be read — a crash wearing the costume of a diagnostic. A bounded loop replaces it: the count a repo can stage is now bounded by memory rather than by how much stack the process happened to get. The guard is structural, not size-based, and deliberately so. A "make the fixture big enough to crash" test passes against unfixed code on any host with a larger stack, which is exactly the guarantee a regression gate cannot give up. It walks the AST and locates the region by role — the `const` staging buffer typed `StoredContract[]`, then the extractor `try` that is a direct statement of the block declaring it — so renaming either identifier keeps it pointed at the same code. `.apply()` is rejected alongside spread, being the same hazard in different syntax. Direct statements only, because `syncGroup` wraps this whole section in its own try/finally for the lease sweep, and that ancestor reads the buffer too. Matching any enclosing `try` pulls in the entire function body — including the two windowed-manifest spreads, which are bounded by the window size and are not what this fixes. Mutation-verified in both directions: restoring the spread turns the gate red naming that line alone; deleting a manifest-window spread, and separately adding a third one, both leave it green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): keep unreadable repos out of manifest contracts too Per-repo staging closed one door: a repo whose extractor threw contributes nothing through the direct path. Deferred manifest resolution was a second door, still open. It derives its known-repo set from the resolved-handle map, which kept an entry for a repo the same run had already declared unreadable — so the sync re-opened that index and resolved symbols against a database it had just told the operator it could not read. Deleting the handle in the catch stops the re-open, but it does not satisfy R2 on its own: `ManifestExtractor` resolves both endpoints of a link and emits a contract for each, and for an endpoint with no executor that contract is still emitted with a synthetic UID. The registry ended up naming a repo the same run reported unreadable. So the emitted output is filtered by ENDPOINT, not by link. Dropping the whole link would delete the healthy partner's contract as well — a repo losing its own output because a neighbour's index would not open, which is wider than the requirement and destroys good data to suppress bad. A cross-link is different: it asserts something about a pair, so if either end is unreadable there is nothing left to anchor it to, and a half-anchored link is exactly the confident-about-what-it-could-not-read answer the registry must not give. Deleting the handle also changed what the operator gets told, so the warning is split. An unreadable repo IS configured; letting it fall into the "references repos not in config.repos" branch states something false and sends the reader to edit group.yaml for a problem only re-indexing fixes. It now gets its own message naming what was actually omitted. Mutation-verified four ways: reverting the endpoint filter turns three scenarios red; the over-broad whole-link variant turns the healthy-partner scenario red and nothing else; removing the handle delete turns the no-re-open scenario red; and reverting the warning split turns the operator- message scenario red. Every assertion reads the written contracts.json rather than the in-memory result. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(group): keep readBridgeMeta's signature stable across the shape gate The shape gate landed by widening the return type to a reader-only `ReadBridgeMeta extends BridgeMeta`. That is source-compatible — a covariant return, one added optional field, every existing caller unaffected, typecheck and suite clean — but the contract check reads it as a changed signature with a caller left behind, and blocks the merge on it. This branch already hit the same wall on `readRegistry` and settled it the same way: leave the signature alone and make the difference legible some other way. So the flag moves onto `BridgeMeta` itself as an optional, documented, never-persisted field, and `readBridgeMeta` goes back to the exact signature its callers already compile against. That is the better shape here anyway. The reader-only subtype would have split the validation two ways: `openBridgeDbReadOnly` and `bridgeExists` both gate on `meta.version`, and the normalization that comes with the gate is what stops a `version: null` in a hand-edited meta.json from reading as `undefined` and sailing through `version > 0` as though the bridge had been vouched for. One type keeps all three callers behind the same guard. Nothing persists the flag: `writeBridgeMeta`'s only caller builds a fresh literal, so it cannot round-trip to disk. No behavior change — pure type restructuring. 927 tests pass, typecheck clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): stop treating a half-written bridge stamp as a verified match `bridgeMetaMatchesFile` joined its two `undefined` checks with `||`, so metadata carrying a size and no mtime — or the reverse — returned `true`, the same answer it gives a fully verified pair. A stamp is a PAIR. Both halves absent is the legacy shape: metadata written before stamping existed, which cannot be verified either way and is accepted deliberately, because failing it closed would mark every pre-existing bridge incomplete until re-synced. Exactly one half present is not that. Something wrote a stamp and did not finish, which is precisely the condition stamping was added to detect — so the check handed back "verified" for the one shape that most deserves suspicion, and a cross-repo impact query built on it would report a confident answer about a database its metadata cannot vouch for. The two states are now separated: neither half present accepts, exactly one rejects as provenance-unknown, both compare against the file as before. Found by the repository's own contract check, not by the plan. Mutation-verified: restoring the `||` form turns both half-stamp cases red while the legacy and fully-stamped controls stay green, so the pair genuinely pins the distinction rather than passing either way. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): pair unstamped bridge metadata by write order, before any open Unstamped metadata was waved through: `bridgeMetaMatchesFile` returned "matches" for any pair with no stamp to check, so the stale-meta-beside-a-new-database window stayed open for every bridge written before stamping existed, and `runGroupImpact` spent that metadata's completeness as fact. `writeBridge` renames the database into place and writes the metadata after, so `meta.mtime >= db.mtime` holds for any pair written together — including by builds that predate the stamp. A database strictly newer than the metadata beside it can only come from a swap whose metadata write did not land. That is the fallback now. It is a heuristic on write order, not proof of provenance, and it is wrong in two directions: a stale metadata file touched after the swap still reads as paired, and a pair whose clock stepped backwards between the two writes reads as unpaired. Both are recorded at the code; the second is the safe direction. Equality counts as paired, or a coarse-granularity filesystem would reject every legacy bridge for a reason that is about the filesystem. The verdict is now taken in `ensureBridgeReady` BEFORE the database is opened, and carried on the metadata rather than recomputed afterwards. That ordering is load-bearing, not tidiness. Impact and trace both open the bridge and only then ask about provenance, so on any platform or LadybugDB build where a read-only open advances the file's mtime, every pre-stamp bridge would report provenance-unknown from its first query onward — the exact repo-wide regression this rule was chosen to avoid, arriving as a silent downgrade rather than an error. It does not happen on Linux, which was measured. It cannot be measured on Windows: pinning it by really opening the database needs an in-process write→read reopen of the same bridge.lbug, which is a documented limitation there. Rather than ship a Windows-skipped test and leave the assumption unverified on the platform whose file semantics are most likely to differ, the check moved ahead of the open so no platform has to be trusted. The new guard forces the hostile case on every platform: the open is stubbed to advance the database's mtime, and the verdict must still be "paired". It is registered in the cross-platform list so the Windows and macOS shards run it, and it has a control so it cannot pass vacuously. Two existing fixtures mocked `readBridgeMeta` to return a stamped-era version while never writing a meta.json — a state production cannot reach, since a non-zero version can only come from a file that exists. They now write the metadata their own mock claims to have read, rather than the helper being loosened to accept metadata it cannot stat. Mutation-verified twice: reverting the write-order branch turns both rejection cases red while all four legacy-accept cases stay green, and moving the pairing call back after the open turns the ordering guard red on its own. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(group): compute cross-repo completeness in one place Three surfaces can return a partial cross-repo answer — impact, trace, and the contract listing — and each decided for itself whether it was complete. Impact carried the structured triple; trace said it in prose, if at all. An agent reading a not-found trace had no machine-readable way to tell "there is no path" from "there may be a path in a repo this sync could not read", which is the difference between an answer and a floor. `crossRepoCompleteness` is now the one computation, and its input deliberately does not name where any of it came from. `BridgeMeta` is not in the signature and must not be: `groupContracts` answers the same question from contracts.json and never opens a bridge, so `version`, `repoListsUnreadable` and `pairedWithDatabase` do not exist on that path. Each caller derives its own `provenanceUnknown` — the bridge callers through `bridgeProvenanceUnknown`, which stays separate for exactly that reason — and passes the boolean in. Scope arrives as a predicate rather than a repo list or a subgroup, so narrowing a query's scope stays a change to one argument at the call site. The trace results now carry `truncated` / `truncationReason` / `riskEpistemic` like impact does. `notes` is untouched; it remains an addition to the machine channel, never the channel. One correction to the approach as written: it said to pass the trace's two endpoint repos as the predicate, but a destination trace declares no `to`. It asks where a call lands, so any member may hold the answer — and an unreadable provider repo is precisely how "no outgoing ContractLink leaves this repo" becomes a wrong answer rather than an empty one. Filtering that path to the `from` repo would have reintroduced the bug this unit exists to close, so it passes every repo and a test pins it. Two pre-existing paths become consistent with the vocabulary as a result: a crossing-capped result now reports `truncationReason: 'partial'` alongside the `truncated` flag it already set, and the destination path's `ambiguous` returns now report the cap its `ok` and `not_found` siblings already reported. Both are additive — no field is removed, and no `truncated` flips from true to false. `truncationFields` returns a discriminated union now, so `truncationReason` reads without a fallback on the branch where it cannot be absent. Mutation-verified: reverting the provenance fold alone — one line in the shared helper — turns 8 tests red across both surfaces, 2 new trace scenarios and 6 existing impact ones, which is the point of there being one helper. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): narrow the incomplete-repo set to the query's declared scope A subgroup-scoped impact query was marked a lower bound by repos it had explicitly excluded. The fan-out already drops every neighbour outside the subgroup, so those repos could not have contributed a crossing to the answer — and a completeness marker that fires on results it does not describe is how a caller learns to ignore the marker. The scope is the query's DECLARED one, not the one the walk reached. An incomplete repo's contracts are absent from the bridge by definition, so it is never in the traversed set; filtering on what was traversed would empty the intersection on every query and silently restore the fail-open this channel exists to close. Declared scope here is the subgroup PLUS the query's own repo, which the approach did not account for. The walk starts from that repo's contracts in the bridge, so when it is the repo the sync could not read there are no crossings to find under any scope — and a subgroup excluding it would have turned that vacuum into a confident "nothing depends on this", for a tool an agent uses to license a delete. That case reported a floor before this change, so narrowing to the subgroup alone would have been a regression. The union only ever widens the in-scope set, so it cannot re-mark a repo the query excluded. Membership goes through the existing `repoInSubgroup` in both clauses, `exact` for the origin equality, rather than growing a second notion of what it means for a repo path to be in scope. Sound only while `MAX_SUPPORTED_CROSS_DEPTH` is 1 — at depth 2 an out-of-scope repo can sit between two in-scope ones — and that constraint is recorded at the intersection. Unscoped queries are byte-for-byte unchanged: `repoInSubgroup` answers true for an absent subgroup, so the intersection is the whole set. Mutation-verified: restoring the unfiltered predicate turns exactly the two scoped cases red while the unscoped control and both in-scope guards stay green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): keep the preserved registry and the bridge from disagreeing A total-failure sync refreshed contracts.json's diagnostic lists and left meta.json alone. But meta.json, not contracts.json, is where runGroupImpact reads completeness from — so the registry said "this sync could not read app/backend" while a cross-repo query answered `{ cross: [], truncated: false }`. Two surfaces describing the same run, one of them wrong, and the wrong one is the machine-readable one an agent uses to license a delete. The preserve path now refreshes the same two fields in the metadata. The database stays untouched: it still holds the contracts being preserved, and rebuilding it here would be the one write that could lose them. Refreshing metadata is not free, though, and the obvious version of it is a fail-open. The rewrite moves meta.json's mtime to now while bridge.lbug's stays old, so an unstamped pair whose database is NEWER than its metadata — the shape the write-order rule exists to reject — would come out of a preserve sync passing the check. Writing "no stamp" does not help; the write-order comparison is exactly what the moved mtime defeats. The verdict has to be recorded in the metadata, because the refresh cannot avoid moving the mtime. So `provenanceUnknown` is persisted whenever the existing pair does not already check out, the existing stamp fields are carried through verbatim rather than dropped, and `bridgeMetaMatchesFile` rejects the marker ahead of both the stamp and the write-order heuristic. A pair that already matched is re-stamped instead, which also upgrades a legacy unstamped-but-paired bridge to an exact stamp. No preserve run can increase the number of pairs that pass the check. The marker self-clears: `writeBridge` builds fresh metadata and never sets it. `BridgeMeta` carries two reader-side fields documented as never persisted, and this is the first code in the repo that reads metadata and writes it back. Both are stripped explicitly before every write. `pairedWithDatabase` is the dangerous one — persisted, it would tell every future reader the pair had been verified — and a test seeds both on disk to pin that neither survives. The write is not wrapped in a catch, unlike writeBridge on the success path. There contracts.json is canonical and already written, so a stale bridge is a recoverable degradation; here the write IS the guard against a confident wrong answer, and swallowing its failure would reinstate the fail-open it closes. `writeContractRegistry` above is unguarded into the same directory for the same reason. A group with neither file writes nothing: `readBridgeMeta` already answers `version: 0` for an absent file, so a written one would say what the absence already says while inventing state for a bridge that has never existed. Mutation-verified three ways: dropping the marker write turns 6 red including both laundering scenarios; moving the marker check below the stamp branches turns the unstamped-laundering case red; removing the field stripping turns the never-persisted test red. Each restored byte-exactly and re-verified. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): report group_contracts' completeness in the shared vocabulary `group_contracts` returned contracts and cross-links and said nothing about whether that listing was the whole story. An agent reading it after a sync that could not open half the group got a confident-looking list with no way to tell it was a floor — the same fail-open the impact path already closed, on a surface that had no channel for the answer at all. It now returns the registry's two diagnostic lists and the structured triple, folded through the same helper the impact and trace surfaces use, so the three cannot drift. The helper takes no `BridgeMeta` precisely so this path — which reads contracts.json and never opens a bridge — can share it. The three registry states stay distinguishable, which is the point: - key absent: the registry predates the field and has no opinion about which indexes opened, so the key is omitted rather than invented as `[]`, and the listing reports a floor. It cannot say which repos the sync failed to read, so it cannot claim to be complete. - key present and empty: measured, clean, not truncated. - key present and populated: the repos, and a floor. `incompleteRepos` is dropped on this surface alone: both lists it derives from are returned verbatim beside it, and a third name for the same repos is drift waiting to happen. The import is lazy, matching `groupImpact` and `groupTrace` in this same class. `cross-impact.js` statically pulls the native LadybugDB binding through `bridge-db.js`, and `service.ts` is loaded by every `gitnexus group` subcommand including ones that touch no database. One fix inside the same file that this unit forced: the registry loader gated `missingRepos` with a bare `Array.isArray`, which admits `[{repo:'x'}]`. That was inert while nothing read the list, but this change both returns it and folds it into the completeness answer — so an unreadable value would have been printed as a repo name and would have flipped `truncated` on garbage. It now uses the same `recordedRepoList` gate `group status` already applies to the same field. `missingRepos` has always been required, so unlike `unreadableRepos` it has no "not recorded" state to preserve and an unreadable value degrades to empty. Mutation-verified: reverting the fold alone turns 14 tests red and leaves the control — the contract and cross-link payload this tool has always returned — green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cli): stop dropping group contracts' completeness fields on the way out `group contracts --json` destructured `{ contracts, crossLinks }` from the service payload and rebuilt an object from just those two. Everything else the service returned was discarded on the way to stdout — so the completeness fields the MCP tool now carries were invisible at the CLI, and the two surfaces disagreed about the same registry. It prints the payload whole now. A field added to the service reaches `--json` without a matching edit here, which is the point: the re-serialized subset was a second place that had to be remembered, and it was not. The human-readable path gains the same signal in words. A listing built from a sync that could not read part of the group shows counts that are a floor, not a census, and it named neither fact. It now says so and names the repos when the registry recorded them — and says the sync did not record which repos it could read when it did not, because a listing that cannot say what it is missing is still incomplete. Mutation-verified: restoring the re-serialized subset turns the `--json` case and the control red. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): tell a missing registry entry apart from an unreadable one `group status` printed MISSING for both "this repo has no row in the registry" and "the registry itself could not be read", so an operator whose registry.json was corrupt was told every repo was unregistered — and sent to re-register them instead of to the one file that was actually broken. The two are now separate. `missing` keeps its old meaning and still flags every unusable repo, so an older consumer is unaffected; `unresolvable` is additive, always present, and carries the reason that produced it. This is the one caller that has to make that distinction, so it takes the strict global-registry read. `readRegistry`'s `catch { return [] }` collapses a malformed registry into an empty one, which is indistinguishable from a genuine absence and is exactly what produced the wrong label. The cost is accepted knowingly and recorded at the call site: the strict read rejects the whole registry when any row fails to identify a repo, so one malformed row renders every member unresolvable — including members whose own rows are fine. That is the honest verdict, and it is reported as an unresolved state rather than a clean one. Choosing between the two labels needs to know whether a row exists at all, which `registryIdentifies` answers by mirroring the two tiers the resolver matches a bare group-config value on — registry name, case-insensitively, and repo path. It deliberately stops short of the hashed-id and partial-name tiers: those exist to be generous about what an operator typed, while this only picks a label, and a looser match would relabel a genuine registry miss as an unresolvable row — the same conflation this change removes, pointed the other way. The plan's third failure mode — a row that resolves but whose storage path cannot be opened — turns out to be unreachable: `loadMeta` returns null on every error and `checkStaleness` catches everything, so nothing after `resolveRepo` inside the try can throw. The reachable per-repo case is `resolveRepo` itself throwing, as it does for two registered clones sharing a name, and that is what the tests drive end to end through the real CLI. The code still handles the plan's case correctly if those helpers ever start throwing. Mutation-verified: reverting the split turns 6 unit and 2 CLI cases red while both controls — a genuine miss, and a healthy group — stay green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(cli): say what the preserve path actually does to contracts.json The sync summary announced "Did NOT write contracts.json" on the branch that writes it. The preserve path rewrites the file — keeping the previous sync's contracts and cross-links, replacing only the two diagnostic lists — so an operator who checked the mtime and found it moved was told the opposite of what had happened, on the command this PR exists to make legible. It now says the previous contracts were kept and names what changed. The no-prior-registry branch is narrowed for the same reason. It claimed nothing at all was written, and that is no longer true either: this path still records the run against an existing bridge's metadata. The claim is now scoped to contracts.json, which is the file it can actually speak for. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): stop the total-failure log promising a preservation that did not happen The warning fired before the prior registry was read, so it could only ever promise one of the two things that might be true — and it promised the wrong one to every group that has never synced: "keeping the contracts from the previous sync" about a file that does not exist. The console line for that same run, driven by `registryOutcome`, said the opposite. It now lives inside the branch, after the read, with one message per outcome chosen at the point the outcome is decided. The log and the console cannot disagree, because the same fact selects both. Both messages keep the warn level and the two repo lists. Mutation-verified: reverting the split turns the no-prior-registry case red while the preserved case — whose claim was already true — stays green. The dry-run test's log filter was also widened to the sentence both messages share, or the new wording would have made that assertion match nothing and pass regardless. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): make the bridge-failure warning describe what the code guarantees The warning after a failed `writeBridge` promised that cross-repo impact would report `truncated` until a sync succeeded. Nothing on that path produces that signal. The swap is the last step: `writeBridge` builds the new database in a staging directory and only then moves the old one aside. A failure during the build therefore leaves the previous sync's `bridge.lbug` exactly where it was, beside the `meta.json` stamped for it — a pair that passes `bridgeMetaMatchesFile` with the previous run's `unreadableRepos`. The next cross-repo query answers `truncated: false` from superseded contracts, which is the opposite of what the operator was told to expect, and worse than being told nothing. The warning now says what is actually true: contracts.json is intact and canonical, the bridge was not replaced, cross-repo queries may still answer from the previous sync's contracts, and nothing marks them as superseded. The metadata is deliberately NOT re-stamped to make the original promise true. That would recreate exactly the metadata/database mis-pairing the stamping on the preserve path exists to prevent, and the comment at the warning records it. The claim is asserted against captured log output rather than left to the state tests. Those check which pairs match and what the preserve path writes; every one of them stays green while this sentence reverts to promising a truncation. An unasserted user-facing branch is the defect class this change is closing, so it does not get to close it while remaining one. No filesystem shape makes the real `writeBridge` fail while `writeContractRegistry` succeeds — they write into the same directory one line apart — so the failure is armed through a pass-through wrapper on the file's existing mock. It delegates byte-for-byte unless a test arms it, and is reset around the new suite. Mutation-verified: restoring the original wording turns its own assertion red and nothing else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(mcp): name every registry outcome group_sync can actually return The tool's description told agents `registryOutcome` is 'written' or 'preserved'. It has a third reachable value: 'no-prior-registry', returned when nothing could be read AND there was no previous contracts.json to carry forward. An agent calling this tool against a group that has never synced got a value its own tool description said did not exist, and no way to tell it apart from the case where the previous contracts survive. The distinction is the whole point of the value. After 'preserved' there is a registry to read — stale, but real. After 'no-prior-registry' there is nothing on disk at all, so a following group_contracts or group_impact has no registry rather than an old one. Those need different responses from the caller. 'not-attempted' stays undocumented because it is unreachable through this tool, and a guard asserts it stays that way. The code comment above the annotations claimed the preserve path does NOT write contracts.json. It does — it rewrites the file, keeping the previous contracts and cross-links and refreshing only the two diagnostic lists, which the CLI's own summary was corrected to say a few commits ago. Left alone it would have re-seeded the same wrong claim next to the text that now states it correctly. Mutation-verified: deleting the 'no-prior-registry' sentence turns the guard red. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(mcp): explain structural incompleteness on the impact tool and status resource The impact tool's GROUP MODE paragraph described one cause of truncation — the fan-out running out of room — and left an agent to assume that was the only one. So a `truncated: true` carrying `truncationReason: 'incomplete-sync'` read as "retry with a smaller scope", when retrying returns the identical floor forever: the repos are absent from the bridge itself, and only a re-sync puts them back. The old text also said the response carries the truncation fields "when it stops early", which is wrong for that case — `truncatedRepos` names repos even when ZERO crossings to them were attempted, because their contracts were never in the bridge to cross to. The paragraph now branches on the reason and gives each its remedy: 'timeout' and 'partial' are runtime limits where a retry or a larger budget can help; 'incomplete-sync' is structural and the remedy is `group_sync`. The reason union is now derived from an exported `as const` array rather than written as a bare type. A type-only union gives a guard nothing to enumerate, so the guard has to hand-list the members — and then it passes forever the moment a fourth is added, which is the exact regression it exists to catch. The guard iterates the runtime array instead. Verified by appending a probe member and watching it go red, then removing it. The resolved type is unchanged; every importer uses `import type` and none needed an edit. The status resource said "Group index / contract staleness" and nothing about the distinctions its payload now carries. It explains all of them: a repo absent from the registry versus one whose entry could not be resolved, and the `unreadableRepos` tri-state where an ABSENT key is not an empty one — absent means the last sync never recorded what it could read, so cross-repo answers for that group are a floor. The description an MCP client actually receives lives in `getResourceTemplates`, not in the context resource's inventory line the plan pointed at. Both now carry the vocabulary, so the two surfaces cannot disagree about the same payload. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * feat(group): serialize group syncs behind a fail-closed per-group lock Two concurrent syncs of one group could lose one another's writes. Both read the prior registry, both built contracts, both wrote — last writer won, and the loser's work was gone with nothing reporting it. A group sync is long and expensive and is exactly the operation whose lost update destroys contracts. `syncGroup` now takes a lock for the whole persist section, acquired exactly once. `acquireIndexLock` is not reentrant, so a second acquisition anywhere below would deadlock the happy path rather than an edge case; `withGroupSyncLock` has one call site and nothing inside it re-acquires. The lock lives on a dedicated `sync-lock` directory inside the group directory, mirroring the registry lock's dedicated directory rather than reusing the resource's own — a lock directory that could collide with a per-repo index slot repeats a bug the registry lock's comment already warns about. It fails CLOSED, which is the opposite of `withRegistryLock` and deliberately so. That one degrades to unlocked because it guards a sub-second JSON merge on a latency-critical path; here running unprotected is the outcome the lock exists to prevent. Three exits are covered: a timeout, an unwritable lock directory, and the lock-free degradation the primitive performs silently. That third exit needed a change in `index-lock.ts`, and it is the one declared exception to keeping this work inside core/group/. `acquireIndexLock` answers a read-only or permission-denied filesystem with a no-op handle that is byte-identical in shape to a real one, so a caller for whom lock-free is not an acceptable outcome could not tell the difference. It now carries an optional `lockFree` marker. The change is additive by construction: no signature moves, no control flow changes, nothing about when or how a lock is taken changes, and every caller that ignores the field behaves exactly as before. A filesystem probe inside the group module was considered and rejected on evidence: `selectBackend` returns `socket` on Linux and Windows, where `acquireViaSocket` never touches the filesystem and this branch cannot occur — so a probe would refuse syncs on the two platforms that never degrade while missing the one that does. The timeout ceiling is a named 600s constant passed explicitly. The magnitude matches the primitive's own analyze-sized default because a group sync is analyze-shaped and a legitimately queued second sync must be able to wait out a full first one. Passing it explicitly is about the override, not the magnitude: `resolveTimeoutMs` resolves `GITNEXUS_INDEX_LOCK_TIMEOUT_MS <= 0` to Infinity, which would turn fail-closed into a hang. Cross-process exclusion is proved with a real spawned holder, not an in-process mock, which cannot demonstrate the property this exists for. The lock-free scenario pins `GITNEXUS_INDEX_LOCK_BACKEND=file` — unpinned it would pass on two of three platforms while measuring nothing — and produces the failure by injecting EACCES on one syscall rather than by chmod, so it runs identically on Windows instead of being skipped there. The CLI reports the failure through pino rather than a bare stderr write, which this package lints as an error to keep that migration moving, and the test reads the `msg` field rather than a raw substring — matching on the raw text would have passed only by accident of quoting and would go green again if the line were downgraded. Nothing is skipped on any platform, and the test is registered for the cross-platform shards. Mutation-verified: removing the lock acquisition turns 6 scenarios red; removing the lock-free rejection turns the degradation scenario red on its own. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): make the sync-lock timeout name a cause it can establish The fail-closed lock surfaced the primitive's own timeout message to users for the first time, and that message says the wait was on "another gitnexus analyze" — a cause its detection path cannot establish. It is the same confident-about-what-it-could-not-determine claim this PR exists to remove, inherited rather than written. The wrapper now throws its own. It names the group, the lock directory, the operation, and the elapsed wait, and it says plainly that nothing was written. The holder clause branches on `holderKnown`. The socket backend exposes no owner metadata and reports a placeholder pid of -1, so on that backend — and on the file backend's malformed or vanished-lock timeouts — the message says the lock stayed held but the backend cannot identify who held it, rather than printing a pid that means nothing. The elapsed wait is measured by the wrapper. `IndexLockTimeoutError` carries only `holder` and `holderKnown`; the figure exists solely inside the string being replaced, so it had to be taken rather than read. One pre-existing assertion changed with it: the timeout case asserted `'Timed out after 600000ms'` from the inherited text, which is precisely the message this replaces. Mutation-verified: restoring the inherited message turns the three assertion cases red and leaves the control — a real acquisition that succeeds — green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): stop a losing sync from downgrading the one that beat it to the lock Serializing is not ordering. Both syncs run extraction outside the critical section, so a total-failure sync that acquires second reads the winner's fresh registry as `prior` and rewrites it with all-unreadable lists. The lock alone does not prevent that — it only decides who goes second, and the loser then overwrites a healthy registry with a description of its own failure. Deterministically, not as a rare interleave. The guard is a compare-and-swap on the registry file's own identity: stat before acquiring, re-stat after, and write nothing when they differ. Identity is presence plus size, mtime and inode — `writeContractRegistry` publishes through write-then-rename, so a real replacement always changes the inode even if size and mtime happen to collide. Deliberately NOT keyed on `generatedAt`, for two independent reasons. It is stamped when the registry object is built, before the lock is acquired, so a winner that waited would write a value older than the loser's start. And the preserve path carries it forward verbatim by design — it dates the contracts, not the write — so after any preserve sync it does not date the write at all, leaving the comparison blind on exactly the pairing this guards. A file-identity compare also needs no cross-process clock agreement. The skip reports the existing `preserved` outcome. Nothing was written and a prior registry was kept, which is what that value already means; a new one would falsify the guard asserting the sync tool's description names every reachable outcome, and would fall through the CLI's outcome chain, which has no fallback. The bridge metadata refresh is skipped too, which the plan did not specify. `refreshPreservedBridgeMeta` stamps THIS run's repo lists into meta.json, and meta.json is where cross-repo impact reads completeness — so writing it would report as unaccounted-for exactly the repos the winning sync had just accounted for. That is the same downgrade being refused, one file over. Skipping both is what makes `preserved` an honest answer here. Mutation-verified: removing the after-stat and the skip turns the three decisive cases red while both non-misfire controls stay green. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(group): run the bridge swap inside the caller's critical section The bridge swap needed the group lock, and could not take it: `syncGroup` already holds it when it calls `writeBridge`, and `acquireIndexLock` is not reentrant. Acquiring inside the swap would deadlock every sync on the happy path rather than on an edge case. So the body splits the way this repo already splits this shape — a lock-free `writeBridgeUnlocked` whose precondition is that the caller holds the lock, and a thin `writeBridge` wrapper that acquires it for direct callers, mirroring `registerRepoUnlocked` / `withRegistryLock`. `syncGroup` calls the inner one; everything else keeps calling `writeBridge` and is now serialized by it. `writeBridge`'s exported signature is byte-identical to before, so no caller changed and nothing about the exported surface moved. The precondition is enforced by a comment naming the single production call site, which is what the existing precedent does. A type could carry it, but the repo's own answer to this question is a comment, and diverging here would make this the odd one out for no additional guarantee. `refreshPreservedBridgeMeta` is deliberately left unsplit. Its one caller is already inside the critical section and it has no test callers, so an acquiring wrapper would be dead code standing in for a guarantee the caller already provides — and moving the lock inside it would be the second acquisition this change exists to avoid. Scope: this delivers writer-writer exclusion only. The reader-side promotion of a leftover `.bak` into place runs on ordinary reads, outside any lock, and is not claimed here — the pairing check remains the reader's defense. Confirmed as live behavior while writing the crash-recovery test, which asserts on file state rather than through `bridgeExists` for exactly that reason. One test file beyond the two the unit named had to change: a suite mocks `bridge-db` to inject a `writeBridge` failure and exercise the bridge-write warning. Once the sync calls `writeBridgeUnlocked`, that fault was being injected into a function the path no longer calls, and the test went red. The mock is repointed. Mutation-verified three ways. Pointing the sync back at the acquiring wrapper deadlocks a single UNCONTENDED sync — the evidence that the nesting defect is real and that this split is what prevents it. Removing the wrapper's acquisition turns the direct-write exclusion case red. Making the lock-free half acquire for itself turns the held-lock case red. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(hygiene): reach every tracked text file with the raw-byte guard The guard claimed to protect tracked source from a raw NUL — the byte that makes git classify a file binary and costs it its diff, its inline comments and its three-way merge on GitHub. It matched on an end-anchored extension regex covering the JavaScript family, so most of what this repo tracks was never looked at: JSON, YAML, TOML, Markdown, snapshots, SQL, protobuf, the .NET project files, the shell and batch scripts. Worse, an extension regex cannot reach a file that has none. `Dockerfile`, `CODEOWNERS`, `LICENSE`, the husky hook and every bare dotfile were unreachable by construction — no amount of widening the pattern would have covered them — so a second basename filter had to exist for the claim to be true. It stays an allowlist rather than becoming "everything git tracks", because the repo legitimately tracks binaries whose extensions must stay out. The two filters together now collect every one of the 5000 tracked files except 31 — the 30 native prebuilds and one PNG — and those 31 are exactly the files that carry a NUL. The allowlist no longer has a gap that is not a genuine binary. The planted-fixture cases route through the collector's own predicate rather than straight into the scanner. The pre-existing fixture test bypassed the filter entirely, so it could only ever prove the byte locator worked, never that the collector would hand it the file — which is precisely how the gap survived. Mutation-verified both ways: removing the basename filter drops `.gitignore` and `Dockerfile` from the planted results, and reverting the extension regex drops `.json` and `.md`. One added case is a preservation pin rather than proof — that tracked binary formats stay out passes either way, and guards the allowlist from becoming a denylist later. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(hygiene): stop the byte guard reading the vendored grammar tree Widening the guard to every tracked text format also pulled in the vendored tree-sitter grammars, and those are where the bytes are: four generated `parser.c` files come to 62 MB between them, Kotlin's alone 33.7 MB. Excluding that root drops 76 files but 66% of the bytes the scan reads — 97 MB down to 33 MB. The exclusion is a single anchored prefix, matched case-sensitively with `startsWith`, and both halves of that matter. A `vendor` path-SEGMENT match would also drop first-party fixtures this repo tracks under directories named `vendor` and `Vendor` — a Kotlin one, a PHP one, and three files under gitnexus-web — silently narrowing coverage while the assertion pinned the loss in place. Case-insensitivity would do the same to a `Vendor` directory at the excluded root's own level. The root is named in the guard itself, so the claim that it covers every tracked text file stays honest about the one place it deliberately does not look. The cost comment was wrong and is now measured rather than estimated. It said "the scan is ~10 ms" — ambiguous between locating the byte and reading the files, and stale in its byte basis. Locating is ~14 ms; the reads dominate it by two orders of magnitude, which is the actual reason for the concurrency pool and the actual reason this exclusion is worth having. Every figure was re-derived from the finished file rather than carried over from a draft. The header's claim that `git ls-files` "never descends into vendor" was already false — vendored code is tracked, so all 106 of its files were being reported and read. Corrected here, where the distinction becomes load-bearing. Registered in the cross-platform list first and given a shard weight second. The weight table is only consulted for files already in that list, so a weight entry alone is inert and the shard test filters unregistered keys without complaining. The three-way split stays within 1.01x of ideal. Mutation-verified three ways: a case-insensitive segment match, a case-sensitive segment match, and a case-insensitive anchored prefix each turn an assertion red. The casing half was initially unfalsifiable — nothing tracked is named `gitnexus/Vendor/`, so a tracked-set assertion could not distinguish it. Rather than leave the claim unpinned or invent a fixture, it is pinned on the predicate with a synthetic path; the tracked-set assertions pin the anchoring. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(group): make the strict-read test able to see which read ran The file bound both registry exports to one mock: readRegistry: (...args) => readRegistryMock(...args), readRegistryStrict: (...args) => readRegistryMock(...args), so the case named for the strict read asserted a behavior it could not attribute. Point the production call at the lenient export and every assertion still holds, because the mock answers the same way whichever one is called. That is not a hypothetical. With this file as it was, and `syncGroup` mutated to call `readRegistry` instead of `readRegistryStrict`, all 32 tests passed — the suite was blind to the exact substitution it exists to prevent, and the fix it guards could have been reverted without a single red. The exports now have separate mocks: the lenient one always resolves an empty list, which is its real contract, and only the strict one is armed by the cases that need a failure. The named case also asserts directly that the strict read was called and the lenient one was not, so the attribution is explicit rather than implied by an outcome. No tests added — the unit is about what the existing ones can see. Mutation-verified: the same substitution now turns 24 cases red, including the named one, and everything stays green unmutated. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(group): pin the CLI output branches this PR introduced The three sync outcomes and the status table's new labels had no assertions. Every one of them is a sentence about what happened on disk, and this PR corrected several that were false — a preserve branch that announced it had not written the file it rewrites, a status table that called an unreadable registry a missing entry. Text that describes state, with nothing pinning it, is how those got wrong in the first place. Six cases drive the real CLI end to end, through the two shapes that need no indexed repo: members absent from the registry, and members registered at a storage path with no index file, which makes every repo unreadable. The file header claimed no LadybugDB-backed command was driven end to end; that is no longer true and it now says so. Each branch was suppressed in turn and its assertion goes red — all five that the plan named. One of those mutations first reported PASS, and the cause is worth recording: the string being suppressed also appears inside a neighbouring branch's comment, so the harness silenced the wrong line. That is a bad mutation, not a weak test. The harness now asserts the marker it suppresses is unique before trusting the result, and the redone check goes red. The plan's sixth scenario is already covered by an existing case that asserts both labels in one table, so it is not duplicated. A seventh case was added beyond the plan: without a populated-list case, "prints neither line" would pass just as well against a CLI that never printed that line at all. Adds about 15s of measured spawn time locally; CI runs these against the built dist, which is materially faster per spawn. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(group): assert the MCP payloads by exact shape, not by partial match Nothing asserted what the group tools actually return. The sync response's unreadable list and registry outcome, and the contract listing's incompleteness fields, are documented in the tool descriptions an agent reads — and could have been dropped in a refactor without a single test noticing. The assertions are exact-shape rather than partial. A `toMatchObject` would let a dropped key pass, which is precisely the regression these exist to catch: the failure mode is an absent field, and a partial match is defined not to see one. Absences are additionally asserted explicitly. The tri-state has to survive the response boundary, and it is the reason exact shape matters here more than usual. An absent `unreadableRepos` means the sync never recorded what it could read, so the listing is a floor; an empty list means it measured none; a populated list names them. Collapsing absent into empty turns "we do not know" into "we checked, it is fine" — so a mutation that replaces the conditional spread with `?? []` is covered specifically, not just the outright deletion. Mutation-verified per field: removing either sync forwarding line, deleting the conditional spread, replacing it with the invent-empty form, dropping the truncation triple, or hardcoding the provenance flag each turns an assertion red. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(group): stop the bridge input narrowing what unreadableRepos means The same field had three definitions. The registry and the bridge metadata both say it covers a repo this sync could not extract from — an index that would not open, or an extractor that threw partway through, one bucket because the consequence is one thing. The bridge input said only "whose index could not be opened", which describes one cause and silently excludes the other. It now points at the registry's definition instead of restating it a third time. A definition written once and referenced cannot drift; three copies of it already had. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(group): record what the mtime pairing does and does not prove The write-order fallback is a heuristic standing in for provenance, and a future reader deciding whether to lean on it needs to know where it breaks before they do. Both directions are now stated where the function is read rather than only in the plan that introduced it. The false-accept direction is a non-monotonic wall clock — mtime is realtime, so an NTP step back, a snapshot restore, or container skew between the two writes can leave a mis-paired set reading as ordered. Coarse filesystem granularity is explicitly called out as NOT being that hazard, because it looks like it: it collapses a pair written together to equal times, and equal is accepted, which is the right answer for that pair. The false-reject direction is any copy or restore that rewrites the database's mtime after the metadata's. An intact legacy pair is demoted to a lower bound and stays there until a sync re-stamps it, because nothing on the read path can tell it apart from the swap window it imitates. That second direction corrects a claim made while planning this work: that the rule could only ever demote pairs already broken. It cannot. `cp -r` and `rsync` without timestamp preservation both produce it on a healthy group, and saying otherwise where the code is read would leave a future reader to discover it the hard way. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(storage): stop a corrupt registry quoting its own bytes into errors `JSON.parse`'s SyntaxError embeds a window of the source around the failure — V8 gives exactly ten characters either side — and the strict read rethrew it untouched. The registry persists HTTPS remote URLs with their userinfo, so a file that breaks next to one puts the credential into the error: Unexpected token 'L', ..."end.git"},LEAKCAN4RY"... is not valid JSON The parse now has its own guarded region and reports the path and the failure class, matching the two corrupt-registry errors already in this function. The original error is discarded — not logged, not attached as `cause`. This codebase's convention elsewhere is to hand the logger the Error so it captures stack and cause, and following that convention here is precisely what would put the byte window into the log. Under MCP stdio that log is written to the client's log file on disk, so the thrown-error channel was never the only one that mattered. The `catch` takes no binding, so the error cannot be reused by accident later. That was not theoretical: a sibling commit routes this message into `unresolvableReason`, which `group status` returns to MCP clients and prints in the CLI table. Every channel was traced — throw, cause, inspect with the full chain, the logger, and both downstream consumers. The leaking shape is narrower than it first appears, and worth recording. The windowed message only fires when the parser fails at a value-start or trailing position; a break inside a quoted string yields an unterminated-string error carrying no window. So a plain mid-URL truncation does not leak — a short write landing over a longer one does, leaving a URL fragment where a value was expected. That is a reachable shape for the one machine-wide file every gitnexus process writes. The test asserts the message still names the path and the corruption class, not only that the secret is absent. Asserting absence alone would stay green if the message became empty. Mutation-verified: restoring the raw rethrow brings the token back verbatim. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(storage): drop the stale lenient call-site count The docstring said keeping `readRegistry`'s signature untouched leaves "its nine other call sites" unaffected. There were thirteen when the discrepancy was noticed and fourteen by the time it was fixed. The same figure appeared in the test file's header. Replaced rather than corrected. A count in prose next to code that moves is a claim that goes stale without anything failing — which is the defect class this change set exists to remove, so re-seeding a fresh number would be repeating it with a longer fuse. The argument was never about the quantity: leaving the signature alone keeps every lenient caller provably unaffected whether there is one or fifty. Also withdrawn while here: the claim that the bridge schema-version guards diverge between call sites. They do not — the two forms are complements for every value a writer can produce, there are three sites rather than the two claimed, and all three agree. Recording a divergence that does not exist would leave a future reader chasing it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(group): add an auditable finding-to-commit map The Definition of Done claims every review finding has exactly one commit and that reverting it reintroduces that finding and no other. Without a map that claim is only checkable by whoever holds the review report, which is one person for a short time. The map lists all 28 primary findings against their commits, the three findings whose suggested fix was deliberately not implemented and what shipped instead, and the four defects found while executing that no reviewer raised. It also records the revert contract honestly. Revertability is dependency-aware, not absolute: the shared completeness helper has three consumers, so reverting it alone does not build. That coupled set is named rather than left for someone to discover mid-revert. Two sections exist because the work produced them, not because the plan asked. Six claims in the plan turned out to be contradicted by the code — among them a scope predicate that would have reintroduced the bug its unit was closing, and an assertion about the mtime rule that was simply wrong. Recording only the findings would leave the impression the plan was followed as written. Five residual risks are listed for the same reason, including that R14 is not met on this PR: the diff attribute works locally but GitHub reads it from the base side, so this PR's own sync.ts stays binary in the web view and every PR after it renders as text. Not under docs/ — that path is gitignored, so a map written there would never reach the PR and the audit it exists for could not be performed by anyone else. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): read a version that is not a version as no provenance Raised by the check bot on this PR, and real — the bot found one symptom of it; the field splits four gates apart, not one. `readBridgeMeta` accepted any numeric `version`, and `0` is this file's word for "no provenance". A parseable but impossible value — negative, fractional — is not a schema version, and each gate that reads the field disagreed about it: ensureBridgeReady `> 0 && !== CURRENT` → opens the bridge openBridgeDbReadOnly `> 0 && !== CURRENT` → opens the bridge bridgeExists `=== 0 || === CURRENT` → says it is not there bridgeProvenanceUnknown `=== 0` → reports the answer complete Four verdicts about one file, and the last one is a fail-open of exactly the class this PR exists to close: a bridge nothing can vouch for, reported as fully accounted for. The suggested fix was to widen the provenance check to `<= 0`. That closes the reported symptom and leaves `bridgeExists` still disagreeing with both openers, so it is fixed at the reader instead: a version that is not a positive integer normalizes to the sentinel the gates were all written against. One change, four gates agreeing by construction, rather than teaching each of them the same new case and hoping the fifth reader remembers. Infinity is covered too, though by the pre-existing type check rather than the range one — JSON cannot carry it, so it arrives as `null`. Recorded at the test so the case is not mistaken for proof of the range check. Mutation-verified: restoring the loose numeric check turns the negative and fractional cases red. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): stop a malformed contracts.json reading as an unresolvable registry entry Raised by the check bot on this PR. Its stated mechanism was wrong — `loadMeta` returns null on every error and `checkStaleness` catches everything, so neither can throw — but its conclusion was right, and there is a concrete path it did not name. `readContractRegistry` is a bare `JSON.parse(content) as ContractRegistry` with no shape check, and the snapshot lookup guarded only the registry object: registry?.repoSnapshots[repoPath] The `?.` covers `registry` being null, not `repoSnapshots` being absent. A contracts.json without that field — a legacy file, a hand-edit, a truncated write — throws `TypeError: Cannot read properties of undefined`, which lands in the catch that labels failures as unresolvable GLOBAL-registry entries. So a group whose own contracts file is malformed reported every repo as a broken registry row, sending the operator to repair a file that was fine. An error from one cause presented as another, which is the defect this PR has been removing everywhere else. The optional chain closes the crash. The try is also narrowed to the call that earns the label: only `resolveRepo` sits inside it now, so "did not resolve" describes something that actually failed to resolve rather than whatever else happened to throw nearby. The comment records why the other two calls in that block cannot throw, so the next reader does not have to re-derive it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * refactor(group): give the completeness fold a module no native binding reaches The shared fold ended up in `cross-impact.ts`, which statically imports `bridge-db.ts` and through it the native LadybugDB binding. `groupContracts` therefore reached it through `await import('./cross-impact.js')` — loading that whole module graph to run a Set union and a ternary. Measured: 44-51ms and 8.4MB of RSS on first call, paid once per MCP server and once per `gitnexus group contracts` invocation. `completeness.ts` holds the vocabulary and the fold and imports nothing but types. `service.ts` imports it statically; the lazy import and the comment justifying it both go. `cross-impact.ts` re-exports so the three surfaces still have one import site for the vocabulary. Three other duplications collapse into the same move. `traceCompleteness` was hand-writing `{truncated, truncationReason, riskEpistemic}` — a third writer of the pair `truncationFields` exists to keep mechanically linked (#2787), in the file the consolidation had just touched. It calls the helper now. `recordedRepoList` existed twice, byte-identical, one copy's docblock saying it mirrored the other. That gate is the predicate the whole absent-vs-empty-vs-populated distinction rests on, applied to the same two lists on both the registry and the bridge — tightening one copy would have fixed one surface silently. One definition now. The trace's scope predicate compared repo paths with `===` while its sibling in `cross-impact.ts`, added in the same change, went through `repoInSubgroup` with a comment about not growing a second notion of membership. It had grown one: the helper normalizes separators and strips trailing slashes, so the same group.yaml spelling could be in scope for impact and out of scope for trace. Also here: `registryIdentifies` was a third, weaker copy of the registry's path rule — it skipped `realpath`, so a symlinked row would not match where the real resolver would. It uses `canonicalizePath`/`registryPathEquals` now. `contracts.json` is no longer respelled as a literal in `sync.ts`; `storage.ts` owns the name it reads and writes. And the runtime-truncation predicate is bound once instead of written out at both the flag and the reason, where forgetting the second would label a retry-able answer `incomplete-sync`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(group): give the lost-the-race sync its own outcome instead of overloading preserved A sync that finds contracts.json replaced while it waited for the lock reported `registryOutcome: 'preserved'`. That value already meant something else, and the two differ in exactly the thing the value is for: `preserved` rewrites the file with this run's diagnostics; this path does not touch it and deliberately does not record them. So both surfaces stated something false about disk. The tool description told agents `preserved` means "contracts.json was rewritten ... refreshing only missingRepos/unreadableRepos to describe THIS run (the file changed)". The CLI said "only the unreadable/missing repo lists were refreshed to describe THIS run". On the lost-race branch nothing was written and the log line beside it says so outright. That is the defect class this whole change set removes, reintroduced by the change set itself — and the reasoning recorded at the time makes it worse, not better: a new value was rejected because it "would fall through cli/group.ts's outcome chain, which has no fallback branch". A renderer limitation decided a domain value, and the description then had to cover two states with one sentence that fits one of them. `superseded` is its own outcome now, described in its own words to agents and rendered in its own words at the CLI. The registry on disk is FRESHER than this response's diagnostics, which is the opposite of every other non-written outcome and is why an agent needs to tell them apart. The CLI renders from a `Record` keyed on the union, so the next outcome fails the build here rather than printing nothing — the gap that made folding the state in look like the cheap option. The description guard is scoped per clause rather than over the whole string. It forbade "untouched" anywhere, which was right when one clause could only lie in that direction and wrong now that another clause is accurately untouched. It also asserts the superseded clause says so, or the two collapse back into one word for two states. Found by the quality pass over this branch, not by review. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * test(group): read bytes and stat through one handle, not two path lookups CodeQL flagged both sites as `js/file-system-race`, high severity, and it is right about the shape. `stat(path)` followed by `readFile(path)` is two independent path resolutions with a window between them — the classic check-then-use race. It also made the assertions weaker than they read. These two tests exist to prove a specific file was left untouched, and two lookups can land on different inodes, so "the bytes and the mtime are both unchanged" was not actually a statement about one file. The distinction is the whole point here rather than a technicality. `snapshotFile` opens the path once and takes both answers from that handle. The race is gone because there is no second lookup, and the assertion now genuinely concerns one inode. I had previously triaged these as below the ruleset's threshold and left them for the repository owner. That was wrong: they carry `security_severity_level: high`, and the branch ruleset gates on `high_or_higher`, so they were blocking the merge rather than sitting under it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Gergő Magyar <gergomagyar@icloud.com> Co-authored-by: Gergo Magyar <gergomagyar0@gmail.com>	2026-08-26 09:37:16 +01:00
azizur100389	24584297d2	fix(trace): add file disambiguator alias (#2705)	2026-07-27 05:05:14 +01:00
Parafee41	b85f1ace7a	fix(mcp): avoid api impact schema combinators (#2489) ... Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>	2026-07-16 15:20:22 +01:00
Gergo Magyar	c836801c4a	feat(mcp): add deterministic response budgets (#2460) ... Composed with the read-only and repository policies in the CallTool handler: read-only assert, then budget resolution, then scoped dispatch with the transport arg stripped. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-16 08:59:05 +00:00
Eva	3f3494fd32	fix(mcp): validate aliases without schema combinators	2026-07-16 09:29:47 +07:00
Eva	a75844b692	feat(mcp): normalize impact and context aliases	2026-07-14 01:54:49 +07:00
Eva	627ec5a5aa	feat(mcp): add deterministic output budgets	2026-07-14 01:48:17 +07:00
Gergő Magyar	57e4afa4c8	fix(mcp): stabilize api_impact response shape for same-URL multi-verb routes (#2308) (#2309) ... * fix(mcp): stabilize api_impact response shape for same-URL multi-verb routes After #2302 made Route identity method-aware, a same URL exposes one Route node per HTTP verb, so a bare-URL api_impact lookup could silently flip from a direct route object to the wrapped { routes, total } envelope. Surface each route's `method` (via the shared fetch) so multi-verb results are distinguishable, and add an optional `method` selector that narrows a multi-verb URL/file to one verb and forces the singular shape. A verb that matches no route returns a clear error. Document the match-count contract in the tool schema. Refs #2308 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(mcp): cover same-URL multi-verb api_impact contract Regression coverage for #2308: bare-URL and bare-file lookups of a same-URL GET+POST pair return the wrapped form with distinct per-route methods; the method selector collapses to the singular shape (case-insensitively); an unmatched verb returns a verb-not-found error; and verbless routes surface a null method. Refs #2308 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(review): apply autofix feedback - tools.ts: correct api_impact contract docs — `method` narrows to one verb but the singular shape only holds when exactly one route remains after filtering (substring route/file matches can still wrap); cover file lookups; enumerate verbs. - local-backend.ts: surface `method` in route_map and shape_check output (the shared fetch already returns it; agents discover verbs there before api_impact). - local-backend.ts: compute routeCountByHandler from the unfiltered match so a method-scoped api_impact still flags a multi-verb handler's partial middleware. - tests: add file+method and verbless-exclusion cases; assert unconditionally via toMatchObject; lowercase the verb-not-found input to exercise error uppercasing. Refs #2308 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): treat wildcard '*' routes as matching any api_impact method selector (#2308) Method-agnostic routes (Django function views) persist with Route method '*', not null. The api_impact method selector used exact verb equality, so '*' routes were excluded and api_impact({route, method:'POST'}) falsely reported 'No routes found' for a route that handles every verb. Treat '*' as matching any requested verb, and correct the comment + tool-description strings that wrongly grouped Django wildcards with null/verbless routes. * fix(mcp): harden api_impact method input against non-string and empty values (#2308) The MCP envelope is not schema-validated, so a non-string `method` reached `.toUpperCase()` and threw a TypeError. Widen the param to `unknown` and guard it with a typeof check that returns a structured error (mirroring the resolveAliasString pattern from #2175), and collapse empty/whitespace verbs to no selector. * fix(mcp): distinguish url-not-found from verb-not-found in api_impact error (#2308) The verb-not-found error appended 'with method "X"' even when the URL/file itself did not exist, implying the URL exists with other verbs. Gate the verb clause on matched.length > 0 so a non-existent URL/file gets the plain message. * fix(mcp): clarify api_impact middlewareNote wording for verbless siblings (#2308) The partial-middleware note claimed 'other methods in this handler' even when the co-located sibling is a verbless (null) route rather than another HTTP verb. Refer to 'other route exports' instead, which covers both cases. * docs(mcp): document and test the method field on route_map and shape_check (#2308) The shared fetchRoutesWithConsumers change surfaced a method key on route_map and shape_check responses too, but their tool descriptions never mentioned it and no test covered it. Document the field on both descriptions and add unit tests asserting it (shape_check rows carry responseKeys + a consumer so they survive shape_check's keys-and-consumers filter). * test(mcp): cover middlewareDetection 'partial' survival under a method filter (#2308) The diff's core behavioral line counts verbs-per-handler from the unfiltered match set so a method-scoped query still flags a multi-verb handler's partial middleware, but no test exercised it (every verbRow hardcoded middleware:null). Add a middleware param to verbRow and a test that fails if the count is taken from the post-filter set instead. Verified via mutation: matched->routes fails it. * test(mcp): add live-LadybugDB integration coverage for route method round-trip (#2308) The new n.method query column was only unit-mocked. Add a self-contained integration suite that seeds GET+POST /api/orders and a method-agnostic '*' Django route, then asserts api_impact surfaces method, narrows by verb, and matches the '*' route end-to-end (the U1 fix), plus route_map surfacing. Own seed + no FTS so it neither perturbs api-impact-e2e nor silently skips. * refactor(mcp): type the api_impact response shape instead of Promise<any> (#2308) Replace apiImpact's Promise<any> with an explicit ApiImpactResult union (single route | wrapped { routes, total } | { error }) and a typed ApiImpactRoute. The results.map is annotated so the response builder is checked against the declared shape. Behavior unchanged; sibling MCP methods keep their Promise<any> convention. * fix(mcp): express the route-or-file requirement in the api_impact schema (#2308) The inputSchema left route/file as bare optionals, so the 'at least one of route/file' rule the handler enforces was invisible to clients. Add an optional anyOf to ToolDefinition (forwarded verbatim by the ListTools handler) and an anyOf:[{required:[route]},{required:[file]}] on api_impact. Matches runtime (both allowed, route wins); 'at least one' not 'exactly one'. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-26 19:50:10 +01:00
Gergő Magyar	47477e5554	fix(mcp): tolerate adapter-materialized line:0 in impact callgraph mode (#2279) (#2283) ... * fix(mcp): tolerate adapter-materialized line:0 in impact callgraph mode (#2279) Some MCP client/agent adapters serialize an omitted optional numeric field as `0` rather than dropping it, so callgraph `impact` calls arrive carrying a spurious `line: 0`. `line` is a PDG-only statement anchor and is meaningless on the callgraph path, so the backend rejected the call ("'line' is only supported with mode:'pdg'") and strict clients rejected it client-side against the advertised `minimum: 1`. Treat a literal `line: 0` as omitted in `_impactImpl` when mode !== 'pdg' and let the normal symbol→symbol BFS run. The coercion is deliberately narrow: only the literal 0, only on the callgraph path. A genuine positive `line` on callgraph still errors (real mode mistake), negative/ fractional values still error, and pdg mode is untouched — `line: 0` there is still rejected (there is no 1-based source line 0 to anchor on). Regression tests pin the full matrix: callgraph + line:0 runs the BFS and is byte-identical to omitting line; pdg + line:0 still errors; positive line on callgraph still errors. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): log swallowed best-effort query degradations at warn, not error `logQueryError` is the shared handler for query failures that every caller catches and degrades past with a safe fallback (the operation still returns a result). It logged all of them at `logger.error` (level 50) — the same severity as fatal failures — so a gracefully-handled degradation raised a false alarm and drowned genuine errors. This surfaced as an ERROR-level log firing during a passing unit test that intentionally injects a slice-callees query failure to verify the degrade path. Make the severity match reality: - benign missing optional table/label/column (a repo analyzed without processes/communities, or a pre-v3 PDG index lacking the `calleeIds` column — a query that fails on every pdg-downstream impact for such an index) → debug, the normal-configuration case. - any other swallowed failure → warn (handled degradation, still observable). - error is reserved for failures that actually abort an operation, which log directly rather than through this helper. Also fix the sibling bm25/FTS fallback, which logged its swallowed "FTS indexes may not exist" degradation at error while its own import-failure fallback already used warn. The slice-callees degradation test now captures the log and asserts it lands at warn (40), not error (50), pinning the severity against regression. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): relax impact `line` schema minimum to 0 for adapter compatibility (#2279) Strict MCP clients/agents validate against the advertised input schema and reject a request before sending it. With `line` declaring `minimum: 1`, a client that materializes the omitted optional `line` as `0` rejects a perfectly valid callgraph impact call client-side — so the backend tolerance added in the previous commit never gets a chance to run. Lower the advertised `line.minimum` to 0 and document that 0 (or omission) means "no statement anchor" while mode:'pdg' still requires a positive line. The advertised schema is advisory (the backend self-validates and is the real gate), so this cannot loosen any enforced contract — it only stops strict clients from pre-rejecting `line: 0`. Negative lines are still rejected at the client boundary. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(review): apply autofix feedback Code-review autofix pass on the #2279 branch: - Replace a newly-introduced `mode as any` cast in the #2279 it.each with the narrow `mode as 'callgraph' | undefined` (strict-typing-no-any). - Add a degradation test for the new logQueryError benign-missing-table → debug branch (asserts no warn/error record surfaces, i.e. it routed to debug). - Pin the bm25/FTS error→warn severity change with a _captureLogger assertion in the existing #1489 test. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): make swallowed-failure callers surface degradation; narrow benign-error match (#2283) Tri-review (#2283) found the `error → {debug|warn}` rework reduced telemetry for `logQueryError` callers that do NOT degrade safely, while the docstring over-claimed "every caller degrades to a safe fallback". Address the substance rather than only the log level: - rename apply-edit: track failed writes and return status:'partial' with `failed_files` instead of reporting `status:'success'` when a write was swallowed. A partial rename is no longer indistinguishable from a clean one. - detect_changes: a swallowed symbol/process query failure now sets `partial:true` (rendered by the existing eval-server partial path) so the pre-commit safety gate can't return a false-clean `risk_level:'low'` no-op. - isBenignMissingTableError: scope the `not (defined|found)` arm to a schema object (table/label/rel/column/property), mirroring lbug-adapter's isMissingColumnError. An unscoped "not found" matched operation failures like `rg: not found` / `Symbol not found` and silently demoted them to debug. - logQueryError docstring: state the contract honestly — level reflects telemetry severity, and mutating/safety-critical callers MUST also surface a result-level degradation signal; `warn` alone is not a substitute. - pdg dispatch: pass the normalized `effectiveLine` (not raw params.line) so the validation gate and engine share one source of truth (identity today). Tests: - _captureLogger(level?) lets tests capture below info; the benign-missing-table test now asserts the record IS emitted at debug (20), not merely absent — no longer a vacuous pass if the call were deleted. - new: a non-schema "not found" failure logs at warn (regex-narrowing guard); rename write-failure degrades to status:'partial'+failed_files; line:-1 on the callgraph path still errors (line:0 coercion is narrow); typed the it.each tuple to drop a `mode as` cast. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(mcp): fix impact `line` description contradiction for whole-symbol pdg (#2283) The new `line` schema description said "mode:'pdg' requires a positive line", which contradicted the top-level impact description ("Without 'line', pdg returns whole-symbol inter-procedural reach plus local whole-symbol PDG diagnostics"). A pdg call without a line is a valid (degraded whole-symbol) call, not an error — the old wording could push an agent to avoid valid no-line pdg calls or synthesize line:0 (which then hard-errors). Reword to: omit line for whole-symbol pdg; a positive line anchors a statement slice; literal 0 is tolerated only as an omitted-line compatibility sentinel on the callgraph path and is rejected for mode:'pdg'. Update the schema test to pin the new, non-contradictory wording and assert "requires a positive line" is gone. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-23 20:35:49 +01:00
Gergő Magyar	1a03c8527a	feat(group): cross-repo call trace using PDG (#2269) ... * refactor(group): extract shared resolveBridgeNeighbors from cross-impact Lift the uid-filtered consumer<->provider ContractLink join (direction + queryBridge + row normalization + confidence sort) out of runGroupImpact's inline Phase-2 block into an exported resolveBridgeNeighbors helper. Behavior is unchanged for impact; the helper becomes the single shared bridge join so the upcoming cross-repo trace path never forks its own copy of the neighbor Cypher. Empty uid sets short-circuit without a DB round-trip. Adds direct coverage (real bridge via writeBridge/openBridgeDbReadOnly) for both directions plus the empty-set and unknown-uid edges. * feat(group): cross-repo trace stitching (groupTrace + runGroupTrace) Add GroupService.groupTrace and the pure runGroupTrace engine that stitches per-repo CALLS/HAS_METHOD trace segments across one ContractLink boundary in the group bridge: from --(local trace)--> consumer --(ContractLink)--> provider --(local trace)--> to - Resolves from/to across all members (symbol node id == bridge symbolUid); same-repo endpoints delegate to a single local trace with no crossing. - Single boundary crossing (MAX_SUPPORTED_CROSS_DEPTH); deeper crossDepth is clamped with a note, mirroring cross-impact. - Discriminated GroupTraceResult union (ok|not_found|ambiguous|error) with per-hop repo tags, a typed crossings[] entry, and centralized degraded-state note constants (TRACE_NOTES). No . - Trace-specific pair query (keeps BOTH crossing endpoints) lives in this module; the uid-filtered neighbor join (resolveBridgeNeighbors) is reused where it fits. ensureBridgeReady exported for reuse. - New GroupToolPort methods (trace/resolveSymbol/pdgFlows) are optional so existing port mocks keep type-checking; runGroupTrace guards on presence. PDG enrichment is wired as an opt-in hook (enrichSegment) — the port method is stubbed until U4. Covered by unit tests over a real bridge + mocked port. * feat(group): route trace tool to groupTrace on @group syntax Wire the cross-repo trace through the existing @group dispatch: - callTool routes trace with an @-prefixed repo to callToolAtGroupRepo, which forwards from/to/uid/file/maxDepth/includeTests plus the experimental pdg/crossDepth flags to GroupService.groupTrace. Member path in @group/path is advisory for trace (resolution is whole-group). - Port gains trace/resolveSymbol/pdgFlows adapters. resolveSymbolForGroup wraps the shared resolveSymbolCandidates so groupTrace can locate the member repo and recover each endpoint node id (== bridge symbolUid). pdgFlowsForGroup is a degraded stub here (call-level only); U4 implements the REACHING_DEF walk. - trace tool schema documents the @group entry point, pdg, and crossDepth. Single-repo trace is untouched. Covered by dispatch-routing tests (@group -> groupTrace, non-group stays local) and tool-schema assertions. * feat(group): opt-in PDG data-flow enrichment for cross-repo trace Implement _pdgFlowsForGroupImpl: the real REACHING_DEF anchor walk that backs the port pdgFlows adapter (replacing the U3 call-level stub). When pdg:true and the segment repo has a flows PDG layer, the boundary-adjacent segments carry their intra-procedural def->use hops: - Anchors by the boundary symbol UID (precise; avoids the by-name ambiguity the resolveBlockAnchor path can hit), then reuses the same span-anchored, bind-param-only flows query as pdg_query (BasicBlock id-prefix + [start+1, end+1] line window; no rel-property index, so the anchor IS the bound). - Stays intra-procedural: data flow never crosses the repo boundary. - pdgStampForMode probe: false -> available:false (degrade with note); the trace stays ok. Any query failure is swallowed (enrichment is auxiliary). Covered by runGroupTrace enrichment tests: dataFlow attached on opt-in, degraded note when no layer, and no pdgFlows call when pdg is omitted. * test(group): evaluation-first cross-repo trace e2e (two real indexes) End-to-end gate for the cross-repo trace: stands up two real LadybugDB indexes (consumer 'frontend' + provider 'backend'), a real ContractLink bridge, and a real LocalBackend with both repos registered, then drives the public callTool('trace', { repo: '@grp', pdg: true }) and asserts: - the stitched checkout -> callUsers -(CONTRACT_LINK)-> handleUsers -> getUsers path, each hop tagged with its member repo - real REACHING_DEF data-flow enrichment of the consumer segment (userId) - a degraded 'No PDG layer in app/backend' note (provider has no PDG layer) - single-repo trace against one member is unchanged (no crossings) Hand-persists the minimal real graph (deterministic; a full two-repo analyze is heavier than this gate needs) and exercises real Cypher across resolveSymbolCandidates, _traceImpl, the bridge pair query, and _pdgFlowsForGroupImpl. Windows-skipped (describeReopen) and registered in the cross-platform native-lbug set. Scoped to a single @group call: opening bridge.lbug read-only a SECOND time in one process currently fails (shared bridge open/close lifecycle, also affects impact @group) — the pdg-omitted/clamp variants are unit-covered. * docs(group): document cross-repo trace + PDG enrichment ARCHITECTURE.md: trace is now group-aware; describe the @group cross-repo stitch over a single ContractLink boundary (CONTRACT_LINK hop, crossings[], crossDepth clamp), the opt-in experimental PDG REACHING_DEF enrichment of boundary-adjacent segments, the symbolUid-grain join between the two stores, and the deferred full cross-program (SDG-like) data flow. PIPELINE.md: add the cross-trace consumer of the bridge with its pair-query rationale. Does not touch gitnexus/CHANGELOG.md (release-owned). * fix(review): apply autofix feedback Apply safe_auto findings from ce-code-review (run 20260622-094243): - local-backend.ts: drop (r: any) in _pdgFlowsForGroupImpl row map; coerce hop line via Number() so a nullish LadybugDB cell can't surface NaN. - tools.ts: advertise the forwarded param in the trace schema and add crossDepth maximum:10 (schema now matches what groupTrace reads). - cross-trace.ts: parallelize per-member resolveSymbol/resolveRepo with order-preserving Promise.all (matches groupContext/groupQuery); add a note when pdg:true is passed to a same-repo trace (PDG only enriches at a cross-repo boundary). - tests: remove / tighten (no-any rule). Residual gated_auto/manual findings (unbounded crossing query + loop, whole-file PDG widening on absent span, error-vs-no_path masking, top-level try/catch parity, helper dedupe, branch-coverage gaps) are recorded in the run artifact for the PR body. * fix(group): skip CHECKPOINT on read-only bridge close so it can reopen Root cause of the in-process bridge.lbug reopen failure (which broke repeated @group impact/trace calls in a long-lived MCP server): closeBridgeDb issued CHECKPOINT on EVERY handle, including read-only ones. A CHECKPOINT on a read-only connection has nothing to flush but leaves a WAL/shadow lock artifact that makes the next read-only open of the same path fail (openBridgeDbReadOnly returns null -> 'Could not open bridge.lbug read-only'). Reproduced: open -> query -> closeBridgeDb -> open again returned null only when the close ran CHECKPOINT; a non-checkpoint close reopened fine, and the raw native open/close cycle was never the problem. Fix: tag read-only handles (BridgeHandle._readOnly, set by openBridgeDbReadOnly) and skip CHECKPOINT for them in closeBridgeDb. Writable handles are unchanged (they still flush before close). This is the shared bridge-db close path, so impact @group benefits identically. - Regression test in bridge-db.test.ts: open/query/close/open/query/open in one process now succeeds. - Re-enabled the second @group call in cross-trace-e2e.test.ts (was scoped to a single call for this very limitation). * fix(group): bring bridge-db close to parity with the core adapter safeClose The bridge open/close cycle was less robust than the main graph DB's: closeBridgeDb closed the connection/database but skipped the post-close steps the core adapter's safeClose performs, so a rapid in-process reopen could race the OS handle release (Windows) or an orphaned WAL sidecar. That gap is why the close-then-reopen tests had to skip Windows. closeBridgeDb now mirrors safeClose after closing the handle: - waitForWindowsHandleRelease(dbPath): probe the file (+ .wal) until the residual Windows lock clears, so the next open does not race (warns if the budget is exhausted, matching the core adapter). - finalizeLbugSidecarsAfterClose(dbPath): quarantine an orphaned WAL (shadow missing) so the next open replays a consistent file. Both helpers are the same ones safeClose uses (Windows-proven via the core adapter CI), and the bridge read open already retries transient locks. Combined with the read-only CHECKPOINT skip, the bridge reopen is now robust on every platform, so the close-then-reopen tests run on all platforms (Windows CI exercises them via the cross-platform subset). No write-path behavior change; Linux/macOS unaffected. * fix(group): bound cross-repo crossing fan-out (LIMIT + segment memoization) Address the top review residual: the bridge crossing query was unbounded and the crossing-selection loop could run an O(2*N) sequential trace-BFS over every ContractLink between a repo pair. - CY_CROSSINGS_BETWEEN now ORDERs BY confidence DESC and LIMITs to MAX_CROSSINGS_TO_TRY + 1; listCrossingsBetween slices to the cap and reports truncation. Exceeding the cap surfaces a note (no silent truncation), keeping the highest-confidence crossings. Aligns with the repo's anchored+LIMIT-bounded query discipline (LadybugDB has no rel-property index). - The home-repo segment (from -> consumer) depends only on the consumer uid and the target-repo segment (provider -> to) only on the provider uid, so each is memoized by that uid. Many crossings sharing a consumer/provider (one client call linked to several providers) now cost one trace per distinct endpoint instead of one per crossing. A consumer whose segment already failed is skipped for every later crossing that shares it. Test: two links sharing a consumer (first provider unreachable, second reachable) assert the from->consumer segment is traced exactly once and the second crossing wins. * fix(group): restore Windows skip for bridge reopen tests; drop ineffective close-side probe The previous commit flipped the bridge close-then-reopen tests to run on Windows, betting that a close-side waitForWindowsHandleRelease + finalizeLbugSidecarsAfterClose probe (mirroring the core adapter safeClose) would make the in-process reopen work there. Windows CI proved otherwise: 4 writeBridge->openBridgeDbReadOnly tests fail ('expected null not to be null' — the read open returns null). The writable-close -> read-open handoff plus writeBridge's atomic sidecar rename does not release the OS file handle before the read open races, and the existing open-side LBUG_OPEN_RETRY only retries lock-pattern errors, not the post-rename sidecar database-id mismatch. macOS passes; the core adapter's own reopen also passes — this is bridge+Windows specific. - Revert itLbugReopen to the Windows skip (the pre-existing, correct state). - Remove the close-side probe + finalize from closeBridgeDb: it did NOT close the Windows gap, and reviewers flagged it for hot-path latency (finalize ran on every close, all platforms) and safeClose duplication. - KEEP the load-bearing fix — skipping CHECKPOINT on read-only handles — which fixed the reproduced Linux/macOS in-process reopen artifact (the real bug). Net: Linux/macOS repeated @group impact/trace works in-process; Windows in-process bridge reopen remains a documented limitation (unchanged from before this PR). * fix(group): surface degraded members + cap truncation; honest crossDepth schema Address the cross-engine-corroborated tri-review findings (Codex + Claude): - resolveAcrossMembers / runGroupTrace now track member repos that could NOT be queried (resolveRepo or resolveSymbol threw) and, when the result is not_found, attach a degraded-member note. A transient/corrupt member DB is no longer silently reported as a clean 'symbol absent' not_found. (Codex B1+B3 + ce-reliability.) - The cross-repo not_found now carries a programmatic truncated:true flag (and a clearer suggestion) when the MAX_CROSSINGS_TO_TRY cap was hit, so a consumer can distinguish 'no path' from 'cap may have hidden a connecting ContractLink'. (Codex B3 + ce-adversarial + ce-api-contract.) - trace tool schema: crossDepth maximum 10 -> 1 to match the implementation's single-hop clamp (the schema previously advertised an unsupported 2-10 range). (ce-api-contract, conf 100.) Test: a member whose resolveSymbol throws yields not_found WITH a degraded note naming the unreachable repo (if-free responder map). * docs(group): clarify trace @group/memberPath is advisory (resolves all members) Tri-review (Codex ce, conf 100) caught a doc/impl inconsistency: ARCHITECTURE.md lumped trace with query/context/impact as honoring @group/memberPath member scoping, but cross-repo trace resolves from/to across ALL members (the member path is advisory). Clarify the behavior and point to from_uid/to_uid for disambiguating same-named symbols across members. * feat(group): file-level boundary fallback so cross-repo trace works on HTTP contracts Benchmark (bench/cross-repo-trace/) running the REAL pipeline (runFullAnalysis --pdg -> real syncGroup -> trace @group) found that cross-repo trace returned not_found for real HTTP links even though sync built the correct ContractLinks: HTTP (and other source-scan) contracts hardcode symbolUid:'' (http-route-extractor), and both cross-trace AND cross-impact join crossings by Contract.symbolUid, which never matches an empty uid. (Pre-existing — impact @group has the same gap.) Fix: when a crossing's symbolUid is empty, fall back to the contract's FILE — if the user's from/to resolves into the contract file, that endpoint anchors the boundary. CY_CROSSINGS_BETWEEN now returns consumer/provider filePath; a crossing is kept if it can be anchored by uid OR file on each side; a fileBoundaryFallback note flags that the boundary is file-level, not symbol-precise. This makes the common 'trace from=<calling fn> to=<handler fn>' case work end-to-end (verified: fetchUsers -> listUsers stitches with a CONTRACT_LINK hop + PDG enrichment, 2/2). Limits (documented in the bench README + the note): anonymous handlers have no named target; when several contracts share files the file fallback may attach the wrong contractId to a correct path. The proper upstream fix is to populate symbolUid in the HTTP extraction (benefits impact too) — the bench is its gate. Adds a unit test pinning the empty-symbolUid file-fallback stitch. * fix(group): resolve HTTP contract symbolUid by containment (fixes cross-repo trace + impact) Addresses the root cause behind the cross-repo trace file-fallback: HTTP contracts hardcoded symbolUid:'' (http-route-extractor), so both cross-trace and cross-impact — which join crossings on Contract.symbolUid — could not traverse HTTP links. (Also found: the pre-existing graph-assisted resolution queried the wrong edge, CONTAINS instead of DEFINES, so it never resolved a uid either.) Now the extractor resolves each detection to a real symbol: - HttpDetection carries the call-site line (node.ts sets it on every express/ fetch/axios/jquery/nest detection; express also captures the handler arg). - resolveDetectionSymbol resolves the named handler first, else the innermost Function/Method whose line span encloses the call (consumer = the function containing the fetch; provider = the named/inline handler), over the correct File-[DEFINES]->symbol edge. Base-tolerant (0- vs 1-based startLine). - Wired into both source-scan and graph-assisted provider/consumer paths. Verified end-to-end (bench/cross-repo-trace): all 4 contracts now carry real uids, trace is symbol-precise (GET pair -> http::GET, POST -> http::POST, no file-fallback note), and impact @group fans out (cross_repo_hits 0 -> 1). The cross-trace file-level fallback remains as the secondary path for truly anonymous handlers. Adds 2 containment unit tests; 738 group/integration pass. Languages other than JS/TS still resolve providers by handler name; their consumers fall through to the file fallback until their plugins set the line. * fix(group): extend HTTP symbolUid containment to all languages + nested methods Completes the symbolUid resolution across every bundled HTTP plugin: Python, Go, PHP, Kotlin and Java now set the call-site line on their consumer (and Feign/ named) detections, so their HTTP contracts resolve to the containing function the same way Node/TS already did. Also generalizes the containment query: it now matches Function/Method/CodeElement by filePath (UNION ALL) instead of File-[DEFINES]->symbol. The DEFINES edge only reaches a file's TOP-LEVEL symbols, so methods nested in classes (Java/Kotlin — File defines the class, the class defines the method) were invisible; matching by filePath reaches them. Verified against a real index (LadybugDB supports the UNION); JS/TS still fully symbol-precise (bench 2/2), 709 group tests pass. Residual is now only the inherent case — a fully anonymous handler with no named callee — which keeps the cross-trace file-level fallback. * feat(group): destination trace — follow a consumer to an anonymous handler Handles the one inherent residual: an anonymous route handler (`router.get('/x', (req,res) => …)`) has no symbol node at all (the file holds only a Const + PDG BasicBlocks), so it can never be named as a trace `to`. Adds a DESTINATION TRACE: omit to/to_uid/to_file on an @group trace and `trace from=<consumer>` follows the consumer's outgoing HTTP call across the bridge and reports where it lands — by route + file:line, with a notes[] entry flagging the handler as anonymous. Implemented as a new branch in runGroupTrace (p.destination) backed by CY_CROSSINGS_FROM (all ContractLinks leaving the consumer repo) + stitchToDestination; the provider endpoint is labelled '<METHOD /path handler>' when its symbolName is a generic token/file basename. The MCP routing already omitted an absent `to`, so only the schema docs changed. parseTraceParams now treats a missing `to` as a destination trace instead of an error. Verified end-to-end: anonymous fixture reports 'app/frontend:fetchUsers -> app/backend:<http::GET::/api/users handler>'; named fixture lands at the real function. Adds 2 unit tests; 915 group tests pass. * fix(group): tri-review fixes for cross-repo trace + symbolUid resolution Two-engine tri-review (Claude swarm+ce + Codex GPT-5.5 swarm+ce+adversarial) surfaced these; cross-engine-corroborated unless noted. Correctness (P1, all four lanes): destination trace reported the WRONG endpoint — an empty-uid consumer made trace(from->from) trivially succeed, so the highest- confidence same-file crossing won regardless of which call `from` makes. stitchToDestination now collects ALL connecting crossings, prefers symbol-precise hits, and returns `ambiguous` (with candidates) when it cannot disambiguate. Correctness (P1, Codex): resolveDetectionSymbol early-returned null when d.line==null, blocking NAME resolution for named providers that set no line (Spring/Go/etc.). Name resolution now runs first; only containment needs a line. Correctness (P2): resolveContainingSymbol OR-ed `line` and `line-1`, which could mis-pick a one-line sibling. It now probes the base-correct `line-1` first and falls back to `line` only if nothing matches. Correctness (Codex): anonymous Express handlers emitted name:'handler' and could attach to an unrelated fn literally named `handler`. node.ts now emits name:null for non-identifier handlers (containment-only). Robustness: drop the first-symbol-in-file pickSymbolUid guess from the graph consumer/provider paths (a wrong uid would win the contractId merge); remove the dead CONTAINS_QUERY fallback (CONTAINS is File->Folder, never a symbol) + the now -unused pickSymbolUid/handlerName; seed destination notes with degraded-member notes so a successful trace still surfaces them; providerLabel takes providerUid so a resolved fn named `handler` is not mislabeled anonymous, and only true file basenames (known extensions) — not any dotted name — count as anonymous. API contract: a single-repo trace with no `to` now returns an actionable error (destination trace is @group-only) instead of "symbol 'undefined' not found". Maintainability/tests: narrow asLocalTrace per-field (drop as-unknown-as); fix the PR's lone as-any (vi.mocked); if-free e2e teardown; qualify the bench README. Adds ambiguous-destination, anonymous-handler-no-false-name, and single-repo-no-to tests; redirects graph mocks CONTAINS->UNION ALL. 918 group/integration pass. * fix(group): carry degraded-member notes through SUCCESSFUL group traces A reviewer (koriyoshi2041, PR #2269) correctly flagged that degraded-member resolution was surfaced only on not_found, not on a successful ok result. Group trace resolves names across ALL members, so an ok is 'unique among the members we could query' — if a member that threw during resolveSymbol also holds from/to, the real answer could be ambiguous. The destination path already seeded the note (prior commit); this extends it to the same-repo and cross-repo success paths by seeding the dispatch notes with degradedNotes([...fromRes.degraded, ...toRes.degraded]). Adds a regression test: reg-be throws while a same-repo trace succeeds in reg-fe; the ok result now carries the 'could not be queried' degraded note (app/backend). * test(bench): cover all implemented cross-repo trace cases in one runner Replace the single named-handler script with a self-contained verify.mjs that generates each fixture inline and exercises every implemented end-to-end case against the real analyze -> sync -> trace/impact pipeline, asserting PASS/FAIL (exit non-zero on failure). 10 checks across 4 scenarios: - named handlers: 4/4 symbolUid resolved; symbol-precise GET vs POST crossing selection; destination trace lands at the named handler. - anonymous handler: empty symbolUid; destination trace reports it by route with the anonymous note. - impact @group fan-out (cross_repo_hits >= 1). - multi-language (Python Flask + requests): link built, cross-repo trace stitches, and the file-level boundary fallback is exercised when the provider has no uid. Ambiguous-destination and degraded-member paths need synthetic inputs the real analyzer cannot produce, so they stay in the unit suite (documented in the README + script header). Removes verify-named.mjs + fixtures-named/ (folded inline). * test(group): pin destination degraded-success + precise-tier ambiguity Adds the two regression guards koriyoshi2041 requested on PR #2269 after the degraded-on-success fix: - destination trace success with a degraded member: reg-fe resolves from and follows the link to an anonymous handler while reg-be throws; the ok result carries the anonymous endpoint AND the 'could not be queried' degraded note, so the no-to path stays aligned with explicit to traces. - multiple PRECISE destination hits: one from reaches two consumers with resolved uids linked to different routes; the result is ambiguous (role: to) with both route candidates. Distinct from the existing file-level ambiguous test, this pins the stronger precise tier against a future change silently picking the highest-confidence destination. Both already pass against current behavior; 716 group tests pass.	2026-06-23 07:54:13 +01:00
Gergő Magyar	78b4077d8a	feat(impact): opt-in PDG-backed impact mode - statement + inter-procedural slicing, resolved-callee-id soundness, mutation-oracle validated (#2227)	2026-06-20 12:04:32 +01:00
Goutham Krishna Mandati	4c73b18387	feat(mcp): add trace tool for shortest call path between symbols (#2173) ... * feat(mcp): add trace tool for shortest call path between symbols (#1821) Implement the \ race\ MCP tool and \gitnexus trace\ CLI command that finds the shortest directed call path between two symbols using BFS over CALLS + HAS_METHOD edges. - MCP tool definition in tools.ts with READ_ONLY annotations - Directed BFS in local-backend.ts with parent-map path reconstruction - Symbol resolution via resolveSymbolCandidates (name/UID/file-hint) - Gap reporting with furthest reachable node and depth tracking - CLI wiring: gitnexus trace <from> <to> [--from-uid] [--to-uid] [--depth] - i18n keys in en.ts and zh-CN.ts + help-i18n.ts registration - ARCHITECTURE.md tools table entry - 16 unit tests (11 BFS core + 5 CLI wiring) * test(mcp): account for trace tool in tools.test.ts count The trace tool makes GITNEXUS_TOOLS length 15; update the hardcoded count, add 'trace' to the expected-names list, and refresh the stale "13 tools" comment and it() title. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): sanitize trace maxDepth to reject 0/NaN/negative `Math.min(params.maxDepth ?? 10, 30)` had no lower bound and `??` does not recover 0 or NaN, so `--depth 0|-5|abc` made the BFS loop run zero iterations and return a false `no_path`. Clamp at the real boundary with a `Number.isInteger && > 0` guard (the MCP inputSchema minimum is advisory only), and reject a non-numeric `--depth` in the CLI up front rather than forwarding NaN. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): check trace target before applying test-file filter The `isTestFilePath` filter ran before the target-equality check, but resolveSymbolCandidates does not exclude test-file symbols. A target (or a required hop) that lives in a test file was therefore skipped under the default includeTests=false and produced a false no_path with a misleading dynamic-dispatch suggestion. Match the explicitly-requested target first; non-target test-file nodes are still filtered. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * perf(mcp): bound trace BFS with per-level LIMIT and visited cap The per-level query had no LIMIT and the visited set was uncapped, so a high-fanout hub could materialize an unbounded frontier. Cap per-level rows (interpolated LIMIT — Kuzu does not bind LIMIT) and the total visited set; either cap sets a `truncated` flag so a resulting no_path reports that the search was cut short rather than implying the graph was exhausted. Note: the sibling impact BFS shares the same unbounded pattern; applying the cap there is deferred (out of scope for this PR). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(mcp): clarify trace traverses call + class-member edges trace was advertised as a "shortest call path" but also traverses HAS_METHOD (class→member) containment edges so a class-rooted trace can descend into its methods. Keep that capability (consistent with impact/ context) and make the docs honest: rename EDGE_TYPES→TRAVERSAL_EDGE_TYPES, state the call + class-member traversal in the MCP/CLI/i18n/ARCHITECTURE descriptions, and note each hop's edge type is reported in edges[]. No behavior change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): set status:'error' on trace failure responses Every trace return path sets a `status` discriminator except the caught-error path, so a consumer switching on `result.status` saw undefined on failure. Add status:'error' to both the backend trace() catch and the CLI traceCommand catch. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): return a friendly error for non-string trace from/to A non-string from/to reaching resolveSymbolCandidates surfaced a low-level "x.includes is not a function" via name.includes. Guard the four name/uid params at the top of _traceImpl and return a structured status:'error' with a clear message instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(mcp): single row-decode + drop dead field in trace BFS Decode each BFS row once into named locals instead of repeating `(row.x ?? row[N])` across the two parent.set calls and the furthest-tracking. Drop the `type` field from the parent map value (it was written but never read), and rename the internal `deepestInfo` to `lastReached` for accuracy (the output field `furthest` is unchanged). Pure refactor — no behavior change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(cli): dedicated trace includeTests i18n key + guard coverage `trace|--include-tests` reused the impact help key, so rewording the impact option would silently change trace's help text. Add a dedicated help.option.trace.includeTests key in en + zh-CN and repoint it. Add CLI coverage for the (already symmetric) --from-uid/--to-uid flag-value guard and for --include-tests forwarding. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(mcp): faithful BFS mock + expand trace coverage Fix makeResolveMock: concatenate neighbors across ALL frontier ids (it returned only the first node's, so a multi-node frontier was unmodelled) and key the UID branch on params.uid (the old query-text match never fired). Add coverage: shortest path through the second frontier node (proves the mock fix), confidence floor fallback, HAS_METHOD traversal with a mixed edge-type chain, no_path furthest:null, and from_file disambiguation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style(trace): apply root prettier formatting to trace files The root `quality / format` gate (prettier --check, printWidth 100) runs on the full repo and flagged the trace sources/tests (the local config masks it). Reformat to root style — no behavior change; trace + tools suites and tsc stay green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(skills): document the trace tool for AI agents Add `trace` to the GitNexus skill docs so agents reach for it instead of hand-chaining context/impact hops. The guide gains a Tools Reference row and a "shortest path between two symbols" subsection (params, result shape, status/furthest/truncated semantics); the debugging skill gains a "how does A reach B?" pattern row and a trace tool example. Mirrored to the .claude and claude-plugin copies (byte-identical) and the cursor copy (compact style). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(mcp): drop unused trace test fixtures (CodeQL js/unused-local-variable) CodeQL flagged two unused locals in the trace BFS tests: the top-level SYMBOL_C and a SYMBOL_D inside the maxDepth test (both defined, never referenced). Remove them. No behavior change — 58 trace/tools tests stay green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Gergő Magyar <gergomagyar@icloud.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-14 10:43:01 +01:00
Gergő Magyar	7c3d4e6862	feat(pdg): control dependence — post-dominators + CDG (Ferrante) [M5 #2085] (#2188) ... * feat(pdg): add CDG + POST_DOMINATE edge types (M5 #2085) * feat(pdg): post-dominator tree on reverse CFG (M5 #2085) * feat(pdg): Ferrante control-dependence over the post-dom tree (M5 #2085) * feat(pdg): emitFileCdg + optional POST_DOMINATE debug edges (M5 #2085) * feat(pdg): wire CDG emission in-phase + pdgModeMismatch CDG-cap stamp (M5 #2085) * test(pdg): CDG snapshot + end-to-end pipeline answerability (M5 #2085) * fix(review): apply autofix feedback (M5 #2085) * fix(pdg): label CDG edges by controller arm sense, not edge kind (#2188 F1/F2/F4) Tri-review (with Codex as the independent engine) found the CDG 'T'/'F' label was wrong for the commonest control flow: the M1 TS visitor wires a condition's fall-through FALSE arm as `seq`/`loop-back`, but `branchSense` mapped both to 'T', so guard clauses, if-no-else, and loop `break` got 'T' instead of 'F' (F1, P1). The structural CDG edges were correct; only the label — the AC3 "under what condition does X run?" answer — was wrong. - F1: replace edge-kind `branchSense` with controller-arm-sense `labelFor`. An ambiguous fall-through edge (seq/loop-back) takes the COMPLEMENT of its source block's explicit cond-true/cond-false sibling arm. This correctly handles do/while (loop-back = TRUE arm) and inner-if-in-loop (loop-back = FALSE arm) — the ambiguity a kind→label table cannot resolve. Adds real-parser regression tests (the hand-built tests used a fictional cond-false edge and missed it). - F2: correct the false "sound over-approximation that never drops a real dependence" claim in post-dominators.ts — exit-unreachable regions both drop and invent control dependences (latent for the current TS visitor, which keeps EXIT reverse-reachable). Reframe the exit-less-loop test to characterize, not bless, the degenerate behavior. - F4: make the AC2 property-test reference compute post-dominance INDEPENDENTLY (node-removal reachability, no shared code with post-dominators.ts), so a post-dom direction bug can no longer pass both the impl and the reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(ci): root-prettier format + run-analyze pdg stamp gains maxCdgEdgesPerFunction (#2085) Two deterministic CI failures from the M5 CDG work: - quality/format: basicblock-roundtrip.test.ts failed CI's root `prettier --check .` (the pre-commit hook uses the gitnexus-local prettier config, which differs); reformatted with the root config. - tests/ubuntu/coverage: run-analyze.test.ts pinned the resolved RepoMeta.pdg shape (DEFAULTS) and the all-zero cap override without the new maxCdgEdgesPerFunction key (default 5000); added it so resolvePdgConfig toEqual and pdgModeMismatch(DEFAULTS) pass. (The stale-test sweep missed this file in PR #2188 — same trap M2 hit.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(mcp): add pdg_query tool definition (controls/flows modes) [M6 #2086] * feat(mcp): pdg_query backend — controls (CDG) + flows (REACHING_DEF) + e2e test [M6 #2086] * feat(mcp): document PDG edges + pdg_query (schema, cypher, skill, --pdg-gated ai-context) [M6 #2086] * fix(mcp): correct pdg_query symbol-anchor lower bound + harden inputs [PR #2188 review] Tri-review (Codex + adversarial + correctness lanes) of the M6 pdg_query surface found the symbol-anchor window over-includes a neighbor function's block. The upper bound was widened to the 1-based BasicBlock basis (symEnd+1) but the lower bound was left 0-based, so a block on the line directly above the target function leaked into the result. Shift both bounds +1 ([symStart+1, symEnd+1]) so the window is the function's true block span. Also from the same review: - pdg_query no longer throws on a no-arguments MCP call: the dispatch passes raw `params`, so default it to {} → a clean mode-validation error instead of a TypeError. (`explain` shares this latent pattern — pre-existing follow-up.) - tools.ts: the controls-mode description no longer hard-codes the 'F' branch sense for guards — `if (!ok) return;` rides the predicate's 'T' arm; the guard:true flag is label-agnostic (regex on the dependent block text). Tests: a hand-seeded adjacency regression (verified failing without the lower-bound +1) + a no-arguments validation test. Skill doc updated to document the two-sided [symStart+1, symEnd+1] window. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): drop always-true anchor conditional in pdg_query [CodeQL #2188] CodeQL alert 756 flagged `...(anchor ? { anchor } : {})` in _pdgQueryImpl as a useless conditional: `anchor` is unconditionally assigned in both the file-path and symbol branches before the return (the not-found/ambiguous/no-layer paths return earlier), so it is always truthy. Drop `| undefined` from the declaration (TypeScript definite-assignment holds across both branches) and emit `anchor` directly. No runtime change — the `anchor` field was already present on every result. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(cli): add hasPdg to the noStats bridge expectation [#2188] The M6 work threaded `hasPdg: options.pdg === true` into the AIContextOptions passed to generateAIContextFiles on the --skills regeneration path, but this test's strict .toEqual expectation predated it (4 keys vs 3 → CI failure). Add `hasPdg: false` (the value on this non---pdg path). The assertion stays strict; the #1477 noStats bridging it guards is unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(cli): collapse generateGitNexusContent params to an options bag [#2188] The function had grown to 9 positional params; reaching `hasPdg` meant passing six `undefined`s (the M6 review's maintainability flag). Collapse params 3-9 (generatedSkills, groupNames, noStats, skipSkills, runnerPath, defaultBranch, hasPdg) into a `GitNexusContentOptions` object with the defaults moved to destructuring. The body is unchanged (same local names); the single production caller and the test calls become self-documenting named fields. Pure refactor — generated AGENTS.md/CLAUDE.md content is byte-identical. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cfg): skip CDG for exit-unreachable CFGs (unsound post-dominance) [#2188] M5 review P2: computePostDominators roots only at cfg.exitIndex and nothing enforced that EXIT is reachable from every block. For an entry-reachable region that cannot reach EXIT (a non-terminating loop, or a multi-terminal CFG a future visitor might emit) the EXIT-rooted reverse walk degenerates — it both drops real control dependences and invents spurious ones. Add a pure precondition predicate `isExitReachableFromAllBlocks` (co-located with the algorithm it guards) and gate it in emitFileCdg: a CFG that violates it is skipped for CDG (counted as skippedUnsoundFunctions + one onWarn), while its CFG and REACHING_DEF projections — which do not depend on post-dominance — are kept. A CDG-specific gate, not a widening of isEmitSafeCfg, so the blast radius is exactly the unsound CDG. The current TS visitor always satisfies the precondition (every loop gets a structural header→loopExit edge), so CDG output for real fixtures is unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(cfg): bound computeControlDependence materialization (heap parity) [#2188] M5 review P2: unlike computeReachingDefs (maxFacts) and the emit-side edge cap, computeControlDependence materialized the full deduped seen/out before emitFileCdg's per-function cap could trim it — O(edges × post-dom depth) heap for a deeply nested function. Add a `maxEdges` ceiling (default 0 = unbounded) returning {edges, truncated}, mirroring computeReachingDefs's {facts, truncated}. The ceiling is checked before pushing a new unique edge, so `truncated` means a genuine overflow (not merely "reached cap"). emitFileCdg passes a FIXED materialization ceiling (8× the default edge cap) — deliberately NOT derived from the runtime edge cap, because CDG's materialization IS the deduped-edge quantity the cap reports on (deriving it would pre-truncate that set and lose the exact dropped count). A ceiling hit is surfaced via onWarn + the truncated flag — never silent. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(mcp): share resolveBlockAnchor; fix explain's anchor off-by-one [#2188] M6 review P2 (duplication) + the flagged pre-existing _explainImpl correctness follow-up. _pdgQueryImpl and _explainImpl each carried a near-identical symbol↔block anchor resolver that had DRIFTED: pdg_query used the corrected [symStart+1, symEnd+1] window (BasicBlock startLine is 1-based, the symbol span 0-based) while _explainImpl still used [symStart, symEnd] — dropping a taint source on the function's final line AND leaking a neighbor's block on the line directly above. Extract one `resolveBlockAnchor` helper, used by both, that applies the correct window and a single (bare) clause convention (callers compose their own WHERE). This removes ~50 duplicated lines and fixes explain's anchor in one place. A hand-seeded characterization test (taint-explain Block 4) pins both bounds — verified to FAIL on the pre-fix window (it returned the line-10 neighbor instead of the line-15 final-line source). Existing taint-explain + pdg-query suites are unchanged (their fixtures have interior sources/sinks). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): pdg_query reports "status unknown" when the layer can't be confirmed [#2188] M6 review P3 (Codex): when meta is UNREADABLE and the bounded global existence probe returns zero rows of the edge type, _pdgQueryImpl asserted "no PDG layer" — but a genuinely edge-free layer (all-linear functions) is indistinguishable from a missing one via that probe. Soften only that fallback path to an inconclusive "PDG layer status unknown — was this repo indexed with --pdg?" note. The meta-stamped path (stamp present, cap absent ⇒ layer truly missing) keeps the definitive "no PDG layer" wording. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(mcp): cover pdg_query ambiguous / pagination / Windows-path gaps [#2188] M6 review test-gap follow-ups, all hand-seeded with controlled data: - ambiguous symbol name → status:'ambiguous' + ranked candidates shape (uid/name/filePath/score), never a silent guess; - total/truncated page boundary in both directions (limit below the match count sets truncated with the full total; limit above it omits truncated); - a Windows-style filePath containing ':' resolves and fnLineOf decodes the function-line segment correctly (split-from-right past the drive letter). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(skills): ship gitnexus-pdg-query skill mirrors + add pdg_query to the guide [#2086] M6 bundled pdg_query into this PR, but the skill shipped only in the canonical gitnexus/skills/ root. Mirror it (byte-identical) to the two hand-maintained roots the sibling taint skill uses — .claude/skills/gitnexus/ and the plugin — so Claude Code + plugin users get it too. Also extend the gitnexus-guide tool reference (all 3 copies, now byte-identical): add a `pdg_query` row + a "Control & data dependence" section mirroring the taint/`explain` section, and reconcile the pre-existing drift where only the .claude copy carried the `check` tool row (a real registered tool) — all three now list it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(architecture): refresh CFG/PDG section for the full M1–M6 stack [#2086] The PR body had deferred the "ARCHITECTURE docs refresh" to #2086; now that M6 ships here, do it: - MCP tools table gains `explain` and `pdg_query` (were absent). - "Optional CFG/PDG emission" was M1-only; rewrite to cover the whole opt-in stack — M1 CFG, M2 REACHING_DEF, M3/M4 taint, M5 CDG (Ferrante over CHK post-dominators, with the exit-unreachable skip), M6 read surface (pdg_query + explain, anchored + LIMIT-bounded, shared resolveBlockAnchor) — and note the no-Function→BasicBlock-edge join. - LadybugDB schema notes the `--pdg` additions: the `BasicBlock` node table and the CFG/REACHING_DEF/CDG/TAINTED/SANITIZES/TAINT_PATH relation types, kept out of the default VALID_RELATION_TYPES / web schema. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-13 18:49:03 +01:00
Gergő Magyar	9ff7337f1e	fix(mcp): rename query/cypher params so Claude Code can call them (#2186) ... * fix(mcp): advertise search_query/statement params for query/cypher tools (#2175) Claude Code drops a tool-call argument named exactly 'query', making the query and cypher tools unusable from it. Rename the advertised required parameters to search_query and statement so the client transmits them. Handler-side backward-compat for the legacy 'query' key follows in the next commit. * fix(mcp): accept search_query/statement with legacy query fallback (#2175) Resolve the new advertised param names in the backend while still accepting the legacy 'query' key, so curl/HTTP, other MCP clients, the CLI, the group path, and the internal executeCypher() all keep working. Alias is normalized once at the callTool chokepoint (covers group-forward + search alias); query() and cypher() dual-read defensively. New name wins when both are supplied. Updates the required-error message and adds dual-accept unit + integration coverage. * fix(cli): pass canonical search_query/statement params to query/cypher tools (#2175) Stop the CLI from depending on the deprecated 'query' alias. No user-facing change — the positional args are unchanged and the backend accepts both keys. * fix(mcp): generators advertise search_query in query() examples (#2175) Update the three doc/example generators (ai-context AGENTS/CLAUDE block, skill-gen community skills, resources repo hint) so future analyze runs emit query({search_query: ...}) — the param name Claude Code actually transmits. Tests assert the new form is present and the legacy query({query: form is absent (the #2059 generator-test pattern). * docs(mcp): advertise search_query/statement in skill & guidance examples (#2175) Sync the committed agent-facing docs to the renamed params so a Claude Code agent following them emits the transmittable key: AGENTS.md/CLAUDE.md gitnexus block, the canonical gitnexus/skills/* source and its installed/plugin/cursor mirrors, and the README examples. Scoped rewrite of the two call prefixes only (query({query: -> search_query, cypher({query: -> statement). * style(mcp): prettier line-wrap for #2175 alias-resolution edits * fix(review): uniform search_query precedence + cypher empty guard (#2175) Code-review findings (correctness/adversarial/api-contract/maintainability consensus): - Group-mode query inverted the 'new name wins' rule: the callTool chokepoint backfilled params.query only when empty and the @group-forward read params.query directly, so a both-keys (or whitespace-legacy) group call let the legacy value win — unlike the local path. Replace the hidden param mutation with a self-contained 'search_query ?? query' resolve at the group-forward; precedence is now uniformly new-wins at every consumer site. - cypher() now returns the same friendly required-param error as query() when neither statement nor query is supplied, instead of a raw DB prepare error. - Document the legacy alias as permanent (third-party clients may send query=). Adds group-forward alias tests (both-keys + legacy-only), empty/whitespace search_query, the search-alias path, and the cypher empty-statement guard. * fix(review): non-string alias safety + drop stale chokepoint comment (#2175) Tri-review findings (correctness/adversarial/security + maintainability): - Non-string statement/search_query/query (the MCP envelope is not schema-validated) hit .trim() and threw TypeError to the server boundary instead of a friendly required-param error. Introduce resolveAliasString() (new name wins; non-string -> undefined) used by query(), cypher(), and the group-forward, so all three return the structured error. Empirically verified (123 ?? '' -> 123, (123).trim() throws) — this overrides a critic refutation that mis-read ?? as a string coercion. - Remove the stale query() comment claiming alias resolution happens at a callTool chokepoint; that mutation was removed earlier in this PR — each site resolves the alias itself. - Document GroupToolPort.query's intentionally-narrower required type vs the wider LocalBackend impl. Adds non-string and empty-new-key precedence tests. * fix(mcp): alias falls back to legacy value when new key is blank (#2175) PR #2186 review finding: resolveAliasString used `canonical ?? legacy` (nullish), so an explicitly empty/whitespace new-name value (e.g. {search_query:'', query:'real'}) won and was rejected — discarding a valid legacy value, contradicting the 'new name wins when both supplied' intent. Resolve to the first NON-BLANK string instead (new preferred when it carries a real value, else legacy). Covers query(), cypher(), and the group-forward (all route through the helper); non-string still resolves to a friendly error. Flips the presence-based test and adds whitespace/cypher/group fallback cases. * fix(mcp): drop legacy "query" mention from query/cypher schema descriptions (#2175) PR #2186 review finding: the search_query/statement inputSchema descriptions named the legacy "query" key — the exact arg Claude Code drops — and description text is read by an LLM choosing arguments, weakly nudging it to send "query". Trim the descriptions to their clean form and move the legacy-alias note to a code comment next to the schema (preserved for maintainers / non-CC clients). properties/required unchanged (no `query`).	2026-06-13 10:24:16 +01:00
Gergő Magyar	14397dd4aa	feat(taint): intra-procedural taint analysis (#2083) (#2164) ... * feat(taint): harvest occurrence-tagged call/member sites on StatementFacts (#2083 U1) Worker-side site harvest in TsHarvester: call/new/member-read records with dotted callee paths, receiver slots, per-argument occurrence tagging with nested-site links, per-declarator resultDefs, spread/template/require-literal markers. hasTaintSafeSites validation seam. The pdg parse-cache chunk-key namespace is versioned (pdg:1 -> pdg:2) instead of a global SCHEMA_BUMP so flag-off users keep warm caches; bench fingerprints re-baselined for the three call-bearing scenarios (straight-line/dense-bindings byte-unchanged). * feat(taint): built-in TS/JS source/sink/sanitizer model + site matcher (#2083 U2) Typed spec (kind taxonomy; sanitizers carry neutralizes-kinds), the canonical Express/Node model, and matchFunctionSites: ESM alias/namespace + require- literal callee resolution, bare-name fallback restricted to true globals, sanitizers module-or-global only (never user-shadowable by name), spread/ template arg-position rules, deterministic taintModelVersion. * feat(taint): pure intra-procedural taint propagation engine (#2083 U3) Two-rule model (statement-local + du-fact worklist) with per-taint neutralized-kind exclusion sets: sanitizers exclude only the sink kinds they neutralize (escape(req.body) suppresses res.send but still fires db.query; exec(path.basename(t)) fires), intersection-over-paths so a bypass occurrence keeps the taint live, kill locality on resultDefs, propagate-through args+receiver with viaCall hops, one path per finding, deterministic caps, coverage-gap statuses. Test-first: 38 scenarios on real harvested CFGs. * feat(taint): thread taint caps + model version through pdg config/meta (#2083 U5) resolvePdgConfig gains maxTaintFindingsPerFunction (200), maxTaintHops (32), and the taintModelVersion digest; RepoMeta.pdg + RunScopeResolutionInput surfaces added. The key-union comparator trips full writeback on M2->M3 upgrade and on model-version change without --force (mode-flip tested). No CLI flags or rc keys (programmatic parity with the other caps). * feat(taint): in-phase taint emit with sparse TAINTED/SANITIZES edges (#2083 U4) run.ts pdg window: match-first fast path (solver only when a function has both a matched source and sink) -> computeReachingDefs with the shared RD fact derivation -> computeTaintFlows -> per-finding TAINTED (versioned hop-encoded reason via the shared path codec, statement-level occurrence identity) + per-kill SANITIZES, dedup-before-budget, truncate-and-warn. All emit counters surfaced (aggregate warn for gaps/drops, debug for volume); PROF gains taint=. Flag-off golden untouched. * feat(mcp): explain tool for persisted taint findings (#2083 U6) Anchorless calls enumerate the sparse TAINTED table (bounded, deterministic, limit-clamped); anchored calls (file or symbol via resolveSymbolCandidates) return full decoded hop detail. sinkKind rides a version-1 codec header (1;<kind>|hops — no other persisted channel exists; U4/U6 ship together). RepoMeta.pdg probe yields a no-taint-layer note instead of an error. TAINTED/SANITIZES pinned OUT of VALID_RELATION_TYPES (KTD9a negative- membership tests); generators + canonical skill docs + mirrors updated. * test(taint): acceptance fixture battery, snapshots, and bench gates (#2083 U7) pdg-repo taint-cases fixtures complete the six plan shapes; committed findings/kills snapshot via a shared pure-path harness that also feeds the AE2 exact-equality assertion (stored TAINTED == pure-path findings, the no-explosion gate). New taint-dense bench scenario with four --check gates: per-function findings pinned AT the cap, absolute reason-byte + site-bytes disk ceilings (the load-bearing R10 gate), zero-match pass < 0.5x match- dense, N-linearity. Pre-existing scenario baselines untouched. * refactor(taint): share one pointKey helper across propagate + emit (#2083 review) Extract pointKey(ProgramPoint) to cfg/reaching-defs.ts (colon-separated, matching the codebase block:stmt id convention) and import it in both propagate.ts and emit.ts, replacing the two divergent locals (':' vs '.'). Edge-id material now uses the colon form; ids are in-memory only and no test asserts the pointKey segment shape. * fix(taint): discriminate taint state by source occurrence (#2083 review) Two distinct sources flowing into one variable at one def point no longer collapse to a single TAINTED edge: the taint-state key gains a root source-occurrence discriminator ({point, siteIndex} — the same fields recordFinding's identity uses, excluding kind). Def->use fact lookup keys on the source-independent (binding, def-point) portion. Same-source multi-path flows still share one state so their exclusion sets intersect (the raw arm soundly wins); termination holds (finite keys, monotone shrink, no cross-source ping-pong). Restores the KTD6 identity contract. * fix(mcp): route dotted symbol names in explain to symbol resolution (#2083 review) The fileish classifier matched any dotted name (UserController.create) as a file via its extension-like suffix, so symbol resolution never ran and the tool returned a silent empty file-anchored result. Tighten the classifier to require a path separator or a real source extension (derived from the resolver's EXTENSIONS list, multi-language), so dotted/bare names route to resolveSymbolCandidates (found / ambiguous / not-found). * fix(mcp): gate explain no-taint-layer note on taintModelVersion (#2083 review) An M1/M2-era --pdg index has meta.pdg defined (BasicBlock/REACHING_DEF recorded) but no taintModelVersion and zero TAINTED rows. The probe keyed on generic meta.pdg presence, so explain returned the generic empty note instead of the actionable 'no taint layer — run analyze' hint. Gate on meta.pdg?.taintModelVersion (the field M3 stamps) so an M2-era index gets the layer hint; a taint-stamped index with no findings still gets the generic note. * fix(taint): sequence-expression value flows only the final operand (#2083 review) A comma expression in value position (exec((log(x), 'safe'))) default- descended, fanning every operand's occurrences into the enclosing sink argument — over-tainting exec's arg 0 with x. Add an explicit walkValue case that records earlier operands' uses with occurrence fan-out suppressed (new FactAccumulator.suppressOccurrences) and routes only the last operand through the value path. Sites-layer only; defs/uses/mayDefs byte-identical (cfg + reaching-defs snapshots unchanged). * perf(taint): FIFO head-cursor worklist + dedup before chainHops (#2083 review) Replace queue.shift() (O(N) dequeue) with a strict-FIFO head cursor plus order-preserving prefix reclamation; FIFO is load-bearing because chainHops reads the live taints map whose parent/source/viaCall are rewritten order-sensitively on monotone shrink, so hop determinism is dequeue-order contingent. Extract findingKey() and dedup-check before chainHops in the justify branch — already-recorded identities discard their hop chain (first write wins), so the ancestry walk was pure waste. The else kill branch is untouched. Findings + hops byte-identical (snapshot unchanged). * perf(taint): O(1) member-read dedup via composite-key set (#2083 review) addMemberRead rescanned the whole per-statement sites array per call to dedup by (object, property, parent) — O(n^2) on member-read-dense statements. Track a composite-key Set alongside sites for O(1) dedup. (The require-literal join is already O(sites) with a no-op body on non-require sites, so no early-exit is needed there.) Behavior identical: harvest + model-match + taint snapshots unchanged. * refactor(taint): drop test-only export; source taint caps via emit.ts (#2083 review) Remove the sanitizerNeutralizes export (its only consumers were two test assertions — inlined to entry.neutralizes membership). Re-export the DEFAULT_PDG_MAX_TAINT_* caps from emit.ts and point run.ts at emit.ts, so the pipeline's taint dependency surface is the single orchestration module rather than reaching into propagate.ts. * test(taint): extract the shared TS CFG/taint test harness (#2083 review) The parse/collectFunctions/cfgOf/cfgsOf/importsFor harness was copied byte-for-byte across four suites (harvest, model-match, propagate, taint-emit). Promote it to test/helpers/ts-cfg-harness.ts and import it. site-safety/reaching-defs carry a structurally different inlined builder and are left as-is. Pure extraction, no assertion changes. * test(mcp): harden explain limit-rejection battery (#2083 review) Add NaN, Infinity, -Infinity, and a numeric string to the out-of-bounds limit cases — a regression fence over the interpolated LIMIT, confirming the Number.isInteger guard rejects every non-integer/non-finite/string input before it reaches the query.	2026-06-12 07:35:09 +01:00
azizur100389	bdb824cfe4	feat(cli): add circular import cycle check (#2166)	2026-06-12 04:53:17 +01:00
Gergő Magyar	7eaeb0a0c4	feat: multi-branch indexing and branch-scoped querying (#2106) (#2137) ... * feat(git): add getCurrentBranch + resolveRefToCommit helpers (#2106) * feat(storage): branch-scoped getStoragePaths + branchSlug + resolveBranchPlacement (#2106) * feat(analyze): branch-aware indexing — per-branch slot, no overwrite (#2106) * feat(registry): nest non-primary branches under one path entry (#2106) * feat(mcp): optional branch scope on query tools + list_repos branches (#2106) * feat(cli): --branch on analyze + query/context/impact/cypher/detect-changes (#2106) * feat(cli): branch-aware list/status + per-branch staleness meta (#2106) * fix(review): apply autofix feedback - guard analyze against --branch != checked-out branch (prevents writing one branch's working tree into another branch's index slot) - fix branch-handle pool reinit thrash (track observed indexedAt by lbugPath, since applyBranchScope returns fresh handles) - remove dead resolveRefToCommit helper (staleness uses HEAD vs branch meta) - RepoListing.branches -> Omit<BranchSummary,'stats'> for type cohesion - add tests: branchSlug traversal containment, --branch mismatch reject, callTool branch threading, legacy-entry branch routing, status detached/stale * fix(review): address tri-review findings (#2106) - P1 data-loss: a detached-HEAD re-analyze (CI's actions/checkout default) no longer strips the primary's meta.branch stamp; preserve it so a later branch analyze cannot claim & overwrite the flat/primary index. +cascade integration test - P2: capture validateBranchName's trimmed return for --branch so a whitespace-padded value no longer false-rejects on-branch or ghosts an index - F1: on a lost/rebuilt registry, a branch run reconstructs the primary top-level entry from the flat meta, not the feature branch's meta * fix(storage): only trust a non-empty-string flatMeta.branch (#2106 R5) * fix(analyze): warn when the default branch is not the primary index (#2106 R8) * fix(mcp): resolve --branch <primary> on a legacy unstamped flat index (#2106 R4) * feat(cli): gitnexus clean --branch to remove a single branch index (#2106 R7) * fix(mcp): evict orphaned branch pools on unregister/clean (#2106 R3) * fix(analyze): union per-branch cache keys so a branch switch keeps shards (#2106 R6) * fix(analyze): normalize the auto-detected branch label via sanitizeDetectedBranch (#2106 R1) * fix(cli): skip AGENTS.md base_ref refresh for a non-primary branch fast path (#2106 R2) * fix(storage): atomic writeRegistry + re-read-before-write to narrow the registry race (#2106 R9) * refactor(storage): extract branch primitives to branch-index.ts (#2106 R10)	2026-06-10 10:24:40 +01:00
Gergő Magyar	4682a477d8	feat(mcp): paginate list_repos to avoid client token truncation (#2119) (#2120) ... * feat(mcp): paginate list_repos to avoid client token truncation (#2119) list_repos returned every indexed repository in one unpaginated array, which large/LLM MCP clients truncate by token limit — so agents with hundreds of indexed repos could not enumerate them all (the data transmits fully; the consuming client drops it). Add bounded limit/offset pagination to the list_repos tool: - result changes from a bare array to { repositories, pagination: { total, limit, offset, returned, hasMore, nextOffset } }; default page 50, max 200 (shared constants) - reject malformed limit/offset; clamp limit above the max - deterministic order (lower-cased name, then path) over one registry snapshot per call, so paging never skips or duplicates an entry - covers both stdio and remote /api/mcp (shared createMCPServer/callTool) The internal listRepos() method (5 callers), GET /api/repos, and the `gitnexus list` CLI are unchanged. The array->object tool-result shape is a deliberate contract change, documented in CHANGELOG. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(mcp): reject list_repos limit above the max instead of clamping (#2119) parseListReposPagination silently clamped limit>max to the maximum while throwing on every other out-of-bounds value (limit<1, offset<0, non-integer, NaN). A client that advanced offset by its requested limit (rather than pagination.nextOffset) then silently skipped repositories and saw hasMore:false — defeating the "never skips" guarantee. Reject an over-max limit too, so validation is symmetric and a caller never gets a smaller page than it asked for without a clear error. Updates the schema/description, the helper + ListReposPagination JSDoc, the guide note, and the two clamp tests. Resolves the cross-engine-corroborated P2 (Codex + adversarial lane) and the maintainability lane's clamp-vs-throw inconsistency from the PR #2120 review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(mcp): name the list_repos return type and mark the parser @internal Extract the inline listRepos() element shape into an exported RepoListing interface and use it for both listRepos() and listReposPage().repositories, replacing the opaque Awaited<ReturnType<LocalBackend['listRepos']>> expression the maintainability review flagged. Tag parseListReposPagination @internal (it is exported only for unit testing). Pure type/JSDoc change; no behavior. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(eval-server): type formatListReposResult to the paginated shape Narrow formatListReposResult's parameter from `any` to { repositories: RepoListing[]; pagination?: ListReposPagination } and drop the dead bare-array branch — after #2119 callTool('list_repos') always returns the paginated object, so the Array.isArray shim was unreachable. Add a list_repos continuation hint to the eval-server's getNextStepHint (parity with the MCP server), and cover the previously-untested non-empty + hasMore:false formatter branch. Migrates the two bare-array formatter tests to the object shape. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(mcp): harden list_repos pagination coverage - Exercise the #2054 sibling-clone guarantee through the real callTool tool path (in the #2054 describe, which has temp-dir cleanup), proving siblings and remoteUrl survive listReposPage's sort+slice — not only listRepos(). - Assert total + limit on the middle-page test (a total miscalculation at a non-zero offset would otherwise slip past it). - Cover the benign boundaries: negative-zero offset (accepted as page 0) and a MAX_SAFE_INTEGER offset (empty page). - Replace the integration test's '\n\n---' split with a string-aware brace scan, so a repo path containing braces can never truncate the JSON parse. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(skills): sync the list_repos pagination example to the guide mirrors The .claude and gitnexus-claude-plugin guide mirrors only carried the one-line table note; add the full "Paginating list_repos" section (shape + multi-page traversal example + notes) so all three guide copies are byte-consistent with the canonical gitnexus/skills/gitnexus-guide.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: drop list_repos CHANGELOG entries from this PR Restore gitnexus/CHANGELOG.md to match main so this PR contributes no changelog change; the changelog is curated separately from feature PRs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-09 19:59:54 +01:00
Copilot	7d500390b9	fix: Use Ladybug native read-only enforcement and prepared statement execution for Cypher query paths (#1655)	2026-05-18 06:54:24 +01:00
Temirkhan	1fe3bf9399	feat(mcp): add tool safety annotations (#1127) ... * feat(mcp): add tool safety annotations * test(mcp): address PR #1127 review follow-ups - Replace private `_requestHandlers` SDK access in server.test.ts with `Client` + `InMemoryTransport.createLinkedPair()` for the tools/list annotation propagation test. The new path uses supported public APIs and surfaces SDK changes loudly instead of silently degrading. - Extract `OPEN_WORLD_READ_ONLY_TOOLS` set in tools.test.ts so future read-only open-world tools can be added without rewriting the invariant; preserves the current "only `query` is open-world" guard. - Add inline rationale on `group_sync` annotations explaining the conservative `idempotentHint: false` (writes contracts.json on every call even when output is deterministic). No runtime behavior change. Annotations themselves and tools/list shape are unchanged. --------- Co-authored-by: Gergo Magyar <gergomagyar@icloud.com>	2026-05-03 09:06:41 +01:00
ivkond	00966630c4	feat: cross-repo impact analysis (#794) — @repo MCP routing + group resources (#984)	2026-04-20 11:55:07 +01:00
ivkond	4fed097abb	feat(group): add sync pipeline, CLI, MCP tools, and monorepo fixture ... Wire extractors into the sync pipeline with service boundary detection. GroupService provides high-level API for all group operations. - Sync pipeline: orchestrates extraction (HTTP, gRPC, topics) with service boundary assignment and exact matching - GroupService: groupList, groupSync, groupContracts, groupQuery, groupStatus (groupImpact deferred to cross-repo follow-up PR) - CLI: group create/add/remove/list/sync/contracts/query/status - MCP tools: group_list, group_sync, group_contracts, group_query, group_status - Monorepo fixture: 3 services (auth/orders/gateway) connected via gRPC + Kafka + HTTP — all intra-repo cross-links discovered - Documentation: CLI commands and MCP tools added to both READMEs Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 00:40:31 +03:00
Gergő Magyar	acf6fbdd39	feat: configure eslint with unused import removal (#564) ... * feat: configure eslint with unused import removal Add ESLint v9 (flat config) for code quality: - eslint-plugin-unused-imports for auto-removing dead imports - @typescript-eslint for TypeScript-aware linting - eslint-plugin-react-hooks for React hooks rules - eslint-config-prettier to avoid formatting conflicts - lint-staged runs eslint --fix before prettier on .ts/.tsx - CI lint job added to ci-quality.yml * refactor: remove unused imports via eslint --fix Auto-fixed by eslint-plugin-unused-imports. No logic changes. * chore: add eslint fix commit to .git-blame-ignore-revs	2026-03-28 15:28:09 +00:00
Gergő Magyar	bf09eab95b	feat: configure prettier with pre-commit hook (#563) ... * feat: configure prettier with pre-commit hook integration Add prettier, lint-staged, and prettier-plugin-tailwindcss at the repo root with husky pre-commit hook integration. Moves husky from gitnexus/ to root package.json for reliable hook installation. - Root package.json with prepare/format/format:check scripts - .prettierrc with endOfLine:lf and tailwindStylesheet for TW v4 - .prettierignore excluding fixtures, vendor, generated, *.d.ts, *.md - .gitattributes enforcing LF line endings for Windows consistency - Pre-commit hook uses direct node_modules/.bin/ paths (no npx) * style: apply prettier formatting to entire codebase One-time bulk format. No logic changes. Use .git-blame-ignore-revs to skip this commit in git blame. * chore: add .git-blame-ignore-revs for prettier format commit * perf: pre-commit hook runs only tests related to staged files Use vitest --related to scope test execution to tests that import the changed files, instead of running the full suite on every commit. * perf: remove vitest from pre-commit hook, keep in CI only Pre-commit now runs lint-staged + tsc only. Tests run in CI (ci-tests.yml) where they belong — keeps commits fast. * ci: add prettier format check to quality workflow PRs will now fail if code isn't formatted with prettier.	2026-03-28 14:58:04 +00:00
marxo126	c437acf6bb	feat: deep flow detection — consumer access tracking, middleware chains, error shapes, api_impact tool (#482)	2026-03-23 22:13:48 +00:00
abhigyanpatwari	8a100a76d3	test: add test suite with vitest (unit + integration + fixtures) ... - 59 test files covering unit and integration tests - vitest config with coverage thresholds and fork pooling - Test fixtures (mini-repo + multi-language sample code) - Add vitest + coverage-v8 to devDependencies - Add test scripts (test, test:integration, test:all, test:watch, test:coverage) - Move typescript to devDependencies where it belongs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-01 20:07:02 +05:30