backend-skeleton 1.0.0-beta.6 → 1.0.0-beta.7

package/lib/gate-definitions.mjs

@@ -196,9 +196,10 @@ export const GATE_DEFINITIONS = Object.freeze({
 			};
 			const moduleName = report?.disposition?.module ?? report?.related_modules?.[0]?.module;
 			const mod = report?.related_modules?.find((m) => m.module === moduleName);
-			// DTOs deliberately excluded -- scanJavaSpring() stores them as bare class-name
-			// strings today, no `.file` field (Part 1's own named, out-of-scope gap).
-			for (const item of [...(mod?.controllers ?? []), ...(mod?.entities ?? []), ...(mod?.enums ?? [])]) {
+			// DTOs now included -- every adapter pushes {className, file} objects for dtos, the
+			// same shape controllers/entities/enums already use. See D-gate-precision "Continued
+			// (part 3)" in DECISIONS.md.
+			for (const item of [...(mod?.controllers ?? []), ...(mod?.entities ?? []), ...(mod?.enums ?? []), ...(mod?.dtos ?? [])]) {
 				if (!item.file) continue;
 				// related_modules[].{controllers,entities,enums}[].file are stored ABSOLUTE
 				// (unlike Part 1's own repo-relative files_read) -- confirmed live against a real

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.7",
   "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",

package/scanners/adapters/java-spring.mjs

@@ -257,7 +257,7 @@ export function scanJavaSpring(repoRoot) {
 			if (en) moduleEntry(mod).enums.push(en);
 		}
 		if (mod && file.includes(`${path.sep}presentation${path.sep}dto${path.sep}`)) {
-			moduleEntry(mod).dtos.push(path.basename(file, '.java'));
+			moduleEntry(mod).dtos.push({ className: path.basename(file, '.java'), file });
 		}
 	}
 

package/scanners/adapters/python-fastapi.mjs

@@ -160,6 +160,42 @@ function extractTableEntities(text, file) {
 	return entities;
 }
 
+// D-gate-precision (Continued, part 3): the DTO/request-response-shape counterpart to
+// extractTableEntities() -- a SQLModel-family class WITHOUT `table=True` (`ItemBase(SQLModel)`,
+// `ItemPublic(ItemBase)`, `ItemCreate(ItemBase)`), the real convention confirmed against this
+// project's own committed fixture and the real oracle it mirrors (fastapi/full-stack-fastapi-
+// template). Deliberately a separate function, not merged into extractTableEntities() -- zero
+// regression risk to existing entity extraction. One narrow, named exclusion beyond "not
+// table=True": `class Settings(BaseSettings):` (pydantic-settings' own well-known config-class
+// base) is not API request/response surface -- excluding it is a concrete, common false-positive
+// fix, not a hypothetical one. No broader positive allowlist (e.g. requiring `SQLModel`/`BaseModel`
+// literally in the base list) is layered on top: the real oracle's own `ItemPublic(ItemBase)` shape
+// (a DTO extending ANOTHER DTO, not SQLModel/BaseModel directly) would fail such an allowlist,
+// trading a bounded, low-cost false positive for a worse false negative (a missed real DTO change)
+// -- the same "prefer false positive over false negative" call this exact drift-detection mechanism
+// already makes for controllers/entities/enums.
+function extractDtoClasses(text, file) {
+	const dtos = [];
+	for (const m of text.matchAll(CLASS_RE)) {
+		if (/table\s*=\s*True/.test(m[2])) continue; // has its own entity extractor above
+		if (/\bBaseSettings\b/.test(m[2])) continue; // pydantic-settings config, not API surface
+		dtos.push({ className: m[1], file, line: lineNumberAt(text, m.index) });
+	}
+	return dtos;
+}
+
+// Bounded, non-exhaustive allowlist of DTO class-name suffixes -- validated against this project's
+// own committed fixture (ItemBase/ItemCreate/ItemPublic/ItemsPublic, all correctly stripping to
+// "item"/"items", the real "items" module). A DTO whose class name uses a different convention
+// (Schema, Payload, Out) lands in the `_dtos` bucket below instead -- named, accepted, untracked,
+// same shape as an unmatched entity's `_models` fallback. Purely additive to extend: a future
+// suffix added here can only ever gain coverage, never lose it.
+const KNOWN_DTO_SUFFIXES = ['Base', 'Create', 'Update', 'Public', 'Read', 'Response', 'Request', 'In', 'Out'];
+function stripKnownDtoSuffix(className) {
+	const suffix = KNOWN_DTO_SUFFIXES.find((s) => className.length > s.length && className.endsWith(s));
+	return suffix ? className.slice(0, -suffix.length) : className;
+}
+
 // A1 §7 equivalent for FastAPI: `include_router(router, prefix=X)` applies a prefix the
 // per-router-file scan above cannot see (each file is read independently, with no idea another
 // file mounts it under a further prefix). Two-step resolution when X is a variable/attribute
@@ -224,6 +260,7 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 	};
 
 	const allEntities = [];
+	const allDtos = [];
 	for (const file of files) {
 		const text = fs.readFileSync(file, 'utf8');
 
@@ -240,6 +277,7 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 		}
 
 		allEntities.push(...extractTableEntities(text, file));
+		allDtos.push(...extractDtoClasses(text, file));
 	}
 
 	// Entity -> module assignment: this repo's real layout has no domain/<module>/ folder (all
