Macro diag 

diag!() { /* proc-macro */ }

Define complete diagnostic metadata with full 4-part error codes.

This macro generates THREE constants:

1. E_COMPONENT_PRIMARY_SEQUENCE - Runtime metadata (always present)
2. E_COMPONENT_PRIMARY_SEQUENCE_DOCS - Compile-time docs (with metadata feature)
3. E_COMPONENT_PRIMARY_SEQUENCE_COMPLETE - Combined (with metadata feature)

4-Part Code Format

Severity.Component.Primary.Sequence

Visibility Markers

Fields can have visibility markers to control where they’re included:

• 'C - Compile-time only (documentation generation, not in binary)
• 'R - Runtime only (in production binary, not in docs)
• 'RC or 'CR - Both (default for most fields)

Mnemonic: 'CR = Compile + Runtime (both contexts)

Supported Fields (in any order)

Core fields (always present):

• message (required) - Message template with {{field}} placeholders
• fields (optional) - Array of non-PII field names used in message (referenced as {{field}})
• pii (optional) - Array of PII field names (referenced as {{pii/field}} in message)
• severity (optional) - Override the severity from the code

Fields with visibility markers:

• description ['C|'R|'RC|'CR] - Human-readable description
• hints ['C|'R|'RC|'CR] - Array of helpful hints
• role ['R|'RC|'CR] - Role-based visibility
• tags ['R] - Categorization tags (runtime only)
• related_codes ['R] - Related error codes (runtime only)
• code_snippet ['C] - Code examples (compile-time only)
• docs_url ['C] - Documentation URL (compile-time only)
• introduced ['C] - Version introduced (compile-time only)
• deprecated ['C] - Deprecation notice (compile-time only)

Examples

Basic usage (defaults to ’RC - both contexts):

diag! {
    Error.Auth.Token.MISSING: {
        message: "Token '{{token}}' not found",
        fields: [token],
        description: "API token missing",  // Available in both
        hints: ["Check your credentials"],  // Available in both
    },
}

With PII fields:

diag! {
    Error.Auth.Login.FAILED: {
        message: "Login failed for {{pii/email}} at {{timestamp}}",
        fields: [timestamp],           // Non-PII: goes to `f` in wire protocol
        pii: [email],                  // PII: goes to `pii.data` in wire protocol
        description: "Authentication failed",
    },
}

Advanced usage with visibility markers:

diag! {
    Error.Auth.Token.MISSING: {
        message: "Token '{{token}}' not found",
        fields: [token],

        // Verbose docs for compile-time
        description 'C: "Detailed explanation for documentation...",

        // Short message for runtime
        description 'R: "Token missing",

        // Different hints for different audiences
        hints 'C: ["For developers: Check auth flow", "See RFC 6750"],
        hints 'R: ["Include Authorization header", "Verify API key"],
        hints 'CR: ["Contact support if needed"],  // 'RC also works

        // Runtime categorization
        role 'R: "Public",
        tags: ["auth", "security"],

        // Compile-time documentation
        code_snippet: {
            wrong: "fetch(url)",
            correct: "fetch(url, { headers: { 'Authorization': 'Bearer <token>' } })",
        },
        docs_url: "https://docs.example.com/auth",
        introduced: "1.0.0",
    },
}

Generated Code

This generates THREE constants:

// Always generated (no feature flags)
pub const E_AUTH_TOKEN_MISSING: DiagnosticRuntime = /* runtime metadata */;

// Only with metadata feature
#[cfg(feature = "metadata")]
pub const E_AUTH_TOKEN_MISSING_DOCS: DiagnosticDocs = /* compile-time docs */;

#[cfg(feature = "metadata")]
pub const E_AUTH_TOKEN_MISSING_COMPLETE: DiagnosticComplete = /* both */;

Frameworks can use the runtime constant for error handling, and the complete constant for documentation generation.