backend-skeleton 1.1.1 → 1.3.0

package/scanners/adapters/python-fastapi.mjs

@@ -12,7 +12,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { lineNumberAt, listRgFiles as sharedListRgFiles, byShallowestThenName } from '../text-util.mjs';
+import { lineNumberAt, listRgFiles as sharedListRgFiles, byShallowestThenName, binaryAvailable } from '../text-util.mjs';
 
 const PROJECT_FILE_GLOBS = ['pyproject.toml', 'requirements*.txt'];
 const EXCLUDE_GLOBS = ['!**/.venv/**', '!**/site-packages/**', '!**/node_modules/**', '!**/__pycache__/**'];
@@ -25,6 +25,12 @@ const FASTAPI_DEP_RE = /(?:^|[\s"'[])fastapi(?:\[[^\]]*\])?(?:[\s"',\]=<>~!;]|$)
 
 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;
 
@@ -287,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: [] });
@@ -298,13 +355,15 @@ 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');
+			// 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);
 
@@ -430,14 +489,12 @@ export const adapter = {
 		})) {
 			messages.push({ level: 'info', code: 'fastapi-not-a-dependency', message: `found ${depFiles.length} Python project file(s), but none declare a fastapi dependency` });
 		}
-		let rgOk = true;
-		try {
-			execFileSync('rg', ['--version'], { stdio: 'pipe' });
-		} catch {
-			rgOk = false;
-		}
-		if (!rgOk) {
-			messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it and will throw, not degrade, if it is missing' });
+		// D-zero-config-scan: traced live -- this does NOT throw at scan time as the message used to
+		// claim. detectPythonFastApiRoot()'s own rg shell-out is wrapped in a blanket try/catch that
+		// returns [] on failure, so a missing `rg` makes this adapter silently detect nothing
+		// (degrades to generic-grep) rather than crashing.
+		if (!binaryAvailable('rg')) {
+			messages.push({ level: 'warn', code: 'rg-missing', message: 'ripgrep (rg) is not on PATH -- this adapter shells out to it for file discovery and silently detects nothing without it (degrades to the generic-grep fallback), it does not throw' });
 		}
 		// D-openapi-extraction-hint: unlike java-spring, this adapter's own capabilities already
 		// declare `api.operations: false` (FastAPI assigns operationIds at runtime) -- --openapi-file

package/scanners/index.mjs

@@ -182,7 +182,12 @@ export function computeDbDrift(liveTables, relatedModules) {
 // every other env-var-driven input in this codebase is resolved at the bin/bskel.mjs layer, never
 // inside a "pure" lib/scanner function), and keeps this function synchronous (Plane C's real I/O
 // is `await`ed by the caller before ever calling this).
-export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, adapters = ADAPTERS }) {
+//
+// D-zero-config-scan: `rgAvailable` is the SAME kind of CLI-boundary-resolved input as `dbSchema`
+// -- bin/bskel.mjs computes it once via lib/doctor.mjs's binaryAvailable('rg') and hands it in as
+// plain data. Defaults to `true` so every existing call site (this whole test suite included)
+// stays byte-for-byte unchanged.
+export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, adapters = ADAPTERS, rgAvailable = true }) {
 	const detections = adapters
 		.map((a) => ({ a, d: a.detect(repoRoot) }))
 		.filter(({ d }) => d != null)
@@ -221,26 +226,73 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	// than crashing -- the gate token still falls back to hashing the report itself.
 	const filesRead = result.filesRead ?? [];
 
-	// O6: score alone isn't a deterministic sort key -- two modules tying on score fall back to
-	// whatever order they were already in, which traces back to non-deterministic rg discovery
-	// order in the adapters above (mitigated there too, but a second determinism layer here is
-	// cheap and doesn't depend on every adapter getting it right). Module name is a stable,
-	// meaningful secondary key.
-	const scored = modules
-		.map((m) => {
-			const { score, evidence, cappedSignals } = scoreModule(m, terms);
-			return { ...m, score, evidence, capped_signals: cappedSignals };
-		})
-		.sort((a, b) => b.score - a.score || a.module.localeCompare(b.module));
+	// D-zero-config-scan: an empty `terms` array is how bin/bskel.mjs's cmdScan signals its new
+	// zero-flag "inventory" mode (neither --terms nor --feature was given) -- every detected module
+	// is listed exactly as the adapter found it, with NO term-matching/scoring/collision-detection
+	// performed. Faking `score: 0` here would be actively misleading -- 0 already means "scored,
+	// found nothing" in the existing contract -- so each module is built as an explicit allowlist
+	// (never `{...m}`), which guarantees `score`/`evidence`/`capped_signals` are genuinely ABSENT
+	// from the object, not merely `undefined`, and stops any future adapter-internal field from
+	// leaking into this report shape by accident.
+	const isInventory = terms.length === 0;
+	let relatedModules;
+	let collisions;
+	let verdict;
+	if (isInventory) {
+		relatedModules = modules
+			.map((m) => ({ module: m.module, controllers: m.controllers, entities: m.entities, enums: m.enums, dtos: m.dtos }))
+			.sort((a, b) => a.module.localeCompare(b.module)); // deterministic -- no score to sort by
+		collisions = []; // not "nothing collides" -- nothing was CHECKED. See the disclaimer below.
+		verdict = 'inventory';
+	} else {
+		// O6: score alone isn't a deterministic sort key -- two modules tying on score fall back to
+		// whatever order they were already in, which traces back to non-deterministic rg discovery
+		// order in the adapters above (mitigated there too, but a second determinism layer here is
+		// cheap and doesn't depend on every adapter getting it right). Module name is a stable,
+		// meaningful secondary key.
+		const scored = modules
+			.map((m) => {
+				const { score, evidence, cappedSignals } = scoreModule(m, terms);
+				return { ...m, score, evidence, capped_signals: cappedSignals };
+			})
+			.sort((a, b) => b.score - a.score || a.module.localeCompare(b.module));
 
-	const relatedModules = scored.filter((m) => m.score > 0);
-	const collisions = relatedModules.filter((m) => m.score >= COLLISION_THRESHOLD);
+		relatedModules = scored.filter((m) => m.score > 0);
+		collisions = relatedModules.filter((m) => m.score >= COLLISION_THRESHOLD);
 
-	let verdict = 'greenfield';
-	if (collisions.length > 0) verdict = 'collision';
-	else if (relatedModules.length > 0) verdict = 'adjacent';
+		verdict = 'greenfield';
+		if (collisions.length > 0) verdict = 'collision';
+		else if (relatedModules.length > 0) verdict = 'adjacent';
+	}
 
 	const unknowns = [];
+	// D-zero-config-scan: the FIRST unknowns entry in inventory mode -- visible in --json too, not
+	// just prose a human might skim past -- so nothing downstream (human or agent) backfills a
+	// relevance/collision judgment this report never made. See D-greenfield-parameters's safe/
+	// unsafe line: every module/controller/entity listed below is a real, observed fact about this
+	// repo; this disclaimer is what keeps "here's what exists" from being read as "here's what's
+	// safe to build".
+	if (isInventory) {
+		unknowns.push(
+			'this is an unscored inventory of every module this adapter found -- no term-matching, ' +
+			'relevance scoring, or collision/greenfield classification was performed against any ' +
+			'specific feature idea. Re-run with --terms <keywords> or --feature <id> to check a ' +
+			'specific idea against this repo before treating anything here as "safe" or "colliding".',
+		);
+	}
+	// D-zero-config-scan: without `rg`, every real adapter's detect() silently degrades (a blanket
+	// try/catch around the rg shell-out returns [] on failure -- see scanners/text-util.mjs's
+	// listRgFiles()), so a real Spring/FastAPI/Express repo can look indistinguishable from one
+	// this tool genuinely doesn't recognize. `rg_available` (always present on the returned report,
+	// both modes) is the machine-checkable signal; this is the human-readable one.
+	if (!rgAvailable) {
+		unknowns.push(
+			'ripgrep (`rg`) was not found on PATH -- every real scanner adapter depends on it for file ' +
+			'discovery, so a low-confidence or apparently-empty result here may simply mean `rg` is ' +
+			'missing, not that this repo lacks recognizable backend structure. Install it (`brew ' +
+			'install ripgrep`) and re-run, or run `bskel doctor` for full diagnostics.',
+		);
+	}
 	if (!includeDb) {
 		unknowns.push('DB not scanned (Plane C is opt-in via --db --database-url-env <NAME>) -- pass --db to scan migration files, add --database-url-env for live introspection too. See A4 in CATALOG.md.');
 	} else if (!dbSchema?.live) {
@@ -265,12 +317,13 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	}
 
 	return {
-		schema: 'sbf.scan-report/1',
+		schema: 'sbf.scan-report/2',
 		terms,
 		adapter,
 		confidence,
 		api_surface_source: apiSurfaceSource,
 		verdict,
+		rg_available: rgAvailable,
 		path_prefix_signals: pathPrefixSignals,
 		related_modules: relatedModules,
 		collisions,

package/scanners/render.mjs

@@ -50,13 +50,22 @@ export function renderScanMarkdown(report) {
 	lines.push(`**Verdict**: \`${report.verdict}\``);
 	lines.push('');
 
+	// D-zero-config-scan: inventory mode has no term/collision semantics -- "greenfield for these
+	// terms" would be a lie when there were no terms to begin with, and a scored module's heading
+	// would dangle a `bskel scan explain` pointer that mode can never actually serve (it requires
+	// --feature, structurally unreachable here).
+	const isInventory = report.verdict === 'inventory';
 	if (report.related_modules.length === 0) {
-		lines.push('No related modules found -- greenfield for these terms.');
+		lines.push(isInventory
+			? `No modules detected by the \`${report.adapter}\` adapter in this repo.`
+			: 'No related modules found -- greenfield for these terms.');
 	} else {
-		lines.push('## Related modules');
+		lines.push(isInventory ? '## Modules found' : '## Related modules');
 		lines.push('');
 		for (const mod of report.related_modules) {
-			lines.push(`### \`${mod.module}\` (score: ${mod.score} -- run \`bskel scan explain ${mod.module}\` for the evidence breakdown)`);
+			lines.push(isInventory
+				? `### \`${mod.module}\``
+				: `### \`${mod.module}\` (score: ${mod.score} -- run \`bskel scan explain ${mod.module}\` for the evidence breakdown)`);
 			for (const c of mod.controllers) {
 				lines.push(`- Controller \`${c.className}\` (base path \`${c.basePath}\`), ${c.endpoints.length} endpoint(s):`);
 				for (const ep of c.endpoints) {

package/scanners/text-util.mjs

@@ -31,3 +31,25 @@ export function byShallowestThenName(a, b) {
 	const depthB = b.split(path.sep).length;
 	return depthA !== depthB ? depthA - depthB : a.localeCompare(b);
 }
+
+// D-zero-config-scan: the pure "is this binary on PATH" check, deliberately living HERE (a
+// leaf module with zero project-internal imports) rather than in lib/doctor.mjs, where it was
+// first written. lib/doctor.mjs imports lib/verify.mjs, which imports scanners/registry.mjs --
+// and every adapter file is dynamically import()ed BY registry.mjs's own top-level await. An
+// adapter importing lib/doctor.mjs would close that cycle (adapter -> lib/doctor.mjs ->
+// lib/verify.mjs -> scanners/registry.mjs -> [import()s the adapter]) and registry.mjs's OWN
+// header comment already flags exactly this risk ("no adapter imports anything from this
+// module" -- true of registry.mjs itself, but lib/doctor.mjs transitively reaches it). Found
+// live: the first version of this change put binaryAvailable() in lib/doctor.mjs and every
+// adapter import of it hung the whole CLI (a real "Detected unsettled top-level await" Node
+// warning, reproduced against a real fixture repo, not a hypothetical). lib/doctor.mjs now
+// re-exports this for its own existing callers (bin/bskel.mjs, its own binaryCheck()) --
+// nothing outside this file needs to know it moved.
+export function binaryAvailable(name, execFn = execFileSync) {
+	try {
+		execFn(name, ['--version'], { stdio: 'pipe' });
+		return true;
+	} catch {
+		return false;
+	}
+}

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/pattern-record.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:pattern-record:1",
+  "title": "backend-skeleton pattern-accrual record (sbf_pattern.params, one row)",
+  "description": "D-pattern-accrual: one real `bskel new --record-pattern` invocation, recorded into a database the user owns and named via --pattern-database-url-env -- never bskel's own repo state. `params` holds ONLY the flag values new/index.mjs's reusableParamsFor(stack) names for that stack (the user-typed CLI value, not a resolved/defaulted one) -- keyed by the exact flag name (e.g. `java-version`, not `javaVersion`), so `bskel pattern suggest`'s output is always a literal, paste-ready `--flag value` pair. Validated on both write (patterns/store.mjs's recordPattern) and read (listPatterns/getPattern) -- the patch-approvals.mjs doctrine.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "pattern_id", "stack", "params", "recorded_at"],
+  "properties": {
+    "schema": { "const": "sbf.pattern/1" },
+    "pattern_id": { "type": "string", "format": "uuid" },
+    "stack": { "enum": ["spring", "fastapi"] },
+    "params": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "recorded_at": { "type": "string", "format": "date-time" }
+  }
+}

package/schemas/scan-report.schema.json

@@ -6,19 +6,23 @@
   "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-]*$" },
     "confidence": { "enum": ["high", "low"] },
     "api_surface_source": { "type": "string" },
-    "verdict": { "enum": ["greenfield", "adjacent", "collision"] },
+    "verdict": { "enum": ["greenfield", "adjacent", "collision", "inventory"] },
+    "rg_available": {
+      "description": "D-zero-config-scan: whether `rg` (ripgrep) was found on PATH when this scan ran -- every real adapter's detect() silently degrades without it (see scanners/text-util.mjs's listRgFiles()), so this is the machine-checkable signal that distinguishes 'this repo genuinely has no recognizable backend structure' from 'rg is just missing'. Optional (not in the top-level `required` array below) purely because older/hand-written report objects predate this field -- every report `runScan()` itself produces always sets it.",
+      "type": "boolean"
+    },
     "path_prefix_signals": { "type": "array" },
     "related_modules": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["module", "score"],
+        "required": ["module"],
         "properties": {
           "module": { "type": "string" },
           "score": { "type": "number" },