backend-skeleton 1.1.0 → 1.1.1

package/handles/providers/typescript-express/plan.mjs

@@ -172,11 +172,18 @@ export function plan({ repoRoot, scanReport, module: moduleName, resourceFilter
 	for (const entity of targetModule.entities) {
 		if (resourceFilter && !resourceFilter.includes(entity.className)) continue;
 		const fetchRoute = findFetchRoute(targetModule.controllers, entity.className);
-		const handlerFile = fetchRoute ? resolveHandlerFile(fetchRoute.file, fetchRoute.method, srcRoot) : null;
+		// D-typescript-express-inline-handlers: `method === null` means the scanner found a real
+		// route but its handler is an inline function expression, not a named export -- there is
+		// genuinely nothing for resolveHandlerFile()'s import/barrel-hop search to correlate to, so
+		// this is checked explicitly (a clear, named reason) rather than relying on the incidental
+		// fact that a regex built from the literal string "null" also happens not to match anything.
+		const handlerFile = fetchRoute && fetchRoute.method ? resolveHandlerFile(fetchRoute.file, fetchRoute.method, srcRoot) : null;
 		const selectFields = handlerFile ? findSelectAllowList(handlerFile) : null;
 
 		if (!fetchRoute) {
 			notes.push(`${entity.className}: no single-resource GET route found on a router whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
+		} else if (!fetchRoute.method) {
+			notes.push(`${entity.className}: the single-resource GET route's handler is an inline function expression, not a named export -- nothing to correlate to a defining file, resolver NOT generated.`);
 		} else if (!handlerFile) {
 			notes.push(`${entity.className}: could not resolve ${fetchRoute.method}'s own defining file (import, or one barrel hop, from ${path.relative(repoRoot, fetchRoute.file)}) -- resolver NOT generated.`);
 		} else if (!selectFields) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "type": "module",
   "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scaffolding codegen included (Java/Spring, Python/FastAPI, TypeScript/Express).",
   "license": "AGPL-3.0-or-later",

package/scanners/adapters/_java-spring-analyzer.mjs

@@ -149,7 +149,22 @@ const MAPPING_VERBS = ['Get', 'Post', 'Put', 'Patch', 'Delete'];
 const MAPPING_ANNOTATION_RE = new RegExp(`@(?:(${MAPPING_VERBS.join('|')})Mapping|RequestMapping)\\b`, 'g');
 const REQUEST_MAPPING_RE = /@RequestMapping\b/g;
 const CLASS_OR_RECORD_START_RE = /^(?:public\s+)?(?:class|record)\b/;
-const REQUEST_MAPPING_METHOD_RE = /\bmethod\s*=\s*RequestMethod\.(\w+)\b/;
+// D-java-spring-static-import-method: `RequestMethod.` prefix made optional -- confirmed live,
+// dogfooding against a real, popular repo (gothinkster/spring-boot-realworld-example-app, 1,584
+// real GitHub stars): its UsersApi.java (register + login, 2 of the RealWorld spec's most
+// fundamental endpoints) uses `import static ... RequestMethod.POST;` then bare
+// `@RequestMapping(path = "/users", method = POST)` -- a real, common Java style (static-import a
+// single enum constant to cut the qualifier) the original prefix-required regex silently missed
+// (0/2 endpoints on this file; the OTHER 15/17 endpoints in this same corpus, using
+// @PostMapping/@GetMapping shorthand elsewhere, were unaffected and already correct). The verb
+// alternation is restricted to Spring's own real `RequestMethod` enum's 8 actual values (GET,
+// HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE) rather than a bare `\w+` -- narrower than
+// "any identifier", so an unrelated `method = someVariable` still correctly fails to match rather
+// than being misread as a verb. Verified live: the existing multi-verb array form (`method =
+// {RequestMethod.GET, RequestMethod.POST}`, still deliberately unresolved/skipped) does NOT
+// accidentally partial-match here -- the array's own `{` breaks the match before any verb name is
+// reached, same as before this change.
+const REQUEST_MAPPING_METHOD_RE = /\bmethod\s*=\s*(?:RequestMethod\.)?(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|TRACE)\b/;
 
 // True when `class`/`record` is the next real declaration after `index`, ONE OR MORE further
 // annotations allowed in between (e.g. a real oracle shape: `@RequestMapping(...)

package/scanners/adapters/python-fastapi.mjs

@@ -23,7 +23,8 @@ const EXCLUDE_GLOBS = ['!**/.venv/**', '!**/site-packages/**', '!**/node_modules
 // `fastapi==0.100.0`.
 const FASTAPI_DEP_RE = /(?:^|[\s"'[])fastapi(?:\[[^\]]*\])?(?:[\s"',\]=<>~!;]|$)/mi;
 
-const VERB_DECORATOR_RE = /@\w+\.(get|post|put|patch|delete)\s*\(/gi;
+const VERB_DECORATOR_RE = /@(\w+)\.(get|post|put|patch|delete)\s*\(/gi;
+const ROUTER_DECL_RE = /(\w+)\s*=\s*APIRouter\s*\(/g;
 const CLASS_RE = /^class\s+(\w+)\s*\(([^)]*)\)\s*:/gm;
 const INCLUDE_ROUTER_RE = /include_router\s*\(/g;
 
@@ -104,24 +105,42 @@ function capitalize(s) {
 // resolved against a global prefix applied elsewhere (e.g. `include_router(prefix=...)`) -- that
 // asymmetry is exactly what `pathPrefixSignals`/`unknowns` exists to flag, same role java-spring's
 // detectGlobalPathPrefixSignals plays for `configurePathMatch`/`context-path`.
-function extractBasePath(text) {
-	const m = text.match(/APIRouter\s*\(/);
-	if (!m) return '';
-	const openIdx = m.index + m[0].length - 1;
-	const closeIdx = matchBalancedParens(text, openIdx);
-	if (closeIdx === -1) return '';
-	const prefixMatch = text.slice(openIdx + 1, closeIdx).match(/prefix\s*=\s*["']([^"']*)["']/);
-	return prefixMatch ? prefixMatch[1] : '';
+//
+// D-fastapi-multi-router-per-file: a real dogfooding find against `polarsource/polar` (a 400+
+// route production FastAPI monorepo) -- 3 real files (`checkout/endpoints.py`,
+// `member/endpoints.py`, `auth/oauth2/router.py`) declare MORE THAN ONE `<var> = APIRouter(...)`
+// in the same file (e.g. member.py's `router = APIRouter(prefix="/members")` plus a second,
+// distinct `customer_members_router = APIRouter(prefix="/customers")` for a nested customer-scoped
+// resource). The single-basePath-per-file design used to always read only the FIRST `APIRouter(`
+// occurrence and apply it to every decorator in the file regardless of which router variable
+// actually decorates it -- silently discarding the second router's own real prefix. Returns
+// Map<varName, prefix> for every declared router in the file so each decorator can look up its
+// OWN router's prefix instead.
+function extractRouterPrefixes(text) {
+	const prefixes = new Map();
+	for (const m of text.matchAll(ROUTER_DECL_RE)) {
+		const openIdx = m.index + m[0].length - 1;
+		const closeIdx = matchBalancedParens(text, openIdx);
+		if (closeIdx === -1) continue;
+		const prefixMatch = text.slice(openIdx + 1, closeIdx).match(/prefix\s*=\s*["']([^"']*)["']/);
+		prefixes.set(m[1], prefixMatch ? prefixMatch[1] : '');
+	}
+	return prefixes;
 }
 
 // `operationId` is always null -- see the adapter's own `api.operations: false` and
 // D-fastapi-adapter in DECISIONS.md: FastAPI generates operation ids at request-handling time
 // (per-project, sometimes via a custom `generate_unique_id_function`), never pinned in source the
 // way `@Operation(operationId=...)` is for Java, so there is nothing honest to statically correlate.
+//
+// D-fastapi-multi-router-per-file: `routerVar` (the exact identifier before `.get`/`.post`/...) is
+// now captured per endpoint so the caller can resolve basePath per-router-variable rather than
+// once for the whole file -- see extractRouterPrefixes() above.
 function extractEndpoints(text) {
 	const endpoints = [];
 	for (const m of text.matchAll(VERB_DECORATOR_RE)) {
-		const verb = m[1].toUpperCase();
+		const routerVar = m[1];
+		const verb = m[2].toUpperCase();
 		const openIdx = m.index + m[0].length - 1;
 		const closeIdx = matchBalancedParens(text, openIdx);
 		if (closeIdx === -1) continue;
@@ -134,11 +153,19 @@ function extractEndpoints(text) {
 		const funcMatch = afterDecoratorRe.exec(text);
 		if (!funcMatch) continue;
 
-		endpoints.push({ verb, path: pathMatch[1], operationId: null, method: funcMatch[1], line: lineNumberAt(text, m.index) });
+		endpoints.push({ verb, path: pathMatch[1], operationId: null, method: funcMatch[1], routerVar, line: lineNumberAt(text, m.index) });
 	}
 	return endpoints;
 }
 
+// snake_case/mixed identifier -> PascalCase, e.g. "customer_members_router" -> "CustomerMembersRouter",
+// "inner_router" -> "InnerRouter". Only used for a NON-default router variable name (see
+// scanPythonFastApi below) -- the common single-router-per-file case keeps its existing
+// `${capitalize(moduleName)}Router` className exactly as before, byte-for-byte.
+function pascalCase(identifier) {
+	return identifier.split('_').filter(Boolean).map(capitalize).join('');
+}
+
 // SQLModel `class X(<bases>, table=True):` -- table name is the lowercased class name (SQLModel's
 // own default when no explicit `__tablename__` is declared; cross-checked against the real
 // oracle's own Alembic migration, `op.create_table("user", ...)`/`op.create_table("item", ...)`,
@@ -249,9 +276,10 @@ function extractIncludeRouterPrefixSignals(repoRoot, files) {
 	return signals;
 }
 
-// D-fastapi-adapter: paths are router-local (see extractBasePath); FastAPI generates operation ids
-// at runtime, never pinned in source -- see extractEndpoints. --openapi-file + --path-prefix is the
-// trustworthy path (contracts/openapi.mjs's existing, adapter-agnostic reconciliation).
+// D-fastapi-adapter: paths are router-local (see extractRouterPrefixes); FastAPI generates
+// operation ids at runtime, never pinned in source -- see extractEndpoints. --openapi-file +
+// --path-prefix is the trustworthy path (contracts/openapi.mjs's existing, adapter-agnostic
+// reconciliation).
 const API_SURFACE_SOURCE = 'router-local paths only (this scan does not resolve a global prefix applied via ' +
 	'include_router(prefix=...) beyond a simple literal/single-variable lookup -- see unknowns below if one ' +
 	'was found) -- FastAPI generates operation ids at request-handling time (per-project, sometimes via a ' +
@@ -277,10 +305,27 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 			// login.py, which declares `APIRouter(tags=["login"])` with no prefix at all, so a
 			// prefix-derived name fails on a real file while the filename stem works for every one.
 			const moduleName = path.basename(file, '.py');
-			const basePath = extractBasePath(text);
-			const endpoints = extractEndpoints(text).map((ep) => ({ ...ep, path: joinPath(basePath, ep.path) }));
-			if (endpoints.length > 0) {
-				moduleEntry(moduleName).controllers.push({ className: `${capitalize(moduleName)}Router`, basePath, operationIds: [], endpoints, file });
+			const routerPrefixes = extractRouterPrefixes(text);
+			const rawEndpoints = extractEndpoints(text);
+
+			// D-fastapi-multi-router-per-file: group by the router variable each decorator actually
+			// belongs to (not the file as a whole) -- a decorator on a router variable this file never
+			// itself declares (e.g. imported from elsewhere, or a same-file `include_router()` alias)
+			// falls back to '' rather than guessing, same as the pre-fix single-router behavior.
+			const byRouterVar = new Map();
+			for (const ep of rawEndpoints) {
+				if (!byRouterVar.has(ep.routerVar)) byRouterVar.set(ep.routerVar, []);
+				byRouterVar.get(ep.routerVar).push(ep);
+			}
+
+			for (const [routerVar, eps] of byRouterVar) {
+				const basePath = routerPrefixes.get(routerVar) ?? '';
+				const endpoints = eps.map((ep) => ({ verb: ep.verb, path: joinPath(basePath, ep.path), operationId: ep.operationId, method: ep.method, line: ep.line }));
+				// the common case (single router per file, conventionally named "router") keeps the
+				// existing className exactly as before -- only a second/other-named router variable
+				// gets a distinguishing className derived from its own identifier.
+				const className = routerVar === 'router' ? `${capitalize(moduleName)}Router` : `${pascalCase(routerVar)}`;
+				moduleEntry(moduleName).controllers.push({ className, basePath, operationIds: [], endpoints, file });
 			}
 		}
 

package/scanners/adapters/typescript-express.mjs

@@ -89,6 +89,20 @@ function listTypeScriptFiles(projectRoot) {
 // of `router.use('/literal', subRouter)` mount edges from a graph root down to the leaf file. This
 // extracts just the LOCAL endpoints (verb/path/handler/line) with an EMPTY prefix -- the mount-tree
 // walk in scanTypeScriptExpress() below joins the real prefix chain afterward.
+//
+// D-typescript-express-inline-handlers: an inline function expression (`router.get('/x', async
+// (req, res) => {...})`) is a DIFFERENT shape from a bare-identifier handler reference
+// (`router.get('/x', show)`) -- confirmed live, dogfooding against a real, popular repo
+// (gothinkster/node-express-realworld-example-app, 3,796 real GitHub stars): ALL 19 of its real
+// route registrations use this inline form, and the bare-identifier-only gate this comment used to
+// describe found ZERO of them (verdict: greenfield on a repo with a real, complete REST API).
+// `method: null` (not a synthesized/guessed name) marks this case -- there is no export to
+// correlate an inline handler to, and `handles/providers/typescript-express/plan.mjs`'s own
+// `resolveHandlerFile()` already has a real, tested `null`-propagates-to-"resolver not generated"
+// path for exactly this "handler correlates to nothing" case (see its own Update note in
+// DECISIONS.md) -- this is NOT a new failure mode, just a new, real way to reach the existing one.
+const INLINE_HANDLER_RE = /^(?:async\s+)?(?:\([^)]*\)|[$\w]+)\s*(?::[^=]*)?=>|^(?:async\s+)?function\b/;
+
 function extractEndpoints(text) {
 	const endpoints = [];
 	for (const m of text.matchAll(VERB_CALL_RE)) {
@@ -102,13 +116,14 @@ function extractEndpoints(text) {
 
 		const args = splitTopLevelArgs(argsText);
 		const lastArg = args[args.length - 1]?.trim();
-		// A bare identifier only -- an inline arrow-function handler has no name to correlate to a
-		// controller file, so it's skipped rather than guessed at (same discipline as FastAPI's own
-		// "no path literal -> skip").
 		const handlerMatch = lastArg?.match(/^(\w+)$/);
-		if (!handlerMatch) continue;
+		const isInlineHandler = !handlerMatch && lastArg && INLINE_HANDLER_RE.test(lastArg);
+		// Neither a bare identifier nor a recognizable inline function expression (e.g. a member
+		// expression like `controller.show`, or something built dynamically) -- skip rather than
+		// guess, same discipline as the missing-path-literal case just above.
+		if (!handlerMatch && !isInlineHandler) continue;
 
-		endpoints.push({ verb, path: pathMatch[1], operationId: null, method: handlerMatch[1], line: lineNumberAt(text, m.index) });
+		endpoints.push({ verb, path: pathMatch[1], operationId: null, method: handlerMatch ? handlerMatch[1] : null, line: lineNumberAt(text, m.index) });
 	}
 	return endpoints;
 }