@obsidiane/meridiane 0.0.13 → 1.0.1

package/README.md

@@ -31,7 +31,11 @@ Options :
 - `--debug` : active des logs supplémentaires (CLI).
 
 Bonnes pratiques :
-- utiliser `--preset=native` si vous voulez des modèles “entity-like” (sans variantes `.jsonld/.jsonMergePatch`)
+- utiliser `--preset=native` pour un mode “contract-driven” (LD+JSON) :
+  - modèles générés uniquement s’ils sont utilisés par les endpoints
+  - groups conservés
+  - pas de modèles `*.jsonMergePatch` (PATCH = `Partial<...>`)
+  - noms normalisés (pas de suffixe `.jsonld`)
 - utiliser `--no-models` si vous voulez uniquement le runtime (pas besoin de `--spec`)
 - laisser le registry à la CI (`.npmrc`, variables d’environnement, `npm publish --registry …`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "0.0.13",
+  "version": "1.0.1",
   "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
   "repository": {
     "type": "git",

package/tools/generator/models/openapi-to-models.js

@@ -50,6 +50,146 @@ function buildNameMap(schemaNames, schemas, preset) {
   return nameMap;
 }
 
+function getContentSchema(content, wantedLower) {
+  if (!content || typeof content !== 'object') return undefined;
+  for (const [k, v] of Object.entries(content)) {
+    if (String(k).toLowerCase() === wantedLower) return v?.schema;
+  }
+  return undefined;
+}
+
+function is2xxStatus(code) {
+  const s = String(code || '');
+  return /^[0-9]{3}$/.test(s) && s.startsWith('2');
+}
+
+function collectRefsFromSchema(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') {
+      out.add(schemaNameFromRef(node.$ref));
+      return;
+    }
+
+    if (Array.isArray(node)) {
+      for (const it of node) walk(it);
+      return;
+    }
+
+    // Common JSON schema constructs (plus a generic fallback)
+    if (node.allOf) walk(node.allOf);
+    if (node.oneOf) walk(node.oneOf);
+    if (node.anyOf) walk(node.anyOf);
+    if (node.items) walk(node.items);
+    if (node.properties) walk(node.properties);
+    if (node.additionalProperties) walk(node.additionalProperties);
+
+    for (const v of Object.values(node)) walk(v);
+  }
+
+  walk(schema);
+}
+
+function listNativeRootsFromPaths(spec, { mediaType = 'application/ld+json' } = {}) {
+  const wantedLower = String(mediaType).toLowerCase();
+  const roots = [];
+
+  const paths = spec?.paths;
+  if (!paths || typeof paths !== 'object') return roots;
+
+  for (const pathItem of Object.values(paths)) {
+    if (!pathItem || typeof pathItem !== 'object') continue;
+    for (const op of Object.values(pathItem)) {
+      if (!op || typeof op !== 'object') continue;
+
+      // requestBody (LD+JSON only)
+      const rbSchema = getContentSchema(op.requestBody?.content, wantedLower);
+      if (rbSchema) roots.push(rbSchema);
+
+      // responses 2xx (LD+JSON only)
+      const responses = op.responses;
+      if (!responses || typeof responses !== 'object') continue;
+      for (const [code, resp] of Object.entries(responses)) {
+        if (!is2xxStatus(code)) continue;
+        const schema = getContentSchema(resp?.content, wantedLower);
+        if (schema) roots.push(schema);
+      }
+    }
+  }
+
+  return roots;
+}
+
+function parseOpenApiSchemaName(originalName) {
+  const raw = String(originalName || '');
+  const i = raw.indexOf('-');
+  let baseRaw = i >= 0 ? raw.slice(0, i) : raw;
+  let groupRaw = i >= 0 ? raw.slice(i + 1) : '';
+
+  let baseVariant = 'none';
+  if (/\.jsonld$/i.test(baseRaw)) {
+    baseVariant = 'jsonld';
+    baseRaw = baseRaw.replace(/\.jsonld$/i, '');
+  } else if (/\.multipart$/i.test(baseRaw)) {
+    baseVariant = 'multipart';
+    baseRaw = baseRaw.replace(/\.multipart$/i, '');
+  }
+
+  let isMergePatch = false;
+  if (/\.jsonmergepatch$/i.test(baseRaw)) {
+    isMergePatch = true;
+    baseRaw = baseRaw.replace(/\.jsonmergepatch$/i, '');
+  }
+  if (/\.jsonmergepatch$/i.test(groupRaw)) {
+    isMergePatch = true;
+    groupRaw = groupRaw.replace(/\.jsonmergepatch$/i, '');
+  }
+
+  return {
+    originalName: raw,
+    basePath: baseRaw,
+    groupPath: groupRaw,
+    baseVariant,
+    isMergePatch,
+    key: `${baseRaw.toLowerCase()}|${groupRaw.toLowerCase()}`,
+  };
+}
+
+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('');
+}
+
+function baseTsNameFromBasePath(basePath) {
+  const parts = String(basePath || '').split('.').filter(Boolean);
+  if (parts.length === 0) return 'Model';
+  const a = pascalizeTokens([parts[0]]);
+  if (parts.length === 1) return a;
+  const b = pascalizeTokens([parts[1]]);
+  if (parts.length === 2 && b.toLowerCase().startsWith(a.toLowerCase())) return b;
+  return parts.map((p) => pascalizeTokens([p])).join('');
+}
+
+function groupTsNameFromGroupPath(groupPath) {
+  const tokens = String(groupPath || '').split(/[._:]+/g).filter(Boolean);
+  return pascalizeTokens(tokens);
+}
+
+function stableUnion(types) {
+  const uniq = [...new Set(types.filter(Boolean))];
+  uniq.sort((a, b) => a.localeCompare(b));
+  return uniq.join(' | ') || 'any';
+}
+
 /**
  * Construit les définitions de modèles à partir d’une spec OpenAPI (components.schemas)
  * @param {any} spec
@@ -59,77 +199,249 @@ function buildNameMap(schemaNames, schemas, preset) {
 export function buildModelsFromOpenAPI(spec, options) {
   const opts = { requiredMode: 'all-optional', ...(options || {}) };
   const schemas = spec?.components?.schemas || {};
-  const schemaNames = applySchemaNameFilters(filterSchemaNames(schemas, opts), opts);
   const preset = opts.preset ?? 'all';
-  const nameMap = buildNameMap(schemaNames, schemas, preset);
-  const allSanitizedNames = new Set([...nameMap.values()]);
 
   /** @type {ModelDefinition[]} */
   const models = [];
 
