backend-skeleton 1.0.0-beta.2 → 1.0.0-beta.4

package/contracts/emit.mjs

@@ -15,24 +15,42 @@ import { pathPrefixCandidates, unreflectedPathPrefixes } from './export.mjs';
 // a path param. Direction stays one-way (openapi.mjs imports from emit.mjs, never the reverse).
 export const BARE_UUID_PATTERN = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$';
 
-// A7/A8: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
+// A7/A8/A9/A10: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
 // const -- bin/bskel.mjs's loadContract() imports this too, so the friendly "re-emit with the
-// current bskel" message and the value actually written here cannot drift apart. Bumped "5" -> "6"
-// for this item (sourceResponses/sourceRequestBody) -- cheap this time: the friendly re-emit
-// pre-check in loadContract() needed zero code change, it already compares against this imported
-// constant -- see D-openapi-per-status.
-export const CONTRACT_SCHEMA_VERSION = '6';
+// current bskel" message and the value actually written here cannot drift apart. Bumped "7" -> "8"
+// for this item (sourceDescription) -- again cheap, the friendly re-emit pre-check needs zero
+// code change -- see D-openapi-description.
+export const CONTRACT_SCHEMA_VERSION = '8';
 
-function pathParamsSchema(routePath) {
+// A9 (D-openapi-path-params): `sourcePathParamSchemas` (a Map<name, schema>, contracts/openapi.mjs's
+// applyPathParameterSchemas -- present only for a matched/adopted operation whose source document
+// resolved at least one real path-param schema) is preferred per-segment over the name heuristic
+// below. The heuristic remains the fallback for any segment the source doesn't answer (no source
+// document at all, source declared no schema for that name, or the schema failed to resolve) --
+// this function's OWN correctness posture is unchanged for those cases, exactly as before this
+// item. `pathParamsHeuristic` names every segment that still fell back, so a downstream consumer
+// (contracts/export.mjs's collectOmissions()) can tell, per operation, whether ANY segment is still
+// a guess -- `null` (never `[]`) when every segment was source-resolved or the route has none.
+function pathParamsSchema(routePath, sourcePathParamSchemas = null) {
 	const params = [...routePath.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
 	const properties = {};
+	const heuristicNames = [];
 	for (const p of params) {
+		const sourced = sourcePathParamSchemas ? sourcePathParamSchemas.get(p) : undefined;
+		if (sourced) {
+			properties[p] = sourced;
+			continue;
+		}
 		// Naming convention seen throughout Team-IZ-Backend (`UUID organizationId`, etc.) --
 		// a heuristic, not a guarantee; wrong for a path param that happens to end in "Id" but
 		// isn't a UUID, which just means an over-strict uuid-shaped check on that one field.
 		properties[p] = /id$/i.test(p) ? { type: 'string', pattern: BARE_UUID_PATTERN } : { type: 'string' };
+		heuristicNames.push(p);
 	}
-	return { type: 'object', additionalProperties: false, properties, required: params };
+	return {
+		pathParams: { type: 'object', additionalProperties: false, properties, required: params },
+		pathParamsHeuristic: heuristicNames.length > 0 ? heuristicNames : null,
+	};
 }
 
 // Re-reads the controller source (already located by the scan) to check whether this specific
@@ -85,6 +103,17 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 	const warnings = [];
 	let endpointCount = 0;
 
+	// D-unsupported-annotation-warning: module-wide, computed once, independent of targetModule/
+	// endpoint iteration below -- the source document either uses one of the 5 permanently-dropped
+	// schema keywords or it doesn't, a fact about the WHOLE document, not any one operation.
+	for (const keyword of openapi?.unsupportedAnnotations ?? []) {
+		warnings.push(makeWarning('CONTRACT_OPENAPI_UNSUPPORTED_ANNOTATION_PRESENT', {
+			subject: keyword,
+			message: `the source OpenAPI document uses the schema keyword "${keyword}" at least once -- this projection unconditionally drops it (0 real occurrences were measured against the reference document this behavior was built against, but this document has at least one), so it is never represented in any operation's projected schema`,
+			detail: { keyword },
+		}));
+	}
+
 	if (!targetModule) {
 		warnings.push(makeWarning('CONTRACT_NO_MODULE', {
 			message: 'no related module in the scan report -- emitting an empty operation set. Pass --module, or re-run `bskel scan` with terms that actually match the intended feature.',
@@ -122,6 +151,12 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 				let sourceResponses = null;
 				let sourceRequestBody = null;
 				let requestMediaTypesUnresolvedReason = null;
+				// A9: same discipline -- transient (Map), consulted below by pathParamsSchema(), never
+				// itself spread into the persisted operation object (see that function's own comment).
+				let pathParamSchemas = null;
+				// A10: same discipline, for the opt-in operation-level description.
+				let sourceDescription = null;
+				let descriptionUnresolvedReason = null;
 
 				if (res) {
 					switch (res.kind) {
@@ -148,6 +183,9 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 							sourceResponses = res.sourceResponses ?? null;
 							sourceRequestBody = res.sourceRequestBody ?? null;
 							requestMediaTypesUnresolvedReason = res.requestMediaTypesUnresolvedReason ?? null;
+							pathParamSchemas = res.pathParamSchemas ?? null;
+						sourceDescription = res.sourceDescription ?? null;
+						descriptionUnresolvedReason = res.descriptionUnresolvedReason ?? null;
 							break;
 						case 'adopted':
 							// No @Operation(operationId=...) in source at all -- the id itself comes from
@@ -174,6 +212,9 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 							sourceResponses = res.sourceResponses ?? null;
 							sourceRequestBody = res.sourceRequestBody ?? null;
 							requestMediaTypesUnresolvedReason = res.requestMediaTypesUnresolvedReason ?? null;
+							pathParamSchemas = res.pathParamSchemas ?? null;
+						sourceDescription = res.sourceDescription ?? null;
+						descriptionUnresolvedReason = res.descriptionUnresolvedReason ?? null;
 							warnings.push(makeWarning('CONTRACT_OPENAPI_DERIVED_OPERATION_ID', {
 								subject: operationId,
 								message: `operationId "${operationId}" for ${res.verb} ${res.path} was not found in the source (no @Operation(operationId=...)) -- adopted directly from the OpenAPI document instead`,
@@ -320,10 +361,22 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 						detail: { reason: requestMediaTypesUnresolvedReason, verb, path: route, operationId },
 					}));
 				}
+				// A10: only fires when --descriptions was passed AND the source declared one AND it
+				// exceeded MAX_DESCRIPTION_LENGTH -- independent from every other unresolved code above
+				// (a genuinely new failure mode, not reusing an existing one), same reasoning A8 used to
+				// justify its own new multipart code instead of overloading an existing one.
+				if (descriptionUnresolvedReason) {
+					warnings.push(makeWarning('CONTRACT_OPENAPI_DESCRIPTION_UNRESOLVED', {
+						subject: operationId,
+						message: `operationId "${operationId}" (${verb} ${route}) declares a description that could not be copied (${descriptionUnresolvedReason}) -- description stays unrepresented for this operation, same as before --descriptions`,
+						detail: { reason: descriptionUnresolvedReason, verb, path: route, operationId },
+					}));
+				}
+				const { pathParams, pathParamsHeuristic } = pathParamsSchema(route, pathParamSchemas);
 				operations[operationId] = {
 					verb,
 					path: route,
-					pathParams: pathParamsSchema(route),
+					pathParams,
 					body: hasBody === null ? 'unknown' : hasBody,
 					provenance,
 					// A2/A3/A7: omitted entirely (not null/false) when there's nothing to project/copy --
@@ -338,6 +391,12 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 					...(sourceTags ? { sourceTags } : {}),
 					...(sourceResponses ? { sourceResponses } : {}),
 					...(sourceRequestBody ? { sourceRequestBody } : {}),
+					// A9: omitted (not []) when every segment resolved from source, or the route has none.
+					...(pathParamsHeuristic ? { pathParamsHeuristic } : {}),
+					// A10: omitted entirely when --descriptions was not passed, the source had none, or
+					// it failed the length cap -- same "omitted, never null/false" discipline as every
+					// other field above.
+					...(sourceDescription ? { sourceDescription } : {}),
 				};
 			}
 		}

package/contracts/export.mjs

@@ -16,12 +16,20 @@
 // but ONLY when a real source document (--openapi-file) licensed it for that EXACT operation; where
 // no source stated one, the key is still omitted, meaning "unspecified". A8 (D-openapi-per-status)
 // extends the same discipline to per-status responses (additive to, never replacing, the
-// responseSchema/errorSchema union) and non-JSON request media types. Operation-level
-// `description` remains excluded -- measured too expensive to default-on (2,442.7 bytes/operation
-// average, larger than every other field this projection copies combined), still disclosed as
-// structural. Every omission is disclosed in prose (`info.description`) and machine-readably
+// responseSchema/errorSchema union) and non-JSON request media types. A9 (D-openapi-path-params) is
+// different in kind from A7/A8 -- not additive, a REPLACEMENT in place: a path parameter's own
+// `pathParams` schema is corrected from the source document per-segment when it resolves one,
+// falling back to the pre-existing name heuristic only where the source doesn't answer. A10
+// (D-openapi-description) finally builds operation-level `description` -- the one field this whole
+// effort measured too expensive to default-on (2,442.7 bytes/operation average, larger than every
+// other field this projection copies combined) -- as the one source-backed field that is opt-in
+// (`contract emit --descriptions`) rather than default-on. A11 (D-openapi-field-docs) extends the
+// SAME `--descriptions` flag one level deeper: schema FIELD-level `description`/`example` (a
+// property's own annotation, not the operation's), reusing the flag rather than adding a second
+// one. Every omission is disclosed in prose (`info.description`) and machine-readably
 // (`info.x-bskel-omitted`) rather than papered over -- see D-openapi-export, D-openapi-passthrough,
-// and D-openapi-per-status in DECISIONS.md.
+// D-openapi-per-status, D-openapi-path-params, D-openapi-description, and D-openapi-field-docs in
+// DECISIONS.md.
 import { createHash } from 'node:crypto';
 import { BSKEL_GENERATED_EXTENSION, BSKEL_PASSTHROUGH_EXTENSION, PATH_PREFIX_RE, RESPONSE_STATUS_KEY_RE, MEDIA_TYPE_RE, PER_STATUS_NO_DESCRIPTION_STANDIN, SUCCESS_STATUS_RE, ERROR_STATUS_RE, DEFAULT_STATUS_KEY } from './openapi.mjs';
 
@@ -58,34 +66,48 @@ const ERROR_RESPONSE_DESCRIPTION = 'Error. The source contract records the union
 // A7: query/header/cookie parameters, security, summaries, and tags moved OUT of this list -- they
 // are now real emitted content when a source document licensed them, so they only belong in the
 // DERIVED (ANY-based) set collectOmissions() builds below. A8 moves `per-status-responses` and
-// `non-json-request-media-types` (renamed from `non-json-media-types`) out the same way. What
-// stays structural: `descriptions` (field-level AND operation-level -- the latter measured and
-// deliberately excluded, not merely unbuilt), `path-parameter-schemas` (path-param schemas come
-// from this contract's own name heuristic, never from a source document, even when --openapi-file
-// was given -- see the real `batchRequestId` finding in D-openapi-passthrough), `vendor-extensions`
-// (x-* keys on an operation are never copied -- excluded in principle, not by cap or failure, since
-// their semantics are tool-specific), and two A8 additions: `non-json-response-schemas` (a
-// non-JSON response media type's NAME is copied via a per-status entry's `mediaTypes`, but its
-// SHAPE is never projected -- 0/674 real occurrences, so building that machinery would violate
-// this project's own "don't build for zero real cases" discipline) and `response-headers`
-// (response `headers`/`links` -- 0/694 real occurrences, a genuinely visible gap only now that
-// per-status responses look complete).
+// `non-json-request-media-types` (renamed from `non-json-media-types`) out the same way. A9 moves
+// `path-parameter-schemas` out the same way too -- path-param schemas now come from a real source
+// document whenever it declares a resolvable one (see D-openapi-path-params, the real fix for the
+// `batchRequestId` finding this omission entry used to describe unconditionally), falling back to
+// the contract's own name heuristic only per-segment, so its presence is now content-conditional
+// like every other A7/A8 field, not a permanent structural fact. A10 splits the old single
+// `descriptions` entry in two: `operation-descriptions` moves out (opt-in via `--descriptions`, so
+// its presence is now content-AND-flag-conditional, same ANY-based doctrine), while
+// `field-descriptions` (schema-field-level `description`/`title`/`example`, dropped as
+// DROPPED_KEYWORDS while inlining ANY schema) stays structural at that point. A11
+// (D-openapi-field-docs) splits `field-descriptions` again the same way: `description`/`example`
+// move OUT to the ANY-based set below (`--descriptions` now doubles as the field-level flag too,
+// keeping the `field-descriptions` NAME since that is still exactly what it describes -- only its
+// meaning moves from "never built" to "content-AND-flag-conditional"), while `title`/`examples`
+// (plural)/`externalDocs`/`xml`/`deprecated` move to a new, narrower structural entry
+// (`field-metadata`) -- measured 0 real occurrences each against the Team-IZ-Backend oracle, so
+// they stay permanently unbuilt on the same "don't build for zero real cases" grounds as the two
+// A8 entries below, not this item's scope. What else stays structural: `vendor-extensions` (x-*
+// keys on an operation are never copied -- excluded in principle, not by cap or failure, since
+// their semantics are tool-specific), and two A8 additions: `non-json-response-schemas` (a non-JSON
+// response media type's NAME is copied via a per-status entry's `mediaTypes`, but its SHAPE is never
+// projected -- 0/674 real occurrences, so building that machinery would violate this project's own
+// "don't build for zero real cases" discipline) and `response-headers` (response `headers`/`links`
+// -- 0/694 real occurrences, a genuinely visible gap only now that per-status responses look
+// complete).
 const STRUCTURAL_OMISSIONS = Object.freeze([
-	'descriptions',
+	'field-metadata',
 	'non-json-response-schemas',
-	'path-parameter-schemas',
 	'response-headers',
 	'vendor-extensions',
 ]);
 
 const OMISSION_PROSE = Object.freeze({
 	'cookie-parameters': 'cookie parameters, for at least one operation that does not carry a fully-copied set (never emitted at all when --openapi-file was not given, or the source document declared none)',
-	descriptions: 'field-level descriptions/titles/examples (contracts/openapi.mjs drops them as DROPPED_KEYWORDS while inlining a schema), and operation-level `description` -- measured and deliberately excluded (real average 2,442.7 bytes/operation, larger than every other field this projection copies combined); if ever built, it must be opt-in behind a flag, unlike everything else this projection copies by default',
 	'error-schemas': 'a JSON error-body schema for at least one operation',
+	'field-descriptions': 'a schema field\'s own `description`/`example` (a property\'s own annotation, distinct from the operation-level `description` field -- see `operation-descriptions` below), for at least one field in the request-body/response/error schema of at least one operation -- copied only when `contract emit --descriptions` was used (the same flag as operation-level description) AND the source declared one for that exact field AND it did not exceed the length/size cap; otherwise the field carries no `description`/`example` key, never synthesized. Not tracked separately for per-status responses, non-JSON request media types, or path-parameter schemas -- those may carry field docs when the flag is on, but their presence is not reflected in this specific omission entry',
+	'field-metadata': 'a schema field\'s `title`, plural `examples`, `externalDocs`, `xml`, or `deprecated` keyword -- dropped unconditionally while inlining a schema (contracts/openapi.mjs\'s DROPPED_KEYWORDS), regardless of `--descriptions`. Permanently unbuilt: 0 real occurrences of any of these five measured against the Team-IZ-Backend oracle',
 	'header-parameters': 'header parameters, for at least one operation that does not carry a fully-copied set (never emitted at all when --openapi-file was not given, or the source document declared none)',
 	'non-json-request-media-types': 'the media type of the request body, for at least one operation that takes one -- a non-application/json request media type is emitted only when a real source document declared one for that exact operation, copied byte-for-byte; otherwise this document shows a JSON media-type entry because that is all the contract knows, never because the real body is known to be JSON',
 	'non-json-response-schemas': 'a JSON Schema for any response body in a media type other than application/json -- the media type is named where a source document declared one for that status, but its shape is never projected',
-	'path-parameter-schemas': 'path parameter schemas -- always derived from this contract\'s own name heuristic (a trailing "Id" is assumed to be a UUID), never from a source document even when --openapi-file was given; a real, small false-negative of this heuristic is known and disclosed, not fixed, by this projection',
+	'operation-descriptions': 'the operation-level `description`, for at least one operation -- copied only when `contract emit --descriptions` was used (opt-in: measured real average 2,442.7 bytes/operation, larger than every other field this projection copies combined) AND the source document declared one for that exact operation AND it did not exceed the length cap; otherwise this key is absent for that operation, never synthesized',
+	'path-parameter-schemas': 'a path parameter\'s schema, for at least one path segment on at least one operation -- derived from this contract\'s own name heuristic (a trailing "Id" is assumed to be a UUID) rather than a real source document, because no source document was given, the source declared no schema for that segment, or the schema failed to resolve; a segment not covered by this note was resolved from the source document\'s own real schema',
 	'per-status-responses': 'per-status responses, for at least one operation -- that operation\'s entry collapses every documented 2xx body into one `2XX` union and every 4xx/5xx body into one `default` union, and records no real status codes. Where a real source document (--openapi-file) documented statuses for an operation, its own status codes and descriptions are emitted verbatim instead; nothing is invented for an operation the source said nothing about',
 	'query-parameters': 'query parameters, for at least one operation that does not carry a fully-copied set (never emitted at all when --openapi-file was not given, or the source document declared none)',
 	'request-body-schemas': 'a JSON request-body schema for at least one operation that takes a body',
@@ -101,6 +123,28 @@ function hasSourceParamIn(op, loc) {
 	return Array.isArray(op.sourceParameters) && op.sourceParameters.some((p) => p.in === loc);
 }
 
+// A11: whether AT LEAST ONE node anywhere in this schema carries a copied `description`/`example`
+// -- deliberately the same coarse "presence, not completeness" doctrine `operation-descriptions`
+// already uses for `op.sourceDescription` (this cannot know, from the exported contract alone,
+// whether a field WITHOUT one had none in the source or was simply never reached with the flag
+// off; it only discloses whether ANY field-level annotation survived at all). `seen` guards the
+// same delete-on-exit-shaped cycle risk inlineSchema() itself defends against -- belt-and-braces,
+// since a contract's own schemas are already acyclic by construction, but this walk is generic over
+// whatever JSON shape ends up in a contract field.
+function schemaHasFieldDocs(node, seen = new Set()) {
+	if (node === null || typeof node !== 'object' || Array.isArray(node) || seen.has(node)) return false;
+	seen.add(node);
+	if (typeof node.description === 'string' || Object.hasOwn(node, 'example')) return true;
+	if (node.properties && typeof node.properties === 'object' && !Array.isArray(node.properties)) {
+		for (const propSchema of Object.values(node.properties)) {
+			if (schemaHasFieldDocs(propSchema, seen)) return true;
+		}
+	}
+	if (node.items && typeof node.items === 'object' && schemaHasFieldDocs(node.items, seen)) return true;
+	if (node.additionalProperties && typeof node.additionalProperties === 'object' && schemaHasFieldDocs(node.additionalProperties, seen)) return true;
+	return false;
+}
+
 // Derived from the contract's ACTUAL content, not hardcoded -- an operation that takes a body but
 // has no projected schema, or has no response/error schema, each add their own entry, so the list
 // says what is missing from THIS document rather than reciting a fixed disclaimer.
@@ -133,6 +177,25 @@ export function collectOmissions(contract) {
 		if ((op.body === true || op.body === 'unknown') && !op.requestBodySchema && !op.sourceRequestBody) {
 			omissions.add('non-json-request-media-types');
 		}
+		// A9: path-parameter schemas -- ANY-based, same doctrine as every check above. An operation
+		// with zero path params, or every one source-resolved, has no pathParamsHeuristic at all
+		// (contracts/emit.mjs never persists an empty array), so it naturally never trips this check.
+		if (Array.isArray(op.pathParamsHeuristic) && op.pathParamsHeuristic.length > 0) {
+			omissions.add('path-parameter-schemas');
+		}
+		// A10: operation-level description -- ANY-based, same doctrine. Absent whenever
+		// --descriptions was not used at all (every operation then lacks sourceDescription, so this
+		// always trips until the flag is used), the source had none for this operation, or it
+		// exceeded the length cap.
+		if (!op.sourceDescription) omissions.add('operation-descriptions');
+		// A11: schema field-level description/example -- ANY-based, same doctrine as
+		// response-schemas/error-schemas just above: added whenever NONE of this operation's
+		// projected schemas carry a field-level annotation, including the (common) case where the
+		// operation has no projected schema at all to carry one -- same "absence of the whole class
+		// is itself disclosed" posture response-schemas/error-schemas already take unconditionally,
+		// not gated on whether a schema exists first.
+		const fieldSchemas = [op.requestBodySchema, op.responseSchema, op.errorSchema].filter(Boolean);
+		if (!fieldSchemas.some((s) => schemaHasFieldDocs(s))) omissions.add('field-descriptions');
 	}
 	return [...omissions].sort();
 }
@@ -464,25 +527,31 @@ export function buildOpenApiDocument({ contract, snapshot = null, options = {} }
 		// for this exact operation. `security: []` is spec-legal (confirmed by executing the
 		// meta-schema) AND, when copied, a genuine positive claim FROM THE SOURCE that no
 		// authentication is required -- Array.isArray, not a truthy check, so `[]` is correctly
-		// treated as present. `op.sourceSecurity` is never emitted when absent; `description` (the
-		// operation-level field, not the response-object one) remains deliberately unset -- Phase 2.
+		// treated as present. `op.sourceSecurity` is never emitted when absent.
 		if (Array.isArray(op.sourceSecurity)) operation.security = op.sourceSecurity;
 		if (op.sourceSummary) operation.summary = op.sourceSummary;
 		if (Array.isArray(op.sourceTags) && op.sourceTags.length > 0) operation.tags = op.sourceTags;
+		// A10: same "only when the contract carries a copied value" discipline -- `sourceDescription`
+		// is present only when `contract emit --descriptions` was used AND the source had one for this
+		// exact operation, so this is never a synthesized or inferred string.
+		if (op.sourceDescription) operation.description = op.sourceDescription;
 
 		// A8: two more clauses -- an operation whose ONLY passthrough is per-status responses or a
 		// copied multipart body (no source parameters/security/summary/tags at all) previously got NO
 		// marker, reopening the exact self-import hole A7 closed for that one operation. Never arises
 		// on the real oracle (148/148 already carry summary+tags+security) but is structurally
 		// reachable from a minimal hand-written document declaring only `responses` -- see
-		// D-openapi-per-status.
+		// D-openapi-per-status. A10 adds a third clause for the same reason: an operation whose ONLY
+		// passthrough is a copied description (structurally reachable even though never arises on the
+		// real oracle, which already carries summary/tags/security everywhere).
 		const hasPassthrough = Boolean(
 			(Array.isArray(op.sourceParameters) && op.sourceParameters.length > 0)
 			|| Array.isArray(op.sourceSecurity)
 			|| op.sourceSummary
 			|| (Array.isArray(op.sourceTags) && op.sourceTags.length > 0)
 			|| (op.sourceResponses && typeof op.sourceResponses === 'object' && Object.keys(op.sourceResponses).length > 0)
-			|| (op.sourceRequestBody && typeof op.sourceRequestBody === 'object'),
+			|| (op.sourceRequestBody && typeof op.sourceRequestBody === 'object')
+			|| op.sourceDescription,
 		);
 		passthroughByOperation[operationId] = hasPassthrough;
 		if (hasPassthrough) {