scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-09-07 08:26:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

docs(graph): state the CALLS contract on staticGated; say "provably unreachable at compile time"

Browse source 
Review on #3161 (magyargergo): the flag must not redefine what a CALLS
edge means. The field's doc now says so explicitly: CALLS still means
"there is a resolved call site from A to B", never "B is reachable from
A"; `staticGated` is additional, statically provable path-feasibility
metadata, an opt-in analysis layer that no core pass acts on. The edge is
emitted, persisted, traversed and counted exactly as before.

Wording: "unreachable in production" -> "provably unreachable from the
indexed source at compile time" on GraphRelationship, ReferenceSite and
Reference. The index has no production build configuration and should not
claim one.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015ciQ3MTjpQXkCoNntZR9zG
This commit is contained in:
Garrett Griffin-Morales 2026-09-03 11:16:17 -04:00
parent 3b96e3ca0d
commit dda4c65749
3 changed files with 29 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
gitnexus-shared/src/graph/types.ts
View file

@ -307,17 +307,31 @@ export interface GraphRelationship {
readonly note?: string;
}[];
/**
* When `true`, the edge originates inside a code branch known at
* index time to be unreachable in production — e.g. a Zig
* `if (CONST_FALSE)` block where the condition reduces to a
* comptime-known `false`. Consumers of impact / context queries
* can filter these edges out to suppress paper-tiger callers
* caused by feature-flag-gated dead code paths.
* When `true`, the call site this edge was resolved from sits in a
* branch that is provably unreachable from the indexed source at
* compile time — e.g. a Zig `if (CONST_FALSE)` body, or the `else` of
* `if (CONST_TRUE)`, where the condition folds to a comptime-known
* boolean.
*
* GRAPH CONTRACT (PR #3161 review): this does NOT change what a
* `CALLS` edge means. `CALLS` still means "there is a resolved call
* site from A to B"; it has never meant "B is reachable from A", and
* this flag does not make it mean that. `staticGated` is additional,
* statically provable path-feasibility METADATA on the edge: an opt-in
* analysis layer that a consumer may read (for example to rank or
* filter callers in an impact view) and that no core pass acts on.
* The edge is emitted, persisted, traversed and counted exactly as it
* was before the flag existed.
*
* Scope: only conditions that fold from constants in the source.
* Anything the index cannot know (build mode, target, environment) is
* never marked; the index has no production build configuration and
* does not claim to.
*
* Optional and additive: edges from languages that don't compute
* static gating leave this `undefined`, which existing readers
* treat identically to "live". Currently set only by the Zig
* call-extractor.
* static gating leave this `undefined`, which readers treat
* identically to `false` (live). Currently set only by the Zig
* scope-capture emitter.
*/
staticGated?: boolean;
}

5
gitnexus-shared/src/scope-resolution/reference-site.ts
View file

@ -209,8 +209,9 @@ export interface ReferenceSite {
*/
readonly embeddedAsPointer?: boolean;
/**
* The call sits inside a branch known at index time to be unreachable —
* a Zig `if (CONST_FALSE)` body, or the `else` of `if (CONST_TRUE)`,
* The call sits inside a branch that is provably unreachable from the
* indexed source at compile time — a Zig `if (CONST_FALSE)` body, or the
* `else` of `if (CONST_TRUE)`,
* where the condition folds to a comptime-known boolean. Set only when
* `kind === 'call'` and only by languages that compute static gating (Zig
* today); absent everywhere else, so every other site stays byte-identical.

5
gitnexus-shared/src/scope-resolution/types.ts
View file

@ -765,8 +765,9 @@ export interface Reference {
*/
readonly callForm?: CallForm;
/** Copied from `ReferenceSite.staticGated` for `kind === 'call'`: the site is
* in a branch proven dead at index time. The emit phase writes it to
* `GraphRelationship.staticGated`. Optional and additive. */
* in a branch provably unreachable from the indexed source at compile time.
* The emit phase writes it to `GraphRelationship.staticGated` as metadata;
* see the contract note there. Optional and additive. */
readonly staticGated?: boolean;
readonly confidence: number;
readonly evidence: readonly ResolutionEvidence[];