eva4j 1.0.13 → 1.0.14

package/src/commands/generate-kafka-event.js

@@ -151,7 +151,7 @@ async function generateKafkaEventCommand(moduleName, eventName) {
   try {
     for (const name of eventNames) {
       const normalizedName = toPascalCase(name);
-      const evtClassName = normalizedName.endsWith('Event') ? normalizedName : `${normalizedName}Event`;
+      const evtClassName = normalizedName.endsWith('IntegrationEvent') ? normalizedName : `${normalizedName}IntegrationEvent`;
 
       // In batch mode skip already-existing events; in single mode abort
       const evtPath = path.join(projectDir, 'src', 'main', 'java', packagePath, moduleName, 'application', 'events', `${evtClassName}.java`);
@@ -566,10 +566,10 @@ async function updateDomainEventHandler(projectDir, packagePath, context) {
     return false;
   }
 
-  // Compute domain event name by stripping 'Event' suffix from eventClassName
-  // e.g. OrderPlacedEvent → OrderPlaced
-  const domainEventName = context.eventClassName.endsWith('Event')
-    ? context.eventClassName.slice(0, -'Event'.length)
+  // Compute domain event name by stripping 'IntegrationEvent' suffix from eventClassName
+  // e.g. OrderPlacedIntegrationEvent → OrderPlaced
+  const domainEventName = context.eventClassName.endsWith('IntegrationEvent')
+    ? context.eventClassName.slice(0, -'IntegrationEvent'.length)
     : context.eventClassName;
 
   // Guard: the TODO comment must exist (generated by g entities)
@@ -639,4 +639,58 @@ function injectImportIntoFile(content, importStatement) {
   }
 }
 
+/**
+ * Returns the name of the installed message broker ('kafka' | 'rabbitmq') or null.
+ * Extensibility: add 'rabbitmq' support here when `eva add rabbitmq-client` is implemented.
+ * @param {import('../utils/config-manager')} configManager
+ * @returns {Promise<'kafka'|'rabbitmq'|null>}
+ */
+async function getInstalledBroker(configManager) {
+  if (await configManager.featureExists('kafka')) return 'kafka';
+  if (await configManager.featureExists('rabbitmq')) return 'rabbitmq';
+  return null;
+}
+
+/**
+ * Build a Kafka event generation context for a given domain event.
+ * Intended for use by `generate-entities.js` to auto-wire broker integration events
+ * without requiring a separate `eva g kafka-event` invocation.
+ *
+ * @param {string} packageName
+ * @param {string} moduleName
+ * @param {{ name: string, fields: Array }} domainEvent - Domain event from parsed domain.yaml
+ * @param {{ partitions?: number, replicas?: number }} [options]
+ * @returns {Object} context ready for generateSingleKafkaEvent()
+ */
+function buildKafkaEventContext(packageName, moduleName, domainEvent, { partitions = 3, replicas = 1 } = {}) {
+  const normalizedName = toPascalCase(domainEvent.name);
+  const integrationEventClassName = normalizedName.endsWith('IntegrationEvent')
+    ? normalizedName
+    : `${normalizedName}IntegrationEvent`;
+  const topicNameKebab = toKebabCase(domainEvent.name);
+  const topicNameCamel = toCamelCase(domainEvent.name);
+  const topicNameSnake = toSnakeCase(domainEvent.name).toUpperCase();
+  const topicSpringProperty = `\${topics.${topicNameKebab}}`;
+  return {
+    packageName,
+    moduleName,
+    modulePascalCase: toPascalCase(moduleName),
+    moduleCamelCase: toCamelCase(moduleName),
+    kafkaMessageBrokerClassName: `${toPascalCase(moduleName)}KafkaMessageBroker`,
+    eventClassName: integrationEventClassName,
+    topicNameSnake,
+    topicNameKebab,
+    topicNameCamel,
+    topicPropertyKey: topicNameKebab,
+    topicPropertyValue: topicNameSnake,
+    topicSpringProperty,
+    partitions,
+    replicas,
+    eventFields: domainEvent.fields || null
+  };
+}
+
 module.exports = generateKafkaEventCommand;
+module.exports.generateSingleKafkaEvent = generateSingleKafkaEvent;
+module.exports.buildKafkaEventContext = buildKafkaEventContext;
+module.exports.getInstalledBroker = getInstalledBroker;

package/src/commands/generate-system.js

@@ -0,0 +1,243 @@
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const pluralize = require('pluralize');
+
+const ConfigManager = require('../utils/config-manager');
+const { isEva4jProject } = require('../utils/validator');
+const { toCamelCase, toPascalCase, toPackagePath } = require('../utils/naming');
+
+const addModuleCommand = require('./add-module');
+const addKafkaClientCommand = require('./add-kafka-client');
+
+// Supported brokers → add-client command mapping
+const BROKER_CLIENT_COMMANDS = {
+  kafka: addKafkaClientCommand,
+};
+
+async function generateSystemCommand() {
+  const projectDir = process.cwd();
+
+  if (!(await isEva4jProject(projectDir))) {
+    console.error(chalk.red('❌ Not in an eva4j project directory'));
+    console.error(chalk.gray('Run this command inside a project created with eva4j'));
+    process.exit(1);
+  }
+
+  // ── Read system.yaml ──────────────────────────────────────────────────────
+  const systemYamlPath = path.join(projectDir, 'system.yaml');
+  if (!(await fs.pathExists(systemYamlPath))) {
+    console.error(chalk.red('❌ system.yaml not found in project root'));
+    console.error(chalk.gray('Create a system.yaml file first'));
+    process.exit(1);
+  }
+
+  let systemConfig;
+  try {
+    const content = await fs.readFile(systemYamlPath, 'utf-8');
+    systemConfig = yaml.load(content);
+  } catch (err) {
+    console.error(chalk.red('❌ Failed to parse system.yaml:'), err.message);
+    process.exit(1);
+  }
+
+  const { messaging, modules = [] } = systemConfig;
+
+  if (!modules.length) {
+    console.log(chalk.yellow('⚠️  No modules defined in system.yaml'));
+    process.exit(0);
+  }
+
+  console.log(chalk.blue('\n🚀 eva generate system\n'));
+
+  const configManager = new ConfigManager(projectDir);
+
+  // ── Step 1: Add modules ───────────────────────────────────────────────────
+  console.log(chalk.blue('\n📦 Adding modules...\n'));
+
+  for (const mod of modules) {
+    const modulePackageName = toCamelCase(mod.name);
+    const alreadyExists = await configManager.moduleExists(modulePackageName);
+
+    if (alreadyExists) {
+      console.log(chalk.gray(`  ✓ Module '${mod.name}' already exists, skipping`));
+    } else {
+      await addModuleCommand(mod.name, {});
+    }
+  }
+
+  // ── Step 2: Messaging broker client ──────────────────────────────────────
+  if (messaging && messaging.enabled === true) {
+    const broker = messaging.broker;
+    const addClientFn = BROKER_CLIENT_COMMANDS[broker];
+
+    if (!addClientFn) {
+      console.log(chalk.yellow(`  ⚠️  Broker '${broker}' is not yet supported. Skipping client setup.`));
+    } else {
+      const alreadyInstalled = await configManager.featureExists(broker);
+      if (alreadyInstalled) {
+        console.log(chalk.gray(`  ✓ ${broker}-client already installed, skipping\n`));
+      } else {
+        console.log(chalk.blue(`\n📡 Adding ${broker}-client...\n`));
+        await addClientFn();
+      }
+    }
+  }
+
+  // ── Step 3: Generate domain.yaml per module ───────────────────────────────
+  const projectConfig = await configManager.loadProjectConfig();
+  if (!projectConfig) {
+    console.error(chalk.red('❌ Could not load project configuration'));
+    process.exit(1);
+  }
+
+  const packagePath = toPackagePath(projectConfig.packageName);
+
+  console.log(chalk.blue('\n📄 Generating domain.yaml skeletons...\n'));
+
+  for (const mod of modules) {
+    const modulePackageName = toCamelCase(mod.name);
+    const moduleDir = path.join(projectDir, 'src', 'main', 'java', packagePath, modulePackageName);
+    const domainYamlPath = path.join(moduleDir, 'domain.yaml');
+
+    const existed = await fs.pathExists(domainYamlPath);
+    const content = buildDomainYaml(mod, systemConfig);
+    await fs.writeFile(domainYamlPath, content, 'utf-8');
+
+    if (existed) {
+      console.log(chalk.yellow(`  ♻️  ${modulePackageName}/domain.yaml overwritten`));
+    } else {
+      console.log(chalk.green(`  ✨ ${modulePackageName}/domain.yaml created`));
+    }
+  }
+
+  console.log(chalk.blue('\n✅ System bootstrap complete!\n'));
+  console.log(chalk.white('Next steps:'));
+  console.log(chalk.gray("  1. Edit each module's domain.yaml — add fields, enums, and refine the aggregate"));
+  console.log(chalk.gray('  2. Run: eva g entities <module>  (for each module)'));
+  console.log(chalk.gray('\n  Tip: run eva system validate to check cross-module consistency'));
+  console.log();
+}
+
+// ── Domain YAML builder ───────────────────────────────────────────────────────
+
+function buildDomainYaml(mod, systemConfig) {
+  const integrations = systemConfig.integrations || {};
+  const asyncEvents = integrations.async || [];
+  const syncCalls = integrations.sync || [];
+
+  const moduleName = mod.name;
+  const aggregateName = toPascalCase(pluralize.singular(moduleName));
+  const entityName = aggregateName.charAt(0).toLowerCase() + aggregateName.slice(1);
+  const tableName = moduleName.replace(/-/g, '_');
+
+  // Events this module produces
+  const producedEvents = asyncEvents.filter(e => e.producer === moduleName);
+  // Sync calls this module makes as caller
+  const outboundPorts = syncCalls.filter(s => s.caller === moduleName);
+  // REST endpoints exposed by this module
+  const exposes = mod.exposes || [];
+
+  const lines = [];
+  const today = new Date().toISOString().split('T')[0];
+
+  lines.push(`# domain.yaml — ${moduleName}`);
+  lines.push(`# Generated by: eva generate system  (${today})`);
+  lines.push(`#`);
+  lines.push(`# TODO: Complete this file:`);
+  lines.push(`#   - Add entity fields under aggregates[].entities[].fields`);
+  if (producedEvents.length) lines.push(`#   - Add event fields under aggregates[].events[].fields`);
+  if (outboundPorts.length)  lines.push(`#   - Add response shapes to ports[].methods[].response`);
+  if (exposes.length)        lines.push(`#   - Verify endpoints[].operations match the use cases in aggregates[]`);
+  lines.push(``);
+
+  // ── aggregates ────────────────────────────────────────────────────────────
+  lines.push(`aggregates:`);
+  lines.push(`  - name: ${aggregateName}`);
+  lines.push(`    entities:`);
+  lines.push(`      - name: ${entityName}`);
+  lines.push(`        isRoot: true`);
+  lines.push(`        tableName: ${tableName}`);
+  lines.push(`        audit:`);
+  lines.push(`          enabled: true`);
+  lines.push(`        fields:`);
+  lines.push(`          - name: id`);
+  lines.push(`            type: String`);
+  lines.push(`          # TODO: add more fields`);
+
+  if (producedEvents.length) {
+    lines.push(`    events:`);
+    for (const ev of producedEvents) {
+      lines.push(`      - name: ${ev.event}`);
+      lines.push(`        fields: []  # TODO: add event fields`);
+      lines.push(`        kafka: true`);
+    }
+  }
+
+  lines.push(``);
+
+  // ── endpoints ─────────────────────────────────────────────────────────────
+  if (exposes.length) {
+    // Derive basePath from the first exposed endpoint (e.g. /orders/{id} → /orders)
+    const basePath = '/' + (exposes[0].path || '').replace(/^\//, '').split('/')[0];
+    lines.push(`endpoints:`);
+    lines.push(`  basePath: ${basePath}`);
+    lines.push(`  versions:`);
+    lines.push(`    - version: v1`);
+    lines.push(`      operations:`);
+    for (const ep of exposes) {
+      lines.push(`        - useCase: ${ep.useCase}`);
+      lines.push(`          method: ${ep.method}`);
+      lines.push(`          path: ${ep.path}`);
+      if (ep.description) lines.push(`          description: "${ep.description}"`);
+    }
+    lines.push(``);
+  }
+
+  // ── ports ─────────────────────────────────────────────────────────────────
+  if (outboundPorts.length) {
+    lines.push(`ports:`);
+    for (const port of outboundPorts) {
+      lines.push(`  - name: ${port.port}`);
+      lines.push(`    target: ${port.calls}  # from system.yaml integrations.sync`);
+      lines.push(`    methods:`);
+      for (const endpoint of (port.using || [])) {
+        const methodName = deriveMethodName(endpoint);
+        lines.push(`      - name: ${methodName}  # TODO: rename if needed`);
+        lines.push(`        http: ${endpoint}`);
+        lines.push(`        response: []  # TODO: add response fields`);
+      }
+    }
+    lines.push(``);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Derive a camelCase Java method name from an HTTP entry like "GET /customers/{id}"
+ */
+function deriveMethodName(httpEntry) {
+  const parts = httpEntry.trim().split(/\s+/);
+  const method = (parts[0] || 'GET').toUpperCase();
+  const urlPath = parts[1] || '/';
+
+  const segments = urlPath.split('/').filter(s => s.length > 0);
+  const hasId = segments.some(s => s.charAt(0) === '{');
+  const resourceSegments = segments.filter(s => s.charAt(0) !== '{');
+  const lastResource = resourceSegments[resourceSegments.length - 1] || 'resource';
+  const singular = pluralize.singular(lastResource);
+  const pascal = toPascalCase(singular);
+
+  if (method === 'GET' && hasId) return `find${pascal}ById`;
+  if (method === 'GET') return `findAll${toPascalCase(lastResource)}`;
+  if (method === 'POST') return `create${pascal}`;
+  if (method === 'PUT' || method === 'PATCH') return `update${pascal}`;
+  if (method === 'DELETE') return `delete${pascal}`;
+  return toCamelCase(`${method.toLowerCase()}_${lastResource}`);
+}
+
+module.exports = generateSystemCommand;

package/src/generators/base-generator.js

@@ -8,7 +8,7 @@ class BaseGenerator {
   constructor(context) {
     this.context = context;
     this.templatesDir = path.join(__dirname, '../../templates/base');
-    this.projectDir = path.join(process.cwd(), context.artifactId);
+    this.projectDir = path.join(process.cwd(), context.projectName);
   }
 
   async generate() {
@@ -130,6 +130,14 @@ class BaseGenerator {
       path.join(this.projectDir, 'README.md'));
     await this.generateFile('root/AGENTS.md.ejs', 
       path.join(this.projectDir, 'AGENTS.md'));
+    await this.generateFile('root/system.yaml.ejs', 
+      path.join(this.projectDir, 'system.yaml'));
+    await this.generateFile('root/skill-build-system-yaml.ejs', 
+      path.join(this.projectDir, '.agents', 'skills', 'build-system-yaml', 'SKILL.md'));
+    await this.generateFile('root/skill-build-domain-yaml.ejs', 
+      path.join(this.projectDir, '.agents', 'skills', 'build-domain-yaml', 'SKILL.md'));
+    await this.generateFile('root/skill-build-domain-yaml-references-generate-entities.md.ejs', 
+      path.join(this.projectDir, '.agents', 'skills', 'build-domain-yaml', 'references', 'GENERATE_ENTITIES.md'));
     
     if (this.context.features.includeDocker) {
       await this.generateFile('docker/docker-compose.yaml.ejs', 

package/src/utils/naming.js

@@ -84,12 +84,13 @@ function getBaseEntity(hasSoftDelete, hasAudit) {
 /**
  * Convert artifact ID to valid Java package name
  * @param {string} artifactId - Artifact ID (e.g., my-project)
- * @returns {string} Valid package name (e.g., myproject)
+ * @returns {string} Valid package name (e.g., my_project)
  */
 function artifactIdToPackageName(artifactId) {
   return artifactId
     .toLowerCase()
-    .replace(/[^a-z0-9]/g, '');
+    .replace(/-/g, '_')
+    .replace(/[^a-z0-9_]/g, '');
 }
 
 /**

package/src/utils/system-validator.js

@@ -0,0 +1,314 @@
+'use strict';
+
+/**
+ * Validates a parsed system.yaml object against 5 architectural checks.
+ *
+ * @param {object} systemConfig - Parsed system.yaml content
+ * @returns {{ errors: string[], warnings: string[], ok: string[], score: number }}
+ */
+function validateSystem(systemConfig) {
+  const errors = [];
+  const warnings = [];
+  const ok = [];
+
+  const modules = systemConfig.modules || [];
+  const moduleNames = new Set(modules.map((m) => m.name));
+  const integrations = systemConfig.integrations || {};
+  const asyncEvents = integrations.async || [];
+  const syncIntegrations = integrations.sync || [];
+
+  // Build a quick lookup: module name → exposes array of "METHOD /path" strings
+  const moduleExposes = {};
+  for (const mod of modules) {
+    moduleExposes[mod.name] = (mod.exposes || []).map(
+      (ep) => `${ep.method} ${ep.path}`
+    );
+  }
+
+  // ── Check 1: Referential Integrity ────────────────────────────────────────
+
+  // 1a. Event producers
+  for (const ev of asyncEvents) {
+    if (!moduleNames.has(ev.producer)) {
+      errors.push(
+        `Integridad referencial: el productor '${ev.producer}' del evento '${ev.event}' no está declarado en modules[]`
+      );
+    } else {
+      ok.push(`Productor '${ev.producer}' del evento '${ev.event}' existe ✓`);
+    }
+  }
+
+  // 1b. Event consumers
+  for (const ev of asyncEvents) {
+    const consumers = ev.consumers || [];
+    for (const c of consumers) {
+      const moduleName = typeof c === 'string' ? c : c.module;
+      if (!moduleNames.has(moduleName)) {
+        errors.push(
+          `Integridad referencial: el consumidor '${moduleName}' del evento '${ev.event}' no está declarado en modules[]`
+        );
+      }
+    }
+  }
+  if (asyncEvents.every((ev) => (ev.consumers || []).every((c) => moduleNames.has(typeof c === 'string' ? c : c.module)))) {
+    ok.push('Todos los consumidores de eventos están declarados como módulos ✓');
+  }
+
+  // 1c. Sync integration caller/callee existence
+  for (const sync of syncIntegrations) {
+    if (!moduleNames.has(sync.caller)) {
+      errors.push(
+        `Integridad referencial: el caller '${sync.caller}' de la integración síncrona no está declarado en modules[]`
+      );
+    }
+    if (!moduleNames.has(sync.calls)) {
+      errors.push(
+        `Integridad referencial: el callee '${sync.calls}' de la integración síncrona (caller: ${sync.caller}) no está declarado en modules[]`
+      );
+    }
+  }
+
+  // 1d. Sync endpoints exist in target module's exposes
+  let allSyncEndpointsFound = true;
+  for (const sync of syncIntegrations) {
+    if (!moduleNames.has(sync.calls)) continue; // already caught above
+    const targetExposes = moduleExposes[sync.calls] || [];
+    for (const endpoint of sync.using || []) {
+      const normalized = endpoint.trim().toUpperCase().replace(/\/+$/, '');
+      const found = targetExposes.some((ep) => {
+        const normalizedEp = ep.trim().toUpperCase().replace(/\/+$/, '');
+        return normalizedEp === normalized || endpointMatches(ep, endpoint);
+      });
+      if (!found) {
+        errors.push(
+          `Integridad referencial: el endpoint '${endpoint}' usado por '${sync.caller}' no está declarado en el exposes[] de '${sync.calls}'`
+        );
+        allSyncEndpointsFound = false;
+      }
+    }
+  }
+  if (allSyncEndpointsFound && syncIntegrations.length > 0) {
+    ok.push('Todos los endpoints usados en integraciones síncronas están declarados en los módulos destino ✓');
+  }
+
+  // ── Check 2: Cycle Detection (sync deps) ─────────────────────────────────
+
+  // Build directed graph: A → B when caller=A, calls=B
+  const syncGraph = {};
+  for (const sync of syncIntegrations) {
+    if (!syncGraph[sync.caller]) syncGraph[sync.caller] = [];
+    syncGraph[sync.caller].push(sync.calls);
+  }
+
+  // Detect strict bidirectional sync coupling (A→B and B→A)
+  const biDirChecked = new Set();
+  let biDirFound = false;
+  for (const sync of syncIntegrations) {
+    const key = [sync.caller, sync.calls].sort().join('↔');
+    if (biDirChecked.has(key)) continue;
+    biDirChecked.add(key);
+    const reverse = syncIntegrations.find(
+      (s) => s.caller === sync.calls && s.calls === sync.caller
+    );
+    if (reverse) {
+      errors.push(
+        `Acoplamiento circular síncrono: '${sync.caller}' y '${sync.calls}' se llaman mutuamente de forma síncrona. Esto puede causar deadlocks.`
+      );
+      biDirFound = true;
+    }
+  }
+
+  // DFS for longer cycles
+  function detectCycle(startNode) {
+    const visited = new Set();
+    function dfs(node, path) {
+      if (path.includes(node)) return path.concat(node);
+      if (visited.has(node)) return null;
+      visited.add(node);
+      for (const neighbor of syncGraph[node] || []) {
+        const result = dfs(neighbor, path.concat(node));
+        if (result) return result;
+      }
+      return null;
+    }
+    return dfs(startNode, []);
+  }
+
+  const cycleChecked = new Set();
+  let cycleFound = false;
+  for (const node of Object.keys(syncGraph)) {
+    if (cycleChecked.has(node)) continue;
+    const cycle = detectCycle(node);
+    if (cycle && cycle.length > 2) {
+      const cycleStr = cycle.join(' → ');
+      errors.push(`Ciclo síncrono detectado: ${cycleStr}`);
+      cycle.forEach((n) => cycleChecked.add(n));
+      cycleFound = true;
+    }
+  }
+
+  if (!biDirFound && !cycleFound) {
+    ok.push('No se detectaron ciclos ni acoplamiento síncrono bidireccional ✓');
+  }
+
+  // ── Check 3: Role Analysis ────────────────────────────────────────────────
+
+  for (const mod of modules) {
+    const hasExposes = (mod.exposes || []).length > 0;
+    const producesEvents = asyncEvents.some((e) => e.producer === mod.name);
+    const consumesEvents = asyncEvents.some((e) =>
+      (e.consumers || []).some((c) => (typeof c === 'string' ? c : c.module) === mod.name)
+    );
+    const makesSyncCalls = syncIntegrations.some((s) => s.caller === mod.name);
+    const receivesSyncCalls = syncIntegrations.some((s) => s.calls === mod.name);
+
+    const hasAnyIntegration = producesEvents || consumesEvents || makesSyncCalls || receivesSyncCalls;
+
+    if (!hasExposes && !hasAnyIntegration) {
+      warnings.push(
+        `Módulo aislado: '${mod.name}' no tiene endpoints expuestos ni integraciones declaradas`
+      );
+    } else if (!hasExposes) {
+      warnings.push(
+        `'${mod.name}' no tiene endpoints expuestos (exposes[] vacío o ausente)`
+      );
+    } else if (!hasAnyIntegration) {
+      ok.push(`'${mod.name}' es un módulo autónomo sin dependencias de integración`);
+    }
+
+    // Check: module that only consumes — expected, no warning
+    if (!producesEvents && consumesEvents && !makesSyncCalls) {
+      ok.push(`'${mod.name}' es consumidor puro de eventos (correcto: no produce eventos propios)`);
+    }
+  }
+
+  // ── Check 4: Behavior Gaps ─────────────────────────────────────────────────
+
+  const schedulerVerbs = ['expire', 'clean', 'close', 'archive', 'timeout', 'process', 'purge', 'flush'];
+  const mutationMethods = new Set(['PUT', 'PATCH', 'DELETE', 'POST']);
+
+  for (const mod of modules) {
+    for (const ep of mod.exposes || []) {
+      const useCaseLower = (ep.useCase || '').toLowerCase();
+      const method = (ep.method || '').toUpperCase();
+
+      if (!mutationMethods.has(method)) continue;
+
+      const matchedVerb = schedulerVerbs.find((v) => useCaseLower.startsWith(v) || useCaseLower.includes(v));
+      if (!matchedVerb) continue;
+
+      // Check: is this endpoint reachable via an async event
+      const triggeredByEvent = asyncEvents.some((ev) =>
+        (ev.consumers || []).some((c) => {
+          const consumer = typeof c === 'string' ? c : c.module;
+          if (consumer !== mod.name) return false;
+          // The event name often matches the use case verb
+          const eventLower = ev.event.toLowerCase();
+          return schedulerVerbs.some((v) => eventLower.includes(v));
+        })
+      );
+
+      // Check: is this endpoint called by a sync integration
+      const triggeredBySync = syncIntegrations.some((s) => s.calls === mod.name && (s.using || []).some((u) => u.includes(ep.path)));
+
+      if (!triggeredByEvent && !triggeredBySync) {
+        warnings.push(
+          `Gap de comportamiento: '${ep.useCase}' (${ep.method} ${ep.path}) en '${mod.name}' no tiene ningún evento ni llamada síncrona que lo active. Puede necesitar un scheduler o job periódico.`
+        );
+      }
+    }
+  }
+
+  // Check: modules with no exposes at all (already partially covered above, but surface separately)
+  for (const mod of modules) {
+    if (!mod.exposes || mod.exposes.length === 0) {
+      ok.push(`'${mod.name}' no expone endpoints REST directamente (módulo de integración)`);
+    }
+  }
+
+  // ── Check 5: Coupling Patterns ────────────────────────────────────────────
+
+  for (const sync of syncIntegrations) {
+    const caller = sync.caller;
+    const callee = sync.calls;
+
+    // Find reverse async: callee publishes event that caller consumes
+    const reverseAsyncEvents = asyncEvents.filter((ev) => {
+      if (ev.producer !== callee) return false;
+      return (ev.consumers || []).some((c) => (typeof c === 'string' ? c : c.module) === caller);
+    });
+
+    if (reverseAsyncEvents.length > 0) {
+      const eventNames = reverseAsyncEvents.map((e) => e.event).join(', ');
+      warnings.push(
+        `Acoplamiento asimétrico: '${caller}' llama síncronamente a '${callee}', mientras '${callee}' responde vía eventos asíncronos (${eventNames}). Considerar pasar los datos necesarios directamente en el evento para eliminar la llamada síncrona.`
+      );
+    }
+  }
+
+  // Detect dual trigger: endpoint appears in both sync.using and as event-triggered consumer
+  for (const mod of modules) {
+    for (const ep of mod.exposes || []) {
+      const endpointStr = `${ep.method} ${ep.path}`;
+      const inSync = syncIntegrations.some(
+        (s) => s.calls === mod.name && (s.using || []).some((u) => endpointMatches(endpointStr, u) || endpointMatches(u, endpointStr))
+      );
+      const inEvents = asyncEvents.some(
+        (ev) =>
+          (ev.consumers || []).some((c) => (typeof c === 'string' ? c : c.module) === mod.name) &&
+          asyncEvents.some(() => false) // placeholder; real dual-trigger needs business knowledge
+      );
+      // Flag endpoints used in sync AND the module also consumes events (approximate heuristic)
+      if (inSync) {
+        const modConsumesEvents = asyncEvents.some((ev) =>
+          (ev.consumers || []).some((c) => (typeof c === 'string' ? c : c.module) === mod.name)
+        );
+        if (modConsumesEvents) {
+          ok.push(
+            `'${mod.name}' tiene endpoints accesibles tanto síncronamente como vía eventos (diseño dual — intencional)`
+          );
+          break; // one ok per module is enough
+        }
+      }
+      void inEvents; // suppress unused warning
+    }
+  }
+
+  // Highlight producer-only modules (no event consumption, no sync calls received) — healthy pattern
+  for (const mod of modules) {
+    const onlyProduces =
+      asyncEvents.some((e) => e.producer === mod.name) &&
+      !asyncEvents.some((e) =>
+        (e.consumers || []).some((c) => (typeof c === 'string' ? c : c.module) === mod.name)
+      ) &&
+      !syncIntegrations.some((s) => s.calls === mod.name);
+
+    if (onlyProduces) {
+      ok.push(`'${mod.name}' es productor puro de eventos sin dependencias entrantes (bajo acoplamiento) ✓`);
+    }
+  }
+
+  // ── Score ────────────────────────────────────────────────────────────────
+
+  const total = ok.length + errors.length + warnings.length * 0.5;
+  const score = total > 0 ? Math.round((ok.length / total) * 100) : 100;
+
+  return { errors, warnings, ok, score };
+}
+
+/**
+ * Compares two HTTP endpoint strings with path param normalization.
+ * e.g.  "GET /screenings/{id}/seats"  matches  "GET /screenings/{id}/seats"
+ * Path params ({anything}) are treated as wildcards.
+ */
+function endpointMatches(declared, used) {
+  const normalizePath = (str) =>
+    str
+      .trim()
+      .toUpperCase()
+      .replace(/\{[^}]+\}/g, '{*}')
+      .replace(/\/+$/, '');
+  return normalizePath(declared) === normalizePath(used);
+}
+
+module.exports = { validateSystem };