backend-skeleton 1.0.0-beta.1

package/scanners/capabilities.mjs

@@ -0,0 +1,90 @@
+// G1: the fixed capability vocabulary a scanner adapter can declare support for, and which
+// capabilities a CLI command needs before it's allowed to run adapter-specific codegen. Adding a
+// capability here touches zero adapter files (an adapter that doesn't mention it is `false` by
+// construction, via schemas/adapter.schema.json's additionalProperties:{type:'boolean'} +
+// fail-closed reads elsewhere) -- and adding an adapter never touches this file. See
+// D-adapter-registry in DECISIONS.md.
+export const CAPABILITIES = Object.freeze({
+	'api.operations': {
+		summary: 'endpoints carry a source-pinned, non-null operationId',
+		why: 'a contract operation must be addressable by id -- generic-grep\'s route-pattern grep never correlates one (operationId is always null by construction, see D-generic-grep-reconnaissance in DECISIONS.md)',
+	},
+	'api.request-shape': {
+		summary: '`controller.file` + `ep.method` are present and re-readable as source, so request-body shape is derivable',
+		why: 'declared for documentation, not enforced -- its absence already degrades gracefully to body: "unknown" (see contracts/emit.mjs)',
+	},
+	'resource.fetch': {
+		summary: 'the IR carries persistence entities (table/idField) and a canonical single-resource GET is identifiable',
+		why: 'handle codegen needs to know what to fetch, and by what key',
+	},
+	'codegen.handles': {
+		summary: 'a handle codegen provider exists for this adapter\'s stack',
+		why: 'two providers exist today (java-spring, python-fastapi) -- see D-handles-providers (G4) in DECISIONS.md; a stack without one still fails this capability honestly rather than pretending',
+	},
+});
+
+export const CAPABILITY_NAMES = Object.freeze(Object.keys(CAPABILITIES));
+
+// Which capabilities a command needs before it's allowed to touch adapter-specific codegen, and
+// which gate (if any) a human can `bskel gate force` past once they've hand-supplied the missing
+// artifact themselves.
+//
+// G4: `resource.fetch` moved OFF this list and onto each handles provider's own
+// `requiresCapabilities` (bin/bskel.mjs's requireProviderCapabilitiesOrExit) -- it was never a
+// property of the COMMAND, it was a property of what a codegen PROVIDER needs to do its job, and
+// a future provider could plausibly need a different capability set than "resource.fetch". This
+// list is purely dispatch: does a provider exist at all for this adapter.
+export const COMMAND_CAPABILITIES = Object.freeze({
+	'contract emit': Object.freeze(['api.operations']),
+	'handles plan': Object.freeze(['codegen.handles']),
+	'handles emit': Object.freeze(['codegen.handles']),
+});
+
+export const COMMAND_GATE = Object.freeze({
+	'contract emit': 'contract',
+	'handles plan': 'handles',
+	'handles emit': 'handles',
+});
+
+// G2: data, not a per-adapter special case -- a capability a weak adapter can't earn statically
+// can still be legitimately satisfied by an explicit CLI flag that supplies the missing ground
+// truth from elsewhere. Today's one instance: `api.operations` (a real OpenAPI document supplies
+// operation identity a static scan of e.g. python-fastapi honestly cannot -- see D-fastapi-adapter
+// in DECISIONS.md). Expressed here, once, as a frozen map keyed by capability -- so
+// `requireCapabilitiesOrExit()` and `explainMissingCapability()` never need to know which
+// ADAPTER this applies to. Any adapter (including a future one) with the same honest weakness
+// benefits automatically; this is deliberately NOT java-spring/python-fastapi-specific.
+export const CAPABILITY_SATISFIERS = Object.freeze({
+	'api.operations': {
+		flag: 'openapi-file',
+		note: 'a real OpenAPI document can supply operation identity a weak adapter cannot derive statically -- ' +
+			'retry with --openapi-file <path> (and --path-prefix <prefix>, if this repo applies a global prefix ' +
+			'the document\'s own paths already include but this adapter could not resolve on its own -- ' +
+			'otherwise every endpoint stays unresolved with reason "prefix-inconclusive", see ' +
+			'D-openapi-reconciliation in DECISIONS.md)',
+	},
+});
+
+// Pure and exported so a test can assert the message shape without shelling out. `scanReportPath`
+// is an absolute path, matching this codebase's existing "no scan report at <abs path>"-style
+// messages (bin/bskel.mjs's loadScanReportOrExit).
+export function explainMissingCapability({ adapterId, capability, command, featureId, scanReportPath }) {
+	const cap = CAPABILITIES[capability];
+	const gate = COMMAND_GATE[command];
+	const satisfier = CAPABILITY_SATISFIERS[capability];
+	const lines = [
+		`blocked: \`bskel ${command}\` requires the \`${capability}\` capability, which the \`${adapterId}\` ` +
+			`adapter -- the adapter that produced ${scanReportPath} -- does not declare.`,
+		'',
+		`  ${capability}: ${cap.summary}. ${cap.why}.`,
+		'',
+		'Nothing was written.',
+		'',
+		'What you can do:',
+	];
+	if (satisfier) lines.push(`  - ${satisfier.note}.`);
+	lines.push('  - run `bskel doctor` -- it reports why each installed adapter did or did not detect this repo.');
+	lines.push(`  - hand-write the required artifact against its schema yourself, then \`bskel gate force ${gate} --feature ${featureId} --reason "..."\` if you're confident it's correct.`);
+	lines.push('  - no adapter/codegen provider exists for this stack yet -- see G2/G4 in CATALOG.md.');
+	return lines.join('\n');
+}

