weavatrix_parse/
facts.rs

1//! Language-neutral facts a structural pass extracts from a token stream.
2//!
3//! These are the shapes repository intelligence actually consumes. Anything a
4//! consumer cannot use - operator precedence, expression trees, type
5//! inference - is deliberately absent, which is what keeps extraction linear
6//! in the token count.
7
8/// Position of a fact in its source file.
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub struct Span {
11    pub start: usize,
12    pub end: usize,
13    pub line: u32,
14    pub column: u32,
15    pub end_line: u32,
16    pub end_column: u32,
17}
18
19/// The GraphQL root operation a field exposes or an executable document calls.
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub enum GraphqlOperation {
22    Query,
23    Mutation,
24    Subscription,
25}
26
27/// The schema role of a GraphQL named type.
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29pub enum GraphqlType {
30    Object,
31    Interface,
32    Input,
33    Enum,
34    Scalar,
35    Union,
36}
37
38/// A typed API-contract fact.
39#[derive(Debug, Clone, PartialEq, Eq)]
40#[non_exhaustive]
41pub enum ContractKind {
42    GraphqlType(GraphqlType),
43    GraphqlField {
44        operation: Option<GraphqlOperation>,
45        return_type: String,
46    },
47    GraphqlOperation(GraphqlOperation),
48    GraphqlCall(GraphqlOperation),
49    GraphqlFragment {
50        on_type: String,
51        operation: Option<GraphqlOperation>,
52    },
53    GraphqlFragmentSpread,
54    ProtobufPackage,
55    ProtobufMessage,
56    ProtobufEnum,
57    ProtobufService,
58    ProtobufRpc {
59        input: String,
60        output: String,
61        client_streaming: bool,
62        server_streaming: bool,
63    },
64}
65
66/// A named contract element and its exact source location.
67#[derive(Debug, Clone, PartialEq, Eq)]
68pub struct Contract {
69    pub name: String,
70    pub kind: ContractKind,
71    pub span: Span,
72    pub owner: Option<String>,
73}
74
75/// A fail-closed diagnostic emitted instead of guessed structural facts.
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub struct ParseDiagnostic {
78    pub code: &'static str,
79    pub message: String,
80    pub span: Span,
81}
82
83/// What a declared name is.
84#[derive(Debug, Clone, Copy, PartialEq, Eq)]
85#[non_exhaustive]
86pub enum DeclarationKind {
87    Function,
88    Method,
89    Class,
90    Interface,
91    Enum,
92    TypeAlias,
93    Field,
94    Constant,
95    Variable,
96    Module,
97    Struct,
98    Trait,
99    Table,
100    View,
101    Procedure,
102    /// A CSS class or id selector, named with its leading `.` or `#`.
103    Selector,
104    /// An infrastructure object: a Terraform resource, data source or output.
105    Resource,
106    /// A section heading in a document.
107    Heading,
108}
109
110/// A named declaration and where it was written.
111#[derive(Debug, Clone, PartialEq, Eq)]
112pub struct Declaration {
113    pub name: String,
114    pub kind: DeclarationKind,
115    pub span: Span,
116    /// Enclosing declaration, when the language nests them.
117    pub owner: Option<String>,
118    /// Whether the declaration leaves the module.
119    pub exported: bool,
120}
121
122/// A module this file pulls in.
123#[derive(Debug, Clone, PartialEq, Eq)]
124pub struct ImportBinding {
125    /// The name exported by the imported module.
126    pub imported: String,
127    /// The name made available in this file.
128    pub local: String,
129}
130
131/// A module this file pulls in.
132#[derive(Debug, Clone, PartialEq, Eq)]
133pub struct Import {
134    /// The specifier exactly as written, without quotes.
135    pub specifier: String,
136    pub span: Span,
137    /// A type-position import, which disappears when the code is compiled.
138    pub type_only: bool,
139    /// `export ... from`, which forwards another module's surface.
140    pub reexport: bool,
141    /// Local names this import binds.
142    ///
143    /// Without them a consumer meeting `router` in `app.use("/api", router)`
144    /// cannot tell which module it came from, and the mount resolves to
145    /// nothing.
146    pub names: Vec<String>,
147    /// Lossless exported-to-local binding pairs.
148    ///
149    /// `names` remains the backward-compatible list of local names. This field
150    /// preserves the source name too, so `import { original as local }` can be
151    /// resolved to `original` without a repository-wide guess for `local`.
152    pub bindings: Vec<ImportBinding>,
153}
154
155/// Why one name mentions another.
156///
157/// A call and an `extends` clause are both "this name depends on that name",
158/// and separating them into different fact types would force every consumer to
159/// walk two collections to answer one question.
160#[derive(Debug, Clone, Copy, PartialEq, Eq)]
161#[non_exhaustive]
162pub enum ReferenceKind {
163    Call,
164    Inherits,
165    Implements,
166    /// A name used without being called, as an HTML `class` attribute uses a
167    /// CSS selector.
168    Uses,
169    /// A statement that reads the named object, as `SELECT ... FROM users`.
170    Reads,
171    /// A statement that writes it, as `INSERT INTO users`.
172    Writes,
173}
174
175/// One name mentioning another.
176#[derive(Debug, Clone, PartialEq, Eq)]
177pub struct Reference {
178    /// The referenced name, without its receiver.
179    pub name: String,
180    pub kind: ReferenceKind,
181    /// Receiver written before the final dot, when there was one.
182    pub receiver: Option<String>,
183    pub span: Span,
184    /// Enclosing declaration the reference was written in.
185    pub owner: Option<String>,
186    /// Literal string arguments, which carry routes, topics and table names.
187    pub string_arguments: Vec<String>,
188    /// Names passed as arguments, in the order written.
189    ///
190    /// `app.use("/api", router)` mounts one module under a prefix, and the
191    /// prefix is a string while the module is a name - so a consumer that
192    /// only sees literals sees half the fact and can resolve neither end.
193    pub name_arguments: Vec<String>,
194}
195
196/// Everything one structural pass found in one file.
197#[derive(Debug, Clone, Default, PartialEq, Eq)]
198pub struct Facts {
199    pub declarations: Vec<Declaration>,
200    pub imports: Vec<Import>,
201    pub references: Vec<Reference>,
202    pub contracts: Vec<Contract>,
203    pub diagnostics: Vec<ParseDiagnostic>,
204}
205
206impl Facts {
207    /// Just the call sites, for consumers that want a call graph and nothing
208    /// else.
209    pub fn calls(&self) -> impl Iterator<Item = &Reference> {
210        self.references
211            .iter()
212            .filter(|reference| reference.kind == ReferenceKind::Call)
213    }
214}
weavatrix_parse/facts.rs

weavatrix_parse/
facts.rs