-  for (const originalName of schemaNames) {
-    const raw = schemas[originalName];
-    const sanitized = nameMap.get(originalName);
-    if (!sanitized) continue;
+  if (preset !== 'native') {
+    const schemaNames = applySchemaNameFilters(filterSchemaNames(schemas, opts), opts);
+    const nameMap = buildNameMap(schemaNames, schemas, preset);
+    const allSanitizedNames = new Set([...nameMap.values()]);
+
+    for (const originalName of schemaNames) {
+      const raw = schemas[originalName];
+      const sanitized = nameMap.get(originalName);
+      if (!sanitized) continue;
+
+      /** @type {string[]} */
+      const extendsTypes = [];
 
-    /** @type {string[]} */
-    const extendsTypes = [];
-
-    let effective = raw;
-    if (raw?.allOf) {
-      const merged = mergeAllOf(raw.allOf);
-      if (merged) {
-        effective = merged;
-      } else {
-        // Non-flattenable allOf (refs, mixed forms): keep inline object props and model refs as extends.
-        const props = {};
-        const required = new Set();
-        const ext = new Set();
-
-        for (const part of raw.allOf) {
-          if (part?.$ref) {
-            const orig = schemaNameFromRef(part.$ref);
-            const refName = orig ? nameMap.get(orig) : undefined;
-            if (refName && refName !== sanitized && allSanitizedNames.has(refName)) ext.add(refName);
-            continue;
+      let effective = raw;
+      if (raw?.allOf) {
+        const merged = mergeAllOf(raw.allOf);
+        if (merged) {
+          effective = merged;
+        } else {
+          // Non-flattenable allOf (refs, mixed forms): keep inline object props and model refs as extends.
+          const props = {};
+          const required = new Set();
+          const ext = new Set();
+
+          for (const part of raw.allOf) {
+            if (part?.$ref) {
+              const orig = schemaNameFromRef(part.$ref);
+              const refName = orig ? nameMap.get(orig) : undefined;
+              if (refName && refName !== sanitized && allSanitizedNames.has(refName)) ext.add(refName);
+              continue;
+            }
+            const isObj = part?.type === 'object' || isObject(part?.properties);
+            if (!isObj) continue;
+            Object.assign(props, part.properties || {});
+            for (const r of part.required || []) required.add(r);
           }
-          const isObj = part?.type === 'object' || isObject(part?.properties);
-          if (!isObj) continue;
-          Object.assign(props, part.properties || {});
-          for (const r of part.required || []) required.add(r);
-        }
 
-        extendsTypes.push(...[...ext].sort((a, b) => a.localeCompare(b)));
-        effective = { type: 'object', properties: props, required: [...required] };
+          extendsTypes.push(...[...ext].sort((a, b) => a.localeCompare(b)));
+          effective = { type: 'object', properties: props, required: [...required] };
+        }
       }
+
+      const isObjectLike = effective?.type === 'object' || isObject(effective?.properties) || extendsTypes.length > 0;
+      if (!isObjectLike) continue;
+
+      const required = new Set(effective.required || []);
+      const deps = new Set();
+
+      for (const e of extendsTypes) deps.add(e);
+
+      const props = Object.entries(effective.properties || {}).map(([propName, prop]) => {
+        const baseType = tsTypeOf(prop, deps, nameMap, { requiredMode: opts.requiredMode ?? 'all-optional', forceNullable: false });
+        const type = withNullable(baseType, prop);
+        return {
+          name: propName,
+          tsKey: quoteKeyIfNeeded(propName),
+          type,
+          optional: opts.requiredMode === 'spec' ? !required.has(propName) : true,
+        };
+      });
+
+      const imports = [...deps]
+        .filter((n) => n !== sanitized)
+        .filter((n) => allSanitizedNames.has(n))
+        .sort((a, b) => a.localeCompare(b));
+
+      models.push({name: sanitized, props, imports, extendsTypes});
+    }
+
+    return { models };
+  }
+
+  // preset=native (v2): contract-driven (paths), LD+JSON, groups preserved, jsonld/non-jsonld merged.
+  const roots = listNativeRootsFromPaths(spec, { mediaType: 'application/ld+json' });
+  const initialRefs = new Set();
+  for (const r of roots) collectRefsFromSchema(r, initialRefs);
+
+  const usedSchemaNames = new Set();
+  const queue = [...initialRefs];
+  while (queue.length) {
+    const name = queue.pop();
+    if (!name || usedSchemaNames.has(name)) continue;
+    usedSchemaNames.add(name);
+    const schema = schemas[name];
+    if (!schema) continue;
+    const refs = new Set();
+    collectRefsFromSchema(schema, refs);
+    for (const ref of refs) if (ref && !usedSchemaNames.has(ref)) queue.push(ref);
+  }
+
+  // Group and merge by (basePath, groupPath), ignoring variants.
+  const buckets = new Map();
+  for (const originalName of [...usedSchemaNames].sort((a, b) => a.localeCompare(b))) {
+    if (!originalName) continue;
+    if (/^Hydra/i.test(originalName)) continue; // technical
+
+    const parsed = parseOpenApiSchemaName(originalName);
+    if (!parsed.basePath) continue;
+
+    // User include/exclude filters (apply to canonical name and to raw variants)
+    const canonical = parsed.groupPath ? `${parsed.basePath}-${parsed.groupPath}` : parsed.basePath;
+    const fulls = [originalName, canonical];
+    const include = Array.isArray(opts.includeSchemaNames) ? opts.includeSchemaNames : [];
+    const exclude = Array.isArray(opts.excludeSchemaNames) ? opts.excludeSchemaNames : [];
+
+    const matches = (val, rule) => {
+      if (rule instanceof RegExp) return rule.test(val);
+      if (typeof rule === 'function') return !!rule(val);
+      if (typeof rule === 'string' && rule.length) return val.includes(rule);
+      return false;
+    };
+
+    const hasInclude = include.length > 0;
+    const included = !hasInclude || include.some((r) => fulls.some((v) => matches(v, r)));
+    const excluded = exclude.some((r) => fulls.some((v) => matches(v, r)));
+    if (!included || excluded) continue;
+
+    const bucket = buckets.get(parsed.key) || { basePath: parsed.basePath, groupPath: parsed.groupPath, entries: [] };
+    bucket.entries.push(parsed);
+    buckets.set(parsed.key, bucket);
+  }
+
+  // Stable bucket ordering
+  const bucketList = [...buckets.values()].sort((a, b) => {
+    const ka = `${a.basePath}-${a.groupPath}`.toLowerCase();
+    const kb = `${b.basePath}-${b.groupPath}`.toLowerCase();
+    return ka.localeCompare(kb);
+  });
+
+  // Compute TS names (unique) and build originalName -> tsName map (all variants in a bucket).
+  const usedTsNames = new Set();
+  const nameMap = new Map();
+  for (const b of bucketList) {
+    const baseTs = baseTsNameFromBasePath(b.basePath);
+    const groupTs = groupTsNameFromGroupPath(b.groupPath);
+    const desired = `${baseTs}${groupTs}` || 'Model';
+    const tsName = sanitizeTypeName(desired, usedTsNames);
+    b.tsName = tsName;
+    for (const e of b.entries) {
+      nameMap.set(e.originalName, tsName);
     }
+  }
+  const allSanitizedNames = new Set(bucketList.map((b) => b.tsName));
 
-    const isObjectLike = effective?.type === 'object' || isObject(effective?.properties) || extendsTypes.length > 0;
-    if (!isObjectLike) continue;
+  // Generate merged models per bucket.
+  for (const b of bucketList) {
+    const sanitized = b.tsName;
+    if (!sanitized) continue;
 
-    const required = new Set(effective.required || []);
     const deps = new Set();
+    const extendsSet = new Set();
+    const propTypes = new Map(); // propName -> Set<tsType>
 
-    for (const e of extendsTypes) deps.add(e);
+    // Choose candidates: jsonld + base (no multipart, no merge-patch)
+    const candidates = b.entries
+      .filter((e) => !e.isMergePatch)
+      .filter((e) => e.baseVariant !== 'multipart')
+      .sort((a, b2) => {
+        const score = (e) => (e.baseVariant === 'jsonld' ? 2 : 1);
+        const sa = score(a), sb = score(b2);
+        if (sb !== sa) return sb - sa;
+        return a.originalName.localeCompare(b2.originalName);
+      });
+
+    for (const e of candidates) {
+      const raw = schemas[e.originalName];
+      if (!raw) continue;
+
+      let effective = raw;
+      /** @type {string[]} */
+      const extendsTypes = [];
+
+      if (raw?.allOf) {
+        const merged = mergeAllOf(raw.allOf);
+        if (merged) {
+          effective = merged;
+        } else {
+          const props = {};
+          const ext = new Set();
+          for (const part of raw.allOf) {
+            if (part?.$ref) {
+              const orig = schemaNameFromRef(part.$ref);
+              const refName = orig ? nameMap.get(orig) || orig : undefined;
+              if (refName && refName !== sanitized && allSanitizedNames.has(refName)) ext.add(refName);
+              continue;
+            }
+            const isObj = part?.type === 'object' || isObject(part?.properties);
+            if (!isObj) continue;
+            Object.assign(props, part.properties || {});
+          }
+          extendsTypes.push(...[...ext].sort((a, b3) => a.localeCompare(b3)));
+          effective = { type: 'object', properties: props };
+        }
+      }
+
+      const isObjectLike = effective?.type === 'object' || isObject(effective?.properties) || extendsTypes.length > 0;
+      if (!isObjectLike) continue;
+
+      for (const ex of extendsTypes) extendsSet.add(ex);
 
-    const props = Object.entries(effective.properties || {}).map(([propName, prop]) => {
-      const baseType = tsTypeOf(prop, deps, nameMap);
-      const type = withNullable(baseType, prop);
-      return {
-        name: propName,
-        tsKey: quoteKeyIfNeeded(propName),
-        type,
-        optional: opts.requiredMode === 'spec' ? !required.has(propName) : true,
-      };
-    });
+      for (const [propName, prop] of Object.entries(effective.properties || {})) {
+        const baseType = tsTypeOf(prop, deps, nameMap, { requiredMode: 'all-optional', forceNullable: true });
+        const existing = propTypes.get(propName) || new Set();
+        existing.add(baseType);
+        propTypes.set(propName, existing);
+      }
+    }
 
+    const extendsTypes = [...extendsSet]
+      .filter((n) => n !== sanitized)
+      .filter((n) => allSanitizedNames.has(n))
+      .sort((a, b2) => a.localeCompare(b2));
+
+    // Imports are any referenced model types (+ extends), excluding self.
+    for (const e of extendsTypes) deps.add(e);
     const imports = [...deps]
       .filter((n) => n !== sanitized)
       .filter((n) => allSanitizedNames.has(n))
-      .sort((a, b) => a.localeCompare(b));
+      .sort((a, b2) => a.localeCompare(b2));
+
+    const props = [...propTypes.keys()]
+      .sort((a, b2) => a.localeCompare(b2))
+      .map((propName) => {
+        const union = stableUnion([...propTypes.get(propName)]);
+        const type = /\|\s*null\b/.test(union) ? union : `${union} | null`;
+        return {
+          name: propName,
+          tsKey: quoteKeyIfNeeded(propName),
+          type,
+          optional: true,
+        };
+      });
+
+    // Skip empty models (no props + no extends): avoid polluting exports.
+    if (props.length === 0 && extendsTypes.length === 0) continue;
 
-    models.push({name: sanitized, props, imports, extendsTypes});
+    models.push({ name: sanitized, props, imports, extendsTypes });
   }
 
-  return {models};
+  return { models };
 }

package/tools/generator/models/schema-utils.js

@@ -112,6 +112,9 @@ export function applySchemaNameFilters(schemaNames, cfg) {
   if (preset === 'native') {
     out = out
       .filter((n) => !/^Hydra/i.test(n))
+      // API Platform adds a technical "Multipart" schema for multipart/form-data request bodies (file uploads).
+      // It's not a resource model and tends to pollute the generated "native" model list.
+      .filter((n) => !/^Multipart(?:$|[.-])/i.test(n))
       .filter((n) => !/jsonMergePatch/i.test(n))
       .filter((n) => !/\.jsonld\b/i.test(n))
       .filter((n) => !/\.jsonapi\b/i.test(n));

package/tools/generator/models/type-resolver.js

@@ -16,10 +16,13 @@ export function withNullable(ts, schema) {
  * @param {any} schema
  * @param {Set<string>} deps
  * @param {Map<string,string>} nameMap
+ * @param {{ requiredMode?: 'all-optional'|'spec', forceNullable?: boolean }} [cfg]
  * @returns {string}
  */
-export function tsTypeOf(schema, deps, nameMap) {
+export function tsTypeOf(schema, deps, nameMap, cfg) {
   if (!schema) return 'any';
+  const requiredMode = cfg?.requiredMode ?? 'all-optional';
+  const forceNullable = !!cfg?.forceNullable;
 
   if (schema.$ref) {
     const orig = schemaNameFromRef(schema.$ref);
@@ -49,9 +52,14 @@ export function tsTypeOf(schema, deps, nameMap) {
       else if (t === 'string') parts.add('string');
       else if (t === 'integer' || t === 'number') parts.add('number');
       else if (t === 'boolean') parts.add('boolean');
-      else if (t === 'array') parts.add(tsTypeOf({ type: 'array', items: schema.items }, deps, nameMap));
+      else if (t === 'array') parts.add(tsTypeOf({ type: 'array', items: schema.items }, deps, nameMap, cfg));
       else if (t === 'object') {
-        const objTs = tsTypeOf({ type: 'object', properties: schema.properties, required: schema.required, additionalProperties: schema.additionalProperties }, deps, nameMap);
+        const objTs = tsTypeOf(
+          { type: 'object', properties: schema.properties, required: schema.required, additionalProperties: schema.additionalProperties },
+          deps,
+          nameMap,
+          cfg
+        );
         parts.add(objTs);
       } else parts.add('any');
     }
@@ -60,13 +68,13 @@ export function tsTypeOf(schema, deps, nameMap) {
 
   if (schema.allOf) {
     // Aplatir au niveau buildModelsFromOpenAPI; ici on combine si nécessaire
-    return schema.allOf.map((s) => tsTypeOf(s, deps, nameMap)).join(' & ');
+    return schema.allOf.map((s) => tsTypeOf(s, deps, nameMap, cfg)).join(' & ');
   }
-  if (schema.oneOf) return schema.oneOf.map((s) => tsTypeOf(s, deps, nameMap)).join(' | ');
-  if (schema.anyOf) return schema.anyOf.map((s) => tsTypeOf(s, deps, nameMap)).join(' | ');
+  if (schema.oneOf) return schema.oneOf.map((s) => tsTypeOf(s, deps, nameMap, cfg)).join(' | ');
+  if (schema.anyOf) return schema.anyOf.map((s) => tsTypeOf(s, deps, nameMap, cfg)).join(' | ');
 
   if (schema.type === 'array') {
-    const it = tsTypeOf(schema.items || {}, deps, nameMap);
+    const it = tsTypeOf(schema.items || {}, deps, nameMap, cfg);
     return `${it}[]`;
   }
 
@@ -74,14 +82,15 @@ export function tsTypeOf(schema, deps, nameMap) {
     const props = schema.properties || {};
     const entries = Object.entries(props);
     const inline = entries.map(([k, v]) => {
-      const t = tsTypeOf(v, deps, nameMap);
-      const opt = (schema.required || []).includes(k) ? '' : '?';
-      const nullable = v?.nullable && !/\|\s*null\b/.test(t) ? ' | null' : '';
+      const t0 = tsTypeOf(v, deps, nameMap, cfg);
+      const opt = requiredMode === 'spec' ? ((schema.required || []).includes(k) ? '' : '?') : '?';
+      const wantsNull = forceNullable || v?.nullable;
+      const nullable = wantsNull && !/\|\s*null\b/.test(t0) ? ' | null' : '';
       const key = quoteKeyIfNeeded(k);
-      return `${key}${opt}: ${t}${nullable};`;
+      return `${key}${opt}: ${t0}${nullable};`;
     });
     if (schema.additionalProperties) {
-      const at = tsTypeOf(schema.additionalProperties, deps, nameMap);
+      const at = tsTypeOf(schema.additionalProperties, deps, nameMap, cfg);
       inline.push(`[key: string]: ${at};`);
     }
     return `{ ${inline.join(' ')} }`;
@@ -93,4 +102,3 @@ export function tsTypeOf(schema, deps, nameMap) {
 
   return 'any';
 }
-