@obsidiane/meridiane 1.0.0 → 2.0.0

package/README.md

@@ -21,17 +21,24 @@ npm i -g @obsidiane/meridiane
 ```bash
 # Dev: génère le bridge (+ models par défaut)
 # (build standalone + install local dans node_modules)
-npx meridiane dev <packageName> --spec <url|file> [--preset[=native|all]] [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
+npx meridiane dev <packageName> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
 
 # CI/CD: génère + build Angular + npm pack (artefact prêt à publier)
-npx meridiane build <packageName> --version <semver> --spec <url|file> [--preset[=native|all]] [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
+npx meridiane build <packageName> --version <semver> --spec <url|file> [--formats <mimeTypes>]... [--include <substr>]... [--exclude <substr>]... [--no-models] [--debug]
 ```
 
 Options :
 - `--debug` : active des logs supplémentaires (CLI).
+- `--formats` : peut être répété ou fourni en liste séparée par virgules :
+  - `--formats application/ld+json`
+  - `--formats application/ld+json,application/json`
 
 Bonnes pratiques :
-- utiliser `--preset=native` si vous voulez des modèles “entity-like” (sans variantes `.jsonld/.jsonMergePatch`)
+- utiliser `--formats application/ld+json` (ou plusieurs formats) pour un mode “contract-driven” :
+  - modèles générés uniquement s’ils sont utilisés par les endpoints (pour ces formats)
+  - 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 …`)
 
@@ -41,7 +48,7 @@ Note (repo Meridiane) :
 ## Exemple CI (générer + build + publish)
 
 ```bash
