Extractores

Un extractor es un componente reutilizable, identificado con un nombre estable, que obtiene un tipo concreto de datos. En Guida 0.9, los descriptores residen en el espacio de trabajo, Guida los carga en un catálogo consultable y el equipo puede validarlos, certificarlos y comparar sus resultados sin depender de listas informales.

Guida Complete y Guida Node ejecutan los extractores. Guida Control ofrece una vista remota de los mismos contratos mediante Remote Ops, pero no mantiene un segundo catálogo.

Descriptor e implementación

El descriptor es el contrato público. Identifica la implementación, la fuente, el flujo de trabajo, la cola, la entrada predeterminada, los dominios de destino, el contrato de salida y las pruebas exigidas. La implementación sigue siendo código normal del espacio de trabajo.

{
  "$schema": "../../../extractors.schema.json",
  "id": "careers.example.jobs",
  "profile": "web.discovery.browser",
  "label": "Example engineering jobs",
  "domain": "careers",
  "workflowName": "careers-example",
  "queueName": "careers_example",
  "implementation": {
    "module": "lib/careers-example-worker.js",
    "export": "discoverExampleJobs",
    "language": "javascript"
  },
  "source": { "kind": "web", "url": "https://example.com/careers" },
  "targetDomains": ["example.com"],
  "input": {
    "defaultUrl": "https://example.com/careers",
    "defaultCompanyName": "Example",
    "defaultSlug": "example"
  },
  "evidence": {
    "requiresPageLoaded": true,
    "requiresResultEvidence": true,
    "allowQualifiedEmpty": true
  }
}

Un archivo raíz extractors.json puede incluir descriptores, elegir perfiles comunes y dividir un catálogo grande en particiones deterministas. Cada entrada conserva su identidad y su ruta de origen.

Contratos antes de ejecutar

La validación detecta descriptores mal formados, ID duplicados, implementaciones ausentes, perfiles sin resolver, reglas de dominio no válidas y contratos de entrada o salida incompatibles. Las comprobaciones de compatibilidad hacen explícito el límite entre un extractor y sus consumidores.

La API de scripting proporciona consultas síncronas y de solo lectura mediante g.extractors.list(), g.extractors.get() y g.extractors.validate(). Los clientes remotos usan workspace.extractors.* y workspace.extractors.contracts.*.

Certificación con pruebas

La certificación es una verificación operativa acotada, no un distintivo permanente. Quick revisa un conjunto pequeño para dar una respuesta rápida; Coverage amplía la revisión dentro de límites declarados. Un resultado vacío solo es aceptable con pruebas de carga y con permiso explícito en el descriptor. Las pruebas de selectores deben observarse de verdad. Guida registra la integridad y cualquier truncamiento para no presentar una revisión parcial como si fuera completa.

Planifica primero con workspace.extractors.certification.plan. El plan separa lo ejecutable de lo bloqueado y muestra los límites. El inicio, la cancelación y la exportación de pruebas mantienen las reglas y confirmaciones locales de Guida.

Guida separa el resultado más reciente de su historial. Se pueden consultar ejecuciones, resultados por extractor, estadísticas, anomalías, cambios de contrato y pruebas exportadas. La política de conservación se define en el espacio de trabajo y los datos operativos se guardan en operations.db.

El catálogo y las superficies operativas se han validado con 5.000 extractores en pruebas deterministas sobre un solo host. No es una promesa de 5.000 sesiones de navegador simultáneas ni una cifra de capacidad Enterprise.

Una pipeline semántica conecta la salida contratada con validadores, mapeadores y destinos. Las pipelines generadas usan asociaciones explícitas como $extractor.id; Guida no deduce significados a partir de nombres de archivos o carpetas.