@obsidiane/meridiane 2.0.7 → 2.0.11

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

@@ -0,0 +1,240 @@
+import {hasOwn, resolveLocalRef, schemaNameFromRef} from './schema-utils.js';
+import {
+  arrayType,
+  atomicType,
+  formatType,
+  intersectionType,
+  nullableType,
+  unionType,
+} from './type-expression.js';
+import {quoteKeyIfNeeded, quoteStringLiteral} from './utils.js';
+
+const PRIMITIVE_TYPES = {
+  string: 'string',
+  integer: 'number',
+  number: 'number',
+  boolean: 'boolean',
+  null: 'null',
+};
+
+function literalExpression(value) {
+  if (value === null) return atomicType('null', true);
+  if (typeof value === 'string') return atomicType(quoteStringLiteral(value));
+  if (typeof value === 'number' || typeof value === 'bigint') return atomicType(String(value));
+  if (typeof value === 'boolean') return atomicType(String(value));
+
+  if (Array.isArray(value)) {
+    const items = value.map((item) => literalExpression(item).code);
+    return atomicType(`[${items.join(', ')}]`);
+  }
+
+  if (value && typeof value === 'object') {
+    const properties = Object.entries(value).map(([key, item]) =>
+      `${quoteKeyIfNeeded(key)}: ${literalExpression(item).code};`
+    );
+    return atomicType(`{ ${properties.join(' ')} }`);
+  }
+
+  return atomicType('any');
+}
+
+function tupleMember(type, optional = false) {
+  return optional ? `${formatType(type)}?` : type.code;
+}
+
+function nonNegativeInteger(value) {
+  return Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+/**
+ * Creates one resolver for a model. Its lexical context owns name resolution,
+ * dependency collection and local-reference cycle detection.
+ */
+export function createTypeResolver({
+  dependencies = new Set(),
+  typeNames = new Map(),
+  requiredMode = 'all',
+  spec,
+} = {}) {
+  const resolvingRefs = new Set();
+
+  function resolveReference(ref) {
+    const componentName = schemaNameFromRef(ref);
+    if (componentName) {
+      if (/jsonMergePatch/i.test(componentName) || /^Hydra/i.test(componentName)) {
+        return atomicType('any');
+      }
+
+      const typeName = typeNames.get(componentName) ?? componentName;
+      dependencies.add(typeName);
+      return atomicType(typeName);
+    }
+
+    const target = resolveLocalRef(spec, ref);
+    if (target === undefined || resolvingRefs.has(ref)) return atomicType('any');
+
+    resolvingRefs.add(ref);
+    try {
+      return resolve(target);
+    } finally {
+      resolvingRefs.delete(ref);
+    }
+  }
+
+  function resolveProperty(schema) {
+    const type = resolve(schema);
+    return requiredMode === 'spec' ? type : nullableType(type);
+  }
+
+  function resolveDictionaryValue(additionalProperties, properties) {
+    const additionalType = additionalProperties === true
+      ? atomicType('any')
+      : resolve(additionalProperties);
+    if (additionalType.code === 'any') return additionalType;
+
+    const memberTypes = properties.map(({type}) => type);
+    if (properties.some(({optional}) => optional)) memberTypes.push(atomicType('undefined'));
+    return unionType([additionalType, ...memberTypes]);
+  }
+
+  function resolveObject(schema) {
+    const requiredProperties = new Set(schema.required ?? []);
+    const properties = Object.entries(schema.properties ?? {}).map(([key, propertySchema]) => ({
+      key,
+      optional: requiredMode !== 'spec' || !requiredProperties.has(key),
+      type: resolveProperty(propertySchema),
+    }));
+    const members = properties.map(({key, optional, type}) =>
+      `${quoteKeyIfNeeded(key)}${optional ? '?' : ''}: ${type.code};`
+    );
+
+    if (hasOwn(schema, 'additionalProperties') && schema.additionalProperties !== false) {
+      const valueType = resolveDictionaryValue(schema.additionalProperties, properties);
+      members.push(`[key: string]: ${valueType.code};`);
+    } else if (properties.length === 0) {
+      const valueType = schema.additionalProperties === false ? 'never' : 'any';
+      members.push(`[key: string]: ${valueType};`);
+    }
+
+    return atomicType(`{ ${members.join(' ')} }`);
+  }
+
+  function resolveTuple(schema, prefixSchemas, additionalSchema) {
+    const minimum = nonNegativeInteger(schema.minItems) ?? 0;
+    const maximum = nonNegativeInteger(schema.maxItems);
+    if (maximum !== undefined && maximum < minimum) return atomicType('never');
+
+    const prefixLimit = maximum === undefined
+      ? prefixSchemas.length
+      : Math.min(prefixSchemas.length, maximum);
+    const prefix = prefixSchemas.slice(0, prefixLimit).map(resolve);
+    const requiredPrefixCount = Math.min(minimum, prefix.length);
+    const members = prefix.map((type, index) => tupleMember(type, index >= requiredPrefixCount));
+
+    const hasAdditionalItems = additionalSchema !== false;
+    if (!hasAdditionalItems && minimum > prefix.length) return atomicType('never');
+    if (!hasAdditionalItems || maximum === prefix.length) {
+      return atomicType(`[${members.join(', ')}]`);
+    }
+
+    const additionalType = additionalSchema === undefined || additionalSchema === true
+      ? atomicType('any')
+      : resolve(additionalSchema);
+    const requiredAdditionalCount = Math.max(0, minimum - prefix.length);
+    for (let index = 0; index < requiredAdditionalCount; index += 1) {
+      members.push(tupleMember(additionalType));
+    }
+
+    if (maximum === undefined) {
+      members.push(`...${formatType(additionalType)}[]`);
+    } else {
+      const optionalCount = Math.max(0, maximum - prefix.length - requiredAdditionalCount);
+      for (let index = 0; index < optionalCount; index += 1) {
+        members.push(tupleMember(additionalType, true));
+      }
+    }
+
+    return atomicType(`[${members.join(', ')}]`);
+  }
+
+  function resolveArray(schema) {
+    if (Array.isArray(schema.prefixItems)) {
+      return resolveTuple(schema, schema.prefixItems, schema.items);
+    }
+    if (Array.isArray(schema.items)) {
+      return resolveTuple(schema, schema.items, schema.additionalItems);
+    }
+    if (schema.items === false) return atomicType('[]');
+
+    const itemType = schema.items === true || schema.items === undefined
+      ? atomicType('any')
+      : resolve(schema.items);
+    return arrayType(itemType);
+  }
+
+  function resolveDeclaredType(type, schema) {
+    if (type === 'array') return resolveArray(schema);
+    if (type === 'object') return resolveObject(schema);
+
+    const primitive = PRIMITIVE_TYPES[type];
+    return primitive ? atomicType(primitive, type === 'null') : atomicType('any');
+  }
+
+  function resolveStructure(schema) {
+    if (Array.isArray(schema.type)) {
+      return unionType(schema.type.map((type) => resolveDeclaredType(type, schema)));
+    }
+    if (typeof schema.type === 'string') return resolveDeclaredType(schema.type, schema);
+    if (schema.properties || hasOwn(schema, 'additionalProperties') || schema.patternProperties) {
+      return resolveObject(schema);
+    }
+    if (schema.prefixItems || hasOwn(schema, 'items')) return resolveArray(schema);
+    return undefined;
+  }
+
+  function resolve(schema) {
+    if (schema === true || schema === undefined || schema === null) return atomicType('any');
+    if (schema === false) return atomicType('never');
+
+    const constraints = [];
+    if (schema.$ref) constraints.push(resolveReference(schema.$ref));
+
+    if (hasOwn(schema, 'const')) {
+      constraints.push(literalExpression(schema.const));
+    } else if (Array.isArray(schema.enum)) {
+      constraints.push(unionType(schema.enum.map(literalExpression)));
+    } else {
+      const structure = resolveStructure(schema);
+      if (structure) constraints.push(structure);
+    }
+
+    if (Array.isArray(schema.allOf)) {
+      constraints.push(intersectionType(schema.allOf.map(resolve)));
+    }
+    if (Array.isArray(schema.oneOf)) {
+      constraints.push(unionType(schema.oneOf.map(resolve)));
+    }
+    if (Array.isArray(schema.anyOf)) {
+      constraints.push(unionType(schema.anyOf.map(resolve)));
+    }
+
+    const type = intersectionType(constraints);
+    return schema.nullable ? nullableType(type) : type;
+  }
+
+  return {
+    typeOf: (schema) => resolve(schema).code,
+    nullableTypeOf: (schema) => nullableType(resolve(schema)).code,
+  };
+}
+
+/**
+ * Resolves an OpenAPI schema to TypeScript and collects component dependencies.
+ */
+export function tsTypeOf(schema, dependencies, typeNames, options) {
+  return createTypeResolver({dependencies, typeNames, ...options}).typeOf(schema);
+}
+
+export function nullableTsTypeOf(schema, dependencies, typeNames, options) {
+  return createTypeResolver({dependencies, typeNames, ...options}).nullableTypeOf(schema);
+}

package/src/generators/models/utils.js

@@ -0,0 +1,89 @@
+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',
+]);
+
+const STRING_ESCAPES = {
+  "'": "\\'",
+  '\\': '\\\\',
+  '\b': '\\b',
+  '\f': '\\f',
+  '\n': '\\n',
+  '\r': '\\r',
+  '\t': '\\t',
+};
+
+export function quoteStringLiteral(value) {
+  const escaped = String(value).replace(/['\\\u0000-\u001f\u2028\u2029]/g, (character) => {
+    const knownEscape = STRING_ESCAPES[character];
+    if (knownEscape) return knownEscape;
+    return `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`;
+  });
+  return `'${escaped}'`;
+}
+
+/**
+ * Construit un PascalCase à partir d’une liste de tokens
+ * @param {string[]} tokens
+ */
+export function pascalCase(tokens) {
+  return tokens
+    .filter(Boolean)
+    .map((token) => token.replace(/^[^A-Za-z0-9]+|[^A-Za-z0-9]+$/g, ''))
+    .filter(Boolean)
+    .map((token) => token.charAt(0).toUpperCase() + token.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 tokens = String(original).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;
+  let suffix = 2;
+  while (used.has(unique)) {
+    unique = `${name}${suffix++}`;
+  }
+  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 : quoteStringLiteral(k);
+}

package/src/generators/models/write-model-files.js

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { renderTemplateToFile } from './handlebars.js';
+import { buildModelsFromOpenAPI } from './openapi-to-models.js';
+import { ensureCleanDir } from './utils.js';
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const templatesDir = path.join(currentDir, 'templates');
+
+export async function writeModelFiles({ projectDir, spec, requiredMode, formats, include, exclude, debug, log }) {
+  const outputDir = path.resolve(projectDir, 'src', 'models');
+  if (debug) {
+    log?.debug?.('[meridiane] generate models', {
+      outputDir,
+      requiredMode,
+      formats: Array.isArray(formats) ? formats : [],
+      includeCount: include.length,
+      excludeCount: exclude.length,
+    });
+  }
+
+  await ensureCleanDir(outputDir);
+
+  const { models } = buildModelsFromOpenAPI(spec, {
+    requiredMode,
+    formats: Array.isArray(formats) ? formats : [],
+    includeSchemaNames: include,
+    excludeSchemaNames: exclude,
+  });
+
+  for (const model of models) {
+    await renderTemplateToFile({
+      templatePath: path.join(templatesDir, model.isAlias ? 'type-alias.hbs' : 'model.hbs'),
+      outPath: path.join(outputDir, `${model.name}.ts`),
+      ctx: {
+        name: model.name,
+        props: model.props,
+        imports: model.imports,
+        extendsTypes: model.extendsTypes || [],
+        extendsItem: model.extendsItem === true,
+        type: model.type,
+        separator: model.imports.length > 0 ? '\n' : '',
+      },
+    });
+  }
+
+  await renderTemplateToFile({
+    templatePath: path.join(templatesDir, 'index.hbs'),
+    outPath: path.join(outputDir, 'index.ts'),
+    ctx: { models: models.map(({ name }) => ({ name })) },
+  });
+
+  if (debug) log?.debug?.(`[meridiane] ${models.length} model(s) generated`);
+}

package/src/infrastructure/dev-project.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const SANDBOX_PACKAGE_NAME = '@obsidiane/meridiane-sandbox';
+
+async function isFile(filePath) {
+  try {
+    return (await fs.stat(filePath)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function readPackageName(projectRoot) {
+  try {
+    const packageJson = JSON.parse(await fs.readFile(path.join(projectRoot, 'package.json'), 'utf8'));
+    return typeof packageJson.name === 'string' ? packageJson.name : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function isSandboxProject(projectRoot) {
+  return (await readPackageName(projectRoot)) === SANDBOX_PACKAGE_NAME;
+}
+
+export async function resolveDevAppRoot(startDir) {
+  if (await isFile(path.join(startDir, 'package.json'))) return startDir;
+  throw new Error('No package.json found. Run `meridiane dev` from your Angular app root.');
+}
+
+export async function resolveSandboxAppRoot(startDir) {
+  if (await isSandboxProject(startDir)) return startDir;
+
+  const playgroundRoot = path.join(startDir, 'playground', 'angular-app');
+  if (await isSandboxProject(playgroundRoot)) return playgroundRoot;
+
+  throw new Error(
+    'Missing <packageName>. Run from the playground app (`playground/angular-app`) or provide a package name.'
+  );
+}
+
+export async function resolveSpecSource({useSandboxDefaults, appRoot, specArg}) {
+  if (!useSandboxDefaults || specArg) return specArg;
+
+  const localSpec = path.resolve(appRoot, '..', 'api-platform', 'var', 'openapi.json');
+  return (await isFile(localSpec)) ? localSpec : 'http://localhost:8000/api/docs.json';
+}

package/{tools/infra → src/infrastructure}/exec.js

@@ -10,12 +10,13 @@ export class ExitCodeError extends Error {
 }
 
 export function runCommand(cmd, args, { cwd, env } = {}) {
-  return new Promise((resolve) => {
+  return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, {
       stdio: 'inherit',
       cwd: cwd ?? process.cwd(),
       env: env ?? process.env,
     });
-    child.on('exit', (code) => resolve(code ?? 0));
+    child.once('error', reject);
+    child.once('exit', (code) => resolve(code ?? 1));
   });
 }

package/src/infrastructure/local-package-install.js

@@ -0,0 +1,104 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+function splitPackageName(packageName) {
+  const normalized = String(packageName || '').trim();
+  if (!normalized) throw new Error('Missing packageName');
+  if (!normalized.startsWith('@')) return {name: normalized};
+
+  const [scope, name] = normalized.split('/');
+  if (!scope || !name) throw new Error(`Invalid packageName: ${packageName}`);
+  return {scope, name};
+}
+
+async function findNodeModules(startDir) {
+  let currentDir = startDir;
+
+  while (true) {
+    const candidate = path.join(currentDir, 'node_modules');
+    try {
+      if ((await fs.stat(candidate)).isDirectory()) return candidate;
+    } catch {
+      // Continue towards the filesystem root.
+    }
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+
+  const nodeModules = path.join(startDir, 'node_modules');
+  await fs.mkdir(nodeModules, {recursive: true});
+  return nodeModules;
+}
+
+export async function installPackageFromDist({packageName, distDir, appRoot, log}) {
+  const nodeModules = await findNodeModules(appRoot);
+  const {scope, name} = splitPackageName(packageName);
+  const packageDir = scope ? path.join(nodeModules, scope, name) : path.join(nodeModules, name);
+  const displayName = scope ? `${scope}/${name}` : name;
+
+  log?.step?.(`installation locale dans node_modules (${displayName})`);
+
+  await fs.rm(packageDir, {recursive: true, force: true});
+  await fs.mkdir(path.dirname(packageDir), {recursive: true});
+  await fs.cp(distDir, packageDir, {
+    recursive: true,
+    filter: (source) => !source.endsWith('.tgz'),
+  });
+
+  await invalidateAngularViteCache({appRoot, packageName, log});
+  return packageDir;
+}
+
+async function invalidateAngularViteCache({appRoot, packageName, log}) {
+  const dependencyCaches = await findViteDependencyCaches(appRoot);
+  if (dependencyCaches.length === 0) return;
+
+  const packageCacheName = packageName.replace('/', '_');
+  const generatedFiles = ['.js', '.js.map', '.mjs', '.mjs.map'].map((suffix) => `${packageCacheName}${suffix}`);
+  let removedFiles = 0;
+
+  for (const cacheDir of dependencyCaches) {
+    for (const fileName of [...generatedFiles, '_metadata.json']) {
+      try {
+        await fs.rm(path.join(cacheDir, fileName), {force: true});
+        removedFiles += 1;
+      } catch {
+        // A stale cache file may disappear between discovery and deletion.
+      }
+    }
+  }
+
+  if (removedFiles > 0) {
+    log?.info?.(`cache Angular/Vite invalidé (${removedFiles} fichier(s)) pour ${packageName}`);
+  }
+}
+
+async function findViteDependencyCaches(appRoot) {
+  const cacheRoot = path.join(appRoot, '.angular', 'cache');
+  const dependencyCaches = [];
+
+  async function visit(dir, depth) {
+    if (depth > 8) return;
+
+    let entries;
+    try {
+      entries = await fs.readdir(dir, {withFileTypes: true});
+    } catch {
+      return;
+    }
+
+    if (path.basename(dir) === 'vite' && entries.some((entry) => entry.isDirectory() && entry.name === 'deps')) {
+      dependencyCaches.push(path.join(dir, 'deps'));
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === 'node_modules') continue;
+      await visit(path.join(dir, entry.name), depth + 1);
+    }
+  }
+
+  await visit(cacheRoot, 0);
+  return dependencyCaches;
+}

package/src/infrastructure/spec-loader.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs/promises';
+
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value || ''));
+}
+
+async function fetchJson(url) {
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    const message = error?.message ?? String(error);
+    throw new Error(
+      `Spec fetch failed: ${url}\n` +
+        `Reason: ${message}\n` +
+        `Tip: if your environment cannot access the network, use a local JSON file via --spec ./openapi.json`
+    );
+  }
+  if (!response.ok) {
+    const body = await response.text().catch(() => '');
+    throw new Error(
+      `Spec fetch failed: ${response.status} ${response.statusText}${body ? `\n${body}` : ''}`
+    );
+  }
+  return response.json();
+}
+
+export async function readOpenApiSpec(specArg) {
+  if (!specArg) throw new Error('Missing --spec (url or JSON file path)');
+  const spec = String(specArg);
+
+  if (isHttpUrl(spec)) {
+    try {
+      return await fetchJson(spec);
+    } catch (error) {
+      const isDocsJson = /\/api\/docs\.json$/i.test(spec);
+      if (!isDocsJson) throw error;
+      const fallback = spec.replace(/\/api\/docs\.json$/i, '/api/docs.jsonopenapi');
+      try {
+        return await fetchJson(fallback);
+      } catch (fallbackError) {
+        const primaryMessage = error?.message ?? String(error);
+        const fallbackMessage = fallbackError?.message ?? String(fallbackError);
+        throw new Error(
+          `Spec fetch failed (both endpoints tried)\n` +
+            `- ${spec}\n  ${primaryMessage}\n` +
+            `- ${fallback}\n  ${fallbackMessage}`
+        );
+      }
+    }
+  }
+
+  try {
+    const raw = await fs.readFile(spec, 'utf8');
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(`Spec file not found: ${spec}`);
+    }
+    if (error?.name === 'SyntaxError') {
+      throw new Error(`Invalid JSON in spec file ${spec}: ${error.message}`);
+    }
+    throw error;
+  }
+}