@obsidiane/meridiane 2.0.10 → 2.0.12

package/README.md

@@ -59,10 +59,27 @@ Sorties :
 ## Notes importantes
 
 - fallback automatique `.../api/docs.json` -> `.../api/docs.jsonopenapi` si nécessaire
-- mode contract-driven : uniquement les schémas atteignables via `paths` pour les formats sélectionnés
+- mode contract-driven : uniquement les schémas atteignables via `paths` et `webhooks` pour les formats sélectionnés
 - modèles `*jsonMergePatch*` non générés (`PATCH` typé `Partial<T>`)
 - Meridiane ne publie pas : publication via `npm publish` côté CI
 
+## Couverture des schémas
+
+Le compilateur suit les types d’[OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.4.html) et le dialecte
+[JSON Schema 2020-12 d’OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0.html#schema-object) :
+
+- primitives, unions de `type`, objets, propriétés requises, dictionnaires et schémas booléens ;
+- tableaux homogènes, tuples `prefixItems`, tuples historiques et bornes de longueur des tuples ;
+- `enum` et `const`, y compris les valeurs JSON structurées ;
+- `allOf`, `oneOf`, `anyOf`, `nullable` et références locales vers `components.schemas` ou `$defs` ;
+- schémas racine objets sous forme d’interfaces et autres schémas sous forme d’aliases TypeScript ;
+- contrats atteignables depuis les bodies, paramètres, en-têtes, callbacks et webhooks.
+
+Les règles de validation sans équivalent structurel TypeScript (`pattern`, bornes numériques,
+`uniqueItems`, `contains`, `not`, conditions, fermeture exacte des propriétés, etc.) restent à la
+charge de la validation runtime. Les références externes doivent être préalablement regroupées dans
+le document OpenAPI fourni à Meridiane.
+
 ## Spécifique à ce repo
 
-Dans ce monorepo, `meridiane dev` peut être exécuté sans `packageName` et cible alors `@obsidiane/bridge-sandbox` (app `apps/sandbox`).
+Dans ce monorepo, `meridiane dev` peut être exécuté sans `packageName` et cible alors `@obsidiane/bridge-sandbox` (app `playground/angular-app`).

package/cli.js

@@ -2,10 +2,10 @@
 import process from 'node:process';
 import { Command } from 'commander';
 
-import { runDev } from './tools/dev.js';
-import { runBuild } from './tools/build.js';
-import { runGenerate } from './tools/generate.js';
-import { createLogger } from './tools/infra/logger.js';
+import { runBuild } from './src/application/run-build.js';
+import { runDev } from './src/application/run-dev.js';
+import { runGenerate } from './src/application/run-generate.js';
+import { createLogger } from './src/infrastructure/logger.js';
 
 const program = new Command();
 
@@ -30,6 +30,20 @@ function commonOptions(cmd) {
     .option('--debug', 'Enable debug logs');
 }
 
+function action(run) {
+  return async (packageName, opts) => {
+    const log = createLogger({debug: !!opts?.debug});
+
+    try {
+      const exitCode = await run(packageName, opts);
+      if (typeof exitCode === 'number' && exitCode !== 0) process.exit(exitCode);
+    } catch (error) {
+      log.error(error);
+      process.exit(typeof error?.exitCode === 'number' ? error.exitCode : 1);
+    }
+  };
+}
+
 commonOptions(
   program
     .command('dev')
@@ -37,17 +51,7 @@ commonOptions(
       '[packageName]',
       'NPM package name of the generated bridge (e.g. @acme/backend-bridge). Optional in this repo (defaults to @obsidiane/bridge-sandbox).'
     )
-    .action(async (packageName, opts) => {
-      const log = createLogger({ debug: !!opts?.debug });
-      try {
-        const exitCode = await runDev(packageName, opts);
-        if (typeof exitCode === 'number' && exitCode !== 0) process.exit(exitCode);
-      } catch (err) {
-        log.error(err);
-        const exitCode = typeof err?.exitCode === 'number' ? err.exitCode : 1;
-        process.exit(exitCode);
-      }
-    })
+    .action(action(runDev))
 );
 
 commonOptions(
@@ -55,17 +59,7 @@ commonOptions(
     .command('build')
     .argument('<packageName>', 'NPM package name of the generated bridge (e.g. @acme/backend-bridge)')
     .option('--version <semver>', 'Version to write in the generated bridge package.json (CI/CD)')
-    .action(async (packageName, opts) => {
-      const log = createLogger({ debug: !!opts?.debug });
-      try {
-        const exitCode = await runBuild(packageName, opts);
-        if (typeof exitCode === 'number' && exitCode !== 0) process.exit(exitCode);
-      } catch (err) {
-        log.error(err);
-        const exitCode = typeof err?.exitCode === 'number' ? err.exitCode : 1;
-        process.exit(exitCode);
-      }
-    })
+    .action(action(runBuild))
 );
 
 commonOptions(
@@ -74,17 +68,7 @@ commonOptions(
     .argument('<packageName>', 'NPM package name of the generated bridge (e.g. @acme/backend-bridge)')
     .option('--version <semver>', 'Version to write in the generated bridge package.json')
     .option('--out <dir>', 'Output directory (default: projects/<libName>)')
-    .action(async (packageName, opts) => {
-      const log = createLogger({ debug: !!opts?.debug });
-      try {
-        const exitCode = await runGenerate(packageName, opts);
-        if (typeof exitCode === 'number' && exitCode !== 0) process.exit(exitCode);
-      } catch (err) {
-        log.error(err);
-        const exitCode = typeof err?.exitCode === 'number' ? err.exitCode : 1;
-        process.exit(exitCode);
-      }
-    })
+    .action(action(runGenerate))
 );
 
 program.parse(process.argv);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@obsidiane/meridiane",
-  "version": "2.0.10",
+  "version": "2.0.12",
   "description": "Générateur de librairie Angular et modèles TypeScript (OpenAPI) pour un bridge Symfony/API Platform + Mercure.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/obsidiane-lab/meridiane"
+    "url": "git+https://github.com/obsidiane-lab/meridiane.git"
   },
   "type": "module",
   "publishConfig": {
@@ -18,16 +18,23 @@
   },
   "files": [
     "cli.js",
-    "tools/**",
+    "src/**",
     "templates/**",
     "README.md"
   ],
   "engines": {
-    "node": ">=20.19"
+    "node": ">=24.0.0"
   },
   "dependencies": {
+    "@angular/common": "20.3.29",
+    "@angular/compiler": "20.3.29",
+    "@angular/compiler-cli": "20.3.29",
+    "@angular/core": "20.3.29",
     "commander": "^14.0.3",
-    "handlebars": "^4.7.8",
-    "tslib": "^2.3.0"
+    "handlebars": "^4.7.9",
+    "ng-packagr": "20.3.2",
+    "rxjs": "7.8.2",
+    "tslib": "^2.8.1",
+    "typescript": "5.9.3"
   }
 }

package/src/README.md

@@ -0,0 +1,9 @@
+# Sources internes du générateur
+
+- `application/` orchestre les workflows du CLI ;
+- `domain/` contient les règles et la normalisation des options ;
+- `infrastructure/` gère fichiers, processus, specs, workspaces et installation locale ;
+- `generators/bridge/` écrit les fichiers du runtime Angular ;
+- `generators/models/` transforme OpenAPI et écrit les modèles TypeScript.
+
+Le runtime Angular généré se trouve dans `../templates/angular-bridge/`.

package/{tools/app → src/application}/bridge-workflow.js

@@ -1,11 +1,13 @@
 import process from 'node:process';
 import path from 'node:path';
 import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
 
-import { readOpenApiSpec } from '../infra/spec-loader.js';
-import { generateBridgeWorkspace } from '../infra/generate/bridge.js';
-import { ensureStandaloneWorkspace, ensureToolchainInstalled } from '../infra/standalone-workspace.js';
-import { ExitCodeError, runCommand } from '../infra/exec.js';
+import { generateBridgeWorkspace } from './generate-bridge.js';
+import { readOpenApiSpec } from '../infrastructure/spec-loader.js';
+import { ExitCodeError, runCommand } from '../infrastructure/exec.js';
+
+const ngPackagrPath = fileURLToPath(import.meta.resolve('ng-packagr/src/cli/main.js'));
 
 export async function runBridgeWorkflow({
   repoRoot,
@@ -25,23 +27,17 @@ export async function runBridgeWorkflow({
   packRelativeTo,
   projectReadmePath,
 }) {
-  const { workspaceRoot, distRoot, npmCacheDir, requireFromWs } = await ensureStandaloneWorkspace({ repoRoot, log });
-  log?.info?.(`workspace: ${workspaceRoot}`);
-
-  let resolvedSpec = spec;
-  if (!noModels) {
-    if (!resolvedSpec) {
-      if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
-      log?.step?.('lecture de la spec OpenAPI');
-      resolvedSpec = await readOpenApiSpec(specSource);
-      log?.success?.('spec chargée');
-    }
-  }
+  const distRoot = path.join(repoRoot, 'dist');
+  const buildRoot = path.join(distRoot, '.meridiane-workspace');
+  const npmCacheDir = path.join(buildRoot, '.npm-cache');
+  await fs.rm(buildRoot, { recursive: true, force: true });
+  await fs.mkdir(buildRoot, { recursive: true });
+  log?.info?.(`workspace: ${buildRoot}`);
 
-  await ensureToolchainInstalled({ workspaceRoot, requireFromWs, npmCacheDir, log });
+  const resolvedSpec = await loadSpecIfNeeded({ noModels, spec, specSource, log });
 
   await generateBridgeWorkspace({
-    cwd: workspaceRoot,
+    cwd: buildRoot,
     libName,
     packageName,
     version,
@@ -57,13 +53,13 @@ export async function runBridgeWorkflow({
     projectReadmePath,
   });
 
-  const ngPackageJsonPath = path.join(workspaceRoot, 'projects', libName, 'ng-package.json');
-  const tsconfigAbsPath = path.join(workspaceRoot, 'projects', libName, tsconfigPath);
+  const projectDir = path.join(buildRoot, 'projects', libName);
+  const ngPackageJsonPath = path.join(projectDir, 'ng-package.json');
+  const tsconfigAbsPath = path.join(projectDir, tsconfigPath);
 
   log?.step?.('ng-packagr');
-  const ngPackagrPath = requireFromWs.resolve('ng-packagr/src/cli/main.js');
   const packagrCode = await runCommand(process.execPath, [ngPackagrPath, '-p', ngPackageJsonPath, '-c', tsconfigAbsPath], {
-    cwd: workspaceRoot,
+    cwd: buildRoot,
   });
   if (packagrCode !== 0) throw new ExitCodeError(`ng-packagr failed (exit ${packagrCode})`, packagrCode);
 
@@ -83,7 +79,17 @@ export async function runBridgeWorkflow({
   });
   if (packCode !== 0) throw new ExitCodeError(`npm pack failed (exit ${packCode})`, packCode);
 
-  return { workspaceRoot, distRoot, distDir, npmCacheDir };
+  return { distDir };
+}
+
+async function loadSpecIfNeeded({ noModels, spec, specSource, log }) {
+  if (noModels || spec) return spec;
+  if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
+
+  log?.step?.('lecture de la spec OpenAPI');
+  const loadedSpec = await readOpenApiSpec(specSource);
+  log?.success?.('spec chargée');
+  return loadedSpec;
 }
 
 async function cleanupPackedTarballs(distDir) {

package/src/application/generate-bridge.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+
+import { configureBridgeOutput, writeBridgeFiles } from '../generators/bridge/write-bridge-files.js';
+import { writeModelFiles } from '../generators/models/write-model-files.js';
+
+/** Generates the Angular bridge sources in a workspace project. */
+export async function generateBridgeWorkspace({
+  cwd,
+  libName,
+  packageName,
+  version,
+  noModels,
+  spec,
+  requiredMode,
+  formats,
+  include,
+  exclude,
+  debug,
+  log,
+  distRoot,
+  projectDir: configuredProjectDir,
+  projectReadmePath,
+}) {
+  const projectDir = configuredProjectDir ?? path.resolve(cwd, 'projects', libName);
+
+  log?.step?.(`génération de la librairie (${path.relative(cwd, projectDir)})`);
+  await writeBridgeFiles({
+    projectDir,
+    libName,
+    packageName,
+    version,
+    projectReadmePath,
+    debug,
+    log,
+  });
+
+  if (distRoot) await configureBridgeOutput({ projectDir, distRoot, libName, log });
+
+  if (noModels) {
+    log?.info?.('models ignorés (--no-models)');
+    if (debug) log?.debug?.('[meridiane] --no-models enabled, skipping models generation');
+    return;
+  }
+
+  if (!spec) throw new Error('Internal error: spec is required when noModels=false');
+
+  log?.step?.('génération des models (OpenAPI)');
+  await writeModelFiles({ projectDir, spec, requiredMode, formats, include, exclude, debug, log });
+  log?.success?.('génération terminée');
+}

package/{tools/app → src/application}/run-build.js

@@ -2,7 +2,7 @@ import process from 'node:process';
 import path from 'node:path';
 
 import { normalizeBuildOptions } from '../domain/bridge-options.js';
-import { createLogger } from '../infra/logger.js';
+import { createLogger } from '../infrastructure/logger.js';
 import { runBridgeWorkflow } from './bridge-workflow.js';
 
 export async function runBuild(packageName, opts) {

package/{tools/app → src/application}/run-dev.js

@@ -2,17 +2,37 @@ import process from 'node:process';
 import path from 'node:path';
 
 import { normalizeDevOptions } from '../domain/bridge-options.js';
-import { createLogger } from '../infra/logger.js';
-import {
-  findLatestTgz,
-  installPackageFromDist,
-  resolveDevAppRoot,
-  resolveSandboxAppRoot,
-  resolveSpecSource,
-} from '../infra/dev-support.js';
-import { readOpenApiSpec } from '../infra/spec-loader.js';
+import { createLogger } from '../infrastructure/logger.js';
+import {resolveDevAppRoot, resolveSandboxAppRoot, resolveSpecSource} from '../infrastructure/dev-project.js';
+import {installPackageFromDist} from '../infrastructure/local-package-install.js';
+import { readOpenApiSpec } from '../infrastructure/spec-loader.js';
 import { runBridgeWorkflow } from './bridge-workflow.js';
 
+async function loadDevSpec({config, opts, appRoot, log}) {
+  if (config.noModels) return {noModels: true};
+
+  const specSource = await resolveSpecSource({
+    useSandboxDefaults: config.useSandboxDefaults,
+    appRoot,
+    specArg: opts.spec,
+  });
+
+  if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
+
+  try {
+    return {noModels: false, specSource, spec: await readOpenApiSpec(specSource)};
+  } catch (error) {
+    const canSkipModels = config.useSandboxDefaults && opts.spec == null;
+    if (!canSkipModels) throw error;
+
+    log.warn(
+      'spec OpenAPI indisponible (backend non démarré ?) → génération des models ignorée. ' +
+        'Démarrez le backend ou passez `--spec ./openapi.json` (ou `--no-models`).'
+    );
+    return {noModels: true, specSource};
+  }
+}
+
 export async function runDev(packageName, opts) {
   const startCwd = process.cwd();
   const config = normalizeDevOptions(packageName, opts);
@@ -20,32 +40,7 @@ export async function runDev(packageName, opts) {
 
   const appRoot = config.useSandboxDefaults ? await resolveSandboxAppRoot(startCwd) : await resolveDevAppRoot(startCwd);
   const projectReadmePath = path.join(appRoot, 'README.md');
-
-  const specSource = config.noModels
-    ? undefined
-    : await resolveSpecSource({
-        useSandboxDefaults: config.useSandboxDefaults,
-        appRoot,
-        specArg: opts.spec,
-      });
-  let noModels = config.noModels;
-  let spec;
-  if (!noModels) {
-    if (!specSource) throw new Error('Missing --spec (url or JSON file path)');
-    try {
-      spec = await readOpenApiSpec(specSource);
-    } catch (err) {
-      if (config.useSandboxDefaults && opts.spec == null) {
-        noModels = true;
-        log.warn(
-          "spec OpenAPI indisponible (backend non démarré ?) → génération des models ignorée. " +
-            'Démarrez le backend ou passez `--spec ./openapi.json` (ou `--no-models`).'
-        );
-      } else {
-        throw err;
-      }
-    }
-  }
+  const {noModels, specSource, spec} = await loadDevSpec({config, opts, appRoot, log});
 
   log.title('dev — build standalone + install local');
   log.info(`app: ${appRoot}`);
@@ -74,7 +69,6 @@ export async function runDev(packageName, opts) {
     projectReadmePath,
   });
 
-  await findLatestTgz(distDir);
   await installPackageFromDist({ packageName: config.packageName, distDir, appRoot, log });
 
   log.success('bridge installé (node_modules) ✅');

package/{tools/app → src/application}/run-generate.js

@@ -2,9 +2,9 @@ import process from 'node:process';
 import path from 'node:path';
 
 import { normalizeGenerateOptions } from '../domain/bridge-options.js';
-import { createLogger } from '../infra/logger.js';
-import { readOpenApiSpec } from '../infra/spec-loader.js';
-import { generateBridgeWorkspace } from '../infra/generate/bridge.js';
+import { generateBridgeWorkspace } from './generate-bridge.js';
+import { createLogger } from '../infrastructure/logger.js';
+import { readOpenApiSpec } from '../infrastructure/spec-loader.js';
 
 function resolveProjectDir({ cwd, libName, outDir }) {
   if (outDir && outDir.length > 0) return path.resolve(cwd, outDir);

package/{tools → src}/domain/bridge-options.js

@@ -1,5 +1,5 @@
 import { deriveLibName } from './lib-name.js';
-import { splitListArgs } from './paths.js';
+import {splitListArgs} from './list-values.js';
 
 const DEFAULT_FORMATS = ['application/ld+json'];
 const SANDBOX_PACKAGE_NAME = '@obsidiane/bridge-sandbox';
@@ -23,13 +23,12 @@ function normalizeVersion(version) {
   return raw || '0.0.0';
 }
 
-export function normalizeBuildOptions(packageName, opts) {
+function normalizeNamedOptions(packageName, opts) {
   const common = normalizeCommonOptions(opts);
   const normalizedPackageName = String(packageName || '').trim();
   if (!normalizedPackageName) throw new Error('Missing packageName');
 
   return {
-    mode: 'build',
     packageName: normalizedPackageName,
     libName: deriveLibName(normalizedPackageName),
     version: normalizeVersion(opts?.version),
@@ -42,25 +41,14 @@ export function normalizeBuildOptions(packageName, opts) {
   };
 }
 
-export function normalizeGenerateOptions(packageName, opts) {
-  const common = normalizeCommonOptions(opts);
-  const normalizedPackageName = String(packageName || '').trim();
-  if (!normalizedPackageName) throw new Error('Missing packageName');
-
-  const outDir = typeof opts?.out === 'string' ? opts.out.trim() : '';
+export function normalizeBuildOptions(packageName, opts) {
+  return normalizeNamedOptions(packageName, opts);
+}
 
+export function normalizeGenerateOptions(packageName, opts) {
   return {
-    mode: 'generate',
-    packageName: normalizedPackageName,
-    libName: deriveLibName(normalizedPackageName),
-    version: normalizeVersion(opts?.version),
-    requiredMode: 'spec',
-    formats: normalizeFormats(common.formats),
-    include: common.include,
-    exclude: common.exclude,
-    noModels: common.noModels,
-    debug: common.debug,
-    outDir,
+    ...normalizeNamedOptions(packageName, opts),
+    outDir: typeof opts?.out === 'string' ? opts.out.trim() : '',
   };
 }
 
@@ -70,7 +58,6 @@ export function normalizeDevOptions(packageName, opts) {
   const effectivePackageName = String(packageName ?? SANDBOX_PACKAGE_NAME).trim();
 
   return {
-    mode: 'dev',
     useSandboxDefaults,
     packageName: effectivePackageName,
     libName: deriveLibName(effectivePackageName),

package/src/domain/list-values.js

@@ -0,0 +1,6 @@
+export function splitListArgs(values) {
+  return (Array.isArray(values) ? values : [])
+    .flatMap((value) => String(value).split(','))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}

package/src/generators/bridge/write-bridge-files.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { readJson, writeJsonIfChanged } from '../../infrastructure/json.js';
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(currentDir, '../../..');
+const bridgeTemplateDir = path.join(packageRoot, 'templates', 'angular-bridge');
+
+export async function writeBridgeFiles({
+  projectDir,
+  libName,
+  packageName,
+  version,
+  projectReadmePath,
+  debug,
+  log,
+}) {
+  if (debug) {
+    log?.debug?.('[meridiane] generate lib', {
+      libName,
+      packageName,
+      version,
+      targetDir: projectDir,
+    });
+  }
+
+  await fs.rm(projectDir, { recursive: true, force: true });
+  await fs.mkdir(projectDir, { recursive: true });
+  await fs.cp(bridgeTemplateDir, projectDir, { recursive: true });
+
+  await replacePlaceholders(projectDir, {
+    '__LIB_NAME__': libName,
+    '__PACKAGE_NAME__': packageName,
+  });
+
+  const packageJsonPath = path.join(projectDir, 'package.json');
+  const packageJson = await readJson(packageJsonPath);
+  packageJson.name = packageName;
+  packageJson.version = version;
+  await writeJsonIfChanged(packageJsonPath, packageJson);
+
+  await appendProjectReadme(path.join(projectDir, 'README.md'), projectReadmePath, debug, log);
+}
+
+export async function configureBridgeOutput({ projectDir, distRoot, libName, log }) {
+  const ngPackagePath = path.join(projectDir, 'ng-package.json');
+  const ngPackage = await readJson(ngPackagePath);
+  const outputDir = path.join(distRoot, libName);
+
+  ngPackage.dest = path.relative(projectDir, outputDir).split(path.sep).join('/');
+  await writeJsonIfChanged(ngPackagePath, ngPackage);
+  log?.debug?.('ng-package.json dest overridden', { dest: ngPackage.dest });
+}
+
+async function replacePlaceholders(directory, placeholders) {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const filePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      await replacePlaceholders(filePath, placeholders);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+
+    const content = await fs.readFile(filePath, 'utf8');
+    const rendered = Object.entries(placeholders)
+      .reduce((value, [placeholder, replacement]) => value.replaceAll(placeholder, replacement), content);
+    if (rendered !== content) await fs.writeFile(filePath, rendered);
+  }
+}
+
+async function appendProjectReadme(targetPath, sourcePath, debug, log) {
+  if (!sourcePath) return;
+
+  const projectReadme = await readText(sourcePath);
+  if (!projectReadme?.trim()) return;
+
+  const bridgeReadme = await readText(targetPath);
+  if (!bridgeReadme?.trim()) {
+    await fs.writeFile(targetPath, projectReadme);
+    if (debug) log?.debug?.('[meridiane] project README copied', { source: sourcePath });
+    return;
+  }
+
+  const combinedReadme =
+    `${bridgeReadme.trimEnd()}\n\n---\n\n## Documentation du projet\n\n${projectReadme.trimStart()}`;
+  await fs.writeFile(targetPath, combinedReadme);
+  if (debug) log?.debug?.('[meridiane] project README appended', { source: sourcePath });
+}
+
+async function readText(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return undefined;
+  }
+}