This commit is contained in:
breezefaith 2026-10-29 17:41:47 +00:00 • committed by GitHub
commit dbb2139c80
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
34 changed files with 1521 additions and 84 deletions

View file

@ -229,6 +229,10 @@ Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max
| `GITNEXUS_QUERY_MAX_RSS_MB` | max(8192 MiB, 25% of available RAM), capped at 75% of available RAM | Process-memory ceiling while pooled reads run; available RAM is the smaller of physical RAM and a reported runtime/container constraint. Positive MiB values override it; `0` disables the guard. Invalid, overflowing, or sub-byte values use the default. A breach exits the process with code 70. | Set in the CLI/MCP/serve environment when a legitimate read workload needs a different budget. It does not resize the database buffer pool. |
| `GITNEXUS_QUERY_TRACE` | unset | `1` writes query duration, row count, and sampled memory to stderr. Bound parameters are omitted; query text is included. | Diagnose an expensive read or a memory-guard exit. Inspect trace output before sharing it. |
| Analyze configuration | Default | Effect | When to tune |
| --- | --- | --- | --- |
| `GITNEXUS_RC` | unset | Absolute path to a JSON file with the same keys as `.gitnexusrc`. Its keys override repository configuration; CLI flags still win. Missing, invalid, or oversized files fail analysis. | Keep local configuration outside the checkout. Re-indexing hooks and watch processes must inherit it too. Changing or removing router aliases or handler wrappers rebuilds route evidence. |
| Variable | Default | Effect | Tune when… |
| ----------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GITNEXUS_TEST_REPORT` | unset | Write a JSON execution receipt from `scripts/run-cross-platform.ts`; accepts a basename ending in `.json`. | CI platform shards use distinct filenames so the completeness check can require every report. |

View file

@ -409,6 +409,21 @@ anchors are deliberately omitted. Add common infrastructure fields such as `/hea
`--spring-actuator` is explicitly opt-in. The path may be a JSON bundle keyed by `mappings`, `beans`, `conditions`, `configprops`, and/or `env`, or a directory containing endpoint-named JSON files. Runtime mappings and beans confirm matching static nodes; conditions and configuration property keys enrich existing evidence, with conservative runtime-only nodes added when no match exists. The configured input is excluded from source scanning; only normalized repository-relative exclusions are retained for future scans, never absolute paths. Env/configprops values, origins, condition messages, and source names are never persisted or printed. Enabled runs always rebuild because runtime snapshots are external to git freshness; omitting the option later rebuilds once to remove runtime evidence. Project config can set the same path with `springActuator` in `.gitnexusrc`.
Go gin/echo routes are indexed when a file imports `github.com/gin-gonic/gin` or `github.com/labstack/echo` directly. A service that registers routes through an internal wrapper package — `func InitRoute(s *core.Engine)`, where the dependency declares `type Engine = gin.Engine` — produces no routes, because the wrapper's source is usually not in the repository and the equivalence cannot be proven. Declare it in `.gitnexusrc`, together with any application adapters that wrap the real handler (`common.Wrapper(api.CreateJob)`):
```json
{
"goRouterAliases": [
{ "importPath": "example.com/infra/pkg", "type": "Engine", "framework": "gin" }
],
"goHandlerWrappers": ["common.Wrapper", "common.WrapperWithSuccessCode"]
}
```
`framework` is `gin` or `echo` and selects the handler argument order. A wrapper entry is the callee exactly as written at the registration site; its first argument becomes the route's handler. Registrations on an undeclared wrapper type are dropped, and `analyze` logs how many were dropped per `importPath.Type` so you can see what to declare. Changing either key rebuilds Route evidence on the next `analyze` without `--force`.
To keep this configuration out of the working tree, set `GITNEXUS_RC` to the absolute path of a JSON file with the same shape as `.gitnexusrc`. Its keys override the repository's `.gitnexusrc` key by key, and CLI flags still win. Hooks, MCP servers, and watch processes that re-index must see the same variable; if a later run no longer has it, `analyze` warns before removing the Routes it produced.
`--asyncapi-spec` is explicitly opt-in and accepts a directory of AsyncAPI documents or a single document; the path is resolved against the repository root, so a committed `docs/asyncapi` and an absolute cache written by something else both work. Each `operations[]` entry of an **AsyncAPI 3.x** document can contribute a `Destination` node keyed by broker and address, with `action: send` emitting `PUBLISHES_TO` and `action: receive` emitting `CONSUMES_FROM`, so a document and source code that name one address on one broker land on the same node. Edges start at the document, not at a callable — a document states that the service talks to an address, not which method does — and no address a document names is ever attached to an unresolved source site.
An operation must name a protocol, either through its own `bindings` or through the `servers[].protocol` of the servers its channel resolves to (a channel that lists no `servers` resolves to all of them); operations that name none are refused, as are operations whose two readings name different brokers, and channels that inherit a multi-protocol server set without choosing. HTTP and WebSocket documents are refused for destination minting: there the host rather than the address names the place, and an HTTP endpoint is already modelled as a `Route`. A parameterized address — a channel declaring `parameters`, or an address containing `{` — is refused rather than keyed: two services publishing `{env}.orders` share a pattern, not a queue. AsyncAPI **2.x is refused** under its own counted reason and never mapped, because its `publish`/`subscribe` are inverted relative to 3.x `send`/`receive` and a naive mapping would reverse the async graph while leaving it connected. Every refusal is counted, and a configured path that yields nothing is reported rather than passed over in silence.

View file

@ -0,0 +1,97 @@
/**
* Compare Go route collection in two compiled builds, with exact output parity.
* Run after building both checkouts:
* node --expose-gc --import tsx scripts/bench/go-route-facts.ts /baseline/gitnexus/dist
*
* The baseline must already expose the Go provider's `resolveRouteFacts` hook
* (e.g. an earlier commit of this feature), not a build from before it.
*
* Parsing and module startup are excluded. Nine batches alternate build order;
* serialized bytes measure the worker payload, not heap or whole-index memory.
*/
import assert from 'node:assert/strict';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { performance } from 'node:perf_hooks';
import Parser from 'tree-sitter';
import Go from 'tree-sitter-go';
import type { ParsedFile } from 'gitnexus-shared';
import type { LanguageProvider } from '../../src/core/ingestion/language-provider.js';
const baseline = process.argv[2];
assert(baseline, 'Pass the baseline build directory (gitnexus/dist)');
const builds = [path.resolve(baseline), fileURLToPath(new URL('../../dist', import.meta.url))];
const providers: LanguageProvider[] = await Promise.all(
builds.map(
async (dir) =>
(await import(pathToFileURL(path.join(dir, 'core/ingestion/languages/go.js')).href))
.goProvider,
),
);
const parser = new Parser();
parser.setLanguage(Go);
const parsedFile: ParsedFile = {
filePath: 'routes.go',
moduleScope: 'bench' as ParsedFile['moduleScope'],
scopes: [],
parsedImports: [],
localDefs: [],
referenceSites: [],
};
const config = {
routeFrameworkAliases: [
{ importPath: 'example.com/infra/pkg', type: 'Engine', framework: 'gin' },
],
routeHandlerWrappers: ['common.Wrapper'],
};
// The baseline used flat hook options; the current build receives one object.
const context = { resolveImportTargets: () => [], ...config, routeHookConfig: config };
const lines = (count: number, line: (i: number) => string) =>
Array.from({ length: count }, (_, i) => line(i)).join('\n');
const workloads = {
noRoutes: `package routes\nimport "fmt"\n${lines(100, (i) => `func F${i}(x int) int { fmt.Println(x); return x + 1 }`)}`,
direct: `package routes\nimport "github.com/gin-gonic/gin"\nfunc R(r *gin.Engine) {\n${lines(100, (i) => `r.GET("/${i}", Middleware, Handler)`)}\n}`,
wrapped: `package routes\nimport core "example.com/infra/pkg"\nimport "example.com/app/common"\nfunc R(r *core.Engine) {\n${lines(100, (i) => `r.GET("/${i}", Middleware, common.Wrapper(Handler))`)}\n}`,
mixed: `package routes\nimport "github.com/gin-gonic/gin"\nimport core "example.com/infra/pkg"\nfunc R(r *gin.Engine, s *core.Engine) {\n${lines(100, (i) => `${i % 2 ? 'r' : 's'}.GET("/${i}", Middleware, Handler)`)}\n}`,
manyParameters: `package routes\nimport core "example.com/infra/pkg"\nfunc R(r *core.Engine, ${Array.from({ length: 30 }, (_, i) => `x${i} *core.T${i}`).join(', ')}) {\n${lines(100, (i) => `r.GET("/${i}", Middleware, Handler)`)}\n}`,
};
const results = [];
for (const [name, source] of Object.entries(workloads)) {
const tree = parser.parse(source);
const collect = (provider: LanguageProvider) => ({
direct: provider.extractDecoratorRoutes?.(tree, parsedFile.filePath, 0) ?? [],
facts: provider.extractRouteFacts?.(tree, parsedFile, 0),
});
const outputs = providers.map((provider) => {
const { direct, facts } = collect(provider);
return [
...provider.resolveRouteFacts!([{ filePath: parsedFile.filePath, facts }], context),
...direct,
];
});
assert.deepEqual(outputs[1], outputs[0], `${name}: route/handler/order parity`);
assert.equal(outputs[0].length, name === 'noRoutes' ? 0 : 100);
for (const provider of providers) for (let i = 0; i < 20; i++) collect(provider);
const samples: number[][] = [[], []];
const iterations = name === 'manyParameters' ? 30 : 75;
for (let round = 0; round < 9; round++) {
for (const index of round % 2 ? [1, 0] : [0, 1]) {
global.gc?.();
const start = performance.now();
for (let i = 0; i < iterations; i++) collect(providers[index]);
samples[index].push((performance.now() - start) / iterations);
}
}
results.push({
name,
routes: outputs[0].length,
iterations,
sampleMs: samples,
medianMs: samples.map((sample) => [...sample].sort((a, b) => a - b)[4]),
serializedFactsBytes: providers.map((provider) =>
Buffer.byteLength(JSON.stringify(collect(provider))),
),
});
}
console.log(JSON.stringify({ node: process.version, builds, results }, null, 2));

View file

