feat(gts-macros): implement GtsSchema derive macro with gts(...) struct/field attributes

Replaces the prior plan for a future attribute-macro rewrite with a shipped
derive macro. `#[derive(GtsSchema)]` + `#[gts(...)]` helper attributes live
alongside the existing `#[struct_to_gts_schema]` attribute macro; coexistence
is the steady state, deprecation and removal are out of scope.

Highlights:
- Struct-level `#[gts(dir_path, schema_id, description, extends)]` and
  field-level `#[gts(type_field | instance_id | skip)]` attribute grammar.
- Identity-field rule enforced at compile time: every root struct declares
  exactly one of `type_field` / `instance_id`; derived structs (`extends =
  Parent`) declare neither. `extends = None` is an equivalent explicit root
  marker.
- Generated `pub fn new(...)` constructor on every named-field struct.
  `type_field` auto-populated from `GtsSchemaId::new(<P as GtsSchema>::SCHEMA_ID)`
  (generic root) or `Self::gts_schema_id().clone()` (non-generic root);
  `instance_id` passed by the caller.
- Unconditional block on direct `Serialize` / `Deserialize` on derived
  structs via the `GtsNoDirectSerialize` / `GtsNoDirectDeserialize` marker
  traits. No opt-out attribute.
- Spec-correct `"x-gts-ref": "/$id"` on identity fields; generic
  `"x-gts-ref": "gts.*"` retained for other `GtsSchemaId` fields.
- `description` now emitted into runtime schemas via
  `gts_schema_with_refs()`.
- Per-field serde rename in the nested deserializer (replaces the prior
  `rename_all = "snake_case"` blanket).

Docs:
- New ADR (`docs/001-gts-schema-derive-macro-adr.md`).
- Migration guide (`docs/002-struct-to-gts-schema-migration.md`) describing
  the old/new diff, schema-output parity, compile-fail fixture mapping, and
  the coexistence stance.
- Implementation plan (`docs/002-macro-migration-implementation-plan.md`).
- Old `001-macro-proposal.md` / `001-macro-alignment-*.md` superseded and
  removed.
- `gts-macros/README.md` rewritten around the derive macro, with the old
  macro presented as legacy.

Tests (all suites green, ~104 tests + 24 trybuild fixtures):
- `v2_compile_fail/` — compile-time rejection of invalid configurations
  (missing identity, wrong field types, schema-ID format, inheritance
  mismatches, direct-serde on nested, etc.).
- `v2_integration_tests` — runtime API + schema output for base structs,
  incl. generated-constructor behavior.
- `v2_inheritance_tests` — multi-level inheritance chains.
- `v2_serialization_tests` — `Serialize` / `Deserialize` round-trips through
  the `GtsSerialize` bridge.
- `v2_serde_rename_tests` — per-field `#[serde(rename)]` handling.
- `v2_parity_tests` — identical output vs `#[struct_to_gts_schema]` on
  equivalent structs (with the `x-gts-ref: "/$id"` improvement noted
  above).
- `v2_inheritance_tests_mixed` — interop between old and new macros.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Andre Smith <andre.smith@acronis.com>

Author: Andre Smith

docs/001-gts-schema-derive-macro-adr.md

