Autonomous-Bug-Explorer/.ralph/specs/legacy/project-structure.md

ABE — Project Structure Specification

Árbol completo de archivos a crear

abe/
├── src/
│   ├── core/
│   │   ├── interfaces.ts        ← TODAS las interfaces (IState, IAction, etc.)
│   │   ├── StateGraph.ts        ← implementación del grafo de estados
│   │   ├── ExplorationEngine.ts ← loop principal de exploración
│   │   └── AnomalyDetector.ts   ← reglas heurísticas de detección
│   ├── plugins/
│   │   ├── agents/
│   │   │   └── PlaywrightAgent.ts   ← implementa IInteractionAgent
│   │   ├── collectors/
│   │   │   ├── ScreenshotCollector.ts
│   │   │   ├── NetworkCollector.ts
│   │   │   └── DOMSnapshotCollector.ts
│   │   ├── exporters/
│   │   │   ├── MarkdownExporter.ts
│   │   │   └── JSONExporter.ts
│   │   └── reproducers/
│   │       └── PlaywrightReproducer.ts
│   └── index.ts                 ← punto de entrada, conecta todo
│
├── tests/
│   ├── core/
│   │   ├── StateGraph.test.ts
│   │   ├── ExplorationEngine.test.ts
│   │   └── AnomalyDetector.test.ts
│   └── plugins/
│       ├── agents/
│       │   └── PlaywrightAgent.test.ts
│       └── exporters/
│           ├── MarkdownExporter.test.ts
│           └── JSONExporter.test.ts
│
├── reports/                     ← generado en runtime, ignorado por git
├── logs/                        ← generado en runtime, ignorado por git
│
├── package.json
├── tsconfig.json
├── jest.config.ts
└── CLAUDE.md

---

Reglas de importación — MUY IMPORTANTE

✅ PERMITIDO:
   src/core/ExplorationEngine.ts  →  importa de  src/core/interfaces.ts
   src/plugins/agents/PlaywrightAgent.ts  →  importa de  src/core/interfaces.ts
   src/index.ts  →  importa de  src/core/ Y src/plugins/

❌ PROHIBIDO:
   src/core/ExplorationEngine.ts  →  importa de  src/plugins/  (rompe el desacoplamiento)
   src/plugins/agents/A.ts  →  importa de  src/plugins/exporters/B.ts  (plugins no se conocen entre sí)

---

Cómo se conecta todo en src/index.ts

El archivo de entrada debe seguir este patrón:

// src/index.ts
import { ExplorationEngine } from './core/ExplorationEngine';
import { StateGraph } from './core/StateGraph';
import { PlaywrightAgent } from './plugins/agents/PlaywrightAgent';
import { ScreenshotCollector } from './plugins/collectors/ScreenshotCollector';
import { NetworkCollector } from './plugins/collectors/NetworkCollector';
import { DOMSnapshotCollector } from './plugins/collectors/DOMSnapshotCollector';
import { JSONExporter } from './plugins/exporters/JSONExporter';
import { MarkdownExporter } from './plugins/exporters/MarkdownExporter';
import { PlaywrightReproducer } from './plugins/reproducers/PlaywrightReproducer';

const graph = new StateGraph();
const agent = new PlaywrightAgent();
const collectors = [new ScreenshotCollector(), new NetworkCollector(), new DOMSnapshotCollector()];
const exporters = [new JSONExporter(), new MarkdownExporter()];
const reproducer = new PlaywrightReproducer();

const engine = new ExplorationEngine({ graph, agent, collectors, exporters, reproducer });

engine.run({ url: process.argv[2] || 'http://localhost:3000', seed: 42 });

---

package.json — scripts obligatorios

{
  "name": "abe",
  "version": "0.1.0",
  "scripts": {
    "build": "tsc",
    "test": "jest",
    "typecheck": "tsc --noEmit",
    "lint": "eslint src/ tests/",
    "explore": "ts-node src/index.ts",
    "replay": "ts-node src/replay.ts"
  }
}

---

tsconfig.json — configuración base

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "tests"]
}

---

jest.config.ts — configuración base

export default {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/tests'],
  testMatch: ['**/*.test.ts'],
};