{"record":{"id":"50b6c24865048807","repo":"sinelaw/fresh","slug":"syn-error-new-span-message","errorCode":null,"errorMessage":"syn::Error::new(span, message)","messagePattern":"syn::Error::new\\(span, message\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/fresh-plugin-api-macros/src/lib.rs","lineNumber":102,"sourceCode":"//! 2. **Explicit Over Implicit**: No magic naming conventions, use attributes\n//! 3. **Deterministic Output**: Same input always produces same output\n//! 4. **Preserve Original Code**: Macro passes through impl block unchanged\n//! 5. **Clear Errors**: Compile-time errors with helpful messages\n\nuse proc_macro::TokenStream;\nuse quote::{format_ident, quote};\nuse syn::{\n    parse_macro_input, spanned::Spanned, Attribute, FnArg, GenericArgument, ImplItem, ImplItemFn,\n    ItemImpl, Meta, Pat, PathArguments, ReturnType, Type,\n};\n\n// ============================================================================\n// Error Handling\n// ============================================================================\n\n/// Create a compile error with a helpful message and source span\nfn compile_error(span: proc_macro2::Span, message: &str) -> proc_macro2::TokenStream {\n    syn::Error::new(span, message).to_compile_error()\n}\n\n// ============================================================================\n// API Method Classification\n// ============================================================================\n\n/// Classification of API method return behavior\n#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum ApiKind {\n    /// Synchronous method - returns value directly\n    Sync,\n    /// Async method returning `Promise<T>`\n    AsyncPromise,\n    /// Async method returning `ProcessHandle<T>` (cancellable)\n    AsyncThenable,\n}\n\nimpl ApiKind {","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/sinelaw/fresh/blob/67894ca5463dbd7a89bb31add4627c27d6b79d83/crates/fresh-plugin-api-macros/src/lib.rs#L84-L120","documentation":"This is the macro crate's helper that converts a `syn::Error` into a `proc_macro2::TokenStream` compile error, so any classification/validation failure in `plugin_api_impl` surfaces at compile time with the offending span. The message shown is the generic constructor call site; the actual text comes from the macro's validation logic.","triggerScenarios":"Using the `plugin_api!` (or equivalent) macro on an item the macro cannot classify — e.g. a trait method whose signature doesn't match expected patterns, unsupported types, or malformed API definitions.","commonSituations":"Plugin authors writing an API method with an unsupported parameter/return type; misplacing attributes the macro expects; upgrading the macro crate and using newly rejected shapes.","solutions":["Read the accompanying compiler message at the pointed span and fix the offending token","Match the API method signature patterns documented for the macro (supported arg/return types)","Check the macro crate's docs/examples for the accepted item shape","File an issue if a valid signature is wrongly rejected"],"exampleFix":"// before\nfn read(&self, cb: fn(Vec<u8>));\n// after\nfn read(&self, cb: fn(PluginResult<Vec<u8>>));","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// This is a compile-time error: fix the macro input; cannot be caught at runtime.\n// Read the spanned message from cargo output and adjust the API definition to match\n// the macro's supported method shapes.","preventionTips":["Copy method signatures from the macro crate's documented examples","Avoid exotic parameter/return types in plugin API definitions","Run cargo check early and often when authoring plugin APIs","Pin and read the changelog when upgrading the macro crate for newly rejected shapes"],"tags":["rust","proc-macro","compile-time"],"backgroundTag":"schema-validation-failed","analyzedSha":"67894ca5463dbd7a89bb31add4627c27d6b79d83","analyzedAt":"2026-09-13T15:04:03.701Z","contentChangedAt":"2026-09-13T15:04:03.701Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}