@obsidiane/meridiane 0.0.6

package/tools/generate-models.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import process from 'node:process';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+import {renderTemplateToFile} from './generator/models/handlebars.js';
+import {buildModelsFromOpenAPI} from './generator/models/openapi-to-models.js';
+import {ensureCleanDir} from './generator/models/utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Récupère un argument CLI de la forme --name=value
+ * @param {string} name
+ * @param {string|undefined} def
+ * @returns {string|undefined}
+ */
+function getArg(name, def) {
+  const a = process.argv.find((x) => x.startsWith(`--${name}=`));
+  return a ? a.split('=')[1] : def;
+}
+
+/**
+ * Lit la specification OpenAPI depuis une URL http(s) ou un chemin fichier JSON.
+ * @param {string} specPathOrUrl
+ */
+async function readSpec(specPathOrUrl) {
+  if (/^https?:\/\//.test(specPathOrUrl)) {
+    const res = await fetch(specPathOrUrl);
+    if (!res.ok) {
+      throw new Error(`Impossible de télécharger la spec : ${res.status} ${res.statusText}`);
+    }
+    return await res.json();
+  }
+
+  try {
+    const src = await fs.readFile(specPathOrUrl, 'utf8');
+    return JSON.parse(src);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`Fichier non trouvé : ${specPathOrUrl}`);
+    }
+    if (err.name === 'SyntaxError') {
+      throw new Error(`JSON invalide dans ${specPathOrUrl} : ${err.message}`);
+    }
+    throw err;
+  }
+}
+/**
+ * Charge un fichier de config local `models.config.js` (CWD) s'il existe.
+ * Le module peut exporter par défaut ou via export nommé.
+ */
+async function loadUserConfig() {
+  const cfgPath = path.resolve(process.cwd(), 'models.config.js');
+  try {
+    const st = await fs.stat(cfgPath);
+    if (!st.isFile()) return {};
+    const mod = await import(pathToFileURL(cfgPath).href);
+    return (mod?.default && typeof mod.default === 'object') ? mod.default : (mod || {});
+  } catch {
+    return {};
+  }
+}
+async function main() {
+  const specPathOrUrl = process.argv[2];
+  if (!specPathOrUrl) {
+    console.error('Usage: generate-models.js <OpenAPI spec (url|fichier)> [--item-import=../lib/ports/resource-repository.port] [--out=models] [--required-mode=all-optional|spec] [--no-index]');
+    process.exit(1);
+  }
+
+  const workDir = process.cwd();
+  const userCfg = await loadUserConfig();
+  const outDir = path.resolve(workDir, getArg('out', userCfg.outDir || 'models'));
+  const writeIndex = !('' + process.argv.join(' ')).includes('--no-index');
+  const itemImportPath = getArg('item-import', userCfg.itemImportPath || '../lib/ports/resource-repository.port');
+  const requiredMode = (() => {
+    const v = getArg('required-mode', userCfg.requiredMode || 'all-optional');
+    return (v === 'spec' || v === 'all-optional') ? v : 'all-optional';
+  })();
+  const preferFlavor = userCfg.preferFlavor; // 'jsonld' | 'jsonapi' | 'none'
+  const hydraBaseRegex = userCfg.hydraBaseRegex; // RegExp|string
+
+  console.log(`📥 Spec OpenAPI: ${specPathOrUrl}`);
+  const spec = await readSpec(specPathOrUrl);
+
+
+  console.log('🔧 Construction des interfaces…');
+  const {models} = buildModelsFromOpenAPI(spec, { requiredMode, preferFlavor, hydraBaseRegex });
+
+  const templatesDir = path.join(__dirname, 'generator', 'models', 'templates');
+  await ensureCleanDir(outDir);
+
+  for (const m of models) {
+    await renderTemplateToFile({
+      templatePath: path.join(templatesDir, 'model.hbs'),
+      outPath: path.join(outDir, `${m.name}.ts`),
+      ctx: {
+        itemImportPath,
+        name: m.name,
+        props: m.props,
+        imports: m.imports,
+      },
+    });
+  }
+
+  if (writeIndex) {
+    await renderTemplateToFile({
+      templatePath: path.join(templatesDir, 'index.hbs'),
+      outPath: path.join(outDir, 'index.ts'),
+      ctx: {models: models.map((m) => ({name: m.name}))},
+    });
+  }
+
+  console.log(`✅ ${models.length} modèle(s) écrit(s) dans ${path.relative(workDir, outDir)}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/tools/generator/models/handlebars.js

@@ -0,0 +1,15 @@
+import fs from 'node:fs/promises';
+import * as path from 'node:path';
+import Handlebars from 'handlebars';
+
+/**
+ * Rend un template Handlebars avec un contexte et écrit le fichier.
+ * @param {{ templatePath: string, outPath: string, ctx: any }} params
+ */
+export async function renderTemplateToFile({templatePath, outPath, ctx}) {
+  const tplSrc = await fs.readFile(templatePath, 'utf8');
+  const tpl = Handlebars.compile(tplSrc, {noEscape: true});
+  const out = tpl(ctx);
+  await fs.mkdir(path.dirname(outPath), {recursive: true});
+  await fs.writeFile(outPath, out, 'utf8');
+}

package/tools/generator/models/naming.js

@@ -0,0 +1,20 @@
+/**
+ * Convertit un nom de schéma OpenAPI en un nom lisible (sans artefacts jsonld/jsonapi)
+ * et intégrant les groupes (ex: Identity.jsonld-user.read -> Identity user read)
+ * @param {string} original
+ */
+export function friendlyName(original) {
+  const m = original.match(/^(.*?)(?:\.(?:jsonld|jsonapi))?-(.+)$/i);
+  if (m) {
+    const base = m[1];
+    const baseSimple = base.split('.').pop();
+    const groupTokens = m[2].split('.');
+    if (groupTokens.length && groupTokens[0].toLowerCase() === String(baseSimple).toLowerCase()) {
+      groupTokens.shift();
+    }
+    const group = groupTokens.join(' ');
+    return group ? `${base} ${group}` : base;
+  }
+  return original.replace(/\.(jsonld|jsonapi)$/ig, '');
+}
+

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

@@ -0,0 +1,98 @@
+import { sanitizeTypeName, quoteKeyIfNeeded } from './utils.js';
+import { filterSchemaNames, mergeAllOf, isObject } from './schema-utils.js';
+import { friendlyName } from './naming.js';
+import { tsTypeOf, withNullable } from './type-resolver.js';
+
+/**
+ * Construit une map originalName -> sanitizedName, en assurant l’unicité
+ * @param {string[]} schemaNames
+ */
+function buildNameMap(schemaNames) {
+  const parse = (original) => {
+    const m = original.match(/^(.*?)(?:\.(?:jsonld|jsonapi))?-(.+)$/i);
+    return m ? { base: m[1], group: m[2] } : { base: original, group: null };
+  };
+
+  const parsed = schemaNames.map((n) => ({ name: n, ...parse(n) }));
+  const roots = parsed.filter((p) => !p.group);
+  const grouped = parsed.filter((p) => !!p.group);
+
+  // Root sanitized names (to avoid collisions when dropping group)
+  const rootSanitized = new Set(roots.map((p) => sanitizeTypeName(p.base, new Set())));
+
+  // Count base candidates among grouped to see if unique
+  const baseCount = new Map();
+  for (const p of grouped) {
+    const cand = sanitizeTypeName(p.base, new Set());
+    baseCount.set(cand, (baseCount.get(cand) || 0) + 1);
+  }
+
+  // Build final map with uniqueness
+  const used = new Set();
+  const nameMap = new Map();
+  for (const p of parsed) {
+    let label;
+    if (p.group) {
+      const cand = sanitizeTypeName(p.base, new Set());
+      const isUniqueBase = (baseCount.get(cand) === 1) && !rootSanitized.has(cand);
+      label = isUniqueBase ? p.base : friendlyName(p.name);
+    } else {
+      label = friendlyName(p.name);
+    }
+    nameMap.set(p.name, sanitizeTypeName(label, used));
+  }
+  return nameMap;
+}
+
+/**
+ * Construit les définitions de modèles à partir d’une spec OpenAPI (components.schemas)
+ * @param {any} spec
+ * @param {BuildOptions} [options]
+ * @returns {{ models: ModelDefinition[] }}
+ */
+export function buildModelsFromOpenAPI(spec, options) {
+  const opts = { requiredMode: 'all-optional', ...(options || {}) };
+  const schemas = spec?.components?.schemas || {};
+  const schemaNames = filterSchemaNames(schemas, opts);
+  const nameMap = buildNameMap(schemaNames);
+  const allSanitizedNames = new Set([...nameMap.values()]);
+
+  /** @type {ModelDefinition[]} */
+  const models = [];
+
+  for (const originalName of schemaNames) {
+    const raw = schemas[originalName];
+    let effective = raw;
+    if (raw?.allOf) {
+      const merged = mergeAllOf(raw.allOf, opts);
+      if (merged) effective = merged;
+    }
+
+    const isObjectLike = effective?.type === 'object' || isObject(effective?.properties);
+    if (!isObjectLike) continue;
+
+    const sanitized = nameMap.get(originalName);
+    const required = new Set(effective.required || []);
+    const deps = new Set();
+
+    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 imports = [...deps]
+      .filter((n) => n !== sanitized)
+      .filter((n) => allSanitizedNames.has(n))
+      .sort((a, b) => a.localeCompare(b));
+
+    models.push({name: sanitized, props, imports});
+  }
+
+  return {models};
+}

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

@@ -0,0 +1,125 @@
+/** Hydra base schemas to ignore in merges and filtering */
+const DEFAULT_HYDRA_BASE_RE = /^Hydra(?:Item|Collection)BaseSchema$/;
+
+/**
+ * Récupère la RegExp Hydra à partir d'une config optionnelle.
+ * @param {{ hydraBaseRegex?: RegExp|string }} [cfg]
+ */
+function hydraRe(cfg) {
+  const r = cfg?.hydraBaseRegex;
+  if (!r) return DEFAULT_HYDRA_BASE_RE;
+  if (r instanceof RegExp) return r;
+  try { return new RegExp(r); } catch { return DEFAULT_HYDRA_BASE_RE; }
+}
+
+/**
+ * Détermine si une valeur est un objet simple (non tableau)
+ * @param {unknown} v
+ * @returns {v is Record<string, unknown>}
+ */
+export function isObject(v) {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Extrait le nom du schéma depuis une référence $ref
+ * @param {string} $ref
+ */
+export function schemaNameFromRef($ref) {
+  const m = $ref.match(/#\/components\/schemas\/(.+)$/);
+  return m ? m[1] : $ref;
+}
+
+/**
+ * Essaie d'aplatir un allOf en un objet unique.
+ * Ignore HydraItemBaseSchema/HydraCollectionBaseSchema quand rencontré.
+ * Retourne null si l'aplatissement n'est pas possible de manière sûre.
+ * @param {any[]} schemas
+ * @returns {any|null}
+ */
+export function mergeAllOf(schemas, cfg) {
+  const out = {type: 'object', properties: {}, required: []};
+  for (const s of schemas) {
+    if (s.$ref) {
+      const ref = schemaNameFromRef(s.$ref);
+      if (hydraRe(cfg).test(ref)) {
+        continue;
+      }
+      return null;
+    }
+    if (s.type === 'object') {
+      Object.assign(out.properties, s.properties || {});
+      if (Array.isArray(s.required)) out.required.push(...s.required);
+    } else {
+      return null;
+    }
+  }
+  out.required = [...new Set(out.required)];
+  return out;
+}
+
+/**
+ * Filtre et déduplique les noms de schémas à générer.
+ * Préférence entre variantes: jsonld > none > jsonapi.
+ * - Exclut HydraItem/Collection base schemas
+ * - Garde les noms groupés (avec `-`) en choisissant la meilleure variante
+ * - Garde les racines sans point et sans suffixe jsonld/jsonapi
+ * @param {Record<string, any>} schemas
+ * @returns {string[]}
+ */
+export function filterSchemaNames(schemas, cfg) {
+  const prefer = (cfg?.preferFlavor === 'jsonapi') ? ['jsonapi','none','jsonld']
+               : (cfg?.preferFlavor === 'none') ? ['none','jsonld','jsonapi']
+               : ['jsonld','none','jsonapi']; // default jsonld
+  const flavorOf = (name) => /\.jsonld\b/i.test(name) ? 'jsonld' : /\.jsonapi\b/i.test(name) ? 'jsonapi' : 'none';
+  const rank = (name) => 3 - prefer.indexOf(flavorOf(name));
+
+  const roots = [];
+  const grouped = new Map();
+  const variantsNoGroup = new Map(); // base -> best variant (no '-')
+
+  for (const n of Object.keys(schemas)) {
+    if (hydraRe(cfg).test(n)) continue;
+
+    const hasGroup = n.includes('-');
+    const hasDot = n.includes('.');
+    const isJsonFlavor = /\.jsonld\b|\.jsonapi\b/i.test(n);
+
+    if (!hasGroup) {
+      // Cas 1: racine simple (pas de point, pas de variante jsonld/jsonapi)
+      if (!hasDot && !isJsonFlavor) {
+        roots.push(n);
+        continue;
+      }
+      // Cas 2: variante jsonld/jsonapi sans groupe (ex: Workflow.WorkflowInput.jsonld ou Foo.jsonld)
+      if (isJsonFlavor) {
+        const base = n.replace(/\.(jsonld|jsonapi)\b/i, '');
+        // Si une base "pure" existe dans la spec, on préfère l’ignorer pour éviter les doublons
+        if (Object.prototype.hasOwnProperty.call(schemas, base)) {
+          continue;
+        }
+        const curr = variantsNoGroup.get(base);
+        if (!curr || rank(n) > rank(curr)) variantsNoGroup.set(base, n);
+        continue;
+      }
+      // Cas 3: nom avec point mais sans suffixe jsonld/jsonapi et sans group — on le considère tel quel
+      variantsNoGroup.set(n, n);
+      continue;
+    }
+
+    const m = n.match(/^(.*?)(?:\.(?:jsonld|jsonapi))?-(.+)$/i);
+    if (!m) {
+      const curr = grouped.get(n);
+      if (!curr || rank(n) > rank(curr)) grouped.set(n, n);
+      continue;
+    }
+    const base = m[1];
+    const group = m[2];
+    const key = `${base}|${group}`;
+    const curr = grouped.get(key);
+    if (!curr || rank(n) > rank(curr)) grouped.set(key, n);
+  }
+  // Ajoute les variantes sans groupe sélectionnées
+  const noGroupSelected = [...variantsNoGroup.values()];
+  return [...roots, ...[...grouped.values()], ...noGroupSelected].sort((a, b) => a.localeCompare(b));
+}

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

@@ -0,0 +1,3 @@
+{{#each models}}
+export type { {{name}} } from './{{name}}';
+{{/each}}

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

@@ -0,0 +1,10 @@
+import { Item } from '{{itemImportPath}}';
+{{#each imports}}
+import { {{this}} } from './{{this}}';
+{{/each}}
+
+export interface {{name}} extends Item {
+{{#each props}}
+  {{{tsKey}}}{{#if optional}}?{{/if}}: {{type}};
+{{/each}}
+}

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

@@ -0,0 +1,96 @@
+import { schemaNameFromRef } from './schema-utils.js';
+import { quoteKeyIfNeeded } from './utils.js';
+
+/**
+ * Ajoute | null à un type TS si le schéma est nullable (compat OAS 3.0),
+ * sauf si 'null' est déjà présent dans l'union.
+ * @param {string} ts
+ * @param {any} schema
+ */
+export function withNullable(ts, schema) {
+  return schema?.nullable && !/\|\s*null\b/.test(ts) ? `${ts} | null` : ts;
+}
+
+/**
+ * Résout un schéma OpenAPI vers un type TypeScript, en collectant les dépendances ($ref)
+ * @param {any} schema
+ * @param {Set<string>} deps
+ * @param {Map<string,string>} nameMap
+ * @returns {string}
+ */
+export function tsTypeOf(schema, deps, nameMap) {
+  if (!schema) return 'any';
+
+  if (schema.$ref) {
+    const orig = schemaNameFromRef(schema.$ref);
+    const name = nameMap.get(orig) || orig;
+    deps.add(name);
+    return name;
+  }
+
+  // Enum prioritaires: union littérale (supporte null)
+  if (schema.enum) {
+    const lit = schema.enum.map((v) => {
+      if (v === null) return 'null';
+      if (typeof v === 'string') return `'${v.replace(/'/g, "\\'")}'`;
+      if (typeof v === 'number' || typeof v === 'bigint') return String(v);
+      if (typeof v === 'boolean') return v ? 'true' : 'false';
+      return 'any';
+    });
+    return [...new Set(lit)].join(' | ');
+  }
+
+  // OpenAPI 3.1: null explicite et tableau de types (union)
+  if (schema.type === 'null') return 'null';
+  if (Array.isArray(schema.type)) {
+    const parts = new Set();
+    for (const t of schema.type) {
+      if (t === 'null') parts.add('null');
+      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 === 'object') {
+        const objTs = tsTypeOf({ type: 'object', properties: schema.properties, required: schema.required, additionalProperties: schema.additionalProperties }, deps, nameMap);
+        parts.add(objTs);
+      } else parts.add('any');
+    }
+    return [...parts].join(' | ');
+  }
+
+  if (schema.allOf) {
+    // Aplatir au niveau buildModelsFromOpenAPI; ici on combine si nécessaire
+    return schema.allOf.map((s) => tsTypeOf(s, deps, nameMap)).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.type === 'array') {
+    const it = tsTypeOf(schema.items || {}, deps, nameMap);
+    return `${it}[]`;
+  }
+
+  if (schema.type === 'object' || (schema.properties || schema.additionalProperties)) {
+    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 key = quoteKeyIfNeeded(k);
+      return `${key}${opt}: ${t}${nullable};`;
+    });
+    if (schema.additionalProperties) {
+      const at = tsTypeOf(schema.additionalProperties, deps, nameMap);
+      inline.push(`[key: string]: ${at};`);
+    }
+    return `{ ${inline.join(' ')} }`;
+  }
+
+  if (schema.type === 'string') return 'string';
+  if (schema.type === 'integer' || schema.type === 'number') return 'number';
+  if (schema.type === 'boolean') return 'boolean';
+
+  return 'any';
+}
+

