fix(macros): resolve quick start source info from item spans

Fixes #17.

- prefer annotated item spans over anonymous proc-macro call sites when resolving source and module information
- fall back for validator line numbers when impl span location data is unavailable
- add a Quick Start regression fixture and repo-relative docs links for CI

Author: eboody

docs/inspector-plan.md

@@ -36,7 +36,7 @@ Current shipping surface:
 ## Dependency
 
 The exact static substrate is tracked separately in
-[exact-static-relations-plan.md](/home/eran/code/statum/docs/exact-static-relations-plan.md).
+[exact-static-relations-plan.md](exact-static-relations-plan.md).
 
 That plan is the protocol-truth dependency for this one.
 
@@ -205,7 +205,7 @@ Heuristic lane:
 
 Source of truth:
 
-- [exact-static-relations-plan.md](/home/eran/code/statum/docs/exact-static-relations-plan.md)
+- [exact-static-relations-plan.md](exact-static-relations-plan.md)
 
 Status:
 

macro_registry/Cargo.toml

@@ -2,6 +2,10 @@
 path = "../module_path_extractor"
 version = "0.6.9"
 
+[dependencies.proc-macro2]
+features = ["span-locations"]
+version = "1.0"
+
 [dependencies.syn]
 features = ["full"]
 version = "2.0"

macro_registry/src/callsite.rs

@@ -1,4 +1,5 @@
 use module_path_extractor::{find_module_path, get_pseudo_module_path, get_source_info};
+use proc_macro2::Span;
 use std::path::Path;
 
 fn normalize_file_path(file_path: &str) -> String {
@@ -13,9 +14,39 @@ fn normalize_file_path(file_path: &str) -> String {
     }
 }
 
+fn source_file_exists(file_path: &str) -> bool {
+    Path::new(file_path).is_file()
+}
+
 /// Returns `(file_path, line_number)` for the current macro call-site when available.
 pub fn current_source_info() -> Option<(String, usize)> {
-    get_source_info().map(|(file_path, line_number)| (normalize_file_path(&file_path), line_number))
+    get_source_info()
+        .map(|(file_path, line_number)| (normalize_file_path(&file_path), line_number))
+        .filter(|(file_path, _)| source_file_exists(file_path))
+}
+
+/// Returns `(file_path, line_number)` for an explicit span when available.
+pub fn source_info_for_span(span: Span) -> Option<(String, usize)> {
+    let file_path = span
+        .local_file()
+        .map(|path| path.to_string_lossy().into_owned())
+        .or_else(|| {
+            let file_path = span.file();
+            (!file_path.is_empty()).then_some(file_path)
+        })?;
+
+    let file_path = normalize_file_path(&file_path);
+    source_file_exists(&file_path).then_some((file_path, span.start().line))
+}
+
+/// Returns `(file_path, line_number)` for an explicit span, falling back to the
+/// current macro call-site when the span does not carry usable source info.
+pub fn source_info_for_span_or_callsite(span: Span) -> Option<(String, usize)> {
+    match source_info_for_span(span) {
+        Some((file_path, line_number)) if line_number > 0 => Some((file_path, line_number)),
+        Some((file_path, _)) => current_source_info().or(Some((file_path, 0))),
+        None => current_source_info(),
+    }
 }
 
 /// Returns the best-effort source file for the current macro call-site.
@@ -35,6 +66,16 @@ pub fn current_module_path_at_line(line_number: usize) -> Option<String> {
     module_path_for_line(&file_path, line_number)
 }
 
