gitnexus 1.6.4-rc.100 → 1.6.4-rc.102

package/dist/_shared/index.d.ts

@@ -48,6 +48,8 @@ export { buildScopeTree, canParentScope, ScopeTreeInvariantError, } from './scop
 export type { ScopeTree } from './scope-resolution/scope-tree.js';
 export { buildPositionIndex } from './scope-resolution/position-index.js';
 export type { PositionIndex } from './scope-resolution/position-index.js';
+export { UNDERSTAND_QUICKLY_DISPATCH_URL, UNDERSTAND_QUICKLY_EVENT_TYPE, UNDERSTAND_QUICKLY_TOKEN_ENV, buildUqDispatchPayload, isValidOwnerRepo, parseOwnerRepoFromRemote, stripGitSuffix, } from './integrations/understand-quickly.js';
+export type { UqDispatchPayload } from './integrations/understand-quickly.js';
 export { diffResolutions } from './scope-resolution/shadow/diff.js';
 export type { ShadowAgreement, ShadowCallsite, ShadowDiff, } from './scope-resolution/shadow/diff.js';
 export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';

package/dist/_shared/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAGzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACjG,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChF,YAAY,EACV,OAAO,EACP,KAAK,EACL,SAAS,EACT,KAAK,EACL,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,KAAK,EACL,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,QAAQ,EACR,WAAW,GACZ,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG/E,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAG5F,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,YAAY,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACnG,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,YAAY,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AAKrF,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAC;AAGpF,YAAY,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAGnG,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AACvF,YAAY,EACV,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EAAE,QAAQ,EAAE,MAAM,0CAA0C,CAAC;AACpE,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,aAAa,GACd,MAAM,0CAA0C,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AACrF,YAAY,EAAE,aAAa,EAAE,MAAM,iDAAiD,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AACvF,YAAY,EACV,cAAc,EACd,mBAAmB,GACpB,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AACrF,YAAY,EACV,aAAa,EACb,kBAAkB,GACnB,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,8CAA8C,CAAC;AAC1E,YAAY,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,MAAM,mDAAmD,CAAC;AACpF,YAAY,EAAE,qBAAqB,EAAE,MAAM,mDAAmD,CAAC;AAC/F,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AACpG,YAAY,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AAC5E,OAAO,EACL,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,6CAA6C,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,6CAA6C,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAClG,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,GACb,MAAM,0CAA0C,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACrF,YAAY,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EACL,cAAc,EACd,cAAc,EACd,uBAAuB,GACxB,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAG1E,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,YAAY,EACV,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/_shared/index.js

@@ -33,6 +33,8 @@ export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS } from './scope-resolution/regis
 export { makeScopeId, clearScopeIdInternPool } from './scope-resolution/scope-id.js';
 export { buildScopeTree, canParentScope, ScopeTreeInvariantError, } from './scope-resolution/scope-tree.js';
 export { buildPositionIndex } from './scope-resolution/position-index.js';
+// Understand-Quickly registry integration (opt-in)
+export { UNDERSTAND_QUICKLY_DISPATCH_URL, UNDERSTAND_QUICKLY_EVENT_TYPE, UNDERSTAND_QUICKLY_TOKEN_ENV, buildUqDispatchPayload, isValidOwnerRepo, parseOwnerRepoFromRemote, stripGitSuffix, } from './integrations/understand-quickly.js';
 // Shadow-mode diff + aggregation (RFC §6.3; Ring 2 SHARED #918)
 export { diffResolutions } from './scope-resolution/shadow/diff.js';
 export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';

