refactor(macros): simplify internal layout and harden transition returns#20
refactor(macros): simplify internal layout and harden transition returns#20eboody wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
This PR restructures statum-macros into clearer internal subsystems (source observation → semantic resolution → emission/diagnostics) while aiming to keep public macro behavior unchanged, and adds internal contract types + an architecture note to codify the intended boundaries.
Changes:
- Introduces a
source/facade (analysis, callsite/module-path lookup, source-backed queries) and migrates callsite/query/pathing usage to it. - Splits major subsystems into smaller modules (notably
state/,transition/resolve/,validators/, andmachine/emission/) and replaces some ad-hoc plumbing with sharedcontracts.rs. - Adds targeted tests for transition return-shape parsing/collection and documents internal boundaries in
ARCHITECTURE.md.
Reviewed changes
Copilot reviewed 35 out of 37 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| statum-macros/src/validators/resolution.rs | Migrates source-backed candidate lookup helpers to the new source facade and updates formatting helpers. |
| statum-macros/src/validators/plan.rs | New validator planning pass to collect checks/report checks and async-ness. |
| statum-macros/src/validators/contract.rs | New internal “contract” helpers for validator planning/emission (variant specs, path helpers, type qualification). |
| statum-macros/src/validators.rs | Refactors #[validators] orchestration to use contract/planning modules and ValidatorContract. |
| statum-macros/src/transition/resolve/mod.rs | New split resolve module that re-exports alias/shape/strategy utilities + hosts resolve tests. |
| statum-macros/src/transition/resolve/alias.rs | New alias-expansion logic using source queries for source-backed type aliases. |
| statum-macros/src/transition/resolve/shape.rs | New return-shape parsing helpers (target matching, wrapper detection, generic extraction). |
| statum-macros/src/transition/resolve/strategy.rs | New strict vs relaxed resolution strategies + collectors for all targets in wrapper shapes. |
| statum-macros/src/transition/resolve.rs | Deleted monolithic resolve implementation; logic moved under transition/resolve/. |
| statum-macros/src/transition/parse.rs | Updates transition return-shape resolution flow to use new resolve exports and only the multi-target path. |
| statum-macros/src/transition/diagnostics.rs | Migrates candidate formatting and source helpers to source facade. |
| statum-macros/src/transition/contract.rs | New contract builder that produces TransitionContract from parsed transition info. |
| statum-macros/src/transition.rs | Refactors transition validation to build/use a transition contract (next-states list). |
| statum-macros/src/state/mod.rs | New #[state] subsystem module (parse/validate/store/emit) replacing the previous monolith. |
| statum-macros/src/state/validation.rs | New extracted validation logic for legal #[state] enum shapes. |
| statum-macros/src/state/registry.rs | New extracted state registry storage/lookup + currentness checks. |
| statum-macros/src/state/emission.rs | New extracted state marker/data surface emission. |
| statum-macros/src/state.rs | Deleted monolithic state implementation; functionality moved under state/. |
| statum-macros/src/source/mod.rs | New source-observation facade module re-exporting callsite/pathing/query/syntax helpers. |
| statum-macros/src/source/analysis.rs | New file analysis implementation for discovering items + line numbers with macro-body skipping. |
| statum-macros/src/source/cache.rs | Migrates line/module caching under source/ namespace. |
| statum-macros/src/source/callsite.rs | Migrates callsite helpers under source/ and removes a test-only helper. |
| statum-macros/src/source/module_path.rs | Migrates module-path resolution to source/ and updates internal imports/tests. |
| statum-macros/src/source/parser.rs | Migrates module parsing helpers to source/ and updates imports. |
| statum-macros/src/source/pathing.rs | New pathing utilities (normalization, module-path ↔ file mapping). |
| statum-macros/src/source/query.rs | Migrates query utilities to source/ and updates analysis type usage. |
| statum-macros/src/source/syntax.rs | Migrates syntax helpers to source/ and updates callsite import path. |
| statum-macros/src/machine/mod.rs | Updates exports/docs and exposes ParsedMachineInfo for internal contracts. |
| statum-macros/src/machine/metadata.rs | Migrates source-backed helpers to source, replaces removed callsite helper usage, adds clone derives for parsed types. |
| statum-macros/src/machine/emission/mod.rs | New machine emission module split (support/builders/presentation) orchestrator. |
| statum-macros/src/machine/emission/support.rs | New extracted support utilities for generics, transition traits, aliases, struct definition emission. |
| statum-macros/src/machine/emission/builders.rs | New extracted builder emission logic for state-specific builders and RA shim. |
| statum-macros/src/machine/emission/presentation.rs | New extracted presentation/introspection surface emission. |
| statum-macros/src/machine/emission.rs | Deleted monolithic machine emission; logic moved under machine/emission/. |
| statum-macros/src/lib.rs | Introduces contracts and source modules and updates root wiring/imports accordingly. |
| statum-macros/src/contracts.rs | Adds shared internal contract types used across subsystems (validators/transitions). |
| statum-macros/ARCHITECTURE.md | Documents internal subsystem boundaries and dependency direction expectations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3ecae65d50
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| let contract = match build_transition_contract(func, &tr_impl.target_type) { | ||
| Ok(contract) => contract, | ||
| Err(err) => return Some(err), | ||
| }; | ||
| for return_state in return_states { | ||
| for return_state in contract.next_states { |
There was a problem hiding this comment.
validate_transition_functions now validates only contract.next_states, which are collected from any matching branch in wrapper return types, but it no longer enforces that the primary return shape itself resolves to the target machine. This allows signatures like Result<Error, Machine<Done>> (or analogous Branch forms) to pass even though the documented canonical contract is Result<Machine<Next>, E>, so strict/introspection metadata can accept and register transitions where the primary branch is not a machine transition.
Useful? React with 👍 / 👎.
eboody
changed the title
|
Closing as obsolete: the simplification and transition-return work already landed directly on |
Summary
statum-macrosinto clearer internal subsystemsstatum-macros/src/source/state, machine emission, and transition resolution into focused modulesDetails
This keeps the public macro surface the same while making
statum-macroseasier to navigate as three internal layers:The structural changes in this PR are:
statum-macros/src/source/now owns file analysis, module-path lookup, and source-backed candidate queriesstatum-macros/src/state/now owns#[state]parsing, validation, registry storage, and emissionstatum-macros/src/machine/emission/is split into support scaffolding, builders, and presentation/introspection outputstatum-macros/src/transition/resolve/is split into alias expansion, shape parsing, and strict-vs-relaxed strategy codestatum-macros/src/validators/now has explicit contract and planning modulesstatum-macros/src/contracts.rsprovides shared internal handoff typesstatum-macros/ARCHITECTURE.mddocuments the intended subsystem boundariesThis PR also fixes a transition-validation regression: wrapper return shapes now have to resolve to the target machine in the primary branch, instead of passing just because a later branch mentions the machine. That restores the documented canonical contract and closes the matching strict
#[introspect(return = ...)]hole.Validation
cargo fmt --all --checkcargo test --workspace --all-featurescargo clippy --workspace --all-targets --all-features -- -D warningsNotes
Result<Error, Machine<Next>>-style primary-branch shapes in both strict and non-strict modes.