Crate alba_core 

Core domain model for beams and Beamfiles.

alba-core takes the AST alba-syntax produces and evaluates it into the typed Project model the execution engine schedules: resolving let bindings and {expr} interpolation, checking the small type system (strings and booleans), and running the built-in env()/glob() functions. See render_template and eval_expr for the load-time-vs-schedule-time rendering split between a beam’s fields.

Multi-file loading (import "path" as alias, namespaced beam ids) is load_project’s job, which also validates the resulting dependency graph (unknown needs targets, needs-cycles) via validate_graph before returning it. execution_subgraph extracts the transitive closure of a target beam, for whichever engine schedules and runs it. git wraps the git CLI, the only place in the workspace that spawns it.

Modules

git

The one place Alba talks to git: a thin wrapper over the git CLI.

Structs

Beam

A single beam: the unit of work produced by evaluating a beam { ... } declaration.

BeamId

A fully namespaced beam identifier, e.g. "api:build" for a beam imported under the alias api, "api:db:migrate" for one imported transitively through a chain of aliases, or "build" for a local one.

CoreError

An error produced while evaluating a Beamfile: an unknown variable, a type mismatch, an unresolvable built-in call, and so on. Carries the span of the offending source text (and, when a nearby valid name exists, help text) so it can be rendered the same way alba_syntax::Diagnostic renders parse errors.

Hook

A git hook bound to a beam: hook pre-commit { beam check }. Only the root Beamfile’s hooks make it here; an import’s are ignored, as its default is.

LoadError

A load_project failure, paired with every source file successfully read before it happened. sources lets a caller render error (via SourceMap::get and alba_syntax::render_diagnostic) even though loading never finished — error.source_id is always resolvable through it, since a file is registered in sources before it’s parsed or evaluated.

Project

A fully evaluated Beamfile (single-file loading only; see the module doc comment): every beam it declares, and which one runs by default.

Scope

Name bindings available while evaluating expressions: a file’s evaluated lets, later composed with a beam’s own parameter values.

SourceId

Identifies which source file a Beam or crate::CoreError came from, for pointing diagnostics at the right source text. Assigned by crate::loader::load_project (the root file is always SourceId(0), each import gets the next one in load order) and resolvable back to a path and source text via crate::loader::SourceMap::get. load_str’s single-file loading always produces SourceId(0).

SourceMap

The path and source text of every file load_project read, indexed by SourceId, so a CoreError’s source_id can be turned back into something renderable: look up (path, source) here and hand both to alba_syntax::render_diagnostic(source, &path.display().to_string(), &diagnostic).

Enums

ExecutorKind

How a beam’s commands run.

OptionValue

The value half of an executor option, once rendered (its {expr} interpolation resolved, for the Str/List cases) at load time. Mirrors alba_syntax::ExecutorOptionValue, minus the interpolation itself.

Value

A value produced by evaluating an alba_syntax::Expr: either of the DSL’s two runtime types.

Functions

anchor_pattern

Where pattern’s matches live: base with the pattern’s leading . and .. components applied, and the rest of the pattern, relative to that directory. ../../Dockerfile declared in /repo/contexts/shared anchors at /repo as Dockerfile.

eval_expr

Evaluates expr against scope. The public entry point; internally delegates to a private helper that threads a span to fall back on for spanless expression kinds (Bool, Binary, If) down through recursive calls. Called directly (rather than through render_template or the deferred-template checker below, both of which have richer context to use as that fallback), the best available fallback is expr’s own span if it has one, or a zero-width span at the start of the source as a last resort.

execution_subgraph

The transitive closure of target (itself included), unordered: scheduling order is the engine’s job, not this crate’s. A needs entry repeated within one beam (needs [a, a]) contributes a to the closure once, not twice.

expand_globs

The files matching any of patterns, resolved from base, as (relative path with '/' separators, absolute path) pairs sorted by relative path — sorted so a fingerprint built from the list is deterministic across platforms and directory iteration orders.

load_project

Loads root and every Beamfile it (transitively) imports into one Project, namespacing imported beams by the alias they were imported under. See the module doc comment for the resolution rules.

outputs_satisfied

Whether every outputs pattern is satisfied on disk: a literal path must exist, a glob pattern must match at least one entry. Raw disk, no .gitignore filtering — see the module doc comment.

pattern_dir

The deepest directory every match of pattern, resolved from base, lies under: its anchor_pattern joined with the pattern’s leading literal directories. Watching it recursively sees every file the pattern can ever match.

render_template

Renders template against scope: literal parts pass through unchanged, {expr} parts are evaluated and interpolated (strings verbatim, booleans as true/false).

suggest

The closest name in candidates to name, if within Levenshtein distance 2, matching alba_syntax’s unknown-field suggestion threshold. Ties are broken alphabetically, not by iteration order: candidates is typically a HashMap’s keys (via Scope::names), whose iteration order is randomized per process, so without an explicit tie-break the suggestion offered for the same typo could change from run to run.

validate_graph

Checks that every needs entry in project names a beam that actually exists, that project’s default (if it declares one) does too, and that no beam (transitively) needs itself.