backend-skeleton 1.0.0-beta.9 → 1.1.0

package/contracts/emit.mjs

@@ -31,8 +31,12 @@ export const CONTRACT_SCHEMA_VERSION = '8';
 // 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.
+// Update (D-openapi-path-params, closing the O8 typescript-express port's own Finding 2): the
+// regex also recognizes Express's own `:name`/`:name(...)` segment syntax now, not just OpenAPI/
+// Spring/FastAPI-style `{name}` -- additive-only for java-spring/python-fastapi (their own route
+// strings never contain a colon in this position).
 function pathParamsSchema(routePath, sourcePathParamSchemas = null) {
-	const params = [...routePath.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+	const params = [...routePath.matchAll(/\{(\w+)\}|:(\w+)(?:\([^)]*\))?/g)].map((m) => m[1] ?? m[2]);
 	const properties = {};
 	const heuristicNames = [];
 	for (const p of params) {

package/contracts/export.mjs

@@ -82,8 +82,18 @@ const ERROR_RESPONSE_DESCRIPTION = 'Error. The source contract records the union
 // 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-*
+// they stayed unbuilt on the same "don't build for zero real cases" grounds as the two A8 entries
+// below, not this item's scope.
+// A14 (D-openapi-field-metadata-passthrough): D-oracle-corpus-openapi-remeasurement (ROADMAP
+// Phase 5c) found `title`/plural `examples`/`deprecated` DO occur for real against a much larger
+// second corpus (polarsource/polar, 1046 component schemas vs 308) -- those 3 of the original 5
+// `field-metadata` keywords are now conditionally copied (contracts/openapi.mjs's
+// DOCUMENTATION_KEYWORDS), same "gated on --descriptions" doctrine as A11's own description/
+// example. `field-metadata` migrates from a STRUCTURAL (always-present) omission to an ANY-based
+// one below -- the exact same migration A10 made for `operation-descriptions` when it left the
+// original single `descriptions` structural entry. `externalDocs`/`xml` remain 0 real occurrences
+// even at Polar's scale, so THOSE two keep the narrower structural entry
+// `external-docs-and-xml-metadata`. 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
@@ -92,7 +102,7 @@ const ERROR_RESPONSE_DESCRIPTION = 'Error. The source contract records the union
 // -- 0/694 real occurrences, a genuinely visible gap only now that per-status responses look
 // complete).
 const STRUCTURAL_OMISSIONS = Object.freeze([
-	'field-metadata',
+	'external-docs-and-xml-metadata',
 	'non-json-response-schemas',
 	'response-headers',
 	'vendor-extensions',
@@ -102,7 +112,8 @@ 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)',
 	'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',
+	'field-metadata': 'a schema field\'s `title`, plural `examples`, or `deprecated` keyword, for at least one field in the request-body/response/error schema of at least one operation -- copied only when `--descriptions` is passed (contracts/openapi.mjs\'s DOCUMENTATION_KEYWORDS, A14/D-openapi-field-metadata-passthrough), same doctrine as `field-descriptions`. Present whenever the flag was not used at all, none of this operation\'s projected schemas carry any of the three, or the value exceeded its cap (MAX_TITLE_LENGTH/MAX_EXAMPLES_ARRAY_LENGTH/MAX_EXAMPLE_LENGTH)',
+	'external-docs-and-xml-metadata': 'a schema field\'s `externalDocs` or `xml` keyword -- dropped unconditionally while inlining a schema (contracts/openapi.mjs\'s DROPPED_KEYWORDS), regardless of `--descriptions`. Permanently unbuilt: 0 real occurrences of either keyword measured against either real corpus (the original Team-IZ-Backend oracle or the larger polarsource/polar re-measurement) -- see D-oracle-corpus-openapi-remeasurement in DECISIONS.md',
 	'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',
@@ -145,6 +156,26 @@ function schemaHasFieldDocs(node, seen = new Set()) {
 	return false;
 }
 
+// A14 (D-openapi-field-metadata-passthrough): the exact same recursive shape as schemaHasFieldDocs
+// above, checking the OTHER three DOCUMENTATION_KEYWORDS (title/examples/deprecated) instead of
+// description/example -- kept as a separate function rather than merged into schemaHasFieldDocs
+// so the two disclosure keys (`field-descriptions` vs `field-metadata`) stay independently
+// derived from what's ACTUALLY in the projected schema, not conflated into one flag a caller
+// can't tell apart.
+function schemaHasFieldMetadata(node, seen = new Set()) {
+	if (node === null || typeof node !== 'object' || Array.isArray(node) || seen.has(node)) return false;
+	seen.add(node);
+	if (typeof node.title === 'string' || Object.hasOwn(node, 'examples') || Object.hasOwn(node, 'deprecated')) return true;
+	if (node.properties && typeof node.properties === 'object' && !Array.isArray(node.properties)) {
+		for (const propSchema of Object.values(node.properties)) {
+			if (schemaHasFieldMetadata(propSchema, seen)) return true;
+		}
+	}
+	if (node.items && typeof node.items === 'object' && schemaHasFieldMetadata(node.items, seen)) return true;
+	if (node.additionalProperties && typeof node.additionalProperties === 'object' && schemaHasFieldMetadata(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.
@@ -196,6 +227,10 @@ export function collectOmissions(contract) {
 		// 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');
+		// A14: same ANY-based doctrine as field-descriptions immediately above -- added whenever
+		// NONE of this operation's projected schemas carry a field-level title/examples/deprecated,
+		// including the case where the operation has no projected schema at all.
+		if (!fieldSchemas.some((s) => schemaHasFieldMetadata(s))) omissions.add('field-metadata');
 	}
 	return [...omissions].sort();
 }
@@ -239,20 +274,37 @@ function renderDescription(contract, omissions, statusCodes) {
 	return lines.join('\n');
 }
 
+// Update (D-openapi-export, closing the gap named in D-openapi-reconciliation's own Update note):
+// rewrites Express's own `:name`/`:name(...)` segments into OpenAPI's `{name}` templating -- an
+// OpenAPI Paths Object key must use `{name}` (verified against the real 3.1 meta-schema), but
+// `op.path` for an unmatched/document-less typescript-express operation is still the scan's own
+// colon syntax. A true no-op for java-spring/python-fastapi (their own paths never contain a colon
+// in this position, confirmed live -- no behavior change).
+function colonPathToBraceSyntax(routePath) {
+	return routePath.replace(/:(\w+)(?:\([^)]*\))?/g, '{$1}');
+}
+
 // Every `{name}` in the path template, in order, deduplicated (OpenAPI forbids two parameters
 // sharing name+location). The schema comes from the contract's own `pathParams.properties`; the
 // `{}` fallback for a name the contract has no property for is "unconstrained", which is both
 // honest and the minimum the 3.1 meta-schema accepts (`$defs.parameter`'s
 // `oneOf: [{required:["schema"]}, {required:["content"]}]` means a parameter MUST carry one or the
 // other -- confirmed by executing the real schema).
+//
+// Update (D-openapi-export, closing the gap named in D-openapi-reconciliation's own Update note):
+// also recognizes Express's own `:name`/`:name(...)` syntax -- `op.path` for a typescript-express
+// operation that never matched/adopted against an OpenAPI document (drift/missing/unresolved/
+// ambiguous, or a document-less scan-only contract) is still the scan's own colon syntax, and this
+// function would otherwise silently list zero path parameters for it. The existing `{name}`
+// branch's own character class (`[^{}/]+`, more permissive than `\w+`) stays untouched.
 function buildPathParameters(op) {
 	const props = op.pathParams && typeof op.pathParams === 'object' && !Array.isArray(op.pathParams)
 		? (op.pathParams.properties ?? {})
 		: {};
 	const seen = new Set();
 	const params = [];
-	for (const match of String(op.path).matchAll(/\{([^{}/]+)\}/g)) {
-		const name = match[1];
+	for (const match of String(op.path).matchAll(/\{([^{}/]+)\}|:(\w+)(?:\([^)]*\))?/g)) {
+		const name = match[1] ?? match[2];
 		if (seen.has(name)) continue;
 		seen.add(name);
 		params.push({
@@ -500,7 +552,13 @@ export function buildOpenApiDocument({ contract, snapshot = null, options = {} }
 
 	for (const operationId of operationIds) {
 		const op = contract.operations[operationId];
-		const route = String(op.path);
+		// Update (D-openapi-export): op.path can still be Express's own colon syntax (a
+		// typescript-express operation that never matched/adopted against an OpenAPI document) --
+		// an OpenAPI Paths Object key must use {name} templating (verified against the real 3.1
+		// meta-schema), so this is rewritten unconditionally here, once, before it becomes both the
+		// document's own path key AND every downstream use of `route` in this loop. A no-op for
+		// java-spring/python-fastapi (their own paths never contain a colon in this position).
+		const route = colonPathToBraceSyntax(String(op.path));
 		if (!route.startsWith('/')) {
 			return { ok: false, error: `operation "${operationId}" has path "${route}", which does not start with "/" -- an OpenAPI Paths Object key must (verified against the official 3.1 meta-schema)` };
 		}