+/// Returns the best-effort module path for an explicit span or, if needed, the
+/// current macro call-site.
+pub fn module_path_for_span(span: Span) -> Option<String> {
+    let (file_path, line_number) = source_info_for_span_or_callsite(span)?;
+    if line_number == 0 {
+        return None;
+    }
+    module_path_for_line(&file_path, line_number)
+}
+
 /// Returns the best-effort module path for the current macro call-site.
 pub fn current_module_path() -> String {
     current_module_path_opt().unwrap_or_else(get_pseudo_module_path)

statum-macros/src/lib.rs

@@ -42,7 +42,7 @@ pub(crate) use syntax::{
     extract_derives, source_file_fingerprint,
 };
 
-use macro_registry::callsite::{current_module_path_at_line, current_module_path_opt};
+use macro_registry::callsite::{module_path_for_span, source_info_for_span_or_callsite};
 use proc_macro::TokenStream;
 use proc_macro2::Span;
 use syn::{Item, ItemImpl, parse_macro_input};
@@ -138,7 +138,7 @@ pub fn transition(
     item: proc_macro::TokenStream,
 ) -> proc_macro::TokenStream {
     let input = parse_macro_input!(item as ItemImpl);
-    let module_path = match resolved_current_module_path(Span::call_site(), "#[transition]") {
+    let module_path = match resolved_current_module_path(input.impl_token.span, "#[transition]") {
         Ok(path) => path,
         Err(err) => return err,
     };
@@ -172,12 +172,21 @@ pub fn transition(
 /// `.build_reports()`.
 #[proc_macro_attribute]
 pub fn validators(attr: TokenStream, item: TokenStream) -> TokenStream {
-    let line_number = Span::call_site().start().line;
-    let module_path = match resolved_current_module_path(Span::call_site(), "#[validators]") {
+    let item_impl = parse_macro_input!(item as ItemImpl);
+    let span = item_impl.impl_token.span;
+    let line_number = source_info_for_span_or_callsite(span)
+        .map(|(_, line_number)| line_number)
+        .filter(|line_number| *line_number > 0)
+        .or_else(|| {
+            let raw_line_number = span.start().line;
+            (raw_line_number > 0).then_some(raw_line_number)
+        })
+        .unwrap_or_default();
+    let module_path = match resolved_current_module_path(span, "#[validators]") {
         Ok(path) => path,
         Err(err) => return err,
     };
-    parse_validators(attr, item, &module_path, line_number)
+    parse_validators(attr, item_impl, &module_path, line_number)
 }
 
 #[doc(hidden)]
@@ -190,12 +199,7 @@ pub(crate) fn resolved_current_module_path(
     span: Span,
     macro_name: &str,
 ) -> Result<String, TokenStream> {
-    let line_number = span.start().line;
-    let resolved = if line_number == 0 {
-        current_module_path_opt()
-    } else {
-        current_module_path_at_line(line_number).or_else(current_module_path_opt)
-    };
+    let resolved = module_path_for_span(span);
 
     resolved.ok_or_else(|| {
         let message = format!(

statum-macros/src/machine/metadata.rs

@@ -1,4 +1,6 @@
-use macro_registry::callsite::{current_source_file, current_source_info, module_path_for_line};
+use macro_registry::callsite::{
+    current_source_info, module_path_for_span, source_info_for_span_or_callsite,
+};
 use macro_registry::query;
 use proc_macro2::{Span, TokenStream};
 use quote::{format_ident, quote, ToTokens};
@@ -8,8 +10,7 @@ use crate::{
     EnumInfo, LoadedStateLookupFailure, ModulePath, SourceFingerprint, StateModulePath,
     crate_root_for_file, extract_derives, format_loaded_state_candidates,
     lookup_loaded_state_enum, lookup_loaded_state_enum_by_name, source_file_fingerprint,
-    parse_present_attrs, parse_presentation_types_attr, PresentationAttr,
-    PresentationTypesAttr,
+    parse_present_attrs, parse_presentation_types_attr, PresentationAttr, PresentationTypesAttr,
 };
 use super::extra_type_arguments_tokens;
 
@@ -77,19 +78,19 @@ impl MachineInfo {
     }
 
     pub fn from_item_struct(item: &ItemStruct) -> syn::Result<Self> {
-        let Some(file_path) = current_source_file() else {
+        let span = item.ident.span();
+        let Some((file_path, line_number)) = source_info_for_span_or_callsite(span) else {
             return Err(syn::Error::new(
-                item.ident.span(),
+                span,
                 format!(
                     "Internal error: could not read source information for `#[machine]` struct `{}`.",
                     item.ident
                 ),
             ));
         };
-        let line_number = item.ident.span().start().line;
-        let Some(module_path) = module_path_for_line(&file_path, line_number) else {
+        let Some(module_path) = module_path_for_span(span) else {
             return Err(syn::Error::new(
-                item.ident.span(),
+                span,
                 format!(
                     "Internal error: could not resolve the module path for `#[machine]` struct `{}`.",
                     item.ident
@@ -129,8 +130,9 @@ impl MachineInfo {
             return None;
         }
 
-        let line_number = item.ident.span().start().line;
-        let file_path = current_source_file();
+        let (file_path, line_number) = source_info_for_span_or_callsite(item.ident.span())
+            .map(|(file_path, line_number)| (Some(file_path), line_number))
+            .unwrap_or((None, item.ident.span().start().line));
         let presentation = parse_present_attrs(&item.attrs).ok()?;
         let presentation_types = parse_presentation_types_attr(&item.attrs).ok()?;
         Some(Self {

statum-macros/src/state.rs

@@ -1,4 +1,4 @@
-use macro_registry::callsite::{current_source_file, module_path_for_line};
+use macro_registry::callsite::{module_path_for_span, source_info_for_span_or_callsite};
 use proc_macro2::TokenStream;
 use quote::{format_ident, quote, ToTokens};
 use std::sync::{OnceLock, RwLock};
@@ -336,19 +336,19 @@ pub fn invalid_state_target_error(item: &Item) -> TokenStream {
 
 impl EnumInfo {
     pub fn from_item_enum(item: &ItemEnum) -> syn::Result<Self> {
-        let Some(file_path) = current_source_file() else {
+        let span = item.ident.span();
+        let Some((file_path, line_number)) = source_info_for_span_or_callsite(span) else {
             return Err(syn::Error::new(
-                item.ident.span(),
+                span,
                 format!(
                     "Internal error: could not read source information for `#[state]` enum `{}`.",
                     item.ident
                 ),
             ));
         };
-        let line_number = item.ident.span().start().line;
-        let Some(module_path) = module_path_for_line(&file_path, line_number) else {
+        let Some(module_path) = module_path_for_span(span) else {
             return Err(syn::Error::new(
-                item.ident.span(),
+                span,
                 format!(
                     "Internal error: could not resolve the module path for `#[state]` enum `{}`.",
                     item.ident
@@ -368,8 +368,9 @@ impl EnumInfo {
         item: &ItemEnum,
         module_path: StateModulePath,
     ) -> syn::Result<Self> {
-        let file_path = current_source_file();
-        let line_number = item.ident.span().start().line;
+        let (file_path, line_number) = source_info_for_span_or_callsite(item.ident.span())
+            .map(|(file_path, line_number)| (Some(file_path), line_number))
+            .unwrap_or((None, item.ident.span().start().line));
         Self::from_item_enum_with_module_and_file(item, module_path, file_path, line_number)
     }
 

statum-macros/src/validators.rs

@@ -34,12 +34,11 @@ struct CollectValidatorContext<'a> {
 
 pub fn parse_validators(
     attr: TokenStream,
-    item: TokenStream,
+    item_impl: ItemImpl,
     module_path: &str,
     line_number: usize,
 ) -> TokenStream {
     let machine_ident = parse_macro_input!(attr as Ident);
-    let item_impl = parse_macro_input!(item as ItemImpl);
     let struct_ident = &item_impl.self_ty;
     let persisted_type_display = struct_ident.to_token_stream().to_string();
     let machine_name = machine_ident.to_string();

statum-macros/src/validators/resolution.rs

@@ -2,7 +2,7 @@ use proc_macro2::TokenStream;
 use quote::quote;
 use syn::Ident;
 
-use macro_registry::callsite::current_source_info;
+use macro_registry::callsite::{current_source_info, source_info_for_span_or_callsite};
 use macro_registry::query;
 
 use crate::{
@@ -14,12 +14,14 @@ pub(super) fn resolve_machine_metadata(
     module_path: &str,
     machine_ident: &Ident,
 ) -> Result<MachineInfo, TokenStream> {
+    let source_info = source_info_for_span_or_callsite(machine_ident.span());
     let module_path_key: MachinePath = module_path.into();
     let machine_name = machine_ident.to_string();
     lookup_loaded_machine_in_module(&module_path_key, &machine_name).map_err(|failure| {
-        let current_line = current_source_info().map(|(_, line)| line).unwrap_or_default();
-        let available = available_machine_candidates_in_module(module_path);
-        let same_named_elsewhere = same_named_machine_candidates_elsewhere(&machine_name, module_path);
+        let current_line = source_info.as_ref().map(|(_, line)| *line).unwrap_or_default();
+        let available = available_machine_candidates_in_module(source_info.as_ref(), module_path);
+        let same_named_elsewhere =
+            same_named_machine_candidates_elsewhere(source_info.as_ref(), &machine_name, module_path);
         let loaded_same_named_elsewhere =
             same_named_loaded_machines_elsewhere(&module_path_key, &machine_name);
         let suggested_machine_name = available
@@ -72,11 +74,14 @@ pub(super) fn resolve_machine_metadata(
         } else {
             String::new()
         };
-        let missing_attr_line = plain_struct_line_in_module(module_path, &machine_name).map(|line| {
-            format!(
-                "A struct named `{machine_name}` exists on line {line}, but it is not annotated with `#[machine]`."
-            )
-        });
+        let missing_attr_line =
+            plain_struct_line_in_module(source_info.as_ref(), module_path, &machine_name).map(
+                |line| {
+                    format!(
+                        "A struct named `{machine_name}` exists on line {line}, but it is not annotated with `#[machine]`."
+                    )
+                },
+            );
         let authority_line = match failure {
             LoadedMachineLookupFailure::NotFound => {
                 "Statum only resolves `#[machine]` items that have already expanded before this `#[validators]` impl.".to_string()
@@ -96,18 +101,28 @@ pub(super) fn resolve_machine_metadata(
     })
 }
 
-fn available_machine_candidates_in_module(module_path: &str) -> Vec<query::ItemCandidate> {
-    let Some((file_path, _)) = current_source_info() else {
+fn source_file_from_info(source_info: Option<&(String, usize)>) -> Option<String> {
+    source_info
+        .map(|(file_path, _)| file_path.clone())
+        .or_else(|| current_source_info().map(|(file_path, _)| file_path))
+}
+
+fn available_machine_candidates_in_module(
+    source_info: Option<&(String, usize)>,
+    module_path: &str,
+) -> Vec<query::ItemCandidate> {
+    let Some(file_path) = source_file_from_info(source_info) else {
         return Vec::new();
     };
     query::candidates_in_module(&file_path, module_path, query::ItemKind::Struct, Some("machine"))
 }
 
 fn same_named_machine_candidates_elsewhere(
+    source_info: Option<&(String, usize)>,
     machine_name: &str,
     module_path: &str,
 ) -> Option<Vec<query::ItemCandidate>> {
-    let (file_path, _) = current_source_info()?;
+    let file_path = source_file_from_info(source_info)?;
     let candidates = query::same_named_candidates_elsewhere(
         &file_path,
         module_path,
@@ -118,8 +133,12 @@ fn same_named_machine_candidates_elsewhere(
     (!candidates.is_empty()).then_some(candidates)
 }
 
-fn plain_struct_line_in_module(module_path: &str, struct_name: &str) -> Option<usize> {
-    let (file_path, _) = current_source_info()?;
+fn plain_struct_line_in_module(
+    source_info: Option<&(String, usize)>,
+    module_path: &str,
+    struct_name: &str,
+) -> Option<usize> {
+    let file_path = source_file_from_info(source_info)?;
     query::plain_item_line_in_module(
         &file_path,
         module_path,

statum-macros/tests/macro_errors.rs

@@ -153,6 +153,7 @@ fn test_valid_macro_usage() {
     t.pass("tests/ui/valid_same_names_different_modules.rs");
     t.pass("tests/ui/valid_transition_nested_wrappers.rs");
     t.pass("tests/ui/valid_transition_branch.rs");
+    t.pass("tests/ui/valid_quick_start.rs");
     t.pass("tests/ui/valid_transition_include.rs");
     t.pass("tests/ui/valid_into_machines_by.rs");
     t.pass("tests/ui/valid_transition_map.rs");