@lssm/bundle.contractspec-workspace 0.0.0-canary-20251217060834 → 0.0.0-canary-20251217072406

package/dist/libs/contracts-transformers/dist/openapi/importer.js

@@ -0,0 +1,255 @@
+import { toFileName, toPascalCase, toSpecName, toValidIdentifier } from "../common/utils.js";
+import { generateImports, generateSchemaModelCode } from "./schema-converter.js";
+
+//#region ../../libs/contracts-transformers/dist/openapi/importer.js
+/**
+* HTTP methods that typically indicate a command (state-changing).
+*/
+const COMMAND_METHODS = [
+	"post",
+	"put",
+	"delete",
+	"patch"
+];
+/**
+* Determine if an operation is a command or query based on HTTP method.
+*/
+function inferOpKind(method) {
+	return COMMAND_METHODS.includes(method.toLowerCase()) ? "command" : "query";
+}
+/**
+* Determine auth level based on security requirements.
+*/
+function inferAuthLevel(operation, defaultAuth) {
+	if (!operation.security || operation.security.length === 0) return defaultAuth;
+	for (const sec of operation.security) if (Object.keys(sec).length === 0) return "anonymous";
+	return "user";
+}
+/**
+* Build a merged input schema from all parameter sources.
+*/
+function buildInputSchema(operation) {
+	const fields = [];
+	for (const param of operation.pathParams) fields.push({
+		name: param.name,
+		schema: param.schema,
+		required: true
+	});
+	for (const param of operation.queryParams) fields.push({
+		name: param.name,
+		schema: param.schema,
+		required: param.required
+	});
+	const excludedHeaders = [
+		"authorization",
+		"content-type",
+		"accept",
+		"user-agent"
+	];
+	for (const param of operation.headerParams) if (!excludedHeaders.includes(param.name.toLowerCase())) fields.push({
+		name: param.name,
+		schema: param.schema,
+		required: param.required
+	});
+	if (operation.requestBody?.schema) {
+		const bodySchema = operation.requestBody.schema;
+		if (!("$ref" in bodySchema)) {
+			const schemaObj = bodySchema;
+			const properties = schemaObj["properties"];
+			const required = schemaObj["required"] ?? [];
+			if (properties) for (const [propName, propSchema] of Object.entries(properties)) fields.push({
+				name: propName,
+				schema: propSchema,
+				required: required.includes(propName)
+			});
+		} else fields.push({
+			name: "body",
+			schema: bodySchema,
+			required: operation.requestBody.required
+		});
+	}
+	if (fields.length === 0) return {
+		schema: null,
+		fields: []
+	};
+	return {
+		schema: {
+			type: "object",
+			properties: fields.reduce((acc, f) => {
+				acc[f.name] = f.schema;
+				return acc;
+			}, {}),
+			required: fields.filter((f) => f.required).map((f) => f.name)
+		},
+		fields
+	};
+}
+/**
+* Get the output schema from the operation responses.
+*/
+function getOutputSchema(operation) {
+	for (const code of [
+		"200",
+		"201",
+		"202",
+		"204"
+	]) {
+		const response = operation.responses[code];
+		if (response?.schema) return response.schema;
+	}
+	for (const [code, response] of Object.entries(operation.responses)) if (code.startsWith("2") && response.schema) return response.schema;
+	return null;
+}
+/**
+* Generate ContractSpec TypeScript code for an operation.
+*/
+function generateSpecCode(operation, options, inputModel, outputModel) {
+	const specName = toSpecName(operation.operationId, options.prefix);
+	const kind = inferOpKind(operation.method);
+	const auth = inferAuthLevel(operation, options.defaultAuth ?? "user");
+	const lines = [];
+	lines.push("import { defineCommand, defineQuery } from '@lssm/lib.contracts';");
+	if (inputModel || outputModel) lines.push(generateImports([...inputModel?.fields ?? [], ...outputModel?.fields ?? []]));
+	lines.push("");
+	if (inputModel && inputModel.code) {
+		lines.push("// Input schema");
+		lines.push(inputModel.code);
+		lines.push("");
+	}
+	if (outputModel && outputModel.code) {
+		lines.push("// Output schema");
+		lines.push(outputModel.code);
+		lines.push("");
+	}
+	const defineFunc = kind === "command" ? "defineCommand" : "defineQuery";
+	const safeName = toValidIdentifier(toPascalCase(operation.operationId));
+	lines.push(`/**`);
+	lines.push(` * ${operation.summary ?? operation.operationId}`);
+	if (operation.description) {
+		lines.push(` *`);
+		lines.push(` * ${operation.description}`);
+	}
+	lines.push(` *`);
+	lines.push(` * @source OpenAPI: ${operation.method.toUpperCase()} ${operation.path}`);
+	lines.push(` */`);
+	lines.push(`export const ${safeName}Spec = ${defineFunc}({`);
+	lines.push("  meta: {");
+	lines.push(`    name: '${specName}',`);
+	lines.push("    version: 1,");
+	lines.push(`    stability: '${options.defaultStability ?? "stable"}',`);
+	lines.push(`    owners: [${(options.defaultOwners ?? []).map((o) => `'${o}'`).join(", ")}],`);
+	lines.push(`    tags: [${operation.tags.map((t) => `'${t}'`).join(", ")}],`);
+	lines.push(`    description: ${JSON.stringify(operation.summary ?? operation.operationId)},`);
+	lines.push(`    goal: ${JSON.stringify(operation.description ?? "Imported from OpenAPI")},`);
+	lines.push(`    context: 'Imported from OpenAPI: ${operation.method.toUpperCase()} ${operation.path}',`);
+	lines.push("  },");
+	lines.push("  io: {");
+	if (inputModel) lines.push(`    input: ${inputModel.name},`);
+	else lines.push("    input: null,");
+	if (outputModel) lines.push(`    output: ${outputModel.name},`);
+	else lines.push("    output: null, // TODO: Define output schema");
+	lines.push("  },");
+	lines.push("  policy: {");
+	lines.push(`    auth: '${auth}',`);
+	lines.push("  },");
+	lines.push("  transport: {");
+	lines.push("    rest: {");
+	lines.push(`      method: '${operation.method.toUpperCase()}',`);
+	lines.push(`      path: '${operation.path}',`);
+	lines.push("    },");
+	lines.push("  },");
+	lines.push("});");
+	return lines.join("\n");
+}
+/**
+* Import operations from a parsed OpenAPI document.
+*/
+function importFromOpenApi(parseResult, options = {}) {
+	const { tags, exclude = [], include } = options;
+	const specs = [];
+	const skipped = [];
+	const errors = [];
+	for (const operation of parseResult.operations) {
+		if (tags && tags.length > 0) {
+			if (!operation.tags.some((t) => tags.includes(t))) {
+				skipped.push({
+					sourceId: operation.operationId,
+					reason: `No matching tags (has: ${operation.tags.join(", ")})`
+				});
+				continue;
+			}
+		}
+		if (include && include.length > 0) {
+			if (!include.includes(operation.operationId)) {
+				skipped.push({
+					sourceId: operation.operationId,
+					reason: "Not in include list"
+				});
+				continue;
+			}
+		} else if (exclude.includes(operation.operationId)) {
+			skipped.push({
+				sourceId: operation.operationId,
+				reason: "In exclude list"
+			});
+			continue;
+		}
+		if (operation.deprecated && options.defaultStability !== "deprecated") {
+			skipped.push({
+				sourceId: operation.operationId,
+				reason: "Deprecated operation"
+			});
+			continue;
+		}
+		try {
+			const { schema: inputSchema } = buildInputSchema(operation);
+			const inputModel = inputSchema ? generateSchemaModelCode(inputSchema, `${operation.operationId}Input`) : null;
+			const outputSchema = getOutputSchema(operation);
+			const code = generateSpecCode(operation, options, inputModel, outputSchema ? generateSchemaModelCode(outputSchema, `${operation.operationId}Output`) : null);
+			const fileName = toFileName(toSpecName(operation.operationId, options.prefix));
+			const transportHints = { rest: {
+				method: operation.method.toUpperCase(),
+				path: operation.path,
+				params: {
+					path: operation.pathParams.map((p) => p.name),
+					query: operation.queryParams.map((p) => p.name),
+					header: operation.headerParams.map((p) => p.name),
+					cookie: operation.cookieParams.map((p) => p.name)
+				}
+			} };
+			const source = {
+				type: "openapi",
+				sourceId: operation.operationId,
+				operationId: operation.operationId,
+				openApiVersion: parseResult.version,
+				importedAt: /* @__PURE__ */ new Date()
+			};
+			specs.push({
+				spec: {},
+				code,
+				fileName,
+				source,
+				transportHints
+			});
+		} catch (error) {
+			errors.push({
+				sourceId: operation.operationId,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	return {
+		specs,
+		skipped,
+		errors,
+		summary: {
+			total: parseResult.operations.length,
+			imported: specs.length,
+			skipped: skipped.length,
+			errors: errors.length
+		}
+	};
+}
+
+//#endregion
+export { importFromOpenApi };

package/dist/libs/contracts-transformers/dist/openapi/index.js

@@ -0,0 +1,4 @@
+import { detectFormat, detectVersion, parseOpenApi, parseOpenApiDocument, parseOpenApiString } from "./parser.js";
+import "./exporter.js";
+import { generateImports, generateSchemaModelCode, getScalarType, jsonSchemaToField, jsonSchemaToType } from "./schema-converter.js";
+import { importFromOpenApi } from "./importer.js";

package/dist/libs/contracts-transformers/dist/openapi/parser.js

@@ -0,0 +1,231 @@
+import { parse } from "yaml";
+
+//#region ../../libs/contracts-transformers/dist/openapi/parser.js
+/**
+* OpenAPI document parser.
+* Parses OpenAPI 3.x documents from JSON/YAML files or URLs.
+*/
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"put",
+	"delete",
+	"patch",
+	"head",
+	"options",
+	"trace"
+];
+/**
+* Parse an OpenAPI document from a string (JSON or YAML).
+*/
+function parseOpenApiString(content, format = "json") {
+	if (format === "yaml") return parse(content);
+	return JSON.parse(content);
+}
+/**
+* Detect the format of content (JSON or YAML).
+*/
+function detectFormat(content) {
+	const trimmed = content.trim();
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) return "json";
+	return "yaml";
+}
+/**
+* Detect OpenAPI version from document.
+*/
+function detectVersion(doc) {
+	if (doc.openapi.startsWith("3.1")) return "3.1";
+	return "3.0";
+}
+/**
+* Check if a value is a reference object.
+*/
+function isReference(obj) {
+	return typeof obj === "object" && obj !== null && "$ref" in obj;
+}
+/**
+* Resolve a $ref reference in the document.
+*/
+function resolveRef(doc, ref) {
+	if (!ref.startsWith("#/")) return;
+	const path = ref.slice(2).split("/");
+	let current = doc;
+	for (const part of path) {
+		if (current === null || current === void 0) return void 0;
+		if (typeof current !== "object") return void 0;
+		current = current[part];
+	}
+	return current;
+}
+/**
+* Resolve a schema, following $ref if needed.
+*/
+function resolveSchema(doc, schema) {
+	if (!schema) return void 0;
+	if (isReference(schema)) return resolveRef(doc, schema.$ref) ?? schema;
+	return schema;
+}
+/**
+* Parse parameters from an operation.
+*/
+function parseParameters(doc, params) {
+	const result = {
+		path: [],
+		query: [],
+		header: [],
+		cookie: []
+	};
+	if (!params) return result;
+	for (const param of params) {
+		let resolved;
+		if (isReference(param)) {
+			const ref = resolveRef(doc, param.$ref);
+			if (!ref) continue;
+			resolved = ref;
+		} else resolved = param;
+		const parsed = {
+			name: resolved.name,
+			in: resolved.in,
+			required: resolved.required ?? resolved.in === "path",
+			description: resolved.description,
+			schema: resolved.schema,
+			deprecated: resolved.deprecated ?? false
+		};
+		result[resolved.in]?.push(parsed);
+	}
+	return result;
+}
+/**
+* Generate an operationId if not present.
+*/
+function generateOperationId(method, path) {
+	return method + path.split("/").filter(Boolean).map((part) => {
+		if (part.startsWith("{") && part.endsWith("}")) return "By" + part.slice(1, -1).charAt(0).toUpperCase() + part.slice(2, -1);
+		return part.charAt(0).toUpperCase() + part.slice(1);
+	}).join("");
+}
+/**
+* Parse a single operation.
+*/
+function parseOperation(doc, method, path, operation, pathParams) {
+	const params = parseParameters(doc, [...pathParams ?? [], ...operation.parameters ?? []]);
+	let requestBody;
+	if (operation.requestBody) {
+		const body = isReference(operation.requestBody) ? resolveRef(doc, operation.requestBody.$ref) : operation.requestBody;
+		if (body) {
+			const contentType = Object.keys(body.content ?? {})[0] ?? "application/json";
+			const content = body.content?.[contentType];
+			if (content?.schema) requestBody = {
+				required: body.required ?? false,
+				schema: resolveSchema(doc, content.schema),
+				contentType
+			};
+		}
+	}
+	const responses = {};
+	for (const [status, response] of Object.entries(operation.responses ?? {})) {
+		const resolved = isReference(response) ? resolveRef(doc, response.$ref) : response;
+		if (resolved) {
+			const contentType = Object.keys(resolved.content ?? {})[0];
+			const content = contentType ? resolved.content?.[contentType] : void 0;
+			responses[status] = {
+				description: resolved.description,
+				schema: content?.schema ? resolveSchema(doc, content.schema) : void 0,
+				contentType
+			};
+		}
+	}
+	const contractSpecMeta = operation?.["x-contractspec"];
+	return {
+		operationId: operation.operationId ?? generateOperationId(method, path),
+		method,
+		path,
+		summary: operation.summary,
+		description: operation.description,
+		tags: operation.tags ?? [],
+		pathParams: params.path,
+		queryParams: params.query,
+		headerParams: params.header,
+		cookieParams: params.cookie,
+		requestBody,
+		responses,
+		deprecated: operation.deprecated ?? false,
+		security: operation.security,
+		contractSpecMeta
+	};
+}
+/**
+* Parse an OpenAPI document into a structured result.
+*/
+function parseOpenApiDocument(doc, _options = {}) {
+	const version = detectVersion(doc);
+	const warnings = [];
+	const operations = [];
+	for (const [path, pathItem] of Object.entries(doc.paths ?? {})) {
+		if (!pathItem) continue;
+		const pathParams = pathItem.parameters;
+		for (const method of HTTP_METHODS) {
+			const operation = pathItem[method];
+			if (operation) try {
+				operations.push(parseOperation(doc, method, path, operation, pathParams));
+			} catch (error) {
+				warnings.push(`Failed to parse ${method.toUpperCase()} ${path}: ${error}`);
+			}
+		}
+	}
+	const schemas = {};
+	const components = doc.components;
+	if (components?.schemas) for (const [name, schema] of Object.entries(components.schemas)) schemas[name] = schema;
+	const servers = (doc.servers ?? []).map((s) => ({
+		url: s.url,
+		description: s.description,
+		variables: s.variables
+	}));
+	return {
+		document: doc,
+		version,
+		info: {
+			title: doc.info.title,
+			version: doc.info.version,
+			description: doc.info.description
+		},
+		operations,
+		schemas,
+		servers,
+		warnings
+	};
+}
+/**
+* Parse OpenAPI from a file path or URL.
+* Note: This is an async function that requires I/O adapters.
+* For pure parsing, use parseOpenApiString or parseOpenApiDocument.
+*/
+async function parseOpenApi(source, options = {}) {
+	const { fetch: fetchFn = globalThis.fetch, readFile, timeout = 3e4 } = options;
+	let content;
+	let format;
+	if (source.startsWith("http://") || source.startsWith("https://")) {
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), timeout);
+		try {
+			const response = await fetchFn(source, { signal: controller.signal });
+			if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			content = await response.text();
+		} finally {
+			clearTimeout(timeoutId);
+		}
+		if (source.endsWith(".yaml") || source.endsWith(".yml")) format = "yaml";
+		else if (source.endsWith(".json")) format = "json";
+		else format = detectFormat(content);
+	} else {
+		if (!readFile) throw new Error("readFile adapter required for file paths");
+		content = await readFile(source);
+		if (source.endsWith(".yaml") || source.endsWith(".yml")) format = "yaml";
+		else if (source.endsWith(".json")) format = "json";
+		else format = detectFormat(content);
+	}
+	return parseOpenApiDocument(parseOpenApiString(content, format), options);
+}
+
+//#endregion
+export { detectFormat, detectVersion, parseOpenApi, parseOpenApiDocument, parseOpenApiString };