@@ -255,6 +293,18 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 		moduleEntry(targetModule ?? '_models').entities.push(entity);
 	}
 
+	// DTO -> module assignment: same narrow name-match as entities, suffix-stripped first via the
+	// bounded allowlist above (ItemPublic -> "item" -> matches "items"). Unmatched (unlisted suffix,
+	// or no correlation at all) lands in a separate `_dtos` bucket -- not merged into entities' own
+	// `_models` -- and is therefore NOT tracked by any feature's contract gate; a real, named,
+	// accepted limitation (see D-gate-precision "Continued (part 3)" in DECISIONS.md).
+	for (const dto of allDtos) {
+		const lower = stripKnownDtoSuffix(dto.className).toLowerCase();
+		const candidates = new Set([lower, `${lower}s`]);
+		const targetModule = [...modules.keys()].find((name) => candidates.has(name));
+		moduleEntry(targetModule ?? '_dtos').dtos.push(dto);
+	}
+
 	return {
 		modules: [...modules.values()],
 		pathPrefixSignals: extractIncludeRouterPrefixSignals(repoRoot, files),

package/scanners/adapters/typescript-express.mjs

@@ -32,6 +32,15 @@ const VERB_CALL_RE = new RegExp(`\\brouter\\.(${VERBS.join('|')})\\s*\\(`, 'gi')
 const ROUTER_USE_RE = /\brouter\.use\s*\(/g;
 const ENTITY_CLASS_RE = /@Entity\s*\(\s*(?:["'`]([^"'`]*)["'`])?\s*\)\s*\n?\s*export\s+class\s+(\w+)/g;
 
+// D-gate-precision (Continued, part 3): a pure PATH-CONVENTION heuristic, mirroring java-spring's
+// own identical solution to the identical problem (`.../presentation/dto/`) rather than inventing
+// syntactic DTO detection this ecosystem doesn't have a reliable single marker for -- plain
+// `interface`, `type` aliases, class-validator classes, Zod schemas, and undecorated classes are
+// all real conventions, and this adapter's own `api.request-shape: false` capability already names
+// why no such regex is attempted here. One entry per FILE under a `dto/` directory, not per
+// exported symbol -- same file-level granularity java's own DTO tracking already settled for.
+const DTO_DIR_SEGMENT = `${path.sep}dto${path.sep}`;
+
 // 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
@@ -220,6 +229,7 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 	};
 
 	const allEntities = [];
+	const allDtos = [];
 	for (const file of files) {
 		const text = fileTexts.get(file);
 		// G6: `\bRouter\s*\(` -- see detectTypeScriptExpressRoot above. Same widening for the same
@@ -235,6 +245,9 @@ 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
+		}
 		allEntities.push(...extractTableEntities(text, file));
 	}
 
@@ -248,6 +261,19 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 		moduleEntry(targetModule ?? '_models').entities.push(entity);
 	}
 
+	// DTO -> module assignment: same narrow name-match as entities, with a trailing literal
+	// `Dto`/`DTO` stripped first -- the one near-definitional, cross-project-safe TS DTO marker (a
+	// DTO's own name almost universally contains it). An action-prefixed name (`CreateUserDto.ts`,
+	// a common real-world shape) still will NOT exact-match after stripping ("createuser" !=
+	// "user"/"users") and lands in `_dtos` -- honestly uncovered rather than guessed at (see
+	// D-gate-precision "Continued (part 3)" in DECISIONS.md).
+	for (const dto of allDtos) {
+		const lower = dto.className.replace(/Dto$/i, '').toLowerCase();
+		const candidates = new Set([lower, `${lower}s`]);
+		const targetModule = [...modules.keys()].find((name) => candidates.has(name));
+		moduleEntry(targetModule ?? '_dtos').dtos.push(dto);
+	}
+
 	return {
 		modules: [...modules.values()],
 		pathPrefixSignals: [],

package/scanners/render.mjs

@@ -70,7 +70,7 @@ export function renderScanMarkdown(report) {
 				lines.push(`- Enum \`${en.name}\`: ${en.constants.join(', ')}`);
 			}
 			if (mod.dtos.length > 0) {
-				lines.push(`- DTOs: ${mod.dtos.join(', ')}`);
+				lines.push(`- DTOs: ${mod.dtos.map((d) => d.className).join(', ')}`);
 			}
 			lines.push('');
 		}

package/schemas/scan-report.schema.json

@@ -25,7 +25,7 @@
           "controllers": { "type": "array" },
           "entities": { "type": "array" },
           "enums": { "type": "array" },
-          "dtos": { "type": "array", "items": { "type": "string" } },
+          "dtos": { "type": "array" },
           "evidence": {
             "description": "D-scanner-evidence: every {signal, term, value, weight, file, line} match that contributed to `score` -- capped per signal type AT COLLECTION TIME (not filtered afterward), so this array's size stays bounded regardless of repo size. See `capped_signals` for which signal types actually hit that cap.",
             "type": "array",