backend-skeleton 1.4.0 → 1.6.0

package/scanners/adapters/java-spring.mjs

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { lineNumberAt, listRgFiles, byShallowestThenName, binaryAvailable } from '../text-util.mjs';
-import { maskNonCode, findClassOrRecordDeclaration, findClassLevelMappingArgs, findMappingAnnotations } from './_java-spring-analyzer.mjs';
+import { maskNonCode, findClassOrRecordDeclaration, findClassLevelMappingArgs, findMappingAnnotations, matchBalanced, findInterfaceExtendsDeclaration, splitTopLevelTypeArgs } from './_java-spring-analyzer.mjs';
 
 const JAVA_BUILD_FILE_GLOBS = ['build.gradle', 'build.gradle.kts', 'pom.xml'];
 
@@ -36,6 +36,23 @@ export function detectJavaSpringRoot(repoRoot) {
 	return null;
 }
 
+// D-spring-data-rest-adapter: literal substring grep, the same shape as
+// handles/providers/java-spring/emit.mjs's hasSpringAopDependency() -- but here, at SCAN time, for
+// a different reason: @Entity/@RestController pair with spring-boot-starter-data-jpa/-web,
+// dependencies virtually every real Spring Boot app already has, so this adapter has never needed
+// to cross-check a dependency before trusting an annotation. @RepositoryRestResource is unusually
+// easy to add decoratively (copied from a tutorial) without the actual
+// spring-boot-starter-data-rest starter, and without it ALL 6 synthesized routes would be
+// fictional, not just one field -- severe enough to warrant a check no other annotation in this
+// adapter needs. Same version-drift fragility hasSpringAopDependency's own history found for a
+// different artifact name (D-handles-pilot-cohort) is inherited here, not re-solved.
+export function hasSpringDataRestDependency(repoRoot) {
+	for (const buildFile of listRgFiles(repoRoot, JAVA_BUILD_FILE_GLOBS)) {
+		if (fs.readFileSync(buildFile, 'utf8').includes('spring-boot-starter-data-rest')) return true;
+	}
+	return false;
+}
+
 // O6: `rg --files` (no `--sort`) is explicitly unordered/parallel by ripgrep's own docs -- two
 // runs against an unchanged repo can return files in a different order, which without this sort
 // would propagate into non-deterministic controller/entity/module array order in every scan
@@ -165,6 +182,128 @@ function extractController(text, filePath) {
 	return { className, basePath, operationIds, endpoints, file: filePath, line: classLine };
 }
 