package/scanners/conformance.mjs

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+
+// P4 (D-extension-conformance): a reusable conformance check for a scanner adapter -- usable by a
+// third-party adapter author, not just this project's own 3 shipped adapters, before shipping
+// one. Checks the behavioral contract scanners/registry.mjs's schema validation can't (detect/
+// scan are functions, JSON Schema has no vocabulary for them): detect() doesn't throw, a truthy
+// detect() is followed by a scan() whose shape matches what scanners/index.mjs::runScan() actually
+// consumes (`result.modules`, each module carrying `module`/`controllers`/`entities`/`enums`),
+// and -- never machine-verified anywhere in this codebase before this -- that scan() is actually
+// deterministic: two consecutive calls against the same repoRoot return deep-equal results, the
+// exact property every shipped adapter's own `.sort()` calls exist to guarantee (O6), previously
+// only a code-review-level belief, not a checked one.
+export function checkAdapterConformance(adapter, repoRoot) {
+	const errors = [];
+	let detection;
+	try {
+		detection = adapter.detect(repoRoot);
+	} catch (err) {
+		errors.push(`detect() threw: ${err.message}`);
+		return { adapter: adapter.id, ok: false, errors };
+	}
+	if (detection == null) {
+		// A falsy detect() means this adapter doesn't claim this repoRoot -- nothing further to
+		// check (mirrors runScan()'s own `.filter(({ d }) => d != null)`).
+		return { adapter: adapter.id, ok: true, errors: [] };
+	}
+
+	let first;
+	try {
+		first = adapter.scan(repoRoot, detection);
+	} catch (err) {
+		errors.push(`scan() threw: ${err.message}`);
+		return { adapter: adapter.id, ok: false, errors };
+	}
+	if (!first || !Array.isArray(first.modules)) {
+		errors.push('scan() must return { modules: Array } -- runScan() reads result.modules directly');
+		return { adapter: adapter.id, ok: false, errors };
+	}
+	for (const mod of first.modules) {
+		for (const field of ['module', 'controllers', 'entities', 'enums']) {
+			if (!(field in mod)) errors.push(`scan() module ${JSON.stringify(mod.module ?? '(unknown)')} is missing required field "${field}"`);
+		}
+	}
+
+	let second;
+	try {
+		second = adapter.scan(repoRoot, detection);
+	} catch (err) {
+		errors.push(`scan() threw on its second, back-to-back call: ${err.message}`);
+		return { adapter: adapter.id, ok: false, errors };
+	}
+	try {
+		assert.deepStrictEqual(second, first);
+	} catch {
+		errors.push('scan() is not deterministic -- two consecutive calls against the same repoRoot returned different results (check for an un-sorted directory listing or Set/Map iteration order)');
+	}
+
+	return { adapter: adapter.id, ok: errors.length === 0, errors };
+}

package/scanners/db/introspect.mjs

