@lssm/lib.contracts-transformers 0.0.0-canary-20251217063201 → 0.0.0-canary-20251217073102

package/dist/common/index.js

@@ -1 +1,3 @@
-import{deepEqual as e,extractPathParams as t,getByPath as n,normalizePath as r,toCamelCase as i,toFileName as a,toKebabCase as o,toPascalCase as s,toSnakeCase as c,toSpecName as l,toValidIdentifier as u}from"./utils.js";export{e as deepEqual,t as extractPathParams,n as getByPath,r as normalizePath,i as toCamelCase,a as toFileName,o as toKebabCase,s as toPascalCase,c as toSnakeCase,l as toSpecName,u as toValidIdentifier};
+import { deepEqual, extractPathParams, getByPath, normalizePath, toCamelCase, toFileName, toKebabCase, toPascalCase, toSnakeCase, toSpecName, toValidIdentifier } from "./utils.js";
+
+export { deepEqual, extractPathParams, getByPath, normalizePath, toCamelCase, toFileName, toKebabCase, toPascalCase, toSnakeCase, toSpecName, toValidIdentifier };

package/dist/common/utils.js

@@ -1 +1,102 @@
-function e(e){return e.replace(/[-_./\s]+(.)?/g,(e,t)=>t?t.toUpperCase():``).replace(/^./,e=>e.toUpperCase())}function t(t){let n=e(t);return n.charAt(0).toLowerCase()+n.slice(1)}function n(e){return e.replace(/([a-z])([A-Z])/g,`$1-$2`).replace(/[\s_./]+/g,`-`).toLowerCase()}function r(e){return e.replace(/([a-z])([A-Z])/g,`$1_$2`).replace(/[\s\-./]+/g,`_`).toLowerCase()}function i(e){let t=e.replace(/[^a-zA-Z0-9_$]/g,`_`);return/^[0-9]/.test(t)&&(t=`_`+t),t}function a(e,n){let r=t(e);return n?`${n}.${r}`:r}function o(e){return n(e.replace(/\./g,`-`))+`.ts`}function s(e,t){if(e===t)return!0;if(e===null||t===null||typeof e!=typeof t)return!1;if(typeof e==`object`){let n=e,r=t,i=Object.keys(n),a=Object.keys(r);if(i.length!==a.length)return!1;for(let e of i)if(!a.includes(e)||!s(n[e],r[e]))return!1;return!0}return!1}function c(e,t){let n=t.split(`.`).filter(Boolean),r=e;for(let e of n){if(typeof r!=`object`||!r)return;r=r[e]}return r}function l(e){return(e.match(/\{([^}]+)\}/g)||[]).map(e=>e.slice(1,-1))}function u(e){let t=e.replace(/^\/+|\/+$/g,``);return t=t.replace(/\/+/g,`/`),`/`+t}export{s as deepEqual,l as extractPathParams,c as getByPath,u as normalizePath,t as toCamelCase,o as toFileName,n as toKebabCase,e as toPascalCase,r as toSnakeCase,a as toSpecName,i as toValidIdentifier};
+//#region src/common/utils.ts
+/**
+* Common utilities for contract transformations.
+*/
+/**
+* Convert a string to PascalCase.
+*/
+function toPascalCase(str) {
+	return str.replace(/[-_./\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^./, (c) => c.toUpperCase());
+}
+/**
+* Convert a string to camelCase.
+*/
+function toCamelCase(str) {
+	const pascal = toPascalCase(str);
+	return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+/**
+* Convert a string to kebab-case.
+*/
+function toKebabCase(str) {
+	return str.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_./]+/g, "-").toLowerCase();
+}
+/**
+* Convert a string to snake_case.
+*/
+function toSnakeCase(str) {
+	return str.replace(/([a-z])([A-Z])/g, "$1_$2").replace(/[\s\-./]+/g, "_").toLowerCase();
+}
+/**
+* Sanitize a string to be a valid TypeScript identifier.
+*/
+function toValidIdentifier(str) {
+	let result = str.replace(/[^a-zA-Z0-9_$]/g, "_");
+	if (/^[0-9]/.test(result)) result = "_" + result;
+	return result;
+}
+/**
+* Generate a ContractSpec name from an operation identifier.
+*/
+function toSpecName(operationId, prefix) {
+	const name = toCamelCase(operationId);
+	return prefix ? `${prefix}.${name}` : name;
+}
+/**
+* Generate a file name from a spec name.
+*/
+function toFileName(specName) {
+	return toKebabCase(specName.replace(/\./g, "-")) + ".ts";
+}
+/**
+* Deep equality check for objects.
+*/
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (a === null || b === null) return false;
+	if (typeof a !== typeof b) return false;
+	if (typeof a === "object") {
+		const aObj = a;
+		const bObj = b;
+		const aKeys = Object.keys(aObj);
+		const bKeys = Object.keys(bObj);
+		if (aKeys.length !== bKeys.length) return false;
+		for (const key of aKeys) {
+			if (!bKeys.includes(key)) return false;
+			if (!deepEqual(aObj[key], bObj[key])) return false;
+		}
+		return true;
+	}
+	return false;
+}
+/**
+* Get a value from an object by JSON path.
+*/
+function getByPath(obj, path) {
+	const parts = path.split(".").filter(Boolean);
+	let current = obj;
+	for (const part of parts) {
+		if (current === null || current === void 0) return void 0;
+		if (typeof current !== "object") return void 0;
+		current = current[part];
+	}
+	return current;
+}
+/**
+* Extract path parameters from a URL path template.
+* e.g., "/users/{userId}/orders/{orderId}" -> ["userId", "orderId"]
+*/
+function extractPathParams(path) {
+	return (path.match(/\{([^}]+)\}/g) || []).map((m) => m.slice(1, -1));
+}
+/**
+* Normalize a URL path for comparison.
+*/
+function normalizePath(path) {
+	let normalized = path.replace(/^\/+|\/+$/g, "");
+	normalized = normalized.replace(/\/+/g, "/");
+	return "/" + normalized;
+}
+
+//#endregion
+export { deepEqual, extractPathParams, getByPath, normalizePath, toCamelCase, toFileName, toKebabCase, toPascalCase, toSnakeCase, toSpecName, toValidIdentifier };