+const SPRING_DATA_REPOSITORY_SUPERTYPES = new Set(['JpaRepository', 'CrudRepository', 'PagingAndSortingRepository']);
+
+// D-spring-data-rest-adapter: Spring Data REST auto-generates a full CRUD REST API from a
+// repository interface annotated @RepositoryRestResource -- a real, common pattern extractController()
+// above is blind to (it only ever recognizes @RestController classes, and interface declarations
+// aren't recognized anywhere else in this file either). Mirrors extractController()'s shape/style,
+// but gated on a completely different annotation and declaration keyword. Populates
+// controller.declarations[]/endpoint.declarationIndex (see D-route-expansion-provenance) -- this
+// is the first adapter to do so. Every skip below is a deliberate "don't guess" refusal, not a
+// missing feature -- see this item's own DECISIONS.md entry for the full rationale per case.
+function extractRepositoryResource(text, filePath, hasDataRestDependency) {
+	if (!/@RepositoryRestResource\b/.test(text)) return { controller: null, note: null };
+
+	const masked = maskNonCode(text);
+	const decl = findInterfaceExtendsDeclaration(masked);
+	if (!decl || !SPRING_DATA_REPOSITORY_SUPERTYPES.has(decl.superName)) {
+		return { controller: null, note: null };
+	}
+	const declLine = lineNumberAt(text, decl.index);
+
+	if (!hasDataRestDependency) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: @RepositoryRestResource found on ${decl.name}, but no spring-boot-starter-data-rest dependency was found in this repo's build.gradle/build.gradle.kts/pom.xml -- Spring Data REST would not actually be active, so no routes are synthesized for this repository.`,
+		};
+	}
+
+	if (decl.typeArgsStart == null || decl.typeArgsEnd == null) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: @RepositoryRestResource found on ${decl.name}, but its "extends ${decl.superName}<...>" generic type arguments could not be parsed -- the entity type is unknown, so no routes are synthesized.`,
+		};
+	}
+	const typeArgs = splitTopLevelTypeArgs(masked.slice(decl.typeArgsStart, decl.typeArgsEnd));
+	if (typeArgs.length < 2) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: @RepositoryRestResource found on ${decl.name}, but "extends ${decl.superName}<...>" does not declare both an entity and id type -- no routes are synthesized.`,
+		};
+	}
+	const entityName = typeArgs[0];
+
+	// The annotation's own argument text -- scoped so a positional bare-quote grab (like
+	// extractQuotedOrValue() elsewhere in this file) can't accidentally pick a DIFFERENT string
+	// attribute (@RepositoryRestResource also has e.g. collectionResourceRel) instead of `path`.
+	const annotationMatch = masked.match(/@RepositoryRestResource\s*\(/);
+	let explicitPath = null;
+	if (annotationMatch) {
+		const openParen = annotationMatch.index + annotationMatch[0].length - 1;
+		const closeParen = matchBalanced(masked, openParen, '(', ')');
+		if (closeParen !== -1) {
+			const argsText = text.slice(openParen + 1, closeParen);
+			const pathMatch = argsText.match(/path\s*=\s*"([^"]*)"/);
+			if (pathMatch) explicitPath = pathMatch[1];
+		}
+	}
+	if (!explicitPath) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: @RepositoryRestResource on ${decl.name} has no explicit path="..." attribute -- Spring's default (an English-pluralized entity name) is not guessed here. Add path="..." and re-scan.`,
+		};
+	}
+
+	// Any interface-body override of an inherited CRUD action (e.g. `@Override @RestResource(exported
+	// = false) void deleteById(...)`) changes which of the 6 standard routes are actually exposed --
+	// safely determining WHICH action(s) that affects is out of scope, so the whole repository is
+	// refused rather than risk a partially-wrong route set (a resolver pointing at something that
+	// 404s/405s in the real app is worse than no resolver at all).
+	const bodyOpenBrace = masked.indexOf('{', decl.index);
+	const bodyCloseBrace = bodyOpenBrace !== -1 ? matchBalanced(masked, bodyOpenBrace, '{', '}') : -1;
+	const bodyText = bodyOpenBrace !== -1 && bodyCloseBrace !== -1 ? masked.slice(bodyOpenBrace, bodyCloseBrace) : '';
+	if (/@RestResource\b/.test(bodyText)) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: ${decl.name} overrides at least one CRUD method with @RestResource(...) -- which specific action(s) that suppresses or renames can't be safely determined by static scanning, so no routes are synthesized for this repository at all (a partially-correct route set is worse than none).`,
+		};
+	}
+
+	const basePath = `/${explicitPath.replace(/^\/+|\/+$/g, '')}`;
+	const declarations = [{
+		rule: 'java-spring:repository-rest-resource-crud',
+		line: declLine,
+		label: `@RepositoryRestResource(path="${explicitPath}") on ${decl.name}`,
+	}];
+	// D-spring-data-rest-adapter (SR2): operationId is bskel's OWN synthesized, self-describing
+	// label -- not a verified claim about what a real springdoc-generated document would call the
+	// same operation (that was never measured). A real --openapi-file document using a different
+	// name for the same route degrades to the existing CONTRACT_OPENAPI_MISSING_OPERATION warning
+	// every other operationId mismatch already produces, not a new failure mode. The synthesized,
+	// truthy operationId is what lets handles/providers/java-spring/plan.mjs's findFetchOperation()
+	// find these routes at all -- that function needed zero code changes (see SR3).
+	const ROUTES = [
+		{ verb: 'GET', path: basePath, suffix: 'CollectionResource' },
+		{ verb: 'POST', path: basePath, suffix: 'CollectionResource' },
+		{ verb: 'GET', path: `${basePath}/{id}`, suffix: 'ItemResource' },
+		{ verb: 'PUT', path: `${basePath}/{id}`, suffix: 'ItemResource' },
+		{ verb: 'PATCH', path: `${basePath}/{id}`, suffix: 'ItemResource' },
+		{ verb: 'DELETE', path: `${basePath}/{id}`, suffix: 'ItemResource' },
+	];
+	const endpoints = ROUTES.map((r) => ({
+		verb: r.verb,
+		path: r.path,
+		operationId: `${r.verb.toLowerCase()}${entityName}${r.suffix}`,
+		method: null,
+		line: declLine,
+		declarationIndex: 0,
+	}));
+
+	return {
+		controller: {
+			className: decl.name,
+			basePath,
+			operationIds: endpoints.map((e) => e.operationId),
+			endpoints,
+			declarations,
+			file: filePath,
+			line: declLine,
+		},
+		note: null,
+	};
+}
+
 // D-entity-id-field-inheritance: found live against a real corpus check (spring-projects/
 // spring-petclinic) -- `Owner extends Person extends BaseEntity`, and `@Id` lives on `BaseEntity`
 // (a `@MappedSuperclass`), the standard, textbook JPA pattern for sharing an id/audit-field base