package/tools/generator/models/utils.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs/promises';
+
+/**
+ * Supprime et recrée un dossier (idempotent)
+ * @param {string} dir
+ */
+export async function ensureCleanDir(dir) {
+  await fs.rm(dir, { recursive: true, force: true });
+  await fs.mkdir(dir, { recursive: true });
+}
+
+const RESERVED = new Set([
+  'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield', 'let', 'implements', 'interface', 'package', 'private', 'protected', 'public', 'static', 'await', 'abstract', 'boolean', 'byte', 'char', 'double', 'final', 'float', 'goto', 'int', 'long', 'native', 'short', 'synchronized', 'throws', 'transient', 'volatile'
+]);
+
+/**
+ * Construit un PascalCase à partir d’une liste de tokens
+ * @param {string[]} tokens
+ */
+export function pascalCase(tokens) {
+  return tokens
+    .filter(Boolean)
+    .map(t => t.replace(/^[^A-Za-z0-9]+|[^A-Za-z0-9]+$/g, ''))
+    .filter(Boolean)
+    .map(t => t.charAt(0).toUpperCase() + t.slice(1))
+    .join('');
+}
+
+/**
+ * Nettoie et désambiguïse un nom de type TypeScript, en évitant les mots réservés
+ * et collisions via un suffixe numérique.
+ * @param {string} original
+ * @param {Set<string>} used
+ */
+export function sanitizeTypeName(original, used) {
+  const base = original.includes('.') ? original.split('.').pop() : original;
+  const tokens = base.split(/[^A-Za-z0-9]+/);
+  let name = pascalCase(tokens) || 'Model';
+  if (/^[0-9]/.test(name)) name = '_' + name;
+  if (RESERVED.has(name)) name = name + 'Model';
+  let unique = name, i = 2;
+  while (used.has(unique)) {
+    unique = name + i++;
+  }
+  used.add(unique);
+  return unique;
+}
+
+/**
+ * Vérifie qu’une clé est un identifiant TS valide ET non réservé
+ * @param {string} k
+ */
+export function isValidTsIdentifier(k) {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) && !RESERVED.has(k);
+}
+
+/**
+ * Ajoute des quotes sur une clé si nécessaire (clé non valide en TS)
+ * @param {string} k
+ */
+export function quoteKeyIfNeeded(k) {
+  return isValidTsIdentifier(k) ? k : `'${k.replace(/'/g, "\\'")}'`;
+}