backend-skeleton 1.0.0 → 1.1.0

package/scanners/adapters/javascript-express.mjs

@@ -226,10 +226,40 @@ function resolveEsmImport(fromFile, specifier, suffixes) {
 	return null;
 }
 
-// `export default router;` -- which locally-declared mountable a file hands to whoever imports it.
-function defaultExportedMountable(text, mountables) {
-	const m = text.match(/export\s+default\s+([\w$]+)\s*;?/);
-	return m && mountables.has(m[1]) ? m[1] : null;
+// D-javascript-express-adapter (Update): found by the same shadow-validation-style audit that
+// closed D-module-attribution-base-package's own EXIT item for this adapter -- cross-file mount
+// resolution only ever recognized `export default router;`, a real but narrower limitation than
+// java-spring's own moduleOf() bug (endpoints still get FOUND either way, only their prefix goes
+// unresolved). A router handed off via a bare named export (`export { router };`) or an
+// export-prefixed declaration (`export const router = Router();`, ordinary and common) previously
+// had no path to being recognized as this file's "the" exported mountable at all.
+//
+// Three real ways a module hands a locally-declared mountable to whoever imports it -- `export
+// { router as r }` aliasing is deliberately NOT resolved, same restraint as this file's own
+// `Router as R` import-aliasing decision (D-javascript-express-adapter COST): a documented, narrow
+// limitation, not a silent guess at which local name an alias refers to.
+function exportedMountableName(text, mountables) {
+	const defaultMatch = text.match(/export\s+default\s+([\w$]+)\s*;?/);
+	if (defaultMatch && mountables.has(defaultMatch[1])) return defaultMatch[1];
+	const namedMatch = text.match(/export\s*\{\s*([\w$]+)\s*\}/);
+	if (namedMatch && mountables.has(namedMatch[1])) return namedMatch[1];
+	const exportedDeclMatch = text.match(/\bexport\s+(?:const|let|var)\s+([\w$]+)\s*=/);
+	if (exportedDeclMatch && mountables.has(exportedDeclMatch[1])) return exportedDeclMatch[1];
+	return null;
+}
+
+// `import target from '...'` (default) OR `import { target } from '...'` (named, unaliased) --
+// two real ways an imported mountable's LOCAL name reaches this file. `import { target as alias }`
+// is deliberately not resolved, same restraint as exportedMountableName's own aliasing decision
+// above -- a bare, unaliased single-name clause only, matching this file's existing default-import
+// regex's own narrow scope (never a general multi-specifier import-clause parser).
+function importSourceFor(text, target) {
+	const defaultImportRe = new RegExp(`import\\s+${target}\\s*(?:,\\s*\\{[^}]*\\})?\\s*from\\s*["']([^"']+)["']`);
+	const defaultMatch = text.match(defaultImportRe);
+	if (defaultMatch) return defaultMatch[1];
+	const namedImportRe = new RegExp(`import\\s*\\{\\s*${target}\\s*\\}\\s*from\\s*["']([^"']+)["']`);
+	const namedMatch = text.match(namedImportRe);
+	return namedMatch ? namedMatch[1] : null;
 }
 
 // Builds the mount graph over (file, variable) nodes. Two edge kinds, both from the same
@@ -261,13 +291,12 @@ function buildMountEdges(files, fileInfo, suffixes) {
 				edges.push({ from: nodeKey(file, fromVar), to: nodeKey(file, target), prefix: pathMatch[1] });
 				continue;
 			}
-			const importRe = new RegExp(`import\\s+${target}\\s*(?:,\\s*\\{[^}]*\\})?\\s*from\\s*["']([^"']+)["']`);
-			const importMatch = info.text.match(importRe);
-			if (!importMatch) continue;
-			const toFile = resolveEsmImport(file, importMatch[1], suffixes);
+			const importSource = importSourceFor(info.text, target);
+			if (!importSource) continue;
+			const toFile = resolveEsmImport(file, importSource, suffixes);
 			if (!toFile || !fileInfo.has(toFile)) continue;
 			const toInfo = fileInfo.get(toFile);
-			const toVar = defaultExportedMountable(toInfo.text, toInfo.mountables);
+			const toVar = exportedMountableName(toInfo.text, toInfo.mountables);
 			if (!toVar) continue;
 			edges.push({ from: nodeKey(file, fromVar), to: nodeKey(toFile, toVar), prefix: pathMatch[1] });
 		}