-npx -y @obsidiane/meridiane@0.1.0 build @acme/backend-bridge --version 0.1.0 --spec https://staging.example/api/docs.json --preset=native
+npx -y @obsidiane/meridiane@0.1.0 build @acme/backend-bridge --version 0.1.0 --spec https://staging.example/api/docs.json --formats application/ld+json
 npm publish dist/backend-bridge
 ```
 

package/cli.js

@@ -8,16 +8,7 @@ import { createLogger } from './tools/core/logger.js';
 
 const program = new Command();
 
-program
-  .name('meridiane')
-  .description('Generate an Angular bridge + models from an API Platform OpenAPI spec.')
-  .showHelpAfterError()
-  .showSuggestionAfterError();
-
-function presetParser(value, previous) {
-  if (value === undefined && previous === undefined) return true; // `--preset` (no value) => native
-  return value ?? previous;
-}
+program.name('meridiane').description('Generate an Angular bridge + models from an API Platform OpenAPI spec.').showHelpAfterError().showSuggestionAfterError();
 
 function collect(value, previous = []) {
   return [...previous, value];
@@ -26,7 +17,12 @@ function collect(value, previous = []) {
 function commonOptions(cmd) {
   return cmd
     .option('--spec <urlOrFile>', 'OpenAPI spec source (URL or local JSON file)')
-    .option('--preset [mode]', 'Preset: native|all (default: all; `--preset` alone => native)', presetParser)
+    .option(
+      '--formats <mimeTypes>',
+      'Generate only selected media types (repeatable, supports commas). Enables contract-driven mode from paths.',
+      collect,
+      []
+    )
     .option('--include <substr>', 'Include schema names containing substring (repeatable, supports commas)', collect, [])
     .option('--exclude <substr>', 'Exclude schema names containing substring (repeatable, supports commas)', collect, [])
     .option('--no-models', 'Skip models generation (then --spec is not required)')

package/package.json

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

package/tools/build.js

@@ -4,7 +4,7 @@ import { spawn } from 'node:child_process';
 import path from 'node:path';
 
 import { deriveLibName } from './core/lib-name.js';
-import { normalizePreset, splitListArgs } from './core/paths.js';
+import { splitListArgs } from './core/paths.js';
 import { readOpenApiSpec } from './core/spec.js';
 import { createLogger } from './core/logger.js';
 import { generateBridgeWorkspace } from './core/generate.js';
@@ -30,20 +30,21 @@ export async function runBuild(packageName, opts) {
   if (!version) throw new Error('Missing --version');
 
   const noModels = opts.models === false;
-  const preset = normalizePreset(opts.preset);
+  const formats = splitListArgs(opts.formats);
   const include = splitListArgs(opts.include);
   const exclude = splitListArgs(opts.exclude);
 
   const libName = deriveLibName(packageName);
   const requiredMode = 'spec';
+  const effectiveFormats = formats.length > 0 ? formats : ['application/ld+json'];
 
-  // Standalone mode (native): works from any repo (backend pipeline or otherwise).
+  // Standalone mode: works from any repo (backend pipeline or otherwise).
   log.title('build — standalone');
   log.info(`repo: ${cwd}`);
   log.info(`package: ${packageName}@${version}`);
   log.info(`lib: ${libName}`);
   if (noModels) log.info('models: désactivés (--no-models)');
-  else log.info(`spec: ${opts.spec} | preset: ${preset}`);
+  else log.info(`spec: ${opts.spec} | formats: ${effectiveFormats.join(', ')} | nullableMode: ${requiredMode}`);
 
   const { workspaceRoot, distRoot, npmCacheDir, requireFromWs } = await ensureStandaloneWorkspace({ repoRoot: cwd, log });
   log.info(`workspace: ${workspaceRoot}`);
@@ -65,7 +66,7 @@ export async function runBuild(packageName, opts) {
     noModels,
     spec,
     requiredMode,
-    preset,
+    formats: effectiveFormats,
     include,
     exclude,
     debug,

package/tools/core/generate.js

@@ -52,18 +52,25 @@ async function generateLibrary({ cwd, libName, packageName, version, debug }) {
   // angular.json / workspace patching is intentionally not done here (Meridiane is standalone).
 }
 
-async function generateModels({ cwd, libName, spec, requiredMode, preset, include, exclude, debug }) {
+async function generateModels({ cwd, libName, spec, requiredMode, formats, include, exclude, debug }) {
   const outDir = path.resolve(cwd, 'projects', libName, 'src', 'models');
   const templatesDir = path.resolve(pkgRoot, 'tools', 'generator', 'models', 'templates');
 
-  if (debug) console.log('[meridiane] generate models', { outDir: path.relative(cwd, outDir), requiredMode, preset, includeCount: include.length, excludeCount: exclude.length });
+  if (debug)
+    console.log('[meridiane] generate models', {
+      outDir: path.relative(cwd, outDir),
+      requiredMode,
+      formats: Array.isArray(formats) ? formats : [],
+      includeCount: include.length,
+      excludeCount: exclude.length,
+    });
 
   await ensureCleanDir(outDir);
 
   // Write models + index.ts.
   const { models } = buildModelsFromOpenAPI(spec, {
     requiredMode,
-    preset,
+    formats: Array.isArray(formats) ? formats : [],
     includeSchemaNames: include,
     excludeSchemaNames: exclude,
   });
@@ -77,6 +84,7 @@ async function generateModels({ cwd, libName, spec, requiredMode, preset, includ
         props: m.props,
         imports: m.imports,
         extendsTypes: m.extendsTypes || [],
+        extendsItem: m.extendsItem === true,
       },
     });
   }
@@ -98,8 +106,8 @@ async function generateModels({ cwd, libName, spec, requiredMode, preset, includ
  *   version: string,
  *   noModels: boolean,
  *   spec?: any,
- *   requiredMode: 'all-optional'|'spec',
- *   preset: 'all'|'native',
+ *   requiredMode: 'all'|'spec',
+ *   formats?: string[],
  *   include: string[],
  *   exclude: string[],
  *   debug: boolean,
@@ -117,7 +125,7 @@ export async function generateBridgeWorkspace(params) {
     noModels,
     spec,
     requiredMode,
-    preset,
+    formats,
     include,
     exclude,
     debug,
@@ -147,6 +155,6 @@ export async function generateBridgeWorkspace(params) {
 
   if (!spec) throw new Error('Internal error: spec is required when noModels=false');
   log?.step?.('génération des models (OpenAPI)');
-  await generateModels({ cwd, libName, spec, requiredMode, preset, include, exclude, debug });
+  await generateModels({ cwd, libName, spec, requiredMode, formats, include, exclude, debug });
   log?.success?.('génération terminée');
 }

package/tools/core/paths.js

@@ -1,10 +1,3 @@
-export function normalizePreset(presetOption) {
-  if (presetOption === undefined) return 'all';
-  if (presetOption === true) return 'native';
-  if (presetOption === 'native' || presetOption === 'all') return presetOption;
-  throw new Error(`Invalid --preset value: ${presetOption} (expected: native|all)`);
-}
-
 export function splitListArgs(values) {
   const out = [];
   for (const v of Array.isArray(values) ? values : []) {

package/tools/dev.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 
 import { deriveLibName } from './core/lib-name.js';
-import { normalizePreset, splitListArgs } from './core/paths.js';
+import { splitListArgs } from './core/paths.js';
 import { readOpenApiSpec } from './core/spec.js';
 import { createLogger } from './core/logger.js';
 import { generateBridgeWorkspace } from './core/generate.js';
@@ -139,12 +139,13 @@ export async function runDev(packageName, opts) {
   const libName = deriveLibName(effectivePackageName);
 
   const noModels = opts.models === false;
-  const preset = normalizePreset(useSandboxDefaults ? (opts.preset ?? 'native') : opts.preset);
+  const formats = splitListArgs(opts.formats);
   const include = splitListArgs(opts.include);
   const exclude = splitListArgs(opts.exclude);
 
   const version = '0.0.0-dev';
-  const requiredMode = 'all-optional';
+  const requiredMode = 'all';
+  const effectiveFormats = formats.length > 0 ? formats : ['application/ld+json'];
   const specSource = useSandboxDefaults ? (opts.spec ?? 'http://localhost:8000/api/docs.json') : opts.spec;
 
   log.title('dev — build standalone + install local');
@@ -153,7 +154,7 @@ export async function runDev(packageName, opts) {
   log.info(`lib: ${libName}`);
   if (useSandboxDefaults) log.info('defaults sandbox appliqués');
   if (noModels) log.info('models: désactivés (--no-models)');
-  else log.info(`spec: ${specSource} | preset: ${preset}`);
+  else log.info(`spec: ${specSource} | formats: ${effectiveFormats.join(', ')} | nullableMode: ${requiredMode}`);
 
   const { workspaceRoot, distRoot, npmCacheDir, requireFromWs } = await ensureStandaloneWorkspace({ repoRoot: appRoot, log });
   log.info(`workspace: ${workspaceRoot}`);
@@ -175,7 +176,7 @@ export async function runDev(packageName, opts) {
     noModels,
     spec,
     requiredMode,
-    preset,
+    formats: effectiveFormats,
     include,
     exclude,
     debug,

package/tools/generator/models/oas-contract.js

@@ -0,0 +1,159 @@
+import { schemaNameFromRef } from './schema-utils.js';
+
+function resolveRefPointer(spec, ref) {
+  const s = String(ref || '');
+  if (!s.startsWith('#/')) return undefined;
+  const parts = s.slice(2).split('/').filter(Boolean);
+  let cur = spec;
+  for (const p of parts) {
+    if (!cur || typeof cur !== 'object') return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function deref(spec, maybeRef) {
+  if (!maybeRef || typeof maybeRef !== 'object') return maybeRef;
+  if (typeof maybeRef.$ref === 'string') return resolveRefPointer(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 [k, v] of Object.entries(content)) {
+    const canon = canonicalizeMediaType(k);
+    if (canon === wantedLower) return v?.schema;
+  }
+  return undefined;
+}
+
+function is2xxStatus(code) {
+  const s = String(code || '');
+  if (/^[0-9]{3}$/.test(s)) return s.startsWith('2');
+  return /^2xx$/i.test(s);
+}
+
+/**
+ * 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);
+      return;
+    }
+
+    if (Array.isArray(node)) {
+      for (const it of node) walk(it);
+      return;
+    }
+
+    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);
+}
+
+/**
+ * Extracts root schemas from endpoints for one media type.
+ * - requestBody is ignored for PATCH (merge-patch typed as Partial<> elsewhere)
+ * - responses keep only 2xx and default
+ */
+function listRootsFromPaths(spec, { mediaType } = {}) {
+  const wantedLower = canonicalizeMediaType(mediaType);
+  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 [method, op0] of Object.entries(pathItem)) {
+      const op = deref(spec, op0);
+      if (!op || typeof op !== 'object') continue;
+
+      const isPatch = String(method || '').toLowerCase() === 'patch';
+
+      if (!isPatch) {
+        const rb = deref(spec, op.requestBody);
+        const rbSchema = getContentSchema(rb?.content, wantedLower);
+        if (rbSchema) roots.push(rbSchema);
+      }
+
+      const responses = op.responses;
+      if (!responses || typeof responses !== 'object') continue;
+      for (const [code, resp] of Object.entries(responses)) {
+        if (!is2xxStatus(code) && String(code).toLowerCase() !== 'default') continue;
+        const resolved = deref(spec, resp);
+        const schema = getContentSchema(resolved?.content, wantedLower);
+        if (schema) roots.push(schema);
+      }
+    }
+  }
+
+  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 n of start) {
+    if (!n || out.has(n)) continue;
+    out.add(n);
+    queue.push(n);
+  }
+
+  while (queue.length) {
+    const name = queue.pop();
+    const schema = schemas[name];
+    if (!schema) continue;
+    const refs = new Set();
+    collectComponentSchemaRefs(schema, refs);
+    for (const ref of refs) {
+      if (!ref || out.has(ref)) continue;
+      out.add(ref);
+      queue.push(ref);
+    }
+  }
+
+  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 = listRootsFromPaths(spec, cfg);
+  const initialRefs = new Set();
+  for (const r of roots) collectComponentSchemaRefs(r, initialRefs);
+  return expandWithSchemaDependencies(initialRefs, schemas);
+}

package/tools/generator/models/oas-schema-name.js

@@ -0,0 +1,71 @@
+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('');
+}
+
+export 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, '');
+  }
+
+  const basePath = baseRaw;
+  const groupPath = groupRaw;
+
+  return {
+    originalName: raw,
+    basePath,
+    groupPath,
+    baseVariant,
+    isMergePatch,
+    key: `${basePath.toLowerCase()}|${groupPath.toLowerCase()}`,
+  };
+}
+
+export 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('');
+}
+
+export function groupTsNameFromGroupPath(groupPath) {
+  const tokens = String(groupPath || '').split(/[._:]+/g).filter(Boolean);
+  return pascalizeTokens(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';
+}
+

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

@@ -1,53 +1,47 @@
 import { sanitizeTypeName, quoteKeyIfNeeded } from './utils.js';
-import { filterSchemaNames, applySchemaNameFilters, mergeAllOf, isObject, schemaNameFromRef } from './schema-utils.js';
-import { schemaLabel } from './naming.js';
+import { mergeAllOf, isObject, schemaNameFromRef } from './schema-utils.js';
 import { tsTypeOf, withNullable } from './type-resolver.js';
+import { canonicalizeMediaType, collectUsedSchemasForMediaType, expandWithSchemaDependencies } from './oas-contract.js';
+import { baseTsNameFromBasePath, formatSuffixToken, groupTsNameFromGroupPath, parseOpenApiSchemaName } from './oas-schema-name.js';
 
 /**
  * @typedef {{
- *   requiredMode?: 'all-optional'|'spec',
- *   preset?: 'all'|'native',
+ *   requiredMode?: 'all'|'spec',
+ *   formats?: string[],
  *   includeSchemaNames?: Array<RegExp|string|((name: string) => boolean)>,
  *   excludeSchemaNames?: Array<RegExp|string|((name: string) => boolean)>,
  * }} BuildOptions
  */
 
 /**
- * Construit une map originalName -> sanitizedName, en assurant l’unicité
- * @param {string[]} schemaNames
+ * @typedef {{
+ *   name: string,
+ *   tsKey: string,
+ *   type: string,
+ *   optional: boolean,
+ * }} ModelProp
  */
-function normalizeNativeBase(original) {
-  return String(original)
-    .replace(/\.jsonld\b/ig, '')
-    .replace(/\.jsonapi\b/ig, '')
-    .replace(/\.jsonmergepatch\b/ig, '')
-    .split('-')[0];
-}
 
-function buildNameMap(schemaNames, schemas, preset) {
-  // Build final map with uniqueness (deterministic order)
-  const used = new Set();
-  const nameMap = new Map();
-  for (const original of schemaNames) {
-    const label = schemaLabel(original, {preset});
-    nameMap.set(original, sanitizeTypeName(label, used));
-  }
+/**
+ * @typedef {{
+ *   name: string,
+ *   props: ModelProp[],
+ *   imports: string[],
+ *   extendsTypes: string[],
+ *   extendsItem?: boolean,
+ * }} ModelDefinition
+ */
 
-  // In native mode, alias excluded variants to the selected base type
-  // so `$ref` doesn't leak "User-user.write" etc into generated types.
-  if (preset === 'native') {
-    const baseToSanitized = new Map();
-    for (const original of schemaNames) {
-      baseToSanitized.set(normalizeNativeBase(original), nameMap.get(original));
-    }
-    for (const original of Object.keys(schemas)) {
-      const base = normalizeNativeBase(original);
-      const sanitized = baseToSanitized.get(base);
-      if (sanitized) nameMap.set(original, sanitized);
-    }
-  }
+function ensureNullable(ts) {
+  return /\|\s*null\b/.test(ts) ? ts : `${ts} | null`;
+}
 
-  return nameMap;
+function normalizeRequiredMode(value) {
+  const v = String(value ?? '').trim().toLowerCase();
+  if (!v) return 'all';
+  if (v === 'spec') return 'spec';
+  if (v === 'all') return 'all';
+  return 'all';
 }
 
 /**
@@ -57,23 +51,129 @@ function buildNameMap(schemaNames, schemas, preset) {
  * @returns {{ models: ModelDefinition[] }}
  */
 export function buildModelsFromOpenAPI(spec, options) {
-  const opts = { requiredMode: 'all-optional', ...(options || {}) };
+  const opts = { requiredMode: 'all', ...(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()]);
+  const formatsOpt = Array.isArray(opts.formats) ? opts.formats : [];
+  const formats = formatsOpt.length > 0 ? formatsOpt : ['application/ld+json'];
+  const requiredMode = normalizeRequiredMode(opts.requiredMode);
 
   /** @type {ModelDefinition[]} */
   const models = [];
 
-  for (const originalName of schemaNames) {
-    const raw = schemas[originalName];
-    const sanitized = nameMap.get(originalName);
+  // Contract-driven (formats): keep only schemas used by selected media types in real endpoints.
+  const normalizedFormats = [];
+  for (const f of formats) {
+    const canon = canonicalizeMediaType(f);
+    if (!canon) continue;
+    if (!normalizedFormats.includes(canon)) normalizedFormats.push(canon);
+  }
+  if (normalizedFormats.length === 0) normalizedFormats.push('application/ld+json');
+
+  /** @type {Map<string, Set<string>>} */
+  const usedByFormat = new Map(); // formatLower -> Set<schemaName>
+
+  for (const fmt of normalizedFormats) {
+    usedByFormat.set(fmt, collectUsedSchemasForMediaType(spec, { mediaType: fmt }));
+  }
+
+  /** @type {Map<string, Set<string>>} */
+  const schemaToFormats = new Map();
+  for (const [fmt, names] of usedByFormat.entries()) {
+    for (const name of names) {
+      if (!name) continue;
+      const set = schemaToFormats.get(name) || new Set();
+      set.add(fmt);
+      schemaToFormats.set(name, set);
+    }
+  }
+
+  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 allUsed = [...schemaToFormats.keys()]
+    .filter(Boolean)
+    .filter((n) => !/^Hydra/i.test(n))
+    .sort((a, b) => a.localeCompare(b))
+    .filter((originalName) => {
+      const parsed = parseOpenApiSchemaName(originalName);
+      const canonical = parsed.groupPath ? `${parsed.basePath}-${parsed.groupPath}` : parsed.basePath;
+      const fulls = [originalName, canonical];
+
+      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)));
+      return included && !excluded;
+    });
+
+  // Ensure filters never break compilation: always keep transitive deps of selected schemas.
+  const candidatesSet = include.length > 0 || exclude.length > 0 ? expandWithSchemaDependencies(allUsed, schemas) : new Set(allUsed);
+
+  const candidates = [...candidatesSet]
+    .filter((n) => !!n)
+    .filter((n) => !/^Hydra/i.test(n))
+    .sort((a, b) => a.localeCompare(b));
+
+  // Assign a preferred format to each schema (used for naming + JSON-LD behavior).
+  const formatIndex = new Map(normalizedFormats.map((f, i) => [f, i]));
+  const schemaEntries = candidates.map((schemaName) => {
+    const fmts = schemaToFormats.get(schemaName) || new Set();
+    const best = [...fmts].sort((a, b) => (formatIndex.get(a) ?? 999) - (formatIndex.get(b) ?? 999))[0] || normalizedFormats[0];
+    return { schemaName, preferredFormat: best, preferredFormatIndex: formatIndex.get(best) ?? 0 };
+  });
+  const preferredFormatBySchema = new Map(schemaEntries.map((e) => [e.schemaName, e.preferredFormat]));
+
+  // Compute desired TS names (format-agnostic), then disambiguate collisions by preferred format.
+  const byDesired = new Map(); // desired -> entries[]
+  for (const e of schemaEntries) {
+    const parsed = parseOpenApiSchemaName(e.schemaName);
+    if (parsed.isMergePatch) continue; // never generate patch models
+    const baseTs = baseTsNameFromBasePath(parsed.basePath);
+    const groupTs = groupTsNameFromGroupPath(parsed.groupPath);
+    const desired = `${baseTs}${groupTs}` || 'Model';
+    const list = byDesired.get(desired) || [];
+    list.push({ ...e, desired });
+    byDesired.set(desired, list);
+  }
+
+  // Assign unique TS names and build schemaName -> tsName map.
+  const usedTsNames = new Set();
+  const nameMap = new Map();
+  for (const [desired, list] of [...byDesired.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    list.sort((a, b) => {
+      const da = a.preferredFormatIndex - b.preferredFormatIndex;
+      if (da !== 0) return da;
+      return a.schemaName.localeCompare(b.schemaName);
+    });
+
+    for (let i = 0; i < list.length; i++) {
+      const entry = list[i];
+      const withFmt = i === 0 ? desired : `${desired}${formatSuffixToken(entry.preferredFormat)}`;
+      const tsName = sanitizeTypeName(withFmt, usedTsNames);
+      nameMap.set(entry.schemaName, tsName);
+    }
+  }
+  const allSanitizedNames = new Set([...nameMap.values()]);
+
+  for (const schemaName of candidates) {
+    const sanitized = nameMap.get(schemaName);
     if (!sanitized) continue;
 
+    const raw = schemas[schemaName];
+    if (!raw) continue;
+
+    const preferredFormat = preferredFormatBySchema.get(schemaName) ?? normalizedFormats[0];
+    const isJsonLd = canonicalizeMediaType(preferredFormat) === 'application/ld+json';
+    const forceNullable = requiredMode !== 'spec';
+
     /** @type {string[]} */
     const extendsTypes = [];
+    const deps = new Set();
 
     let effective = raw;
     if (raw?.allOf) {
@@ -81,7 +181,7 @@ export function buildModelsFromOpenAPI(spec, options) {
       if (merged) {
         effective = merged;
       } else {
-        // Non-flattenable allOf (refs, mixed forms): keep inline object props and model refs as extends.
+        // Non-flattenable allOf: keep inline object props + other model refs as extends.
         const props = {};
         const required = new Set();
         const ext = new Set();
@@ -89,7 +189,9 @@ export function buildModelsFromOpenAPI(spec, options) {
         for (const part of raw.allOf) {
           if (part?.$ref) {
             const orig = schemaNameFromRef(part.$ref);
-            const refName = orig ? nameMap.get(orig) : undefined;
+            if (!orig) continue;
+            if (/^Hydra/i.test(orig)) continue;
+            const refName = orig ? nameMap.get(orig) || orig : undefined;
             if (refName && refName !== sanitized && allSanitizedNames.has(refName)) ext.add(refName);
             continue;
           }
@@ -107,29 +209,32 @@ export function buildModelsFromOpenAPI(spec, options) {
     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);
-      const type = withNullable(baseType, prop);
-      return {
-        name: propName,
-        tsKey: quoteKeyIfNeeded(propName),
-        type,
-        optional: opts.requiredMode === 'spec' ? !required.has(propName) : true,
-      };
-    });
+    const required = new Set(effective.required || []);
+    const props = Object.entries(effective.properties || {})
+      .filter(([propName]) => {
+        if (!isJsonLd) return true;
+        return propName !== '@id' && propName !== '@type' && propName !== '@context';
+      })
+      .map(([propName, prop]) => {
+        const baseType = tsTypeOf(prop, deps, nameMap, { requiredMode });
+        const type = forceNullable ? ensureNullable(baseType) : withNullable(baseType, prop);
+        return {
+          name: propName,
+          tsKey: quoteKeyIfNeeded(propName),
+          type,
+          optional: 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});
+    models.push({ name: sanitized, props, imports, extendsTypes, extendsItem: isJsonLd });
   }
 
-  return {models};
+  return { models };
 }

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

@@ -13,10 +13,11 @@ export function isObject(v) {
 /**
  * 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] : $ref;
+  return m ? m[1] : undefined;
 }
 
 /**
@@ -31,7 +32,7 @@ export function mergeAllOf(schemas) {
   for (const s of schemas) {
     if (s.$ref) {
       const ref = schemaNameFromRef(s.$ref);
-      if (HYDRA_BASE_RE.test(ref)) {
+      if (ref && HYDRA_BASE_RE.test(ref)) {
         continue;
       }
       return null;
@@ -46,98 +47,3 @@ export function mergeAllOf(schemas) {
   out.required = [...new Set(out.required)];
   return out;
 }
-
-/**
- * Liste les noms de schémas dans `components.schemas`.
- * La sélection/filtres est gérée par `applySchemaNameFilters`.
- * @param {Record<string, any>} schemas
- * @returns {string[]}
- */
-export function filterSchemaNames(schemas, cfg) {
-  return Object.keys(schemas).sort((a, b) => a.localeCompare(b));
-}
-
-/**
- * @param {unknown} rule
- * @returns {rule is ((name: string) => boolean)}
- */
-function isRuleFn(rule) {
-  return typeof rule === 'function';
-}
-
-/**
- * @param {string} name
- * @param {RegExp|string|((name: string) => boolean)} rule
- */
-function matchesRule(name, rule) {
-  if (rule instanceof RegExp) return rule.test(name);
-  if (isRuleFn(rule)) return !!rule(name);
-  if (typeof rule === 'string' && rule.length) return name.includes(rule);
-  return false;
-}
-
-/**
- * Applique un preset de génération et/ou des règles include/exclude.
- *
- * - `preset: "all"`: ne filtre rien (comportement par défaut)
- * - `preset: "native"`: retire les schémas "techniques" (Hydra*, jsonMergePatch…)
- *
- * Les règles `includeSchemaNames` / `excludeSchemaNames` s'appliquent sur les noms
- * de schémas OpenAPI (ex: "User-user.read", "Conversation.jsonMergePatch", …).
- *
- * @param {string[]} schemaNames
- * @param {{
- *   preset?: 'all'|'native',
- *   includeSchemaNames?: Array<RegExp|string|((name: string) => boolean)>,
- *   excludeSchemaNames?: Array<RegExp|string|((name: string) => boolean)>,
- * }} [cfg]
- */
-export function applySchemaNameFilters(schemaNames, cfg) {
-  const preset = cfg?.preset ?? 'all';
-
-  /** @type {Array<RegExp|string|((name: string) => boolean)>} */
-  const include = Array.isArray(cfg?.includeSchemaNames) ? cfg.includeSchemaNames : [];
-  /** @type {Array<RegExp|string|((name: string) => boolean)>} */
-  const exclude = Array.isArray(cfg?.excludeSchemaNames) ? [...cfg.excludeSchemaNames] : [];
-
-  // 1) include/exclude user filters (always applied first)
-  const hasInclude = include.length > 0;
-  let out = schemaNames.filter((name) => {
-    if (hasInclude && !include.some((r) => matchesRule(name, r))) return false;
-    if (exclude.some((r) => matchesRule(name, r))) return false;
-    return true;
-  });
-
-  // 2) preset filters
-  if (preset === 'native') {
-    out = out
-      .filter((n) => !/^Hydra/i.test(n))
-      .filter((n) => !/jsonMergePatch/i.test(n))
-      .filter((n) => !/\.jsonld\b/i.test(n))
-      .filter((n) => !/\.jsonapi\b/i.test(n));
-
-    // 3) collapse group variants: keep one schema per base (before `-`)
-    const score = (name) => {
-      if (!name.includes('-')) return 100;
-      const group = name.split('-').slice(1).join('-');
-      if (/(^|[.\-])read($|[.\-])/i.test(group)) return 50;
-      return 0;
-    };
-    const byBase = new Map();
-    for (const name of out) {
-      const base = name.split('-')[0];
-      const prev = byBase.get(base);
-      if (!prev) {
-        byBase.set(base, name);
-        continue;
-      }
-      const a = prev, b = name;
-      const sa = score(a), sb = score(b);
-      if (sb > sa) byBase.set(base, b);
-      else if (sb === sa && b.localeCompare(a) < 0) byBase.set(base, b);
-    }
-    out = [...byBase.values()].sort((a, b) => a.localeCompare(b));
-  }
-
-  return out;
-}

package/tools/generator/models/templates/model.hbs

@@ -1,9 +1,11 @@
+{{#if extendsItem}}
 import type { Item } from '../lib/ports/resource-repository.port';
+{{/if}}
 {{#each imports}}
 import type { {{this}} } from './{{this}}';
 {{/each}}
 
-export interface {{name}} extends Item{{#each extendsTypes}}, {{this}}{{/each}} {
+export interface {{name}}{{#if extendsItem}} extends Item{{#each extendsTypes}}, {{this}}{{/each}}{{else}}{{#each extendsTypes}}{{#if @first}} extends {{this}}{{else}}, {{this}}{{/if}}{{/each}}{{/if}} {
 {{#each props}}
   {{{tsKey}}}{{#if optional}}?{{/if}}: {{type}};
 {{/each}}

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

@@ -16,13 +16,19 @@ export function withNullable(ts, schema) {
  * @param {any} schema
  * @param {Set<string>} deps
  * @param {Map<string,string>} nameMap
+ * @param {{ requiredMode?: 'all'|'spec' }} [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';
+  const forceNullable = requiredMode !== 'spec';
 
   if (schema.$ref) {
     const orig = schemaNameFromRef(schema.$ref);
+    if (!orig) return 'any';
+    if (/jsonMergePatch/i.test(orig)) return 'any';
+    if (/^Hydra/i.test(orig)) return 'any';
     const name = nameMap.get(orig) || orig;
     deps.add(name);
     return name;
@@ -49,9 +55,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 +71,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 +85,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 +105,3 @@ export function tsTypeOf(schema, deps, nameMap) {
 
   return 'any';
 }
-

package/tools/generator/models/naming.js

@@ -1,26 +0,0 @@
-/**
- * Construit un label "tokenisé" (sans `.` ni `-`) à partir d'un nom de schéma OpenAPI.
- * Le label est ensuite passé à `sanitizeTypeName()` pour produire un identifiant TS stable.
- *
- * @param {string} original
- * @param {{ preset: 'all'|'native' }} cfg
- */
-export function schemaLabel(original, cfg) {
-  const preset = cfg?.preset ?? 'all';
-  if (preset === 'native') {
-    // En native, on vise un nom "entity-like" : on ignore le groupe (après `-`) si présent.
-    // Les variantes .jsonld/.jsonapi/jsonMergePatch sont censées être filtrées par le preset.
-    return String(original).split('-')[0];
-  }
-
-  // En all, on encode tout : `.` et `-` deviennent des séparateurs de tokens.
-  const rawTokens = String(original).split(/[.-]/g).filter(Boolean);
-  const tokens = rawTokens.map((t) => {
-    const lower = t.toLowerCase();
-    if (lower === 'jsonld') return 'Jsonld';
-    if (lower === 'jsonapi') return 'Jsonapi';
-    if (lower === 'jsonmergepatch' || t === 'jsonMergePatch') return 'JsonMergePatch';
-    return t;
-  });
-  return tokens.join(' ');
-}