@obsidiane/meridiane 2.0.10 → 2.0.11

package/src/generators/models/model-selection.js

@@ -0,0 +1,148 @@
+import {
+  canonicalizeMediaType,
+  collectUsedSchemasForMediaType,
+  expandWithSchemaDependencies,
+} from './oas-contract.js';
+import {
+  baseTsNameFromBasePath,
+  formatSuffixToken,
+  groupTsNameFromGroupPath,
+  parseOpenApiSchemaName,
+} from './oas-schema-name.js';
+import {sanitizeTypeName} from './utils.js';
+
+export const DEFAULT_MODEL_FORMAT = 'application/ld+json';
+
+function normalizeFormats(values) {
+  const formats = [];
+  for (const value of Array.isArray(values) ? values : []) {
+    const format = canonicalizeMediaType(value);
+    if (format && !formats.includes(format)) formats.push(format);
+  }
+  return formats.length > 0 ? formats : [DEFAULT_MODEL_FORMAT];
+}
+
+function indexFormatsBySchema(spec, formats) {
+  const formatsBySchema = new Map();
+
+  for (const format of formats) {
+    const schemaNames = collectUsedSchemasForMediaType(spec, {mediaType: format});
+    for (const schemaName of schemaNames) {
+      if (!schemaName) continue;
+      const schemaFormats = formatsBySchema.get(schemaName) ?? new Set();
+      schemaFormats.add(format);
+      formatsBySchema.set(schemaName, schemaFormats);
+    }
+  }
+
+  return formatsBySchema;
+}
+
+function matchesRule(value, rule) {
+  if (rule instanceof RegExp) return rule.test(value);
+  if (typeof rule === 'function') return !!rule(value);
+  return typeof rule === 'string' && rule.length > 0 && value.includes(rule);
+}
+
+function isSelected(schemaName, include, exclude) {
+  const parsed = parseOpenApiSchemaName(schemaName);
+  const canonicalName = parsed.groupPath ? `${parsed.basePath}-${parsed.groupPath}` : parsed.basePath;
+  const names = [schemaName, canonicalName];
+  const matchesAny = (rules) => rules.some((rule) =>
+    names.some((name) => matchesRule(name, rule))
+  );
+
+  return (include.length === 0 || matchesAny(include)) && !matchesAny(exclude);
+}
+
+function selectCandidates(schemas, formatsBySchema, include, exclude) {
+  const selected = [...formatsBySchema.keys()]
+    .filter((name) => name && !/^Hydra/i.test(name))
+    .sort((left, right) => left.localeCompare(right))
+    .filter((name) => isSelected(name, include, exclude));
+
+  const candidates = include.length > 0 || exclude.length > 0
+    ? expandWithSchemaDependencies(selected, schemas)
+    : new Set(selected);
+
+  return [...candidates]
+    .filter((name) => name && !/^Hydra/i.test(name))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function choosePreferredFormats(schemaNames, formats, formatsBySchema) {
+  const formatPriority = new Map(formats.map((format, index) => [format, index]));
+  const preferredFormats = new Map();
+
+  for (const schemaName of schemaNames) {
+    const schemaFormats = [...(formatsBySchema.get(schemaName) ?? [])];
+    const preferred = schemaFormats.sort(
+      (left, right) => (formatPriority.get(left) ?? 999) - (formatPriority.get(right) ?? 999)
+    )[0] ?? formats[0];
+    preferredFormats.set(schemaName, preferred);
+  }
+
+  return {preferredFormats, formatPriority};
+}
+
+function desiredTypeName(schemaName) {
+  const parsed = parseOpenApiSchemaName(schemaName);
+  if (parsed.isMergePatch) return undefined;
+
+  const base = baseTsNameFromBasePath(parsed.basePath);
+  const group = groupTsNameFromGroupPath(parsed.groupPath);
+  return `${base}${group}` || 'Model';
+}
+
+function assignTypeNames(schemaNames, preferredFormats, formatPriority) {
+  const schemasByDesiredName = new Map();
+
+  for (const schemaName of schemaNames) {
+    const desiredName = desiredTypeName(schemaName);
+    if (!desiredName) continue;
+
+    const entries = schemasByDesiredName.get(desiredName) ?? [];
+    entries.push({schemaName, preferredFormat: preferredFormats.get(schemaName)});
+    schemasByDesiredName.set(desiredName, entries);
+  }
+
+  const usedNames = new Set();
+  const typeNames = new Map();
+  const sortedGroups = [...schemasByDesiredName.entries()]
+    .sort(([left], [right]) => left.localeCompare(right));
+
+  for (const [desiredName, entries] of sortedGroups) {
+    entries.sort((left, right) => {
+      const byFormat =
+        (formatPriority.get(left.preferredFormat) ?? 999) -
+        (formatPriority.get(right.preferredFormat) ?? 999);
+      return byFormat || left.schemaName.localeCompare(right.schemaName);
+    });
+
+    entries.forEach((entry, index) => {
+      const candidateName = index === 0
+        ? desiredName
+        : `${desiredName}${formatSuffixToken(entry.preferredFormat)}`;
+      typeNames.set(entry.schemaName, sanitizeTypeName(candidateName, usedNames));
+    });
+  }
+
+  return typeNames;
+}
+
+export function selectModelSchemas(spec, options = {}) {
+  const schemas = spec?.components?.schemas ?? {};
+  const formats = normalizeFormats(options.formats);
+  const include = Array.isArray(options.includeSchemaNames) ? options.includeSchemaNames : [];
+  const exclude = Array.isArray(options.excludeSchemaNames) ? options.excludeSchemaNames : [];
+  const formatsBySchema = indexFormatsBySchema(spec, formats);
+  const schemaNames = selectCandidates(schemas, formatsBySchema, include, exclude);
+  const {preferredFormats, formatPriority} = choosePreferredFormats(
+    schemaNames,
+    formats,
+    formatsBySchema
+  );
+  const typeNames = assignTypeNames(schemaNames, preferredFormats, formatPriority);
+
+  return {schemas, formats, schemaNames, preferredFormats, typeNames};
+}

package/src/generators/models/oas-contract.js

@@ -0,0 +1,170 @@
+import {resolveLocalRef, schemaNameFromRef} from './schema-utils.js';
+
+function deref(spec, maybeRef) {
+  if (!maybeRef || typeof maybeRef !== 'object') return maybeRef;
+  if (typeof maybeRef.$ref === 'string') return resolveLocalRef(spec, maybeRef.$ref) || maybeRef;
+  return maybeRef;
+}
+
+export function canonicalizeMediaType(mediaType) {
+  return String(mediaType || '').split(';')[0].trim().toLowerCase();
+}
+
+function getContentSchema(content, wantedLower) {
+  if (!content || typeof content !== 'object') return undefined;
+  for (const [mediaType, definition] of Object.entries(content)) {
+    if (canonicalizeMediaType(mediaType) === wantedLower) return definition?.schema;
+  }
+  return undefined;
+}
+
+function is2xxStatus(code) {
+  const status = String(code || '');
+  if (/^[0-9]{3}$/.test(status)) return status.startsWith('2');
+  return /^2xx$/i.test(status);
+}
+
+const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+
+/**
+ * Collects only component schema refs (`#/components/schemas/*`) found in a JSON schema.
+ * @param {any} schema
+ * @param {Set<string>} out
+ */
+function collectComponentSchemaRefs(schema, out) {
+  const seen = new Set();
+
+  function walk(node) {
+    if (!node || typeof node !== 'object') return;
+    if (seen.has(node)) return;
+    seen.add(node);
+
+    if (node.$ref && typeof node.$ref === 'string') {
+      const name = schemaNameFromRef(node.$ref);
+      if (name) out.add(name);
+    }
+
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+      return;
+    }
+
+    for (const [key, value] of Object.entries(node)) {
+      if (key !== '$ref') walk(value);
+    }
+  }
+
+  walk(schema);
+}
+
+function listSchemaRoots(spec, {mediaType} = {}) {
+  const wantedLower = canonicalizeMediaType(mediaType);
+  const roots = [];
+  const visited = new Set();
+
+  function addParameter(parameterOrRef) {
+    const parameter = deref(spec, parameterOrRef);
+    if (!parameter || typeof parameter !== 'object') return;
+    if (parameter.schema) roots.push(parameter.schema);
+    const contentSchema = getContentSchema(parameter.content, wantedLower);
+    if (contentSchema) roots.push(contentSchema);
+  }
+
+  function addHeaders(headers) {
+    for (const header of Object.values(headers ?? {})) addParameter(header);
+  }
+
+  function visitOperation(method, operationOrRef) {
+    const operation = deref(spec, operationOrRef);
+    if (!operation || typeof operation !== 'object') return;
+    if (visited.has(operation)) return;
+    visited.add(operation);
+
+    for (const parameter of operation.parameters ?? []) addParameter(parameter);
+
+    if (method !== 'patch') {
+      const requestBody = deref(spec, operation.requestBody);
+      const requestSchema = getContentSchema(requestBody?.content, wantedLower);
+      if (requestSchema) roots.push(requestSchema);
+    }
+
+    for (const [code, responseOrRef] of Object.entries(operation.responses ?? {})) {
+      if (!is2xxStatus(code) && String(code).toLowerCase() !== 'default') continue;
+      const response = deref(spec, responseOrRef);
+      const responseSchema = getContentSchema(response?.content, wantedLower);
+      if (responseSchema) roots.push(responseSchema);
+      addHeaders(response?.headers);
+    }
+
+    for (const callbackOrRef of Object.values(operation.callbacks ?? {})) {
+      const callback = deref(spec, callbackOrRef);
+      for (const pathItem of Object.values(callback ?? {})) visitPathItem(pathItem);
+    }
+  }
+
+  function visitPathItem(pathItemOrRef) {
+    const pathItem = deref(spec, pathItemOrRef);
+    if (!pathItem || typeof pathItem !== 'object') return;
+    if (visited.has(pathItem)) return;
+    visited.add(pathItem);
+
+    for (const parameter of pathItem.parameters ?? []) addParameter(parameter);
+    for (const [method, operation] of Object.entries(pathItem)) {
+      const normalizedMethod = method.toLowerCase();
+      if (HTTP_METHODS.has(normalizedMethod)) visitOperation(normalizedMethod, operation);
+    }
+  }
+
+  function visitPaths(paths) {
+    for (const pathItem of Object.values(paths ?? {})) visitPathItem(pathItem);
+  }
+
+  visitPaths(spec?.paths);
+  visitPaths(spec?.webhooks);
+
+  return roots;
+}
+
+/**
+ * Returns the transitive closure of schema dependencies (following component-schema $ref).
+ * @param {Iterable<string>} start
+ * @param {Record<string, any>} schemas
+ */
+export function expandWithSchemaDependencies(start, schemas) {
+  const out = new Set();
+  const queue = [];
+
+  for (const schemaName of start) {
+    if (!schemaName || out.has(schemaName)) continue;
+    out.add(schemaName);
+    queue.push(schemaName);
+  }
+
+  while (queue.length) {
+    const name = queue.pop();
+    const schema = schemas[name];
+    if (!schema) continue;
+    const refs = new Set();
+    collectComponentSchemaRefs(schema, refs);
+    for (const dependency of refs) {
+      if (!dependency || out.has(dependency)) continue;
+      out.add(dependency);
+      queue.push(dependency);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Collects all component schemas used by endpoints for one media type.
+ * @param {any} spec
+ * @param {{ mediaType: string }} cfg
+ */
+export function collectUsedSchemasForMediaType(spec, cfg) {
+  const schemas = spec?.components?.schemas || {};
+  const roots = listSchemaRoots(spec, cfg);
+  const initialRefs = new Set();
+  for (const root of roots) collectComponentSchemaRefs(root, initialRefs);
+  return expandWithSchemaDependencies(initialRefs, schemas);
+}

package/{tools/generator → src/generators}/models/oas-schema-name.js

@@ -1,13 +1,5 @@
 import { canonicalizeMediaType } from './oas-contract.js';
-
-function pascalizeTokens(tokens) {
-  return tokens
-    .filter(Boolean)
-    .map((t) => String(t).replace(/^[^A-Za-z0-9]+|[^A-Za-z0-9]+$/g, ''))
-    .filter(Boolean)
-    .map((t) => t.charAt(0).toUpperCase() + t.slice(1))
-    .join('');
-}
+import {pascalCase} from './utils.js';
 
 export function parseOpenApiSchemaName(originalName) {
   const raw = String(originalName || '');
@@ -50,22 +42,21 @@ export function parseOpenApiSchemaName(originalName) {
 export function baseTsNameFromBasePath(basePath) {
   const parts = String(basePath || '').split('.').filter(Boolean);
   if (parts.length === 0) return 'Model';
-  const a = pascalizeTokens([parts[0]]);
+  const a = pascalCase([parts[0]]);
   if (parts.length === 1) return a;
-  const b = pascalizeTokens([parts[1]]);
+  const b = pascalCase([parts[1]]);
   if (parts.length === 2 && b.toLowerCase().startsWith(a.toLowerCase())) return b;
-  return parts.map((p) => pascalizeTokens([p])).join('');
+  return parts.map((part) => pascalCase([part])).join('');
 }
 
 export function groupTsNameFromGroupPath(groupPath) {
   const tokens = String(groupPath || '').split(/[._:]+/g).filter(Boolean);
-  return pascalizeTokens(tokens);
+  return pascalCase(tokens);
 }
 
 export function formatSuffixToken(mediaType) {
   const canon = canonicalizeMediaType(mediaType);
   const tokens = canon.split(/[\/+.-]+/g).filter(Boolean);
   const trimmed = tokens[0] === 'application' ? tokens.slice(1) : tokens;
-  return pascalizeTokens(trimmed.length ? trimmed : tokens) || 'Fmt';
+  return pascalCase(trimmed.length ? trimmed : tokens) || 'Fmt';
 }
-

package/src/generators/models/openapi-to-models.js

@@ -0,0 +1,136 @@
+import {canonicalizeMediaType} from './oas-contract.js';
+import {collectInterfaceTypeNames, resolveInterfaceSchema} from './interface-schema.js';
+import {DEFAULT_MODEL_FORMAT, selectModelSchemas} from './model-selection.js';
+import {isObject} from './schema-utils.js';
+import {createTypeResolver} from './type-resolver.js';
+import {quoteKeyIfNeeded} from './utils.js';
+
+/**
+ * @typedef {{
+ *   requiredMode?: 'all'|'spec',
+ *   formats?: string[],
+ *   includeSchemaNames?: Array<RegExp|string|((name: string) => boolean)>,
+ *   excludeSchemaNames?: Array<RegExp|string|((name: string) => boolean)>,
+ * }} BuildOptions
+ */
+
+/** @typedef {{name: string, tsKey: string, type: string, optional: boolean}} ModelProp */
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   props: ModelProp[],
+ *   imports: string[],
+ *   extendsTypes: string[],
+ *   extendsItem?: boolean,
+ *   isAlias?: boolean,
+ *   type?: string,
+ * }} ModelDefinition
+ */
+
+function normalizeRequiredMode(value) {
+  return String(value ?? '').trim().toLowerCase() === 'spec' ? 'spec' : 'all';
+}
+
+function createModelBuilder({spec, schemas, typeNames, interfaceTypeNames, requiredMode}) {
+  const knownTypeNames = new Set(typeNames.values());
+
+  function importsFor(dependencies, currentTypeName) {
+    return [...dependencies]
+      .filter((dependency) => dependency !== currentTypeName && knownTypeNames.has(dependency))
+      .sort((left, right) => left.localeCompare(right));
+  }
+
+  function resolverFor(dependencies) {
+    return createTypeResolver({dependencies, typeNames, requiredMode, spec});
+  }
+
+  function buildAlias(raw, typeName) {
+    const dependencies = new Set();
+    const type = resolverFor(dependencies).typeOf(raw);
+    return {
+      name: typeName,
+      type,
+      imports: importsFor(dependencies, typeName),
+      isAlias: true,
+      props: [],
+      extendsTypes: [],
+    };
+  }
+
+  function buildInterface(schema, typeName, extendsTypes, preferredFormat) {
+    const isJsonLd = canonicalizeMediaType(preferredFormat) === DEFAULT_MODEL_FORMAT;
+    const requiredProperties = new Set(schema.required ?? []);
+    const dependencies = new Set(extendsTypes);
+    const resolver = resolverFor(dependencies);
+
+    const props = Object.entries(schema.properties ?? {})
+      .filter(([propertyName]) => !isJsonLd || !['@id', '@type', '@context'].includes(propertyName))
+      .map(([propertyName, propertySchema]) => ({
+        name: propertyName,
+        tsKey: quoteKeyIfNeeded(propertyName),
+        type: requiredMode === 'spec'
+          ? resolver.typeOf(propertySchema)
+          : resolver.nullableTypeOf(propertySchema),
+        optional: requiredMode === 'spec' ? !requiredProperties.has(propertyName) : true,
+      }));
+
+    return {
+      name: typeName,
+      props,
+      imports: importsFor(dependencies, typeName),
+      extendsTypes,
+      extendsItem: isJsonLd,
+    };
+  }
+
+  return function buildModel(schemaName, preferredFormat) {
+    const raw = schemas[schemaName];
+    const typeName = typeNames.get(schemaName);
+    if (!typeName || raw === undefined) return undefined;
+
+    const {schema, extendsTypes, compatible} = resolveInterfaceSchema(
+      raw,
+      typeName,
+      typeNames,
+      interfaceTypeNames
+    );
+    const isObjectLike = schema?.type === 'object' || isObject(schema?.properties) || extendsTypes.length > 0;
+    if (!compatible || !isObjectLike || !interfaceTypeNames.has(typeName)) {
+      return buildAlias(raw, typeName);
+    }
+
+    return buildInterface(schema, typeName, extendsTypes, preferredFormat);
+  };
+}
+
+/**
+ * Builds TypeScript model definitions from OpenAPI `components.schemas`.
+ * @param {any} spec
+ * @param {BuildOptions} [options]
+ * @returns {{models: ModelDefinition[]}}
+ */
+export function buildModelsFromOpenAPI(spec, options = {}) {
+  const requiredMode = normalizeRequiredMode(options.requiredMode);
+  const {schemas, formats, schemaNames, preferredFormats, typeNames} = selectModelSchemas(
+    spec,
+    options
+  );
+  const interfaceTypeNames = collectInterfaceTypeNames(schemas, schemaNames, typeNames);
+  const buildModel = createModelBuilder({
+    spec,
+    schemas,
+    typeNames,
+    interfaceTypeNames,
+    requiredMode,
+  });
+
+  const models = [];
+  for (const schemaName of schemaNames) {
+    const preferredFormat = preferredFormats.get(schemaName) ?? formats[0];
+    const model = buildModel(schemaName, preferredFormat);
+    if (model) models.push(model);
+  }
+
+  return {models};
+}

package/{tools/generator → src/generators}/models/schema-utils.js

@@ -10,14 +10,35 @@ export function isObject(v) {
   return !!v && typeof v === 'object' && !Array.isArray(v);
 }
 
+export function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function decodeJsonPointerSegment(segment) {
+  return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+export function resolveLocalRef(document, ref) {
+  const pointer = String(ref ?? '');
+  if (pointer === '#') return document;
+  if (!pointer.startsWith('#/')) return undefined;
+
+  let current = document;
+  for (const segment of pointer.slice(2).split('/').map(decodeJsonPointerSegment)) {
+    if (!current || typeof current !== 'object') return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
 /**
  * Extrait le nom du schéma depuis une référence $ref
  * @param {string} $ref
  * @returns {string|undefined}
  */
 export function schemaNameFromRef($ref) {
-  const m = $ref.match(/#\/components\/schemas\/(.+)$/);
-  return m ? m[1] : undefined;
+  const match = String($ref ?? '').match(/^#\/components\/schemas\/([^/]+)$/);
+  return match ? decodeJsonPointerSegment(match[1]) : undefined;
 }
 
 /**
@@ -38,7 +59,10 @@ export function mergeAllOf(schemas) {
       return null;
     }
     if (s.type === 'object') {
-      Object.assign(out.properties, s.properties || {});
+      for (const [name, property] of Object.entries(s.properties ?? {})) {
+        if (hasOwn(out.properties, name)) return null;
+        out.properties[name] = property;
+      }
       if (Array.isArray(s.required)) out.required.push(...s.required);
     } else {
       return null;

package/src/generators/models/templates/type-alias.hbs

@@ -0,0 +1,2 @@
+{{#each imports}}import type { {{this}} } from './{{this}}';
+{{/each}}{{{separator}}}export type {{name}} = {{type}};

package/src/generators/models/type-expression.js

@@ -0,0 +1,65 @@
+const PRECEDENCE = {
+  union: 1,
+  intersection: 2,
+  primary: 3,
+};
+
+function expression(code, precedence, kind, members, acceptsNull) {
+  return {code, precedence, kind, members, acceptsNull};
+}
+
+export function atomicType(code, acceptsNull = false) {
+  return expression(code, PRECEDENCE.primary, 'atomic', [], acceptsNull);
+}
+
+export function formatType(type, parentPrecedence = PRECEDENCE.primary) {
+  return type.precedence < parentPrecedence ? `(${type.code})` : type.code;
+}
+
+function uniqueTypes(types) {
+  return [...new Map(types.map((type) => [type.code, type])).values()];
+}
+
+function flatten(types, kind) {
+  return types.flatMap((type) => type.kind === kind ? type.members : [type]);
+}
+
+export function unionType(types) {
+  const members = uniqueTypes(flatten(types, 'union')).filter((member) => member.code !== 'never');
+  if (members.length === 0) return atomicType('any');
+  if (members.some((member) => member.code === 'any')) return atomicType('any');
+  if (members.length === 1) return members[0];
+
+  const ordered = members.filter((member) => member.code !== 'null');
+  ordered.push(...members.filter((member) => member.code === 'null'));
+  return expression(
+    ordered.map((member) => formatType(member, PRECEDENCE.union)).join(' | '),
+    PRECEDENCE.union,
+    'union',
+    ordered,
+    members.some((member) => member.acceptsNull)
+  );
+}
+
+export function intersectionType(types) {
+  const members = uniqueTypes(flatten(types, 'intersection')).filter((member) => member.code !== 'any');
+  if (members.length === 0) return atomicType('any');
+  if (members.some((member) => member.code === 'never')) return atomicType('never');
+  if (members.length === 1) return members[0];
+
+  return expression(
+    members.map((member) => formatType(member, PRECEDENCE.intersection)).join(' & '),
+    PRECEDENCE.intersection,
+    'intersection',
+    members,
+    members.every((member) => member.acceptsNull)
+  );
+}
+
+export function arrayType(item) {
+  return atomicType(`${formatType(item)}[]`);
+}
+
+export function nullableType(type) {
+  return type.acceptsNull ? type : unionType([type, atomicType('null', true)]);
+}