@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/monorepo/scripts/harness-rules/lint-barrels.ts

@@ -0,0 +1,1059 @@
+/**
+ * lint-barrels.ts — Linter determinista para HR-BARRELS-002 y HR-BARRELS-004 (deep-path imports).
+ *
+ * HR-BARRELS-004 sustituye a la derogada HR-BARRELS-003 (T-45: defecto de proceso — la excepción
+ * por `import()` dinámico se había editado en sitio sobre HR-BARRELS-003 en vez de derogar+crear;
+ * ver `cliter/harness-rules/barrels.md`). HR-BARRELS-003, a su vez, sustituyó a la derogada
+ * HR-BARRELS-001 (change reduce-frontend-eager-payload, task 5.5): mismos chequeos de deep-path,
+ * ahora atribuidos al id activo. El discriminante de
+ * unidad gobernada (`unitOf`) se extendió para tratar cada superficie declarada del @aurora
+ * frontend (grupo o módulo, tabla D1 del design de esa change) como unidad — la tabla de alias de
+ * `frontend/tsconfig.json` no puede impedir que un specifier RELATIVO escape a un fichero de
+ * implementación, así que el linter lo sigue cazando.
+ *
+ * Estructura (D9 del design):
+ *   - Funciones puras exportadas: `unitOf`, `resolveSpecifier`, `extractSpecifiers`,
+ *     `classifyImport`, `checkBarrels002` — testeables sin tocar disco.
+ *   - `main()` — orquesta E/S: escanea ficheros, lee catálogo, formatea salida, gestiona exit code.
+ *
+ * Alias pnpm: `hr:lint-barrels`
+ * Runner de tests: `node --import tsx --test scripts/harness-rules/lint-barrels.test.ts`
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Superficies declaradas del @aurora frontend (D1 de reduce-frontend-eager-payload)
+// ---------------------------------------------------------------------------
+
+/**
+ * Superficies de GRUPO declaradas como alias exacto en `frontend/tsconfig.json`
+ * (`@aurora/<grupo>`). Deliberadamente estática — igual que la tabla del tsconfig, añadir una
+ * superficie aquí es un acto explícito y revisable, no una introspección automática.
+ * `types` queda fuera: es un fichero (`types.ts`), no una carpeta con `index.ts`.
+ */
+const FRONTEND_AURORA_GROUP_SURFACES = new Set([
+  'components',
+  'composables',
+  'directives',
+  'lib',
+  'pipes',
+  'query-dsl',
+  'validators',
+]);
+
+/**
+ * Superficies de MÓDULO declaradas como alias exacto `@aurora/modules/<módulo>`.
+ * `@aurora/modules` (el grupo completo) NO está en la tabla D1 a propósito — arrastraría los
+ * nueve módulos vía el barrel de grupo, justo el drag que la change elimina.
+ */
+const FRONTEND_AURORA_MODULE_SURFACES = new Set([
+  'authentication',
+  'dashboard',
+  'graphql',
+  'health',
+  'lang',
+  'report-viewer',
+  'session',
+  'theme',
+  'widget',
+]);
+
+// ---------------------------------------------------------------------------
+// Tipos públicos
+// ---------------------------------------------------------------------------
+
+/** Un specifier extraído del código fuente con su número de línea. */
+export interface ExtractedSpecifier {
+  specifier: string;
+  line: number;
+  /**
+   * 'dynamic': proviene de un `import('...')` con literal — es un límite de code-splitting
+   * deliberado (T-45, HR-BARRELS-004 caso 10): Angular emite un chunk propio por specifier
+   * concreto, así que classifyImport() lo exime de la regla POR FORMA, nunca por fichero.
+   * 'static': import/export ... from, o jest.mock() — sigue gobernado sin cambios.
+   */
+  kind: 'static' | 'dynamic';
+}
+
+/** Resultado de un chequeo 002 sobre un fichero o especificador. */
+export interface Check002Violation {
+  /** Identificador del anchor pattern (A/B/C). */
+  anchor: '002-A' | '002-B' | '002-C';
+  /** El specifier o export que viola la regla. */
+  specifier: string;
+  /** Línea en el fichero donde aparece (0 si es chequeo de existencia de fichero). */
+  line: number;
+  message: string;
+}
+
+/** Clasificación de un import: 'ok' o 'violation'. */
+export type ImportClassification = 'ok' | 'violation';
+
+// ---------------------------------------------------------------------------
+// Tipos de la forma del tsconfig paths y de findings del orquestador
+// ---------------------------------------------------------------------------
+
+/** Mapa `alias → [path de expansión]` extraído de tsconfig.compilerOptions.paths */
+export type TsconfigPaths = Record<string, string[]>;
+
+// ---------------------------------------------------------------------------
+// unitOf()
+// ---------------------------------------------------------------------------
+
+/**
+ * Determina la "unidad gobernada" a la que pertenece un fichero absoluto.
+ *
+ * Reglas (D2 del design):
+ *   backend  @api|@app|@bridges / <bc> / <module> / **  → "<alias>/<bc>/<module>"
+ *   backend  @aurora/modules/<module>/**                 → "@aurora/modules/<module>"
+ *   frontend apps/<bc>/<module>/**           → "<bc>/<module>"
+ *   resto (raíz de BC/alias, layout/, @config, seeds…)  → undefined
+ *
+ * El parámetro `repoRoot` permite instanciar la función con raíces distintas en tests.
+ */
+export function unitOf(absolutePath: string, repoRoot: string): string | undefined {
+  const backendSrc = path.join(repoRoot, 'backend', 'src');
+  const frontendBc = path.join(
+    repoRoot,
+    'frontend',
+    'src',
+    'app',
+    'domains',
+    'admin',
+    'apps',
+  );
+
+  // Backend @api|@app|@bridges
+  for (const alias of ['@api', '@app', '@bridges']) {
+    const prefix = path.join(backendSrc, alias) + path.sep;
+    if (absolutePath.startsWith(prefix)) {
+      const relative = absolutePath.slice(prefix.length);
+      const segments = relative.split(path.sep);
+      // Necesitamos al menos 3 segmentos: <bc>/<module>/<fichero-o-sub>
+      // Si hay sólo 2 segmentos, el fichero está directamente en <bc>/ → sin unidad
+      if (segments.length >= 3) {
+        return `${alias}/${segments[0]}/${segments[1]}`;
+      }
+      return undefined;
+    }
+  }
+
+  // Backend @aurora/modules/<module>
+  const auroraModulesPrefix = path.join(backendSrc, '@aurora', 'modules') + path.sep;
+  if (absolutePath.startsWith(auroraModulesPrefix)) {
+    const relative = absolutePath.slice(auroraModulesPrefix.length);
+    const segments = relative.split(path.sep);
+    if (segments.length >= 1 && segments[0] !== '') {
+      return `@aurora/modules/${segments[0]}`;
+    }
+    return undefined;
+  }
+
+  // Frontend @aurora — superficies declaradas (D1 de reduce-frontend-eager-payload, HR-BARRELS-004)
+  const frontendAuroraPrefix = path.join(repoRoot, 'frontend', 'src', '@aurora') + path.sep;
+  if (absolutePath.startsWith(frontendAuroraPrefix)) {
+    const relative = absolutePath.slice(frontendAuroraPrefix.length);
+    const segments = relative.split(path.sep);
+
+    if (
+      segments[0] === 'modules' &&
+      segments.length >= 2 &&
+      FRONTEND_AURORA_MODULE_SURFACES.has(segments[1])
+    ) {
+      return `@aurora/modules/${segments[1]}`;
+    }
+    if (segments.length >= 1 && FRONTEND_AURORA_GROUP_SURFACES.has(segments[0])) {
+      return `@aurora/${segments[0]}`;
+    }
+    // Barrel raíz (index.ts), types.ts, story.types.ts, u otra carpeta NO declarada en la tabla
+    // D1 (p.ej. services/) → sin unidad, fail-open.
+    return undefined;
+  }
+
+  // Frontend apps/<bc>/<module>
+  const frontendPrefix = frontendBc + path.sep;
+  if (absolutePath.startsWith(frontendPrefix)) {
+    const relative = absolutePath.slice(frontendPrefix.length);
+    const segments = relative.split(path.sep);
+    // Necesitamos al menos 3 segmentos: <bc>/<module>/<fichero-o-sub>
+    // Con 2 segmentos el fichero está directamente en <bc>/ → sin unidad (raíz de BC)
+    if (segments.length >= 3) {
+      return `${segments[0]}/${segments[1]}`;
+    }
+    return undefined;
+  }
+
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// resolveSpecifier()
+// ---------------------------------------------------------------------------
+
+/**
+ * Resuelve un specifier de import a una ruta absoluta en disco.
+ *
+ * Estrategia:
+ *  1. Si el specifier comienza con '.' → resolución relativa desde el directorio del importador.
+ *  2. Si hay un alias en `tsconfigPaths` que casa → sustitución y búsqueda en disco.
+ *  3. Candidatos de extensión: sin extensión (carpeta/index.ts), .ts, /index.ts.
+ *
+ * El predicado `exists` es inyectable para testear sin disco.
+ */
+export function resolveSpecifier(
+  specifier: string,
+  importerAbsPath: string,
+  tsconfigPaths: TsconfigPaths,
+  exists: (absPath: string) => boolean,
+): string | undefined {
+  const importerDir = path.dirname(importerAbsPath);
+
+  if (specifier.startsWith('.')) {
+    // Resolución relativa
+    const base = path.resolve(importerDir, specifier);
+    return resolveWithExtensions(base, exists);
+  }
+
+  // Alias EXACTO (sin comodín '/*') — la forma que usa la tabla D1 del frontend @aurora:
+  // "@aurora/components": ["./src/@aurora/components/index.ts"], nunca "@aurora/components/*".
+  if (Object.prototype.hasOwnProperty.call(tsconfigPaths, specifier)) {
+    for (const target of tsconfigPaths[specifier]) {
+      const resolved = resolveWithExtensions(target, exists);
+      if (resolved !== undefined) return resolved;
+    }
+  }
+
+  // Intenta casar alias con comodín '/*' del tsconfig
+  for (const [pattern, targets] of Object.entries(tsconfigPaths)) {
+    if (!pattern.endsWith('/*')) continue;
+    const prefix = pattern.slice(0, -2); // quita "/*"
+    if (!specifier.startsWith(prefix + '/')) continue;
+    const rest = specifier.slice(prefix.length + 1); // lo que va tras el alias
+    for (const target of targets) {
+      const targetBase = target.slice(0, -2); // quita "/*"
+      const candidate = path.join(targetBase, rest);
+      const resolved = resolveWithExtensions(candidate, exists);
+      if (resolved !== undefined) return resolved;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Prueba las extensiones/index habituales para un path base.
+ *
+ * GROUP 10 (10.2): si `base` ya trae un specifier ESM explícito (termina en `/index.js` o en
+ * `.js`), el candidato de esa forma se prueba PRIMERO, mapeado a la extensión `.ts` que el
+ * compilador realmente emite (`x/index.js` → `x/index.ts`; `x.js` → `x.ts`) — el mismo mapeo
+ * que `scripts/packager/monorepo-script-paths.test.mjs` ya aplica sobre el árbol de plantillas.
+ * Esto REPARA la resolución; no afloja nada: un specifier que no resuelve en ninguna forma sigue
+ * sin resolver (fail-open intacto, D lint original).
+ */
+function resolveWithExtensions(
+  base: string,
+  exists: (p: string) => boolean,
+): string | undefined {
+  const candidates: string[] = [];
+
+  // `/index.js` (carpeta con barrel) y `.js` (fichero) son el MISMO caso aquí: ambos
+  // terminan en `.js`, y mapear ese sufijo a `.ts` da la ruta correcta en los dos —
+  // `x/index.js` → `x/index.ts`, `x.js` → `x.ts`.
+  if (base.endsWith('.js')) {
+    candidates.push(base.slice(0, -'.js'.length) + '.ts');
+  }
+
+  // Candidatos de la forma extensionless histórica, en el mismo orden de preferencia.
+  candidates.push(
+    base + '/index.ts', // carpeta con index
+    base + '.ts', // fichero con extensión
+    base, // ruta literal (si ya tiene extensión)
+  );
+
+  for (const candidate of candidates) {
+    if (exists(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// extractSpecifiers()
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrae todos los specifiers de import/export/import()/jest.mock() con su número de línea.
+ * Opera sobre el texto fuente (string puro, sin tocar disco).
+ *
+ * Superficies cubiertas (D5 del design):
+ *   - import ... from '...'
+ *   - export ... from '...'
+ *   - import('...')  dinámico con literal
+ *   - jest.mock('...')
+ */
+export function extractSpecifiers(source: string): ExtractedSpecifier[] {
+  const results: ExtractedSpecifier[] = [];
+  const lines = source.split('\n');
+
+  // Construimos un mapa de offset de inicio de línea para el cálculo rápido de nº de línea
+  const lineOffsets: number[] = [];
+  let offset = 0;
+  for (const line of lines) {
+    lineOffsets.push(offset);
+    offset += line.length + 1; // +1 por el '\n'
+  }
+
+  /** Dado un offset en el texto, devuelve el número de línea (1-based). */
+  function lineAt(charOffset: number): number {
+    let lo = 0;
+    let hi = lineOffsets.length - 1;
+    while (lo < hi) {
+      const mid = Math.floor((lo + hi + 1) / 2);
+      if (lineOffsets[mid] <= charOffset) {
+        lo = mid;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    return lo + 1;
+  }
+
+  // Para imports/exports estáticos buscamos el "from '...'" y reportamos la línea del from.
+  // Para import() y jest.mock() reportamos la línea del paréntesis de apertura.
+  //
+  // Regex 1: import('<specifier>') dinámico con literal
+  const DYNAMIC_RE = /\bimport\(\s*(['"])(.*?)\1\s*\)/g;
+  // Regex 2: jest.mock('<specifier>') o vi.mock('<specifier>') — el backend migró a Vitest
+  // (81 ficheros) y el frontend ya tenía 12 ficheros vi.mock que la extracción jest-only nunca vio.
+  const MOCK_RE = /\b(?:jest|vi)\.mock\(\s*(['"])(.*?)\1\s*[,)]/g;
+
+  // Verificamos que un "from '...'" esté precedido de import/export (no el from de otros contextos)
+  // Usamos una segunda regex para confirmar el contexto del "from" encontrado.
+  const IMPORT_EXPORT_RE =
+    /\b(?:import|export)\b(?:[\s\S]*?)\bfrom\s+(['"])(.*?)\1/gs;
+
+  let match: RegExpExecArray | null;
+
+  // from-specifiers
+  while ((match = IMPORT_EXPORT_RE.exec(source)) !== null) {
+    const specifier = match[2];
+    // Localizar la posición exacta del 'from' dentro del match para el número de línea
+    const matchText = match[0];
+    const fromIndex = matchText.lastIndexOf('from');
+    const specifierOffset = match.index + fromIndex;
+    results.push({
+      specifier,
+      line: lineAt(specifierOffset),
+      kind: 'static',
+    });
+  }
+
+  // import() dinámico con literal
+  while ((match = DYNAMIC_RE.exec(source)) !== null) {
+    results.push({
+      specifier: match[2],
+      line: lineAt(match.index),
+      kind: 'dynamic',
+    });
+  }
+
+  // jest.mock()
+  while ((match = MOCK_RE.exec(source)) !== null) {
+    results.push({
+      specifier: match[2],
+      line: lineAt(match.index),
+      kind: 'static',
+    });
+  }
+
+  // Ordenar por línea de aparición
+  results.sort((a, b) => a.line - b.line);
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// classifyImport()
+// ---------------------------------------------------------------------------
+
+/**
+ * Clasifica un import individual como 'ok' o 'violation' según HR-BARRELS-004 (D2-D4; regla
+ * activa desde la derogación de HR-BARRELS-003, T-45 — que a su vez sustituyó a la derogada
+ * HR-BARRELS-001 en reduce-frontend-eager-payload).
+ *
+ * Algoritmo (D2 del design):
+ *   T = resolveSpecifier(specifier)
+ *   isDynamicImport              → OK (T-45: import() dinámico — chunk boundary deliberado, ver
+ *                                  HR-BARRELS-004 caso 10 en cliter/harness-rules/barrels.md)
+ *   unidad(T) = undefined       → OK (target sin unidad: @api/graphql, seeds, @aurora/decorators…)
+ *   unidad(T) = unidad(importer)→ OK (mismo módulo, cualquier forma)
+ *   distinto                    → T debe ser carpeta con index.ts (barrel o sub-barrel)
+ *                                  si T es fichero de implementación → VIOLATION
+ */
+export function classifyImport(
+  importerAbsPath: string,
+  specifier: string,
+  tsconfigPaths: TsconfigPaths,
+  exists: (absPath: string) => boolean,
+  repoRoot: string,
+  isDynamicImport = false,
+): ImportClassification {
+  // HR-BARRELS-004 caso 10: un import() dinámico con literal es el límite de code-splitting que
+  // Angular usa para emitir un chunk propio por ruta lazy (loadComponent/loadChildren). Enrutarlo
+  // por un barrel de grupo arrastraría el módulo entero al chunk — la regresión que la regla
+  // existe para evitar (change reduce-frontend-eager-payload). Exención por FORMA del import,
+  // nunca por nombre de fichero: un import ... from ESTÁTICO al mismo target sigue violando.
+  if (isDynamicImport) return 'ok';
+
+  const resolved = resolveSpecifier(specifier, importerAbsPath, tsconfigPaths, exists);
+  if (resolved === undefined) {
+    // No se pudo resolver → no bloquear (fail-open en cero info)
+    return 'ok';
+  }
+
+  const targetUnit = unitOf(resolved, repoRoot);
+  if (targetUnit === undefined) {
+    // Target fuera de cualquier unidad gobernada → OK (caso 7, @api/graphql, seeds…)
+    return 'ok';
+  }
+
+  const importerUnit = unitOf(importerAbsPath, repoRoot);
+  if (importerUnit === targetUnit) {
+    // Mismo módulo → OK (caso 6)
+    return 'ok';
+  }
+
+  // Cross-unit: el target debe ser un barrel (index.ts) o sub-barrel (carpeta con index.ts)
+  // Si resolveSpecifier devolvió una ruta que termina en index.ts → es barrel → OK
+  if (resolved.endsWith(`${path.sep}index.ts`) || resolved.endsWith('/index.ts')) {
+    return 'ok';
+  }
+
+  // Target es un fichero de implementación → VIOLATION
+  return 'violation';
+}
+
+// ---------------------------------------------------------------------------
+// suggestBarrel()
+// ---------------------------------------------------------------------------
+
+/**
+ * Devuelve el barrel sugerido (raíz de la unidad destino) para un mensaje de error accionable.
+ * Ejemplo: target en "@app/o-auth/access-token" → "@app/o-auth/access-token"
+ */
+export function suggestBarrel(
+  resolvedTargetPath: string,
+  repoRoot: string,
+): string | undefined {
+  const backendSrc = path.join(repoRoot, 'backend', 'src');
+  const frontendBc = path.join(
+    repoRoot,
+    'frontend',
+    'src',
+    'app',
+    'domains',
+    'admin',
+    'apps',
+  );
+
+  for (const alias of ['@api', '@app', '@bridges']) {
+    const prefix = path.join(backendSrc, alias) + path.sep;
+    if (resolvedTargetPath.startsWith(prefix)) {
+      const relative = resolvedTargetPath.slice(prefix.length);
+      const segments = relative.split(path.sep);
+      if (segments.length >= 2) {
+        return `${alias}/${segments[0]}/${segments[1]}`;
+      }
+    }
+  }
+
+  const auroraModulesPrefix = path.join(backendSrc, '@aurora', 'modules') + path.sep;
+  if (resolvedTargetPath.startsWith(auroraModulesPrefix)) {
+    const relative = resolvedTargetPath.slice(auroraModulesPrefix.length);
+    const segments = relative.split(path.sep);
+    if (segments.length >= 1 && segments[0] !== '') {
+      return `@aurora/modules/${segments[0]}`;
+    }
+  }
+
+  // Frontend @aurora — mismas superficies declaradas que unitOf() (task 5.8, HR-BARRELS-004):
+  // sin esta rama, un target aquí SÍ tiene unidad (unitOf) pero el mensaje no nombra el alias.
+  const frontendAuroraPrefix = path.join(repoRoot, 'frontend', 'src', '@aurora') + path.sep;
+  if (resolvedTargetPath.startsWith(frontendAuroraPrefix)) {
+    const relative = resolvedTargetPath.slice(frontendAuroraPrefix.length);
+    const segments = relative.split(path.sep);
+
+    if (
+      segments[0] === 'modules' &&
+      segments.length >= 2 &&
+      FRONTEND_AURORA_MODULE_SURFACES.has(segments[1])
+    ) {
+      return `@aurora/modules/${segments[1]}`;
+    }
+    if (segments.length >= 1 && FRONTEND_AURORA_GROUP_SURFACES.has(segments[0])) {
+      return `@aurora/${segments[0]}`;
+    }
+    // Superficie NO declarada en la tabla D1 (p.ej. services/) → fail-open, igual que unitOf().
+    return undefined;
+  }
+
+  const frontendPrefix = frontendBc + path.sep;
+  if (resolvedTargetPath.startsWith(frontendPrefix)) {
+    const relative = resolvedTargetPath.slice(frontendPrefix.length);
+    const segments = relative.split(path.sep);
+    if (segments.length >= 2) {
+      return `${segments[0]}/${segments[1]}`;
+    }
+  }
+
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// checkBarrels002
+// ---------------------------------------------------------------------------
+
+/**
+ * Agrupa los tres chequeos estructurales de HR-BARRELS-002 como funciones puras.
+ * Cada función recibe solo lo que necesita para operar sin leer disco directamente,
+ * permitiendo tests unitarios sin filesystem.
+ */
+export const checkBarrels002 = {
+  /**
+   * 002-A: barrel de módulo @bridges que re-exporta desde './adapters' o un '*.adapter'.
+   * Recibe la ruta absoluta del fichero y su contenido en texto.
+   */
+  checkAdapterLeakInBarrel(
+    filePath: string,
+    content: string,
+    repoRoot: string,
+  ): Check002Violation[] {
+    const bridgesBarrelPattern = buildBridgesModuleBarrelPattern(repoRoot);
+    if (!bridgesBarrelPattern.test(filePath)) return [];
+
+    const violations: Check002Violation[] = [];
+    const lines = content.split('\n');
+
+    lines.forEach((lineText, idx) => {
+      const lineNum = idx + 1;
+      // Detecta "export ... from './adapters'" o su forma explícita './adapters/index.js'
+      // (el sub-barrel completo) — caso 3 prohibido. NO detecta './adapters/validate-redirect-uri'
+      // ni su forma explícita './adapters/validate-redirect-uri.js' (helper puro, caso 7 permitido).
+      if (/export\s+.*\s+from\s+['"]\.\/adapters(?:\/index\.js)?['"]/.test(lineText)) {
+        const specMatch = lineText.match(/from\s+['"]([^'"]+)['"]/);
+        const specifier = specMatch ? specMatch[1] : './adapters';
+        violations.push({
+          anchor: '002-A',
+          specifier,
+          line: lineNum,
+          message: `HR-BARRELS-002 (002-A): barrel de módulo @bridges re-exporta el sub-barrel adapters/ → mover wiring a adapters/index.ts`,
+        });
+        return;
+      }
+      // Detecta re-export de fichero *.adapter (p.ej. './adapters/x.adapter' o './adapters/x.adapter.js')
+      // Pero NO detecta helpers puros (sin sufijo .adapter, con o sin '.js' explícito)
+      if (/export\s+.*\s+from\s+['"][^'"]*\.adapter(?:\.js)?['"]/.test(lineText)) {
+        const specMatch = lineText.match(/from\s+['"]([^'"]+)['"]/);
+        const specifier = specMatch ? specMatch[1] : '*.adapter';
+        violations.push({
+          anchor: '002-A',
+          specifier,
+          line: lineNum,
+          message: `HR-BARRELS-002 (002-A): barrel de módulo @bridges re-exporta *.adapter → mover a adapters/index.ts`,
+        });
+      }
+    });
+
+    return violations;
+  },
+
+  /**
+   * 002-B: import de '@bridges/<bc>/<module>/adapters' desde fichero fuera de composition roots.
+   * Composition roots permitidos:
+   *   - @bridges/providers/[x].bridge.ts
+   *   - @bridges/bridges.module.ts
+   *   - @api/[cualquier-subruta]/[x].module.ts
+   */
+  checkAdaptersImportOutsideCompositionRoots(
+    importerAbsPath: string,
+    specifier: string,
+    repoRoot: string,
+  ): Check002Violation[] {
+    // Solo chequear cuando el specifier termina en '/adapters' o en su forma explícita
+    // '/adapters/index.js'.
+    if (!/^@bridges\/[^/]+\/[^/]+\/adapters(?:\/index\.js)?$/.test(specifier)) return [];
+
+    if (isCompositionRoot(importerAbsPath, repoRoot)) return [];
+
+    return [
+      {
+        anchor: '002-B',
+        specifier,
+        line: 0, // la línea la determina extractSpecifiers() en el orquestador
+        message: `HR-BARRELS-002 (002-B): import de ${specifier} fuera de composition roots → usar el barrel del módulo e inyectar por token`,
+      },
+    ];
+  },
+
+  /**
+   * 002-C: existencia de barrel de BC en @bridges → @bridges/<bc>/index.ts
+   * El fichero en sí ya es la violación; recibe su ruta absoluta.
+   *
+   * @param hasSubdirFn — predicado inyectable: dado el directorio del fichero, devuelve true
+   *   si contiene subdirectorios (indica que es un BC real con módulos). Por defecto usa
+   *   `fs.readdirSync` para verificar en disco. Los tests inyectan su propio predicado.
+   */
+  checkBcBarrelInBridges(
+    filePath: string,
+    repoRoot: string,
+    hasSubdirFn?: (dir: string) => boolean,
+  ): Check002Violation[] {
+    const bridgesSrc = path.join(repoRoot, 'backend', 'src', '@bridges') + path.sep;
+    if (!filePath.startsWith(bridgesSrc)) return [];
+    const relative = filePath.slice(bridgesSrc.length);
+    const segments = relative.split(path.sep);
+    // Es barrel de BC si la ruta tiene EXACTAMENTE 2 segmentos: <bc>/index.ts
+    if (segments.length !== 2 || segments[1] !== 'index.ts') return [];
+
+    const dir = path.dirname(filePath);
+    const checkHasSubdir = hasSubdirFn ?? defaultHasSubdir;
+
+    // Solo es una violación si el directorio contiene subdirectorios (es un BC real con módulos).
+    // 'providers/' contiene únicamente .bridge.ts; no es un BC → no se reporta.
+    if (!checkHasSubdir(dir)) return [];
+
+    return [
+      {
+        anchor: '002-C',
+        specifier: filePath,
+        line: 0,
+        message: `HR-BARRELS-002 (002-C): barrel de BC prohibido en @bridges → eliminar ${relative}; importar del módulo concreto @bridges/${segments[0]}/<module>`,
+      },
+    ];
+  },
+};
+
+/** Implementación real de hasSubdir: verifica si hay subdirectorios en el directorio dado. */
+function defaultHasSubdir(dir: string): boolean {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    return entries.some((e) => e.isDirectory());
+  } catch {
+    return false;
+  }
+}
+
+/** Patrón para detectar si un fichero es un index.ts de módulo en @bridges (no de sub-directorio). */
+function buildBridgesModuleBarrelPattern(repoRoot: string): RegExp {
+  const bridgesSrc = path.join(repoRoot, 'backend', 'src', '@bridges');
+  // Escapa los separadores para la regex
+  const escaped = bridgesSrc.replace(/[\\[\]^$.|?*+()]/g, '\\$&');
+  const sep = path.sep === '\\' ? '\\\\' : '/';
+  // Acepta @bridges/<bc>/<module>/index.ts (exactamente 3 segmentos más index.ts)
+  return new RegExp(`^${escaped}${sep}[^${sep}]+${sep}[^${sep}]+${sep}index\\.ts$`);
+}
+
+/** True si el fichero es un composition root de @bridges. */
+function isCompositionRoot(absPath: string, repoRoot: string): boolean {
+  const backendSrc = path.join(repoRoot, 'backend', 'src');
+
+  // @bridges/providers/*.bridge.ts
+  const bridgesProviders = path.join(backendSrc, '@bridges', 'providers') + path.sep;
+  if (absPath.startsWith(bridgesProviders) && absPath.endsWith('.bridge.ts')) return true;
+
+  // @bridges/bridges.module.ts (exacto)
+  const bridgesModule = path.join(backendSrc, '@bridges', 'bridges.module.ts');
+  if (absPath === bridgesModule) return true;
+
+  // @api/**/*.module.ts
+  const apiPrefix = path.join(backendSrc, '@api') + path.sep;
+  if (absPath.startsWith(apiPrefix) && absPath.endsWith('.module.ts')) return true;
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Utilidades internas del orquestador
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee el índice del catálogo y devuelve la severidad y estado de HR-BARRELS-004 (deep-path
+ * imports; sustituye a la derogada HR-BARRELS-003, T-45, que a su vez sustituyó a la derogada
+ * HR-BARRELS-001, task 5.5 de reduce-frontend-eager-payload) y HR-BARRELS-002 (sin cambios).
+ */
+interface RuleMeta {
+  severity: 'blocking' | 'informational';
+  state: string;
+}
+
+function loadRuleMeta(repoRoot: string): { rule004: RuleMeta; rule002: RuleMeta } {
+  const indexPath = path.join(repoRoot, 'cliter', 'harness-rules-index.json');
+  const raw = fs.readFileSync(indexPath, 'utf-8');
+  const index = JSON.parse(raw) as { byId: Record<string, { severity: string; state: string }> };
+
+  function toMeta(id: string): RuleMeta {
+    const entry = index.byId[id];
+    if (!entry) {
+      return { severity: 'informational', state: 'active' };
+    }
+    return {
+      severity: (entry.severity as RuleMeta['severity']) ?? 'informational',
+      state: entry.state ?? 'active',
+    };
+  }
+
+  return {
+    rule004: toMeta('HR-BARRELS-004'),
+    rule002: toMeta('HR-BARRELS-002'),
+  };
+}
+
+/** Lee los paths del tsconfig del backend. */
+function loadBackendPaths(repoRoot: string): TsconfigPaths {
+  const tsconfig = path.join(repoRoot, 'backend', 'tsconfig.json');
+  const raw = fs.readFileSync(tsconfig, 'utf-8');
+  const parsed = JSON.parse(raw) as {
+    compilerOptions?: { paths?: Record<string, string[]> };
+  };
+  const relativePaths = parsed.compilerOptions?.paths ?? {};
+
+  // Convierte los paths relativos del tsconfig a absolutos respecto a backend/
+  const backendDir = path.join(repoRoot, 'backend');
+  const result: TsconfigPaths = {};
+  for (const [pattern, targets] of Object.entries(relativePaths)) {
+    result[pattern] = targets.map((t) => path.join(backendDir, t));
+  }
+  return result;
+}
+
+/**
+ * Lee los paths del tsconfig del frontend (task 5.5 de reduce-frontend-eager-payload): incluye
+ * el alias exacto "@aurora" y, tras esa change, la tabla D1 de sub-barrels declarados
+ * (`@aurora/components`, `@aurora/modules/health`, …) que `resolveSpecifier` ya sabe casar.
+ */
+function loadFrontendPaths(repoRoot: string): TsconfigPaths {
+  const tsconfig = path.join(repoRoot, 'frontend', 'tsconfig.json');
+  const raw = fs.readFileSync(tsconfig, 'utf-8');
+  const parsed = JSON.parse(raw) as {
+    compilerOptions?: { paths?: Record<string, string[]> };
+  };
+  const relativePaths = parsed.compilerOptions?.paths ?? {};
+
+  // Convierte los paths relativos del tsconfig a absolutos respecto a frontend/
+  const frontendDir = path.join(repoRoot, 'frontend');
+  const result: TsconfigPaths = {};
+  for (const [pattern, targets] of Object.entries(relativePaths)) {
+    result[pattern] = targets.map((t) => path.join(frontendDir, t));
+  }
+  return result;
+}
+
+/** Recopila todos los ficheros .ts bajo las raíces gobernadas. */
+function collectGoverned(repoRoot: string): string[] {
+  const files: string[] = [];
+
+  const backendRoots = ['@api', '@app', '@bridges', '@aurora'].map((alias) =>
+    path.join(repoRoot, 'backend', 'src', alias),
+  );
+  const frontendRoot = path.join(
+    repoRoot,
+    'frontend',
+    'src',
+    'app',
+    'domains',
+    'admin',
+    'apps',
+  );
+
+  for (const root of [...backendRoots, frontendRoot]) {
+    if (fs.existsSync(root)) {
+      collectTsFiles(root, files);
+    }
+  }
+
+  return files;
+}
+
+function collectTsFiles(dir: string, accumulator: string[]): void {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === 'node_modules') continue;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectTsFiles(fullPath, accumulator);
+    } else if (entry.isFile() && entry.name.endsWith('.ts')) {
+      accumulator.push(fullPath);
+    }
+  }
+}
+
+/** Detecta si un fichero tiene el header @aurora-catalyst-generated en las primeras 3 líneas. */
+export function isGeneratedFile(content: string): boolean {
+  const firstLines = content.split('\n').slice(0, 3).join('\n');
+  return firstLines.includes('@aurora-catalyst-generated');
+}
+
+/**
+ * Calcula el exit code a partir de los findings y la configuración de reglas (D6/D7).
+ * Los findings de ficheros generados NUNCA contribuyen al exit code (D7).
+ */
+export function computeExitCode(
+  findings: Array<{ kind: '001' | '002'; isGenerated: boolean }>,
+  rule001Severity: 'blocking' | 'informational',
+  rule002Severity: 'blocking' | 'informational',
+  rule001Active: boolean,
+  rule002Active: boolean,
+): 0 | 1 | 2 {
+  let worstSeverity: 'clean' | 'informational' | 'blocking' = 'clean';
+
+  for (const f of findings) {
+    if (f.isGenerated) continue; // D7: generados no afectan exit code
+
+    if (f.kind === '001' && rule001Active) {
+      if (rule001Severity === 'blocking' && worstSeverity !== 'blocking') {
+        worstSeverity = 'blocking';
+      } else if (rule001Severity === 'informational' && worstSeverity === 'clean') {
+        worstSeverity = 'informational';
+      }
+    }
+
+    if (f.kind === '002' && rule002Active) {
+      if (rule002Severity === 'blocking' && worstSeverity !== 'blocking') {
+        worstSeverity = 'blocking';
+      } else if (rule002Severity === 'informational' && worstSeverity === 'clean') {
+        worstSeverity = 'informational';
+      }
+    }
+  }
+
+  return worstSeverity === 'blocking' ? 1 : worstSeverity === 'informational' ? 2 : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Tipos de findings internos del orquestador
+// ---------------------------------------------------------------------------
+
+interface Finding001 {
+  kind: '001';
+  file: string;
+  line: number;
+  specifier: string;
+  suggestedBarrel: string | undefined;
+}
+
+interface Finding002 {
+  kind: '002';
+  file: string;
+  anchor: '002-A' | '002-B' | '002-C';
+  line: number;
+  specifier: string;
+  message: string;
+}
+
+type Finding = Finding001 | Finding002;
+
+// ---------------------------------------------------------------------------
+// lintFile() — analiza un fichero y devuelve sus findings
+// ---------------------------------------------------------------------------
+
+export function lintFile(
+  absolutePath: string,
+  content: string,
+  tsconfigPaths: TsconfigPaths,
+  repoRoot: string,
+  existsFn?: (p: string) => boolean,
+  hasSubdirFn?: (dir: string) => boolean,
+): Finding[] {
+  const existsOnDisk = existsFn ?? ((p: string) => fs.existsSync(p));
+  const findings: Finding[] = [];
+
+  const specifiers = extractSpecifiers(content);
+
+  // Chequeo 002-C: ¿es este fichero un barrel de BC en @bridges?
+  const bcBarrelViolations = checkBarrels002.checkBcBarrelInBridges(absolutePath, repoRoot, hasSubdirFn);
+  for (const v of bcBarrelViolations) {
+    findings.push({
+      kind: '002',
+      file: absolutePath,
+      anchor: v.anchor,
+      line: v.line,
+      specifier: v.specifier,
+      message: v.message,
+    });
+  }
+
+  // Chequeo 002-A: si es un index.ts de módulo en @bridges, revisar su contenido
+  const adapterLeaks = checkBarrels002.checkAdapterLeakInBarrel(absolutePath, content, repoRoot);
+  for (const v of adapterLeaks) {
+    findings.push({
+      kind: '002',
+      file: absolutePath,
+      anchor: v.anchor,
+      line: v.line,
+      specifier: v.specifier,
+      message: v.message,
+    });
+  }
+
+  // Chequeos por especificador
+  for (const { specifier, line, kind: specifierKind } of specifiers) {
+    // Chequeo 002-B: import de .../adapters fuera de composition roots
+    const adapterImportViolations = checkBarrels002.checkAdaptersImportOutsideCompositionRoots(
+      absolutePath,
+      specifier,
+      repoRoot,
+    );
+    for (const v of adapterImportViolations) {
+      findings.push({
+        kind: '002',
+        file: absolutePath,
+        anchor: v.anchor,
+        line,
+        specifier: v.specifier,
+        message: v.message,
+      });
+    }
+
+    // Chequeo 001: classificación de import (T-45: 'dynamic' exime por FORMA, ver classifyImport)
+    const classification = classifyImport(
+      absolutePath,
+      specifier,
+      tsconfigPaths,
+      existsOnDisk,
+      repoRoot,
+      specifierKind === 'dynamic',
+    );
+
+    if (classification === 'violation') {
+      const resolved = resolveSpecifier(specifier, absolutePath, tsconfigPaths, existsOnDisk);
+      const suggested = resolved ? suggestBarrel(resolved, repoRoot) : undefined;
+      findings.push({
+        kind: '001',
+        file: absolutePath,
+        line,
+        specifier,
+        suggestedBarrel: suggested,
+      });
+    }
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// main() — orquestador de E/S
+// ---------------------------------------------------------------------------
+
+export function main(): void {
+  const repoRoot = process.cwd();
+  const args = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  const files = args.length > 0 ? args.map((a) => path.resolve(a)) : collectGoverned(repoRoot);
+
+  // rule004 gobierna los findings de kind '001' (deep-path): el tag interno 'kind: 001' identifica
+  // la FAMILIA de chequeo (heredada de HR-BARRELS-001), no el id de catálogo que la gobierna hoy.
+  const { rule004, rule002 } = loadRuleMeta(repoRoot);
+  const tsconfigPaths = { ...loadBackendPaths(repoRoot), ...loadFrontendPaths(repoRoot) };
+
+  // Apagar chequeos de reglas no activas
+  const check004Active = rule004.state === 'active';
+  const check002Active = rule002.state === 'active';
+
+  interface FileFindings {
+    file: string;
+    generated: boolean;
+    findings001: Finding001[];
+    findings002: Finding002[];
+  }
+
+  const allFileFindings: FileFindings[] = [];
+
+  for (const file of files) {
+    if (!file.endsWith('.ts')) continue;
+
+    let content: string;
+    try {
+      content = fs.readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const generated = isGeneratedFile(content);
+    const rawFindings = lintFile(file, content, tsconfigPaths, repoRoot);
+
+    const findings001 = check004Active
+      ? (rawFindings.filter((f) => f.kind === '001') as Finding001[])
+      : [];
+    const findings002 = check002Active
+      ? (rawFindings.filter((f) => f.kind === '002') as Finding002[])
+      : [];
+
+    if (findings001.length > 0 || findings002.length > 0) {
+      allFileFindings.push({ file, generated, findings001, findings002 });
+    }
+  }
+
+  // Separa generados de manuales
+  const manualFindings = allFileFindings.filter((f) => !f.generated);
+  const generatedFindings = allFileFindings.filter((f) => f.generated);
+
+  // Determina el exit code basado en severidad (D6) — única fuente de verdad:
+  // computeExitCode (cubierta por la suite), en vez de duplicar la regla inline.
+  const exitCode = computeExitCode(
+    manualFindings.flatMap((ff) => [
+      ...ff.findings001.map(() => ({ kind: '001' as const, isGenerated: false })),
+      ...ff.findings002.map(() => ({ kind: '002' as const, isGenerated: false })),
+    ]),
+    rule004.severity,
+    rule002.severity,
+    check004Active,
+    check002Active,
+  );
+
+  // Formato de salida
+  if (manualFindings.length === 0 && generatedFindings.length === 0) {
+    console.log('✔ hr:lint-barrels — sin violaciones\n');
+  } else {
+    if (manualFindings.length > 0) {
+      console.log('\n=== HR-BARRELS: Violaciones ===\n');
+      for (const ff of manualFindings) {
+        const relFile = path.relative(repoRoot, ff.file);
+        for (const f of ff.findings001) {
+          const barrel = f.suggestedBarrel ? ` → barrel sugerido: ${f.suggestedBarrel}` : '';
+          console.log(`  HR-BARRELS-004  ${relFile}:${f.line}  ${f.specifier}${barrel}`);
+        }
+        for (const f of ff.findings002) {
+          const lineStr = f.line > 0 ? `:${f.line}` : '';
+          console.log(`  HR-BARRELS-002  ${relFile}${lineStr}  ${f.message}`);
+        }
+      }
+    }
+
+    if (generatedFindings.length > 0) {
+      console.log('\n=== HR-BARRELS: Ficheros generados (informativo — fix pertenece al CLI) ===\n');
+      for (const ff of generatedFindings) {
+        const relFile = path.relative(repoRoot, ff.file);
+        for (const f of ff.findings001) {
+          const barrel = f.suggestedBarrel ? ` → barrel sugerido: ${f.suggestedBarrel}` : '';
+          console.log(`  [generado] HR-BARRELS-004  ${relFile}:${f.line}  ${f.specifier}${barrel}`);
+        }
+        for (const f of ff.findings002) {
+          const lineStr = f.line > 0 ? `:${f.line}` : '';
+          console.log(`  [generado] HR-BARRELS-002  ${relFile}${lineStr}  ${f.message}`);
+        }
+      }
+    }
+  }
+
+  // Exit code (D6): blocking → 1, informational → 2, limpio → 0; los generados
+  // NO contribuyen (D7) — calculado arriba por computeExitCode sobre los manuales.
+  process.exit(exitCode);
+}
+
+// Entry point: solo se ejecuta cuando este fichero es el script principal invocado.
+// La comprobación usa la ruta absoluta resuelta para evitar que un importador cuyo
+// nombre termina en 'lint-barrels.ts' (p.ej. el hook PostToolUse) dispare main().
+// tsx opera en modo CJS-compatible: __filename está disponible y da la ruta absoluta
+// del FICHERO ACTUAL sin importar quién lo importa.
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(__filename)) {
+  main();
+}