@@ -0,0 +1,109 @@
+// A4 (D-db-schema-plane): Plane C -- live Postgres introspection. The one place in this whole
+// tool that opens a network connection to something other than a git remote/GitHub API. Reads the
+// connection string ONLY from `process.env[databaseUrlEnv]` at call time -- NEVER from `.env`
+// directly (this codebase's own convention, and Team-IZ-Backend's own CLAUDE.md `.env` caution).
+// `pg` is this project's first-ever SQL dependency -- confirmed no existing dependency does SQL.
+import pg from 'pg';
+import { sha256String } from '../../lib/fsutil.mjs';
+
+const { Client } = pg;
+
+// information_schema is the SQL-standard view (portable across schemas/versions); pg_indexes and
+// pg_policies are Postgres-specific catalog views with no information_schema equivalent for
+// indexes/RLS. All four queries are parameterized on `schemaName` -- never string-interpolated --
+// even though `schemaName` here only ever comes from a CLI flag this process's own owner typed,
+// not untrusted network input; parameterizing anyway costs nothing and is simply correct SQL
+// hygiene, matching this project's own "parameterized queries only" global rule (CLAUDE.md §6).
+const TABLES_SQL = `SELECT table_name FROM information_schema.tables WHERE table_schema = $1 AND table_type = 'BASE TABLE' ORDER BY table_name`;
+const COLUMNS_SQL = `SELECT table_name, column_name, data_type, is_nullable FROM information_schema.columns WHERE table_schema = $1 ORDER BY table_name, ordinal_position`;
+const PRIMARY_KEYS_SQL = `
+	SELECT tc.table_name, kcu.column_name
+	FROM information_schema.table_constraints tc
+	JOIN information_schema.key_column_usage kcu
+		ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+	WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_schema = $1
+	ORDER BY tc.table_name, kcu.ordinal_position`;
+const FOREIGN_KEYS_SQL = `
+	SELECT
+		tc.table_name, kcu.column_name,
+		ccu.table_name AS foreign_table_name, ccu.column_name AS foreign_column_name
+	FROM information_schema.table_constraints tc
+	JOIN information_schema.key_column_usage kcu
+		ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+	JOIN information_schema.constraint_column_usage ccu
+		ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+	WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_schema = $1
+	ORDER BY tc.table_name, kcu.column_name`;
+const INDEXES_SQL = `SELECT tablename AS table_name, indexname AS index_name FROM pg_indexes WHERE schemaname = $1 ORDER BY tablename, indexname`;
+const RLS_POLICIES_SQL = `SELECT tablename AS table_name, policyname AS policy_name FROM pg_policies WHERE schemaname = $1 ORDER BY tablename, policyname`;
+
+function groupByTable(rows, tableKey = 'table_name') {
+	const map = new Map();
+	for (const row of rows) {
+		const key = row[tableKey];
+		if (!map.has(key)) map.set(key, []);
+		map.get(key).push(row);
+	}
+	return map;
+}
+
+// A real, live-tested Node quirk (not hypothetical): a refused TCP connection surfaces as an
+// `AggregateError` (dual-stack IPv6+IPv4 connection attempts, both failing) whose own top-level
+// `.message` is an EMPTY STRING -- `.code` (e.g. `ECONNREFUSED`) and `.errors[]` (the individual
+// per-address failures) carry the actual information. A plain `err.message` alone would surface
+// nothing useful to the user here; this builds a real message from whichever shape the error is.
+export function describeConnectionError(err) {
+	if (err.message) return err.message;
+	if (Array.isArray(err.errors) && err.errors.length > 0) {
+		return err.errors.map((e) => e.message).join('; ');
+	}
+	return err.code ?? String(err);
+}
+
+// Entry point. `connectionString` is whatever `process.env[databaseUrlEnv]` resolved to -- the
+// caller (scanners/index.mjs) owns reading that env var and failing loudly if it's unset; this
+// function only ever receives an already-resolved string. `BEGIN TRANSACTION READ ONLY` is
+// structural defense-in-depth -- every query here is already a SELECT, but a read-only
+// transaction means the database itself refuses any write this connection could ever attempt,
+// not just "we didn't write any queries that would".
+export async function introspectSchema({ connectionString, schema = 'public' }) {
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query('BEGIN TRANSACTION READ ONLY');
+
+		// Sequential, not Promise.all -- a single pg.Client processes one query at a time over one
+		// connection; issuing several concurrently on the same client is deprecated (pg queues them
+		// internally today, but warns, and that queuing behavior is going away in pg 9). A Pool
+		// would allow real concurrency, but this is a one-shot CLI invocation, not a long-lived
+		// server -- the simplicity of one client, one connection, sequential queries is the right
+		// trade-off here, not premature optimization for concurrency nothing needs.
+		const tablesRes = await client.query(TABLES_SQL, [schema]);
+		const columnsRes = await client.query(COLUMNS_SQL, [schema]);
+		const pkRes = await client.query(PRIMARY_KEYS_SQL, [schema]);
+		const fkRes = await client.query(FOREIGN_KEYS_SQL, [schema]);
+		const indexesRes = await client.query(INDEXES_SQL, [schema]);
+		const policiesRes = await client.query(RLS_POLICIES_SQL, [schema]);
+
+		await client.query('COMMIT');
+
+		const columnsByTable = groupByTable(columnsRes.rows);
+		const pkByTable = groupByTable(pkRes.rows);
+		const fkByTable = groupByTable(fkRes.rows);
+		const indexesByTable = groupByTable(indexesRes.rows);
+		const policiesByTable = groupByTable(policiesRes.rows);
+
+		const tables = tablesRes.rows.map(({ table_name: name }) => ({
+			name,
+			columns: (columnsByTable.get(name) ?? []).map((c) => ({ name: c.column_name, type: c.data_type, nullable: c.is_nullable === 'YES' })),
+			primary_key: (pkByTable.get(name) ?? []).map((r) => r.column_name),
+			foreign_keys: (fkByTable.get(name) ?? []).map((r) => ({ column: r.column_name, references_table: r.foreign_table_name, references_column: r.foreign_column_name })),
+			indexes: (indexesByTable.get(name) ?? []).map((r) => r.index_name),
+			rls_policies: (policiesByTable.get(name) ?? []).map((r) => r.policy_name),
+		}));
+
+		return { schema, tables, schema_hash: sha256String(JSON.stringify(tables)) };
+	} finally {
+		await client.end();
+	}
+}