package/dist/libs/contracts-transformers/dist/openapi/schema-converter.js

@@ -0,0 +1,201 @@
+import { toCamelCase, toPascalCase, toValidIdentifier } from "../common/utils.js";
+
+//#region ../../libs/contracts-transformers/dist/openapi/schema-converter.js
+/**
+* Map JSON Schema types to ContractSpec ScalarTypeEnum values.
+*/
+const JSON_SCHEMA_TO_SCALAR = {
+	string: "ScalarTypeEnum.STRING",
+	integer: "ScalarTypeEnum.INT",
+	number: "ScalarTypeEnum.FLOAT",
+	boolean: "ScalarTypeEnum.BOOLEAN",
+	"string:date": "ScalarTypeEnum.DATE",
+	"string:date-time": "ScalarTypeEnum.DATE_TIME",
+	"string:email": "ScalarTypeEnum.EMAIL",
+	"string:uri": "ScalarTypeEnum.URL",
+	"string:uuid": "ScalarTypeEnum.ID"
+};
+/**
+* Check if a schema is a reference object.
+*/
+function isReference(schema) {
+	return "$ref" in schema;
+}
+/**
+* Extract type name from a $ref.
+*/
+function typeNameFromRef(ref) {
+	const parts = ref.split("/");
+	return parts[parts.length - 1] ?? "Unknown";
+}
+/**
+* Convert a JSON Schema to a TypeScript type representation.
+*/
+function jsonSchemaToType(schema, name) {
+	if (isReference(schema)) return {
+		type: toPascalCase(typeNameFromRef(schema.$ref)),
+		optional: false,
+		array: false,
+		primitive: false
+	};
+	const schemaObj = schema;
+	const type = schemaObj["type"];
+	const format = schemaObj["format"];
+	const nullable = schemaObj["nullable"];
+	if (type === "array") {
+		const items = schemaObj["items"];
+		if (items) return {
+			...jsonSchemaToType(items, name),
+			array: true,
+			optional: nullable ?? false
+		};
+		return {
+			type: "unknown",
+			optional: nullable ?? false,
+			array: true,
+			primitive: false
+		};
+	}
+	if (type === "object" || schemaObj["properties"]) return {
+		type: name ? toPascalCase(name) : "Record<string, unknown>",
+		optional: nullable ?? false,
+		array: false,
+		primitive: false
+	};
+	if (schemaObj["enum"]) return {
+		type: name ? toPascalCase(name) : "string",
+		optional: nullable ?? false,
+		array: false,
+		primitive: false
+	};
+	format && `${type}${format}`;
+	if (type === "string") return {
+		type: "string",
+		optional: nullable ?? false,
+		array: false,
+		primitive: true
+	};
+	if (type === "integer" || type === "number") return {
+		type: "number",
+		optional: nullable ?? false,
+		array: false,
+		primitive: true
+	};
+	if (type === "boolean") return {
+		type: "boolean",
+		optional: nullable ?? false,
+		array: false,
+		primitive: true
+	};
+	return {
+		type: "unknown",
+		optional: nullable ?? false,
+		array: false,
+		primitive: false
+	};
+}
+/**
+* Get the ScalarTypeEnum value for a JSON Schema type.
+*/
+function getScalarType(schema) {
+	if (isReference(schema)) return;
+	const schemaObj = schema;
+	const type = schemaObj["type"];
+	const format = schemaObj["format"];
+	if (!type) return void 0;
+	return JSON_SCHEMA_TO_SCALAR[format ? `${type}:${format}` : type] ?? JSON_SCHEMA_TO_SCALAR[type];
+}
+/**
+* Convert a JSON Schema to a SchemaModel field definition.
+*/
+function jsonSchemaToField(schema, fieldName, required) {
+	const type = jsonSchemaToType(schema, fieldName);
+	const scalarType = getScalarType(schema);
+	let enumValues;
+	if (!isReference(schema)) {
+		const enumArr = schema["enum"];
+		if (enumArr) enumValues = enumArr.map(String);
+	}
+	return {
+		name: toValidIdentifier(toCamelCase(fieldName)),
+		type: {
+			...type,
+			optional: !required || type.optional,
+			description: !isReference(schema) ? schema["description"] : void 0
+		},
+		scalarType,
+		enumValues
+	};
+}
+/**
+* Generate SchemaModel TypeScript code for a JSON Schema object.
+*/
+function generateSchemaModelCode(schema, modelName, indent = 0) {
+	const spaces = "  ".repeat(indent);
+	const fields = [];
+	let description;
+	if (isReference(schema)) return {
+		name: toPascalCase(typeNameFromRef(schema.$ref)),
+		fields: [],
+		code: `// Reference to ${schema.$ref}`
+	};
+	const schemaObj = schema;
+	description = schemaObj["description"];
+	const properties = schemaObj["properties"];
+	const required = schemaObj["required"] ?? [];
+	if (!properties) return {
+		name: toPascalCase(modelName),
+		description,
+		fields: [],
+		code: `${spaces}// Empty schema for ${modelName}`
+	};
+	for (const [propName, propSchema] of Object.entries(properties)) {
+		const isRequired = required.includes(propName);
+		fields.push(jsonSchemaToField(propSchema, propName, isRequired));
+	}
+	const lines = [];
+	const safeModelName = toPascalCase(toValidIdentifier(modelName));
+	lines.push(`${spaces}export const ${safeModelName} = defineSchemaModel({`);
+	lines.push(`${spaces}  name: '${safeModelName}',`);
+	if (description) lines.push(`${spaces}  description: ${JSON.stringify(description)},`);
+	lines.push(`${spaces}  fields: {`);
+	for (const field of fields) {
+		const fieldLines = generateFieldCode(field, indent + 2);
+		lines.push(fieldLines);
+	}
+	lines.push(`${spaces}  },`);
+	lines.push(`${spaces}});`);
+	return {
+		name: safeModelName,
+		description,
+		fields,
+		code: lines.join("\n")
+	};
+}
+/**
+* Generate TypeScript code for a single field.
+*/
+function generateFieldCode(field, indent) {
+	const spaces = "  ".repeat(indent);
+	const lines = [];
+	lines.push(`${spaces}${field.name}: {`);
+	if (field.enumValues) lines.push(`${spaces}  type: new EnumType([${field.enumValues.map((v) => `'${v}'`).join(", ")}]),`);
+	else if (field.scalarType) lines.push(`${spaces}  type: ${field.scalarType},`);
+	else lines.push(`${spaces}  type: ${field.type.type}, // TODO: Define or import this type`);
+	if (field.type.optional) lines.push(`${spaces}  isOptional: true,`);
+	if (field.type.array) lines.push(`${spaces}  isArray: true,`);
+	lines.push(`${spaces}},`);
+	return lines.join("\n");
+}
+/**
+* Generate import statements for a SchemaModel.
+*/
+function generateImports(fields) {
+	const imports = /* @__PURE__ */ new Set();
+	imports.add("import { defineSchemaModel, ScalarTypeEnum, EnumType } from '@lssm/lib.schema';");
+	for (const field of fields) if (!field.type.primitive && !field.enumValues && !field.scalarType) {}
+	return Array.from(imports).join("\n");
+}
+
+//#endregion
+export { generateImports, generateSchemaModelCode, getScalarType, jsonSchemaToField, jsonSchemaToType };