macroonz-macros 0.2.0

//! The thin proc-macro carrier for the root recipe entrance, item-preserving attributes, and direct declarations.
//!
//! Recipe grammar and projection belong to the compiler's `recipe` home; the other entries use the compiler's `descriptor` home and its `door` road.
//! What this crate adds is exactly what a proc host owns: token conversion, span custody, one compiler call, diagnostic placement, and emission — plus the facts of its own act, declared once beside each entry.
//! Built-in recipe projections may cross this host, while an arbitrary downstream projection algorithm uses the same compiler contract from a caller-owned compiler or proc host.
//!
//! Each attribute expands to one exported carrier and then re-emits the item token stream it received; the carrier is inert until a consumption target invokes it, so an ordinary build compiles the item and one macro definition and nothing more.
//! Direct declarations such as [`shadow!`](macro@shadow), [`network!`](macro@network), and [`concurrency!`](macro@concurrency) emit ordinary items where the declaration stands, inert inside nothing, because a face and a builder are not cargo.

use macroonz_compiler::descriptor::door;
use macroonz_compiler::descriptor::{Emitter, Grammar};
use macroonz_compiler::{CrateBinding, Door, Producer, host};
use proc_macro::TokenStream;

/// Who is asking wherever the root recipe entrance refuses.
const RECIPE_DOOR: Door = Door::declared(
    "macroonz",
    "macroonz.recipe",
    "macroonz::recipe!",
    CrateBinding::declared("macroonz"),
    Producer {
        namespace: "macroonz",
        name: "macroonz-macros",
    },
);

/// The procedural carrier behind `macroonz::recipe!`.
///
/// Rust requires this function-like proc entry to be public so the facade's hygienic wrapper can reach it across the package boundary.
/// `macroonz::recipe!` is the only supported entrance; direct invocation is outside the compatibility contract and may change or break in any release without notice.
#[doc(hidden)]
#[proc_macro]
pub fn __macroonz_recipe_carrier(body: TokenStream) -> TokenStream {
    host::expand_emittable(body, |capture| {
        macroonz_compiler::recipe::bake_wrapped(&capture, &RECIPE_DOOR)
    })
}

/// The grammar spelling the `trials` attribute registers.
const TRIALS_GRAMMAR: Grammar = Grammar {
    attribute: "trials",
};

/// The grammar spelling the `mutations` attribute registers.
const MUTATIONS_GRAMMAR: Grammar = Grammar {
    attribute: "mutations",
};

/// The grammar spelling the `bench` attribute registers.
const BENCH_GRAMMAR: Grammar = Grammar { attribute: "bench" };

/// This crate's own act, for the trial door.
const TRIALS_EMITTER: Emitter = Emitter {
    namespace: "macroonz",
    producer: "macroonz-macros",
    door: "trials",
};

/// This crate's own act, for the bench door.
const BENCH_EMITTER: Emitter = Emitter {
    namespace: "macroonz",
    producer: "macroonz-macros",
    door: "bench",
};

/// Who is asking, wherever a `trials` expansion refuses.
const TRIALS_DOOR: Door = Door::declared(
    "macroonz",
    "macroonz.trials",
    "macroonz_macros::trials",
    CrateBinding::declared("macroonz"),
    Producer {
        namespace: "macroonz",
        name: "macroonz-macros",
    },
);

/// Who is asking, wherever a `mutations` expansion refuses.
const MUTATIONS_DOOR: Door = Door::declared(
    "macroonz",
    "macroonz.mutations",
    "macroonz_macros::mutations",
    CrateBinding::declared("macroonz"),
    Producer {
        namespace: "macroonz",
        name: "macroonz-macros",
    },
);

/// Who is asking, wherever a `bench` expansion refuses.
const BENCH_DOOR: Door = Door::declared(
    "macroonz",
    "macroonz.bench",
    "macroonz_macros::bench",
    CrateBinding::declared("macroonz"),
    Producer {
        namespace: "macroonz",
        name: "macroonz-macros",
    },
);

/// The grammar spelling the `shadow` declaration registers.
const SHADOW_GRAMMAR: Grammar = Grammar {
    attribute: "shadow",
};

/// The grammar spelling the `network` declaration registers.
const NETWORK_GRAMMAR: Grammar = Grammar {
    attribute: "network",
};

/// The grammar spelling the `concurrency` declaration registers.
const CONCURRENCY_GRAMMAR: Grammar = Grammar {
    attribute: "concurrency",
};

/// Who is asking, wherever a `network` expansion refuses.
const NETWORK_DOOR: Door = Door::declared(
    "macroonz",
    "macroonz.network",
    "macroonz_macros::network",
    CrateBinding::declared("macroonz"),
    Producer {
        namespace: "macroonz",
        name: "macroonz-macros",
    },
);

/// Who is asking, wherever a `concurrency` expansion refuses.
const CONCURRENCY_DOOR: Door = Door::declared(
    "macroonz",
    "macroonz.concurrency",
    "macroonz_macros::concurrency",
    CrateBinding::declared("macroonz"),
    Producer {
        namespace: "macroonz",
        name: "macroonz-macros",
    },
);

/// Who is asking, wherever a `shadow` expansion refuses.
const SHADOW_DOOR: Door = Door::declared(
    "macroonz",
    "macroonz.shadow",
    "macroonz_macros::shadow",
    CrateBinding::declared("macroonz"),
    Producer {
        namespace: "macroonz",
        name: "macroonz-macros",
    },
);