package/scanners/db/migrations.mjs

@@ -0,0 +1,126 @@
+// A4 (D-db-schema-plane): Plane A -- migration-file scanning, always local, never a network call.
+// Deliberately NOT a real SQL parser -- same "good-enough regex, not a real parser" restraint as
+// A2's Java analyzer and G2's Python analyzer, bounded to what real Flyway/Liquibase repos
+// actually look like, not general SQL. Confirmed against the real oracle repo (Team-IZ-Backend)
+// that it has ZERO migration files of either kind -- this module is unverifiable against it and
+// is built/tested entirely against a synthetic fixture instead (see DECISIONS.md D-db-schema-plane).
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+function listRgFiles(repoRoot, glob) {
+	try {
+		return execFileSync('rg', ['--files', '-g', glob, repoRoot], { encoding: 'utf8' }).split('\n').filter(Boolean).sort();
+	} catch {
+		return []; // rg exits 1 on "no files matched" -- not an error
+	}
+}
+
+// Same balanced-paren algorithm as python-fastapi.mjs's own local matchBalancedParens() and
+// _java-spring-analyzer.mjs's matchBalanced() -- a third, deliberately separate copy, matching
+// this project's own established precedent (see python-fastapi.mjs's own comment) of NOT reaching
+// across an unrelated module boundary for a five-line algorithm; SQL is a different language from
+// either of those, sharing the module would be a false economy.
+function matchBalancedParens(text, openIndex) {
+	let depth = 0;
+	for (let i = openIndex; i < text.length; i++) {
+		if (text[i] === '(') depth++;
+		else if (text[i] === ')') {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+
+// Splits a column-definition list on top-level commas only -- `VARCHAR(255)`/`NUMERIC(10,2)`/
+// `CHECK (price > 0)` all carry their own parens that must not be mistaken for a column separator.
+function splitTopLevelCommas(text) {
+	const parts = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < text.length; i++) {
+		if (text[i] === '(') depth++;
+		else if (text[i] === ')') depth = Math.max(0, depth - 1);
+		else if (text[i] === ',' && depth === 0) {
+			parts.push(text.slice(start, i));
+			start = i + 1;
+		}
+	}
+	const last = text.slice(start);
+	if (last.trim()) parts.push(last);
+	return parts.map((p) => p.trim()).filter(Boolean);
+}
+
+const CREATE_TABLE_RE = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(\w+)"?\s*\(/gi;
+const ALTER_ADD_COLUMN_RE = /ALTER\s+TABLE\s+"?(\w+)"?\s+ADD\s+COLUMN\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(\w+)"?/gi;
+// A column definition line's own leading constraint keywords never name a column -- skips them so
+// e.g. `PRIMARY KEY (id, org_id)` isn't mistaken for a column named "primary".
+const CONSTRAINT_LEAD_RE = /^(PRIMARY\s+KEY|FOREIGN\s+KEY|UNIQUE|CHECK|CONSTRAINT)\b/i;
+const COLUMN_NAME_RE = /^"?(\w+)"?/;
+
+function extractTablesFromSql(sqlText, sourceFile) {
+	const tables = new Map(); // name -> Set<column>
+
+	CREATE_TABLE_RE.lastIndex = 0;
+	let m;
+	while ((m = CREATE_TABLE_RE.exec(sqlText))) {
+		const tableName = m[1];
+		const openParen = m.index + m[0].length - 1;
+		const closeParen = matchBalancedParens(sqlText, openParen);
+		if (closeParen === -1) continue; // malformed -- skip, don't misattribute
+		const body = sqlText.slice(openParen + 1, closeParen);
+		const columns = new Set();
+		for (const segment of splitTopLevelCommas(body)) {
+			if (CONSTRAINT_LEAD_RE.test(segment)) continue;
+			const colMatch = segment.match(COLUMN_NAME_RE);
+			if (colMatch) columns.add(colMatch[1]);
+		}
+		if (!tables.has(tableName)) tables.set(tableName, new Set());
+		for (const c of columns) tables.get(tableName).add(c);
+	}
+
+	ALTER_ADD_COLUMN_RE.lastIndex = 0;
+	while ((m = ALTER_ADD_COLUMN_RE.exec(sqlText))) {
+		const [, tableName, columnName] = m;
+		if (!tables.has(tableName)) tables.set(tableName, new Set());
+		tables.get(tableName).add(columnName);
+	}
+
+	return [...tables.entries()].map(([name, columns]) => ({ name, columns: [...columns].sort(), source_file: sourceFile }));
+}
+
+// Entry point. Returns `{ tool, files, tables }` -- `tool: 'none'` (empty files/tables) is a real,
+// expected, and reported outcome, not an error -- most real repos (including the oracle repo
+// itself) have no migration-file convention at all; their schema lives elsewhere (JPA ddl-auto,
+// or -- the oracle repo's actual case -- entirely outside this repo, in an external Supabase
+// project).
+export function scanMigrations(repoRoot) {
+	const flywayFiles = listRgFiles(repoRoot, '**/db/migration/**/*.sql');
+	const liquibaseFiles = listRgFiles(repoRoot, '**/db/changelog/**/*.{xml,yaml,yml,sql}');
+
+	if (flywayFiles.length === 0 && liquibaseFiles.length === 0) {
+		return { tool: 'none', files: [], tables: [] };
+	}
+
+	if (flywayFiles.length > 0) {
+		const tables = [];
+		for (const file of flywayFiles) {
+			const text = fs.readFileSync(file, 'utf8');
+			tables.push(...extractTablesFromSql(text, path.relative(repoRoot, file)));
+		}
+		return { tool: 'flyway', files: flywayFiles.map((f) => path.relative(repoRoot, f)), tables };
+	}
+
+	// Liquibase changelogs are DETECTED (filenames recorded) but not deep-parsed in this first
+	// pass -- XML/YAML changeSet parsing is a materially larger, separate job than Flyway's plain
+	// SQL files; recording their presence is still real value over today's total silence, and is
+	// an honestly documented gap, not a silent guess (see DECISIONS.md D-db-schema-plane).
+	const sqlLiquibaseFiles = liquibaseFiles.filter((f) => f.endsWith('.sql'));
+	const tables = [];
+	for (const file of sqlLiquibaseFiles) {
+		const text = fs.readFileSync(file, 'utf8');
+		tables.push(...extractTablesFromSql(text, path.relative(repoRoot, file)));
+	}
+	return { tool: 'liquibase', files: liquibaseFiles.map((f) => path.relative(repoRoot, f)), tables };
+}