@@ -391,10 +420,14 @@ export const adapter = {
 	// walk), not how many capabilities it can offer. generic-grep is `low` because it has no module
 	// inference and no prefix resolution at all -- this adapter has both.
 	confidence: 'high',
-	// D-adapter-verification-basis: no real-world oracle at all, unlike every other real framework
-	// adapter -- the real target repository was deliberately never touched, and the committed
-	// synthetic fixture carries all of the regression weight. Named honestly, not hidden.
-	verificationBasis: 'synthetic-only',
+	// D-oracle-corpus-pinning: promoted from synthetic-only -- 3 real, pinned community repos
+	// now exist in test/fixtures/oracle-manifest.json (JeanCaicedo/employees-api-mysql,
+	// Serkanbyx/chat-app-backend, nekesam/helloworld), found via a genuine search effort that
+	// contradicted this adapter's own prior 'may be structurally unpromotable' hedge. The
+	// committed synthetic fixture still carries the exact-count regression weight; the real
+	// corpus is diagnostic/diversity coverage on top, same role every other adapter's real
+	// oracle plays.
+	verificationBasis: 'community-sample',
 	capabilities: {
 		// false: plain Express has no operationId concept at all. --openapi-file is the honest path
 		// forward for an app that has one; see CAPABILITY_SATISFIERS in scanners/capabilities.mjs.

package/scanners/adapters/typescript-express.mjs

@@ -41,6 +41,17 @@ const ENTITY_CLASS_RE = /@Entity\s*\(\s*(?:["'`]([^"'`]*)["'`])?\s*\)\s*\n?\s*ex
 // exported symbol -- same file-level granularity java's own DTO tracking already settled for.
 const DTO_DIR_SEGMENT = `${path.sep}dto${path.sep}`;
 
+// D-module-attribution-base-package (Update): found by the same shadow-validation pass that fixed
+// java-spring's own moduleOf() -- a real project not using a `dto/` folder at all (flat `CreateUserDto.ts` files, or
+// NestJS's own common `create-user.dto.ts` naming) had every DTO silently invisible, the same class
+// of single-convention overfit, just on a narrower surface (DTO tracking only, not module/entity/
+// controller extraction). This does NOT reopen the CONTENT-detection problem the comment above
+// explicitly rejected (interface/type/class-validator/Zod/undecorated class all have different
+// shapes) -- it's an independent, NAME-only signal: the file's own basename ends in "dto"
+// (case-insensitive), the same near-definitional marker this file's own entity-matching step below
+// already leans on for MATCHING. Catches both `CreateUserDto.ts` and `create-user.dto.ts`.
+const DTO_NAME_SUFFIX_RE = /dto$/i;
+
 // Two independent signals required, mirroring java-spring's "build file AND src layout" /
 // python-fastapi's "dependency declared AND source-confirmed" combined bar: (a) package.json
 // declares express, (b) at least one .ts file actually imports Router from 'express' and calls
@@ -251,8 +262,8 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 				moduleEntry(moduleName).controllers.push({ className, basePath: prefix, operationIds: [], endpoints, file });
 			}
 		}
-		if (file.includes(DTO_DIR_SEGMENT)) {
-			allDtos.push({ className: path.basename(file, '.ts'), file }); // no `line` -- path-based, no content parsed
+		if (file.includes(DTO_DIR_SEGMENT) || DTO_NAME_SUFFIX_RE.test(path.basename(file, '.ts'))) {
+			allDtos.push({ className: path.basename(file, '.ts'), file }); // no `line` -- path/name-based, no content parsed
 		}
 		allEntities.push(...extractTableEntities(text, file));
 	}

package/schemas/feature-contract.schema.json

@@ -36,16 +36,16 @@
           "body": { "enum": [true, false, "unknown"] },
           "provenance": { "type": "string" },
           "requestBodySchema": {
-            "description": "A2: the operation's request body projected from a real OpenAPI 3.1 document, fully inlined (no $ref) -- see contracts/openapi.mjs's inlineSchema(). Present only when reconciliation matched/adopted this operation AND its application/json schema resolved; omitted otherwise. Not deeply validated as 'is this a valid JSON Schema' here -- that would need a schema-of-schemas, out of scope.",
+            "description": "A2: the operation's request body projected from a real OpenAPI 3.1 document -- see contracts/openapi.mjs's inlineSchema(). Fully inlined (no $ref) EXCEPT at a genuinely self-referential component (D-openapi-cyclic-refs), where a $ref/$defs pair is used instead -- see this schema's own top-level $defs when present. Present only when reconciliation matched/adopted this operation AND its application/json schema resolved; omitted otherwise. Not deeply validated as 'is this a valid JSON Schema' here -- that would need a schema-of-schemas, out of scope.",
             "type": "object"
           },
           "requestBodyRequired": { "type": "boolean" },
           "responseSchema": {
-            "description": "A3: all documented 2xx application/json response schemas for this operation, fully inlined (no $ref); an anyOf union when 2+ distinct shapes are documented. Present only when matched/adopted AND at least one resolved.",
+            "description": "A3: all documented 2xx application/json response schemas for this operation, fully inlined (no $ref) EXCEPT at a genuinely self-referential component (D-openapi-cyclic-refs, $ref/$defs used instead); an anyOf union when 2+ distinct shapes are documented. Present only when matched/adopted AND at least one resolved.",
             "type": "object"
           },
           "errorSchema": {
-            "description": "A3: all documented 4xx/5xx application/json response schemas for this operation, fully inlined (no $ref); an anyOf union when 2+ distinct shapes are documented. Present only when matched/adopted AND at least one resolved.",
+            "description": "A3: all documented 4xx/5xx application/json response schemas for this operation, fully inlined (no $ref) EXCEPT at a genuinely self-referential component (D-openapi-cyclic-refs, $ref/$defs used instead); an anyOf union when 2+ distinct shapes are documented. Present only when matched/adopted AND at least one resolved.",
             "type": "object"
           },
           "sourceParameters": {

package/schemas/handles-plan.schema.json

@@ -20,6 +20,8 @@
           "type": { "type": "string" },
           "table": { "type": ["string", "null"] },
           "idField": { "type": ["string", "null"] },
+          "idFieldType": { "type": ["string", "null"], "description": "D-write-safety-phase1 (item 4a): java-spring only -- the primary key's declared Java type (e.g. 'UUID', 'Integer'). null when it couldn't be determined at all (not the same as a confirmed non-UUID type)." },
+          "idFieldIsUuid": { "type": ["boolean", "null"], "description": "D-write-safety-phase1 (item 4a): mirrors typescript-express's own already-established field of the same name. false means a resolver is structurally impossible for this entity (the handles subsystem is UUID-addressable only), independent of whether a service file can be found." },
           "readPath": { "type": ["string", "null"] },
           "requiredAuthority": { "type": "string" },
           "requiredAuthorityForPatch": { "type": "string", "description": "O5 (D-resolver-authorization-action-aware): java-spring only -- derived independently from the entity's UPDATE endpoint, not copied from requiredAuthority (which is fetch/recover's own value)." },

package/schemas/oracle-manifest.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:oracle-manifest:1",
+  "title": "backend-skeleton scanner-adapter verification-corpus manifest",
+  "description": "ROADMAP.md Phase 5b (D-oracle-corpus-pinning): the committed, human-readable record of real, third-party repos pinned to a real commit SHA per scanner adapter, driven by scripts/shadow-validation-smoke.mjs --manifest. Loaded at scripts/shadow-validation-smoke.mjs run time, not by the CLI itself -- this is a test/verification-only artifact, never read by bin/bskel.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contract", "adapters"],
+  "properties": {
+    "contract": { "const": "sbf.oracle-manifest/1" },
+    "adapters": {
+      "type": "object",
+      "propertyNames": {
+        "enum": ["java-spring", "python-fastapi", "typescript-express", "javascript-express", "generic-grep"]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "minItems": 1,
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "repo", "terms", "note"],
+          "properties": {
+            "id": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9-]*$",
+              "description": "Short, unique-within-this-adapter identifier for this manifest entry (e.g. 'spring-petclinic') -- used in report output, never sent to git/GitHub."
+            },
+            "owner": {
+              "type": ["string", "null"],
+              "description": "null means \"repo\" is used as-is as a literal clone URL/local path (matches scripts/shadow-validation-smoke.mjs's own parseRepoSpec literal form) -- ONLY for local, non-network test fixtures (test/shadow-validation-cli.test.mjs); every real corpus entry in this file names a real owner."
+            },
+            "repo": { "type": "string", "minLength": 1 },
+            "ref": {
+              "type": ["string", "null"],
+              "pattern": "^([0-9a-f]{40})?$",
+              "description": "A real, pinned commit SHA -- ROADMAP.md Phase 5b's own 'pin refs' requirement. null is permitted only for the local-fixture literal-owner form above (no meaningful \"pin\" for a throwaway local bare repo). Never a branch/tag name here (scripts/shadow-validation-smoke.mjs's own DEFAULT_REPOS/CLI-spec forms still accept branch names for quick manual use; this committed manifest does not)."
+            },
+            "path": {
+              "type": ["string", "null"],
+              "description": "Subdirectory within the clone to scope every bskel invocation to (relative, no leading/trailing slash) -- null/absent means the clone root. Needed for monorepos where the actual backend lives under a subdirectory (e.g. polarsource/polar's 'server')."
+            },
+            "terms": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "note": {
+              "type": "string",
+              "minLength": 1,
+              "description": "One-line, human-readable justification for why this repo is in the corpus (what real coverage it adds, or what real diagnostic gap it's expected to surface) -- see DECISIONS.md's D-oracle-corpus-pinning for the full record."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/stack-record.schema.json

@@ -15,6 +15,11 @@
       "items": { "type": "string" }
     },
     "env_example_keys": { "type": "array", "items": { "type": "string" } },
-    "at": { "type": "string", "format": "date-time" }
+    "at": { "type": "string", "format": "date-time" },
+    "file_hashes": {
+      "description": "D-write-safety-phase0 (item 2): additive, optional (absent on a record written before this existed -- planApply() treats a missing entry as no prior provenance, same as classifyFile()'s own no-manifest-entry fallback). sha256 of what `stack apply --apply` itself last wrote to each path in applied_files, keyed by that same relative path -- gives planApply() a preimage to check a hand-edit against, instead of only comparing to the current fresh render.",
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    }
   }
 }

package/stack/apply.mjs

@@ -6,6 +6,13 @@ import Ajv2020 from 'ajv/dist/2020.js';
 // P2b (D-greenfield-parameters): was a private `renderTemplate(templatePath, vars)` here, moved to
 // lib/template.mjs unchanged once `new/fastapi.mjs` became its second real consumer.
 import { renderTemplateFile } from '../lib/template.mjs';
+// D-write-safety-phase0 (item 2): reusing the exact same provenance-based classification and
+// git-recoverability check the handles write path already established, rather than inventing a
+// second one for this write path.
+import { classifyFile } from '../lib/handles-manifest.mjs';
+import { isDirtyOrUntracked } from '../handles/_engine.mjs';
+import { sha256String, readJsonIfExists } from '../lib/fsutil.mjs';
+import { sbfPath } from '../lib/paths.mjs';
 
 const STACK_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMAS_ROOT = path.join(STACK_ROOT, '..', 'schemas');
@@ -84,19 +91,31 @@ export function planApply(repoRoot, entry, { port = 8080 } = {}) {
 	// crossed the stated boundary).
 	plan.alreadyDetected = (entry.detect?.files ?? []).some((f) => fs.existsSync(path.join(repoRoot, f)));
 
+	// D-write-safety-phase0 (item 2): `file_hashes` (additive, schemas/stack-record.schema.json) is
+	// what `stack apply` itself last wrote to each path -- absent on a record from before this
+	// existed, or if `stack apply` never ran. classifyFile()'s own no-manifest-entry fallback
+	// (content-comparison only) covers that case exactly the way handles emit's first-ever run does.
+	const priorRecord = readJsonIfExists(sbfPath(repoRoot, 'stack.json'));
+	const priorHashes = priorRecord?.file_hashes ?? {};
+
 	for (const f of entry.static?.files ?? []) {
 		const templatePath = path.join(STACK_ROOT, f.template);
 		assertContained(STACK_ROOT, templatePath, 'catalog template path');
 		const targetPath = path.join(repoRoot, f.path);
 		assertContained(repoRoot, targetPath, 'catalog target path');
 		const rendered = renderTemplateFile(templatePath, { PORT: port });
-		const exists = fs.existsSync(targetPath);
-		const unchanged = exists && fs.readFileSync(targetPath, 'utf8') === rendered;
+		const diskContent = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, 'utf8') : null;
+		const exists = diskContent !== null;
+		const diskHash = exists ? sha256String(diskContent) : null;
+		const freshRenderHash = sha256String(rendered);
+		const matchesPristineRender = exists && diskContent === rendered;
+		const action = classifyFile({ exists, diskHash, manifestEntryHash: priorHashes[f.path] ?? null, freshRenderHash, matchesPristineRender });
 		plan.files.push({
 			path: f.path,
 			mode: f.mode ?? null,
-			action: !exists ? 'create' : (unchanged ? 'unchanged' : 'update'),
+			action,
 			content: rendered,
+			contentHash: freshRenderHash,
 		});
 	}
 
@@ -133,18 +152,40 @@ export function planApply(repoRoot, entry, { port = 8080 } = {}) {
 // API supports this), config_check could gain an `apply` action -- not built now because the
 // real target (Team-IZ-Backend) doesn't need it (already externalized), so there's no concrete
 // case to validate a patcher against yet.
-export function applyPlan(repoRoot, plan) {
+// D-write-safety-phase0 (item 2): `force` mirrors handles emit's own `--force` gate exactly -- a
+// `conflict` file (diverged from what `stack apply` itself last wrote) is refused outright without
+// it, and even with it is refused if not git-recoverable (uncommitted/untracked), so a --force
+// overwrite is only ever reversible. The `--reason` a real overwrite requires is a CLI-layer
+// concern (validated in cmdStackApply, mirroring cmdContractWaive/handles emit's identical
+// pattern) -- applyPlan() itself has nothing to do with an audit string it never persists. Returns
+// `fileHashes` (sha256 of what was ACTUALLY written this run) so the caller can persist it into
+// `.sbf/stack.json`'s new `file_hashes` field -- unchanged/adopt-unchanged files are simply absent
+// here, so the caller must merge onto the PRIOR record's file_hashes, not replace it wholesale.
+export function applyPlan(repoRoot, plan, { force = false } = {}) {
 	const written = [];
+	const conflicts = [];
+	const fileHashes = {};
 	for (const f of plan.files) {
-		if (f.action === 'unchanged') continue;
+		if (f.action === 'unchanged' || f.action === 'adopt-unchanged') continue;
 		const targetPath = path.join(repoRoot, f.path);
 		// Re-asserted here too (planApply already checked it) -- applyPlan must not assume it's
 		// only ever called with a plan it just generated for the same repoRoot.
 		assertContained(repoRoot, targetPath, 'catalog target path');
+		if (f.action === 'conflict') {
+			if (!force) {
+				conflicts.push({ path: f.path, reason: 'diverged from the last content `bskel stack apply` generated -- see notes for remediation' });
+				continue;
+			}
+			if (isDirtyOrUntracked(repoRoot, targetPath)) {
+				conflicts.push({ path: f.path, reason: 'refusing --force: this file has uncommitted/untracked changes -- commit or stash it first so the overwrite is recoverable' });
+				continue;
+			}
+		}
 		fs.mkdirSync(path.dirname(targetPath), { recursive: true });
 		fs.writeFileSync(targetPath, f.content);
 		if (f.mode) fs.chmodSync(targetPath, Number.parseInt(f.mode, 8));
 		written.push(f.path);
+		fileHashes[f.path] = f.contentHash;
 	}
 
 	const toAppend = plan.envExampleActions.filter((a) => a.action === 'append');
@@ -158,5 +199,5 @@ export function applyPlan(repoRoot, plan) {
 		written.push('.env.example');
 	}
 
-	return written;
+	return { written, conflicts, fileHashes };
 }