package/dist/_shared/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAiCjG,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAGvD,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAGrF,gEAAgE;AAChE,yEAAyE;AACzE,2DAA2D;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAOxE,oFAAoF;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAMvF,uEAAuE;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,0CAA0C,CAAC;AAUpE,sEAAsE;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAErF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAKvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAKrF,OAAO,EAAE,UAAU,EAAE,MAAM,8CAA8C,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,mDAAmD,CAAC;AAEpF,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAEpG,OAAO,EACL,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAQlG,2EAA2E;AAC3E,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAErF,OAAO,EACL,cAAc,EACd,cAAc,EACd,uBAAuB,GACxB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAG1E,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMpE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAiCjG,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAGvD,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAGrF,gEAAgE;AAChE,yEAAyE;AACzE,2DAA2D;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAOxE,oFAAoF;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAMvF,uEAAuE;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,0CAA0C,CAAC;AAUpE,sEAAsE;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAErF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAKvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iDAAiD,CAAC;AAKrF,OAAO,EAAE,UAAU,EAAE,MAAM,8CAA8C,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,MAAM,mDAAmD,CAAC;AAEpF,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAEpG,OAAO,EACL,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAQlG,2EAA2E;AAC3E,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAErF,OAAO,EACL,cAAc,EACd,cAAc,EACd,uBAAuB,GACxB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAG1E,mDAAmD;AACnD,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,gBAAgB,EAChB,wBAAwB,EACxB,cAAc,GACf,MAAM,sCAAsC,CAAC;AAG9C,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMpE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/_shared/integrations/understand-quickly.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Understand-Quickly registry integration helpers.
+ *
+ * Pure, runtime-agnostic logic for opting in to publishing a GitNexus
+ * index to the [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly)
+ * registry. Lives in `gitnexus-shared` so both the Node CLI and any
+ * future browser-side surface can construct identical dispatch payloads.
+ *
+ * Network I/O lives in the CLI command (`gitnexus/src/cli/publish.ts`)
+ * to keep this module free of Node-only imports — see the comment at
+ * the top of `gitnexus-shared/src/graph/types.ts`.
+ *
+ * The protocol contract (single dispatch event, no graph upload) is
+ * documented at:
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ */
+/**
+ * URL of the registry repo's repository_dispatch endpoint. Hardcoded
+ * because the registry is the canonical home for this integration —
+ * users who want a private registry can fork and patch.
+ */
+export declare const UNDERSTAND_QUICKLY_DISPATCH_URL = "https://api.github.com/repos/looptech-ai/understand-quickly/dispatches";
+/**
+ * Event type the registry's sync workflow listens for.
+ * See `looptech-ai/understand-quickly/.github/workflows/sync.yml`.
+ */
+export declare const UNDERSTAND_QUICKLY_EVENT_TYPE = "sync-entry";
+/** Environment variable that gates the dispatch. */
+export declare const UNDERSTAND_QUICKLY_TOKEN_ENV = "UNDERSTAND_QUICKLY_TOKEN";
+export interface UqDispatchPayload {
+    event_type: typeof UNDERSTAND_QUICKLY_EVENT_TYPE;
+    client_payload: {
+        /** `<owner>/<repo>` shape — must match the registered entry. */
+        id: string;
+    };
+}
+/**
+ * Build the JSON body for the `repository_dispatch` ping. Pure — no
+ * env reads, no network. Validates that `id` looks like `owner/repo`
+ * (one slash, no whitespace, both halves non-empty) so a misconfigured
+ * caller fails loudly before the round-trip.
+ */
+export declare function buildUqDispatchPayload(id: string): UqDispatchPayload;
+/**
+ * `owner/repo` validation. Conservative on purpose: GitHub's actual
+ * naming rules are looser, but we want to catch local paths
+ * (`/Users/...`), bare slugs (`my-repo`), and accidental whitespace.
+ *
+ * Matches GitHub's published slug rules:
+ *   owner: starts with alnum, then alnum/hyphen only, must end with
+ *          alnum (no trailing hyphen — GitHub rejects this at account
+ *          creation, so a `my-org-/repo` input would otherwise pass us
+ *          and 422 from GitHub). No underscore, no dot. Length cap 39.
+ *   repo:  any of alnum/dot/hyphen/underscore. Length cap 100.
+ */
+export declare function isValidOwnerRepo(id: string): boolean;
+/**
+ * Strip a single trailing `.git` (case-insensitive) and any trailing
+ * slashes from a URL-ish string. Bounded linear: each character is
+ * visited at most twice, no backtracking.
+ *
+ * Replaces `s.replace(/\.git\/*$/i, '').replace(/\/+$/, '')` which
+ * CodeQL's polynomial-regex check (codeql/js/polynomial-redos) flags as
+ * a worst-case O(n²) on adversarial input like "////.../x".
+ */
+export declare function stripGitSuffix(input: string): string;
+/**
+ * Parse `owner/repo` out of a git remote URL. Mirrors the heuristic in
+ * `gitnexus/src/storage/git.ts:parseRepoNameFromUrl` but keeps both
+ * halves so we can build a registry id. Returns `null` on shapes we
+ * don't recognise.
+ *
+ * Examples:
+ *   git@github.com:looptech-ai/understand-quickly.git
+ *   https://github.com/looptech-ai/understand-quickly
+ *   ssh://git@github.com/looptech-ai/understand-quickly.git
+ */
+export declare function parseOwnerRepoFromRemote(url: string | null | undefined): string | null;
+//# sourceMappingURL=understand-quickly.d.ts.map

package/dist/_shared/integrations/understand-quickly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"understand-quickly.d.ts","sourceRoot":"","sources":["../../src/integrations/understand-quickly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,2EAC8B,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,eAAe,CAAC;AAE1D,oDAAoD;AACpD,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,6BAA6B,CAAC;IACjD,cAAc,EAAE;QACd,gEAAgE;QAChE,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAYpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAsCtF"}

package/dist/_shared/integrations/understand-quickly.js

