From 909d94979854c34814ca9a8556949eaeca5215d2 Mon Sep 17 00:00:00 2001 From: zhangzhichao13 Date: Wed, 28 Oct 2026 20:18:08 +0800 Subject: [PATCH 1/4] feat(go): index gin/echo routes registered through wrapper-package engine aliases Go services that register routes on a wrapper package's engine alias (`func InitRoute(s *core.Engine)`, `type Engine = gin.Engine` in a dependency that is not vendored) produced zero Route nodes, and handlers wrapped by an adapter (`common.Wrapper(api.CreateJob)`) got no HANDLES_ROUTE edge. - `.gitnexusrc` keys `goRouterAliases` and `goHandlerWrappers`, strictly validated; `GITNEXUS_RC` names an out-of-repo config layered over it. - The parse worker emits configuration-free candidates via `extractRouteFacts`; the Go provider applies the config on the main thread in `resolveRouteFacts` / `resolveRouteHandler`, so config never enters the parse cache. - `routeHookConfig` meta stamp and a `route-hook-config` rebuild reason, so a config change is not swallowed by the up-to-date fast path; a run that lost the config warns before removing its Routes. - Dropped candidates are summarized per `importPath.Type`. Behaviour without the new keys is unchanged. Co-Authored-By: Claude Code --- gitnexus/README.md | 15 ++ gitnexus/src/cli/analyze-config.ts | 116 +++++++- gitnexus/src/cli/analyze-options.ts | 12 + gitnexus/src/cli/analyze-watch.ts | 2 + gitnexus/src/cli/analyze.ts | 2 + gitnexus/src/core/ingestion/call-processor.ts | 6 +- .../src/core/ingestion/language-provider.ts | 23 +- gitnexus/src/core/ingestion/languages/go.ts | 5 + .../ingestion/languages/go/route-facts.ts | 101 +++++++ .../ingestion/languages/go/route-handler.ts | 40 +++ .../ingestion/pipeline-phases/parse-impl.ts | 14 +- gitnexus/src/core/ingestion/pipeline.ts | 9 + .../ingestion/route-extractors/go-gin-echo.ts | 248 +++++++++++++++--- .../src/core/ingestion/route-hook-config.ts | 15 ++ .../core/ingestion/workers/parse-worker.ts | 12 + gitnexus/src/core/rebuild-reasons.ts | 1 + gitnexus/src/core/run-analyze.ts | 31 +++ gitnexus/src/storage/repo-meta.ts | 5 + .../go-wrapped-gin-route-app/api/api.go | 19 ++ .../common/context.go | 19 ++ .../fixtures/go-wrapped-gin-route-app/go.mod | 8 + .../go-wrapped-gin-route-app/routes/routes.go | 18 ++ .../go-wrapped-gin-route-app/service/jobs.go | 7 + .../go-wrapped-gin-route-pipeline.test.ts | 74 ++++++ gitnexus/test/unit/analyze-config.test.ts | 85 ++++++ gitnexus/test/unit/go-gin-echo-routes.test.ts | 73 +++++- gitnexus/test/unit/go-route-facts.test.ts | 70 +++++ gitnexus/test/unit/go-route-handler.test.ts | 43 +++ .../unit/incremental-orchestration.test.ts | 36 +++ gitnexus/test/unit/rebuild-reasons.test.ts | 1 + 30 files changed, 1062 insertions(+), 48 deletions(-) create mode 100644 gitnexus/src/core/ingestion/languages/go/route-facts.ts create mode 100644 gitnexus/src/core/ingestion/route-hook-config.ts create mode 100644 gitnexus/test/fixtures/go-wrapped-gin-route-app/api/api.go create mode 100644 gitnexus/test/fixtures/go-wrapped-gin-route-app/common/context.go create mode 100644 gitnexus/test/fixtures/go-wrapped-gin-route-app/go.mod create mode 100644 gitnexus/test/fixtures/go-wrapped-gin-route-app/routes/routes.go create mode 100644 gitnexus/test/fixtures/go-wrapped-gin-route-app/service/jobs.go create mode 100644 gitnexus/test/integration/go-wrapped-gin-route-pipeline.test.ts create mode 100644 gitnexus/test/unit/go-route-facts.test.ts diff --git a/gitnexus/README.md b/gitnexus/README.md index 373b64e35..44bdbc5b8 100644 --- a/gitnexus/README.md +++ b/gitnexus/README.md @@ -394,6 +394,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. diff --git a/gitnexus/src/cli/analyze-config.ts b/gitnexus/src/cli/analyze-config.ts index 3d2219db2..ec02f38ca 100644 --- a/gitnexus/src/cli/analyze-config.ts +++ b/gitnexus/src/cli/analyze-config.ts @@ -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 type { RouteFrameworkAlias } from '../core/ingestion/language-provider.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 = { // 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,12 +311,65 @@ 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': + return normalizeRouterAliases(value, source); default: // Exhaustive — kept for forward-compat if a new kind is added. throw new GitNexusRcError(`${source}: unsupported config value kind.`); } }; +const ROUTER_ALIAS_FRAMEWORKS: ReadonlySet = new Set(['gin', 'echo']); +const ROUTER_ALIAS_FIELDS: ReadonlySet = new Set(['importPath', 'type', 'framework']); + +/** + * `[{ importPath, type, framework }]` — every field required, no extras, so a + * typo fails closed instead of silently declaring nothing. + */ +function normalizeRouterAliases(value: unknown, source: string): RouteFrameworkAlias[] { + if (!Array.isArray(value) || value.length === 0) { + throw new GitNexusRcError(`${source} must be a non-empty array of alias objects.`); + } + const out = new Map(); + for (const entry of value) { + if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) { + throw new GitNexusRcError( + `${source} entries must be objects like {"importPath": "...", "type": "Engine", "framework": "gin"}.`, + ); + } + const record = entry as Record; + for (const key of Object.keys(record)) { + if (!ROUTER_ALIAS_FIELDS.has(key)) { + throw new GitNexusRcError(`${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 GitNexusRcError(`${source} entry field "${name}" must be a non-empty string.`); + } + const trimmed = raw.trim(); + assertNoHiddenChars(trimmed, source); + if (!pattern.test(trimmed)) { + throw new GitNexusRcError(`${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 (!ROUTER_ALIAS_FRAMEWORKS.has(framework)) { + throw new GitNexusRcError(`${source} entry field "framework" must be "gin" or "echo".`); + } + out.set(`${importPath}\u0000${type}`, { importPath, type, framework }); + } + return [...out.values()].slice(0, 100); +} + /** * Normalize one level (flat top-level or the nested `analyze` block) into a * partial `AnalyzeOptions`. Rejects unknown keys and two aliases that configure @@ -356,11 +419,11 @@ export function loadAnalyzeConfig(repoRoot: string): Partial | 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 +436,50 @@ 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 | undefined, +): Partial | 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 { + const stat = fs.statSync(envPath); + 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(envPath, 'utf-8'); + } catch (err) { + throw new GitNexusRcError(`Could not read ${label}: ${(err as Error).message}`); + } + let envConfig: Partial; + 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 { diff --git a/gitnexus/src/cli/analyze-options.ts b/gitnexus/src/cli/analyze-options.ts index d548484e0..2083487e1 100644 --- a/gitnexus/src/cli/analyze-options.ts +++ b/gitnexus/src/cli/analyze-options.ts @@ -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. diff --git a/gitnexus/src/cli/analyze-watch.ts b/gitnexus/src/cli/analyze-watch.ts index 88080bd06..42c3bc7a7 100644 --- a/gitnexus/src/cli/analyze-watch.ts +++ b/gitnexus/src/cli/analyze-watch.ts @@ -202,6 +202,8 @@ export async function resolveWatchOptions( maxProcessTraceDepth: processDetection.maxProcessTraceDepth, maxEntryPointCandidates: processDetection.maxEntryPointCandidates, fetchWrappers: merged.fetchWrappers, + routeFrameworkAliases: merged.routeFrameworkAliases, + routeHandlerWrappers: merged.routeHandlerWrappers, skipAgentsMd: true, skipSkills: true, noStats: true, diff --git a/gitnexus/src/cli/analyze.ts b/gitnexus/src/cli/analyze.ts index 483b889de..be6d3adf0 100644 --- a/gitnexus/src/cli/analyze.ts +++ b/gitnexus/src/cli/analyze.ts @@ -1589,6 +1589,8 @@ const analyzeCommandImpl = async ( // Extra fetch-wrapper names from `.gitnexusrc` (#1589/#1852 residual); // forwarded to the routes phase consumer scan. fetchWrappers: options.fetchWrappers, + 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 diff --git a/gitnexus/src/core/ingestion/call-processor.ts b/gitnexus/src/core/ingestion/call-processor.ts index fa69b72e2..bbc6d7678 100644 --- a/gitnexus/src/core/ingestion/call-processor.ts +++ b/gitnexus/src/core/ingestion/call-processor.ts @@ -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,7 @@ export function resolveRouteHandlerSymbols( return routeContext.resolveImportTargets(parsedImport, fromFile); }; - const providerContext = { model, importTargetsFor }; + const providerContext = { model, importTargetsFor, ...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); diff --git a/gitnexus/src/core/ingestion/language-provider.ts b/gitnexus/src/core/ingestion/language-provider.ts index b8665f1cd..01aa49681 100644 --- a/gitnexus/src/core/ingestion/language-provider.ts +++ b/gitnexus/src/core/ingestion/language-provider.ts @@ -56,8 +56,27 @@ 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 { +export interface RouteHandlerResolutionHookContext extends RouteHookConfig { /** The model after every file has been parsed; scope resolution has not run. */ readonly model: SemanticModel; /** @@ -619,7 +638,7 @@ interface LanguageProviderConfig { * callback uses the language's configured ScopeResolver module resolution. */ readonly resolveRouteFacts?: ( files: readonly { filePath: string; facts: unknown }[], - context: { + context: RouteHookConfig & { resolveImportTargets: (fromFile: string, moduleSpecifier: string) => readonly string[]; }, ) => ExtractedDecoratorRoute[]; diff --git a/gitnexus/src/core/ingestion/languages/go.ts b/gitnexus/src/core/ingestion/languages/go.ts index dd6ea6895..b479335ba 100644 --- a/gitnexus/src/core/ingestion/languages/go.ts +++ b/gitnexus/src/core/ingestion/languages/go.ts @@ -27,6 +27,7 @@ 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'; @@ -165,6 +166,10 @@ export const goProvider = defineLanguage({ // gin / echo verb registrations with in-function Group prefixes (#3402). extractDecoratorRoutes: extractGoGinEchoRoutes, resolveRouteHandler: resolveGoRouteHandler, + // Registrations on a wrapper-package router type; promoted to gin/echo + // routes on the main thread only when declared in `goRouterAliases`. + extractRouteFacts: extractGoRouteFacts, + resolveRouteFacts: resolveGoRouteFacts, // ── RFC #909 Ring 3: scope-based resolution hooks ────────── emitScopeCaptures: emitGoScopeCaptures, diff --git a/gitnexus/src/core/ingestion/languages/go/route-facts.ts b/gitnexus/src/core/ingestion/languages/go/route-facts.ts new file mode 100644 index 000000000..34467dfdc --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/go/route-facts.ts @@ -0,0 +1,101 @@ +import type Parser from 'tree-sitter'; +import type { ParsedFile } from 'gitnexus-shared'; +import { logger } from '../../../logger.js'; +import type { LanguageProvider } from '../../language-provider.js'; +import { + ECHO_ROUTE_SOURCE, + extractGoRouteCandidates, + GIN_ROUTE_SOURCE, + type GoRouteCandidateFacts, + type GoRouteHandlerFact, +} from '../../route-extractors/go-gin-echo.js'; +import type { ExtractedDecoratorRoute } from '../../workers/parse-worker.js'; + +/** + * Routes registered on a router whose type comes from a wrapper package + * (`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 (`extractGoRouteCandidates`), so the parse cache never depends on + * user config. Here, on the main thread, a candidate becomes a gin/echo route + * only when the user declared its root type in `goRouterAliases`; everything + * else is dropped, exactly as before the candidates existed. + */ +export const extractGoRouteFacts = ( + tree: Parser.Tree, + _parsedFile: ParsedFile, + lineOffset: number, +): GoRouteCandidateFacts | undefined => extractGoRouteCandidates(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 = ( + files, + context, +) => { + const aliases = new Map(); + for (const alias of context.routeFrameworkAliases ?? []) { + aliases.set(`${alias.importPath}.${alias.type}`, alias.framework); + } + const out: ExtractedDecoratorRoute[] = []; + const emittedByRoot = new Map(); + const droppedByRoot = new Map(); + 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}`; + candidates += root.routes.length; + const framework = aliases.get(rootKey); + if (framework !== 'gin' && framework !== 'echo') { + droppedByRoot.set(rootKey, (droppedByRoot.get(rootKey) ?? 0) + root.routes.length); + continue; + } + emittedByRoot.set(rootKey, (emittedByRoot.get(rootKey) ?? 0) + root.routes.length); + for (const candidate of root.routes) { + const handler: GoRouteHandlerFact = framework === 'gin' ? candidate.gin : candidate.echo; + out.push({ + filePath, + routePath: candidate.routePath, + httpMethod: candidate.httpMethod, + decoratorName: candidate.httpMethod, + lineNumber: candidate.lineNumber, + prefix: null, + source: framework === 'gin' ? GIN_ROUTE_SOURCE : ECHO_ROUTE_SOURCE, + ...handler, + }); + } + } + } + + for (const [rootKey, count] of emittedByRoot) { + logger.debug( + { rootType: rootKey, framework: aliases.get(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] || a[0].localeCompare(b[0])) + .slice(0, SUMMARY_LIMIT) + .map(([rootType, dropped]) => ({ rootType, dropped })); + logger.info( + { + candidates, + emitted: out.length, + 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; +}; diff --git a/gitnexus/src/core/ingestion/languages/go/route-handler.ts b/gitnexus/src/core/ingestion/languages/go/route-handler.ts index 538ec0839..5d599c082 100644 --- a/gitnexus/src/core/ingestion/languages/go/route-handler.ts +++ b/gitnexus/src/core/ingestion/languages/go/route-handler.ts @@ -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>(); + +/** + * 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.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; type PackageIndex = Map; const bucketKey = (dir: string, name: string): string => JSON.stringify([dir, name]); diff --git a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts index 725df68f1..7c0388901 100644 --- a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts +++ b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts @@ -1620,6 +1620,14 @@ 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 = { + routeFrameworkAliases: options?.routeFrameworkAliases ?? [], + routeHandlerWrappers: options?.routeHandlerWrappers ?? [], + }; + // 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 +1643,10 @@ export async function runChunkedParseAndResolve( } const resolvedRoutesByFile = new Map(); 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 +2034,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); diff --git a/gitnexus/src/core/ingestion/pipeline.ts b/gitnexus/src/core/ingestion/pipeline.ts index a6d51e0ad..fe41095ba 100644 --- a/gitnexus/src/core/ingestion/pipeline.ts +++ b/gitnexus/src/core/ingestion/pipeline.ts @@ -17,6 +17,7 @@ import { createKnowledgeGraph } from '../graph/graph.js'; import type { KnowledgeGraph } from '../graph/types.js'; +import type { RouteFrameworkAlias } 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,14 @@ 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. + */ + routeFrameworkAliases?: readonly RouteFrameworkAlias[]; + routeHandlerWrappers?: readonly string[]; } // ── Phase registry ───────────────────────────────────────────────────────── diff --git a/gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts b/gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts index 125f02c72..43840aac8 100644 --- a/gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts +++ b/gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts @@ -62,7 +62,10 @@ const FUNCTION_TYPES: ReadonlySet = new Set(FUNCTION_TYPE_LIST); /** The framework this file routes with, when exactly one is imported. */ function readImports(root: SyntaxNode): { readonly framework: Framework | null; + /** Every qualifier this file can call through, local name → import path. */ + readonly imports: ReadonlyMap; } { + const imports = new Map(); 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,12 +80,14 @@ 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 { + imports, framework: { source: GIN_ROUTE_SOURCE, alias: gin, @@ -94,6 +99,7 @@ function readImports(root: SyntaxNode): { } if (echo !== null && gin === null) { return { + imports, framework: { source: ECHO_ROUTE_SOURCE, alias: echo, @@ -103,7 +109,7 @@ function readImports(root: SyntaxNode): { }, }; } - return { framework: null }; + return { imports, framework: null }; } /** Named descendants of a function body, not descending into nested functions. */ @@ -169,13 +175,28 @@ 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; +/** What proves a router root: an engine constructor call or an engine-typed parameter. */ +interface RouterRoot { + /** Import local name the constructors are reached through; null when none apply. */ + readonly alias: string | null; + readonly constructors: ReadonlySet; + readonly isRootParameterType: (hint: RouteHandlerReceiver | undefined) => boolean; +} + +const frameworkRoot = (fw: Framework): RouterRoot => ({ + alias: fw.alias, + constructors: fw.constructors, + isRootParameterType: (hint) => + hint?.kind === 'type' && hint.qualifier === fw.alias && hint.name === fw.engineType, +}); + class RouterPrefixes { private readonly memo = new Map(); private readonly visiting = new Set(); constructor( private readonly bindings: GoRouteBindings, - private readonly fw: Framework, + private readonly root: RouterRoot, private readonly fn: SyntaxNode, ) {} @@ -197,10 +218,10 @@ class RouterPrefixes { if (!operand || !field) return null; if ( operand.type === 'identifier' && - operand.text === this.fw.alias && + operand.text === this.root.alias && !this.bindings.lookup(operand) ) { - return this.fw.constructors.has(field) ? '' : null; + return this.root.constructors.has(field) ? '' : null; } if (field !== 'Group') return null; const path = stringLiteral(node.childForFieldName('arguments')?.namedChild(0)); @@ -218,12 +239,7 @@ class RouterPrefixes { 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 - ) { + if (binding.isInputParameter && this.root.isRootParameterType(hint)) { candidates.push(''); } else if (binding.isInputParameter || binding.values.length === 0) { candidates.push(null); @@ -283,6 +299,90 @@ 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, +): { 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, +): 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, +): 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, +): Generator<{ fn: SyntaxNode; registrations: VerbRegistration[]; bindings: GoRouteBindings }> { + let bindings: GoRouteBindings | undefined; + for (const fn of root.descendantsOfType(FUNCTION_TYPE_LIST)) { + 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, @@ -294,26 +394,15 @@ export function extractGoGinEchoRoutes( const out: ExtractedDecoratorRoute[] = []; const handlerHints = new Map(); - 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]; - }); - // 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); + for (const { fn, registrations, bindings } of functionRegistrations(root)) { + const prefixes = new RouterPrefixes(bindings, frameworkRoot(framework), fn); 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 = { + out.push({ filePath, routePath: normalizeExtractedRoutePath(path, prefix), httpMethod: verb, @@ -321,20 +410,105 @@ export function extractGoGinEchoRoutes( 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; - } - } - out.push(route); + ...handlerFact(handler, bindings, handlerHints), + }); } } return out; } + +/** 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; + /** The handler read in gin's order (last argument). */ + readonly gin: GoRouteHandlerFact; + /** The handler read in echo's order (second argument). */ + readonly echo: 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 every imported, non-framework root type; nothing here is a route yet. + */ +export interface GoRouteCandidateFacts { + readonly roots: readonly { + readonly importPath: string; + readonly typeName: string; + readonly routes: readonly GoRouteCandidate[]; + }[]; +} + +/** `*Q.T` / `Q.T` parameters of `fn`, where `Q` is an import of this file. */ +function importedRootTypes( + fn: SyntaxNode, + bindings: GoRouteBindings, + imports: ReadonlyMap, +): { importPath: string; qualifier: string; typeName: string }[] { + const out = new Map(); + 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, + }); + } + return [...out.values()]; +} + +export function extractGoRouteCandidates( + tree: Parser.Tree, + lineOffset = 0, +): GoRouteCandidateFacts | undefined { + const root = tree.rootNode; + const { imports } = readImports(root); + const byRoot = new Map< + string, + { importPath: string; typeName: string; routes: GoRouteCandidate[] } + >(); + const handlerHints = new Map(); + for (const { fn, registrations, bindings } of functionRegistrations(root)) { + for (const rootType of importedRootTypes(fn, bindings, imports)) { + const prefixes = new RouterPrefixes( + bindings, + { + alias: null, + constructors: new Set(), + isRootParameterType: (hint) => + hint?.kind === 'type' && + hint.qualifier === rootType.qualifier && + hint.name === rootType.typeName, + }, + fn, + ); + for (const { call, verb, receiver, args, path } of registrations) { + const prefix = prefixes.of(receiver); + if (prefix === null) continue; + const key = `${rootType.importPath}\u0000${rootType.typeName}`; + let group = byRoot.get(key); + if (!group) { + group = { importPath: rootType.importPath, typeName: rootType.typeName, routes: [] }; + byRoot.set(key, group); + } + group.routes.push({ + routePath: normalizeExtractedRoutePath(path, prefix), + httpMethod: verb, + lineNumber: call.startPosition.row + 1 + lineOffset, + gin: handlerFact(args[args.length - 1], bindings, handlerHints), + echo: handlerFact(args[1], bindings, handlerHints), + }); + } + } + } + return byRoot.size === 0 ? undefined : { roots: [...byRoot.values()] }; +} diff --git a/gitnexus/src/core/ingestion/route-hook-config.ts b/gitnexus/src/core/ingestion/route-hook-config.ts new file mode 100644 index 000000000..84f6536ac --- /dev/null +++ b/gitnexus/src/core/ingestion/route-hook-config.ts @@ -0,0 +1,15 @@ +import type { RouteFrameworkAlias } 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( + aliases: readonly RouteFrameworkAlias[] = [], + wrappers: readonly string[] = [], +): string { + const aliasKeys = aliases + .map((alias) => [alias.importPath, alias.type, alias.framework]) + .sort((a, b) => a.join('\u0000').localeCompare(b.join('\u0000'))); + return JSON.stringify([aliasKeys, [...new Set(wrappers)].sort()]); +} diff --git a/gitnexus/src/core/ingestion/workers/parse-worker.ts b/gitnexus/src/core/ingestion/workers/parse-worker.ts index fb0a43b2b..c2f3669ca 100644 --- a/gitnexus/src/core/ingestion/workers/parse-worker.ts +++ b/gitnexus/src/core/ingestion/workers/parse-worker.ts @@ -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-`. Present when the route was extracted from a diff --git a/gitnexus/src/core/rebuild-reasons.ts b/gitnexus/src/core/rebuild-reasons.ts index 44afc2f18..351c8da26 100644 --- a/gitnexus/src/core/rebuild-reasons.ts +++ b/gitnexus/src/core/rebuild-reasons.ts @@ -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', diff --git a/gitnexus/src/core/run-analyze.ts b/gitnexus/src/core/run-analyze.ts index 7cec865c2..768f1e618 100644 --- a/gitnexus/src/core/run-analyze.ts +++ b/gitnexus/src/core/run-analyze.ts @@ -51,6 +51,8 @@ import { countCallsByLanguage, } from './ingestion/scope-resolution/name-fallback-summary.js'; import { runPipelineFromRepo } from './ingestion/pipeline.js'; +import type { RouteFrameworkAlias } from './ingestion/language-provider.js'; +import { routeHookConfigKey } from './ingestion/route-hook-config.js'; import { logUnresolvedReceiverFiles, summarizeUnresolvedReceivers, @@ -624,6 +626,12 @@ 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. + */ + routeFrameworkAliases?: RouteFrameworkAlias[]; + routeHandlerWrappers?: string[]; /** * Explicit local Spring Boot Actuator snapshot input (#2418), forwarded to * the Spring enrichment phase. Undefined keeps static-only analysis. @@ -2358,6 +2366,26 @@ 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.routeFrameworkAliases, + options.routeHandlerWrappers, + ); + 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 ( @@ -3101,6 +3129,8 @@ async function runFullAnalysisInner( ? resolveNativeSafeStorageDir(storagePath, 'graph-csv') : undefined, fetchWrappers: options.fetchWrappers, + routeFrameworkAliases: options.routeFrameworkAliases, + routeHandlerWrappers: options.routeHandlerWrappers, skipDerivedGraphPhases, springActuatorPath: options.springActuatorPath, asyncApiSpecPath: options.asyncApiSpecPath, @@ -5375,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. diff --git a/gitnexus/src/storage/repo-meta.ts b/gitnexus/src/storage/repo-meta.ts index f62684714..c483c4aa7 100644 --- a/gitnexus/src/storage/repo-meta.ts +++ b/gitnexus/src/storage/repo-meta.ts @@ -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 diff --git a/gitnexus/test/fixtures/go-wrapped-gin-route-app/api/api.go b/gitnexus/test/fixtures/go-wrapped-gin-route-app/api/api.go new file mode 100644 index 000000000..7098e53ee --- /dev/null +++ b/gitnexus/test/fixtures/go-wrapped-gin-route-app/api/api.go @@ -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) {} diff --git a/gitnexus/test/fixtures/go-wrapped-gin-route-app/common/context.go b/gitnexus/test/fixtures/go-wrapped-gin-route-app/common/context.go new file mode 100644 index 000000000..3d4bb78c8 --- /dev/null +++ b/gitnexus/test/fixtures/go-wrapped-gin-route-app/common/context.go @@ -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) {} } diff --git a/gitnexus/test/fixtures/go-wrapped-gin-route-app/go.mod b/gitnexus/test/fixtures/go-wrapped-gin-route-app/go.mod new file mode 100644 index 000000000..b0d6e4c01 --- /dev/null +++ b/gitnexus/test/fixtures/go-wrapped-gin-route-app/go.mod @@ -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 +) diff --git a/gitnexus/test/fixtures/go-wrapped-gin-route-app/routes/routes.go b/gitnexus/test/fixtures/go-wrapped-gin-route-app/routes/routes.go new file mode 100644 index 000000000..adc33b7fc --- /dev/null +++ b/gitnexus/test/fixtures/go-wrapped-gin-route-app/routes/routes.go @@ -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) + } +} diff --git a/gitnexus/test/fixtures/go-wrapped-gin-route-app/service/jobs.go b/gitnexus/test/fixtures/go-wrapped-gin-route-app/service/jobs.go new file mode 100644 index 000000000..023e03909 --- /dev/null +++ b/gitnexus/test/fixtures/go-wrapped-gin-route-app/service/jobs.go @@ -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" } diff --git a/gitnexus/test/integration/go-wrapped-gin-route-pipeline.test.ts b/gitnexus/test/integration/go-wrapped-gin-route-pipeline.test.ts new file mode 100644 index 000000000..bc55b6f52 --- /dev/null +++ b/gitnexus/test/integration/go-wrapped-gin-route-pipeline.test.ts @@ -0,0 +1,74 @@ +/** + * 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 { runPipelineFromRepo } from '../../src/core/ingestion/pipeline.js'; +import type { PipelineResult } from '../../src/types/pipeline.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, () => {}, { + 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([]); + }); +}); diff --git a/gitnexus/test/unit/analyze-config.test.ts b/gitnexus/test/unit/analyze-config.test.ts index a4245f6c5..820223708 100644 --- a/gitnexus/test/unit/analyze-config.test.ts +++ b/gitnexus/test/unit/analyze-config.test.ts @@ -289,6 +289,91 @@ 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"/], + [[{ 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); + }); + + 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 => { + 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('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 () => { diff --git a/gitnexus/test/unit/go-gin-echo-routes.test.ts b/gitnexus/test/unit/go-gin-echo-routes.test.ts index c527f7d2c..1d328fb39 100644 --- a/gitnexus/test/unit/go-gin-echo-routes.test.ts +++ b/gitnexus/test/unit/go-gin-echo-routes.test.ts @@ -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,71 @@ 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.gin })), + ).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].echo).toEqual({ handlerName: 'First' }); + // gin order reads the trailing middleware call: no designator, no wrapper. + expect(facts?.roots[0].routes[0].gin).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].gin).toEqual({}); + }); +}); diff --git a/gitnexus/test/unit/go-route-facts.test.ts b/gitnexus/test/unit/go-route-facts.test.ts new file mode 100644 index 000000000..8e2ed1f64 --- /dev/null +++ b/gitnexus/test/unit/go-route-facts.test.ts @@ -0,0 +1,70 @@ +/** + * `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 { 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'; + +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: () => [], routeFrameworkAliases: aliases }, + ); + +describe('resolveGoRouteFacts', () => { + 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([]); + }); +}); diff --git a/gitnexus/test/unit/go-route-handler.test.ts b/gitnexus/test/unit/go-route-handler.test.ts index 5a8736a30..e1f8306f8 100644 --- a/gitnexus/test/unit/go-route-handler.test.ts +++ b/gitnexus/test/unit/go-route-handler.test.ts @@ -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] ?? [], + 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: () => [], + routeHandlerWrappers: ['common.Wrapper'], + }), + ).toBe(`Function:${ROUTER}:Direct`); + }); + }); }); diff --git a/gitnexus/test/unit/incremental-orchestration.test.ts b/gitnexus/test/unit/incremental-orchestration.test.ts index cd17b01b8..8fe3163c7 100644 --- a/gitnexus/test/unit/incremental-orchestration.test.ts +++ b/gitnexus/test/unit/incremental-orchestration.test.ts @@ -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,41 @@ 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, + 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.routeFrameworkAliases, config.routeHandlerWrappers), + ); + + 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 { diff --git a/gitnexus/test/unit/rebuild-reasons.test.ts b/gitnexus/test/unit/rebuild-reasons.test.ts index 803c1941c..c0c14ed40 100644 --- a/gitnexus/test/unit/rebuild-reasons.test.ts +++ b/gitnexus/test/unit/rebuild-reasons.test.ts @@ -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' }, From e659491c88b357c6413fe8dcd3d5eabe4d1e0e77 Mon Sep 17 00:00:00 2001 From: zhangzhichao13 Date: Wed, 28 Oct 2026 21:49:49 +0800 Subject: [PATCH 2/4] fix(go): reject conflicting router aliases and sort route config by code unit Address review on #3750: - `goRouterAliases` declaring one `importPath.type` as both gin and echo now fails validation instead of letting declaration order pick the handler argument order. - `routeHookConfigKey` and the dropped-candidate summary sort with `compareCodeUnits` instead of `localeCompare`, so the persisted config key is identical across host locales and does not trigger spurious rebuilds. Co-Authored-By: Claude Code --- gitnexus/src/cli/analyze-config.ts | 11 +++++++++- .../ingestion/languages/go/route-facts.ts | 3 ++- .../src/core/ingestion/route-hook-config.ts | 5 +++-- gitnexus/test/unit/analyze-config.test.ts | 7 +++++++ gitnexus/test/unit/go-route-facts.test.ts | 21 +++++++++++++++++++ 5 files changed, 43 insertions(+), 4 deletions(-) diff --git a/gitnexus/src/cli/analyze-config.ts b/gitnexus/src/cli/analyze-config.ts index ec02f38ca..8fb0d27f0 100644 --- a/gitnexus/src/cli/analyze-config.ts +++ b/gitnexus/src/cli/analyze-config.ts @@ -365,7 +365,16 @@ function normalizeRouterAliases(value: unknown, source: string): RouteFrameworkA if (!ROUTER_ALIAS_FRAMEWORKS.has(framework)) { throw new GitNexusRcError(`${source} entry field "framework" must be "gin" or "echo".`); } - out.set(`${importPath}\u0000${type}`, { importPath, type, framework }); + const key = `${importPath}\u0000${type}`; + const previous = out.get(key); + // Two frameworks for one type would make the handler argument order depend + // on declaration order; fail closed instead. + if (previous && previous.framework !== framework) { + throw new GitNexusRcError( + `${source} declares ${importPath}.${type} as both "${previous.framework}" and "${framework}".`, + ); + } + out.set(key, { importPath, type, framework }); } return [...out.values()].slice(0, 100); } diff --git a/gitnexus/src/core/ingestion/languages/go/route-facts.ts b/gitnexus/src/core/ingestion/languages/go/route-facts.ts index 34467dfdc..ca3e20951 100644 --- a/gitnexus/src/core/ingestion/languages/go/route-facts.ts +++ b/gitnexus/src/core/ingestion/languages/go/route-facts.ts @@ -1,5 +1,6 @@ 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 { @@ -83,7 +84,7 @@ export const resolveGoRouteFacts: NonNullable 0) { const top = [...droppedByRoot.entries()] - .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])) + .sort((a, b) => b[1] - a[1] || compareCodeUnits(a[0], b[0])) .slice(0, SUMMARY_LIMIT) .map(([rootType, dropped]) => ({ rootType, dropped })); logger.info( diff --git a/gitnexus/src/core/ingestion/route-hook-config.ts b/gitnexus/src/core/ingestion/route-hook-config.ts index 84f6536ac..5de0c46aa 100644 --- a/gitnexus/src/core/ingestion/route-hook-config.ts +++ b/gitnexus/src/core/ingestion/route-hook-config.ts @@ -1,3 +1,4 @@ +import { compareCodeUnits } from '../../lib/utils.js'; import type { RouteFrameworkAlias } from './language-provider.js'; /** @@ -10,6 +11,6 @@ export function routeHookConfigKey( ): string { const aliasKeys = aliases .map((alias) => [alias.importPath, alias.type, alias.framework]) - .sort((a, b) => a.join('\u0000').localeCompare(b.join('\u0000'))); - return JSON.stringify([aliasKeys, [...new Set(wrappers)].sort()]); + .sort((a, b) => compareCodeUnits(a.join('\u0000'), b.join('\u0000'))); + return JSON.stringify([aliasKeys, [...new Set(wrappers)].sort(compareCodeUnits)]); } diff --git a/gitnexus/test/unit/analyze-config.test.ts b/gitnexus/test/unit/analyze-config.test.ts index 820223708..3bd2d8945 100644 --- a/gitnexus/test/unit/analyze-config.test.ts +++ b/gitnexus/test/unit/analyze-config.test.ts @@ -311,6 +311,13 @@ describe('analyze-config (.gitnexusrc support, #243)', () => { 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/], diff --git a/gitnexus/test/unit/go-route-facts.test.ts b/gitnexus/test/unit/go-route-facts.test.ts index 8e2ed1f64..2f2e624d0 100644 --- a/gitnexus/test/unit/go-route-facts.test.ts +++ b/gitnexus/test/unit/go-route-facts.test.ts @@ -8,6 +8,7 @@ import Go from 'tree-sitter-go'; import { 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); @@ -68,3 +69,23 @@ describe('resolveGoRouteFacts', () => { ).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([a, b], ['z.Wrap', 'Z.Wrap'])).toBe( + routeHookConfigKey([b, a], ['Z.Wrap', 'z.Wrap']), + ); + // Uppercase sorts before lowercase by code unit, regardless of host locale. + expect(routeHookConfigKey([a, b], ['z.Wrap', 'Z.Wrap'])).toBe( + JSON.stringify([ + [ + ['example.com/B', 'Engine', 'echo'], + ['example.com/a', 'Engine', 'gin'], + ], + ['Z.Wrap', 'z.Wrap'], + ]), + ); + }); +}); From 57436232da30bd3c0d8e1d122ef235f3c055aa52 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Wed, 28 Oct 2026 22:02:31 +0000 Subject: [PATCH 3/4] perf(go): unify route collection and configuration Collect direct and configured routes in one config-free pass, sharing imports, lexical bindings and root-aware receiver prefix memoization. Use the framework descriptor to select handler arguments and provenance. Thread one RouteHookConfig through analysis and watch mode, with alias validation owned by Go. Preserve cache replay and duplicate-route order, with regression coverage and a reproducible paired collector benchmark. Note: pre-existing failure in parse-cache-identity-package not addressed by this PR. Packed tree-sitter requires GLIBCXX_3.4.31, absent in this container; reproduced on the unchanged original PR head. --- docs/cli-reference.md | 4 + gitnexus/scripts/bench/go-route-facts.ts | 94 ++++++ gitnexus/src/cli/analyze-config.ts | 68 +---- gitnexus/src/cli/analyze-watch.ts | 6 +- gitnexus/src/cli/analyze.ts | 6 +- gitnexus/src/core/ingestion/call-processor.ts | 6 +- .../src/core/ingestion/language-provider.ts | 6 +- gitnexus/src/core/ingestion/languages/go.ts | 6 +- .../ingestion/languages/go/route-config.ts | 51 ++++ .../ingestion/languages/go/route-facts.ts | 49 ++-- .../ingestion/languages/go/route-handler.ts | 2 +- .../ingestion/pipeline-phases/parse-impl.ts | 7 +- gitnexus/src/core/ingestion/pipeline.ts | 5 +- .../ingestion/route-extractors/go-gin-echo.ts | 270 ++++++++++-------- .../src/core/ingestion/route-hook-config.ts | 14 +- gitnexus/src/core/run-analyze.ts | 13 +- .../go-wrapped-gin-route-pipeline.test.ts | 96 ++++++- gitnexus/test/unit/go-gin-echo-routes.test.ts | 11 +- gitnexus/test/unit/go-route-facts.test.ts | 98 ++++++- gitnexus/test/unit/go-route-handler.test.ts | 4 +- .../unit/incremental-orchestration.test.ts | 12 +- gitnexus/test/unit/watch-paths.test.ts | 33 +++ 22 files changed, 601 insertions(+), 260 deletions(-) create mode 100644 gitnexus/scripts/bench/go-route-facts.ts create mode 100644 gitnexus/src/core/ingestion/languages/go/route-config.ts diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 64e986754..4e169e16a 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -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. | diff --git a/gitnexus/scripts/bench/go-route-facts.ts b/gitnexus/scripts/bench/go-route-facts.ts new file mode 100644 index 000000000..e253663d2 --- /dev/null +++ b/gitnexus/scripts/bench/go-route-facts.ts @@ -0,0 +1,94 @@ +/** + * 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 + * + * 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)); diff --git a/gitnexus/src/cli/analyze-config.ts b/gitnexus/src/cli/analyze-config.ts index 8fb0d27f0..42fef6cd3 100644 --- a/gitnexus/src/cli/analyze-config.ts +++ b/gitnexus/src/cli/analyze-config.ts @@ -32,7 +32,7 @@ import fs from 'node:fs'; import path from 'node:path'; import { MAX_REPO_CONTROL_FILE_BYTES, readRepoControlFile } from '../config/repo-control-file.js'; import { logger } from '../core/logger.js'; -import type { RouteFrameworkAlias } from '../core/ingestion/language-provider.js'; +import { normalizeRouterAliases } from '../core/ingestion/languages/go/route-config.js'; import { InvalidBranchError, sanitizeDetectedBranch, @@ -312,73 +312,17 @@ const normalizeValue = (kind: ValueKind, value: unknown, key: string): unknown = ); } case 'router-aliases': - return normalizeRouterAliases(value, source); + 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.`); } }; -const ROUTER_ALIAS_FRAMEWORKS: ReadonlySet = new Set(['gin', 'echo']); -const ROUTER_ALIAS_FIELDS: ReadonlySet = new Set(['importPath', 'type', 'framework']); - -/** - * `[{ importPath, type, framework }]` — every field required, no extras, so a - * typo fails closed instead of silently declaring nothing. - */ -function normalizeRouterAliases(value: unknown, source: string): RouteFrameworkAlias[] { - if (!Array.isArray(value) || value.length === 0) { - throw new GitNexusRcError(`${source} must be a non-empty array of alias objects.`); - } - const out = new Map(); - for (const entry of value) { - if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) { - throw new GitNexusRcError( - `${source} entries must be objects like {"importPath": "...", "type": "Engine", "framework": "gin"}.`, - ); - } - const record = entry as Record; - for (const key of Object.keys(record)) { - if (!ROUTER_ALIAS_FIELDS.has(key)) { - throw new GitNexusRcError(`${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 GitNexusRcError(`${source} entry field "${name}" must be a non-empty string.`); - } - const trimmed = raw.trim(); - assertNoHiddenChars(trimmed, source); - if (!pattern.test(trimmed)) { - throw new GitNexusRcError(`${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 (!ROUTER_ALIAS_FRAMEWORKS.has(framework)) { - throw new GitNexusRcError(`${source} entry field "framework" must be "gin" or "echo".`); - } - const key = `${importPath}\u0000${type}`; - const previous = out.get(key); - // Two frameworks for one type would make the handler argument order depend - // on declaration order; fail closed instead. - if (previous && previous.framework !== framework) { - throw new GitNexusRcError( - `${source} declares ${importPath}.${type} as both "${previous.framework}" and "${framework}".`, - ); - } - out.set(key, { importPath, type, framework }); - } - return [...out.values()].slice(0, 100); -} - /** * Normalize one level (flat top-level or the nested `analyze` block) into a * partial `AnalyzeOptions`. Rejects unknown keys and two aliases that configure diff --git a/gitnexus/src/cli/analyze-watch.ts b/gitnexus/src/cli/analyze-watch.ts index 42c3bc7a7..ebc0d4bff 100644 --- a/gitnexus/src/cli/analyze-watch.ts +++ b/gitnexus/src/cli/analyze-watch.ts @@ -202,8 +202,10 @@ export async function resolveWatchOptions( maxProcessTraceDepth: processDetection.maxProcessTraceDepth, maxEntryPointCandidates: processDetection.maxEntryPointCandidates, fetchWrappers: merged.fetchWrappers, - routeFrameworkAliases: merged.routeFrameworkAliases, - routeHandlerWrappers: merged.routeHandlerWrappers, + routeHookConfig: { + routeFrameworkAliases: merged.routeFrameworkAliases, + routeHandlerWrappers: merged.routeHandlerWrappers, + }, skipAgentsMd: true, skipSkills: true, noStats: true, diff --git a/gitnexus/src/cli/analyze.ts b/gitnexus/src/cli/analyze.ts index be6d3adf0..3ac4a1020 100644 --- a/gitnexus/src/cli/analyze.ts +++ b/gitnexus/src/cli/analyze.ts @@ -1589,8 +1589,10 @@ const analyzeCommandImpl = async ( // Extra fetch-wrapper names from `.gitnexusrc` (#1589/#1852 residual); // forwarded to the routes phase consumer scan. fetchWrappers: options.fetchWrappers, - routeFrameworkAliases: options.routeFrameworkAliases, - routeHandlerWrappers: options.routeHandlerWrappers, + 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 diff --git a/gitnexus/src/core/ingestion/call-processor.ts b/gitnexus/src/core/ingestion/call-processor.ts index bbc6d7678..b0f17b7ea 100644 --- a/gitnexus/src/core/ingestion/call-processor.ts +++ b/gitnexus/src/core/ingestion/call-processor.ts @@ -561,7 +561,11 @@ export function resolveRouteHandlerSymbols( return routeContext.resolveImportTargets(parsedImport, fromFile); }; - const providerContext = { model, importTargetsFor, ...routeContext?.routeHookConfig }; + 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); diff --git a/gitnexus/src/core/ingestion/language-provider.ts b/gitnexus/src/core/ingestion/language-provider.ts index 371f26f8b..4d9e55634 100644 --- a/gitnexus/src/core/ingestion/language-provider.ts +++ b/gitnexus/src/core/ingestion/language-provider.ts @@ -76,7 +76,8 @@ export interface RouteHookConfig { } /** What a provider's {@link LanguageProviderConfig.resolveRouteHandler} can see. */ -export interface RouteHandlerResolutionHookContext extends RouteHookConfig { +export interface RouteHandlerResolutionHookContext { + readonly routeHookConfig?: RouteHookConfig; /** The model after every file has been parsed; scope resolution has not run. */ readonly model: SemanticModel; /** @@ -665,7 +666,8 @@ interface LanguageProviderConfig { * callback uses the language's configured ScopeResolver module resolution. */ readonly resolveRouteFacts?: ( files: readonly { filePath: string; facts: unknown }[], - context: RouteHookConfig & { + context: { + readonly routeHookConfig?: RouteHookConfig; resolveImportTargets: (fromFile: string, moduleSpecifier: string) => readonly string[]; }, ) => ExtractedDecoratorRoute[]; diff --git a/gitnexus/src/core/ingestion/languages/go.ts b/gitnexus/src/core/ingestion/languages/go.ts index b479335ba..590ddfb2b 100644 --- a/gitnexus/src/core/ingestion/languages/go.ts +++ b/gitnexus/src/core/ingestion/languages/go.ts @@ -25,7 +25,6 @@ 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'; @@ -163,11 +162,8 @@ 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, - // Registrations on a wrapper-package router type; promoted to gin/echo - // routes on the main thread only when declared in `goRouterAliases`. + // One config-free collection for direct engines and wrapper-package roots. extractRouteFacts: extractGoRouteFacts, resolveRouteFacts: resolveGoRouteFacts, diff --git a/gitnexus/src/core/ingestion/languages/go/route-config.ts b/gitnexus/src/core/ingestion/languages/go/route-config.ts new file mode 100644 index 000000000..6916afe87 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/go/route-config.ts @@ -0,0 +1,51 @@ +import type { RouteFrameworkAlias } from '../../language-provider.js'; +import { goRouteFramework } from '../../route-extractors/go-gin-echo.js'; + +const FIELDS = new Set(['importPath', 'type', 'framework']); + +/** 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(); + 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; + 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 }); + } + return [...out.values()].slice(0, 100); +} diff --git a/gitnexus/src/core/ingestion/languages/go/route-facts.ts b/gitnexus/src/core/ingestion/languages/go/route-facts.ts index ca3e20951..01cacd236 100644 --- a/gitnexus/src/core/ingestion/languages/go/route-facts.ts +++ b/gitnexus/src/core/ingestion/languages/go/route-facts.ts @@ -4,30 +4,28 @@ import { compareCodeUnits } from '../../../../lib/utils.js'; import { logger } from '../../../logger.js'; import type { LanguageProvider } from '../../language-provider.js'; import { - ECHO_ROUTE_SOURCE, - extractGoRouteCandidates, - GIN_ROUTE_SOURCE, + collectGoRouteFacts, + goRouteFramework, + materializeGoRoute, type GoRouteCandidateFacts, - type GoRouteHandlerFact, } from '../../route-extractors/go-gin-echo.js'; import type { ExtractedDecoratorRoute } from '../../workers/parse-worker.js'; /** - * Routes registered on a router whose type comes from a wrapper package + * 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 (`extractGoRouteCandidates`), so the parse cache never depends on - * user config. Here, on the main thread, a candidate becomes a gin/echo route - * only when the user declared its root type in `goRouterAliases`; everything - * else is dropped, exactly as before the candidates existed. + * 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 => extractGoRouteCandidates(tree, lineOffset); +): GoRouteCandidateFacts | undefined => collectGoRouteFacts(tree, lineOffset); const isCandidateFacts = (facts: unknown): facts is GoRouteCandidateFacts => typeof facts === 'object' && @@ -42,8 +40,8 @@ export const resolveGoRouteFacts: NonNullable { const aliases = new Map(); - for (const alias of context.routeFrameworkAliases ?? []) { - aliases.set(`${alias.importPath}.${alias.type}`, alias.framework); + for (const alias of context.routeHookConfig?.routeFrameworkAliases ?? []) { + aliases.set(`${alias.importPath}\u0000${alias.type}`, alias.framework); } const out: ExtractedDecoratorRoute[] = []; const emittedByRoot = new Map(); @@ -53,32 +51,25 @@ export const resolveGoRouteFacts: NonNullable sum + count, 0), unconfiguredRootTypes: droppedByRoot.size, top, }, diff --git a/gitnexus/src/core/ingestion/languages/go/route-handler.ts b/gitnexus/src/core/ingestion/languages/go/route-handler.ts index 5d599c082..244701004 100644 --- a/gitnexus/src/core/ingestion/languages/go/route-handler.ts +++ b/gitnexus/src/core/ingestion/languages/go/route-handler.ts @@ -64,7 +64,7 @@ function unwrapConfiguredHandler( ): ExtractedDecoratorRoute | undefined { const wrapper = route.handlerWrapper; if (route.handlerName || !wrapper) return route; - if (context.routeHandlerWrappers?.includes(wrapper.callee)) { + if (context.routeHookConfig?.routeHandlerWrappers?.includes(wrapper.callee)) { return { ...route, handlerName: wrapper.handlerName, diff --git a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts index 7c0388901..a93a4b0a7 100644 --- a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts +++ b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts @@ -1623,10 +1623,7 @@ export async function runChunkedParseAndResolve( // 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 = { - routeFrameworkAliases: options?.routeFrameworkAliases ?? [], - routeHandlerWrappers: options?.routeHandlerWrappers ?? [], - }; + const routeHookConfig = options?.routeHookConfig; // A resolver's identity defines a fact family, including providers sharing // one language implementation. Shared ingestion never inspects the payload. @@ -1645,7 +1642,7 @@ export async function runChunkedParseAndResolve( for (const [resolve, files] of routeFactGroups) { for (const route of resolve(files, { resolveImportTargets: resolveRouteModuleTargets, - ...routeHookConfig, + routeHookConfig, })) { const routes = resolvedRoutesByFile.get(route.filePath) ?? []; routes.push(route); diff --git a/gitnexus/src/core/ingestion/pipeline.ts b/gitnexus/src/core/ingestion/pipeline.ts index fe41095ba..9ec3c5981 100644 --- a/gitnexus/src/core/ingestion/pipeline.ts +++ b/gitnexus/src/core/ingestion/pipeline.ts @@ -17,7 +17,7 @@ import { createKnowledgeGraph } from '../graph/graph.js'; import type { KnowledgeGraph } from '../graph/types.js'; -import type { RouteFrameworkAlias } from './language-provider.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'; @@ -314,8 +314,7 @@ export interface PipelineOptions { * provider route hooks — never sent to parse workers, so they never enter a * parse-cache key. Empty/undefined leaves route extraction unchanged. */ - routeFrameworkAliases?: readonly RouteFrameworkAlias[]; - routeHandlerWrappers?: readonly string[]; + routeHookConfig?: RouteHookConfig; } // ── Phase registry ───────────────────────────────────────────────────────── diff --git a/gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts b/gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts index 43840aac8..3a94d197d 100644 --- a/gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts +++ b/gitnexus/src/core/ingestion/route-extractors/go-gin-echo.ts @@ -45,9 +45,8 @@ const VERBS: ReadonlySet = 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,12 +55,34 @@ interface Framework { readonly handlerArg: 'last' | 'second'; } +const FRAMEWORKS: Readonly> = { + 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 = 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; } { @@ -88,25 +109,13 @@ function readImports(root: SyntaxNode): { if (gin !== null && echo === null) { return { imports, - framework: { - source: GIN_ROUTE_SOURCE, - alias: gin, - engineType: 'Engine', - constructors: new Set(['Default', 'New']), - handlerArg: 'last', - }, + framework: { ...FRAMEWORKS.gin, alias: gin, importPath: imports.get(gin)! }, }; } if (echo !== null && gin === null) { return { imports, - framework: { - source: ECHO_ROUTE_SOURCE, - alias: echo, - engineType: 'Echo', - constructors: new Set(['New']), - handlerArg: 'second', - }, + framework: { ...FRAMEWORKS.echo, alias: echo, importPath: imports.get(echo)! }, }; } return { imports, framework: null }; @@ -175,33 +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; -/** What proves a router root: an engine constructor call or an engine-typed parameter. */ interface RouterRoot { - /** Import local name the constructors are reached through; null when none apply. */ - readonly alias: string | null; - readonly constructors: ReadonlySet; - readonly isRootParameterType: (hint: RouteHandlerReceiver | undefined) => boolean; + readonly importPath: string; + readonly typeName: string; + readonly framework?: Framework['name']; } -const frameworkRoot = (fw: Framework): RouterRoot => ({ - alias: fw.alias, - constructors: fw.constructors, - isRootParameterType: (hint) => - hint?.kind === 'type' && hint.qualifier === fw.alias && hint.name === fw.engineType, -}); +interface RouterPrefix { + readonly root: RouterRoot; + readonly path: string; +} class RouterPrefixes { - private readonly memo = new Map(); + private readonly memo = new Map(); private readonly visiting = new Set(); constructor( private readonly bindings: GoRouteBindings, - private readonly root: RouterRoot, + private readonly roots: ReadonlyMap, + 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; @@ -218,19 +224,22 @@ class RouterPrefixes { if (!operand || !field) return null; if ( operand.type === 'identifier' && - operand.text === this.root.alias && + operand.text === this.framework?.alias && !this.bindings.lookup(operand) ) { - return this.root.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); @@ -238,15 +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 && this.root.isRootParameterType(hint)) { - 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; @@ -367,9 +384,21 @@ function handlerFact( /** Verb registrations of every function that has some, with the file's bindings. */ function* functionRegistrations( root: SyntaxNode, + framework: ImportedFramework | null, + imports: ReadonlyMap, ): 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) => { @@ -388,33 +417,12 @@ export function extractGoGinEchoRoutes( filePath: string, lineOffset = 0, ): ExtractedDecoratorRoute[] { - const root = tree.rootNode; - const { framework } = readImports(root); - if (framework === null) return []; - - const out: ExtractedDecoratorRoute[] = []; - const handlerHints = new Map(); - for (const { fn, registrations, bindings } of functionRegistrations(root)) { - const prefixes = new RouterPrefixes(bindings, frameworkRoot(framework), fn); - - 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]; - out.push({ - filePath, - routePath: normalizeExtractedRoutePath(path, prefix), - httpMethod: verb, - decoratorName: verb, - lineNumber: call.startPosition.row + 1 + lineOffset, - prefix: null, - source: framework.source, - ...handlerFact(handler, bindings, handlerHints), - }); - } - } - return out; + return (collectGoRouteFacts(tree, lineOffset)?.roots ?? []).flatMap((root) => { + const framework = root.framework && goRouteFramework(root.framework); + return framework + ? root.routes.map((route) => materializeGoRoute(filePath, route, framework)) + : []; + }); } /** One verb registration whose router root is a parameter of a wrapper-package type. */ @@ -422,24 +430,38 @@ export interface GoRouteCandidate { readonly routePath: string; readonly httpMethod: string; readonly lineNumber: number; - /** The handler read in gin's order (last argument). */ - readonly gin: GoRouteHandlerFact; - /** The handler read in echo's order (second argument). */ - readonly echo: GoRouteHandlerFact; + /** 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 every imported, non-framework root type; nothing here is a route yet. + * 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 { - readonly importPath: string; - readonly typeName: string; + 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. */ @@ -469,46 +491,70 @@ function importedRootTypes( 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 } = readImports(root); - const byRoot = new Map< - string, - { importPath: string; typeName: string; routes: GoRouteCandidate[] } - >(); - const handlerHints = new Map(); - for (const { fn, registrations, bindings } of functionRegistrations(root)) { - for (const rootType of importedRootTypes(fn, bindings, imports)) { - const prefixes = new RouterPrefixes( - bindings, - { - alias: null, - constructors: new Set(), - isRootParameterType: (hint) => - hint?.kind === 'type' && - hint.qualifier === rootType.qualifier && - hint.name === rootType.typeName, - }, - fn, - ); - for (const { call, verb, receiver, args, path } of registrations) { - const prefix = prefixes.of(receiver); - if (prefix === null) continue; - const key = `${rootType.importPath}\u0000${rootType.typeName}`; - let group = byRoot.get(key); - if (!group) { - group = { importPath: rootType.importPath, typeName: rootType.typeName, routes: [] }; - byRoot.set(key, group); - } - group.routes.push({ - routePath: normalizeExtractedRoutePath(path, prefix), - httpMethod: verb, - lineNumber: call.startPosition.row + 1 + lineOffset, - gin: handlerFact(args[args.length - 1], bindings, handlerHints), - echo: handlerFact(args[1], bindings, handlerHints), - }); + 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(); + const handlerHints = new Map(); + for (const { fn, registrations, bindings } of functionRegistrations(root, framework, imports)) { + const roots = new Map(); + 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(); + for (const { call, verb, receiver, args, path } of registrations) { + const prefix = prefixes.of(receiver); + if (prefix === null) continue; + const last = handlerFact(args[args.length - 1], bindings, handlerHints); + const routes = routesByRoot.get(prefix.root) ?? []; + routes.push({ + routePath: normalizeExtractedRoutePath(path, prefix.path), + httpMethod: verb, + lineNumber: call.startPosition.row + 1 + lineOffset, + 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; + } + 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 byRoot.size === 0 ? undefined : { roots: [...byRoot.values()] }; + 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; } diff --git a/gitnexus/src/core/ingestion/route-hook-config.ts b/gitnexus/src/core/ingestion/route-hook-config.ts index 5de0c46aa..716944e55 100644 --- a/gitnexus/src/core/ingestion/route-hook-config.ts +++ b/gitnexus/src/core/ingestion/route-hook-config.ts @@ -1,16 +1,16 @@ import { compareCodeUnits } from '../../lib/utils.js'; -import type { RouteFrameworkAlias } from './language-provider.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( - aliases: readonly RouteFrameworkAlias[] = [], - wrappers: readonly string[] = [], -): string { - const aliasKeys = aliases +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(wrappers)].sort(compareCodeUnits)]); + return JSON.stringify([ + aliasKeys, + [...new Set(config?.routeHandlerWrappers)].sort(compareCodeUnits), + ]); } diff --git a/gitnexus/src/core/run-analyze.ts b/gitnexus/src/core/run-analyze.ts index 768f1e618..7cd2e1c56 100644 --- a/gitnexus/src/core/run-analyze.ts +++ b/gitnexus/src/core/run-analyze.ts @@ -51,7 +51,7 @@ import { countCallsByLanguage, } from './ingestion/scope-resolution/name-fallback-summary.js'; import { runPipelineFromRepo } from './ingestion/pipeline.js'; -import type { RouteFrameworkAlias } from './ingestion/language-provider.js'; +import type { RouteHookConfig } from './ingestion/language-provider.js'; import { routeHookConfigKey } from './ingestion/route-hook-config.js'; import { logUnresolvedReceiverFiles, @@ -630,8 +630,7 @@ export interface AnalyzeOptions { * Declared router-framework aliases and handler-wrapper callees, forwarded to * `PipelineOptions` and stamped into meta so a changed value rebuilds Routes. */ - routeFrameworkAliases?: RouteFrameworkAlias[]; - routeHandlerWrappers?: string[]; + routeHookConfig?: RouteHookConfig; /** * Explicit local Spring Boot Actuator snapshot input (#2418), forwarded to * the Spring enrichment phase. Undefined keeps static-only analysis. @@ -2368,10 +2367,7 @@ 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.routeFrameworkAliases, - options.routeHandlerWrappers, - ); + const currentRouteHookConfig = routeHookConfigKey(options.routeHookConfig); const persistedRouteHookConfig = existingMeta?.routeHookConfig ?? routeHookConfigKey(); if (existingMeta && persistedRouteHookConfig !== currentRouteHookConfig) { if (currentRouteHookConfig === routeHookConfigKey()) { @@ -3129,8 +3125,7 @@ async function runFullAnalysisInner( ? resolveNativeSafeStorageDir(storagePath, 'graph-csv') : undefined, fetchWrappers: options.fetchWrappers, - routeFrameworkAliases: options.routeFrameworkAliases, - routeHandlerWrappers: options.routeHandlerWrappers, + routeHookConfig: options.routeHookConfig, skipDerivedGraphPhases, springActuatorPath: options.springActuatorPath, asyncApiSpecPath: options.asyncApiSpecPath, diff --git a/gitnexus/test/integration/go-wrapped-gin-route-pipeline.test.ts b/gitnexus/test/integration/go-wrapped-gin-route-pipeline.test.ts index bc55b6f52..c71a80e64 100644 --- a/gitnexus/test/integration/go-wrapped-gin-route-pipeline.test.ts +++ b/gitnexus/test/integration/go-wrapped-gin-route-pipeline.test.ts @@ -12,8 +12,17 @@ */ 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'); @@ -38,10 +47,12 @@ describe('wrapper-package gin route ingestion', () => { beforeAll(async () => { [configured, unconfigured] = await Promise.all([ runPipelineFromRepo(FIXTURE, () => {}, { - routeFrameworkAliases: [ - { importPath: 'example.com/infra/pkg', type: 'Engine', framework: 'gin' }, - ], - routeHandlerWrappers: ['common.Wrapper', 'common.WrapperWithSuccessCode'], + routeHookConfig: { + routeFrameworkAliases: [ + { importPath: 'example.com/infra/pkg', type: 'Engine', framework: 'gin' }, + ], + routeHandlerWrappers: ['common.Wrapper', 'common.WrapperWithSuccessCode'], + }, }), runPipelineFromRepo(FIXTURE, () => {}, {}), ]); @@ -71,4 +82,81 @@ describe('wrapper-package gin route ingestion', () => { 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); }); diff --git a/gitnexus/test/unit/go-gin-echo-routes.test.ts b/gitnexus/test/unit/go-gin-echo-routes.test.ts index 1d328fb39..f2bedbe01 100644 --- a/gitnexus/test/unit/go-gin-echo-routes.test.ts +++ b/gitnexus/test/unit/go-gin-echo-routes.test.ts @@ -426,7 +426,10 @@ describe('wrapper-package route candidates', () => { 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.gin })), + facts?.roots[0].routes.map((r) => ({ + route: `${r.httpMethod} ${r.routePath}`, + gin: r.handlers.at(-1), + })), ).toEqual([ { route: 'GET /console/v1/oauth/iam/oauthback', @@ -450,9 +453,9 @@ describe('wrapper-package route candidates', () => { 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].echo).toEqual({ handlerName: 'First' }); + 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].gin).toEqual({}); + expect(facts?.roots[0].routes[0].handlers.at(-1)).toEqual({}); }); it('emits no candidate for a direct gin engine or an unimported type', () => { @@ -462,6 +465,6 @@ describe('wrapper-package route candidates', () => { 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].gin).toEqual({}); + expect(facts?.roots[0].routes[0].handlers.at(-1)).toEqual({}); }); }); diff --git a/gitnexus/test/unit/go-route-facts.test.ts b/gitnexus/test/unit/go-route-facts.test.ts index 2f2e624d0..699b93242 100644 --- a/gitnexus/test/unit/go-route-facts.test.ts +++ b/gitnexus/test/unit/go-route-facts.test.ts @@ -5,7 +5,10 @@ import { describe, expect, it } from 'vitest'; import Parser from 'tree-sitter'; import Go from 'tree-sitter-go'; -import { extractGoRouteCandidates } from '../../src/core/ingestion/route-extractors/go-gin-echo.js'; +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'; @@ -28,10 +31,82 @@ func R(s *core.Engine) { const resolve = (aliases: RouteFrameworkAlias[]) => resolveGoRouteFacts( [{ filePath: 'routes/r.go', facts: extractGoRouteCandidates(parser.parse(SOURCE)) }], - { resolveImportTargets: () => [], routeFrameworkAliases: aliases }, + { 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([ { @@ -74,11 +149,24 @@ 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([a, b], ['z.Wrap', 'Z.Wrap'])).toBe( - routeHookConfigKey([b, a], ['Z.Wrap', 'z.Wrap']), + 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([a, b], ['z.Wrap', 'Z.Wrap'])).toBe( + expect( + routeHookConfigKey({ + routeFrameworkAliases: [a, b], + routeHandlerWrappers: ['z.Wrap', 'Z.Wrap'], + }), + ).toBe( JSON.stringify([ [ ['example.com/B', 'Engine', 'echo'], diff --git a/gitnexus/test/unit/go-route-handler.test.ts b/gitnexus/test/unit/go-route-handler.test.ts index e1f8306f8..9895c5d50 100644 --- a/gitnexus/test/unit/go-route-handler.test.ts +++ b/gitnexus/test/unit/go-route-handler.test.ts @@ -328,7 +328,7 @@ describe('resolveGoRouteHandler', () => { resolveGoRouteHandler(route(wrapped), { model: model(), importTargetsFor: (_from, name) => imports[name as keyof typeof imports] ?? [], - routeHandlerWrappers: ['common.Wrapper'], + routeHookConfig: { routeHandlerWrappers: ['common.Wrapper'] }, }), ).toBe('Method:app/api/job.go:API.CreateJob'); }); @@ -344,7 +344,7 @@ describe('resolveGoRouteHandler', () => { resolveGoRouteHandler(route({ ...wrapped, handlerName: 'Direct' }), { model: m, importTargetsFor: () => [], - routeHandlerWrappers: ['common.Wrapper'], + routeHookConfig: { routeHandlerWrappers: ['common.Wrapper'] }, }), ).toBe(`Function:${ROUTER}:Direct`); }); diff --git a/gitnexus/test/unit/incremental-orchestration.test.ts b/gitnexus/test/unit/incremental-orchestration.test.ts index 8fe3163c7..0227637ce 100644 --- a/gitnexus/test/unit/incremental-orchestration.test.ts +++ b/gitnexus/test/unit/incremental-orchestration.test.ts @@ -903,15 +903,17 @@ describe('runFullAnalysis — incremental orchestration', () => { const { runFullAnalysis } = await import('../../src/core/run-analyze.js'); const config = { skipAgentsMd: true, - routeFrameworkAliases: [ - { importPath: 'example.com/infra/pkg', type: 'Engine', framework: 'gin' }, - ], - routeHandlerWrappers: ['common.Wrapper'], + 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.routeFrameworkAliases, config.routeHandlerWrappers), + routeHookConfigKey(config.routeHookConfig), ); const steady = await runFullAnalysis(repo.dbPath, config, { onProgress: () => {} }); diff --git a/gitnexus/test/unit/watch-paths.test.ts b/gitnexus/test/unit/watch-paths.test.ts index 5dc5ce3f9..0a019d6bb 100644 --- a/gitnexus/test/unit/watch-paths.test.ts +++ b/gitnexus/test/unit/watch-paths.test.ts @@ -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', From ca19bee1ef5e5071d9594a2596620c2e31022913 Mon Sep 17 00:00:00 2001 From: zhangzhichao13 Date: Thu, 29 Oct 2026 15:41:52 +0800 Subject: [PATCH 4/4] fix(go): read GITNEXUS_RC through one descriptor and reject oversized alias lists Address review on #3750: - `withEnvConfig` opens the `GITNEXUS_RC` file once and checks type and size with `fstatSync` on that descriptor before reading from it, so the file cannot be swapped between check and read (CodeQL js/file-system-race). Content that grew after the check is still bounded. - `normalizeRouterAliases` rejects more than 100 aliases instead of silently dropping the tail. - The route-collection benchmark documents that its baseline build must already expose `resolveRouteFacts`. Co-Authored-By: Claude Code --- gitnexus/scripts/bench/go-route-facts.ts | 3 +++ gitnexus/src/cli/analyze-config.ts | 19 +++++++++++++---- .../ingestion/languages/go/route-config.ts | 10 ++++++++- gitnexus/test/unit/analyze-config.test.ts | 21 +++++++++++++++++++ 4 files changed, 48 insertions(+), 5 deletions(-) diff --git a/gitnexus/scripts/bench/go-route-facts.ts b/gitnexus/scripts/bench/go-route-facts.ts index e253663d2..f58b1865b 100644 --- a/gitnexus/scripts/bench/go-route-facts.ts +++ b/gitnexus/scripts/bench/go-route-facts.ts @@ -3,6 +3,9 @@ * 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. */ diff --git a/gitnexus/src/cli/analyze-config.ts b/gitnexus/src/cli/analyze-config.ts index 42fef6cd3..bc6f2f907 100644 --- a/gitnexus/src/cli/analyze-config.ts +++ b/gitnexus/src/cli/analyze-config.ts @@ -412,12 +412,23 @@ function withEnvConfig( } let raw: string; try { - const stat = fs.statSync(envPath); - if (!stat.isFile()) throw new Error('not a regular file'); - if (stat.size > MAX_REPO_CONTROL_FILE_BYTES) { + // 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`); } - raw = fs.readFileSync(envPath, 'utf-8'); } catch (err) { throw new GitNexusRcError(`Could not read ${label}: ${(err as Error).message}`); } diff --git a/gitnexus/src/core/ingestion/languages/go/route-config.ts b/gitnexus/src/core/ingestion/languages/go/route-config.ts index 6916afe87..717488501 100644 --- a/gitnexus/src/core/ingestion/languages/go/route-config.ts +++ b/gitnexus/src/core/ingestion/languages/go/route-config.ts @@ -3,6 +3,9 @@ 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) { @@ -47,5 +50,10 @@ export function normalizeRouterAliases(value: unknown, source: string): RouteFra } out.set(key, { importPath, type, framework }); } - return [...out.values()].slice(0, 100); + if (out.size > MAX_ROUTER_ALIASES) { + throw new Error( + `${source} declares ${out.size} aliases; at most ${MAX_ROUTER_ALIASES} are allowed.`, + ); + } + return [...out.values()]; } diff --git a/gitnexus/test/unit/analyze-config.test.ts b/gitnexus/test/unit/analyze-config.test.ts index 3bd2d8945..e7cc8155a 100644 --- a/gitnexus/test/unit/analyze-config.test.ts +++ b/gitnexus/test/unit/analyze-config.test.ts @@ -329,6 +329,18 @@ describe('analyze-config (.gitnexusrc support, #243)', () => { 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; @@ -375,6 +387,15 @@ describe('analyze-config (.gitnexusrc support, #243)', () => { 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();