devscout_rs/extract/types.rs
1// ---------------------------------------------------------------------------
2// Graph fragment extraction and its helpers. Scope: defs =
3// namespace-level+nested types with public method names plus enum members;
4// refs = using directives, base-list types,
5// object-creation types, field/property/parameter/return types, generic
6// type arguments, and member-access qualifier.member candidates. No
7// call-graph resolution.
8// ---------------------------------------------------------------------------
9
10/// Represents `DefRecord`.
11pub struct DefRecord {
12 /// The id value.
13 pub id: String,
14 /// The name value.
15 pub name: String,
16 /// The namespace value.
17 pub namespace: String,
18 /// The kind value.
19 pub kind: String,
20 /// The line value.
21 pub line: usize,
22 /// The methods value.
23 pub methods: Vec<String>,
24 /// Declared property names, source order, deduped
25 /// (indexers excluded by construction: `indexer_declaration` is a
26 /// different grammar node). NO accessibility filter, deliberately
27 /// asymmetric with `methods`: static/const/readonly/expression-bodied all
28 /// count and only indexers are excluded, so a private member is still a
29 /// member of the type. Empty for every
30 /// enum-member def.
31 pub properties: Vec<String>,
32 /// Declared field names, source order, deduped, every
33 /// declarator of every `field_declaration` ("private int a, b;"
34 /// contributes both). `event_field_declaration` is a distinct node type
35 /// and is NOT a field for this purpose. Same no-accessibility-filter
36 /// rule as `properties`.
37 pub fields: Vec<String>,
38 /// (method name, declared return type NAME) pairs in
39 /// FIRST-declaration source order, parallel to `methods` (same
40 /// `is_recorded_method` predicate, so the two can never drift). The
41 /// first declaration of a name claims the slot outright: a later
42 /// overload with a different return type is ignored, and a first
43 /// declaration whose return type yields no fact (void, var, a
44 /// predefined type) BLOCKS the name rather than letting a later
45 /// overload stand in for it. A Vec of pairs, not a map: the serialized
46 /// key order is significant (see graph.rs's FragDef).
47 pub method_returns: Vec<(String, String)>,
48 /// The extension methods this type declares: every method
49 /// whose FIRST parameter carries the `this` modifier, in source order,
50 /// deduped by (name, thisType, arityMin, arityMax). Appended LAST, after
51 /// `method_returns`, and omitted at serialization when empty. Unlike
52 /// `methods` there is NO accessibility filter (`internal static class
53 /// FooExtensions` is the shape this feature exists for) and no `static`
54 /// check on either the method or its class -- C# already disallows a
55 /// `this` parameter anywhere else, so the parameter modifier IS the
56 /// discriminator.
57 pub extension_methods: Vec<ExtensionMethod>,
58 /// The DIRECT base-type identifiers this
59 /// declaration lists, in source order, deduped. Same base_list traversal
60 /// `record_base_list` walks for its `inherits` refs, reduced to a base
61 /// IDENTIFIER because the resolver re-RESOLVES these names through the
62 /// ordinary ladder rather than matching them; the resulting closure is
63 /// what lets the extension tier see an inherited instance member and
64 /// decline. Appended after `extension_methods` and omitted when empty.
65 pub bases: Vec<String>,
66 /// The declaring type's OWN type-parameter names (`class
67 /// MongoRepository<T>` records `["T"]`), empty for every non-generic
68 /// declaration. This is the ctor-DI resolver's "is this def itself an
69 /// open-generic implementation" signal. Appended after `bases`, omitted
70 /// when empty.
71 pub type_params: Vec<String>,
72 /// Per base name that carried a type-argument list, that
73 /// list's generic-arg descriptors relative to `type_params` (a `"*"`
74 /// wildcard marks a position that is a pass-through of the declaring
75 /// type's own parameter). A `Vec` of pairs, not a map, for the same
76 /// reason `method_returns` is: the serialized key order is significant.
77 /// Appended after `type_params`, omitted when empty; a base
78 /// with no type-argument list at all contributes no entry.
79 pub base_generic_args: Vec<(String, Vec<String>)>,
80 /// The methods this type declares that a test
81 /// framework would DISCOVER as tests, in source order, deduped. Appended
82 /// LAST, after `base_generic_args`, and omitted at serialization when
83 /// empty. The attribute IS the fact, which is why this is the one member
84 /// fact with no accessibility filter at all and why no file, folder or
85 /// type-name convention is read anywhere.
86 pub test_methods: Vec<String>,
87 /// (property name, declared type fact) pairs for exactly the
88 /// properties `properties` records, in the same source order and under the
89 /// same dedup. A property whose declared type yields no fact (a predefined
90 /// type) has no entry, so the two lists are parallel but not equal in
91 /// length. A `Vec` of pairs, not a map, for the same reason
92 /// `method_returns` is one: the serialized key order is significant.
93 /// Appended LAST, after `test_methods`.
94 pub property_types: Vec<(String, Fact)>,
95 /// (field name, declared type fact) pairs for exactly the
96 /// fields `fields` records, in the same source order and under the same
97 /// dedup. A field whose declared type yields no fact (a predefined type)
98 /// has no entry, so the two lists are parallel but not equal in length.
99 /// Every declarator of one `field_declaration` shares that declaration's
100 /// own type node, so `private int a, b;` gives `a` and `b` the SAME
101 /// fact -- the same declarator sharing `fields`'s own collection loop
102 /// already relies on. A `Vec` of pairs, not a map, for the same reason
103 /// `property_types` is one: the serialized key order is significant.
104 /// Appended LAST, after `property_types`.
105 pub field_types: Vec<(String, Fact)>,
106 /// Per method name that `method_returns` also records an
107 /// entry for, that return type's top-level generic-arg descriptors --
108 /// the same capture `base_generic_args` keeps beside `bases`, for the
109 /// same reason: `method_returns` records only the return type's bare
110 /// identifier ("Task" for `Task<Order> GetAsync()`), and this is what
111 /// lets the resolver unwrap ONE `Task<...>`/`ValueTask<...>` layer off
112 /// an AWAITED call's callee without ever touching `method_returns`
113 /// itself, which an unawaited use of the very same callee reads
114 /// unchanged. A `Vec` of pairs, not a map, for the same reason
115 /// `method_returns` is one: the serialized key order is significant.
116 /// Appended LAST of all, after `field_types`; a method whose return
117 /// type carries no type-argument list at all contributes no entry.
118 pub method_return_args: Vec<(String, Vec<String>)>,
119 /// Declared METHOD names this type does NOT record in `methods`,
120 /// because `is_recorded_method` gates that list on a literal `public`
121 /// modifier (or `kind == "interface"`, where every method already
122 /// counts as public and this list is always empty). Same predicate,
123 /// same `method_declaration` node kind, same source order and dedup as
124 /// `methods` -- the two lists partition a type's method declarations
125 /// with no overlap and no gap. Unlike `properties`/`fields`, which
126 /// already carry every accessibility with no filter at all, `methods`
127 /// needed a counterpart list for a non-public method (protected,
128 /// internal, private or no-modifier/private-by-default) to be
129 /// recorded anywhere. Consulted by the resolver ONLY for
130 /// hierarchy-internal receivers -- a `base.` lookup and the `this.`
131 /// shape's own typed-receiver walk -- never by the scored tier's
132 /// vouching or veto, which keep reading `methods` alone. Appended
133 /// LAST of all, after `method_return_args`.
134 pub non_public_methods: Vec<String>,
135 /// Method name -> the (min, max) argument-count RANGE every overload
136 /// sharing that name accepts, one tuple per overload, in declaration
137 /// order -- covers EVERY `method_declaration`, public and non-public
138 /// alike (unlike `methods`/`non_public_methods`, which only say a name
139 /// exists, this says what a CALL of that name needs to look like).
140 /// `min` excludes a parameter carrying a default value or the `params`
141 /// modifier; `max` is the total parameter count, or -1 (unbounded) when
142 /// the trailing parameter is a `params` array -- the same sentinel
143 /// `ExtensionMethod::arity_max` already uses. A `Vec` of pairs, not a
144 /// map, for the same reason `method_returns` is one: the serialized key
145 /// order is significant. Consulted by the resolver's arity-aware call
146 /// vouching: a ref carrying an `argCount` binds to `methods`/
147 /// `non_public_methods` only when SOME overload's range admits it: a
148 /// same-named instance member at the wrong arity does not shadow the
149 /// extension tier. A read (no `argCount`) never consults this table.
150 /// Appended LAST of all, after `non_public_methods`.
151 pub method_arities: Vec<(String, Vec<(usize, i64)>)>,
152 /// Method name -> per-overload parameter type descriptors (see
153 /// `type_descriptor`), one `Vec<String>` per overload in declaration
154 /// order -- covers EVERY `method_declaration`, public and non-public
155 /// alike, same method set as `method_arities`. A position naming the
156 /// enclosing method's or type's own type parameter is recorded as `"*"`
157 /// (wildcard); a parameter carrying the `this` modifier is written
158 /// `"this <descriptor>"` (the extension-method marker). For a
159 /// `delegate` def this carries exactly one entry, keyed `"Invoke"`,
160 /// built from the delegate's own parameter list (a delegate has no
161 /// body, so it is not one of the `method_declaration` overloads this
162 /// otherwise iterates). A `Vec` of pairs, not a map, for the same
163 /// reason `method_returns` is one: the serialized key order is
164 /// significant. Appended LAST of all, after `method_arities`.
165 pub method_params: Vec<(String, Vec<Vec<String>>)>,
166 /// 1-based last line of the complete declaration node.
167 pub end_line: usize,
168}
169
170/// One `extensionMethods` entry. Field order (`name`, `thisType`, `arityMin`,
171/// `arityMax`, `thisArgs`) is significant: it fixes the serialized field
172/// order.
173#[derive(Debug, Clone, PartialEq)]
174pub struct ExtensionMethod {
175 /// The name value.
176 pub name: String,
177 /// The this type value.
178 pub this_type: String,
179 /// Non-this parameters a caller cannot
180 /// leave out: no default value AND no `params` modifier.
181 pub arity_min: usize,
182 /// Total non-this parameter count, or -1 when the trailing parameter is a
183 /// `params` array (unbounded above). Signed precisely so -1 can be the
184 /// sentinel written as a JSON number.
185 pub arity_max: i64,
186 /// The this-parameter type's TOP-LEVEL
187 /// type-argument descriptors, present only when that type is generic.
188 /// A position naming one of the method's or the enclosing class's own type
189 /// parameters is recorded as "*" (wildcard).
190 pub this_args: Option<Vec<String>>,
191}
192
193/// Represents `RefRecord`.
194pub struct RefRecord {
195 /// The kind value.
196 pub kind: String,
197 /// The name value.
198 pub name: String,
199 /// The qualified value.
200 pub qualified: Option<String>,
201 /// The member value.
202 pub member: Option<String>,
203 /// The line value.
204 pub line: usize,
205 /// `None` only for 'imports' refs -- a using directive is not
206 /// namespace-scoped, so `ns` is deliberately `null`. Every other ref
207 /// carries `Some(ns)`, where `ns`
208 /// may itself be the empty string at file scope.
209 pub namespace: Option<String>,
210 /// The type arg count value.
211 pub type_arg_count: Option<usize>,
212 /// `true` when a uses-member qualifier carried a
213 /// type-argument list anywhere (`Cache<T>.x`, `Ns.Cache<T>.x`): syntax
214 /// only a TYPE can carry, so the resolver treats it as type-certainty
215 /// for non-enum member emission. Always `false` for every other ref
216 /// kind.
217 pub generic: bool,
218 /// The declared type NAME of the receiver a uses-member
219 /// qualifier names, when the enclosing scope holds exactly one fact for
220 /// it (a declared local, a `var x = new T()` local, a parameter, a
221 /// field, or a primary-constructor parameter). Set ONLY for a BARE,
222 /// non-generic qualifier -- see the `member_access_expression` arm's
223 /// guard, which is what makes the chain-tail hazard structurally
224 /// impossible. Always `None` for every other ref kind.
225 pub receiver_type: Option<String>,
226 /// The argument count of the call this
227 /// member access is the CALLEE of (`argument_list` named-child count),
228 /// recorded only when the access is the `function` field of an
229 /// `invocation_expression`. A property read (`x.P`) carries `None`, which
230 /// is what keeps it out of the arity-matched extension tier entirely.
231 /// Appended AFTER `receiver_type`. Always `None` for every other ref kind.
232 pub arg_count: Option<usize>,
233 /// The DECLARED receiver type's top-level
234 /// type-argument descriptors, present only when that type is generic. A
235 /// position naming a type parameter of the enclosing method or class is
236 /// recorded as "*" (wildcard): nothing at the fact site knows its binding.
237 /// Travels with `receiver_type` -- the fact carries both or neither.
238 /// Appended LAST, after `arg_count`.
239 pub receiver_args: Option<Vec<String>>,
240 /// The walk's own type_stack verbatim: the enclosing type simple
241 /// names, OUTERMOST first, the same order type_id joins with "+" to build
242 /// a nested def id. Empty at namespace level, and empty is exactly what an
243 /// absent key deserializes to. Appended LAST, after `receiver_args`.
244 pub outer_types: Vec<String>,
245 /// Generic-arg descriptors for a 'ctor-param' ref's
246 /// parameter type (same descriptor shape as `receiver_args`: a `"*"`
247 /// wildcard for a pass-through of the enclosing type's own type
248 /// parameter), present only when that type is generic. `None` for every
249 /// other ref kind. Appended LAST of all, after `outer_types` -- 'ctor-param'
250 /// is a ref kind no other caller touches, so putting it after that
251 /// "last of all" field costs no other ref kind a single byte.
252 pub args: Option<Vec<String>>,
253 /// The type whose PROPERTY the qualifier's last segment is, for
254 /// a two-segment chain whose head the enclosing scope has a fact for
255 /// ("a.Settings" in `a.Settings.Reload()`). Never travels with
256 /// `receiver_type`: that one is bare-qualifier-only and this one is
257 /// dotted-qualifier-only, which is what keeps the chain-tail hazard
258 /// structurally impossible -- the resolver reaches the tail's type through
259 /// the head type's RECORDED property types, never by inheriting the head's
260 /// own. Appended after `args`.
261 pub receiver_property_owner: Option<String>,
262 /// The type whose METHOD a `var x = Q.M(...)` initializer
263 /// called, and that method's name. Always set as a pair, and never
264 /// alongside `receiver_type`: the local's type is whatever `M` returns, a
265 /// lookup only the resolver can do. Appended LAST of all.
266 pub receiver_call_owner: Option<String>,
267 /// The receiver call member value.
268 pub receiver_call_member: Option<String>,
269 /// `true` for a `base.M` qualifier -- the member lookup starts at the
270 /// enclosing type's bases and never considers the enclosing type
271 /// itself. `false` for every other ref kind, including a plain `this.M`
272 /// qualifier (which resolves through the ordinary typed-receiver path
273 /// against the enclosing type itself). Appended LAST of all.
274 pub receiver_base: bool,
275 /// `true` when this ref's `receiver_call_owner`/`receiver_call_member`
276 /// pair came from an AWAITED call (`var x = await Q.M()`, `_client` a
277 /// field: `var order = await _client.FetchAsync()`) -- the resolver reads
278 /// it to decide whether to unwrap exactly one `Task<...>`/`ValueTask<...>`
279 /// layer off `M`'s recorded return type before typing the local. `false`
280 /// for an unawaited call fact and for every ref carrying no call fact at
281 /// all, which is what keeps `var t = x.FetchAsync(); t.Wait();` typed as
282 /// `Task` rather than unwrapped. Appended LAST of all, after
283 /// `receiver_base`.
284 pub receiver_awaited: bool,
285 /// `true` when this ref's qualifier is a bare identifier for which the
286 /// enclosing MEMBER's own fact table -- `Scope::has_local_fact`, the
287 /// SAME `member_facts` table `receiver_fact_for` reads first -- holds
288 /// ANY entry for the name: a local, a parameter, an explicitly-typed
289 /// lambda parameter, a pattern designation, or an `out` designation,
290 /// typed or taken-but-unknown. A member-scoped name always shadows a
291 /// same-named field regardless of whether anything vouches for its
292 /// type, so the resolver's bare-identifier field/property fallback
293 /// (Unit B) reads this to refuse running at all when it is `true` --
294 /// the one shape a resolved `receiver_type`/`receiver_call_owner` of
295 /// `None` cannot itself distinguish from "no fact anywhere for this
296 /// name". `false` for a dotted or generic qualifier, for `this.`/
297 /// `base.` (never asked of the enclosing scope's local table), and for
298 /// every ref kind but `uses-member`. Appended LAST of all, after
299 /// `receiver_awaited`.
300 pub receiver_local: bool,
301 /// Set when this ref's qualifier is an untyped lambda parameter whose
302 /// type is a delegate parameter of some OTHER callee -- a lookup only
303 /// the resolver can do. Never set alongside `receiver_type` or
304 /// `receiver_call_owner`: the three are mutually exclusive on one ref.
305 /// `receiver_local` still reads `true` for such a ref (the parameter
306 /// IS a member-scoped name), and `receiver_type` stays `None`. Appended
307 /// LAST of all, after `receiver_local`.
308 pub receiver_lambda: Option<LambdaSlot>,
309}
310
311/// Represents `UsingRecord`.
312pub enum UsingRecord {
313 /// The value value.
314 Alias {
315 /// The alias name.
316 alias: String,
317 /// The aliased target.
318 target: String,
319 /// Whether the directive is global.
320 global: bool,
321 },
322 /// The value value.
323 Plain {
324 /// The imported namespace text.
325 text: String,
326 /// Whether the directive is global.
327 global: bool,
328 },
329}
330
331/// Represents `Extraction`.
332pub struct Extraction {
333 /// The purpose value.
334 pub purpose: Option<String>,
335 /// The defs value.
336 pub defs: Vec<DefRecord>,
337 /// The usings value.
338 pub usings: Vec<UsingRecord>,
339 /// The refs value.
340 pub refs: Vec<RefRecord>,
341 /// Every member the file's types declare, appended LAST after
342 /// `refs` in both the fragment and the `extract-dump` shape.
343 pub names: Vec<NameRecord>,
344}
345
346/// One declared name and the line its own NAME TOKEN sits on. Deliberately
347/// not the declaration node's start row: a member's span begins
348/// at its attribute list, so an attributed member would point a reader at the
349/// `[` line instead of the line carrying the name they searched for.
350///
351/// Serialized field order (`name`, `kind`, `line`, `owner`) is significant;
352/// `owner` is omitted when empty, which is how a markup or resource
353/// key -- built by `markup.rs`, owned by no C# type -- serializes with three
354/// fields.
355#[derive(Debug, Clone, PartialEq)]
356pub struct NameRecord {
357 /// The name value.
358 pub name: String,
359 /// The kind value.
360 pub kind: String,
361 /// The line value.
362 pub line: usize,
363 /// The owner value.
364 pub owner: String,
365}
366
367/// One untyped lambda parameter's callee slot.
368///
369/// The name's type is the delegate parameter of the invocation the lambda
370/// sits inside as an argument -- a lookup only the resolver can do (it has
371/// to look up the callee's own delegate-typed parameter at `arg_index` and
372/// read ITS `index`-th parameter type). `owner`/`member` name the callee like
373/// a call fact's `type_name`/`call` do; `arg_count`/`arg_index` locate the
374/// lambda among the callee's arguments; `arity`/`index` locate this
375/// parameter inside the lambda itself.
376#[derive(Debug, Clone, PartialEq, Eq)]
377pub struct LambdaSlot {
378 /// The type-name text the callee is invoked on: the identifier's
379 /// in-file fact type, the identifier itself when the name is not taken
380 /// (a static class), or the innermost enclosing type for `this.M(...)`
381 /// / bare `M(...)`.
382 pub owner: String,
383 /// The callee method name.
384 pub member: String,
385 /// The argument count of the callee invocation.
386 pub arg_count: usize,
387 /// The position of the lambda among the callee invocation's arguments.
388 pub arg_index: usize,
389 /// The lambda's own parameter count.
390 pub arity: usize,
391 /// This parameter's position inside the lambda's parameter list.
392 pub index: usize,
393}
394
395/// One receiver fact: the declared type NAME plus that type's top-level
396/// type-argument descriptors when it carried any. Two facts agree only when
397/// BOTH halves do, so `Box<int> a` and `Box<string> a` in sibling blocks
398/// conflict exactly like two different type names would.
399#[derive(Clone, PartialEq, Eq)]
400pub struct Fact {
401 /// The type name value.
402 pub type_name: String,
403 /// The args value.
404 pub args: Option<Vec<String>>,
405 /// When set, the name's type is whatever the method of this name returns
406 /// on the type `type_name` stands for, a lookup only the resolver can do.
407 /// Part of the equality the table compares, so `var x = A.Make()` and
408 /// `var x = A.Build()` in sibling blocks conflict exactly like two
409 /// different type names would.
410 pub call: Option<String>,
411 /// `true` when this is a call fact (`call.is_some()`) built from an
412 /// AWAITED invocation (`var x = await Q.M()`); meaningless -- and always
413 /// `false` -- when `call` is `None`. Part of the equality the table
414 /// compares, so `var x = Q.M()` and `var x = await Q.M()` in sibling
415 /// blocks conflict exactly like two different callees would, rather than
416 /// silently picking one awaited-ness for a name the source gives two.
417 pub awaited: bool,
418 /// `true` when the declaration's own type node was, at its TOP level, an
419 /// `array_type` (`Widget[]`) -- set ONLY by `type_fact`, `false`
420 /// everywhere else (a call fact, a receiver-args unwrap, `this`/`base`'s
421 /// own fact: none of those can be an array). `base_type_identifier`
422 /// already collapses `Widget[]` to the same `type_name`/`args` shape a
423 /// plain `Widget` field would carry (the element type's own base
424 /// identifier, no type-argument list), so this bit is the ONLY signal
425 /// left that distinguishes "one Widget" from "an array of Widget" --
426 /// needed by the lambda-parameter element-typing rule, which must tell
427 /// `Widget[]` apart from `Widget` even though both facts otherwise read
428 /// identically. Part of the equality the table compares.
429 pub is_array: bool,
430 /// When set, the name is an untyped lambda parameter whose type is the
431 /// corresponding delegate parameter of the callee this slot names -- a
432 /// lookup only the resolver can do; `type_name` is empty and `call` is
433 /// `None`. Part of the equality the table compares, so two sibling
434 /// lambdas binding the same parameter name to different callees
435 /// conflict exactly like two different type names would.
436 pub lambda: Option<LambdaSlot>,
437}