backend-skeleton 1.1.0 → 1.2.0

package/scanners/adapters/python-fastapi.mjs

@@ -23,7 +23,14 @@ 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;
+
+// D-fastapi-generic-module-name: real evidence only (polarsource/polar), not a speculative list --
+// same "validated against a real oracle" precedent as KNOWN_DTO_SUFFIXES below. 57 real files
+// literally named `endpoints.py`, 1 named `router.py`; no other generic stem (`routes`, `views`,
+// `api`) has ever been observed.
+const GENERIC_ROUTER_STEMS = new Set(['endpoints', 'router']);
 const CLASS_RE = /^class\s+(\w+)\s*\(([^)]*)\)\s*:/gm;
 const INCLUDE_ROUTER_RE = /include_router\s*\(/g;
 
@@ -104,24 +111,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 +159,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 +282,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 ' +
@@ -259,8 +293,59 @@ const API_SURFACE_SOURCE = 'router-local paths only (this scan does not resolve
 	'document via `bskel contract emit --openapi-file <path> --path-prefix <prefix>` for trustworthy ' +
 	'operation identity and schemas.';
 
+// D-fastapi-generic-module-name: real polarsource/polar dogfooding found `path.basename(file,
+// '.py')` (the module-name rule below) collapses to the literal string "endpoints"/"router" for
+// every file using that repo's own real, common convention -- name every router file generically,
+// carry the real domain identity in the PARENT DIRECTORY instead (`organization/endpoints.py`,
+// `member/endpoints.py`). Two CLOSED passes, not interleaved -- a generic file's directory-derived
+// candidate must never be adopted before every non-generic file's own literal name is known, or a
+// later-discovered collision could arrive too late (the wrong merge would already be written).
+// Pass 1: every non-generic-stem file's own literal name is `reserved`, unchanged from today.
+// Pass 2: a generic-stem file's candidate (its own parent directory's basename) is adopted only if
+// it collides with neither `reserved` nor another generic file's already-`claimed` candidate --
+// real evidence found 9 such real collisions in polar alone (e.g. `subscription/endpoints.py`'s
+// candidate "subscription" collides with the real, unrelated, non-generic
+// `customer_portal/endpoints/subscription.py`). On any collision, the file keeps its old literal
+// generic name -- never guess into a silent wrong merge. `files` is already sorted by full path
+// (`listRgFiles`), so processing order (and therefore first-claim-wins) is deterministic.
+function resolveGenericModuleNames(files, readFile, projectRoot) {
+	const routerFiles = [];
+	const reserved = new Set();
+	for (const file of files) {
+		if (!/APIRouter\s*\(/.test(readFile(file))) continue;
+		const stem = path.basename(file, '.py');
+		routerFiles.push(file);
+		if (!GENERIC_ROUTER_STEMS.has(stem)) reserved.add(stem);
+	}
+
+	const moduleNameByFile = new Map();
+	const claimed = new Set();
+	for (const file of routerFiles) {
+		const stem = path.basename(file, '.py');
+		if (!GENERIC_ROUTER_STEMS.has(stem)) {
+			moduleNameByFile.set(file, stem);
+			continue;
+		}
+		const dir = path.dirname(file);
+		const candidate = dir !== projectRoot ? path.basename(dir) : null;
+		if (candidate && !reserved.has(candidate) && !claimed.has(candidate)) {
+			claimed.add(candidate);
+			moduleNameByFile.set(file, candidate);
+		} else {
+			moduleNameByFile.set(file, stem); // collision or no meaningful parent -- keep the old literal name
+		}
+	}
+	return moduleNameByFile;
+}
+
 export function scanPythonFastApi(repoRoot, projectRoot) {
 	const files = listPythonFiles(projectRoot);
+	const fileTextCache = new Map();
+	const readFile = (f) => {
+		if (!fileTextCache.has(f)) fileTextCache.set(f, fs.readFileSync(f, 'utf8'));
+		return fileTextCache.get(f);
+	};
+	const moduleNameByFile = resolveGenericModuleNames(files, readFile, projectRoot);
 	const modules = new Map();
 	const moduleEntry = (name) => {
 		if (!modules.has(name)) modules.set(name, { module: name, controllers: [], entities: [], enums: [], dtos: [] });
@@ -270,17 +355,36 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 	const allEntities = [];
 	const allDtos = [];
 	for (const file of files) {
-		const text = fs.readFileSync(file, 'utf8');
+		const text = readFile(file);
 
 		if (/APIRouter\s*\(/.test(text)) {
 			// module = filename stem, NOT the router's own prefix -- verified against the real oracle's
 			// 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 });
+			// D-fastapi-generic-module-name: for a GENERIC stem (`endpoints`/`router`), this is the
+			// collision-safe, directory-derived name instead -- see resolveGenericModuleNames() above.
+			const moduleName = moduleNameByFile.get(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;
 }

package/scanners/index.mjs

@@ -265,7 +265,7 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	}
 
 	return {
-		schema: 'sbf.scan-report/1',
+		schema: 'sbf.scan-report/2',
 		terms,
 		adapter,
 		confidence,

package/schemas/conformance-report.schema.json

@@ -30,7 +30,9 @@
         "matched": { "type": "integer", "minimum": 0, "description": "receipts whose contract_ref equals the CURRENT contract hash -- these count as evidence for the current contract." },
         "stale_contract_ref": { "type": "integer", "minimum": 0, "description": "receipts recorded against a contract_ref that no longer matches -- kept on record for audit/trend purposes, not counted as current evidence." },
         "violations": { "type": "integer", "minimum": 0 },
-        "unsupported": { "type": "integer", "minimum": 0 }
+        "unsupported": { "type": "integer", "minimum": 0 },
+        "unsigned": { "type": "integer", "minimum": 0, "description": "receipts with no signature field -- computed regardless of --pubkey, for forward visibility." },
+        "signature_invalid": { "type": "integer", "minimum": 0, "description": "receipts whose signature field failed verification -- only ever non-zero when --pubkey was given; meaningless (always 0) otherwise. Excluded from matched/violations, same as stale_contract_ref." }
       }
     },
     "by_operation": {
@@ -44,6 +46,15 @@
           "violations": { "type": "integer", "minimum": 0 }
         }
       }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Whether signature verification was even attempted at generation time -- without this, signature_invalid: 0 is ambiguous between 'verified, zero invalid' and 'never checked'. See D-runtime-conformance-receipts.",
+      "properties": {
+        "pubkey_given": { "type": "boolean" },
+        "require_signature": { "type": "boolean" }
+      }
     }
   }
 }

package/schemas/observe-receipt.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "urn:sbf:observe-receipt:1",
   "title": "backend-skeleton runtime contract-conformance receipt",
-  "description": "One JSONL line ContractObservationAspect logs per @ObserveContract-annotated call. Verdict-only, by design -- never carries an observed request/response VALUE, only pointers + constraint kinds. See DECISIONS.md D-runtime-conformance-receipts. `bskel observe import --receipts <path>` reads a stream of these.",
+  "description": "One JSONL line ContractObservationAspect logs per @ObserveContract-annotated call. Verdict-only, by design -- never carries an observed request/response VALUE, only pointers + constraint kinds. See DECISIONS.md D-runtime-conformance-receipts. `bskel observe import --receipts <path>` reads a stream of these. `signature` is optional -- unsigned receipts stay valid; `bskel observe import --pubkey <path>` opts into verifying it where present. See the D-runtime-conformance-receipts 'cryptographic receipt attestation' Update note.",
   "type": "object",
   "additionalProperties": false,
   "required": ["feature_id", "feature_uid", "operation_id", "contract_ref", "verb", "recorded_at", "violations"],
@@ -27,6 +27,15 @@
           "message": { "type": "string", "maxLength": 300 }
         }
       }
+    },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algorithm", "value"],
+      "properties": {
+        "algorithm": { "const": "ed25519" },
+        "value": { "type": "string", "description": "base64-encoded raw Ed25519 signature bytes over the canonicalized receipt (this field excluded)." }
+      }
     }
   }
 }

package/schemas/scan-report.schema.json

@@ -6,7 +6,7 @@
   "additionalProperties": false,
   "required": ["schema", "terms", "adapter", "verdict", "related_modules", "collisions", "unknowns", "files_read"],
   "properties": {
-    "schema": { "const": "sbf.scan-report/1" },
+    "schema": { "const": "sbf.scan-report/2" },
     "feature_id": { "type": "string" },
     "terms": { "type": "array", "items": { "type": "string" } },
     "adapter": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },