165 lines
4.6 KiB
Markdown
165 lines
4.6 KiB
Markdown
# ABE — Core Interfaces Specification
|
|
|
|
## Regla fundamental
|
|
`src/core/` solo puede importar desde este documento.
|
|
`src/plugins/` implementa estas interfaces, nunca al revés.
|
|
|
|
---
|
|
|
|
## IState
|
|
|
|
Representa un estado único de la aplicación explorada.
|
|
```typescript
|
|
interface IState {
|
|
id: string; // hash SHA1 del snapshot DOM + URL
|
|
url: string; // URL completa en este estado
|
|
title: string; // document.title
|
|
timestamp: number; // Date.now() cuando se capturó
|
|
domSnapshot: string; // outerHTML del body serializado
|
|
visitCount: number; // cuántas veces se ha visitado este estado
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## IAction
|
|
|
|
Representa una acción que el agente puede ejecutar.
|
|
```typescript
|
|
interface IAction {
|
|
id: string; // uuid v4 generado al crear la acción
|
|
type: 'click' | 'fill' | 'navigate' | 'select' | 'submit';
|
|
selector?: string; // CSS selector del elemento (si aplica)
|
|
value?: string; // valor a introducir (para fill/select)
|
|
url?: string; // destino (solo para navigate)
|
|
timestamp: number; // cuando se ejecutó
|
|
seed: number; // semilla usada para selección aleatoria
|
|
stateId: string; // ID del estado desde el que se ejecutó
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## IObservation
|
|
|
|
Lo que el agente observa DESPUÉS de ejecutar una acción.
|
|
```typescript
|
|
interface IObservation {
|
|
id: string; // uuid v4
|
|
actionId: string; // acción que provocó esta observación
|
|
newStateId: string; // ID del nuevo estado resultante
|
|
httpResponses: IHttpResponse[]; // todas las requests durante la acción
|
|
consoleErrors: string[]; // mensajes de console.error capturados
|
|
jsExceptions: string[]; // excepciones JS no capturadas
|
|
timestamp: number;
|
|
}
|
|
|
|
interface IHttpResponse {
|
|
url: string;
|
|
status: number;
|
|
method: string;
|
|
durationMs: number;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## IAnomaly
|
|
|
|
Una desviación detectada del comportamiento esperado.
|
|
```typescript
|
|
interface IAnomaly {
|
|
id: string; // uuid v4
|
|
type: AnomalyType;
|
|
severity: 'low' | 'medium' | 'high' | 'critical';
|
|
observationId: string; // observación que la provocó
|
|
actionTrace: IAction[]; // secuencia exacta de acciones que llevaron aquí
|
|
description: string; // texto legible explicando qué pasó
|
|
evidence: IAnomalyEvidence;
|
|
timestamp: number;
|
|
}
|
|
|
|
type AnomalyType =
|
|
| 'http_error' // respuesta HTTP 4xx o 5xx
|
|
| 'js_exception' // excepción JavaScript no capturada
|
|
| 'console_error' // console.error detectado
|
|
| 'navigation_fail' // navegación no completada
|
|
| 'element_missing' // elemento esperado desaparece
|
|
| 'timeout'; // acción excede tiempo límite
|
|
|
|
interface IAnomalyEvidence {
|
|
screenshotPath?: string; // ruta relativa al screenshot
|
|
domSnapshotPath?: string; // ruta relativa al DOM serializado
|
|
httpLog?: IHttpResponse[]; // requests relevantes
|
|
rawErrors?: string[]; // errores textuales originales
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## IInteractionAgent (plugin interface)
|
|
|
|
Lo que cualquier agente de interacción debe implementar.
|
|
```typescript
|
|
interface IInteractionAgent {
|
|
launch(url: string): Promise<void>;
|
|
close(): Promise<void>;
|
|
discoverActions(state: IState): Promise<IAction[]>;
|
|
executeAction(action: IAction): Promise<IObservation>;
|
|
captureState(): Promise<IState>;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## ICollector (plugin interface)
|
|
|
|
Lo que cualquier colector de contexto debe implementar.
|
|
```typescript
|
|
interface ICollector {
|
|
name: string;
|
|
collect(anomaly: IAnomaly, agent: IInteractionAgent): Promise<IAnomalyEvidence>;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## IReproducer
|
|
|
|
Genera un script de replay a partir de una traza de acciones.
|
|
```typescript
|
|
interface IReproducer {
|
|
serialize(trace: IAction[]): string; // JSON serializado
|
|
deserialize(raw: string): IAction[]; // reconstruye la traza
|
|
generateScript(trace: IAction[]): string; // script Playwright ejecutable
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## IExporter (plugin interface)
|
|
|
|
Transforma una anomalía en un reporte consumible.
|
|
```typescript
|
|
interface IExporter {
|
|
format: 'markdown' | 'json';
|
|
export(anomaly: IAnomaly, outputDir: string): Promise<string>; // retorna la ruta del archivo generado
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## StateGraph
|
|
|
|
No es una interfaz pero su contrato debe ser explícito.
|
|
```typescript
|
|
class StateGraph {
|
|
addState(state: IState): void;
|
|
hasState(stateId: string): boolean;
|
|
recordTransition(fromId: string, action: IAction, toId: string): void;
|
|
getUnvisited(): IState[]; // estados con visitCount === 0
|
|
getNextToExplore(): IState | null; // heurística BFS por defecto
|
|
toJSON(): object; // serializable para logs
|
|
}
|
|
```
|