@@ -0,0 +1,149 @@
+//! Parsing for `#[gts(...)]` struct-level attributes.
+//!
+//! Parses the top-level `#[gts(...)]` attribute on a struct into [`GtsAttrs`],
+//! which contains the schema metadata needed for `#[derive(GtsSchema)]`.
+
+use syn::{LitStr, Token, parse::ParseStream};
+
+/// Parsed struct-level `#[gts(...)]` attributes.
+pub struct GtsAttrs {
+    pub dir_path: String,
+    pub schema_id: String,
+    pub description: String,
+    pub extends: Option<syn::Ident>,
+}
+
+impl GtsAttrs {
+    /// Parse `#[gts(...)]` from the attributes on a `DeriveInput`.
+    ///
+    /// Returns an error if:
+    /// - No `#[gts(...)]` attribute is found
+    /// - Required keys (`dir_path`, `schema_id`, `description`) are missing
+    /// - Unknown keys are present
+    pub fn from_derive_input(input: &syn::DeriveInput) -> syn::Result<Self> {
+        let gts_attr = input
+            .attrs
+            .iter()
+            .find(|attr| attr.path().is_ident("gts"))
+            .ok_or_else(|| {
+                syn::Error::new_spanned(
+                    &input.ident,
+                    "GtsSchema: missing #[gts(...)] attribute. Add #[gts(dir_path = \"...\", schema_id = \"...\", description = \"...\")]",
+                )
+            })?;
+
+        gts_attr.parse_args_with(|stream: ParseStream| Self::parse_inner(stream, &input.ident))
+    }
+
+    fn parse_inner(input: ParseStream, struct_ident: &syn::Ident) -> syn::Result<Self> {
+        let mut dir_path: Option<String> = None;
+        let mut schema_id: Option<String> = None;
+        let mut description: Option<String> = None;
+        let mut extends: Option<syn::Ident> = None;
+
+        // Tracks which keys have already been parsed so duplicates emit a clear error
+        // rather than silently overwriting.
+        let mut seen_extends = false;
+
+        while !input.is_empty() {
+            let key: syn::Ident = input.parse()?;
+            let key_str = key.to_string();
+
+            match key_str.as_str() {
+                "dir_path" => {
+                    if dir_path.is_some() {
+                        return Err(syn::Error::new_spanned(
+                            key,
+                            "GtsSchema: duplicate attribute 'dir_path'",
+                        ));
+                    }
+                    input.parse::<Token![=]>()?;
+                    let value: LitStr = input.parse()?;
+                    dir_path = Some(value.value());
+                }
+                "schema_id" => {
+                    if schema_id.is_some() {
+                        return Err(syn::Error::new_spanned(
+                            key,
+                            "GtsSchema: duplicate attribute 'schema_id'",
+                        ));
+                    }
+                    input.parse::<Token![=]>()?;
+                    let value: LitStr = input.parse()?;
+                    schema_id = Some(value.value());
+                }
+                "description" => {
+                    if description.is_some() {
+                        return Err(syn::Error::new_spanned(
+                            key,
+                            "GtsSchema: duplicate attribute 'description'",
+                        ));
+                    }
+                    input.parse::<Token![=]>()?;
+                    let value: LitStr = input.parse()?;
+                    description = Some(value.value());
+                }
+                "extends" => {
+                    if seen_extends {
+                        return Err(syn::Error::new_spanned(
+                            key,
+                            "GtsSchema: duplicate attribute 'extends'",
+                        ));
+                    }
+                    seen_extends = true;
+                    input.parse::<Token![=]>()?;
+                    let ident: syn::Ident = input.parse()?;
+                    // `extends = None` is an explicit root-marker equivalent to omitting
+                    // `extends` — ADR §Struct-Level Attributes. Both forms leave `extends`
+                    // unset and are treated identically downstream.
+                    if ident == "None" {
+                        extends = None;
+                    } else {
+                        extends = Some(ident);
+                    }
+                }
+                _ => {
+                    return Err(syn::Error::new_spanned(
+                        key,
+                        format!(
+                            "GtsSchema: unknown attribute '{key_str}'. \
+                             Expected: dir_path, schema_id, description, or extends"
+                        ),
+                    ));
+                }
+            }
+
+            if !input.is_empty() {
+                if !input.peek(Token![,]) {
+                    return Err(syn::Error::new(
+                        input.span(),
+                        "GtsSchema: expected `,` between attributes",
+                    ));
+                }
+                input.parse::<Token![,]>()?;
+            }
+        }
+
+        Ok(GtsAttrs {
+            dir_path: dir_path.ok_or_else(|| {
+                syn::Error::new_spanned(
+                    struct_ident,
+                    "GtsSchema: missing required attribute 'dir_path' in #[gts(...)]",
+                )
+            })?,
+            schema_id: schema_id.ok_or_else(|| {
+                syn::Error::new_spanned(
+                    struct_ident,
+                    "GtsSchema: missing required attribute 'schema_id' in #[gts(...)]",
+                )
+            })?,
+            description: description.ok_or_else(|| {
+                syn::Error::new_spanned(
+                    struct_ident,
+                    "GtsSchema: missing required attribute 'description' in #[gts(...)]",
+                )
+            })?,
+            extends,
+        })
+    }
+}