package/dist/index.js

@@ -1 +1,9 @@
-import{detectFormat as e,detectVersion as t,parseOpenApi as n,parseOpenApiDocument as r,parseOpenApiString as i}from"./openapi/parser.js";import{defaultRestPath as a,openApiForRegistry as o,openApiToJson as s,openApiToYaml as c}from"./openapi/exporter.js";import{deepEqual as l,extractPathParams as u,getByPath as d,normalizePath as f,toCamelCase as p,toFileName as m,toKebabCase as h,toPascalCase as g,toSnakeCase as _,toSpecName as v,toValidIdentifier as y}from"./common/utils.js";import{generateImports as b,generateSchemaModelCode as x,getScalarType as S,jsonSchemaToField as C,jsonSchemaToType as w}from"./openapi/schema-converter.js";import{importFromOpenApi as T,importOperation as E}from"./openapi/importer.js";import{createSpecDiff as D,diffAll as O,diffSpecVsOperation as k,diffSpecs as A,formatDiffChanges as j}from"./openapi/differ.js";import"./openapi/index.js";export{D as createSpecDiff,l as deepEqual,a as defaultRestPath,e as detectFormat,t as detectVersion,O as diffAll,k as diffSpecVsOperation,A as diffSpecs,u as extractPathParams,j as formatDiffChanges,b as generateImports,x as generateSchemaModelCode,d as getByPath,S as getScalarType,T as importFromOpenApi,E as importOperation,C as jsonSchemaToField,w as jsonSchemaToType,f as normalizePath,o as openApiForRegistry,s as openApiToJson,c as openApiToYaml,n as parseOpenApi,r as parseOpenApiDocument,i as parseOpenApiString,p as toCamelCase,m as toFileName,h as toKebabCase,g as toPascalCase,_ as toSnakeCase,v as toSpecName,y as toValidIdentifier};
+import { detectFormat, detectVersion, parseOpenApi, parseOpenApiDocument, parseOpenApiString } from "./openapi/parser.js";
+import { defaultRestPath, openApiForRegistry, openApiToJson, openApiToYaml } from "./openapi/exporter.js";
+import { deepEqual, extractPathParams, getByPath, normalizePath, toCamelCase, toFileName, toKebabCase, toPascalCase, toSnakeCase, toSpecName, toValidIdentifier } from "./common/utils.js";
+import { generateImports, generateSchemaModelCode, getScalarType, jsonSchemaToField, jsonSchemaToType } from "./openapi/schema-converter.js";
+import { importFromOpenApi, importOperation } from "./openapi/importer.js";
+import { createSpecDiff, diffAll, diffSpecVsOperation, diffSpecs, formatDiffChanges } from "./openapi/differ.js";
+import "./openapi/index.js";
+
+export { createSpecDiff, deepEqual, defaultRestPath, detectFormat, detectVersion, diffAll, diffSpecVsOperation, diffSpecs, extractPathParams, formatDiffChanges, generateImports, generateSchemaModelCode, getByPath, getScalarType, importFromOpenApi, importOperation, jsonSchemaToField, jsonSchemaToType, normalizePath, openApiForRegistry, openApiToJson, openApiToYaml, parseOpenApi, parseOpenApiDocument, parseOpenApiString, toCamelCase, toFileName, toKebabCase, toPascalCase, toSnakeCase, toSpecName, toValidIdentifier };

package/dist/openapi/differ.js

