ingraph-derive 0.1.0

The attribute and derive macros for ingraph: the words a record, node, key, filter and vocabulary declaration is written in.
Documentation
//! The REWRITE MODE's front half — what `remote = "…"` does to the item the macro sits on.
//!
//! Every other word in this grammar adds a fact BESIDE the declaration. This one changes what the
//! declaration IS: the fields the author wrote stop being the type's own storage and become a
//! MANIFEST — the shape of a foreign type, restated so this framework can read it — and the item
//! the compiler sees becomes
//!
//! ```text
//! #[repr(transparent)]
//! pub struct Dimensions(mediaframe::Dimensions);
//! ```
//!
//! The orphan rule is why the restatement exists at all: a type another crate owns cannot be given
//! this framework's faces where it is declared, and a wrapper is the position where it can. The
//! wrapper is TRANSPARENT so that the reference family below it — `Deref`, `AsRef`, `Borrow` and
//! their mutable halves — is the language's own guarantee rather than a layout claim: `self.0` is a
//! field access, and no `transmute` is written anywhere in this device. The size/align-plus-
//! `transmute` alternative was examined and refused on soundness — a `repr(Rust)` layout is not
//! verifiable from outside, and `offset_of!` cannot name a private field of a foreign type — and
//! that refusal is settled rather than open.
//!
//! # What is checked HERE, and what the compiler is left to check
//!
//! This module owns the two rules about ATTRIBUTES, because both are about tokens the rewrite would
//! otherwise swallow. Everything else the mode demands is an API-surface fact about a type this
//! crate cannot see — the remote has an accessor per manifest field, of a type that crosses — and
//! those are checked where they are spent, by the compiler, at spans the emission puts on the
//! author's own tokens. See `ingraph_codegen::remote`, which writes them.

use crate::errors::Errors;

/// The attribute the macro's own markers are written in.
const ATTRIBUTE: &str = "ingraph";

/// The one item attribute a rewrite may not carry.
const REPRESENTATION: &str = "repr";

/// The two attributes a manifest field may carry BESIDES a doc comment.
///
/// `cfg` states whether the field exists, and the CONDITION SEAT carries it to every artifact the
/// field mints; `cfg_attr` decorates, and rides the reader beside the docs. Both are read by
/// [`crate::attribute::condition`], which is where the family-level rule lives — this list is only
/// what [`refuse_an_unplaceable_attribute`] must not refuse.
const CONDITIONAL: [&str; 2] = ["cfg", "cfg_attr"];

/// Whether an attribute is a doc comment — `///` or the `#[doc = "…"]` it desugars to.
fn is_doc(attr: &syn::Attribute) -> bool {
  attr.path().is_ident("doc")
}

/// Whether an attribute is this macro's own, and therefore consumed rather than carried.
fn is_ours(attr: &syn::Attribute) -> bool {
  attr.path().is_ident(ATTRIBUTE)
}

/// The item attributes a rewrite CARRIES onto the wrapper, in the order they were written.
///
/// The family law, applied at the one position that rewrites: a non-`ingraph` attribute is
/// forwarded VERBATIM and in order, so an author's `#[derive(…)]`, their `#[cfg]`, their `///` and
/// anything a third-party macro reads all land on the item the compiler sees. Nothing is
/// interpreted — an attribute this grammar does not own is not this grammar's to read.
///
/// Only two things do not come through: the `#[ingraph(…)]` markers, which are the macro's own and
/// were read, and a `#[repr(…)]` — refused by [`refuse_a_representation`] before this is ever
/// reached, so the filter here would be unreachable and is deliberately not written.
pub(crate) fn forwarded(attrs: &[syn::Attribute]) -> Vec<syn::Attribute> {
  attrs
    .iter()
    .filter(|attr| !is_ours(attr))
    .cloned()
    .collect()
}

/// A manifest field's doc comments, for the reader they migrate onto.
///
/// The field is about to stop existing, so its documentation has to be carried or deleted. It is
/// carried to the READER — the method that answers what the field held — which is the one place in
/// the rewritten item where that field's meaning is still a question somebody can ask.
///
/// It does NOT reach the wire face. What a schema publishes is `attrs(desc = "…")` and nothing
/// else, which is a standing law of this grammar rather than a gap: *what reaches a schema is what
/// a declaration says reaches it*. A rewrite is not the occasion to overturn it.
pub(crate) fn docs(field: &syn::Field) -> Vec<syn::Attribute> {
  field
    .attrs
    .iter()
    .filter(|attr| is_doc(attr))
    .cloned()
    .collect()
}

/// **THE MACRO OWNS THE REPRESENTATION** — a hand-written `#[repr(…)]` on a rewrite is refused.
///
/// `#[repr(transparent)]` is not decoration here; it is the premise the whole reference family
/// stands on. An author's own `#[repr(…)]` would either be overwritten silently or emitted beside
/// this macro's and refused by rustc inside an expansion, and both of those are worse than saying
/// so at the token that wrote it.
pub(crate) fn refuse_a_representation(attrs: &[syn::Attribute], errors: &mut Errors) {
  for attr in attrs
    .iter()
    .filter(|attr| attr.path().is_ident(REPRESENTATION))
  {
    errors.push(syn::Error::new_spanned(
      attr,
      "a declaration wrapping a foreign type does not choose its own representation — the macro \
       emits `#[repr(transparent)]`, and that is what makes `Deref`, `AsRef` and `Borrow` sound \
       here rather than a layout claim nobody can verify. Delete this attribute",
    ));
  }
}

/// **A MANIFEST FIELD HAS NO REAL BODY TO CARRY AN ATTRIBUTE**, so one that is not placeable is
/// refused by name rather than swallowed.
///
/// Three answers, and each is about where the attribute could LAND:
///
/// * a doc comment MIGRATES — see [`docs`] — so it is silently accepted here;
/// * `cfg` and `cfg_attr` are the CONDITION, read by [`crate::attribute::condition`] — the first
///   reaching the field's WHOLE generated family and the second riding its reader, so both have a
///   destination and neither is refused. That is what the earlier refuse-until promised and what the
///   condition seat made true: a `cfg` here takes the reader, the column in every database, the
///   filter seat, the order-by term and the place on the wire face, all together;
/// * anything else has no destination at all. The field is not emitted, so an attribute on it would
///   be read by nobody — and an attribute nobody reads is a rule its author believes they declared.
pub(crate) fn refuse_an_unplaceable_attribute(field: &syn::Field, errors: &mut Errors) {
  for attr in &field.attrs {
    if is_ours(attr) || is_doc(attr) {
      continue;
    }
    if CONDITIONAL.iter().any(|word| attr.path().is_ident(word)) {
      continue;
    }
    errors.push(syn::Error::new_spanned(
      attr,
      "a field of a declaration that WRAPS a foreign type is a MANIFEST entry — it states what the \
       wrapped type holds, and no field is emitted for it — so there is nothing here for this \
       attribute to sit on. Doc comments migrate to the field's reader; everything else belongs on \
       the item, where it is forwarded verbatim",
    ));
  }
}

#[cfg(test)]
mod tests;