1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
//! What an ATTRIBUTE macro does that a derive cannot: it owns the item it sits on.
//!
//! A derive is handed a copy and may only append. An attribute macro is handed the item and emits
//! whatever it likes in its place — so the declaration a user writes and the declaration the
//! compiler sees are allowed to differ, which is the whole reason this family pivoted. Two things
//! need it, and neither is expressible under a derive:
//!
//! * the INJECTED PROJECTION FIELD, `__ig_key__: <Upstream as Transformer>::Key`, which is how a
//! derived index carries an identity it does not mint;
//! * the VISIBILITY CONVENTION, which stops being the author's pen: a field written with no
//! visibility at all gets `pub(crate)`, because a declaration's fields are read by the emitted
//! code and by the crate around it, and making every author write the word was a convention
//! nothing enforced.
//!
//! What this module does NOT do is decide anything. It echoes the host, strips what the macro
//! consumed, and hands the arguments to the same grammar the derives already parsed — one form
//! change, no rules moved.
use ToTokens as _;
use crateErrors;
/// The attribute this family's field markers are written in, and the one an echo consumes.
const ATTRIBUTE: &str = "ingraph";
/// The macro's own arguments, as the ATTRIBUTE LIST the grammar already reads.
///
/// `#[ingraph::record(sqlite)]` and the derive's `#[ingraph(sqlite)]` carry the
/// same tokens in the same shape, so the arguments are wrapped back into one synthetic attribute and
/// every rule downstream is the rule that was already there. The pivot is a change of ENTRY POINT
/// and not of grammar, and this is the line that keeps it one.
///
/// Empty arguments produce no attribute rather than an empty one: `#[ingraph::operator]` is the
/// declaration that says nothing, and a walk over an empty list would have to special-case it.
pub
/// The record-level attribute, written where it used to live.
///
/// A named MIGRATION rather than a silent strip: under the derive the options sat in an
/// `#[ingraph(…)]` beside it, and an author who moves a declaration across will bring one. The
/// tokens are still legal, so nothing else would report this — the attribute would be stripped by
/// the echo and the options would vanish without a word.
pub
/// The host, re-emitted: the author's item with what the macro consumed taken out and the
/// visibility convention stamped in.
///
/// EVERYTHING ELSE SURVIVES VERBATIM — the user's own derives, their `cfg`s, their doc comments,
/// their generics, their field order. An attribute macro replaces the item it sits on, so anything
/// this function drops is dropped from the program, and the list of what it deliberately drops is
/// exactly one thing: the `#[ingraph(…)]` markers it read.
///
/// The VISIBILITY rule is per field and one-directional. A field written with no visibility gets
/// `pub(crate)`; a field written with any visibility at all — `pub`, `pub(super)`, or `pub(crate)`
/// spelled by hand — keeps what it says. So the convention has a default and never an override:
/// nothing here can narrow what an author widened, which is the property that makes stamping safe
/// to do silently.
pub
/// The host with ONE field added — the injection, and the whole reason an attribute macro was
/// needed.
///
/// TWO declarations reach it, and they inject for the same reason at two grains. A derived index
/// mints no id, so the two members its entity binding has to answer — the key, and the id inside it
/// — have nothing in the declaration to be read from; γ′ is what they are read from, and a derive
/// could not have put it there. A resource written with a BUILTIN KIND WORD names an engine this
/// framework ships, so the engine itself is not the author's to write; the injected field is where
/// the expansion puts the one it mints.
///
/// The field is the EMITTER's own mint, handed in whole rather than described, so its name, its type
/// and its visibility are decided in the one place that also reads them back — see
/// `IndexModel::carried_key` and `ResourceKind::engine_field`.
///
/// It goes on the END rather than the front, and the position is load-bearing exactly once: a
/// derived index's constructor takes the key FIRST, so the two orders differ, and a caller who
/// confuses a positional struct literal with the constructor is writing something the injection has
/// already made impossible to compile.
///
/// # A UNIT declaration GROWS the brace it has none of
///
/// `pub struct Ft;` is the shape a builtin resource is written in — the author states that the type
/// is the engine and nothing else — so there is no field list to append to, and the injection makes
/// one. That is the injection saying what it means rather than a special case: the declaration the
/// author wrote and the declaration the compiler sees are allowed to differ, and here they differ by
/// exactly the field the macro owns.
pub
/// The host of a REWRITE — the author's item REPLACED by the transparent wrapper the macro owns.
///
/// This is the one thing only an attribute macro can do, taken to its end: the declaration a user
/// writes and the declaration the compiler sees are allowed to differ, and here they differ
/// completely. What the author wrote is a MANIFEST — the shape of `remote`, restated so this
/// framework can read it — and what the compiler sees is one unnamed position holding that type.
///
/// `#[repr(transparent)]` is the emission's own, and it is load-bearing: it is what makes the
/// reference family emitted beside this a fact of the LANGUAGE rather than a layout claim. An
/// author's own `#[repr(…)]` is refused before this is reached — see
/// [`crate::remote::refuse_a_representation`].
///
/// Every OTHER item attribute is forwarded verbatim and in order, which is the family's law rather
/// than this position's exception: an attribute this grammar does not own is not this grammar's to
/// read. The author's `#[derive(…)]` lands on the wrapper, where a 1-tuple's derives delegate to
/// the field — which is exactly what makes `Borrow`'s `Eq`/`Hash` agreement below hold.
///
/// The field is PRIVATE. Everything that reaches the wrapped value goes through an emitted door —
/// `Deref`, `AsRef`, `Borrow`, `From` — so a public position would be a second, unversioned one.
pub
/// The host of a declaration that is a VOCABULARY rather than DATA — echoed with the `dead_code`
/// lint turned off over it, and with the reason written into the attribute.
///
/// A mutation node is the case, and it is not a workaround. Its fields are EXCHANGES: each one's
/// type states what is sent and what comes back, and the words beside it state who runs it. Nothing
/// ever holds a value of the node, because there is nothing a value of it could mean — the emission
/// reads the fields' TYPES and the resolvers it writes take their arguments off the wire. So rustc's
/// *never constructed* is a true observation about a thing that is true of the whole tier, reported
/// inside an expansion the author cannot edit and about a shape the framework asked them to write.
///
/// The lint is turned off HERE — on the echoed host, as narrowly as the tool allows — rather than by
/// the emission naming the fields in some audit, which was the other candidate: an audit would make
/// the silence a side effect of an unrelated item, and a reader finding it would have no way to tell
/// it was deliberate. The `reason` is what makes this one self-describing.
pub
/// One body for both: strip, stamp, and append whatever the macro is adding.
///
/// The injection lands AFTER the stamp, and the order is not incidental. The stamp is a rule about
/// what an AUTHOR wrote — a field with no visibility gets `pub(crate)` — and a field the author did
/// not write is not that; it arrives already spelled, and running the convention over it would make
/// the mint's own decision depend on a rule about somebody else's pen.
/// Put the minted field into the declaration, growing the brace where there is none to put it in.
///
/// A NAMED host takes it at the end. A UNIT host has no field list at all, so one is made and the
/// terminating `;` goes with it — a struct with a brace and a semicolon is not a declaration, and
/// leaving the token would be this function emitting something that does not parse.
///
/// A TUPLE host is left alone, which is the honest answer rather than an omission: the field arrives
/// NAMED, and the two callers that mint one both refuse a host they cannot put a named field in
/// before they ever ask for one. Appending it here would mean inventing a positional form of
/// somebody else's mint.
/// One field list: the markers taken out, and — where the host is one whose fields carry a
/// visibility of their own — the convention stamped in.
/// A DERIVE-SHAPED declaration split into what the attribute form takes separately: the item, and
/// the `#[ingraph(…)]` attributes beside it read as the macro's arguments.
///
/// For the unit suites alone, and it earns its place there. Every assertion below the entry points
/// is about the GRAMMAR — which words a block takes, what each refusal says — and the pivot moved
/// none of that; it moved where the tokens arrive. Splitting here is what lets those suites keep
/// spelling a declaration in one piece, so a test that changed is a test whose RULE changed. What
/// the entry point itself does is asserted where it can only be asserted: by the corpus, which
/// compiles real attribute-form declarations.
pub