@ -30,7 +30,9 @@
import fs from 'node:fs';
import path from 'node:path';
import { readRepoControlFile } from '../config/repo-control-file.js';
import { MAX_REPO_CONTROL_FILE_BYTES, readRepoControlFile } from '../config/repo-control-file.js';
import { logger } from '../core/logger.js';
import { normalizeRouterAliases } from '../core/ingestion/languages/go/route-config.js';
import {
InvalidBranchError,
sanitizeDetectedBranch,
@ -64,7 +66,8 @@ type ValueKind =
| 'numeric-string'
| 'embeddings'
| 'branch'
| 'path';
| 'path'
| 'router-aliases';
interface KeySpec {
/** The `AnalyzeOptions` field this config key normalizes into. */
@ -116,6 +119,13 @@ const KEY_SPECS: Record<string, KeySpec> = {
// built-in convention set, is otherwise invisible to route_map consumers.
// Listing it here adds it to the cross-file consumer scan.
fetchWrappers: { target: 'fetchWrappers', kind: 'string-array' },
// Go router types reached through an in-house wrapper package that are the
// gin/echo engine (`type Engine = gin.Engine`). The indexer cannot read the
// dependency's source, so the equivalence is declared, never guessed.
goRouterAliases: { target: 'routeFrameworkAliases', kind: 'router-aliases' },
// Go functions that wrap a route handler (`common.Wrapper(api.CreateJob)`);
// the wrapped first argument becomes the route's handler.
goHandlerWrappers: { target: 'routeHandlerWrappers', kind: 'string-array' },
// Explicit local Actuator snapshot input (#2418). The path itself is safe in
// project config; payload contents are never copied into the graph wholesale.
springActuator: { target: 'springActuator', kind: 'path' },
@ -301,6 +311,12 @@ const normalizeValue = (kind: ValueKind, value: unknown, key: string): unknown =
`${source} must be a boolean or a non-negative integer (node cap; 0 disables the cap).`,
);
}
case 'router-aliases':
try {
return normalizeRouterAliases(value, source);
} catch (error) {
throw new GitNexusRcError((error as Error).message);
}
default:
// Exhaustive — kept for forward-compat if a new kind is added.
throw new GitNexusRcError(`${source}: unsupported config value kind.`);
@ -356,11 +372,11 @@ export function loadAnalyzeConfig(repoRoot: string): Partial<AnalyzeOptions> | u
try {
raw = fs.readFileSync(filePath, 'utf-8');
} catch (err) {
if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return undefined;
if ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return withEnvConfig(undefined);
throw new GitNexusRcError(`Could not read ${GITNEXUS_RC_FILENAME}: ${(err as Error).message}`);
}
return parseAnalyzeConfig(raw);
return withEnvConfig(parseAnalyzeConfig(raw));
}
/** Load `.gitnexusrc` through the strict bounded reader used by watch mode. */
@ -373,7 +389,61 @@ export async function loadAnalyzeConfigStrict(
} catch (err) {
throw new GitNexusRcError(`Could not read ${GITNEXUS_RC_FILENAME}: ${(err as Error).message}`);
}
return raw === null ? undefined : parseAnalyzeConfig(raw);
return withEnvConfig(raw === null ? undefined : parseAnalyzeConfig(raw));
}
/** Environment variable naming an analyze config file kept outside the repository. */
export const GITNEXUS_RC_ENV = 'GITNEXUS_RC';
/**
* Layer the `GITNEXUS_RC` file over the repository's `.gitnexusrc`, key by key.
* It lets a checkout carry analyze config without a tracked or untracked file
* in the working tree. Being an explicit request, a relative path, a missing
* file, or an oversized file is an error rather than a silent no-op.
*/
function withEnvConfig(
repoConfig: Partial<AnalyzeOptions> | undefined,
): Partial<AnalyzeOptions> | undefined {
const envPath = process.env[GITNEXUS_RC_ENV]?.trim();
if (!envPath) return repoConfig;
const label = `${GITNEXUS_RC_ENV} file "${envPath}"`;
if (!path.isAbsolute(envPath)) {
throw new GitNexusRcError(`${GITNEXUS_RC_ENV} must be an absolute path (got "${envPath}").`);
}
let raw: string;
try {
// Check and read through one descriptor, so the file cannot be swapped
// between the type/size check and the read.
const fd = fs.openSync(envPath, 'r');
try {
const stat = fs.fstatSync(fd);
if (!stat.isFile()) throw new Error('not a regular file');
if (stat.size > MAX_REPO_CONTROL_FILE_BYTES) {
throw new Error(`larger than ${MAX_REPO_CONTROL_FILE_BYTES} bytes`);
}
raw = fs.readFileSync(fd, 'utf-8');
} finally {
fs.closeSync(fd);
}
// A file that grew after fstat is still bounded.
if (Buffer.byteLength(raw) > MAX_REPO_CONTROL_FILE_BYTES) {
throw new Error(`larger than ${MAX_REPO_CONTROL_FILE_BYTES} bytes`);
}
} catch (err) {
throw new GitNexusRcError(`Could not read ${label}: ${(err as Error).message}`);
}
let envConfig: Partial<AnalyzeOptions>;
try {
envConfig = parseAnalyzeConfig(raw);
} catch (err) {
if (err instanceof GitNexusRcError) throw new GitNexusRcError(`${label}: ${err.message}`);
throw err;
}
logger.debug(
{ file: envPath, keys: Object.keys(envConfig), repoKeys: Object.keys(repoConfig ?? {}) },
'analyze config: applied GITNEXUS_RC over .gitnexusrc',
);
return { ...repoConfig, ...envConfig };
}
function parseAnalyzeConfig(rawInput: string): Partial<AnalyzeOptions> {

View file

@ -14,6 +14,8 @@
* back the other way put the two files, plus `core/run-analyze.ts`, in an
* import cycle. `analyze.ts` re-exports the type for existing importers.
*/
import type { RouteFrameworkAlias } from '../core/ingestion/language-provider.js';
export interface AnalyzeOptions {
/** Keep this repository current with serialized incremental refreshes. */
watch?: boolean;
@ -147,6 +149,16 @@ export interface AnalyzeOptions {
* outside the built-in convention still produces `route_map` consumers.
*/
fetchWrappers?: string[];
/**
* Router types reached through a wrapper package that are a framework's
* router root. Supplied via `.gitnexusrc` / `GITNEXUS_RC` `goRouterAliases`.
*/
routeFrameworkAliases?: RouteFrameworkAlias[];
/**
* Handler-wrapper callees whose first argument is the route handler.
* Supplied via `.gitnexusrc` / `GITNEXUS_RC` `goHandlerWrappers`.
*/
routeHandlerWrappers?: string[];
/**
* Explicit local Spring Boot Actuator snapshot input (#2418). Accepts a JSON
* bundle or a directory containing endpoint JSON files. Disabled by default.

View file

@ -202,6 +202,10 @@ export async function resolveWatchOptions(
maxProcessTraceDepth: processDetection.maxProcessTraceDepth,
maxEntryPointCandidates: processDetection.maxEntryPointCandidates,
fetchWrappers: merged.fetchWrappers,
routeHookConfig: {
routeFrameworkAliases: merged.routeFrameworkAliases,
routeHandlerWrappers: merged.routeHandlerWrappers,
},
skipAgentsMd: true,
skipSkills: true,
noStats: true,

View file

@ -1589,6 +1589,10 @@ const analyzeCommandImpl = async (
// Extra fetch-wrapper names from `.gitnexusrc` (#1589/#1852 residual);
// forwarded to the routes phase consumer scan.
fetchWrappers: options.fetchWrappers,
routeHookConfig: {
routeFrameworkAliases: options.routeFrameworkAliases,
routeHandlerWrappers: options.routeHandlerWrappers,
},
springActuatorPath: options.springActuator,
asyncApiSpecPath: options.asyncapiSpec,
// The CLI always process.exit()s after this returns (success path at the

View file

@ -22,7 +22,7 @@ import type { ParsedImport, SymbolDefinition } from 'gitnexus-shared';
import { yieldToEventLoop } from './utils/event-loop.js';
import type { ExtractedRoute, ExtractedFetchCall } from './workers/parse-worker.js';
import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
import type { LanguageProvider } from './language-provider.js';
import type { LanguageProvider, RouteHookConfig } from './language-provider.js';
import { normalizeFetchURL, routeMatches } from './route-extractors/nextjs.js';
import {
isTestRouteFile,
@ -59,6 +59,8 @@ interface RouteHandlerResolutionContext {
) => readonly string[];
/** The route file's `LanguageProvider.resolveRouteHandler`, when it defines one. */
readonly providerRouteHandler?: (filePath: string) => LanguageProvider['resolveRouteHandler'];
/** User route configuration forwarded to provider handler hooks. */
readonly routeHookConfig?: RouteHookConfig;
readonly isExportedSymbol: (nodeId: string) => boolean;
/** 0-based graph-node startLine for same-name tRPC handler disambiguation. */
readonly nodeStartLine?: (nodeId: string) => number | undefined;
@ -559,7 +561,11 @@ export function resolveRouteHandlerSymbols(
return routeContext.resolveImportTargets(parsedImport, fromFile);
};
const providerContext = { model, importTargetsFor };
const providerContext = {
model,
importTargetsFor,
routeHookConfig: routeContext?.routeHookConfig,
};
const decoratorHandlerId = (dr: ExtractedDecoratorRoute): string | undefined => {
if (dr.source === DATA_ROUTE_TABLE_SOURCE) return dataHandlerByRoute.get(dr);
const providerHandler = routeContext?.providerRouteHandler?.(dr.filePath);

View file

@ -56,8 +56,28 @@ import type {
import type { ExtractedDecoratorRoute, ExtractedToolDef } from './workers/parse-worker.js';
import type { SemanticModel } from './model/semantic-model.js';
/**
* A declared router-framework equivalence: values of type `type` reached
* through `importPath` are the `framework`'s router root. Framework names are
* opaque here; the provider that owns the framework interprets them.
*/
export interface RouteFrameworkAlias {
readonly importPath: string;
readonly type: string;
readonly framework: string;
}
/** User route configuration handed to provider route hooks on the main thread. */
export interface RouteHookConfig {
/** Declared router-framework aliases; empty when none are configured. */
readonly routeFrameworkAliases?: readonly RouteFrameworkAlias[];
/** Callee designators (`pkg.Wrap`) whose first argument is the real handler. */
readonly routeHandlerWrappers?: readonly string[];
}
/** What a provider's {@link LanguageProviderConfig.resolveRouteHandler} can see. */
export interface RouteHandlerResolutionHookContext {
readonly routeHookConfig?: RouteHookConfig;
/** The model after every file has been parsed; scope resolution has not run. */
readonly model: SemanticModel;
/**
@ -647,6 +667,7 @@ interface LanguageProviderConfig {
readonly resolveRouteFacts?: (
files: readonly { filePath: string; facts: unknown }[],
context: {
readonly routeHookConfig?: RouteHookConfig;
resolveImportTargets: (fromFile: string, moduleSpecifier: string) => readonly string[];
},
) => ExtractedDecoratorRoute[];

View file

@ -25,8 +25,8 @@ import { createMethodExtractor } from '../method-extractors/generic.js';
import { goMethodConfig } from '../method-extractors/configs/go.js';
import { createVariableExtractor } from '../variable-extractors/generic.js';
import { goVariableConfig } from '../variable-extractors/configs/go.js';
import { extractGoGinEchoRoutes } from '../route-extractors/go-gin-echo.js';
import { resolveGoRouteHandler } from './go/route-handler.js';
import { extractGoRouteFacts, resolveGoRouteFacts } from './go/route-facts.js';
import { goPackageDir } from './go/package-clause.js';
import { createCallExtractor } from '../call-extractors/generic.js';
import { goCallConfig } from '../call-extractors/configs/go.js';
@ -162,9 +162,10 @@ export const goProvider = defineLanguage({
wrapperNodeTypes: ['type_declaration'],
}),
builtInNames: GO_BUILT_INS,
// gin / echo verb registrations with in-function Group prefixes (#3402).
extractDecoratorRoutes: extractGoGinEchoRoutes,
resolveRouteHandler: resolveGoRouteHandler,
// One config-free collection for direct engines and wrapper-package roots.
extractRouteFacts: extractGoRouteFacts,
resolveRouteFacts: resolveGoRouteFacts,
// ── RFC #909 Ring 3: scope-based resolution hooks ──────────
emitScopeCaptures: emitGoScopeCaptures,

View file

@ -0,0 +1,59 @@
import type { RouteFrameworkAlias } from '../../language-provider.js';
import { goRouteFramework } from '../../route-extractors/go-gin-echo.js';
const FIELDS = new Set(['importPath', 'type', 'framework']);
/** Upper bound on declared aliases; a longer list is rejected, never truncated. */
export const MAX_ROUTER_ALIASES = 100;
/** Validate the Go-owned alias syntax before analysis starts. */
export function normalizeRouterAliases(value: unknown, source: string): RouteFrameworkAlias[] {
if (!Array.isArray(value) || value.length === 0) {
throw new Error(`${source} must be a non-empty array of alias objects.`);
}
const out = new Map<string, RouteFrameworkAlias>();
for (const entry of value) {
if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
throw new Error(
`${source} entries must be objects like {"importPath": "...", "type": "Engine", "framework": "gin"}.`,
);
}
const record = entry as Record<string, unknown>;
for (const key of Object.keys(record)) {
if (!FIELDS.has(key)) throw new Error(`${source} entry has unknown field "${key}".`);
}
const field = (name: string, pattern: RegExp, hint: string): string => {
const raw = record[name];
if (typeof raw !== 'string' || !raw.trim()) {
throw new Error(`${source} entry field "${name}" must be a non-empty string.`);
}
const trimmed = raw.trim();
if (!pattern.test(trimmed)) throw new Error(`${source} entry field "${name}" ${hint}.`);
return trimmed;
};
const importPath = field(
'importPath',
/^[A-Za-z0-9._~-]+(\/[A-Za-z0-9._~-]+)*$/,
'must be a Go import path (e.g. "example.com/org/pkg")',
);
const type = field('type', /^[A-Za-z_][A-Za-z0-9_]*$/, 'must be a Go type name');
const framework = field('framework', /^[a-z]+$/, 'must be "gin" or "echo"');
if (!goRouteFramework(framework)) {
throw new Error(`${source} entry field "framework" must be "gin" or "echo".`);
}
const key = `${importPath}\u0000${type}`;
const previous = out.get(key);
if (previous && previous.framework !== framework) {
throw new Error(
`${source} declares ${importPath}.${type} as both "${previous.framework}" and "${framework}".`,
);
}
out.set(key, { importPath, type, framework });
}
if (out.size > MAX_ROUTER_ALIASES) {
throw new Error(
`${source} declares ${out.size} aliases; at most ${MAX_ROUTER_ALIASES} are allowed.`,
);
}
return [...out.values()];
}

View file

@ -0,0 +1,93 @@
import type Parser from 'tree-sitter';
import type { ParsedFile } from 'gitnexus-shared';
import { compareCodeUnits } from '../../../../lib/utils.js';
import { logger } from '../../../logger.js';
import type { LanguageProvider } from '../../language-provider.js';
import {
collectGoRouteFacts,
goRouteFramework,
materializeGoRoute,
type GoRouteCandidateFacts,
} from '../../route-extractors/go-gin-echo.js';
import type { ExtractedDecoratorRoute } from '../../workers/parse-worker.js';
/**
* Direct framework routes and registrations on a wrapper package's router
* (`func Init(s *core.Engine)`, where `core.Engine = gin.Engine` in a
* dependency the indexer cannot read).
*
* The worker records every such registration as a configuration-free
* candidate (`collectGoRouteFacts`), so the parse cache never depends on
* user config. Direct roots already identify their framework. Other roots
* become routes only when declared in `goRouterAliases` on the main thread.
*/
export const extractGoRouteFacts = (
tree: Parser.Tree,
_parsedFile: ParsedFile,
lineOffset: number,
): GoRouteCandidateFacts | undefined => collectGoRouteFacts(tree, lineOffset);
const isCandidateFacts = (facts: unknown): facts is GoRouteCandidateFacts =>
typeof facts === 'object' &&
facts !== null &&
Array.isArray((facts as GoRouteCandidateFacts).roots);
/** Root types logged in the "not configured" summary. */
const SUMMARY_LIMIT = 5;
export const resolveGoRouteFacts: NonNullable<LanguageProvider['resolveRouteFacts']> = (
files,
context,
) => {
const aliases = new Map<string, string>();
for (const alias of context.routeHookConfig?.routeFrameworkAliases ?? []) {
aliases.set(`${alias.importPath}\u0000${alias.type}`, alias.framework);
}
const out: ExtractedDecoratorRoute[] = [];
const emittedByRoot = new Map<string, number>();
const droppedByRoot = new Map<string, number>();
let candidates = 0;
for (const { filePath, facts } of files) {
if (!isCandidateFacts(facts)) continue;
for (const root of facts.roots) {
const rootKey = `${root.importPath}.${root.typeName}`;
const frameworkName =
root.framework ?? aliases.get(`${root.importPath}\u0000${root.typeName}`);
const framework = frameworkName && goRouteFramework(frameworkName);
if (!root.framework) candidates += root.routes.length;
if (!framework) {
droppedByRoot.set(rootKey, (droppedByRoot.get(rootKey) ?? 0) + root.routes.length);
continue;
}
if (!root.framework)
emittedByRoot.set(rootKey, (emittedByRoot.get(rootKey) ?? 0) + root.routes.length);
for (const candidate of root.routes) {
out.push(materializeGoRoute(filePath, candidate, framework));
}
}
}
for (const [rootKey, count] of emittedByRoot) {
logger.debug(
{ rootType: rootKey, routes: count },
'go routes: emitted routes through a configured router alias',
);
}
if (droppedByRoot.size > 0) {
const top = [...droppedByRoot.entries()]
.sort((a, b) => b[1] - a[1] || compareCodeUnits(a[0], b[0]))
.slice(0, SUMMARY_LIMIT)
.map(([rootType, dropped]) => ({ rootType, dropped }));
logger.info(
{
candidates,
emitted: [...emittedByRoot.values()].reduce((sum, count) => sum + count, 0),
unconfiguredRootTypes: droppedByRoot.size,
top,
},
'go routes: dropped verb registrations on unconfigured router types; if one is a ' +
'gin/echo engine alias, declare it in goRouterAliases',
);
}
return out;
};

View file

@ -2,6 +2,7 @@ import type { SymbolDefinition } from 'gitnexus-shared';
import type { RouteHandlerResolutionHookContext } from '../../language-provider.js';
import type { SemanticModel } from '../../model/semantic-model.js';
import type { ExtractedDecoratorRoute } from '../../workers/parse-worker.js';
import { logger } from '../../../logger.js';
import { goPackageDir } from './package-clause.js';
/**
@ -22,6 +23,8 @@ export function resolveGoRouteHandler(
route: ExtractedDecoratorRoute,
context: RouteHandlerResolutionHookContext,
): string | undefined {
const unwrapped = unwrapConfiguredHandler(route, context);
if (unwrapped !== route) return unwrapped && resolveGoRouteHandler(unwrapped, context);
const designator = route.handlerName;
if (!designator) return undefined;
const parts = designator.split('.');
@ -47,6 +50,43 @@ export function resolveGoRouteHandler(
: undefined;
}
/** Wrapper callees already reported as unconfigured, so the debug line fires once each. */
const reportedWrappers = new WeakMap<RouteHandlerResolutionHookContext, Set<string>>();
/**
* A route whose handler slot was `wrap(inner)`: the route re-addressed to
* `inner` when `wrap` is a configured handler wrapper, `undefined` when it is
* not, and the route itself when nothing was wrapped.
*/
function unwrapConfiguredHandler(
route: ExtractedDecoratorRoute,
context: RouteHandlerResolutionHookContext,
): ExtractedDecoratorRoute | undefined {
const wrapper = route.handlerWrapper;
if (route.handlerName || !wrapper) return route;
if (context.routeHookConfig?.routeHandlerWrappers?.includes(wrapper.callee)) {
return {
...route,
handlerName: wrapper.handlerName,
handlerReceiver: wrapper.handlerReceiver,
handlerWrapper: undefined,
};
}
let reported = reportedWrappers.get(context);
if (!reported) {
reported = new Set();
reportedWrappers.set(context, reported);
}
if (!reported.has(wrapper.callee)) {
reported.add(wrapper.callee);
logger.debug(
{ callee: wrapper.callee, file: route.filePath, line: route.lineNumber },
'go routes: handler is wrapped by an unconfigured function; add it to goHandlerWrappers to resolve it',
);
}
return undefined;
}
type DefinitionBuckets = Map<string, SymbolDefinition[]>;
type PackageIndex = Map<string, DefinitionBuckets>;
const bucketKey = (dir: string, name: string): string => JSON.stringify([dir, name]);

View file

@ -1620,6 +1620,11 @@ export async function runChunkedParseAndResolve(
allFetchWrapperDefs = resolvedFetchWrappers.definitions;
allFetchWrapperCalls = resolvedFetchWrappers.calls;
// User route configuration is applied here, on the main thread: workers only
// emit configuration-free candidates, so a config change never stales the
// parse cache.
const routeHookConfig = options?.routeHookConfig;
// A resolver's identity defines a fact family, including providers sharing
// one language implementation. Shared ingestion never inspects the payload.
const routeFactGroups = new Map<
@ -1635,7 +1640,10 @@ export async function runChunkedParseAndResolve(
}
const resolvedRoutesByFile = new Map<string, ExtractedDecoratorRoute[]>();
for (const [resolve, files] of routeFactGroups) {
for (const route of resolve(files, { resolveImportTargets: resolveRouteModuleTargets })) {
for (const route of resolve(files, {
resolveImportTargets: resolveRouteModuleTargets,
routeHookConfig,
})) {
const routes = resolvedRoutesByFile.get(route.filePath) ?? [];
routes.push(route);
resolvedRoutesByFile.set(route.filePath, routes);
@ -2023,6 +2031,7 @@ export async function runChunkedParseAndResolve(
resolveImportTarget: resolveRouteImportTarget,
resolveImportTargets: resolveRouteImportTargets,
providerRouteHandler: (filePath) => getProviderForFile(filePath)?.resolveRouteHandler,
routeHookConfig,
isExportedSymbol: (nodeId: string) => graph.getNode(nodeId)?.properties.isExported === true,
nodeStartLine: (id) => {
const n = graph.getNode(id);

View file

@ -17,6 +17,7 @@
import { createKnowledgeGraph } from '../graph/graph.js';
import type { KnowledgeGraph } from '../graph/types.js';
import type { RouteHookConfig } from './language-provider.js';
import { GLOBAL_NAME_FALLBACK_REASON } from '../graph/edge-reasons.js';
import { GraphEmitSink, type GraphEmitManifest } from '../lbug/graph-emit-sink.js';
import { type PipelineProgress } from 'gitnexus-shared';
@ -307,6 +308,13 @@ export interface PipelineOptions {
* traced. Empty/undefined leaves behavior unchanged.
*/
fetchWrappers?: readonly string[];
/**
* Declared router-framework aliases and handler-wrapper callees, threaded
* from `.gitnexusrc` / `GITNEXUS_RC`. Applied on the main thread by the
* provider route hooks — never sent to parse workers, so they never enter a
* parse-cache key. Empty/undefined leaves route extraction unchanged.
*/
routeHookConfig?: RouteHookConfig;
}
// ── Phase registry ─────────────────────────────────────────────────────────

View file

@ -45,9 +45,8 @@ const VERBS: ReadonlySet<string> = new Set([
]);
interface Framework {
readonly name: 'gin' | 'echo';
readonly source: string;
/** Import local name of the framework package. */
readonly alias: string;
/** Engine type name reached through the alias (`gin.Engine`, `echo.Echo`). */
readonly engineType: string;
/** Engine constructors reached through the alias. */
@ -56,13 +55,38 @@ interface Framework {
readonly handlerArg: 'last' | 'second';
}
const FRAMEWORKS: Readonly<Record<Framework['name'], Framework>> = {
gin: {
name: 'gin',
source: GIN_ROUTE_SOURCE,
engineType: 'Engine',
constructors: new Set(['Default', 'New']),
handlerArg: 'last',
},
echo: {
name: 'echo',
source: ECHO_ROUTE_SOURCE,
engineType: 'Echo',
constructors: new Set(['New']),
handlerArg: 'second',
},
};
export const goRouteFramework = (name: string): Framework | undefined =>
Object.hasOwn(FRAMEWORKS, name) ? FRAMEWORKS[name as Framework['name']] : undefined;
type ImportedFramework = Framework & { readonly alias: string; readonly importPath: string };
const FUNCTION_TYPE_LIST = ['function_declaration', 'method_declaration', 'func_literal'];
const FUNCTION_TYPES: ReadonlySet<string> = new Set(FUNCTION_TYPE_LIST);
/** The framework this file routes with, when exactly one is imported. */
function readImports(root: SyntaxNode): {
readonly framework: Framework | null;
readonly framework: ImportedFramework | null;
/** Every qualifier this file can call through, local name → import path. */
readonly imports: ReadonlyMap<string, string>;
} {
const imports = new Map<string, string>();
let gin: string | null = null;
let echo: string | null = null;
// Imports sit only at file scope; this runs on every Go file, so skip bodies.
@ -77,33 +101,24 @@ function readImports(root: SyntaxNode): {
if (explicit === '_' || explicit === '.') continue;
const local = explicit ?? goImportPackageName(importPath);
if (!local) continue;
imports.set(local, importPath);
if (isGinImportPath(importPath)) gin = local;
if (isEchoImportPath(importPath)) echo = local;
}
// Both, or neither: no way to tell which argument is the handler.
if (gin !== null && echo === null) {
return {
framework: {
source: GIN_ROUTE_SOURCE,
alias: gin,
engineType: 'Engine',
constructors: new Set(['Default', 'New']),
handlerArg: 'last',
},
imports,
framework: { ...FRAMEWORKS.gin, alias: gin, importPath: imports.get(gin)! },
};
}
if (echo !== null && gin === null) {
return {
framework: {
source: ECHO_ROUTE_SOURCE,
alias: echo,
engineType: 'Echo',
constructors: new Set(['New']),
handlerArg: 'second',
},
imports,
framework: { ...FRAMEWORKS.echo, alias: echo, importPath: imports.get(echo)! },
};
}
return { framework: null };
return { imports, framework: null };
}
/** Named descendants of a function body, not descending into nested functions. */
@ -169,18 +184,30 @@ function valueHint(value: SyntaxNode, bindings: GoRouteBindings): RouteHandlerRe
const sameHint = (a: RouteHandlerReceiver, b: RouteHandlerReceiver): boolean =>
a.kind === b.kind && a.name === b.name && a.qualifier === b.qualifier;
interface RouterRoot {
readonly importPath: string;
readonly typeName: string;
readonly framework?: Framework['name'];
}
interface RouterPrefix {
readonly root: RouterRoot;
readonly path: string;
}
class RouterPrefixes {
private readonly memo = new Map<GoRouteBinding, string | null>();
private readonly memo = new Map<GoRouteBinding, RouterPrefix | null>();
private readonly visiting = new Set<GoRouteBinding>();
constructor(
private readonly bindings: GoRouteBindings,
private readonly fw: Framework,
private readonly roots: ReadonlyMap<string, RouterRoot>,
private readonly framework: ImportedFramework | null,
private readonly fn: SyntaxNode,
) {}
/** Proven prefix of a router expression, or null when it cannot be proven. */
of(node: SyntaxNode): string | null {
of(node: SyntaxNode): RouterPrefix | null {
if (node.type === 'parenthesized_expression') {
const inner = node.namedChild(0);
return inner ? this.of(inner) : null;
@ -197,19 +224,22 @@ class RouterPrefixes {
if (!operand || !field) return null;
if (
operand.type === 'identifier' &&
operand.text === this.fw.alias &&
operand.text === this.framework?.alias &&
!this.bindings.lookup(operand)
) {
return this.fw.constructors.has(field) ? '' : null;
const root = this.roots.get(`${this.framework.alias}.${this.framework.engineType}`);
return root && this.framework.constructors.has(field) ? { root, path: '' } : null;
}
if (field !== 'Group') return null;
const path = stringLiteral(node.childForFieldName('arguments')?.namedChild(0));
if (path === null) return null;
const base = this.of(operand);
return base === null ? null : normalizeExtractedRoutePath(path, base);
return base === null
? null
: { root: base.root, path: normalizeExtractedRoutePath(path, base.path) };
}
private ofBinding(binding: GoRouteBinding): string | null {
private ofBinding(binding: GoRouteBinding): RouterPrefix | null {
// Captured routers remain outside this extractor's supported route forms.
if (binding.ownerFunction.id !== this.fn.id || binding.capturedWrite) return null;
const cached = this.memo.get(binding);
@ -217,20 +247,23 @@ class RouterPrefixes {
if (this.visiting.has(binding)) return null;
this.visiting.add(binding);
const hint = typeHint(binding.type, this.bindings);
const candidates: (string | null)[] = [];
if (
binding.isInputParameter &&
hint?.kind === 'type' &&
hint.qualifier === this.fw.alias &&
hint.name === this.fw.engineType
) {
candidates.push('');
const root =
hint?.kind === 'type' ? this.roots.get(`${hint.qualifier}.${hint.name}`) : undefined;
const candidates: (RouterPrefix | null)[] = [];
if (binding.isInputParameter && root) {
candidates.push({ root, path: '' });
} else if (binding.isInputParameter || binding.values.length === 0) {
candidates.push(null);
}
for (const value of binding.values) candidates.push(value === null ? null : this.of(value));
const first = candidates[0] ?? null;
const result = candidates.every((candidate) => candidate === first) ? first : null;
const result =
first &&
candidates.every(
(candidate) => candidate?.root === first.root && candidate.path === first.path,
)
? first
: null;
this.visiting.delete(binding);
this.memo.set(binding, result);
return result;
@ -283,58 +316,245 @@ function verbRegistration(call: SyntaxNode): VerbRegistration | null {
return path === null ? null : { call, verb, receiver, args, path };
}
/** The handler a registration names, read from one argument of the verb call. */
export interface GoRouteHandlerFact {
handlerName?: string;
handlerReceiver?: RouteHandlerReceiver;
/**
* `wrap(inner, …)` in the handler slot: the call's callee designator and the
* inner argument's handler. Only a configured wrapper is unwrapped (by the Go
* provider's `resolveRouteHandler`); the worker never decides that.
*/
handlerWrapper?: { callee: string; handlerName: string; handlerReceiver?: RouteHandlerReceiver };
}
/** A handler designator: a bare package function or a `x.Member` selector. */
function handlerDesignator(
node: SyntaxNode,
bindings: GoRouteBindings,
hints: Map<GoRouteBinding, RouteHandlerReceiver | undefined>,
): { handlerName: string; handlerReceiver?: RouteHandlerReceiver } | undefined {
if (node.type === 'identifier') {
return bindings.lookup(node) ? undefined : { handlerName: node.text };
}
if (node.type !== 'selector_expression') return undefined;
const operand = node.childForFieldName('operand');
const field = node.childForFieldName('field');
if (operand?.type !== 'identifier' || !field) return undefined;
const hint = receiverHint(operand, bindings, hints);
return hint
? { handlerName: `${operand.text}.${field.text}`, handlerReceiver: hint }
: { handlerName: `${operand.text}.${field.text}` };
}
/** `pkg.Wrap(h.Method, …)` / `Wrap(Func)` — a package-level callee wrapping a designator. */
function wrappedHandler(
node: SyntaxNode,
bindings: GoRouteBindings,
hints: Map<GoRouteBinding, RouteHandlerReceiver | undefined>,
): GoRouteHandlerFact['handlerWrapper'] {
if (node.type !== 'call_expression') return undefined;
const callee = node.childForFieldName('function');
if (!callee) return undefined;
if (callee.type === 'identifier') {
if (bindings.lookup(callee)) return undefined;
} else if (callee.type === 'selector_expression') {
const operand = callee.childForFieldName('operand');
// A local value's method (`m.Wrap`) has no stable designator to configure.
if (operand?.type !== 'identifier' || bindings.lookup(operand)) return undefined;
} else {
return undefined;
}
const inner = node.childForFieldName('arguments')?.namedChildren[0];
const designator = inner ? handlerDesignator(inner, bindings, hints) : undefined;
return designator ? { callee: callee.text, ...designator } : undefined;
}
function handlerFact(
node: SyntaxNode,
bindings: GoRouteBindings,
hints: Map<GoRouteBinding, RouteHandlerReceiver | undefined>,
): GoRouteHandlerFact {
const designator = handlerDesignator(node, bindings, hints);
if (designator) return designator;
const handlerWrapper = wrappedHandler(node, bindings, hints);
return handlerWrapper ? { handlerWrapper } : {};
}
/** Verb registrations of every function that has some, with the file's bindings. */
function* functionRegistrations(
root: SyntaxNode,
framework: ImportedFramework | null,
imports: ReadonlyMap<string, string>,
): Generator<{ fn: SyntaxNode; registrations: VerbRegistration[]; bindings: GoRouteBindings }> {
let bindings: GoRouteBindings | undefined;
for (const fn of root.descendantsOfType(FUNCTION_TYPE_LIST)) {
// Without a framework constructor, only imported parameter types can be
// router roots. Avoid walking ordinary Go function bodies in that case.
if (
!framework &&
!fn
.childForFieldName('parameters')
?.descendantsOfType('qualified_type')
.some((type) => imports.has(type.childForFieldName('package')?.text ?? ''))
)
continue;
const body = fn.childForFieldName('body');
if (!body) continue;
const registrations = bodyNodes(body).flatMap((node) => {
const registration = verbRegistration(node);
return registration === null ? [] : [registration];
});
// Most functions register nothing; skip their bindings.
if (registrations.length === 0) continue;
bindings ??= new GoRouteBindings(root);
yield { fn, registrations, bindings };
}
}
export function extractGoGinEchoRoutes(
tree: Parser.Tree,
filePath: string,
lineOffset = 0,
): ExtractedDecoratorRoute[] {
const root = tree.rootNode;
const { framework } = readImports(root);
if (framework === null) return [];
return (collectGoRouteFacts(tree, lineOffset)?.roots ?? []).flatMap((root) => {
const framework = root.framework && goRouteFramework(root.framework);
return framework
? root.routes.map((route) => materializeGoRoute(filePath, route, framework))
: [];
});
}
const out: ExtractedDecoratorRoute[] = [];
const handlerHints = new Map<GoRouteBinding, RouteHandlerReceiver | undefined>();
let bindings: GoRouteBindings | undefined;
for (const fn of root.descendantsOfType(FUNCTION_TYPE_LIST)) {
const body = fn.childForFieldName('body');
if (!body) continue;
const nodes = bodyNodes(body);
const registrations = nodes.flatMap((node) => {
const registration = verbRegistration(node);
return registration === null ? [] : [registration];
/** One verb registration whose router root is a parameter of a wrapper-package type. */
export interface GoRouteCandidate {
readonly routePath: string;
readonly httpMethod: string;
readonly lineNumber: number;
/** Second and last handler arguments; one entry when they are the same slot. */
readonly handlers: readonly [GoRouteHandlerFact, GoRouteHandlerFact?];
}
/**
* Route candidates of one file, grouped by the root parameter's declared type.
* The worker cannot tell whether `pkg.T` is a gin/echo engine (that is user
* configuration, applied on the main thread), so it records registrations
* under each proven root type. Direct roots carry their known framework;
* other roots need configuration before their registrations become routes.
*/
export interface GoRouteCandidateFacts {
readonly roots: readonly (RouterRoot & {
readonly routes: readonly GoRouteCandidate[];
})[];
}
export function materializeGoRoute(
filePath: string,
candidate: GoRouteCandidate,
framework: Framework,
): ExtractedDecoratorRoute {
return {
filePath,
routePath: candidate.routePath,
httpMethod: candidate.httpMethod,
decoratorName: candidate.httpMethod,
lineNumber: candidate.lineNumber,
prefix: null,
source: framework.source,
...candidate.handlers[framework.handlerArg === 'last' ? candidate.handlers.length - 1 : 0],
};
}
/** `*Q.T` / `Q.T` parameters of `fn`, where `Q` is an import of this file. */
function importedRootTypes(
fn: SyntaxNode,
bindings: GoRouteBindings,
imports: ReadonlyMap<string, string>,
): { importPath: string; qualifier: string; typeName: string }[] {
const out = new Map<string, { importPath: string; qualifier: string; typeName: string }>();
const parameters = fn.childForFieldName('parameters');
for (const declaration of parameters?.namedChildren ?? []) {
if (declaration.type !== 'parameter_declaration') continue;
const hint = typeHint(declaration.childForFieldName('type'), bindings);
if (hint?.kind !== 'type' || !hint.qualifier || !hint.name) continue;
const importPath = imports.get(hint.qualifier);
// Framework packages are the direct extractor's job, not a candidate.
if (!importPath || isGinImportPath(importPath) || isEchoImportPath(importPath)) continue;
out.set(`${hint.qualifier}.${hint.name}`, {
importPath,
qualifier: hint.qualifier,
typeName: hint.name,
});
// Most functions in a gin-importing file register nothing; skip their bindings.
if (registrations.length === 0) continue;
bindings ??= new GoRouteBindings(root);
const prefixes = new RouterPrefixes(bindings, framework, fn);
}
return [...out.values()];
}
export function extractGoRouteCandidates(
tree: Parser.Tree,
lineOffset = 0,
): GoRouteCandidateFacts | undefined {
const roots = collectGoRouteFacts(tree, lineOffset)?.roots.filter((root) => !root.framework);
return roots?.length ? { roots } : undefined;
}
/** One config-free pass for both framework engines and configured aliases. */
export function collectGoRouteFacts(
tree: Parser.Tree,
lineOffset = 0,
): GoRouteCandidateFacts | undefined {
const root = tree.rootNode;
const { imports, framework } = readImports(root);
if (imports.size === 0) return undefined;
const directRoot: RouterRoot | undefined = framework
? {
importPath: framework.importPath,
typeName: framework.engineType,
framework: framework.name,
}
: undefined;
const directRoutes: GoRouteCandidate[] = [];
const byRoot = new Map<string, RouterRoot & { routes: GoRouteCandidate[] }>();
const handlerHints = new Map<GoRouteBinding, RouteHandlerReceiver | undefined>();
for (const { fn, registrations, bindings } of functionRegistrations(root, framework, imports)) {
const roots = new Map<string, RouterRoot>();
if (framework && directRoot)
roots.set(`${framework.alias}.${framework.engineType}`, directRoot);
for (const rootType of importedRootTypes(fn, bindings, imports)) {
roots.set(`${rootType.qualifier}.${rootType.typeName}`, {
importPath: rootType.importPath,
typeName: rootType.typeName,
});
}
const prefixes = new RouterPrefixes(bindings, roots, framework, fn);
const routesByRoot = new Map<RouterRoot, GoRouteCandidate[]>();
for (const { call, verb, receiver, args, path } of registrations) {
const prefix = prefixes.of(receiver);
if (prefix === null) continue;
const handler = framework.handlerArg === 'last' ? args[args.length - 1] : args[1];
const route: ExtractedDecoratorRoute = {
filePath,
routePath: normalizeExtractedRoutePath(path, prefix),
const last = handlerFact(args[args.length - 1], bindings, handlerHints);
const routes = routesByRoot.get(prefix.root) ?? [];
routes.push({
routePath: normalizeExtractedRoutePath(path, prefix.path),
httpMethod: verb,
decoratorName: verb,
lineNumber: call.startPosition.row + 1 + lineOffset,
prefix: null,
source: framework.source,
};
if (handler.type === 'identifier' && !bindings.lookup(handler)) {
route.handlerName = handler.text;
} else if (handler.type === 'selector_expression') {
const operand = handler.childForFieldName('operand');
const field = handler.childForFieldName('field');
if (operand?.type === 'identifier' && field) {
route.handlerName = `${operand.text}.${field.text}`;
const hint = receiverHint(operand, bindings, handlerHints);
if (hint) route.handlerReceiver = hint;
}
handlers: args.length === 2 ? [last] : [handlerFact(args[1], bindings, handlerHints), last],
});
routesByRoot.set(prefix.root, routes);
}
// Preserve parameter-type ordering when duplicate URLs compete.
for (const rootType of roots.values()) {
const routes = routesByRoot.get(rootType);
if (!routes) continue;
if (rootType === directRoot) {
directRoutes.push(...routes);
continue;
}
out.push(route);
const key = `${rootType.importPath}\u0000${rootType.typeName}`;
const group = byRoot.get(key);
if (group) group.routes.push(...routes);
else byRoot.set(key, { ...rootType, routes });
}
}
return out;
const roots = [...byRoot.values()];
// The parse dispatcher inserted configured facts before direct routes.
if (directRoot && directRoutes.length) roots.push({ ...directRoot, routes: directRoutes });
return roots.length ? { roots } : undefined;
}

View file

@ -0,0 +1,16 @@
import { compareCodeUnits } from '../../lib/utils.js';
import type { RouteHookConfig } from './language-provider.js';
/**
* Stable metadata value for the declared route configuration. Sorting makes
* equivalent lists independent of declaration order; no config is `[[],[]]`.
*/
export function routeHookConfigKey(config?: RouteHookConfig): string {
const aliasKeys = (config?.routeFrameworkAliases ?? [])
.map((alias) => [alias.importPath, alias.type, alias.framework])
.sort((a, b) => compareCodeUnits(a.join('\u0000'), b.join('\u0000')));
return JSON.stringify([
aliasKeys,
[...new Set(config?.routeHandlerWrappers)].sort(compareCodeUnits),
]);
}

View file

@ -424,6 +424,18 @@ export interface ExtractedDecoratorRoute {
* `LanguageProvider.resolveRouteHandler`; absent when nothing was inferred.
*/
handlerReceiver?: RouteHandlerReceiver;
/**
* The handler slot held a call `callee(inner, …)` instead of a designator.
* `callee` is the call's designator as written (`common.Wrapper`); the inner
* argument's designator and receiver hint travel alongside. A provider uses
* it only when the user configured `callee` as a handler wrapper; otherwise
* the route keeps no handler, as before.
*/
handlerWrapper?: {
callee: string;
handlerName: string;
handlerReceiver?: RouteHandlerReceiver;
};
/**
* Provenance for the `HANDLES_ROUTE` edge, overriding the default
* `decorator-<decoratorName>`. Present when the route was extracted from a

View file

@ -28,6 +28,7 @@ export const REBUILD_REASON_KEYS = [
'graph-write-collapse',
'analysis-features',
'spring-vendor-prefixes',
'route-hook-config',
'runner-identity',
'parser-identity',
'cjk-segmentation',

View file

@ -51,6 +51,8 @@ import {
countCallsByLanguage,
} from './ingestion/scope-resolution/name-fallback-summary.js';
import { runPipelineFromRepo } from './ingestion/pipeline.js';
import type { RouteHookConfig } from './ingestion/language-provider.js';
import { routeHookConfigKey } from './ingestion/route-hook-config.js';
import {
logUnresolvedReceiverFiles,
summarizeUnresolvedReceivers,
@ -625,6 +627,11 @@ export interface AnalyzeOptions {
* consumer scan unchanged.
*/
fetchWrappers?: string[];
/**
* Declared router-framework aliases and handler-wrapper callees, forwarded to
* `PipelineOptions` and stamped into meta so a changed value rebuilds Routes.
*/
routeHookConfig?: RouteHookConfig;
/**
* Explicit local Spring Boot Actuator snapshot input (#2418), forwarded to
* the Spring enrichment phase. Undefined keeps static-only analysis.
@ -2359,6 +2366,23 @@ async function runFullAnalysisInner(
});
}
// Declared route aliases / handler wrappers change Route evidence without
// moving the commit or dirtying the tree, so a changed value must rebuild.
const currentRouteHookConfig = routeHookConfigKey(options.routeHookConfig);
const persistedRouteHookConfig = existingMeta?.routeHookConfig ?? routeHookConfigKey();
if (existingMeta && persistedRouteHookConfig !== currentRouteHookConfig) {
if (currentRouteHookConfig === routeHookConfigKey()) {
log(
'Warning: route aliases / handler wrappers used by the previous index are no longer ' +
'configured (was GITNEXUS_RC unset?) — Routes they produced will be removed.',
);
}
addGateReason({
key: 'route-hook-config',
text: 'route aliases or handler wrappers changed — persisted Route evidence will be rebuilt.',
});
}
const currentSpringVendorPrefixes = springVendorPrefixesKey();
const persistedRouteBindings = existingMeta?.analysisFeatures?.[SPRING_ROUTE_BINDINGS_FEATURE.id];
if (
@ -3106,6 +3130,7 @@ async function runFullAnalysisInner(
? resolveNativeSafeStorageDir(storagePath, 'graph-csv')
: undefined,
fetchWrappers: options.fetchWrappers,
routeHookConfig: options.routeHookConfig,
skipDerivedGraphPhases,
springActuatorPath: options.springActuatorPath,
asyncApiSpecPath: options.asyncApiSpecPath,
@ -5380,6 +5405,7 @@ async function runFullAnalysisInner(
: summarizeUndecidedSatisfaction(pipelineResult.undecidedSatisfaction),
analysisFeatures: currentAnalysisFeatures,
springVendorPrefixes: currentSpringVendorPrefixes,
routeHookConfig: currentRouteHookConfig,
// Always stamped with the live resolved mode (#2331/#2339) — unlike
// `pdg` below, 'none' is a meaningful value to compare, not an
// absence, so this is never conditionally omitted.

View file

@ -285,6 +285,11 @@ export interface RepoMeta {
* annotations. A changed value invalidates persisted JVM Route evidence.
*/
springVendorPrefixes?: string;
/**
* Canonical declared route aliases + handler wrappers (`goRouterAliases`,
* `goHandlerWrappers`). A changed value invalidates persisted Route evidence.
*/
routeHookConfig?: string;
/**
* The resolved GITNEXUS_FTS_CJK_SEGMENTATION mode ('none' | 'bigram') the
* existing index's content/description columns were last written under

View file

@ -0,0 +1,19 @@
package api
import (
"github.com/gin-gonic/gin"
"example.com/wrappedapp/service"
)
// API holds the console handlers.
type API struct{ svc *service.Jobs }
// CreateJob creates a job.
func (a *API) CreateJob(c *gin.Context) (interface{}, error) { return a.svc.Create(), nil }
// JobStatus reports a job's status.
func (a *API) JobStatus(c *gin.Context) (interface{}, error) { return nil, nil }
// UserInfo is a plain gin handler.
func UserInfo(c *gin.Context) {}

View file

@ -0,0 +1,19 @@
package common
import "github.com/gin-gonic/gin"
// HandlerFunc is the application handler shape the wrappers adapt.
type HandlerFunc func(c *gin.Context) (interface{}, error)
// Wrapper adapts an application handler to gin.
func Wrapper(handler HandlerFunc) func(c *gin.Context) {
return WrapperWithSuccessCode(handler, "0")
}
// WrapperWithSuccessCode adapts a handler using the given success code.
func WrapperWithSuccessCode(handler HandlerFunc, code string) func(c *gin.Context) {
return func(c *gin.Context) { _, _ = handler(c) }
}
// Auth is middleware, not a handler wrapper.
func Auth() func(c *gin.Context) { return func(c *gin.Context) {} }

View file

@ -0,0 +1,8 @@
module example.com/wrappedapp
go 1.22
require (
example.com/infra v1.0.0
github.com/gin-gonic/gin v1.10.0
)

View file

@ -0,0 +1,18 @@
package routes
import (
consoleApi "example.com/wrappedapp/api"
"example.com/wrappedapp/common"
core "example.com/infra/pkg"
)
// InitRoute registers every route on the wrapper package's engine alias.
func InitRoute(s *core.Engine, api *consoleApi.API) {
v1 := s.Group("/console/v1")
{
jobs := v1.Group("/jobs")
jobs.POST("/create", common.Wrapper(api.CreateJob))
jobs.GET("/status", common.Auth(), common.WrapperWithSuccessCode(api.JobStatus, "OK"))
jobs.GET("/userinfo", consoleApi.UserInfo)
}
}

View file

@ -0,0 +1,7 @@
package service
// Jobs is the job service.
type Jobs struct{}
// Create creates a job.
func (j *Jobs) Create() string { return "job" }

View file

@ -0,0 +1,162 @@
/**
* Routes registered on a wrapper package's engine alias (`*core.Engine`, where
* the dependency declares `type Engine = gin.Engine`) with handlers wrapped by
* an application adapter (`common.Wrapper(api.CreateJob)`).
*
* Neither fact is provable from the repository: the dependency's source is not
* vendored, and a call in the handler slot may be middleware. Both are user
* configuration (`goRouterAliases`, `goHandlerWrappers`), applied on the main
* thread — so the same parse output yields no routes without it.
*
* Fixture: `test/fixtures/go-wrapped-gin-route-app/`.
*/
import { describe, it, expect, beforeAll } from 'vitest';
import path from 'node:path';
import fs from 'node:fs/promises';
import os from 'node:os';
import { runPipelineFromRepo } from '../../src/core/ingestion/pipeline.js';
import type { PipelineResult } from '../../src/types/pipeline.js';
import { loadParseCache, saveParseCache } from '../../src/storage/parse-cache.js';
import { runtimeParseIdentity } from '../helpers/runtime-parse-identity.js';
import {
clearParsedFileStore,
getDurableParsedFileDir,
pruneAndSaveDurableParsedFileStore,
} from '../../src/storage/parsedfile-store.js';
const FIXTURE = path.resolve(__dirname, '..', 'fixtures', 'go-wrapped-gin-route-app');
const routeView = (result: PipelineResult): string[] => {
const out: string[] = [];
result.graph.forEachNode((node) => {
if (node.label !== 'Route') return;
const handler = result.graph.getNode(String(node.properties.handlerSymbolId));
out.push(
`${String(node.properties.method)} ${String(node.properties.name)} -> ${String(
handler?.properties.name,
)}`,
);
});
return out.sort();
};
describe('wrapper-package gin route ingestion', () => {
let configured: PipelineResult;
let unconfigured: PipelineResult;
beforeAll(async () => {
[configured, unconfigured] = await Promise.all([
runPipelineFromRepo(FIXTURE, () => {}, {
routeHookConfig: {
routeFrameworkAliases: [
{ importPath: 'example.com/infra/pkg', type: 'Engine', framework: 'gin' },
],
routeHandlerWrappers: ['common.Wrapper', 'common.WrapperWithSuccessCode'],
},
}),
runPipelineFromRepo(FIXTURE, () => {}, {}),
]);
}, 300_000);
it('emits prefixed routes and resolves wrapped handlers when configured', () => {
expect(routeView(configured)).toEqual([
'GET /console/v1/jobs/status -> JobStatus',
'GET /console/v1/jobs/userinfo -> UserInfo',
'POST /console/v1/jobs/create -> CreateJob',
]);
});
it('draws HANDLES_ROUTE from the wrapped method with gin provenance', () => {
let edge: { handler: unknown; reason: unknown } | undefined;
configured.graph.forEachRelationship((rel) => {
if (rel.type === 'HANDLES_ROUTE' && rel.targetId === 'Route:POST /console/v1/jobs/create') {
edge = {
handler: configured.graph.getNode(rel.sourceId)?.properties.name,
reason: rel.reason,
};
}
});
expect(edge).toEqual({ handler: 'CreateJob', reason: 'gin-route' });
});
it('emits no route without the alias configuration', () => {
expect(routeView(unconfigured)).toEqual([]);
});
it('preserves the configured route winner when a direct route declares the same URL', async () => {
const repo = await fs.mkdtemp(path.join(os.tmpdir(), 'go-route-collision-'));
try {
await fs.writeFile(path.join(repo, 'go.mod'), 'module example.com/collision\n\ngo 1.22\n');
await fs.writeFile(
path.join(repo, 'routes.go'),
`package routes
import "github.com/gin-gonic/gin"
import core "example.com/infra/pkg"
func Direct(c *gin.Context) {}
func Aliased(c *gin.Context) {}
func R(r *gin.Engine, s *core.Engine) {
r.GET("/same", Direct)
s.GET("/same", Aliased)
}`,
);
const result = await runPipelineFromRepo(repo, () => {}, {
routeHookConfig: {
routeFrameworkAliases: [
{ importPath: 'example.com/infra/pkg', type: 'Engine', framework: 'gin' },
],
},
});
expect(routeView(result)).toEqual(['GET /same -> Aliased']);
} finally {
await fs.rm(repo, { recursive: true, force: true });
}
}, 300_000);
it('applies alias and wrapper changes to persisted worker facts without reparsing', async () => {
const storage = await fs.mkdtemp(path.join(os.tmpdir(), 'go-route-facts-cache-'));
try {
const identity = await runtimeParseIdentity();
const cache = await loadParseCache(storage, identity, storage);
const cold = await runPipelineFromRepo(FIXTURE, () => {}, {
parseCache: cache,
workerPoolSize: 1,
});
expect(routeView(cold)).toEqual([]);
expect(cold.reparsedFileCount).toBeGreaterThan(0);
const keys = await saveParseCache(storage, cache);
await pruneAndSaveDurableParsedFileStore(
getDurableParsedFileDir(storage),
identity.base,
new Set(keys),
);
await clearParsedFileStore(storage);
const aliases = [{ importPath: 'example.com/infra/pkg', type: 'Engine', framework: 'gin' }];
const replay = async (wrappers: string[], includeAlias = true) => {
const result = await runPipelineFromRepo(FIXTURE, () => {}, {
parseCache: await loadParseCache(storage, identity, storage),
workerPoolSize: 1,
routeHookConfig: {
routeFrameworkAliases: includeAlias ? aliases : [],
routeHandlerWrappers: wrappers,
},
});
expect(result.reparsedFileCount).toBe(0);
expect(result.parseCacheHitFileCount).toBe(cold.reparsedFileCount);
expect(result.scopeExtractionFailures).toEqual([]);
return routeView(result);
};
expect(await replay(['common.Wrapper', 'common.WrapperWithSuccessCode'])).toEqual(
routeView(configured),
);
expect(await replay([])).toEqual([
'GET /console/v1/jobs/status -> undefined',
'GET /console/v1/jobs/userinfo -> UserInfo',
'POST /console/v1/jobs/create -> undefined',
]);
expect(await replay([], false)).toEqual([]);
} finally {
await fs.rm(storage, { recursive: true, force: true });
}
}, 300_000);
});

View file

@ -289,6 +289,119 @@ describe('analyze-config (.gitnexusrc support, #243)', () => {
expect(() => loadAnalyzeConfig(dir)).toThrow(/at least one string/);
});
// ── Go route aliases and handler wrappers ──────────────────────────
const CORE = 'example.com/infra/pkg';
it('normalizes goRouterAliases and goHandlerWrappers (de-duped)', async () => {
await writeRc(
JSON.stringify({
goRouterAliases: [
{ importPath: ` ${CORE} `, type: 'Engine', framework: 'gin' },
{ importPath: CORE, type: 'Engine', framework: 'gin' },
],
goHandlerWrappers: ['common.Wrapper', 'common.WrapperWithSuccessCode', 'common.Wrapper'],
}),
);
expect(loadAnalyzeConfig(dir)).toEqual({
routeFrameworkAliases: [{ importPath: CORE, type: 'Engine', framework: 'gin' }],
routeHandlerWrappers: ['common.Wrapper', 'common.WrapperWithSuccessCode'],
});
});
it.each([
[[{ importPath: CORE, type: 'Engine', framework: 'chi' }], /"gin" or "echo"/],
[
[
{ importPath: CORE, type: 'Engine', framework: 'gin' },
{ importPath: CORE, type: 'Engine', framework: 'echo' },
],
/as both "gin" and "echo"/,
],
[[{ type: 'Engine', framework: 'gin' }], /"importPath" must be a non-empty string/],
[[{ importPath: CORE, type: 'Engine', framework: 'gin', extra: 1 }], /unknown field "extra"/],
[[{ importPath: CORE, type: '*Engine', framework: 'gin' }], /must be a Go type name/],
[[{ importPath: 'a b', type: 'Engine', framework: 'gin' }], /must be a Go import path/],
[[], /non-empty array/],
[['gin'], /entries must be objects/],
])('rejects malformed goRouterAliases %j', async (aliases, message) => {
await writeRc(JSON.stringify({ goRouterAliases: aliases }));
expect(() => loadAnalyzeConfig(dir)).toThrow(message);
});
it('rejects more router aliases than the cap instead of truncating', async () => {
const alias = (i: number) => ({ importPath: `${CORE}${i}`, type: 'Engine', framework: 'gin' });
await writeRc(
JSON.stringify({ goRouterAliases: Array.from({ length: 100 }, (_, i) => alias(i)) }),
);
expect(loadAnalyzeConfig(dir)?.routeFrameworkAliases).toHaveLength(100);
await writeRc(
JSON.stringify({ goRouterAliases: Array.from({ length: 101 }, (_, i) => alias(i)) }),
);
expect(() => loadAnalyzeConfig(dir)).toThrow(/declares 101 aliases; at most 100/);
});
describe('GITNEXUS_RC out-of-repo config', () => {
let outside: string;
const saved = process.env.GITNEXUS_RC;
beforeEach(async () => {
outside = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-rc-env-'));
});
afterEach(async () => {
if (saved === undefined) delete process.env.GITNEXUS_RC;
else process.env.GITNEXUS_RC = saved;
await fs.rm(outside, { recursive: true, force: true });
});
const writeEnvRc = async (contents: unknown): Promise<string> => {
const file = path.join(outside, 'service.json');
await fs.writeFile(file, JSON.stringify(contents));
process.env.GITNEXUS_RC = file;
return file;
};
it('applies the file when the repository has no .gitnexusrc', async () => {
await writeEnvRc({ goHandlerWrappers: ['common.Wrapper'] });
expect(loadAnalyzeConfig(dir)).toEqual({ routeHandlerWrappers: ['common.Wrapper'] });
await expect(loadAnalyzeConfigStrict(dir)).resolves.toEqual({
routeHandlerWrappers: ['common.Wrapper'],
});
});
it('overrides the repository .gitnexusrc key by key, and CLI still wins', async () => {
await writeRc(JSON.stringify({ defaultBranch: 'develop', skipSkills: true }));
await writeEnvRc({ defaultBranch: 'release' });
const config = loadAnalyzeConfig(dir);
expect(config).toEqual({ defaultBranch: 'release', skipSkills: true });
expect(mergeAnalyzeOptions({ skipSkills: false }, config).skipSkills).toBe(false);
});
it('rejects a relative path, a missing file, and invalid content', async () => {
process.env.GITNEXUS_RC = 'relative/rc.json';
expect(() => loadAnalyzeConfig(dir)).toThrow(/must be an absolute path/);
process.env.GITNEXUS_RC = path.join(outside, 'missing.json');
expect(() => loadAnalyzeConfig(dir)).toThrow(/Could not read GITNEXUS_RC file/);
await writeEnvRc({ goRouterAliases: 'gin' });
expect(() => loadAnalyzeConfig(dir)).toThrow(/GITNEXUS_RC file .*non-empty array/);
});
it('rejects a directory and an oversized file', async () => {
process.env.GITNEXUS_RC = outside;
expect(() => loadAnalyzeConfig(dir)).toThrow(/not a regular file/);
const big = path.join(outside, 'big.json');
await fs.writeFile(big, `{"skipSkills": true}${' '.repeat(MAX_REPO_CONTROL_FILE_BYTES)}`);
process.env.GITNEXUS_RC = big;
expect(() => loadAnalyzeConfig(dir)).toThrow(/larger than/);
});
it('is ignored when unset or blank', async () => {
process.env.GITNEXUS_RC = ' ';
expect(loadAnalyzeConfig(dir)).toBeUndefined();
});
});
// ── Spring Actuator runtime enrichment (#2418) ────────────────────
it('normalizes a Spring Actuator snapshot path', async () => {

View file

@ -1,7 +1,10 @@
import { describe, expect, it } from 'vitest';
import Parser from 'tree-sitter';
import Go from 'tree-sitter-go';
import { extractGoGinEchoRoutes } from '../../src/core/ingestion/route-extractors/go-gin-echo.js';
import {
extractGoGinEchoRoutes,
extractGoRouteCandidates,
} from '../../src/core/ingestion/route-extractors/go-gin-echo.js';
const parser = new Parser();
parser.setLanguage(Go);
@ -394,3 +397,74 @@ describe('Go route type-parameter shadowing', () => {
expect(routes[0].handlerReceiver).toBeUndefined();
});
});
describe('wrapper-package route candidates', () => {
const CORE_PATH = 'example.com/infra/pkg';
const CORE = `import (
consoleApi "example.com/app/api"
"example.com/app/common"
mw "example.com/app/middleware"
core "${CORE_PATH}"
)
`;
const candidates = (body: string, header = CORE) =>
extractGoRouteCandidates(parser.parse(`package routes\n${header}${body}`));
it('records Group prefixes under the root parameter type, not as routes', () => {
const body = `func initConsoleRoutes(s *core.Engine, api *consoleApi.API) {
v1 := s.Group("/console/v1")
{
oauth := v1.Group("/oauth")
oauth.GET("/iam/oauthback", mw.AppTag(), consoleApi.IamOauthBack)
oauth.POST("/sso/sign", common.Wrapper(api.SingleSignOn))
}
}`;
expect(extractGoGinEchoRoutes(parser.parse(`package routes\n${CORE}${body}`), 'r.go')).toEqual(
[],
);
const facts = candidates(body);
expect(facts?.roots).toHaveLength(1);
expect(facts?.roots[0]).toMatchObject({ importPath: CORE_PATH, typeName: 'Engine' });
expect(
facts?.roots[0].routes.map((r) => ({
route: `${r.httpMethod} ${r.routePath}`,
gin: r.handlers.at(-1),
})),
).toEqual([
{
route: 'GET /console/v1/oauth/iam/oauthback',
gin: {
handlerName: 'consoleApi.IamOauthBack',
handlerReceiver: { kind: 'module', qualifier: 'consoleApi' },
},
},
{
route: 'POST /console/v1/oauth/sso/sign',
gin: {
handlerWrapper: {
callee: 'common.Wrapper',
handlerName: 'api.SingleSignOn',
handlerReceiver: { kind: 'type', name: 'API', qualifier: 'consoleApi' },
},
},
},
]);
});
it('records the echo-order handler too, without deciding the framework', () => {
const facts = candidates(`func R(s *core.Engine) { s.GET("/x", First, mw.Log()) }`);
expect(facts?.roots[0].routes[0].handlers[0]).toEqual({ handlerName: 'First' });
// gin order reads the trailing middleware call: no designator, no wrapper.
expect(facts?.roots[0].routes[0].handlers.at(-1)).toEqual({});
});
it('emits no candidate for a direct gin engine or an unimported type', () => {
expect(candidates(`func R(r *gin.Engine) { r.GET("/x", H) }`, GIN)).toBeUndefined();
expect(candidates(`func R(r *Engine) { r.GET("/x", H) }`)).toBeUndefined();
});
it('does not treat a wrapper on a local value as configurable', () => {
const facts = candidates(`func R(s *core.Engine, m Wrapper) { s.GET("/x", m.Wrap(H)) }`);
expect(facts?.roots[0].routes[0].handlers.at(-1)).toEqual({});
});
});

View file

@ -0,0 +1,179 @@
/**
* `resolveGoRouteFacts`: wrapper-package route candidates become gin/echo
* routes only when their root type is declared in `goRouterAliases`.
*/
import { describe, expect, it } from 'vitest';
import Parser from 'tree-sitter';
import Go from 'tree-sitter-go';
import {
collectGoRouteFacts,
extractGoRouteCandidates,
} from '../../src/core/ingestion/route-extractors/go-gin-echo.js';
import { resolveGoRouteFacts } from '../../src/core/ingestion/languages/go/route-facts.js';
import type { RouteFrameworkAlias } from '../../src/core/ingestion/language-provider.js';
import { routeHookConfigKey } from '../../src/core/ingestion/route-hook-config.js';
const parser = new Parser();
parser.setLanguage(Go);
const CORE_PATH = 'example.com/infra/pkg';
const SOURCE = `package routes
import (
core "${CORE_PATH}"
mw "example.com/app/middleware"
)
func R(s *core.Engine) {
g := s.Group("/api")
g.GET("/users", mw.Auth(), First, Last)
}
`;
const resolve = (aliases: RouteFrameworkAlias[]) =>
resolveGoRouteFacts(
[{ filePath: 'routes/r.go', facts: extractGoRouteCandidates(parser.parse(SOURCE)) }],
{ resolveImportTargets: () => [], routeHookConfig: { routeFrameworkAliases: aliases } },
);
describe('resolveGoRouteFacts', () => {
it('replays serialized direct and alias facts with changed or removed configuration', () => {
const facts = JSON.parse(
JSON.stringify(
collectGoRouteFacts(
parser.parse(`package routes
import "github.com/gin-gonic/gin"
import core "${CORE_PATH}"
func R(r *gin.Engine, s *core.Engine) {
s.Group("/alias").GET("/x", First, Last)
r.Group("/direct").GET("/x", Middleware, Direct)
}`),
10,
),
),
);
const before = JSON.stringify(facts);
const replay = (framework?: string) =>
resolveGoRouteFacts([{ filePath: 'r.go', facts }], {
resolveImportTargets: () => [],
routeHookConfig: framework
? { routeFrameworkAliases: [{ importPath: CORE_PATH, type: 'Engine', framework }] }
: undefined,
}).map((r) => [r.routePath, r.handlerName, r.source, r.lineNumber]);
expect(replay('gin')).toEqual([
['/alias/x', 'Last', 'gin-route', 15],
['/direct/x', 'Direct', 'gin-route', 16],
]);
expect(replay('echo')).toEqual([
['/alias/x', 'First', 'echo-route', 15],
['/direct/x', 'Direct', 'gin-route', 16],
]);
expect(replay()).toEqual([['/direct/x', 'Direct', 'gin-route', 16]]);
expect(JSON.stringify(facts)).toBe(before);
});
it('declines assignments between different root types even when their prefixes agree', () => {
const facts = collectGoRouteFacts(
parser.parse(`package routes
import core "${CORE_PATH}"
func R(a *core.First, b *core.Second) {
g := a.Group("/api")
g = b.Group("/api")
g.GET("/ambiguous", H)
a.GET("/first", H)
b.GET("/second", H)
}`),
);
const routes = resolveGoRouteFacts([{ filePath: 'r.go', facts }], {
resolveImportTargets: () => [],
routeHookConfig: {
routeFrameworkAliases: ['First', 'Second'].map((type) => ({
importPath: CORE_PATH,
type,
framework: 'gin',
})),
},
});
expect(routes.map((r) => r.routePath)).toEqual(['/first', '/second']);
});
it('preserves alias parameter order when registrations use the reverse order', () => {
const facts = collectGoRouteFacts(
parser.parse(`package routes
import core "${CORE_PATH}"
func R(a *core.First, b *core.Second) {
b.GET("/same", Second)
a.GET("/same", First)
}`),
);
expect(facts?.roots.map((root) => root.typeName)).toEqual(['First', 'Second']);
});
it('promotes candidates on a gin alias, taking the last argument as handler', () => {
expect(resolve([{ importPath: CORE_PATH, type: 'Engine', framework: 'gin' }])).toEqual([
{
filePath: 'routes/r.go',
routePath: '/api/users',
httpMethod: 'GET',
decoratorName: 'GET',
lineNumber: 8,
prefix: null,
source: 'gin-route',
handlerName: 'Last',
},
]);
});
it('takes the second argument on an echo alias', () => {
// echo's second argument here is the `mw.Auth()` call: not a designator,
// and not a wrapper of one, so the route stands without a handler.
const [route] = resolve([{ importPath: CORE_PATH, type: 'Engine', framework: 'echo' }]);
expect(route.source).toBe('echo-route');
expect(route.handlerName).toBeUndefined();
expect(route.handlerWrapper).toBeUndefined();
});
it('drops every candidate whose root type is not declared', () => {
expect(resolve([])).toEqual([]);
expect(resolve([{ importPath: CORE_PATH, type: 'Router', framework: 'gin' }])).toEqual([]);
});
it('ignores facts it did not produce', () => {
expect(
resolveGoRouteFacts([{ filePath: 'x.go', facts: { other: true } }], {
resolveImportTargets: () => [],
}),
).toEqual([]);
});
});
describe('routeHookConfigKey', () => {
it('is independent of declaration order and uses code-unit order', () => {
const a = { importPath: 'example.com/a', type: 'Engine', framework: 'gin' };
const b = { importPath: 'example.com/B', type: 'Engine', framework: 'echo' };
expect(
routeHookConfigKey({
routeFrameworkAliases: [a, b],
routeHandlerWrappers: ['z.Wrap', 'Z.Wrap'],
}),
).toBe(
routeHookConfigKey({
routeFrameworkAliases: [b, a],
routeHandlerWrappers: ['Z.Wrap', 'z.Wrap'],
}),
);
// Uppercase sorts before lowercase by code unit, regardless of host locale.
expect(
routeHookConfigKey({
routeFrameworkAliases: [a, b],
routeHandlerWrappers: ['z.Wrap', 'Z.Wrap'],
}),
).toBe(
JSON.stringify([
[
['example.com/B', 'Engine', 'echo'],
['example.com/a', 'Engine', 'gin'],
],
['Z.Wrap', 'z.Wrap'],
]),
);
});
});

View file

@ -306,4 +306,47 @@ describe('resolveGoRouteHandler', () => {
).toBeUndefined();
});
});
describe('configured handler wrappers', () => {
const wrapped = {
handlerWrapper: {
callee: 'common.Wrapper',
handlerName: 'api.CreateJob',
handlerReceiver: { kind: 'type', name: 'API', qualifier: 'consoleApi' },
},
} as const;
const model = (): Model => {
const m = createSemanticModel();
struct(m, 'app/api/api.go', 'API');
method(m, 'app/api/job.go', 'API', 'CreateJob');
return m;
};
const imports = { consoleApi: ['app/api/api.go', 'app/api/job.go'] };
it('resolves the wrapped handler when the callee is configured', () => {
expect(
resolveGoRouteHandler(route(wrapped), {
model: model(),
importTargetsFor: (_from, name) => imports[name as keyof typeof imports] ?? [],
routeHookConfig: { routeHandlerWrappers: ['common.Wrapper'] },
}),
).toBe('Method:app/api/job.go:API.CreateJob');
});
it('declines an unconfigured wrapper, as before wrappers were recorded', () => {
expect(resolve(model(), wrapped, imports)).toBeUndefined();
});
it('prefers a direct handler designator over a wrapper', () => {
const m = model();
fn(m, ROUTER, 'Direct');
expect(
resolveGoRouteHandler(route({ ...wrapped, handlerName: 'Direct' }), {
model: m,
importTargetsFor: () => [],
routeHookConfig: { routeHandlerWrappers: ['common.Wrapper'] },
}),
).toBe(`Function:${ROUTER}:Direct`);
});
});
});

View file

@ -59,6 +59,7 @@ import {
SPRING_ROUTE_BINDINGS_FEATURE,
} from '../../src/core/ingestion/frameworks/spring/analysis-features.js';
import { springVendorPrefixesKey } from '../../src/core/ingestion/frameworks/spring/vendor-prefixes.js';
import { routeHookConfigKey } from '../../src/core/ingestion/route-hook-config.js';
import {
decodeSpringAopReason,
SPRING_AOP_EVIDENCE_ID_PREFIX,
@ -896,6 +897,43 @@ describe('runFullAnalysis — incremental orchestration', () => {
}
}, 300_000);
it('rebuilds when the declared route aliases or handler wrappers change', async () => {
const repo = await setupSpringBeanIncrementalRepo();
try {
const { runFullAnalysis } = await import('../../src/core/run-analyze.js');
const config = {
skipAgentsMd: true,
routeHookConfig: {
routeFrameworkAliases: [
{ importPath: 'example.com/infra/pkg', type: 'Engine', framework: 'gin' },
],
routeHandlerWrappers: ['common.Wrapper'],
},
};
await runFullAnalysis(repo.dbPath, config, { onProgress: () => {} });
const { storagePath } = getStoragePaths(repo.dbPath);
expect((await loadMeta(storagePath))?.routeHookConfig).toBe(
routeHookConfigKey(config.routeHookConfig),
);
const steady = await runFullAnalysis(repo.dbPath, config, { onProgress: () => {} });
expect(steady.alreadyUpToDate).toBe(true);
const logs: string[] = [];
const rebuilt = await runFullAnalysis(
repo.dbPath,
{ skipAgentsMd: true },
{ onProgress: () => {}, onLog: (message) => logs.push(message) },
);
expect(rebuilt.alreadyUpToDate).toBeUndefined();
expect(rebuilt.rebuildReasons).toContain('route-hook-config');
expect(logs.join('\n')).toContain('no longer configured');
expect((await loadMeta(storagePath))?.routeHookConfig).toBe(routeHookConfigKey());
} finally {
await repo.cleanup();
}
}, 300_000);
it('rebuilds a JVM index when the registered Spring vendor prefixes change', async () => {
const repo = await setupSpringBeanIncrementalRepo();
try {

View file

@ -297,6 +297,7 @@ const REBUILD_REASON_COVERAGE = [
{ key: 'graph-write-collapse', file: 'test/unit/incremental-orchestration.test.ts' },
{ key: 'analysis-features', file: 'test/unit/incremental-orchestration.test.ts' },
{ key: 'spring-vendor-prefixes', file: 'test/unit/incremental-orchestration.test.ts' },
{ key: 'route-hook-config', file: 'test/unit/incremental-orchestration.test.ts' },
{ key: 'runner-identity', file: 'test/unit/incremental-orchestration.test.ts' },
{ key: 'parser-identity', file: 'test/integration/parse-cache-identity-lifecycle.test.ts' },
{ key: 'cjk-segmentation', file: 'test/unit/incremental-orchestration.test.ts' },

View file

@ -24,6 +24,39 @@ afterEach(async () => {
});
describe('watch path selection', () => {
it('forwards and removes route configuration on subsequent refreshes', async () => {
const aliases = [{ importPath: 'example.com/core', type: 'Engine', framework: 'gin' }];
const baseline = { maxFileSize: undefined, workerTimeout: undefined, verbose: undefined };
for (const name of [
'GITNEXUS_MAX_FILE_SIZE',
'GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS',
'GITNEXUS_VERBOSE',
]) {
vi.stubEnv(name, process.env[name]);
}
vi.stubEnv('GITNEXUS_RC', '');
try {
await fs.writeFile(
path.join(repoPath, '.gitnexusrc'),
JSON.stringify({
goRouterAliases: aliases,
goHandlerWrappers: ['common.Wrapper'],
}),
);
expect((await resolveWatchOptions(repoPath, {}, baseline)).routeHookConfig).toEqual({
routeFrameworkAliases: aliases,
routeHandlerWrappers: ['common.Wrapper'],
});
await fs.writeFile(path.join(repoPath, '.gitnexusrc'), '{}');
expect((await resolveWatchOptions(repoPath, {}, baseline)).routeHookConfig).toEqual({
routeFrameworkAliases: undefined,
routeHandlerWrappers: undefined,
});
} finally {
vi.unstubAllEnvs();
}
});
it('forwards explicit FTS opt-out without changing the default', async () => {
const names = [
'GITNEXUS_MAX_FILE_SIZE',