alef_core/config/
e2e.rs

1//! E2E test generation configuration types.
2
3use serde::{Deserialize, Serialize};
4use std::collections::{HashMap, HashSet};
5
6/// Controls whether generated e2e test projects reference the package under
7/// test via a local path (for development) or a registry version string
8/// (for standalone `test_apps` that consumers can run without the monorepo).
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
10#[serde(rename_all = "lowercase")]
11pub enum DependencyMode {
12    /// Local path dependency (default) — used during normal e2e development.
13    #[default]
14    Local,
15    /// Registry dependency — generates standalone test apps that pull the
16    /// package from its published registry (PyPI, npm, crates.io, etc.).
17    Registry,
18}
19
20/// Configuration for registry-mode e2e generation (`alef e2e generate --registry`).
21#[derive(Debug, Clone, Serialize, Deserialize)]
22pub struct RegistryConfig {
23    /// Output directory for registry-mode test apps (default: "test_apps").
24    #[serde(default = "default_test_apps_dir")]
25    pub output: String,
26    /// Per-language package overrides used only in registry mode.
27    /// Merged on top of the base `[e2e.packages]` entries.
28    #[serde(default)]
29    pub packages: HashMap<String, PackageRef>,
30    /// When non-empty, only fixture categories in this list are included in
31    /// registry-mode generation (useful for shipping a curated subset).
32    #[serde(default)]
33    pub categories: Vec<String>,
34    /// GitHub repository URL for downloading prebuilt artifacts (e.g., FFI
35    /// shared libraries) from GitHub Releases.
36    ///
37    /// Falls back to `[scaffold] repository` when not set, then to
38    /// `https://github.com/kreuzberg-dev/{crate.name}`.
39    #[serde(default)]
40    pub github_repo: Option<String>,
41}
42
43impl Default for RegistryConfig {
44    fn default() -> Self {
45        Self {
46            output: default_test_apps_dir(),
47            packages: HashMap::new(),
48            categories: Vec::new(),
49            github_repo: None,
50        }
51    }
52}
53
54fn default_test_apps_dir() -> String {
55    "test_apps".to_string()
56}
57
58/// Root e2e configuration from `[e2e]` section of alef.toml.
59#[derive(Debug, Clone, Serialize, Deserialize, Default)]
60pub struct E2eConfig {
61    /// Directory containing fixture JSON files (default: "fixtures").
62    #[serde(default = "default_fixtures_dir")]
63    pub fixtures: String,
64    /// Output directory for generated e2e test projects (default: "e2e").
65    #[serde(default = "default_output_dir")]
66    pub output: String,
67    /// Languages to generate e2e tests for. Defaults to top-level `languages` list.
68    #[serde(default)]
69    pub languages: Vec<String>,
70    /// Default function call configuration.
71    pub call: CallConfig,
72    /// Named additional call configurations for multi-function testing.
73    /// Fixtures reference these via the `call` field, e.g. `"call": "embed"`.
74    #[serde(default)]
75    pub calls: HashMap<String, CallConfig>,
76    /// Per-language package reference overrides.
77    #[serde(default)]
78    pub packages: HashMap<String, PackageRef>,
79    /// Per-language formatter commands.
80    #[serde(default)]
81    pub format: HashMap<String, String>,
82    /// Field path aliases: maps fixture field paths to actual API struct paths.
83    /// E.g., "metadata.title" -> "metadata.document.title"
84    /// Supports struct access (foo.bar), map access (foo[key]), direct fields.
85    #[serde(default)]
86    pub fields: HashMap<String, String>,
87    /// Fields that are Optional/nullable in the return type.
88    /// Rust generators use .as_deref().unwrap_or("") for strings, .is_some() for structs.
89    #[serde(default)]
90    pub fields_optional: HashSet<String>,
91    /// Fields that are arrays/Vecs on the result type.
92    /// When a fixture path like `json_ld.name` traverses an array field, the
93    /// accessor adds `[0]` (or language equivalent) to index into the first element.
94    #[serde(default)]
95    pub fields_array: HashSet<String>,
96    /// Known top-level fields on the result type.
97    ///
98    /// When non-empty, assertions whose resolved field path starts with a
99    /// segment that is NOT in this set are emitted as comments (skipped)
100    /// instead of executable assertions.  This prevents broken assertions
101    /// when fixtures reference fields from a different operation (e.g.,
102    /// `batch.completed_count` on a `ScrapeResult`).
103    #[serde(default)]
104    pub result_fields: HashSet<String>,
105    /// C FFI accessor type chain: maps `"{parent_snake_type}.{field}"` to the
106    /// PascalCase return type name (without prefix).
107    ///
108    /// Used by the C e2e generator to emit chained FFI accessor calls for
109    /// nested field paths. The root type is always `conversion_result`.
110    ///
111    /// Example:
112    /// ```toml
113    /// [e2e.fields_c_types]
114    /// "conversion_result.metadata" = "HtmlMetadata"
115    /// "html_metadata.document" = "DocumentMetadata"
116    /// ```
117    #[serde(default)]
118    pub fields_c_types: HashMap<String, String>,
119    /// Fields whose resolved type is an enum in the generated bindings.
120    ///
121    /// When a `contains` / `contains_all` / etc. assertion targets one of these
122    /// fields, language generators that cannot call `.contains()` directly on an
123    /// enum (e.g., Java) will emit a string-conversion call first.  For Java,
124    /// the generated assertion calls `.getValue()` on the enum — the `@JsonValue`
125    /// method that all alef-generated Java enums expose — to obtain the lowercase
126    /// serde string before performing the string comparison.
127    ///
128    /// Both the raw fixture field path (before alias resolution) and the resolved
129    /// path (after alias resolution via `[e2e.fields]`) are accepted, so you can
130    /// use either form:
131    ///
132    /// ```toml
133    /// # Raw fixture field:
134    /// fields_enum = ["links[].link_type", "assets[].category"]
135    /// # …or the resolved (aliased) field name:
136    /// fields_enum = ["links[].link_type", "assets[].asset_category"]
137    /// ```
138    #[serde(default)]
139    pub fields_enum: HashSet<String>,
140    /// Dependency mode: `Local` (default) or `Registry`.
141    /// Set at runtime via `--registry` CLI flag; not serialized from TOML.
142    #[serde(skip)]
143    pub dep_mode: DependencyMode,
144    /// Registry-mode configuration from `[e2e.registry]`.
145    #[serde(default)]
146    pub registry: RegistryConfig,
147}
148
149impl E2eConfig {
150    /// Resolve the call config for a fixture. Uses the named call if specified,
151    /// otherwise falls back to the default `[e2e.call]`.
152    pub fn resolve_call(&self, call_name: Option<&str>) -> &CallConfig {
153        match call_name {
154            Some(name) => self.calls.get(name).unwrap_or(&self.call),
155            None => &self.call,
156        }
157    }
158
159    /// Resolve the effective package reference for a language.
160    ///
161    /// In registry mode, entries from `[e2e.registry.packages]` are merged on
162    /// top of the base `[e2e.packages]` — registry overrides win for any field
163    /// that is `Some`.
164    pub fn resolve_package(&self, lang: &str) -> Option<PackageRef> {
165        let base = self.packages.get(lang);
166        if self.dep_mode == DependencyMode::Registry {
167            let reg = self.registry.packages.get(lang);
168            match (base, reg) {
169                (Some(b), Some(r)) => Some(PackageRef {
170                    name: r.name.clone().or_else(|| b.name.clone()),
171                    path: r.path.clone().or_else(|| b.path.clone()),
172                    module: r.module.clone().or_else(|| b.module.clone()),
173                    version: r.version.clone().or_else(|| b.version.clone()),
174                }),
175                (None, Some(r)) => Some(r.clone()),
176                (Some(b), None) => Some(b.clone()),
177                (None, None) => None,
178            }
179        } else {
180            base.cloned()
181        }
182    }
183
184    /// Return the effective output directory: `registry.output` in registry
185    /// mode, `output` otherwise.
186    pub fn effective_output(&self) -> &str {
187        if self.dep_mode == DependencyMode::Registry {
188            &self.registry.output
189        } else {
190            &self.output
191        }
192    }
193}
194
195fn default_fixtures_dir() -> String {
196    "fixtures".to_string()
197}
198
199fn default_output_dir() -> String {
200    "e2e".to_string()
201}
202
203/// Configuration for the function call in each test.
204#[derive(Debug, Clone, Serialize, Deserialize, Default)]
205pub struct CallConfig {
206    /// The function name (alef applies language naming conventions).
207    #[serde(default)]
208    pub function: String,
209    /// The module/package where the function lives.
210    #[serde(default)]
211    pub module: String,
212    /// Variable name for the return value (default: "result").
213    #[serde(default = "default_result_var")]
214    pub result_var: String,
215    /// Whether the function is async.
216    #[serde(default)]
217    pub r#async: bool,
218    /// How fixture `input` fields map to function arguments.
219    #[serde(default)]
220    pub args: Vec<ArgMapping>,
221    /// Per-language overrides for module/function/etc.
222    #[serde(default)]
223    pub overrides: HashMap<String, CallOverride>,
224}
225
226fn default_result_var() -> String {
227    "result".to_string()
228}
229
230/// Maps a fixture input field to a function argument.
231#[derive(Debug, Clone, Serialize, Deserialize)]
232pub struct ArgMapping {
233    /// Argument name in the function signature.
234    pub name: String,
235    /// JSON field path in the fixture's `input` object.
236    pub field: String,
237    /// Type hint for code generation.
238    #[serde(rename = "type", default = "default_arg_type")]
239    pub arg_type: String,
240    /// Whether this argument is optional.
241    #[serde(default)]
242    pub optional: bool,
243}
244
245fn default_arg_type() -> String {
246    "string".to_string()
247}
248
249/// Per-language override for function call configuration.
250#[derive(Debug, Clone, Serialize, Deserialize, Default)]
251pub struct CallOverride {
252    /// Override the module/import path.
253    #[serde(default)]
254    pub module: Option<String>,
255    /// Override the function name.
256    #[serde(default)]
257    pub function: Option<String>,
258    /// Override the crate name (Rust only).
259    #[serde(default)]
260    pub crate_name: Option<String>,
261    /// Override the class name (Java/C# only).
262    #[serde(default)]
263    pub class: Option<String>,
264    /// Import alias (Go only, e.g., `htmd`).
265    #[serde(default)]
266    pub alias: Option<String>,
267    /// C header file name (C only).
268    #[serde(default)]
269    pub header: Option<String>,
270    /// FFI symbol prefix (C only).
271    #[serde(default)]
272    pub prefix: Option<String>,
273    /// For json_object args: the constructor to use instead of raw dict/object.
274    /// E.g., "ConversionOptions" — generates `ConversionOptions(**options)` in Python,
275    /// `new ConversionOptions(options)` in TypeScript.
276    #[serde(default)]
277    pub options_type: Option<String>,
278    /// How to pass json_object args: "kwargs" (default), "dict", or "json".
279    ///
280    /// - `"kwargs"`: construct `OptionsType(key=val, ...)` (requires `options_type`).
281    /// - `"dict"`: pass as a plain dict/object literal `{"key": "val"}`.
282    /// - `"json"`: pass via `json.loads('...')` / `JSON.parse('...')`.
283    #[serde(default)]
284    pub options_via: Option<String>,
285    /// Maps fixture option field names to their enum type names.
286    /// E.g., `{"headingStyle": "HeadingStyle", "codeBlockStyle": "CodeBlockStyle"}`.
287    /// The generator imports these types and maps string values to enum constants.
288    #[serde(default)]
289    pub enum_fields: HashMap<String, String>,
290    /// Module to import enum types from (if different from the main module).
291    /// E.g., "html_to_markdown._html_to_markdown" for PyO3 native enums.
292    #[serde(default)]
293    pub enum_module: Option<String>,
294    /// When `true`, the function returns a simple type (e.g., `String`) rather
295    /// than a struct.  Generators that would normally emit `result.content`
296    /// (or equivalent field access) will use the result variable directly.
297    #[serde(default)]
298    pub result_is_simple: bool,
299    /// Maps handle config field names to their Python type constructor names.
300    ///
301    /// When the handle config object contains a nested dict-valued field, the
302    /// generator will wrap it in the specified type using keyword arguments.
303    /// E.g., `{"browser": "BrowserConfig"}` generates `BrowserConfig(mode="auto")`
304    /// instead of `{"mode": "auto"}`.
305    #[serde(default)]
306    pub handle_nested_types: HashMap<String, String>,
307    /// Handle config fields whose type constructor takes a single dict argument
308    /// instead of keyword arguments.
309    ///
310    /// E.g., `["auth"]` means `AuthConfig({"type": "basic", ...})` instead of
311    /// `AuthConfig(type="basic", ...)`.
312    #[serde(default)]
313    pub handle_dict_types: HashSet<String>,
314    /// Elixir struct module name for the handle config argument.
315    ///
316    /// When set, the generated Elixir handle config uses struct literal syntax
317    /// (`%Module.StructType{key: val}`) instead of a plain string-keyed map.
318    /// Rustler `NifStruct` requires a proper Elixir struct — plain maps are rejected.
319    ///
320    /// E.g., `"CrawlConfig"` generates `%Kreuzcrawl.CrawlConfig{download_assets: true}`.
321    #[serde(default)]
322    pub handle_struct_type: Option<String>,
323    /// Handle config fields whose list values are Elixir atoms (Rustler NifUnitEnum).
324    ///
325    /// When a config field is a `Vec<EnumType>` in Rust, the Elixir side must pass
326    /// a list of atoms (e.g., `[:image, :document]`) not strings (`["image"]`).
327    /// List the field names here so the generator emits atom literals instead of strings.
328    ///
329    /// E.g., `["asset_types"]` generates `asset_types: [:image]` instead of `["image"]`.
330    #[serde(default)]
331    pub handle_atom_list_fields: HashSet<String>,
332    /// Static CLI arguments appended to every invocation (brew/CLI generator only).
333    ///
334    /// E.g., `["--format", "json"]` appends `--format json` to every CLI call.
335    #[serde(default)]
336    pub cli_args: Vec<String>,
337    /// Maps fixture config field names to CLI flag names (brew/CLI generator only).
338    ///
339    /// E.g., `{"output_format": "--format"}` generates `--format <value>` from
340    /// the fixture's `output_format` input field.
341    #[serde(default)]
342    pub cli_flags: HashMap<String, String>,
343}
344
345/// Per-language package reference configuration.
346#[derive(Debug, Clone, Serialize, Deserialize, Default)]
347pub struct PackageRef {
348    /// Package/crate/gem/module name.
349    #[serde(default)]
350    pub name: Option<String>,
351    /// Relative path from e2e/{lang}/ to the package.
352    #[serde(default)]
353    pub path: Option<String>,
354    /// Go module path.
355    #[serde(default)]
356    pub module: Option<String>,
357    /// Package version (e.g., for go.mod require directives).
358    #[serde(default)]
359    pub version: Option<String>,
360}
alef_core/config/e2e.rs

alef_core/config/
e2e.rs