@@ -344,6 +483,13 @@ export function scanJavaSpring(repoRoot) {
 		return modules.get(key);
 	};
 
+	// D-spring-data-rest-adapter (SR5): computed once per scan, not per file -- a repo-wide,
+	// multi-module-aware check (same discovery detectJavaSpringRoot() already uses), not the
+	// single-root-file-only shape handles/providers/java-spring/emit.mjs's own
+	// hasSpringAopDependency() has.
+	const hasDataRestDependency = hasSpringDataRestDependency(repoRoot);
+	const repositoryResourceNotes = [];
+
 	for (const file of files) {
 		const text = fileTexts.get(file);
 		const mod = moduleOf(file, srcRoot, basePackage);
@@ -356,6 +502,11 @@ export function scanJavaSpring(repoRoot) {
 			const entity = extractEntity(text, file, classIndex);
 			if (entity) moduleEntry(mod).entities.push(entity);
 		}
+		if (/@RepositoryRestResource\b/.test(text)) {
+			const { controller, note } = extractRepositoryResource(text, file, hasDataRestDependency);
+			if (controller) moduleEntry(mod).controllers.push(controller);
+			if (note) repositoryResourceNotes.push(note);
+		}
 		if (mod && file.includes(`${path.sep}domain${path.sep}`) && /public\s+enum\s+\w+/.test(text)) {
 			const en = extractDomainEnum(text, file);
 			if (en) moduleEntry(mod).enums.push(en);
@@ -370,7 +521,7 @@ export function scanJavaSpring(repoRoot) {
 	// drift, and every other manifest-shaped gate input in this codebase (stack's `applied_file:`)
 	// is repo-relative too.
 	const filesRead = files.map((f) => path.relative(repoRoot, f));
-	return { srcRoot, modules: [...modules.values()], pathPrefixSignals: detectGlobalPathPrefixSignals(repoRoot), filesRead };
+	return { srcRoot, modules: [...modules.values()], pathPrefixSignals: detectGlobalPathPrefixSignals(repoRoot), filesRead, repositoryResourceNotes };
 }
 
 // G1: adapter descriptor consumed by scanners/registry.mjs -- see D-adapter-registry in
@@ -397,7 +548,7 @@ export const adapter = {
 	detect: detectJavaSpringRoot,
 	scan(repoRoot, _detection) {
 		const result = scanJavaSpring(repoRoot);
-		return { modules: result.modules, pathPrefixSignals: result.pathPrefixSignals, filesRead: result.filesRead };
+		return { modules: result.modules, pathPrefixSignals: result.pathPrefixSignals, filesRead: result.filesRead, repositoryResourceNotes: result.repositoryResourceNotes };
 	},
 	// S2 (D-gate-precision, continued): reuses the EXACT same listJavaFiles() call scan() itself
 	// makes -- no separate file-walking logic -- so the `scan` gate's staleness token can re-derive

package/scanners/index.mjs

@@ -218,6 +218,10 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	const confidence = chosen.confidence;
 	const modules = result.modules;
 	const pathPrefixSignals = result.pathPrefixSignals ?? [];
+	// D-spring-data-rest-adapter (SR4): the first per-adapter diagnostic-message passthrough into
+	// unknowns[] -- optional (`?? []`) so an adapter that doesn't populate it degrades to "nothing
+	// to report" rather than throwing, the same discipline apiSurfaceSource/filesRead already use.
+	const repositoryResourceNotes = result.repositoryResourceNotes ?? [];
 	const apiSurfaceSource = result.apiSurfaceSource ?? DEFAULT_API_SURFACE_SOURCE;
 	// S2 (D-gate-precision, continued): the adapter's own real read-set, persisted so
 	// lib/gate-definitions.mjs's `scan` gate can hash it for a precise staleness token instead of
@@ -301,6 +305,12 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	if (dbSchema?.live) {
 		unknowns.push(...computeDbDrift(dbSchema.live.tables, relatedModules));
 	}
+	// D-spring-data-rest-adapter (SR4): each entry names a repository the adapter recognized
+	// (found @RepositoryRestResource) but refused to synthesize routes for, and why -- a
+	// deliberate "don't guess" boundary, never silent.
+	if (repositoryResourceNotes.length > 0) {
+		unknowns.push(...repositoryResourceNotes);
+	}
 	// A1 §7: this scan can't correct a global path prefix (only --openapi-file's real-document
 	// reconciliation can, see D-openapi-reconciliation) -- but it CAN tell a user who doesn't know
 	// that flag exists that the defect is likely present, before they ever emit a wrong contract.

package/schemas/feature-contract.schema.json

@@ -7,7 +7,7 @@
   "additionalProperties": false,
   "required": ["sbf_contract", "feature_id", "feature_uid", "source", "operations", "warnings", "completeness"],
   "properties": {
-    "sbf_contract": { "const": "8" },
+    "sbf_contract": { "const": "9" },
     "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
     "feature_uid": { "type": "string", "format": "uuid" },
     "source": {
@@ -104,6 +104,17 @@
             "type": "array",
             "items": { "type": "string" }
           },
+          "expansion": {
+            "description": "X2 (D-route-expansion-provenance): present only when this operation's scan endpoint was expanded from a multi-route declaration recognized by the scan adapter (e.g. a future Rails/Laravel-style resource declaration, or a Spring Data REST @RepositoryRestResource) -- omitted for every ordinary 1:1 declared endpoint. `rule` is a namespaced <adapter-id>:<rule-slug> naming the expansion pattern; `declarationLine` is the single source line of the declaration itself (not this operation's own route); `label` is an optional human-readable description, null when not worth composing one.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["rule", "declarationLine"],
+            "properties": {
+              "rule": { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" },
+              "declarationLine": { "type": "integer", "minimum": 1 },
+              "label": { "type": ["string", "null"] }
+            }
+          },
           "sourceDescription": {
             "description": "A10: the operation's `description`, copied verbatim from a real source document. Present only when `contract emit --descriptions` (opt-in, unlike every other source-backed field in this schema) was passed AND the source document declared one for this exact operation AND it did not exceed the length cap.",
             "type": "string"

package/schemas/gate-attestation.schema.json

@@ -15,7 +15,12 @@
       "required": ["algorithm", "value"],
       "properties": {
         "algorithm": { "const": "ed25519" },
-        "value": { "type": "string", "description": "base64-encoded raw Ed25519 signature bytes over canonicalize(report)." }
+        "value": { "type": "string", "description": "base64-encoded raw Ed25519 signature bytes over canonicalize(report)." },
+        "key_id": {
+          "type": "string",
+          "pattern": "^ed25519:[0-9a-f]{32}$",
+          "description": "D-attestation-payload-completeness (K6): a SELECTION HINT, not a trust claim. It sits OUTSIDE the signed bytes (only `report` is signed) and is therefore attacker-modifiable -- `bskel attest verify` uses it only to produce a better error message when the wrong --pubkey is supplied. Verification depends solely on the signature over canonicalize(report)."
+        }
       }
     }
   }