backend-skeleton 1.2.0 → 1.3.0

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) {
@@ -271,6 +323,7 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 		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/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

@@ -12,13 +12,17 @@
     "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" },