Skip to main content

fallow_types/
extract_component_contracts.rs

1//! Persisted syntactic evidence for conservative component-input analysis.
2
3/// Framework owning a statically extracted component contract.
4#[derive(Debug, Clone, Copy, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
5pub enum ComponentFramework {
6    /// React JSX.
7    React,
8    /// Preact JSX.
9    Preact,
10    /// Solid JSX.
11    Solid,
12    /// Qwik JSX.
13    Qwik,
14    /// Vue and Nuxt single-file components.
15    Vue,
16    /// Svelte components.
17    Svelte,
18    /// Astro components.
19    Astro,
20    /// Angular components and directives.
21    Angular,
22    /// Lit custom elements.
23    Lit,
24    /// Ember and Glimmer components.
25    Ember,
26}
27
28/// Stable component binding identity, independent of transient parser symbols.
29#[derive(Debug, Clone, PartialEq, Eq, Hash, bitcode::Encode, bitcode::Decode)]
30pub enum ComponentReference {
31    /// A same-module declaration, including resolved immutable local aliases.
32    Local {
33        /// Declaration binding name.
34        name: String,
35        /// Start byte of the declaration binding.
36        span_start: u32,
37    },
38    /// An import binding. Analysis resolves its effective export via the graph.
39    Import {
40        /// Local name of the actual import binding, never a shadowing identifier.
41        local: String,
42        /// Start byte of the import binding declaration.
43        span_start: u32,
44    },
45    /// A direct member of a proven namespace import.
46    NamespaceMember {
47        /// Local namespace import binding name.
48        local: String,
49        /// Namespace import binding byte anchor.
50        span_start: u32,
51        /// Effective value export requested by the member access.
52        member: String,
53    },
54    /// A statically registered Angular selector or custom-element tag.
55    Selector(String),
56    /// Dynamic or unsupported component identity.
57    Unknown,
58}
59
60/// A declared public input, kept distinct from legacy unused-prop facts.
61#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
62pub struct ComponentPropDeclaration {
63    /// Component declaration name. Empty denotes the sole SFC default export.
64    pub component: String,
65    /// Stable declaration binding byte anchor.
66    pub component_span: u32,
67    /// Public input name.
68    pub name: String,
69    /// Local binding name used by destructured template reads.
70    pub local: String,
71    /// Additional public attribute names supplying the same input.
72    pub aliases: Vec<String>,
73    /// Declaration byte anchor in the original source.
74    pub span_start: u32,
75    /// Whether the declaration explicitly permits omission.
76    pub optional: bool,
77    /// Whether omission has a syntactically declared default value.
78    pub has_default: bool,
79    /// Whether the input is consumed within the component.
80    pub is_used: bool,
81    /// Producer framework.
82    pub framework: ComponentFramework,
83    /// Unsupported declarations, forwarding, or open consumers prohibit absence claims.
84    pub incomplete: bool,
85}
86
87/// One inspected render invocation and its supplied input names.
88#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
89pub struct ComponentInvocation {
90    /// Binding or selector used by the invocation.
91    pub target: ComponentReference,
92    /// Original source byte anchor of the opening tag or call.
93    pub span_start: u32,
94    /// Supplied names, independent of values and including proven spread keys.
95    pub supplied: Vec<String>,
96    /// Case-sensitive Lit JavaScript property bindings, distinct from HTML attributes.
97    pub supplied_properties: Vec<String>,
98    /// A spread or dynamic attribute may supply additional names.
99    pub unknown_props: bool,
100    /// Framework syntax of this caller.
101    pub framework: ComponentFramework,
102}
103
104/// Persisted syntactic evidence for conservative component-input analysis.
105#[derive(Debug, Clone, Default, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
106pub struct ComponentContractFacts {
107    /// Immutable root script aliases resolved to their semantic targets.
108    pub aliases: Vec<ComponentAliasBinding>,
109    /// Exact Angular templateUrl source owned by each component binding.
110    pub external_templates: Vec<ComponentExternalTemplate>,
111    /// Original component bodies that own embedded Glimmer templates.
112    pub template_owners: Vec<ComponentTemplateOwner>,
113    /// Effective local export bindings retained after graph payload release.
114    pub exports: Vec<ComponentExportBinding>,
115    /// Immutable local object shapes retained for template spread resolution.
116    pub spread_bindings: Vec<ComponentSpreadBinding>,
117    /// Known declaration contracts.
118    pub declarations: Vec<ComponentPropDeclaration>,
119    /// Inspected render sites, including module-level invocations.
120    pub invocations: Vec<ComponentInvocation>,
121    /// Component bindings used opaquely outside inspected renders.
122    pub escapes: Vec<ComponentReference>,
123    /// Frameworks with a dynamic consumer whose affected target is unknowable.
124    pub incomplete_frameworks: Vec<ComponentFramework>,
125}
126
127/// An immutable, unescaped local object with statically known own keys.
128#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
129pub struct ComponentSpreadBinding {
130    /// Root script binding name, resolved before template scopes are applied.
131    pub local: String,
132    /// Script binding declaration anchor.
133    pub span_start: u32,
134    /// Complete own property names.
135    pub keys: Vec<String>,
136}
137
138/// An export name resolved to its syntactic component or import binding.
139#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
140pub struct ComponentExportBinding {
141    /// Public export name, including `default`.
142    pub export_name: String,
143    /// Original export declaration byte anchor.
144    pub export_span: u32,
145    /// Proven local binding, canonicalizing immutable aliases.
146    pub target: ComponentReference,
147}
148
149/// A semantic component declaration body containing an embedded template.
150#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
151pub struct ComponentTemplateOwner {
152    /// Owning component binding anchor.
153    pub component_span: u32,
154    /// Original class body start.
155    pub start: u32,
156    /// Original class body end.
157    pub end: u32,
158}
159
160/// A statically declared external template owned by one component.
161#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
162pub struct ComponentExternalTemplate {
163    /// Owning component binding anchor.
164    pub component_span: u32,
165    /// Literal templateUrl source, resolved through the graph import edge.
166    pub source: String,
167}
168
169/// An immutable root binding that aliases a component or import.
170#[derive(Debug, Clone, PartialEq, Eq, bitcode::Encode, bitcode::Decode)]
171pub struct ComponentAliasBinding {
172    /// Root script binding spelling used by template expressions.
173    pub local: String,
174    /// Canonical semantic binding target, including its source anchor.
175    pub target: ComponentReference,
176}