Skip to main content

arcature_build/
lib.rs

1//! `arcature-build` — Arcature build/dev-time application intelligence.
2//!
3//! This crate owns the canonical **Arcature Unified Application Graph (UAG)**:
4//! a deterministic, serializable, schema-versioned view of an application
5//! aggregated from the `&'static` compile-time metadata the `arcature-dx`
6//! macros (`module!`, `application!`, `routes!`, `#[controller]`, `#[page]`,
7//! …) already generate. It is the single graph consumed by the CLI, the
8//! frontend virtual modules, the Inspector, MCP, system checks, packaging,
9//! and deployment (ADR-0006 §2: "Same graph everywhere").
10//!
11//! # Two disjoint paths
12//!
13//! ## 1. Build-script entry (`default` features, no `arcature` dependency)
14//!
15//! A generated application lists `arcature-build` as a `[build-dependencies]`
16//! entry and calls [`compile`] from a tiny `build.rs`:
17//!
18//! ```rust,ignore
19//! fn main() {
20//!     arcature_build::compile();
21//! }
22//! ```
23//!
24//! [`compile`] performs **only build-script-safe work**: it emits Cargo
25//! `rerun-if-changed` / `rerun-if-env-changed` directives, a build-time `cfg`,
26//! and a framework-version env. It does **not** aggregate proc-macro
27//! metadata — a build script runs *before* the package's proc-macros expand,
28//! so it cannot observe the `&'static` graph the macros produce this compile.
29//! Aggregation is a dev-time concern (path 2).
30//!
31//! ## 2. Dev-time UAG aggregation (`uag` / `uag-schema` features)
32//!
33//! The `uag` feature pulls `arcature` (for the `ApplicationGraph` types) and
34//! exposes the UAG schema, the `ApplicationGraph -> Uag` conversion, and the
35//! manifest emitter. An application's `arcature-metadata` binary (or
36//! `arc inspect app`) links the compiled application, calls the generated
37//! `<name>_graph()` accessor that `application!` emits, converts the result
38//! to a [`uag::Uag`], and serializes it to `.arcature/app-manifest.json`.
39//!
40//! The **`uag-schema`** feature is the serde-only subset: it exposes the
41//! serializable schema types ([`uag::Uag`] and the `uag::schema` entry types)
42//! and the schema-version constant, with `serde` / `serde_json` and **no
43//! `arcature` dependency**. A consumer that only needs to *read* the
44//! canonical manifest JSON — notably `arcature-cli`, which shells out to the
45//! app's `arcature-metadata` binary and deserializes its stdout — depends on
46//! `arcature-build` with `uag-schema` alone (AGENTS.md §16 standalone-first).
47//! `uag` implies `uag-schema`, so the dev-time serializer and the read-only
48//! consumer never disagree on the schema (ADR-0006 §2: "Same graph
49//! everywhere").
50//!
51//! This split keeps `[build-dependencies]` light (no `arcature` in the build
52//! script) while giving dev-time tooling a single canonical, deterministic,
53//! schema-versioned artifact. Both paths are side-effect-free from the
54//! crate's perspective: no filesystem source scanning, no Rust parsing, no
55//! runtime discovery, no `inventory`/`linkme`/`ctor`, no global mutable state
56//! (ADR-0006 §2; AGENTS.md §17/§20).
57//!
58//! # Determinism
59//!
60//! The UAG is ordered with `BTreeMap` / `BTreeSet` and sorted vectors; the
61//! manifest emitter writes stable JSON (no timestamps, no absolute
62//! `OUT_DIR` / `CARGO_MANIFEST_DIR` paths). A drift-check test (not a build
63//! script) enforces a checked-in `.arcature/app-manifest.json` stays current
64//! (ADR-0006 §2; official Cargo `build-script-examples` "generated file"
65//! guidance).
66//!
67//! See ADR-0006 and `docs/ap2-1/PROGRAM.md` (AP2.1-1).
68
69#![forbid(unsafe_code)]
70#![cfg_attr(docsrs, feature(doc_cfg))]
71
72mod compile;
73
74#[cfg(any(feature = "uag", feature = "uag-schema"))]
75#[cfg_attr(docsrs, doc(cfg(any(feature = "uag", feature = "uag-schema"))))]
76pub mod uag;
77
78pub use compile::compile;