/// Declares a trial table beside the item this attribute sits on.
///
/// The body is the trial grammar, read whole by `macroonz_compiler::descriptor::trial`: the exported support name, the stamped module, the table's own name, and each aggregate seat with its rows.
/// The expansion is one exported carrier holding the stamped table inert, followed by the item unchanged; a consumption target invokes the carrier by the declared support name and supplies its own host facts and callables there.
///
/// A malformed declaration expands to `compile_error!` at the offending token, carrying the compiler's own rendering of the established cause.
#[proc_macro_attribute]
pub fn trials(body: TokenStream, item: TokenStream) -> TokenStream {
    let mut expanded = host::expand_on(body, item.clone(), |captured_body, captured_item| {
        door::trials(
            &captured_body,
            &captured_item,
            TRIALS_GRAMMAR,
            TRIALS_EMITTER,
            &TRIALS_DOOR,
        )
    });
    expanded.extend(item);
    expanded
}

/// Declares a mutation surface over the enum this attribute sits on.
///
/// The body is the mutation grammar, read whole by `macroonz_compiler::descriptor::mutation`: the surface's address, the evaluation family, the point and owner fact, the fact-to-claim mappings, and the operator permissions.
/// The door completes the site from the item itself — the enum's variant list is the declared order, the unchanged operation is that order as authored, and each alternative is one adjacent transposition of it under the harness bank's `declared-order-permutation` operator family.
/// The expansion is one exported carrier holding the rendered module as proved test-carrier cargo, followed by the item unchanged.
///
/// A malformed declaration, and an item that states no order this grammar can read, expand to `compile_error!` at the offending token.
#[proc_macro_attribute]
pub fn mutations(body: TokenStream, item: TokenStream) -> TokenStream {
    let mut expanded = host::expand_on(body, item.clone(), |captured_body, captured_item| {
        door::mutations(
            &captured_body,
            &captured_item,
            MUTATIONS_GRAMMAR,
            &MUTATIONS_DOOR,
        )
    });
    expanded.extend(item);
    expanded
}

/// Declares a neutral benchmark table and its typed report-reader seat beside the item this attribute sits on.
///
/// The body is the bench grammar, read whole by `macroonz_compiler::descriptor::bench`: the exported support name, the table function and name, the reporter module, and each row's references, axis, four exact budget values, optional formula, and observation references.
/// The expansion is one exported carrier holding the table in its stamped seat and one target-supplied `fn(&BenchReport)` value in its opaque seat, followed by the item unchanged.
///
/// A malformed declaration expands to `compile_error!` at the offending token, carrying the compiler's own rendering of the established cause.
#[proc_macro_attribute]
pub fn bench(body: TokenStream, item: TokenStream) -> TokenStream {
    let mut expanded = host::expand_on(body, item.clone(), |captured_body, captured_item| {
        door::bench(
            &captured_body,
            &captured_item,
            BENCH_GRAMMAR,
            BENCH_EMITTER,
            &BENCH_DOOR,
        )
    });
    expanded.extend(item);
    expanded
}

/// Declares the two faces of every chosen synchronization name, once, where the declaration stands.
///
/// The body declares the physical Loom path and a comma-separated choice of names from the compiler's stated shadow roster.
/// Each chosen name expands to exactly the pair its author would have written by hand: the ordinary face behind `#[cfg(not(loom))]` over the standard-library path, and the shadowed face behind `#[cfg(loom)]` over the shadow path.
/// Write the declaration once in a module of the production crate and import through that module everywhere; the crate's one remaining act is its own `[target.'cfg(loom)'.dependencies]` row, declared where it is used.
///
/// A name outside the roster, a malformed choice, and an empty declaration expand to `compile_error!` at the offending token, carrying the compiler's own rendering of the established cause.
#[proc_macro]
pub fn shadow(body: TokenStream) -> TokenStream {
    host::expand(body, |capture| {
        door::shadow(capture, SHADOW_GRAMMAR, &SHADOW_DOOR)
    })
}

/// Declares a topology and its fault schedules, and expands to the builder module an author would have written by hand.
///
/// The body names the physical harness path, a module, a namespace, the nodes, the directed links, and each schedule's discipline as fault phrases in the sim's own vocabulary.
/// What the tokens can know refuses at its own token; what the harness's value guards refuse still refuses there, through the generated functions' honest results.
///
/// A malformed declaration expands to `compile_error!` at the offending token, carrying the compiler's own rendering of the established cause.
#[proc_macro]
pub fn network(body: TokenStream) -> TokenStream {
    host::expand(body, |capture| {
        door::network(capture, NETWORK_GRAMMAR, &NETWORK_DOOR)
    })
}

/// Declares named interleaving explorations, and expands to one generic function per row.
///
/// The body names the physical harness path and each row pins the facts that make a finding replayable — the population, the exhaustive ceiling, the sample count, and the seed — while the generated function takes the strand set and the transition contract at the call, handing back the exploration reading beside its concluded trial verdict.
///
/// A malformed declaration expands to `compile_error!` at the offending token, carrying the compiler's own rendering of the established cause.
#[proc_macro]
pub fn concurrency(body: TokenStream) -> TokenStream {
    host::expand(body, |capture| {
        door::concurrency(capture, CONCURRENCY_GRAMMAR, &CONCURRENCY_DOOR)
    })
}