crawlex/script/mod.rs
1//! ScriptSpec v1 — unified AST for declarative crawl scripts.
2//!
3//! Playwright/Puppeteer-inspired contract that lets a single file describe
4//! everything a render job should do end-to-end: selectors, steps,
5//! captures, assertions, exports. JSON, YAML and Lua all parse to this
6//! same AST so the executor is backend-agnostic.
7//!
8//! ## Example (JSON)
9//!
10//! ```json
11//! {
12//! "version": 1,
13//! "defaults": { "timeout_ms": 10000 },
14//! "selectors": {
15//! "email": "role=textbox[name=\"Email\"]",
16//! "login": "role=button[name=\"Sign in\"]"
17//! },
18//! "steps": [
19//! { "goto": "https://example.com/login" },
20//! { "type": { "locator": "@email", "text": "a@b.c" } },
21//! { "click": { "locator": "@login" } },
22//! { "wait_for": { "locator": "role=heading[name=\"Dashboard\"]" } }
23//! ],
24//! "captures": [
25//! { "screenshot": { "mode": "full_page", "name": "dashboard" } },
26//! { "snapshot": { "kind": "post_js_html" } }
27//! ],
28//! "assertions": [
29//! { "contains": { "locator": "body", "text": "Welcome" } }
30//! ],
31//! "exports": {
32//! "title": "text=h1",
33//! "items": { "locator": "@cards", "as": "list" }
34//! }
35//! }
36//! ```
37//!
38//! Selector names prefixed with `@` reference the `selectors` map; bare
39//! selectors use the full selector DSL (see `render::selector`).
40//!
41//! Design notes:
42//! * `defaults.timeout_ms` sets the fallback actionability timeout per
43//! step; individual steps can override.
44//! * `captures` always emit `artifact.saved` NDJSON events with a
45//! `stage` matching the capture kind.
46//! * `assertions` are checked in order; a failure emits
47//! `job.failed` with `why=assertion:<name>` and halts the script.
48//! * `exports` populate the `ExtractCompleted` event payload.
49
50pub mod executor;
51#[cfg(feature = "cdp-backend")]
52pub mod legacy;
53#[cfg(feature = "cdp-backend")]
54pub mod runner;
55pub mod spec;
56
57pub use executor::{plan, Plan, PlanError, ResolvedExport, ResolvedStep};
58#[cfg(feature = "cdp-backend")]
59pub use legacy::actions_to_script_spec;
60#[cfg(feature = "cdp-backend")]
61pub use runner::{ArtifactRef, RunOutcome, ScriptRunner, StepOutcome};
62pub use spec::*;