@@ -0,0 +1,139 @@
+/**
+ * Understand-Quickly registry integration helpers.
+ *
+ * Pure, runtime-agnostic logic for opting in to publishing a GitNexus
+ * index to the [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly)
+ * registry. Lives in `gitnexus-shared` so both the Node CLI and any
+ * future browser-side surface can construct identical dispatch payloads.
+ *
+ * Network I/O lives in the CLI command (`gitnexus/src/cli/publish.ts`)
+ * to keep this module free of Node-only imports — see the comment at
+ * the top of `gitnexus-shared/src/graph/types.ts`.
+ *
+ * The protocol contract (single dispatch event, no graph upload) is
+ * documented at:
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ */
+/**
+ * URL of the registry repo's repository_dispatch endpoint. Hardcoded
+ * because the registry is the canonical home for this integration —
+ * users who want a private registry can fork and patch.
+ */
+export const UNDERSTAND_QUICKLY_DISPATCH_URL = 'https://api.github.com/repos/looptech-ai/understand-quickly/dispatches';
+/**
+ * Event type the registry's sync workflow listens for.
+ * See `looptech-ai/understand-quickly/.github/workflows/sync.yml`.
+ */
+export const UNDERSTAND_QUICKLY_EVENT_TYPE = 'sync-entry';
+/** Environment variable that gates the dispatch. */
+export const UNDERSTAND_QUICKLY_TOKEN_ENV = 'UNDERSTAND_QUICKLY_TOKEN';
+/**
+ * Build the JSON body for the `repository_dispatch` ping. Pure — no
+ * env reads, no network. Validates that `id` looks like `owner/repo`
+ * (one slash, no whitespace, both halves non-empty) so a misconfigured
+ * caller fails loudly before the round-trip.
+ */
+export function buildUqDispatchPayload(id) {
+    if (!isValidOwnerRepo(id)) {
+        throw new Error(`[understand-quickly] expected id of the form "owner/repo", got "${id}". ` +
+            `The registry uses this string to look up your entry in registry.json — ` +
+            `it must match the GitHub owner/repo of the source code, not a local path.`);
+    }
+    return {
+        event_type: UNDERSTAND_QUICKLY_EVENT_TYPE,
+        client_payload: { id },
+    };
+}
+/**
+ * `owner/repo` validation. Conservative on purpose: GitHub's actual
+ * naming rules are looser, but we want to catch local paths
+ * (`/Users/...`), bare slugs (`my-repo`), and accidental whitespace.
+ *
+ * Matches GitHub's published slug rules:
+ *   owner: starts with alnum, then alnum/hyphen only, must end with
+ *          alnum (no trailing hyphen — GitHub rejects this at account
+ *          creation, so a `my-org-/repo` input would otherwise pass us
+ *          and 422 from GitHub). No underscore, no dot. Length cap 39.
+ *   repo:  any of alnum/dot/hyphen/underscore. Length cap 100.
+ */
+export function isValidOwnerRepo(id) {
+    return /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\/[A-Za-z0-9._-]{1,100}$/.test(id);
+}
+/**
+ * Strip a single trailing `.git` (case-insensitive) and any trailing
+ * slashes from a URL-ish string. Bounded linear: each character is
+ * visited at most twice, no backtracking.
+ *
+ * Replaces `s.replace(/\.git\/*$/i, '').replace(/\/+$/, '')` which
+ * CodeQL's polynomial-regex check (codeql/js/polynomial-redos) flags as
+ * a worst-case O(n²) on adversarial input like "////.../x".
+ */
+export function stripGitSuffix(input) {
+    let end = input.length;
+    // Trim trailing '/'.
+    while (end > 0 && input.charCodeAt(end - 1) === 0x2f)
+        end--;
+    // Drop one trailing '.git' (case-insensitive).
+    if (end >= 4) {
+        const tail = input.slice(end - 4, end).toLowerCase();
+        if (tail === '.git')
+            end -= 4;
+    }
+    // Trim trailing '/' that may have sat between '.git' and the rest.
+    while (end > 0 && input.charCodeAt(end - 1) === 0x2f)
+        end--;
+    return input.slice(0, end);
+}
+/**
+ * Parse `owner/repo` out of a git remote URL. Mirrors the heuristic in
+ * `gitnexus/src/storage/git.ts:parseRepoNameFromUrl` but keeps both
+ * halves so we can build a registry id. Returns `null` on shapes we
+ * don't recognise.
+ *
+ * Examples:
+ *   git@github.com:looptech-ai/understand-quickly.git
+ *   https://github.com/looptech-ai/understand-quickly
+ *   ssh://git@github.com/looptech-ai/understand-quickly.git
+ */
+export function parseOwnerRepoFromRemote(url) {
+    if (!url)
+        return null;
+    const trimmed = url.trim();
+    if (!trimmed)
+        return null;
+    // Strip a trailing `.git` (case-insensitive) and any trailing slashes
+    // so https://h/o/r and https://h/o/r.git collapse to the same id.
+    // Bounded-linear helper avoids the polynomial-regex CodeQL alert.
+    const stripped = stripGitSuffix(trimmed);
+    // SCP-form SSH (`git@host:owner/repo`). Capture host so we can reject
+    // non-GitHub remotes — a GitLab origin like
+    // `https://gitlab.example.com/group/sub/project.git` would otherwise
+    // silently dispatch the wrong id (LOW 9).
+    const ssh = stripped.match(/^[^@]+@([^:]+):([^/]+)\/([^/]+)$/);
+    if (ssh) {
+        const host = ssh[1].toLowerCase();
+        if (host !== 'github.com' && host !== 'www.github.com')
+            return null;
+        return `${ssh[2]}/${ssh[3]}`;
+    }
+    // URL forms (https://, ssh://, git://, file://) — last two path segments.
+    const url2 = stripped.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/([^/]+)\/(.+)$/);
+    if (url2) {
+        // Strip optional `userinfo@` (e.g. `ssh://git@github.com/...`).
+        const authority = url2[1];
+        const atIdx = authority.lastIndexOf('@');
+        const hostAndPort = atIdx >= 0 ? authority.slice(atIdx + 1) : authority;
+        // Strip `:port` suffix if present.
+        const colonIdx = hostAndPort.indexOf(':');
+        const host = (colonIdx >= 0 ? hostAndPort.slice(0, colonIdx) : hostAndPort).toLowerCase();
+        if (host !== 'github.com' && host !== 'www.github.com')
+            return null;
+        const segments = url2[2].split('/').filter(Boolean);
+        if (segments.length >= 2) {
+            const [owner, repo] = segments.slice(-2);
+            return `${owner}/${repo}`;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=understand-quickly.js.map

package/dist/_shared/integrations/understand-quickly.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"understand-quickly.js","sourceRoot":"","sources":["../../src/integrations/understand-quickly.ts"],"names":[],"mappings":"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"}

package/dist/cli/index.js

@@ -106,6 +106,15 @@ program
     .command('augment <pattern>')
     .description('Augment a search pattern with knowledge graph context (used by hooks)')
     .action(createLazyAction(() => import('./augment.js'), 'augmentCommand'));
+program
+    .command('publish [path]')
+    .description('Notify the understand-quickly registry that this repo has a fresh GitNexus index. ' +
+    'Opt-in: requires UNDERSTAND_QUICKLY_TOKEN (fine-grained PAT with ' +
+    '`Repository dispatches: write` on looptech-ai/understand-quickly). ' +
+    'No-op without the token. See https://github.com/looptech-ai/understand-quickly.')
+    .option('--id <owner/repo>', 'Override the registry id (defaults to the origin remote)')
+    .option('--skip-git', 'Treat cwd as the repo root and skip parent git-root discovery')
+    .action(createLazyAction(() => import('./publish.js'), 'publishCommand'));
 // ─── Direct Tool Commands (no MCP overhead) ────────────────────────
 // These invoke LocalBackend directly for use in eval, scripts, and CI.
 program

package/dist/cli/publish.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `gitnexus publish` — opt-in ping to the understand-quickly registry.
+ *
+ * Fires a single `repository_dispatch` event at
+ * `looptech-ai/understand-quickly` so the registry knows to refresh its
+ * entry for the current repo. Does NOT upload anything: per the
+ * understand-quickly protocol, the registry pulls the graph from a
+ * raw-GitHub URL the user controls.
+ *
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ *
+ * Defaults:
+ *   - Without `UNDERSTAND_QUICKLY_TOKEN` in the env, this is a no-op
+ *     (prints one informational line, exit 0). Same shape as the
+ *     `--publish` patterns in sibling tools.
+ *   - With the token, fires the dispatch and reports the response code.
+ *
+ * The `id` is derived from the repo's `origin` remote unless the caller
+ * passes `--id <owner/repo>` explicitly. We deliberately do NOT auto-add
+ * the repo to the registry — registration is one-time and uses the
+ * `npx @understand-quickly/cli add` path documented in the protocol.
+ */
+export interface PublishOptions {
+    /** Override the auto-derived `owner/repo` id. */
+    id?: string;
+    /** Treat the cwd as the repo root (skip git-root walk). */
+    skipGit?: boolean;
+}
+export declare const publishCommand: (inputPath?: string, options?: PublishOptions) => Promise<void>;

package/dist/cli/publish.js

@@ -0,0 +1,174 @@
+/**
+ * `gitnexus publish` — opt-in ping to the understand-quickly registry.
+ *
+ * Fires a single `repository_dispatch` event at
+ * `looptech-ai/understand-quickly` so the registry knows to refresh its
+ * entry for the current repo. Does NOT upload anything: per the
+ * understand-quickly protocol, the registry pulls the graph from a
+ * raw-GitHub URL the user controls.
+ *
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ *
+ * Defaults:
+ *   - Without `UNDERSTAND_QUICKLY_TOKEN` in the env, this is a no-op
+ *     (prints one informational line, exit 0). Same shape as the
+ *     `--publish` patterns in sibling tools.
+ *   - With the token, fires the dispatch and reports the response code.
+ *
+ * The `id` is derived from the repo's `origin` remote unless the caller
+ * passes `--id <owner/repo>` explicitly. We deliberately do NOT auto-add
+ * the repo to the registry — registration is one-time and uses the
+ * `npx @understand-quickly/cli add` path documented in the protocol.
+ */
+import path from 'path';
+import { UNDERSTAND_QUICKLY_DISPATCH_URL, UNDERSTAND_QUICKLY_TOKEN_ENV, buildUqDispatchPayload, isValidOwnerRepo, parseOwnerRepoFromRemote, } from '../_shared/index.js';
+import { getGitRoot, getRemoteOriginUrl, getCurrentCommit } from '../storage/git.js';
+import { hasIndex } from '../storage/repo-manager.js';
+import { cliInfo, cliError } from './cli-message.js';
+const REGISTER_HINT = 'Register your repo once with: npx @understand-quickly/cli add\n' +
+    'Or use the wizard: https://looptech-ai.github.io/understand-quickly/add.html';
+/**
+ * Hard cap on the dispatch fetch to keep CI publish steps from stalling
+ * for the OS TCP timeout (~2 min) when api.github.com is unreachable.
+ * Matches the pattern used in `src/core/embeddings/http-client.ts`.
+ */
+const DISPATCH_TIMEOUT_MS = 15_000;
+export const publishCommand = async (inputPath, options = {}) => {
+    // ── 0. Token gate FIRST — guarantees true no-op without the token. ──
+    // The README, CLI --help, and PR body all promise "exit 0 without
+    // UNDERSTAND_QUICKLY_TOKEN". Doing the index/repo-root checks before
+    // the token gate would make those promises false for users who haven't
+    // run `gitnexus analyze` yet but want to verify the command is wired.
+    const token = process.env[UNDERSTAND_QUICKLY_TOKEN_ENV];
+    if (!token) {
+        cliInfo(`[understand-quickly] ${UNDERSTAND_QUICKLY_TOKEN_ENV} is not set — skipping dispatch.\n` +
+            `Set it to a fine-grained PAT with "Repository dispatches: write" on ` +
+            `looptech-ai/understand-quickly to enable instant resync.\n` +
+            `(Without the token, the registry's nightly sync still picks up your entry.)`, { skipped: 'no-token' });
+        return;
+    }
+    // ── 1. Resolve the repo root (same precedence as `analyze`) ──────────
+    let repoPath;
+    if (inputPath) {
+        repoPath = path.resolve(inputPath);
+    }
+    else if (options.skipGit) {
+        repoPath = path.resolve(process.cwd());
+    }
+    else {
+        const gitRoot = getGitRoot(process.cwd());
+        if (!gitRoot) {
+            cliError('[understand-quickly] not inside a git repository.\n' +
+                'Run from a repo, or pass --skip-git to publish from the current directory.');
+            process.exitCode = 1;
+            return;
+        }
+        repoPath = gitRoot;
+    }
+    // ── 2. Confirm a GitNexus index exists ───────────────────────────────
+    // Publishing without an index is almost always a mistake — the
+    // registry's nightly sync would fetch a stale or missing graph file
+    // and mark the entry `missing`. Refuse loudly with a fix-it hint.
+    if (!(await hasIndex(repoPath))) {
+        cliError(`[understand-quickly] no GitNexus index found at ${repoPath}/.gitnexus.\n` +
+            'Run `gitnexus analyze` first, then re-run `gitnexus publish`.');
+        process.exitCode = 1;
+        return;
+    }
+    // ── 3. Derive the registry id ─────────────────────────────────────────
+    const id = options.id ?? parseOwnerRepoFromRemote(getRemoteOriginUrl(repoPath) ?? undefined) ?? null;
+    if (!id || !isValidOwnerRepo(id)) {
+        cliError(`[understand-quickly] could not derive a registry id from this repo.\n` +
+            `Pass --id <owner/repo> explicitly (e.g. --id looptech-ai/${path.basename(repoPath)}).\n` +
+            REGISTER_HINT);
+        process.exitCode = 1;
+        return;
+    }
+    // ── 4. Fire the dispatch ─────────────────────────────────────────────
+    const payload = buildUqDispatchPayload(id);
+    let response;
+    try {
+        response = await fetch(UNDERSTAND_QUICKLY_DISPATCH_URL, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/vnd.github+json',
+                Authorization: `Bearer ${token}`,
+                'X-GitHub-Api-Version': '2022-11-28',
+                'Content-Type': 'application/json',
+                'User-Agent': 'gitnexus-cli',
+            },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(DISPATCH_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        // `AbortSignal.timeout()` throws a `DOMException` with `name ===
+        // 'TimeoutError'` on Node 18.14+ (and on browsers/Bun). It is NOT
+        // a plain `AbortError`. Match the pattern used in
+        // gitnexus/src/core/embeddings/http-client.ts so the user sees the
+        // targeted "timed out" message instead of a generic "operation
+        // was aborted".
+        const isTimeout = err instanceof DOMException && err.name === 'TimeoutError';
+        if (isTimeout) {
+            cliError(`[understand-quickly] dispatch timed out after ${DISPATCH_TIMEOUT_MS}ms. ` +
+                `Check network access to api.github.com and retry.`, { id });
+        }
+        else {
+            const msg = err instanceof Error ? err.message : String(err);
+            cliError(`[understand-quickly] dispatch network error: ${msg}`, { id });
+        }
+        process.exitCode = 1;
+        return;
+    }
+    // GitHub returns 204 on success. Distinct branches for 401/403/404/422
+    // so users debug without checking the docs.
+    if (response.status === 204) {
+        await response.body?.cancel().catch(() => { });
+        // `getCurrentCommit` is only meaningful in the success path — moving
+        // it inside this branch removes a wasted child-process spawn on every
+        // error response (LOW 7).
+        const commit = getCurrentCommit(repoPath);
+        cliInfo(`[understand-quickly] dispatched sync-entry for ${id}` +
+            (commit ? ` @ ${commit.slice(0, 7)}` : '') +
+            '.\n' +
+            `Note: a 204 only confirms GitHub accepted the dispatch. Whether the ` +
+            `registry workflow finds an entry for "${id}" is logged at ` +
+            `https://github.com/looptech-ai/understand-quickly/actions/workflows/sync.yml`, { id, commit, status: response.status });
+        return;
+    }
+    if (response.status === 401) {
+        cliError(`[understand-quickly] dispatch returned 401 — the ${UNDERSTAND_QUICKLY_TOKEN_ENV} value is invalid or expired.\n` +
+            `Regenerate a fine-grained PAT at https://github.com/settings/personal-access-tokens ` +
+            `with Repository access scoped to looptech-ai/understand-quickly and the ` +
+            `"Repository dispatches: write" permission, then retry.`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 403) {
+        cliError(`[understand-quickly] dispatch returned 403 — the token authenticated but ` +
+            `lacks the "Repository dispatches: write" permission on ` +
+            `looptech-ai/understand-quickly. Edit the PAT scopes and retry.`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 404) {
+        cliError(`[understand-quickly] dispatch returned 404 — the token cannot reach ` +
+            `looptech-ai/understand-quickly. Verify the PAT has Repository access to ` +
+            `that exact repo (not just your own org).`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    if (response.status === 422) {
+        // Malformed event_type / client_payload — a code bug in this CLI,
+        // not a user mistake. Surface so we get bug reports.
+        const body422 = await response.text().catch(() => '');
+        cliError(`[understand-quickly] dispatch returned 422 (this is a CLI bug; please report).\n` +
+            `Body: ${body422 || '(empty)'}`, { id, status: response.status });
+        process.exitCode = 1;
+        return;
+    }
+    // 5xx and anything else → bubble the body so the user has something to act on.
+    const body = await response.text().catch(() => '');
+    cliError(`[understand-quickly] dispatch failed with HTTP ${response.status}: ${body || '(empty body)'}`, { id, status: response.status });
+    process.exitCode = 1;
+};

package/dist/core/ingestion/call-processor.js

@@ -612,9 +612,10 @@ importedRawReturnTypesMap, heritageMap, bindingAccumulator) => {
         await loadLanguage(language, file.path);
         let tree = astCache.get(file.path);
         if (!tree) {
+            const parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;
             try {
-                tree = parser.parse(file.content, undefined, {
-                    bufferSize: getTreeSitterBufferSize(file.content),
+                tree = parser.parse(parseContent, undefined, {
+                    bufferSize: getTreeSitterBufferSize(parseContent),
                 });
             }
             catch (parseError) {
@@ -2583,9 +2584,10 @@ export const extractFetchCallsFromFiles = async (files, astCache) => {
         await loadLanguage(language, file.path);
         let tree = astCache.get(file.path);
         if (!tree) {
+            const parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;
             try {
-                tree = parser.parse(file.content, undefined, {
-                    bufferSize: getTreeSitterBufferSize(file.content),
+                tree = parser.parse(parseContent, undefined, {
+                    bufferSize: getTreeSitterBufferSize(parseContent),
                 });
             }
             catch {

package/dist/core/ingestion/cpp-ue-preprocessor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Strip Unreal Engine reflection macros from C++ source, length-preserving.
+ *
+ * Returns the original string unchanged if no strong UE marker is detected,
+ * so non-UE C++ files (including ones that contain `*_API`-suffixed
+ * identifiers like `REST_API` or `HTTP_API`) incur only a single regex test.
+ *
+ * The `_filePath` parameter is part of the `LanguageProvider.preprocessSource`
+ * contract but is unused — UE detection is purely content-based. Accepted and
+ * ignored here so the function matches the hook signature exactly.
+ */
+export declare function stripUeMacros(source: string, _filePath?: string): string;

package/dist/core/ingestion/cpp-ue-preprocessor.js

@@ -0,0 +1,260 @@
+/**
+ * Unreal Engine reflection-macro preprocessor for C++ source.
+ *
+ * Tree-sitter does not expand C preprocessor macros, so Unreal's reflection
+ * markers (`UCLASS(...)`, `UFUNCTION(...)`, `MODULENAME_API`, ...) are parsed
+ * verbatim. The result is mis-parsed declarations: in `class BRAWLUI_API
+ * UMyClass : public UObject`, tree-sitter-cpp captures `BRAWLUI_API` as the
+ * class name and the rest of the declaration becomes structurally wrong.
+ *
+ * This module elides those macros from the source text BEFORE tree-sitter
+ * parses it. Replacement is **length-preserving** (each elided byte becomes
+ * a space, newlines preserved) so byte offsets and line/column positions
+ * tree-sitter reports remain identical to the original file. Symbol
+ * locations in the graph stay accurate.
+ *
+ * A cheap detection guard short-circuits files that don't look like UE
+ * sources, so non-UE C++ codebases pay no cost.
+ *
+ * Pure function — no tree-sitter dependency, safe for worker threads.
+ */
+/**
+ * Strong UE markers — reflection macros that only Unreal Engine projects use.
+ * Presence of one of these is sufficient evidence that the file is a UE source
+ * and that `MODULENAME_API` tokens in it are intended as export macros.
+ *
+ * Importantly, `_API` tokens are NOT in this guard — `REST_API`, `HTTP_API`,
+ * `MY_LIB_API` and similar identifiers appear in plenty of non-UE C++ codebases
+ * as constants/enums/parameter names. We must not erase them just because the
+ * file mentions an `_API` token.
+ */
+const HAS_UE_HINT = /\b(?:UCLASS|UFUNCTION|UPROPERTY|USTRUCT|UENUM|UINTERFACE|GENERATED_BODY|GENERATED_[A-Z_]+_BODY|UE_DEPRECATED|DECLARE_(?:DYNAMIC_)?(?:MULTICAST_)?DELEGATE)/;
+const SIMPLE_MACROS_NO_ARGS = [
+    'GENERATED_BODY',
+    'GENERATED_UCLASS_BODY',
+    'GENERATED_USTRUCT_BODY',
+    'GENERATED_UINTERFACE_BODY',
+    'GENERATED_IINTERFACE_BODY',
+    'DECLARE_CLASS',
+    'GENERATED_BODY_LEGACY',
+];
+const PARENTHESIZED_MACROS = [
+    'UCLASS',
+    'UFUNCTION',
+    'UPROPERTY',
+    'USTRUCT',
+    'UENUM',
+    'UINTERFACE',
+    'UMETA',
+    'UE_DEPRECATED',
+];
+const DELEGATE_MACRO_RE = /\bDECLARE_(?:DYNAMIC_)?(?:MULTICAST_)?DELEGATE(?:_(?:RetVal_OneParam|RetVal_TwoParams|RetVal_ThreeParams|RetVal_FourParams|RetVal_FiveParams|RetVal_SixParams|RetVal_SevenParams|RetVal_EightParams|RetVal_NineParams|RetVal|OneParam|TwoParams|ThreeParams|FourParams|FiveParams|SixParams|SevenParams|EightParams|NineParams|TenParams))?(?=\s*\()/g;
+/**
+ * Module export tokens like `BRAWLUI_API`, `ENGINE_API`, `COREUOBJECT_API`.
+ * Pattern: ALL_CAPS identifier ending in `_API`. The leading word boundary
+ * (`\b`) prevents matching mid-identifier.
+ */
+const API_MACRO_RE = /\b[A-Z][A-Z0-9_]*_API\b/g;
+/** Replace `[start, end)` of `chars` with spaces, preserving newlines. */
+function eraseRange(chars, start, end) {
+    for (let i = start; i < end; i++) {
+        if (chars[i] !== '\n' && chars[i] !== '\r') {
+            chars[i] = ' ';
+        }
+    }
+}
+/**
+ * Find the matching close paren for an opening paren at index `openIdx`.
+ * Returns the index of `)` (inclusive end), or -1 if unbalanced.
+ *
+ * Handles nested parens and string/char literals so commas/parens inside
+ * strings don't throw off the match. Does not attempt to handle raw string
+ * literals (`R"(...)"`); UE reflection-macro arguments do not use them in
+ * practice.
+ */
+function findMatchingParen(source, openIdx) {
+    if (source.charCodeAt(openIdx) !== 0x28)
+        return -1;
+    let depth = 1;
+    let i = openIdx + 1;
+    const len = source.length;
+    while (i < len && depth > 0) {
+        const ch = source.charCodeAt(i);
+        // String literal
+        if (ch === 0x22) {
+            i++;
+            while (i < len) {
+                const c = source.charCodeAt(i);
+                if (c === 0x5c) {
+                    i += 2;
+                    continue;
+                }
+                if (c === 0x22) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        // Char literal
+        if (ch === 0x27) {
+            i++;
+            while (i < len) {
+                const c = source.charCodeAt(i);
+                if (c === 0x5c) {
+                    i += 2;
+                    continue;
+                }
+                if (c === 0x27) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        // Line comment
+        if (ch === 0x2f && source.charCodeAt(i + 1) === 0x2f) {
+            while (i < len && source.charCodeAt(i) !== 0x0a)
+                i++;
+            continue;
+        }
+        // Block comment
+        if (ch === 0x2f && source.charCodeAt(i + 1) === 0x2a) {
+            i += 2;
+            while (i < len) {
+                if (source.charCodeAt(i) === 0x2a && source.charCodeAt(i + 1) === 0x2f) {
+                    i += 2;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (ch === 0x28)
+            depth++;
+        else if (ch === 0x29) {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+        i++;
+    }
+    return -1;
+}
+/** Match a whole-word identifier at `idx`. Returns the byte after the identifier, or -1 on miss. */
+function matchIdentifierAt(source, idx, name) {
+    if (idx > 0) {
+        const prev = source.charCodeAt(idx - 1);
+        if ((prev >= 0x30 && prev <= 0x39) ||
+            (prev >= 0x41 && prev <= 0x5a) ||
+            (prev >= 0x61 && prev <= 0x7a) ||
+            prev === 0x5f) {
+            return -1;
+        }
+    }
+    for (let k = 0; k < name.length; k++) {
+        if (source.charCodeAt(idx + k) !== name.charCodeAt(k))
+            return -1;
+    }
+    const after = idx + name.length;
+    if (after < source.length) {
+        const next = source.charCodeAt(after);
+        if ((next >= 0x30 && next <= 0x39) ||
+            (next >= 0x41 && next <= 0x5a) ||
+            (next >= 0x61 && next <= 0x7a) ||
+            next === 0x5f) {
+            return -1;
+        }
+    }
+    return after;
+}
+/** Skip ASCII whitespace forward from `idx`. Returns the next non-whitespace byte index. */
+function skipWhitespace(source, idx) {
+    const len = source.length;
+    while (idx < len) {
+        const ch = source.charCodeAt(idx);
+        if (ch === 0x20 || ch === 0x09 || ch === 0x0a || ch === 0x0d) {
+            idx++;
+            continue;
+        }
+        break;
+    }
+    return idx;
+}
+/**
+ * Strip Unreal Engine reflection macros from C++ source, length-preserving.
+ *
+ * Returns the original string unchanged if no strong UE marker is detected,
+ * so non-UE C++ files (including ones that contain `*_API`-suffixed
+ * identifiers like `REST_API` or `HTTP_API`) incur only a single regex test.
+ *
+ * The `_filePath` parameter is part of the `LanguageProvider.preprocessSource`
+ * contract but is unused — UE detection is purely content-based. Accepted and
+ * ignored here so the function matches the hook signature exactly.
+ */
+export function stripUeMacros(source, _filePath) {
+    if (!HAS_UE_HINT.test(source))
+        return source;
+    const chars = source.split('');
+    for (const macro of PARENTHESIZED_MACROS) {
+        let searchFrom = 0;
+        while (true) {
+            const hit = source.indexOf(macro, searchFrom);
+            if (hit < 0)
+                break;
+            searchFrom = hit + 1;
+            const after = matchIdentifierAt(source, hit, macro);
+            if (after < 0)
+                continue;
+            const parenIdx = skipWhitespace(source, after);
+            if (source.charCodeAt(parenIdx) !== 0x28)
+                continue;
+            const close = findMatchingParen(source, parenIdx);
+            if (close < 0)
+                continue;
+            eraseRange(chars, hit, close + 1);
+        }
+    }
+    for (const macro of SIMPLE_MACROS_NO_ARGS) {
+        let searchFrom = 0;
+        while (true) {
+            const hit = source.indexOf(macro, searchFrom);
+            if (hit < 0)
+                break;
+            searchFrom = hit + 1;
+            const after = matchIdentifierAt(source, hit, macro);
+            if (after < 0)
+                continue;
+            const parenIdx = skipWhitespace(source, after);
+            if (source.charCodeAt(parenIdx) === 0x28) {
+                const close = findMatchingParen(source, parenIdx);
+                if (close < 0)
+                    continue;
+                eraseRange(chars, hit, close + 1);
+            }
+            else {
+                eraseRange(chars, hit, after);
+            }
+        }
+    }
+    for (const re of [DELEGATE_MACRO_RE, API_MACRO_RE]) {
+        re.lastIndex = 0;
+        let match;
+        while ((match = re.exec(source)) !== null) {
+            const start = match.index;
+            let end = start + match[0].length;
+            if (re === DELEGATE_MACRO_RE) {
+                const parenIdx = skipWhitespace(source, end);
+                if (source.charCodeAt(parenIdx) === 0x28) {
+                    const close = findMatchingParen(source, parenIdx);
+                    if (close >= 0)
+                        end = close + 1;
+                }
+            }
+            eraseRange(chars, start, end);
+        }
+    }
+    return chars.join('');
+}

package/dist/core/ingestion/heritage-processor.js

@@ -147,9 +147,13 @@ export const processHeritage = async (graph, files, astCache, ctx, onProgress) =
         let tree = astCache.get(file.path);
         if (!tree) {
             // Use larger bufferSize for files > 32KB
+            // Per-language source preprocessor (length-preserving, e.g. UE macro
+            // stripping for C++). MUST mirror parsing-processor on cache miss so
+            // re-parses see the same input as the cached AST.
+            const parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;
             try {
-                tree = parser.parse(file.content, undefined, {
-                    bufferSize: getTreeSitterBufferSize(file.content),
+                tree = parser.parse(parseContent, undefined, {
+                    bufferSize: getTreeSitterBufferSize(parseContent),
                 });
             }
             catch (parseError) {
@@ -294,9 +298,10 @@ export async function extractExtractedHeritageFromFiles(files, astCache) {
         await loadLanguage(language, file.path);
         let tree = astCache.get(file.path);
         if (!tree) {
+            const parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;
             try {
-                tree = parser.parse(file.content, undefined, {
-                    bufferSize: getTreeSitterBufferSize(file.content),
+                tree = parser.parse(parseContent, undefined, {
+                    bufferSize: getTreeSitterBufferSize(parseContent),
                 });
             }
             catch {

package/dist/core/ingestion/import-processor.js

@@ -241,9 +241,10 @@ export const processImports = async (graph, files, astCache, ctx, onProgress, re
         let tree = astCache.get(file.path);
         let wasReparsed = false;
         if (!tree) {
+            const parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;
             try {
-                tree = parser.parse(file.content, undefined, {
-                    bufferSize: getTreeSitterBufferSize(file.content),
+                tree = parser.parse(parseContent, undefined, {
+                    bufferSize: getTreeSitterBufferSize(parseContent),
                 });
             }
             catch (parseError) {

package/dist/core/ingestion/language-provider.d.ts

@@ -74,6 +74,38 @@ interface LanguageProviderConfig {
     /** Tree-sitter query strings for definitions, imports, calls, heritage.
      *  Required for tree-sitter languages; empty string for standalone processors. */
     readonly treeSitterQueries: string;
+    /**
+     * Optional source-text transform that runs **before** tree-sitter parses the file.
+     *
+     * Used to elide language constructs that confuse the grammar without affecting
+     * source-position fidelity — e.g., Unreal Engine reflection macros (`UCLASS`,
+     * `UFUNCTION`, `MODULENAME_API`) in C++ headers that prevent the parser from
+     * recognising class/function names correctly.
+     *
+     * **Length / position preservation:** the returned string MUST have the same
+     * JavaScript `.length` as the input AND preserve every newline (`\n`/`\r`)
+     * position byte-for-byte. Implementations replace elided characters with
+     * ASCII spaces while leaving newlines untouched. With this contract:
+     *
+     *   - tree-sitter's reported `startPosition.row`/`startPosition.column`
+     *     match the original file exactly (line/column come from newline counts)
+     *   - `startIndex`/`endIndex` byte offsets match the original file exactly
+     *     **when the elided range is pure ASCII** (UTF-16 `.length` equals UTF-8
+     *     byte length only for ASCII).
+     *
+     * Implementations targeting languages where elided ranges may contain
+     * non-ASCII content must therefore preserve byte length, not just `.length`,
+     * if downstream code uses `startIndex` to slice the original UTF-8 bytes.
+     * The current C++ UE-macro preprocessor relies on the practical fact that
+     * UE reflection macros and module-export tokens are ASCII-only.
+     *
+     * Must be a pure function — same input always yields the same output. Called
+     * once per file, on every code path that re-parses (parsing-processor, import
+     * processor, heritage processor, call processor, parse worker).
+     *
+     * Default: undefined (no preprocessing — `file.content` is parsed verbatim).
+     */
+    readonly preprocessSource?: (sourceText: string, filePath: string) => string;
     /** Type extraction: declarations, initializers, for-loop bindings */
     readonly typeConfig: LanguageTypeConfig;
     /** Export detection: is this AST node a public/exported symbol? */

package/dist/core/ingestion/languages/c-cpp.js

@@ -36,6 +36,7 @@ import { cVariableConfig, cppVariableConfig } from '../variable-extractors/confi
 import { createCallExtractor } from '../call-extractors/generic.js';
 import { cCallConfig, cppCallConfig } from '../call-extractors/configs/c-cpp.js';
 import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+import { stripUeMacros } from '../cpp-ue-preprocessor.js';
 const C_BUILT_INS = new Set([
     'printf',
     'fprintf',
@@ -380,6 +381,7 @@ export const cppProvider = defineLanguage({
         },
     ],
     treeSitterQueries: CPP_QUERIES,
+    preprocessSource: stripUeMacros,
     typeConfig: cCppConfig,
     exportChecker: cCppExportChecker,
     importResolver: createImportResolver(cppImportConfig),

package/dist/core/ingestion/parsing-processor.js

@@ -262,6 +262,10 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
             lineOffset = extracted.lineOffset;
             isVueSetup = extracted.isSetup;
         }
+        // Per-language source-text transform (e.g., UE macro stripping for C++).
+        // Length-preserving — see LanguageProvider.preprocessSource contract.
+        parseContent =
+            getProvider(language).preprocessSource?.(parseContent, file.path) ?? parseContent;
         try {
             await loadLanguage(language, file.path);
         }

package/dist/core/ingestion/workers/parse-worker.js

@@ -1019,6 +1019,10 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             lineOffset = extracted.lineOffset;
             isVueSetup = extracted.isSetup;
         }
+        // Per-language source-text transform (e.g., UE macro stripping for C++).
+        // Length-preserving — see LanguageProvider.preprocessSource contract.
+        parseContent =
+            getProvider(language).preprocessSource?.(parseContent, file.path) ?? parseContent;
         clearCaches(); // Reset memoization before each new file
         let tree;
         try {

package/package.json

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