backend-skeleton 1.2.0 → 1.3.0

package/contracts/csv.mjs

@@ -0,0 +1,100 @@
+// D-contract-csv: a spreadsheet-shaped projection of a feature contract -- one row per operation,
+// opened by someone who will never read a JSON Schema. Pure module, no I/O, no gate awareness, no
+// process -- mirrors contracts/export.mjs's own contract (see that file's header comment) exactly,
+// so this file can be unit-tested with hand-built `contract` objects and nothing else.
+//
+// C1: a fixed 14-column header, always -- see C2 in DECISIONS.md for why a column is never
+// dropped just because every operation leaves it blank (a scan-only contract's `summary`/`tags`/
+// `security` columns ARE the finding "nobody stated these", not something to hide by omitting the
+// column). C3: `description` is deliberately NOT a column (measured average 2,442.7 bytes/op,
+// larger than every other copied field combined -- see D-openapi-description).
+export const CSV_COLUMNS = Object.freeze([
+	{ name: 'operation_id', extract: (op, operationId) => operationId },
+	{ name: 'verb', extract: (op) => op.verb },
+	{ name: 'path', extract: (op) => op.path },
+	{ name: 'path_params', extract: (op) => sortedKeys(op.pathParams?.properties).join(', ') },
+	{ name: 'path_params_unverified', extract: (op) => (op.pathParamsHeuristic ?? []).join(', ') },
+	{ name: 'body', extract: (op) => String(op.body) },
+	{ name: 'request_body_required', extract: (op) => (op.requestBodyRequired == null ? '' : String(op.requestBodyRequired)) },
+	{ name: 'request_body_fields', extract: (op) => sortedKeys(op.requestBodySchema?.properties).join(', ') },
+	{ name: 'response_fields', extract: (op) => sortedKeys(op.responseSchema?.properties).join(', ') },
+	{ name: 'error_fields', extract: (op) => sortedKeys(op.errorSchema?.properties).join(', ') },
+	{ name: 'provenance', extract: (op) => op.provenance },
+	{ name: 'summary', extract: (op) => op.sourceSummary ?? '' },
+	{ name: 'tags', extract: (op) => (op.sourceTags ?? []).join(', ') },
+	{ name: 'security', extract: (op) => extractSecurity(op.sourceSecurity) },
+]);
+
+function sortedKeys(properties) {
+	return properties ? Object.keys(properties).sort() : [];
+}
+
+// `security: []` is a genuine positive claim ("this operation declared no auth requirement") --
+// see schemas/feature-contract.schema.json's own sourceSecurity description. An ABSENT
+// sourceSecurity means the source document said nothing about security for this operation at all.
+// The two must render distinguishably, or a reviewer cannot tell "confirmed open" from "unknown".
+function extractSecurity(sourceSecurity) {
+	if (sourceSecurity == null) return '';
+	if (sourceSecurity.length === 0) return '(source-declared: none)';
+	const schemeNames = new Set();
+	for (const requirement of sourceSecurity) {
+		for (const scheme of Object.keys(requirement)) schemeNames.add(scheme);
+	}
+	return [...schemeNames].sort().join(', ');
+}
+
+// C4: RFC 4180, hand-rolled -- quote a field iff it contains a double quote, comma, CR, or LF;
+// an embedded double quote is escaped by doubling it. Deliberately does NOT quote a field that
+// needs none of this (the negative case is what catches an over-eager escaper in tests). No new
+// dependency: this is the entire rule CSV has needed since RFC 4180 (2005).
+export function escapeCsvField(value) {
+	const str = String(value);
+	if (/["\n\r,]/.test(str)) {
+		return `"${str.replaceAll('"', '""')}"`;
+	}
+	return str;
+}
+
+// C4: LF line terminator (not RFC 4180's CRLF) -- every other artifact this project writes is
+// LF, and these files get committed/diffed. No comment/provenance preamble: line 1 is always the
+// header row, because a leading `#`/comment line breaks `pandas.read_csv`/`csv.DictReader`/every
+// spreadsheet importer's default settings -- provenance goes to stderr/`--json`, never into the
+// file itself.
+export function toCsv(header, rows) {
+	const lines = [header, ...rows].map((row) => row.map(escapeCsvField).join(','));
+	return `${lines.join('\n')}\n`;
+}
+
+// C5: deliberately does NOT check gate state, does NOT read a scan report, does NOT look at
+// path-prefix signals -- this is a pure projection of an already-loaded `contract` object. The
+// caller (bin/bskel.mjs's cmdContractExportCsv) owns every refusal/warning decision; this
+// function only ever succeeds or reports "there's nothing to export" for a genuinely empty
+// contract.
+export function buildContractCsv({ contract }) {
+	const operationIds = Object.keys(contract.operations).sort((a, b) => a.localeCompare(b));
+	if (operationIds.length === 0) {
+		return { ok: false, error: 'contract has zero operations' };
+	}
+
+	const header = CSV_COLUMNS.map((c) => c.name);
+	const rows = operationIds.map((operationId) => {
+		const op = contract.operations[operationId];
+		return CSV_COLUMNS.map((c) => c.extract(op, operationId));
+	});
+
+	// C2: coverage is reported alongside the file, never inferred by a reader staring at blank
+	// cells wondering whether the tool is broken.
+	const columns = CSV_COLUMNS.map((c, i) => ({
+		name: c.name,
+		populatedRows: rows.filter((row) => row[i] !== '').length,
+	}));
+	const emptyColumns = columns.filter((c) => c.populatedRows === 0).map((c) => c.name);
+
+	return {
+		ok: true,
+		csv: toCsv(header, rows),
+		rowCount: rows.length,
+		columns,
+		emptyColumns,
+	};
+}

package/lib/cli.mjs

@@ -241,6 +241,33 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-contract-csv: deliberately fewer flags than `contract export` -- no `--allow-unprefixed`
+	// (there is no hard refusal here to override, only a warning that always fires), no
+	// `--status-codes` (not an OpenAPI-shaped concept). `--bom` is CSV-specific: opt-in UTF-8 BOM
+	// for Excel-on-Windows, see D-contract-csv in DECISIONS.md.
+	'contract export-csv': {
+		usage: 'bskel contract export-csv --feature <id> [--out <path>] [--bom] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			out: { type: 'string', default: null },
+			bom: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-db-erd: the other "recognizable artifact" export, read-only, repo-independent like
+	// `bskel new` (no --feature -- the database plane is not feature-scoped, see E6 in D-db-erd,
+	// DECISIONS.md). Deliberately no `--db` flag: `db` IS the verb, so it's implied -- internally
+	// reuses `resolveDbSchemaOrExit(root, {...flags, db:true})` unchanged, so env-var handling and
+	// error strings stay byte-identical to `scan --db`.
+	'db erd': {
+		usage: 'bskel db erd [--database-url-env <NAME>] [--schema public] [--out <path>] [--json]',
+		options: {
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			out: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	// D-contract-history: read-only, so no --module/--openapi-file/etc -- it only ever reads what
 	// git already recorded for this feature's own contract file.
 	'contract history': {
@@ -425,12 +452,18 @@ export const COMMANDS = {
 	// nobody actually asked for. The real defaults live in new/spring.mjs / new/fastapi.mjs, one
 	// place each.
 	new: {
-		usage: 'bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none]',
+		usage: 'bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none] [--record-pattern --pattern-database-url-env <NAME>]',
 		options: {
 			stack: { type: 'string', default: null, required: true },
 			slug: { type: 'string', default: null, required: true },
 			dir: { type: 'string', default: null },
 			offline: { type: 'boolean', default: false },
+			// D-pattern-accrual: both opt-in, both required together -- omitting either leaves
+			// `bskel new` byte-identical to today (no recording, no DB connection attempted). The
+			// actual write is best-effort (never fails the scaffold); only the "flag given but the
+			// other half missing / env var unset" usage mistake is checked before scaffold.
+			'record-pattern': { type: 'boolean', default: false },
+			'pattern-database-url-env': { type: 'string', default: null },
 
 			// Both stacks.
 			name: { type: 'string', default: null },
@@ -466,6 +499,34 @@ export const COMMANDS = {
 			'boot-version': { type: 'string', default: null, hidden: true },
 		},
 	},
+	// D-pattern-accrual: all three read-only, all requiring --pattern-database-url-env --
+	// there is no meaningful "run without a live connection" mode, same posture as `handles audit`
+	// (O7). Distinct flag name from every other command's --database-url-env: that flag always means
+	// the TARGET APPLICATION's database; this one is the user's own cross-project pattern store.
+	'pattern list': {
+		usage: 'bskel pattern list --pattern-database-url-env <NAME> [--stack spring|fastapi] [--json]',
+		options: {
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			stack: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'pattern show': {
+		usage: 'bskel pattern show <pattern_id> --pattern-database-url-env <NAME> [--json]',
+		options: {
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+		allowPositionals: true,
+	},
+	'pattern suggest': {
+		usage: 'bskel pattern suggest --stack spring|fastapi --pattern-database-url-env <NAME> [--json]',
+		options: {
+			stack: { type: 'string', default: null, required: true },
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'handles patch approve': {
 		usage: 'bskel handles patch approve --feature <id> [--module <name>] --resource <Type> --field <name> --strategy patch-wrapper|null-means-unchanged --reason "..." [--json]',
 		options: {

package/lib/doctor.mjs

@@ -2,10 +2,18 @@
 // D1's lib/workflow.mjs separates `computeWorkflowState()` from its cmdStatus/cmdNext callers --
 // this stays pure enough to unit test without spawning the CLI, and bin/bskel.mjs just renders
 // whatever this returns.
-import { execFileSync } from 'node:child_process';
 import { detectBuildCommand } from './verify.mjs';
 import { listCatalogChoices, loadCatalogEntry } from '../stack/apply.mjs';
 import { detectAstHelperAvailable } from '../handles/providers/java-spring/ast-bridge.mjs';
+// D-zero-config-scan: re-exported from scanners/text-util.mjs (a cycle-free leaf module), NOT
+// defined here -- this file transitively imports scanners/registry.mjs (via ./verify.mjs), which
+// dynamically import()s every scanner adapter; an adapter importing binaryAvailable() FROM here
+// would close that cycle. See scanners/text-util.mjs's own comment on binaryAvailable() for the
+// real hang this caused before the fix. Every existing caller of `binaryAvailable` from this file
+// (bin/bskel.mjs) needs no change -- it's still available at this same import path.
+import { binaryAvailable } from '../scanners/text-util.mjs';
+
+export { binaryAvailable };
 
 // D5: the three workflows that have tool requirements beyond "git + a supported Node runtime"
 // (every workflow needs those two -- preflight/contract don't need anything ELSE, so they're
@@ -34,15 +42,8 @@ function nodeVersionOk(versionString) {
 }
 
 function binaryCheck(name, { required, remediation }) {
-	let ok = true;
-	let detail = '';
-	try {
-		execFileSync(name, ['--version'], { stdio: 'pipe' });
-	} catch {
-		ok = false;
-		detail = 'not found on PATH';
-	}
-	return { name: `binary: ${name}`, required, ok, detail, remediation: ok ? null : remediation };
+	const ok = binaryAvailable(name);
+	return { name: `binary: ${name}`, required, ok, detail: ok ? '' : 'not found on PATH', remediation: ok ? null : remediation };
 }
 
 function nodeVersionCheck() {

package/lib/workflow.mjs

@@ -78,6 +78,12 @@ function awaitingDispositionCommand(gateName, featureId) {
 // been exercised through `next` recommending the real `conformance`-gate command, so a real
 // `mutating: false` misclassification on a command that actually writes files + passes a gate went
 // unnoticed) -- see D-field-dependency's COST section in DECISIONS.md.
+// D-pattern-accrual: `bskel new`/`bskel pattern list|show|suggest` were deliberately checked
+// against this same gap (per this comment's own warning above) and found NOT to need an entry
+// here or in ESTABLISH_COMMAND -- none of the four corresponds to a GATE_NAMES gate (`new` predates
+// any feature/gate existing at all; the three `pattern` verbs are a repo-independent, cross-project
+// read surface `next`/`status` never has reason to recommend). `handles audit` (O7) is the existing
+// precedent for a read-only command correctly staying out of this list.
 const MUTATING_PREFIXES = [
 	'bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive',
 	'bskel gate force', 'bskel dependency declare', 'bskel dependency remove', 'bskel handles emit',

package/new/index.mjs

@@ -9,6 +9,13 @@
 // parameters it accepts and which it explicitly refuses), and deliberately still a plain object.
 // The reason two first-party stacks don't justify a registry hasn't changed just because each entry
 // grew three fields.
+//
+// D-pattern-accrual: a FOURTH field, `reusableParams` -- the subset of `acceptedParams` worth
+// persisting to a user-owned pattern store when they opt in via `--record-pattern`. Deliberately a
+// subset, not `acceptedParams` itself: per-project identity (`name`/`description`/`project-version`,
+// spring's `artifact-id`/`package-name`) describes THIS project, not a reusable convention, and
+// storing project names in a database buys nothing (see D-pattern-accrual's own EXIT for the full
+// list and why each exclusion is drawn).
 import { scaffoldSpring } from './spring.mjs';
 import { scaffoldFastapi } from './fastapi.mjs';
 
@@ -39,6 +46,10 @@ export const STACKS = Object.freeze({
 			'dependencies', 'add-dependencies',
 		]),
 		refusedParams: SPRING_REFUSED_PARAMS,
+		// D-pattern-accrual: `group-id` is the one per-project-identity-shaped field kept in
+		// (unlike `artifact-id`/`package-name`) -- an organization's group id is itself a reusable
+		// convention (`com.ourco`, applied to every project), not a name unique to this one project.
+		reusableParams: Object.freeze(['java-version', 'packaging', 'dependencies', 'add-dependencies', 'group-id']),
 	}),
 	fastapi: Object.freeze({
 		id: 'fastapi',
@@ -46,9 +57,18 @@ export const STACKS = Object.freeze({
 		requiresNetwork: false,
 		acceptedParams: Object.freeze([...COMMON_PARAMS, 'python-version', 'port', 'license', 'database']),
 		refusedParams: Object.freeze({}),
+		reusableParams: Object.freeze(['python-version', 'port', 'license', 'database']),
 	}),
 });
 
+// D-pattern-accrual: the one place `bskel new`'s best-effort recording call and `bskel pattern
+// suggest` both look up which flags are worth persisting for a stack -- never re-derived, never a
+// hand-copied list at either call site.
+export function reusableParamsFor(stackId) {
+	const stack = STACKS[stackId];
+	return stack ? stack.reusableParams : [];
+}
+
 // Every parameter any stack knows about -- the set cmdNew checks a passed flag against to decide
 // "wrong stack" vs. "not a stack parameter at all". Derived, never a hand-maintained third list.
 export const ALL_STACK_PARAMS = Object.freeze([...new Set(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "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",
@@ -26,6 +26,7 @@
     "handles/",
     "new/",
     "stack/",
+    "patterns/",
     "schemas/",
     "scripts/preflight-base-ref.sh",
     "LICENSE",
@@ -38,6 +39,8 @@
     "test:java-compile": "node scripts/java-compile-smoke.mjs",
     "test:python-import": "node scripts/python-import-smoke.mjs",
     "test:db-introspect": "node scripts/db-introspect-smoke.mjs",
+    "test:pattern-db": "node scripts/pattern-db-smoke.mjs",
+    "test:db-erd": "node scripts/db-erd-smoke.mjs",
     "test:registry-coverage": "node scripts/handles-registry-coverage-smoke.mjs",
     "test:ddl-apply": "node scripts/ddl-apply-smoke.mjs",
     "test:cross-feature-fk": "node scripts/cross-feature-fk-smoke.mjs",
@@ -48,7 +51,7 @@
     "test:spring-initializr-canary": "node scripts/spring-initializr-canary.mjs",
     "test:shadow-validation": "node scripts/shadow-validation-smoke.mjs",
     "test:oracle-corpus": "node scripts/shadow-validation-smoke.mjs --manifest test/fixtures/oracle-manifest.json",
-    "test:all-smoke": "npm test && npm run test:pack && npm run test:java-compile && npm run test:java-integration && npm run test:python-import && npm run test:python-integration && npm run test:db-introspect && npm run test:registry-coverage && npm run test:ddl-apply && npm run test:cross-feature-fk && npm run test:java-ast && npm run test:typescript-compile"
+    "test:all-smoke": "npm test && npm run test:pack && npm run test:java-compile && npm run test:java-integration && npm run test:python-import && npm run test:python-integration && npm run test:db-introspect && npm run test:pattern-db && npm run test:db-erd && npm run test:registry-coverage && npm run test:ddl-apply && npm run test:cross-feature-fk && npm run test:java-ast && npm run test:typescript-compile"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/patterns/schema.sql

@@ -0,0 +1,18 @@
+-- D-pattern-accrual: the sbf_pattern table `bskel new --record-pattern` writes to and
+-- `bskel pattern list/show/suggest` read from. This is a database YOU own for YOUR OWN
+-- projects' conventions -- bskel never creates it automatically (D-migration-scope: the same
+-- "detect the missing table, name this exact file, never auto-DDL" posture handles/migration.sql.tmpl
+-- already established for sbf_handle/sbf_handle_snapshot). Run this by hand, once, against
+-- whatever Postgres database --pattern-database-url-env will point at.
+--
+-- `params` is JSONB, not one column per parameter, because the accepted parameter set differs
+-- per stack (new/index.mjs's reusableParams) and grows independently of this table's own schema --
+-- adding a stack, or widening a stack's reusableParams, needs zero migration here.
+CREATE TABLE IF NOT EXISTS sbf_pattern (
+	pattern_id UUID PRIMARY KEY,
+	stack TEXT NOT NULL,
+	params JSONB NOT NULL,
+	recorded_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS sbf_pattern_stack_idx ON sbf_pattern (stack);

package/patterns/store.mjs

@@ -0,0 +1,122 @@
+// D-pattern-accrual: a database the USER owns for THEIR OWN past `bskel new` invocations --
+// never bskel's own repo state, never a shared/external source (see D-pattern-accrual's own WHY
+// for the line this draws against `.bskel/config.yml`'s standing refusal). Reuses A4/D-db-schema-plane's
+// own `pg`/connection conventions unchanged: one `pg.Client`, sequential queries, `BEGIN TRANSACTION
+// READ ONLY` on every read path (structural defense-in-depth, same as scanners/db/introspect.mjs and
+// handles/audit.mjs). The one write path here (recordPattern) is a plain INSERT, no transaction
+// needed for a single statement.
+import pg from 'pg';
+import { randomUUID } from 'node:crypto';
+import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
+
+const { Client } = pg;
+
+// Postgres error code for "relation does not exist" -- the real, expected shape when
+// patterns/schema.sql was never applied to this database (D-migration-scope: bskel never applies
+// it automatically). Byte-identical convention to handles/audit.mjs's own isMissingHandleTables.
+const UNDEFINED_TABLE = '42P01';
+
+export function isMissingPatternTable(err) {
+	return err?.code === UNDEFINED_TABLE;
+}
+
+function rowToRecord(row) {
+	return {
+		schema: 'sbf.pattern/1',
+		pattern_id: row.pattern_id,
+		stack: row.stack,
+		params: row.params,
+		recorded_at: row.recorded_at instanceof Date ? row.recorded_at.toISOString() : row.recorded_at,
+	};
+}
+
+function validateRecord(record) {
+	const { ok, errors } = validateAgainstSchema('pattern-record.schema.json', record);
+	if (!ok) {
+		throw new Error(`refusing to write invalid pattern record:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+}
+
+// `params` here is already the raw, user-typed CLI flag values for whatever
+// `new/index.mjs`'s reusableParamsFor(stack) names -- the caller (cmdNew) owns filtering down to
+// that set; this function only validates the resulting record's shape and writes it. Best-effort
+// from the CALLER's perspective (bin/bskel.mjs never lets a failure here fail `bskel new` itself) --
+// this function itself throws on any real failure, same as every other patterns/store.mjs function.
+export async function recordPattern({ connectionString, stack, params }) {
+	const record = {
+		schema: 'sbf.pattern/1',
+		pattern_id: randomUUID(),
+		stack,
+		params,
+		recorded_at: new Date().toISOString(),
+	};
+	validateRecord(record);
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query(
+			'INSERT INTO sbf_pattern (pattern_id, stack, params, recorded_at) VALUES ($1, $2, $3, $4)',
+			[record.pattern_id, record.stack, JSON.stringify(record.params), record.recorded_at],
+		);
+	} finally {
+		await client.end();
+	}
+	return record;
+}
+
+export async function listPatterns({ connectionString, stack = null }) {
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query('BEGIN TRANSACTION READ ONLY');
+		const sql = stack
+			? 'SELECT pattern_id, stack, params, recorded_at FROM sbf_pattern WHERE stack = $1 ORDER BY recorded_at DESC'
+			: 'SELECT pattern_id, stack, params, recorded_at FROM sbf_pattern ORDER BY recorded_at DESC';
+		const res = await client.query(sql, stack ? [stack] : []);
+		await client.query('COMMIT');
+		return res.rows.map(rowToRecord);
+	} finally {
+		await client.end();
+	}
+}
+
+export async function getPattern({ connectionString, patternId }) {
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query('BEGIN TRANSACTION READ ONLY');
+		const res = await client.query(
+			'SELECT pattern_id, stack, params, recorded_at FROM sbf_pattern WHERE pattern_id = $1',
+			[patternId],
+		);
+		await client.query('COMMIT');
+		return res.rows.length > 0 ? rowToRecord(res.rows[0]) : null;
+	} finally {
+		await client.end();
+	}
+}
+
+// Pure -- no DB access, unit-testable directly (test/pattern-store.test.mjs). For each name in
+// `reusableParams`, ranks every distinct value actually seen across `records` by how many records
+// carried it, denominator always `records.length` (the full recorded-run count for this stack,
+// NOT just the runs that happened to set this particular param -- an omitted param is real
+// information, not missing data). Never collapses to one "best" value -- see D-pattern-accrual's
+// WHY for the confidence-label posture this mirrors (D-cross-feature-collision).
+export function summarizePatternFrequency(records, reusableParams) {
+	const total = records.length;
+	const summary = [];
+	for (const param of reusableParams) {
+		const counts = new Map();
+		for (const record of records) {
+			const value = record.params[param];
+			if (value == null) continue;
+			counts.set(value, (counts.get(value) ?? 0) + 1);
+		}
+		if (counts.size === 0) continue;
+		const values = [...counts.entries()]
+			.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+			.map(([value, count]) => ({ value, count, total }));
+		summary.push({ param, values });
+	}
+	return summary;
+}

package/scanners/adapters/_express-shared.mjs

@@ -15,7 +15,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { listRgFiles as sharedListRgFiles, byShallowestThenName } from '../text-util.mjs';
+import { listRgFiles as sharedListRgFiles, byShallowestThenName, binaryAvailable } from '../text-util.mjs';
 
 export const EXCLUDE_GLOBS = ['!**/node_modules/**', '!**/dist/**', '!**/build/**'];
 export const VERBS = ['get', 'post', 'put', 'patch', 'delete'];
@@ -220,14 +220,12 @@ export function expressDiagnostics(repoRoot) {
 	} else if (!pkgFiles.some((f) => declaresExpress(f))) {
 		messages.push({ level: 'info', code: 'express-not-a-dependency', message: `found ${pkgFiles.length} package.json file(s), but none declare an express 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. detect()'s own rg shell-outs (e.g. listCandidatePackageFiles()) are 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. Corrected below.
+	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: like FastAPI, both Express adapters declare `api.operations:
 	// false` -- --openapi-file is load-bearing for `contract emit` to adopt any operation, not just

package/scanners/adapters/java-spring.mjs

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { lineNumberAt, listRgFiles, byShallowestThenName } from '../text-util.mjs';
+import { lineNumberAt, listRgFiles, byShallowestThenName, binaryAvailable } from '../text-util.mjs';
 import { maskNonCode, findClassOrRecordDeclaration, findClassLevelMappingArgs, findMappingAnnotations } from './_java-spring-analyzer.mjs';
 
 const JAVA_BUILD_FILE_GLOBS = ['build.gradle', 'build.gradle.kts', 'pom.xml'];
@@ -423,14 +423,12 @@ export const adapter = {
 		if (!srcRoot) {
 			messages.push({ level: 'info', code: 'no-src-main-java', message: buildFiles.length > 0 ? 'found a build file, but none has a sibling src/main/java' : 'src/main/java does not exist' });
 		} else {
-			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. detectJavaSpringRoot() itself (and every other rg shell-out at detect() time)
+			// 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: `contract emit --openapi-file` (A1-A12) is where real accuracy

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__/**'];
@@ -489,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