@@ -1,2 +1,214 @@
-import{deepEqual as e}from"../common/utils.js";function t(t,n,r,i){if(e(n,r))return null;let a=`modified`;return n==null?a=`added`:r==null?a=`removed`:typeof n!=typeof r&&(a=`type_changed`),{path:t,type:a,oldValue:n,newValue:r,description:i}}function n(e,r,i,a){let o=[];if(!r&&!i)return o;if(!r)return o.push({path:e,type:`added`,newValue:i,description:`Added ${e}`}),o;if(!i)return o.push({path:e,type:`removed`,oldValue:r,description:`Removed ${e}`}),o;let s=new Set([...Object.keys(r),...Object.keys(i)]);for(let c of s){let s=e?`${e}.${c}`:c;if(a.ignorePaths?.some(e=>s.startsWith(e)))continue;let l=r[c],u=i[c];if(typeof l==`object`&&typeof u==`object`)o.push(...n(s,l,u,a));else{let e=t(s,l,u,`Changed ${s}`);e&&o.push(e)}}return o}function r(n,r,i={}){let a=[];if(!i.ignoreDescriptions){let e=t(`meta.description`,n.meta.description,r.summary??r.description,`Description changed`);e&&a.push(e)}if(!i.ignoreTags){let t=[...n.meta.tags??[]].sort(),i=[...r.tags].sort();e(t,i)||a.push({path:`meta.tags`,type:`modified`,oldValue:t,newValue:i,description:`Tags changed`})}if(!i.ignoreTransport){let e=n.transport?.rest?.method??(n.meta.kind===`query`?`GET`:`POST`),t=r.method.toUpperCase();e!==t&&a.push({path:`transport.rest.method`,type:`modified`,oldValue:e,newValue:t,description:`HTTP method changed`});let i=n.transport?.rest?.path;i&&i!==r.path&&a.push({path:`transport.rest.path`,type:`modified`,oldValue:i,newValue:r.path,description:`Path changed`})}return n.meta.stability===`deprecated`!==r.deprecated&&a.push({path:`meta.stability`,type:`modified`,oldValue:n.meta.stability,newValue:r.deprecated?`deprecated`:`stable`,description:`Deprecation status changed`}),a}function i(e,t,r={}){let i=[],a=n(`meta`,e.meta,t.meta,{...r,ignorePaths:[...r.ignorePaths??[],...r.ignoreDescriptions?[`meta.description`,`meta.goal`,`meta.context`]:[],...r.ignoreTags?[`meta.tags`]:[]]});if(i.push(...a),!r.ignoreTransport){let a=n(`transport`,e.transport,t.transport,r);i.push(...a)}let o=n(`policy`,e.policy,t.policy,r);return i.push(...o),i}function a(e,t,n,r={}){let a=[],o=!1;return t?(a=i(t,n.spec,r),o=a.length===0):a=[{path:``,type:`added`,newValue:n.spec,description:`New spec imported from OpenAPI`}],{operationId:e,existing:t,incoming:n,changes:a,isEquivalent:o}}function o(e,t,n={}){let r=[],i=new Set;for(let o of t){let t=o.source.sourceId,s;for(let[n,r]of e){let e=r.meta.name;if(n===t||e.includes(t)){s=r,i.add(n);break}}r.push(a(t,s,o,n))}for(let[t,n]of e)i.has(t)||r.push({operationId:t,existing:n,incoming:void 0,changes:[{path:``,type:`removed`,oldValue:n,description:`Spec no longer exists in OpenAPI source`}],isEquivalent:!1});return r}function s(e){if(e.length===0)return`No changes detected`;let t=[];for(let n of e){let e={added:`+`,removed:`-`,modified:`~`,type_changed:`!`,required_changed:`?`}[n.type];t.push(`${e} ${n.path}: ${n.description}`),n.type===`modified`||n.type===`type_changed`?(t.push(`    old: ${JSON.stringify(n.oldValue)}`),t.push(`    new: ${JSON.stringify(n.newValue)}`)):n.type===`added`?t.push(`    value: ${JSON.stringify(n.newValue)}`):n.type===`removed`&&t.push(`    was: ${JSON.stringify(n.oldValue)}`)}return t.join(`
-`)}export{a as createSpecDiff,o as diffAll,r as diffSpecVsOperation,i as diffSpecs,s as formatDiffChanges};
+import { deepEqual } from "../common/utils.js";
+
+//#region src/openapi/differ.ts
+/**
+* Compare two values and generate a diff change if different.
+*/
+function compareValues(path, oldValue, newValue, description) {
+	if (deepEqual(oldValue, newValue)) return null;
+	let changeType = "modified";
+	if (oldValue === void 0 || oldValue === null) changeType = "added";
+	else if (newValue === void 0 || newValue === null) changeType = "removed";
+	else if (typeof oldValue !== typeof newValue) changeType = "type_changed";
+	return {
+		path,
+		type: changeType,
+		oldValue,
+		newValue,
+		description
+	};
+}
+/**
+* Diff two objects recursively.
+*/
+function diffObjects(path, oldObj, newObj, options) {
+	const changes = [];
+	if (!oldObj && !newObj) return changes;
+	if (!oldObj) {
+		changes.push({
+			path,
+			type: "added",
+			newValue: newObj,
+			description: `Added ${path}`
+		});
+		return changes;
+	}
+	if (!newObj) {
+		changes.push({
+			path,
+			type: "removed",
+			oldValue: oldObj,
+			description: `Removed ${path}`
+		});
+		return changes;
+	}
+	const allKeys = new Set([...Object.keys(oldObj), ...Object.keys(newObj)]);
+	for (const key of allKeys) {
+		const keyPath = path ? `${path}.${key}` : key;
+		if (options.ignorePaths?.some((p) => keyPath.startsWith(p))) continue;
+		const oldVal = oldObj[key];
+		const newVal = newObj[key];
+		if (typeof oldVal === "object" && typeof newVal === "object") changes.push(...diffObjects(keyPath, oldVal, newVal, options));
+		else {
+			const change = compareValues(keyPath, oldVal, newVal, `Changed ${keyPath}`);
+			if (change) changes.push(change);
+		}
+	}
+	return changes;
+}
+/**
+* Diff a ContractSpec against an OpenAPI operation.
+*/
+function diffSpecVsOperation(spec, operation, options = {}) {
+	const changes = [];
+	if (!options.ignoreDescriptions) {
+		const descChange = compareValues("meta.description", spec.meta.description, operation.summary ?? operation.description, "Description changed");
+		if (descChange) changes.push(descChange);
+	}
+	if (!options.ignoreTags) {
+		const oldTags = [...spec.meta.tags ?? []].sort();
+		const newTags = [...operation.tags].sort();
+		if (!deepEqual(oldTags, newTags)) changes.push({
+			path: "meta.tags",
+			type: "modified",
+			oldValue: oldTags,
+			newValue: newTags,
+			description: "Tags changed"
+		});
+	}
+	if (!options.ignoreTransport) {
+		const specMethod = spec.transport?.rest?.method ?? (spec.meta.kind === "query" ? "GET" : "POST");
+		const opMethod = operation.method.toUpperCase();
+		if (specMethod !== opMethod) changes.push({
+			path: "transport.rest.method",
+			type: "modified",
+			oldValue: specMethod,
+			newValue: opMethod,
+			description: "HTTP method changed"
+		});
+		const specPath = spec.transport?.rest?.path;
+		if (specPath && specPath !== operation.path) changes.push({
+			path: "transport.rest.path",
+			type: "modified",
+			oldValue: specPath,
+			newValue: operation.path,
+			description: "Path changed"
+		});
+	}
+	if (spec.meta.stability === "deprecated" !== operation.deprecated) changes.push({
+		path: "meta.stability",
+		type: "modified",
+		oldValue: spec.meta.stability,
+		newValue: operation.deprecated ? "deprecated" : "stable",
+		description: "Deprecation status changed"
+	});
+	return changes;
+}
+/**
+* Diff two ContractSpecs.
+*/
+function diffSpecs(oldSpec, newSpec, options = {}) {
+	const changes = [];
+	const metaChanges = diffObjects("meta", oldSpec.meta, newSpec.meta, {
+		...options,
+		ignorePaths: [
+			...options.ignorePaths ?? [],
+			...options.ignoreDescriptions ? [
+				"meta.description",
+				"meta.goal",
+				"meta.context"
+			] : [],
+			...options.ignoreTags ? ["meta.tags"] : []
+		]
+	});
+	changes.push(...metaChanges);
+	if (!options.ignoreTransport) {
+		const transportChanges = diffObjects("transport", oldSpec.transport, newSpec.transport, options);
+		changes.push(...transportChanges);
+	}
+	const policyChanges = diffObjects("policy", oldSpec.policy, newSpec.policy, options);
+	changes.push(...policyChanges);
+	return changes;
+}
+/**
+* Create a SpecDiff from an existing spec and an imported spec.
+*/
+function createSpecDiff(operationId, existing, incoming, options = {}) {
+	let changes = [];
+	let isEquivalent = false;
+	if (existing) {
+		changes = diffSpecs(existing, incoming.spec, options);
+		isEquivalent = changes.length === 0;
+	} else changes = [{
+		path: "",
+		type: "added",
+		newValue: incoming.spec,
+		description: "New spec imported from OpenAPI"
+	}];
+	return {
+		operationId,
+		existing,
+		incoming,
+		changes,
+		isEquivalent
+	};
+}
+/**
+* Batch diff multiple specs against OpenAPI operations.
+*/
+function diffAll(existingSpecs, importedSpecs, options = {}) {
+	const diffs = [];
+	const matchedExisting = /* @__PURE__ */ new Set();
+	for (const imported of importedSpecs) {
+		const operationId = imported.source.sourceId;
+		let existing;
+		for (const [key, spec] of existingSpecs) {
+			const specName = spec.meta.name;
+			if (key === operationId || specName.includes(operationId)) {
+				existing = spec;
+				matchedExisting.add(key);
+				break;
+			}
+		}
+		diffs.push(createSpecDiff(operationId, existing, imported, options));
+	}
+	for (const [key, spec] of existingSpecs) if (!matchedExisting.has(key)) diffs.push({
+		operationId: key,
+		existing: spec,
+		incoming: void 0,
+		changes: [{
+			path: "",
+			type: "removed",
+			oldValue: spec,
+			description: "Spec no longer exists in OpenAPI source"
+		}],
+		isEquivalent: false
+	});
+	return diffs;
+}
+/**
+* Format diff changes for display.
+*/
+function formatDiffChanges(changes) {
+	if (changes.length === 0) return "No changes detected";
+	const lines = [];
+	for (const change of changes) {
+		const prefix = {
+			added: "+",
+			removed: "-",
+			modified: "~",
+			type_changed: "!",
+			required_changed: "?"
+		}[change.type];
+		lines.push(`${prefix} ${change.path}: ${change.description}`);
+		if (change.type === "modified" || change.type === "type_changed") {
+			lines.push(`    old: ${JSON.stringify(change.oldValue)}`);
+			lines.push(`    new: ${JSON.stringify(change.newValue)}`);
+		} else if (change.type === "added") lines.push(`    value: ${JSON.stringify(change.newValue)}`);
+		else if (change.type === "removed") lines.push(`    was: ${JSON.stringify(change.oldValue)}`);
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+export { createSpecDiff, diffAll, diffSpecVsOperation, diffSpecs, formatDiffChanges };

package/dist/openapi/exporter.js

@@ -1 +1,150 @@
-import{z as e}from"zod";function t(e,t){return`${e.replace(/\./g,`_`)}_v${t}`}function n(e,n,r){return`${e}_${t(n,r)}`}function r(e,t){return(t??(e===`query`?`GET`:`POST`)).toLowerCase()}function i(e,t){return`/${e.replace(/\./g,`/`)}/v${t}`}function a(e){let t=e.transport?.rest?.path??i(e.meta.name,e.meta.version);return t.startsWith(`/`)?t:`/${t}`}function o(t){return t?e.toJSONSchema(t.getZod()):null}function s(e){return{input:o(e.io.input),output:o(e.io.output),meta:{name:e.meta.name,version:e.meta.version,kind:e.meta.kind,description:e.meta.description,tags:e.meta.tags??[],stability:e.meta.stability??`stable`}}}function c(e,i={}){let o=e.listSpecs().filter(e=>e.meta.kind===`command`||e.meta.kind===`query`).slice().sort((e,t)=>{let n=e.meta.name.localeCompare(t.meta.name);return n===0?e.meta.version-t.meta.version:n}),c={openapi:`3.1.0`,info:{title:i.title??`ContractSpec API`,version:i.version??`0.0.0`,...i.description?{description:i.description}:{}},...i.servers?{servers:i.servers}:{},paths:{},components:{schemas:{}}};for(let e of o){let i=s(e),o=r(e.meta.kind,e.transport?.rest?.method),l=a(e),u=t(e.meta.name,e.meta.version),d=c.paths[l]??={},f={operationId:u,summary:e.meta.description??e.meta.name,description:e.meta.description,tags:e.meta.tags??[],"x-contractspec":{name:e.meta.name,version:e.meta.version,kind:e.meta.kind},responses:{}};if(i.input){let t=n(`Input`,e.meta.name,e.meta.version);c.components.schemas[t]=i.input,f.requestBody={required:!0,content:{"application/json":{schema:{$ref:`#/components/schemas/${t}`}}}}}let p={};if(i.output){let t=n(`Output`,e.meta.name,e.meta.version);c.components.schemas[t]=i.output,p[200]={description:`OK`,content:{"application/json":{schema:{$ref:`#/components/schemas/${t}`}}}}}else p[200]={description:`OK`};f.responses=p,d[o]=f}return c}function l(e,t={}){let n=c(e,t);return JSON.stringify(n,null,2)}function u(e,t={}){return d(c(e,t))}function d(e,t=0){let n=`  `.repeat(t),r=``;if(Array.isArray(e))for(let i of e)typeof i==`object`&&i?r+=`${n}-\n${d(i,t+1)}`:r+=`${n}- ${JSON.stringify(i)}\n`;else if(typeof e==`object`&&e)for(let[i,a]of Object.entries(e))Array.isArray(a)||typeof a==`object`&&a?r+=`${n}${i}:\n${d(a,t+1)}`:r+=`${n}${i}: ${JSON.stringify(a)}\n`;return r}export{i as defaultRestPath,c as openApiForRegistry,l as openApiToJson,u as openApiToYaml};
+import { z } from "zod";
+
+//#region src/openapi/exporter.ts
+/**
+* Convert a spec name and version to an operationId.
+*/
+function toOperationId(name, version) {
+	return `${name.replace(/\./g, "_")}_v${version}`;
+}
+/**
+* Convert a spec name and version to a schema name.
+*/
+function toSchemaName(prefix, name, version) {
+	return `${prefix}_${toOperationId(name, version)}`;
+}
+/**
+* Determine HTTP method from spec kind and override.
+*/
+function toHttpMethod(kind, override) {
+	return (override ?? (kind === "query" ? "GET" : "POST")).toLowerCase();
+}
+/**
+* Generate default REST path from spec name and version.
+*/
+function defaultRestPath(name, version) {
+	return `/${name.replace(/\./g, "/")}/v${version}`;
+}
+/**
+* Get REST path from spec, using transport override or default.
+*/
+function toRestPath(spec) {
+	const path = spec.transport?.rest?.path ?? defaultRestPath(spec.meta.name, spec.meta.version);
+	return path.startsWith("/") ? path : `/${path}`;
+}
+/**
+* Convert a SchemaModel to JSON Schema using Zod.
+*/
+function schemaModelToJsonSchema(schema) {
+	if (!schema) return null;
+	return z.toJSONSchema(schema.getZod());
+}
+/**
+* Extract JSON Schema for a spec's input and output.
+*/
+function jsonSchemaForSpec(spec) {
+	return {
+		input: schemaModelToJsonSchema(spec.io.input),
+		output: schemaModelToJsonSchema(spec.io.output),
+		meta: {
+			name: spec.meta.name,
+			version: spec.meta.version,
+			kind: spec.meta.kind,
+			description: spec.meta.description,
+			tags: spec.meta.tags ?? [],
+			stability: spec.meta.stability ?? "stable"
+		}
+	};
+}
+/**
+* Export a SpecRegistry to an OpenAPI 3.1 document.
+*
+* @param registry - The SpecRegistry containing specs to export
+* @param options - Export options (title, version, description, servers)
+* @returns OpenAPI 3.1 document
+*/
+function openApiForRegistry(registry, options = {}) {
+	const specs = registry.listSpecs().filter((s) => s.meta.kind === "command" || s.meta.kind === "query").slice().sort((a, b) => {
+		const byName = a.meta.name.localeCompare(b.meta.name);
+		return byName !== 0 ? byName : a.meta.version - b.meta.version;
+	});
+	const doc = {
+		openapi: "3.1.0",
+		info: {
+			title: options.title ?? "ContractSpec API",
+			version: options.version ?? "0.0.0",
+			...options.description ? { description: options.description } : {}
+		},
+		...options.servers ? { servers: options.servers } : {},
+		paths: {},
+		components: { schemas: {} }
+	};
+	for (const spec of specs) {
+		const schema = jsonSchemaForSpec(spec);
+		const method = toHttpMethod(spec.meta.kind, spec.transport?.rest?.method);
+		const path = toRestPath(spec);
+		const operationId = toOperationId(spec.meta.name, spec.meta.version);
+		const pathItem = doc.paths[path] ??= {};
+		const op = {
+			operationId,
+			summary: spec.meta.description ?? spec.meta.name,
+			description: spec.meta.description,
+			tags: spec.meta.tags ?? [],
+			"x-contractspec": {
+				name: spec.meta.name,
+				version: spec.meta.version,
+				kind: spec.meta.kind
+			},
+			responses: {}
+		};
+		if (schema.input) {
+			const inputName = toSchemaName("Input", spec.meta.name, spec.meta.version);
+			doc.components.schemas[inputName] = schema.input;
+			op["requestBody"] = {
+				required: true,
+				content: { "application/json": { schema: { $ref: `#/components/schemas/${inputName}` } } }
+			};
+		}
+		const responses = {};
+		if (schema.output) {
+			const outputName = toSchemaName("Output", spec.meta.name, spec.meta.version);
+			doc.components.schemas[outputName] = schema.output;
+			responses["200"] = {
+				description: "OK",
+				content: { "application/json": { schema: { $ref: `#/components/schemas/${outputName}` } } }
+			};
+		} else responses["200"] = { description: "OK" };
+		op["responses"] = responses;
+		pathItem[method] = op;
+	}
+	return doc;
+}
+/**
+* Export a SpecRegistry to OpenAPI JSON string.
+*/
+function openApiToJson(registry, options = {}) {
+	const doc = openApiForRegistry(registry, options);
+	return JSON.stringify(doc, null, 2);
+}
+/**
+* Export a SpecRegistry to OpenAPI YAML string.
+*/
+function openApiToYaml(registry, options = {}) {
+	return jsonToYaml(openApiForRegistry(registry, options));
+}
+/**
+* Simple JSON to YAML conversion.
+*/
+function jsonToYaml(obj, indent = 0) {
+	const spaces = "  ".repeat(indent);
+	let yaml = "";
+	if (Array.isArray(obj)) for (const item of obj) if (typeof item === "object" && item !== null) yaml += `${spaces}-\n${jsonToYaml(item, indent + 1)}`;
+	else yaml += `${spaces}- ${JSON.stringify(item)}\n`;
+	else if (typeof obj === "object" && obj !== null) for (const [key, value] of Object.entries(obj)) if (Array.isArray(value)) yaml += `${spaces}${key}:\n${jsonToYaml(value, indent + 1)}`;
+	else if (typeof value === "object" && value !== null) yaml += `${spaces}${key}:\n${jsonToYaml(value, indent + 1)}`;
+	else yaml += `${spaces}${key}: ${JSON.stringify(value)}\n`;
+	return yaml;
+}
+
+//#endregion
+export { defaultRestPath, openApiForRegistry, openApiToJson, openApiToYaml };

package/dist/openapi/importer.js

@@ -1,2 +1,264 @@
-import{toFileName as e,toPascalCase as t,toSpecName as n,toValidIdentifier as r}from"../common/utils.js";import{generateImports as i,generateSchemaModelCode as a}from"./schema-converter.js";const o=[`post`,`put`,`delete`,`patch`];function s(e){return o.includes(e.toLowerCase())?`command`:`query`}function c(e,t){if(!e.security||e.security.length===0)return t;for(let t of e.security)if(Object.keys(t).length===0)return`anonymous`;return`user`}function l(e){let t=[];for(let n of e.pathParams)t.push({name:n.name,schema:n.schema,required:!0});for(let n of e.queryParams)t.push({name:n.name,schema:n.schema,required:n.required});let n=[`authorization`,`content-type`,`accept`,`user-agent`];for(let r of e.headerParams)n.includes(r.name.toLowerCase())||t.push({name:r.name,schema:r.schema,required:r.required});if(e.requestBody?.schema){let n=e.requestBody.schema;if(`$ref`in n)t.push({name:`body`,schema:n,required:e.requestBody.required});else{let e=n,r=e.properties,i=e.required??[];if(r)for(let[e,n]of Object.entries(r))t.push({name:e,schema:n,required:i.includes(e)})}}return t.length===0?{schema:null,fields:[]}:{schema:{type:`object`,properties:t.reduce((e,t)=>(e[t.name]=t.schema,e),{}),required:t.filter(e=>e.required).map(e=>e.name)},fields:t}}function u(e){for(let t of[`200`,`201`,`202`,`204`]){let n=e.responses[t];if(n?.schema)return n.schema}for(let[t,n]of Object.entries(e.responses))if(t.startsWith(`2`)&&n.schema)return n.schema;return null}function d(e,a,o,l){let u=n(e.operationId,a.prefix),d=s(e.method),f=c(e,a.defaultAuth??`user`),p=[];p.push(`import { defineCommand, defineQuery } from '@lssm/lib.contracts';`),(o||l)&&p.push(i([...o?.fields??[],...l?.fields??[]])),p.push(``),o&&o.code&&(p.push(`// Input schema`),p.push(o.code),p.push(``)),l&&l.code&&(p.push(`// Output schema`),p.push(l.code),p.push(``));let m=d===`command`?`defineCommand`:`defineQuery`,h=r(t(e.operationId));return p.push(`/**`),p.push(` * ${e.summary??e.operationId}`),e.description&&(p.push(` *`),p.push(` * ${e.description}`)),p.push(` *`),p.push(` * @source OpenAPI: ${e.method.toUpperCase()} ${e.path}`),p.push(` */`),p.push(`export const ${h}Spec = ${m}({`),p.push(`  meta: {`),p.push(`    name: '${u}',`),p.push(`    version: 1,`),p.push(`    stability: '${a.defaultStability??`stable`}',`),p.push(`    owners: [${(a.defaultOwners??[]).map(e=>`'${e}'`).join(`, `)}],`),p.push(`    tags: [${e.tags.map(e=>`'${e}'`).join(`, `)}],`),p.push(`    description: ${JSON.stringify(e.summary??e.operationId)},`),p.push(`    goal: ${JSON.stringify(e.description??`Imported from OpenAPI`)},`),p.push(`    context: 'Imported from OpenAPI: ${e.method.toUpperCase()} ${e.path}',`),p.push(`  },`),p.push(`  io: {`),o?p.push(`    input: ${o.name},`):p.push(`    input: null,`),l?p.push(`    output: ${l.name},`):p.push(`    output: null, // TODO: Define output schema`),p.push(`  },`),p.push(`  policy: {`),p.push(`    auth: '${f}',`),p.push(`  },`),p.push(`  transport: {`),p.push(`    rest: {`),p.push(`      method: '${e.method.toUpperCase()}',`),p.push(`      path: '${e.path}',`),p.push(`    },`),p.push(`  },`),p.push(`});`),p.join(`
-`)}function f(t,r={}){let{tags:i,exclude:o=[],include:s}=r,c=[],f=[],p=[];for(let m of t.operations){if(i&&i.length>0&&!m.tags.some(e=>i.includes(e))){f.push({sourceId:m.operationId,reason:`No matching tags (has: ${m.tags.join(`, `)})`});continue}if(s&&s.length>0){if(!s.includes(m.operationId)){f.push({sourceId:m.operationId,reason:`Not in include list`});continue}}else if(o.includes(m.operationId)){f.push({sourceId:m.operationId,reason:`In exclude list`});continue}if(m.deprecated&&r.defaultStability!==`deprecated`){f.push({sourceId:m.operationId,reason:`Deprecated operation`});continue}try{let{schema:i}=l(m),o=i?a(i,`${m.operationId}Input`):null,s=u(m),f=d(m,r,o,s?a(s,`${m.operationId}Output`):null),p=e(n(m.operationId,r.prefix)),h={rest:{method:m.method.toUpperCase(),path:m.path,params:{path:m.pathParams.map(e=>e.name),query:m.queryParams.map(e=>e.name),header:m.headerParams.map(e=>e.name),cookie:m.cookieParams.map(e=>e.name)}}},g={type:`openapi`,sourceId:m.operationId,operationId:m.operationId,openApiVersion:t.version,importedAt:new Date};c.push({spec:{},code:f,fileName:p,source:g,transportHints:h})}catch(e){p.push({sourceId:m.operationId,error:e instanceof Error?e.message:String(e)})}}return{specs:c,skipped:f,errors:p,summary:{total:t.operations.length,imported:c.length,skipped:f.length,errors:p.length}}}function p(e,t={}){let{schema:n}=l(e),r=n?a(n,`${e.operationId}Input`):null,i=u(e);return d(e,t,r,i?a(i,`${e.operationId}Output`):null)}export{f as importFromOpenApi,p as importOperation};
+import { toFileName, toPascalCase, toSpecName, toValidIdentifier } from "../common/utils.js";
+import { generateImports, generateSchemaModelCode } from "./schema-converter.js";
+
+//#region src/openapi/importer.ts
+/**
+* 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
+		}
+	};
+}
+/**
+* Import a single operation to ContractSpec code.
+*/
+function importOperation(operation, options = {}) {
+	const { schema: inputSchema } = buildInputSchema(operation);
+	const inputModel = inputSchema ? generateSchemaModelCode(inputSchema, `${operation.operationId}Input`) : null;
+	const outputSchema = getOutputSchema(operation);
+	return generateSpecCode(operation, options, inputModel, outputSchema ? generateSchemaModelCode(outputSchema, `${operation.operationId}Output`) : null);
+}
+
+//#endregion
+export { importFromOpenApi, importOperation };

package/dist/openapi/index.js

@@ -1 +1,7 @@
-import{detectFormat as e,detectVersion as t,parseOpenApi as n,parseOpenApiDocument as r,parseOpenApiString as i}from"./parser.js";import{defaultRestPath as a,openApiForRegistry as o,openApiToJson as s,openApiToYaml as c}from"./exporter.js";import{generateImports as l,generateSchemaModelCode as u,getScalarType as d,jsonSchemaToField as f,jsonSchemaToType as p}from"./schema-converter.js";import{importFromOpenApi as m,importOperation as h}from"./importer.js";import{createSpecDiff as g,diffAll as _,diffSpecVsOperation as v,diffSpecs as y,formatDiffChanges as b}from"./differ.js";export{g as createSpecDiff,a as defaultRestPath,e as detectFormat,t as detectVersion,_ as diffAll,v as diffSpecVsOperation,y as diffSpecs,b as formatDiffChanges,l as generateImports,u as generateSchemaModelCode,d as getScalarType,m as importFromOpenApi,h as importOperation,f as jsonSchemaToField,p as jsonSchemaToType,o as openApiForRegistry,s as openApiToJson,c as openApiToYaml,n as parseOpenApi,r as parseOpenApiDocument,i as parseOpenApiString};
+import { detectFormat, detectVersion, parseOpenApi, parseOpenApiDocument, parseOpenApiString } from "./parser.js";
+import { defaultRestPath, openApiForRegistry, openApiToJson, openApiToYaml } from "./exporter.js";
+import { generateImports, generateSchemaModelCode, getScalarType, jsonSchemaToField, jsonSchemaToType } from "./schema-converter.js";
+import { importFromOpenApi, importOperation } from "./importer.js";
+import { createSpecDiff, diffAll, diffSpecVsOperation, diffSpecs, formatDiffChanges } from "./differ.js";
+
+export { createSpecDiff, defaultRestPath, detectFormat, detectVersion, diffAll, diffSpecVsOperation, diffSpecs, formatDiffChanges, generateImports, generateSchemaModelCode, getScalarType, importFromOpenApi, importOperation, jsonSchemaToField, jsonSchemaToType, openApiForRegistry, openApiToJson, openApiToYaml, parseOpenApi, parseOpenApiDocument, parseOpenApiString };

package/dist/openapi/parser.js

@@ -1 +1,231 @@
-import{parse as e}from"yaml";const t=[`get`,`post`,`put`,`delete`,`patch`,`head`,`options`,`trace`];function n(t,n=`json`){return n===`yaml`?e(t):JSON.parse(t)}function r(e){let t=e.trim();return t.startsWith(`{`)||t.startsWith(`[`)?`json`:`yaml`}function i(e){return e.openapi.startsWith(`3.1`)?`3.1`:`3.0`}function a(e){return typeof e==`object`&&!!e&&`$ref`in e}function o(e,t){if(!t.startsWith(`#/`))return;let n=t.slice(2).split(`/`),r=e;for(let e of n){if(typeof r!=`object`||!r)return;r=r[e]}return r}function s(e,t){if(t)return a(t)?o(e,t.$ref)??t:t}function c(e,t){let n={path:[],query:[],header:[],cookie:[]};if(!t)return n;for(let r of t){let t;if(a(r)){let n=o(e,r.$ref);if(!n)continue;t=n}else t=r;let i={name:t.name,in:t.in,required:t.required??t.in===`path`,description:t.description,schema:t.schema,deprecated:t.deprecated??!1};n[t.in]?.push(i)}return n}function l(e,t){return e+t.split(`/`).filter(Boolean).map(e=>e.startsWith(`{`)&&e.endsWith(`}`)?`By`+e.slice(1,-1).charAt(0).toUpperCase()+e.slice(2,-1):e.charAt(0).toUpperCase()+e.slice(1)).join(``)}function u(e,t,n,r,i){let u=c(e,[...i??[],...r.parameters??[]]),d;if(r.requestBody){let t=a(r.requestBody)?o(e,r.requestBody.$ref):r.requestBody;if(t){let n=Object.keys(t.content??{})[0]??`application/json`,r=t.content?.[n];r?.schema&&(d={required:t.required??!1,schema:s(e,r.schema),contentType:n})}}let f={};for(let[t,n]of Object.entries(r.responses??{})){let r=a(n)?o(e,n.$ref):n;if(r){let n=Object.keys(r.content??{})[0],i=n?r.content?.[n]:void 0;f[t]={description:r.description,schema:i?.schema?s(e,i.schema):void 0,contentType:n}}}let p=r?.[`x-contractspec`];return{operationId:r.operationId??l(t,n),method:t,path:n,summary:r.summary,description:r.description,tags:r.tags??[],pathParams:u.path,queryParams:u.query,headerParams:u.header,cookieParams:u.cookie,requestBody:d,responses:f,deprecated:r.deprecated??!1,security:r.security,contractSpecMeta:p}}function d(e,n={}){let r=i(e),a=[],o=[];for(let[n,r]of Object.entries(e.paths??{})){if(!r)continue;let i=r.parameters;for(let s of t){let t=r[s];if(t)try{o.push(u(e,s,n,t,i))}catch(e){a.push(`Failed to parse ${s.toUpperCase()} ${n}: ${e}`)}}}let s={},c=e.components;if(c?.schemas)for(let[e,t]of Object.entries(c.schemas))s[e]=t;let l=(e.servers??[]).map(e=>({url:e.url,description:e.description,variables:e.variables}));return{document:e,version:r,info:{title:e.info.title,version:e.info.version,description:e.info.description},operations:o,schemas:s,servers:l,warnings:a}}async function f(e,t={}){let{fetch:i=globalThis.fetch,readFile:a,timeout:o=3e4}=t,s,c;if(e.startsWith(`http://`)||e.startsWith(`https://`)){let t=new AbortController,n=setTimeout(()=>t.abort(),o);try{let n=await i(e,{signal:t.signal});if(!n.ok)throw Error(`HTTP ${n.status}: ${n.statusText}`);s=await n.text()}finally{clearTimeout(n)}c=e.endsWith(`.yaml`)||e.endsWith(`.yml`)?`yaml`:e.endsWith(`.json`)?`json`:r(s)}else{if(!a)throw Error(`readFile adapter required for file paths`);s=await a(e),c=e.endsWith(`.yaml`)||e.endsWith(`.yml`)?`yaml`:e.endsWith(`.json`)?`json`:r(s)}return d(n(s,c),t)}export{r as detectFormat,i as detectVersion,f as parseOpenApi,d as parseOpenApiDocument,n as parseOpenApiString};
+import { parse } from "yaml";
+
+//#region src/openapi/parser.ts
+/**
+* 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/openapi/schema-converter.js

@@ -1,4 +1,201 @@
-import{toCamelCase as e,toPascalCase as t,toValidIdentifier as n}from"../common/utils.js";const r={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`};function i(e){return`$ref`in e}function a(e){let t=e.split(`/`);return t[t.length-1]??`Unknown`}function o(e,n){if(i(e))return{type:t(a(e.$ref)),optional:!1,array:!1,primitive:!1};let r=e,s=r.type,c=r.format,l=r.nullable;if(s===`array`){let e=r.items;return e?{...o(e,n),array:!0,optional:l??!1}:{type:`unknown`,optional:l??!1,array:!0,primitive:!1}}return s===`object`||r.properties?{type:n?t(n):`Record<string, unknown>`,optional:l??!1,array:!1,primitive:!1}:r.enum?{type:n?t(n):`string`,optional:l??!1,array:!1,primitive:!1}:(c&&`${s}${c}`,s===`string`?{type:`string`,optional:l??!1,array:!1,primitive:!0}:s===`integer`||s===`number`?{type:`number`,optional:l??!1,array:!1,primitive:!0}:s===`boolean`?{type:`boolean`,optional:l??!1,array:!1,primitive:!0}:{type:`unknown`,optional:l??!1,array:!1,primitive:!1})}function s(e){if(i(e))return;let t=e,n=t.type,a=t.format;if(n)return r[a?`${n}:${a}`:n]??r[n]}function c(t,r,a){let c=o(t,r),l=s(t),u;if(!i(t)){let e=t.enum;e&&(u=e.map(String))}return{name:n(e(r)),type:{...c,optional:!a||c.optional,description:i(t)?void 0:t.description},scalarType:l,enumValues:u}}function l(e,r,o=0){let s=`  `.repeat(o),l=[],d;if(i(e))return{name:t(a(e.$ref)),fields:[],code:`// Reference to ${e.$ref}`};let f=e;d=f.description;let p=f.properties,m=f.required??[];if(!p)return{name:t(r),description:d,fields:[],code:`${s}// Empty schema for ${r}`};for(let[e,t]of Object.entries(p)){let n=m.includes(e);l.push(c(t,e,n))}let h=[],g=t(n(r));h.push(`${s}export const ${g} = defineSchemaModel({`),h.push(`${s}  name: '${g}',`),d&&h.push(`${s}  description: ${JSON.stringify(d)},`),h.push(`${s}  fields: {`);for(let e of l){let t=u(e,o+2);h.push(t)}return h.push(`${s}  },`),h.push(`${s}});`),{name:g,description:d,fields:l,code:h.join(`
-`)}}function u(e,t){let n=`  `.repeat(t),r=[];return r.push(`${n}${e.name}: {`),e.enumValues?r.push(`${n}  type: new EnumType([${e.enumValues.map(e=>`'${e}'`).join(`, `)}]),`):e.scalarType?r.push(`${n}  type: ${e.scalarType},`):r.push(`${n}  type: ${e.type.type}, // TODO: Define or import this type`),e.type.optional&&r.push(`${n}  isOptional: true,`),e.type.array&&r.push(`${n}  isArray: true,`),r.push(`${n}},`),r.join(`
-`)}function d(e){let t=new Set;t.add(`import { defineSchemaModel, ScalarTypeEnum, EnumType } from '@lssm/lib.schema';`);for(let t of e)!t.type.primitive&&!t.enumValues&&t.scalarType;return Array.from(t).join(`
-`)}export{d as generateImports,l as generateSchemaModelCode,s as getScalarType,c as jsonSchemaToField,o as jsonSchemaToType};
+import { toCamelCase, toPascalCase, toValidIdentifier } from "../common/utils.js";
+
+//#region src/openapi/schema-converter.ts
+/**
+* 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.contracts-transformers",
-  "version": "0.0.0-canary-20251217063201",
+  "version": "0.0.0-canary-20251217073102",
   "description": "Contract format transformations: import/export between ContractSpec and external formats (OpenAPI, AsyncAPI, etc.)",
   "type": "module",
   "scripts": {
@@ -17,15 +17,15 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@lssm/lib.contracts": "0.0.0-canary-20251217063201",
-    "@lssm/lib.schema": "0.0.0-canary-20251217063201",
+    "@lssm/lib.contracts": "0.0.0-canary-20251217073102",
+    "@lssm/lib.schema": "0.0.0-canary-20251217073102",
     "openapi-types": "^12.1.3",
     "yaml": "^2.7.1",
     "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.0.0-canary-20251217063201",
-    "@lssm/tool.typescript": "0.0.0-canary-20251217063201",
+    "@lssm/tool.tsdown": "0.0.0-canary-20251217073102",
+    "@lssm/tool.typescript": "0.0.0-canary-20251217073102",
     "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },