feat(cargo): split entity-attribute generators into opt-out features (#132)

* #131 feat(cargo): split entity-attribute generators into opt-out features

Every entity-attribute group now lives behind its own Cargo feature so
users can shrink their build by switching off generators they don't need.
All new features ship default-on, so existing projects compile unchanged.

New features (default-on, non-breaking):

- events       — `{Entity}Event` enum, lifecycle event variants
- commands     — command structs, dispatcher trait (`#[entity(commands)]`,
                 `#[command(...)]`)
- hooks        — `{Entity}Hooks` trait (manual wiring; #127 tracks
                 auto-invocation)
- transactions — `{Entity}TransactionRepo` adapter + deprecated `with_*`
                 builders (`#[entity(transactions)]`)
- aggregate_root — `New{Entity}` constructor and transactional `save()`
                   (`#[entity(aggregate_root)]`)
- migrations   — compile-time `MIGRATION_UP`/`MIGRATION_DOWN` constants
                 (`#[entity(migrations)]`)
- projections  — projection structs + `find_by_id_<projection>` methods
                 (`#[projection(...)]`)

Plumbing:

- Each feature in `entity-derive` activates its sibling in
  `entity-derive-impl`. The facade now declares
  `entity-derive-impl = { … default-features = false }` so transitive
  default-on doesn't leak past the user's explicit selection.
- In `entity-derive-impl/src/entity.rs`, every gated submodule and its
  `generate(&entity)` call sits under `#[cfg(feature = "<name>")]`.
- New helper `guard_disabled_attribute()` emits a friendly
  `compile_error!` if the entity attribute is present but the feature is
  off — much clearer than a missing-method puzzle at the call site.
- `streams` now depends on `events` (the NOTIFY payload is an event
  variant; `streams` without `events` would not link).
- Crate-level `#![cfg_attr(any(not(feature = "migrations"), not(feature
  = "projections")), allow(dead_code, unused_imports))]` keeps minimal
  builds warning-free without touching individual parser helpers.

README feature matrix rewritten with a Default column and a "If you use
an entity attribute whose feature is disabled, the macro tells you so"
note plus a `default-features = false` example.

Bump:

- entity-derive-impl: 0.6.2 -> 0.6.3
- entity-derive:      0.8.3 -> 0.8.4

`entity-core` is unchanged.

Closes #131

* test(features): cover guard_disabled_attribute helper

Author: RAprogramm

README.md

@@ -83,15 +83,32 @@ entity-derive = { version = "0.8", features = ["postgres", "api"] }
 
 ### Feature flags
 
-| Feature | What it does |
-|---------|--------------|
-| `postgres` *(default)* | Generate `sqlx::PgPool`-backed repository implementations |
-| `clickhouse` | Generate ClickHouse-backed repositories *(planned)* |
-| `mongodb` | Generate MongoDB-backed repositories *(planned)* |
-| `streams` | Generate `{Entity}Subscriber` using Postgres `LISTEN`/`NOTIFY` |
-| `api` | Generate HTTP handlers (`axum`) and `utoipa` OpenAPI schemas |
-| `validate` | Wire up `validator::Validate` on generated DTOs |
-| `tracing` | Wrap every generated async method in `#[tracing::instrument]` carrying `entity` + `op` span fields |
+| Feature | Default | What it does |
+|---------|:-------:|--------------|
+| `postgres` | ✓ | Generate `sqlx::PgPool`-backed repository implementations |
+| `events` | ✓ | Generate `{Entity}Event` enum (`Created` / `Updated` / `Deleted` variants) |
+| `commands` | ✓ | CQRS command pattern: command structs + dispatcher (`#[entity(commands)]`, `#[command(...)]`) |
+| `hooks` | ✓ | `{Entity}Hooks` trait with before/after lifecycle methods |
+| `transactions` | ✓ | `{Entity}TransactionRepo` adapter + transaction builder helpers (`#[entity(transactions)]`) |
+| `aggregate_root` | ✓ | `New{Entity}` constructor type and transactional `save()` (`#[entity(aggregate_root)]`) |
+| `migrations` | ✓ | Compile-time `MIGRATION_UP` / `MIGRATION_DOWN` SQL constants (`#[entity(migrations)]`) |
+| `projections` | ✓ | Projection structs and `find_by_id_<projection>` lookups (`#[projection(...)]`) |
+| `clickhouse` |   | Generate ClickHouse-backed repositories *(planned)* |
+| `mongodb` |   | Generate MongoDB-backed repositories *(planned)* |
+| `streams` |   | `{Entity}Subscriber` using Postgres `LISTEN`/`NOTIFY` (pulls in `events`) |
+| `api` |   | Generate HTTP handlers (`axum`) and `utoipa` OpenAPI schemas |
+| `validate` |   | Wire up `validator::Validate` on generated DTOs |
+| `tracing` |   | Wrap every generated async method in `#[tracing::instrument]` carrying `entity` + `op` span fields |
+
+Default features cover the full entity-attribute surface so existing projects work without changes. For lean builds, opt out of what you don't need:
+
+```toml
+[dependencies]
+# Just repositories — no events, hooks, commands, etc.
+entity-derive = { version = "0.8", default-features = false, features = ["postgres"] }
+```
+
+If you use an entity attribute whose feature is disabled (e.g. `#[entity(commands)]` without `features = ["commands"]`), the macro emits a `compile_error!` at the attribute pointing to the missing feature.
 
 Enable extras alongside the defaults:
 

crates/entity-derive-impl/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "entity-derive-impl"
-version = "0.6.2"
+version = "0.6.3"
 edition.workspace = true
 rust-version.workspace = true
 authors.workspace = true
@@ -19,7 +19,42 @@ categories = ["development-tools::procedural-macro-helpers"]
 proc-macro = true
 
 [features]
-default = []
+# Default: every entity-attribute generator is on so existing users see no
+# regression. Disable selectively via the `entity-derive` facade for
+# minimal builds (`default-features = false, features = ["postgres"]`).
+default = [
+  "events",
+  "commands",
+  "hooks",
+  "transactions",
+  "aggregate_root",
+  "migrations",
+  "projections"
+]
+
+# Generates `{Entity}Event` enum and lifecycle event helpers. Required
+# transitively by `streams` because the NOTIFY payload uses the event type.
+events = []
+
+# Generates command structs, the handler trait, and the dispatcher.
+commands = []
+
+# Generates `{Entity}Hooks` trait (currently manual-wiring; see #127 for
+# auto-invocation plans).
+hooks = []
+
+# Generates `{Entity}TransactionRepo` adapter, the (deprecated) `with_*`
+# builder methods, and the `ContextExt` accessor trait.
+transactions = []
+
+# Generates `New{Entity}` type and the transactional `save()` method.
+aggregate_root = []
+
+# Generates `MIGRATION_UP` / `MIGRATION_DOWN` SQL constants.
+migrations = []
+
+# Generates projection structs and `find_by_id_<projection>` methods.
+projections = []
 
 [dependencies]
 syn = { version = "2", features = ["full", "extra-traits", "parsing"] }

crates/entity-derive-impl/src/entity.rs

@@ -62,22 +62,29 @@
 //! | `impl UserRepository for PgPool` | PostgreSQL implementation |
 
 mod api;
+#[cfg(feature = "commands")]
 mod commands;
 mod dto;
+#[cfg(feature = "events")]
 mod events;
+#[cfg(feature = "hooks")]
 mod hooks;
 mod insertable;
 mod mappers;
+#[cfg(feature = "migrations")]
 mod migrations;
+#[cfg(feature = "aggregate_root")]
 pub mod new_entity;
 pub mod parse;
 mod policy;
+#[cfg(feature = "projections")]
 mod projection;
 mod query;
 mod repository;
 mod row;
 mod sql;
 mod streams;
+#[cfg(feature = "transactions")]
 mod transaction;
 
 use proc_macro::TokenStream;
@@ -98,22 +105,60 @@ pub fn derive(input: TokenStream) -> TokenStream {
 
 fn generate(entity: EntityDef) -> TokenStream {
     let dto = dto::generate(&entity);
-    let projections = projection::generate(&entity);
     let query_struct = query::generate(&entity);
-    let events = events::generate(&entity);
-    let hooks = hooks::generate(&entity);
-    let commands = commands::generate(&entity);
     let policy = policy::generate(&entity);
     let streams = streams::generate(&entity);
-    let transaction = transaction::generate(&entity);
     let api = api::generate(&entity);
     let repository = repository::generate(&entity);
     let row = row::generate(&entity);
     let insertable = insertable::generate(&entity);
     let mappers = mappers::generate(&entity);
-    let new_entity = new_entity::generate(&entity);
     let sql = sql::generate(&entity);
+
+    // Opt-out generators. Each entity-attribute group is gated behind a
+    // Cargo feature so users can shrink their build by switching them
+    // off via `default-features = false`. The macro itself still parses
+    // every attribute; only the codegen body is skipped when the
+    // feature is off. `guard_disabled_attribute` emits a friendly
+    // compile_error if a user enables an attribute whose feature is
+    // disabled — much clearer than a missing-method error at the call site.
+
+    #[cfg(feature = "events")]
+    let events = events::generate(&entity);
+    #[cfg(not(feature = "events"))]
+    let events = guard_disabled_attribute(&entity, "events", entity.has_events());
+
+    #[cfg(feature = "hooks")]
+    let hooks = hooks::generate(&entity);
+    #[cfg(not(feature = "hooks"))]
+    let hooks = guard_disabled_attribute(&entity, "hooks", entity.has_hooks());
+
+    #[cfg(feature = "commands")]
+    let commands = commands::generate(&entity);
+    #[cfg(not(feature = "commands"))]
+    let commands = guard_disabled_attribute(&entity, "commands", entity.has_commands());
+
+    #[cfg(feature = "transactions")]
+    let transaction = transaction::generate(&entity);
+    #[cfg(not(feature = "transactions"))]
+    let transaction = guard_disabled_attribute(&entity, "transactions", entity.has_transactions());
+
+    #[cfg(feature = "aggregate_root")]
+    let new_entity = new_entity::generate(&entity);
+    #[cfg(not(feature = "aggregate_root"))]
+    let new_entity =
+        guard_disabled_attribute(&entity, "aggregate_root", entity.is_aggregate_root());
+
+    #[cfg(feature = "migrations")]
     let migrations = migrations::generate(&entity);
+    #[cfg(not(feature = "migrations"))]
+    let migrations = guard_disabled_attribute(&entity, "migrations", entity.migrations);
+
+    #[cfg(feature = "projections")]
+    let projections = projection::generate(&entity);
+    #[cfg(not(feature = "projections"))]
+    let projections =
+        guard_disabled_attribute(&entity, "projections", !entity.projections.is_empty());
 
     let expanded = quote! {
         #dto
@@ -137,3 +182,105 @@ fn generate(entity: EntityDef) -> TokenStream {
 
     expanded.into()
 }
+
+/// Emit a `compile_error!` if the user opted into an entity-attribute
+/// group whose Cargo feature is currently disabled.
+///
+/// `feature_name` is the public feature flag name (e.g. `"commands"`).
+/// `is_requested` is the boolean from the entity attribute parser
+/// (e.g. `entity.has_commands()`). If the attribute is not used, this
+/// returns an empty `TokenStream` and nothing is emitted.
+#[allow(dead_code)]
+fn guard_disabled_attribute(
+    entity: &EntityDef,
+    feature_name: &str,
+    is_requested: bool
+) -> proc_macro2::TokenStream {
+    if !is_requested {
+        return proc_macro2::TokenStream::new();
+    }
+    let entity_name = entity.name();
+    let msg = format!(
+        "entity `{entity_name}` uses an attribute that requires the `{feature_name}` feature of \
+         `entity-derive`, but it is currently disabled. Enable it by adding \
+         `features = [\"{feature_name}\"]` to your `entity-derive` dependency, or remove the \
+         corresponding `#[entity(...)]` / `#[command(...)]` / `#[projection(...)]` attribute."
+    );
+    quote! { ::core::compile_error!(#msg); }
+}
+
+#[cfg(test)]
+mod tests {
+    use syn::parse_quote;
+
+    use super::*;
+
+    fn parse_minimal_entity() -> EntityDef {
+        let input: syn::DeriveInput = parse_quote! {
+            #[entity(table = "users")]
+            pub struct User {
+                #[id]
+                pub id: ::uuid::Uuid
+            }
+        };
+        EntityDef::from_derive_input(&input).expect("minimal entity must parse")
+    }
+
+    #[test]
+    fn guard_returns_empty_when_attribute_not_requested() {
+        let entity = parse_minimal_entity();
+        let tokens = guard_disabled_attribute(&entity, "commands", false);
+        assert!(
+            tokens.is_empty(),
+            "no compile_error must be emitted when the attribute is absent, got: {tokens}"
+        );
+    }
+
+    #[test]
+    fn guard_emits_compile_error_when_attribute_requested_without_feature() {
+        let entity = parse_minimal_entity();
+        let tokens = guard_disabled_attribute(&entity, "commands", true).to_string();
+        assert!(
+            tokens.contains("compile_error"),
+            "must emit compile_error! token, got: {tokens}"
+        );
+        assert!(
+            tokens.contains("commands"),
+            "diagnostic must name the missing feature, got: {tokens}"
+        );
+        assert!(
+            tokens.contains("features = "),
+            "diagnostic must show the user how to enable, got: {tokens}"
+        );
+    }
+
+    #[test]
+    fn guard_includes_entity_name_in_diagnostic() {
+        let entity = parse_minimal_entity();
+        let tokens = guard_disabled_attribute(&entity, "hooks", true).to_string();
+        assert!(
+            tokens.contains("User"),
+            "diagnostic must name the offending entity, got: {tokens}"
+        );
+    }
+
+    #[test]
+    fn guard_message_references_correct_feature_name() {
+        let entity = parse_minimal_entity();
+        for feature in [
+            "events",
+            "commands",
+            "hooks",
+            "transactions",
+            "aggregate_root",
+            "migrations",
+            "projections"
+        ] {
+            let tokens = guard_disabled_attribute(&entity, feature, true).to_string();
+            assert!(
+                tokens.contains(feature),
+                "diagnostic for `{feature}` must mention it, got: {tokens}"
+            );
+        }
+    }
+}

crates/entity-derive-impl/src/lib.rs

@@ -7,6 +7,16 @@
     html_favicon_url = "https://raw.githubusercontent.com/RAprogramm/entity-derive/main/assets/favicon.ico"
 )]
 #![cfg_attr(docsrs, feature(doc_cfg))]
+// Several parsing helpers (column DDL, composite indexes, projection
+// metadata) are only consumed by the `migrations` and `projections`
+// generators. When users opt out of those features, the helpers become
+// unused — silence the dead-code lint in those configurations so minimal
+// builds stay warning-clean. Default builds (every feature on) keep the
+// warning active.
+#![cfg_attr(
+    any(not(feature = "migrations"), not(feature = "projections")),
+    allow(dead_code, unused_imports)
+)]
 #![warn(
     missing_docs,
     rustdoc::missing_crate_level_docs,

crates/entity-derive/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "entity-derive"
-version = "0.8.3"
+version = "0.8.4"
 edition.workspace = true
 rust-version.workspace = true
 authors.workspace = true
@@ -16,21 +16,65 @@ keywords = ["derive", "macro", "entity", "dto", "repository"]
 categories = ["development-tools::procedural-macro-helpers", "database"]
 
 [features]
-default = ["postgres"]
+# Default: bring up every entity-attribute generator so existing users
+# see no behavior change. For lean builds use
+# `default-features = false, features = ["postgres", "<the ones you need>"]`.
+default = [
+  "postgres",
+  "events",
+  "commands",
+  "hooks",
+  "transactions",
+  "aggregate_root",
+  "migrations",
+  "projections"
+]
+
+# Database dialects
 postgres = ["entity-core/postgres"]
 clickhouse = ["entity-core/clickhouse"]
 mongodb = ["entity-core/mongodb"]
-streams = ["entity-core/streams"]
+
+# Real-time streams via Postgres LISTEN/NOTIFY. Pulls in `events`
+# because the NOTIFY payload is an event variant.
+streams = ["entity-core/streams", "events"]
+
+# HTTP handlers + OpenAPI generation.
 api = []
+
+# `validator::Validate` integration on DTOs.
 validate = []
+
+# Lifecycle event types (`{Entity}Event::Created` / `Updated` / etc.).
+events = ["entity-derive-impl/events"]
+
+# CQRS command pattern: command structs + dispatcher.
+commands = ["entity-derive-impl/commands"]
+
+# `{Entity}Hooks` trait. Manual wiring today; auto-invocation tracked in #127.
+hooks = ["entity-derive-impl/hooks"]
+
+# `{Entity}TransactionRepo` adapter and the `with_*` builder methods
+# (deprecated, slated for removal in 0.8.0 line; see #110).
+transactions = ["entity-derive-impl/transactions"]
+
+# Aggregate-root scaffolding: `New{Entity}` type + transactional `save()`.
+aggregate_root = ["entity-derive-impl/aggregate_root"]
+
+# Compile-time SQL migration constants (`MIGRATION_UP` / `MIGRATION_DOWN`).
+migrations = ["entity-derive-impl/migrations"]
+
+# Partial-view projections and `find_by_id_<projection>` methods.
+projections = ["entity-derive-impl/projections"]
+
 # Opt-in: emit `#[tracing::instrument]` on every generated async method.
 # Users who enable this must also depend on `tracing` directly so the
 # generated `::tracing::instrument` resolves.
 tracing = ["entity-core/tracing"]
 
 [dependencies]
 entity-core = { path = "../entity-core", version = "0.6" }
-entity-derive-impl = { path = "../entity-derive-impl", version = "0.6" }
+entity-derive-impl = { path = "../entity-derive-impl", version = "0.6", default-features = false }
 
 [dev-dependencies]
 trybuild = "1"