fallow_extract/cache/types.rs
1//! Serialization types for the incremental parse cache.
2//!
3//! All types use bitcode `Encode`/`Decode` for fast binary serialization.
4
5use bitcode::{Decode, Encode};
6
7use crate::MemberKind;
8
9/// Cache version, bump when the cache format or cached extraction semantics change.
10pub(super) const CACHE_VERSION: u32 = 83;
11
12/// Duplication token cache version — bump when duplicate tokenization,
13/// normalization, or the on-disk token cache schema changes.
14pub const DUPES_CACHE_VERSION: u32 = 4;
15
16/// Maximum cache file size to deserialize (256 MB).
17pub(super) const MAX_CACHE_SIZE: usize = 256 * 1024 * 1024;
18
19/// Import kind discriminant for `CachedImport`:
20/// 0 = Named, 1 = Default, 2 = Namespace, 3 = `SideEffect`.
21pub(super) const IMPORT_KIND_NAMED: u8 = 0;
22pub(super) const IMPORT_KIND_DEFAULT: u8 = 1;
23pub(super) const IMPORT_KIND_NAMESPACE: u8 = 2;
24pub(super) const IMPORT_KIND_SIDE_EFFECT: u8 = 3;
25
26/// Cached data for a single module.
27#[derive(Debug, Clone, Encode, Decode)]
28pub struct CachedModule {
29 /// xxh3 hash of the file content.
30 pub content_hash: u64,
31 /// File modification time (seconds since epoch) for fast cache validation.
32 /// When mtime+size match the on-disk file, we skip reading file content entirely.
33 pub mtime_secs: u64,
34 /// File size in bytes for fast cache validation.
35 pub file_size: u64,
36 /// Exported symbols.
37 pub exports: Vec<CachedExport>,
38 /// Import specifiers.
39 pub imports: Vec<CachedImport>,
40 /// Re-export specifiers.
41 pub re_exports: Vec<CachedReExport>,
42 /// Dynamic import specifiers.
43 pub dynamic_imports: Vec<CachedDynamicImport>,
44 /// `require()` specifiers.
45 pub require_calls: Vec<CachedRequireCall>,
46 /// Static member accesses (e.g., `Status.Active`).
47 pub member_accesses: Vec<crate::MemberAccess>,
48 /// Identifiers used as whole objects (Object.values, for..in, spread, etc.).
49 pub whole_object_uses: Vec<String>,
50 /// Dynamic import patterns with partial static resolution.
51 pub dynamic_import_patterns: Vec<CachedDynamicImportPattern>,
52 /// Whether this module uses CJS exports.
53 pub has_cjs_exports: bool,
54 /// Whether this module declares at least one Angular `@Component({
55 /// templateUrl: ... })` decorator. Mirrors `ModuleInfo.has_angular_component_template_url`
56 /// so the CRAP-inherit walker's gate survives a warm-cache load.
57 pub has_angular_component_template_url: bool,
58 /// Local names of import bindings that are never referenced in this file.
59 pub unused_import_bindings: Vec<String>,
60 /// Local import bindings referenced from type positions.
61 pub type_referenced_import_bindings: Vec<String>,
62 /// Local import bindings referenced from value positions.
63 pub value_referenced_import_bindings: Vec<String>,
64 /// Inline suppression directives.
65 pub suppressions: Vec<CachedSuppression>,
66 /// Pre-computed line-start byte offsets for O(log N) byte-to-line/col conversion.
67 pub line_offsets: Vec<u32>,
68 /// Per-function complexity metrics.
69 pub complexity: Vec<fallow_types::extract::FunctionComplexity>,
70 /// Feature flag use sites.
71 pub flag_uses: Vec<fallow_types::extract::FlagUse>,
72 /// Heritage metadata for exported classes.
73 pub class_heritage: Vec<fallow_types::extract::ClassHeritageInfo>,
74 /// Local type-capable declarations.
75 pub local_type_declarations: Vec<CachedLocalTypeDeclaration>,
76 /// Type references from exported public signatures.
77 pub public_signature_type_references: Vec<CachedPublicSignatureTypeReference>,
78 /// Namespace-import aliases re-exported through an object literal
79 /// (`export const API = { foo }` where `foo` is `import * as foo from './bar'`).
80 pub namespace_object_aliases: Vec<CachedNamespaceObjectAlias>,
81}
82
83/// Cached namespace-object alias.
84#[derive(Debug, Clone, Encode, Decode)]
85pub struct CachedNamespaceObjectAlias {
86 /// Canonical export name on this module.
87 pub via_export_name: String,
88 /// Dotted suffix of the property path relative to the export.
89 pub suffix: String,
90 /// Local name of the namespace import on this module.
91 pub namespace_local: String,
92}
93
94/// Cached local type declaration.
95#[derive(Debug, Clone, Encode, Decode)]
96pub struct CachedLocalTypeDeclaration {
97 /// Local declaration name.
98 pub name: String,
99 /// Byte offset of the declaration span start.
100 pub span_start: u32,
101 /// Byte offset of the declaration span end.
102 pub span_end: u32,
103}
104
105/// Cached public signature type reference.
106#[derive(Debug, Clone, Encode, Decode)]
107pub struct CachedPublicSignatureTypeReference {
108 /// Exported symbol whose signature contains the reference.
109 pub export_name: String,
110 /// Referenced type name.
111 pub type_name: String,
112 /// Byte offset of the reference span start.
113 pub span_start: u32,
114 /// Byte offset of the reference span end.
115 pub span_end: u32,
116}
117
118/// Cached suppression directive.
119#[derive(Debug, Clone, Encode, Decode)]
120pub struct CachedSuppression {
121 /// 1-based line this suppression applies to. 0 = file-wide.
122 pub line: u32,
123 /// 1-based line where the comment itself appears.
124 pub comment_line: u32,
125 /// 0 = suppress all, 1-20 = `IssueKind` discriminant.
126 pub kind: u8,
127}
128
129/// Cached export data for a single export declaration.
130#[derive(Debug, Clone, Encode, Decode)]
131pub struct CachedExport {
132 /// Export name (or "default" for default exports).
133 pub name: String,
134 /// Whether this is a default export.
135 pub is_default: bool,
136 /// Whether this is a type-only export.
137 pub is_type_only: bool,
138 /// Whether this export is registered through a runtime side effect at
139 /// module load time (Lit `@customElement` decorator or
140 /// `customElements.define` call). Persisted so warm-cache runs continue
141 /// to skip unused-export reporting for these classes.
142 pub is_side_effect_used: bool,
143 /// Visibility tag discriminant (0=None, 1=Public, 2=Internal, 3=Beta, 4=Alpha).
144 pub visibility: u8,
145 /// The local binding name, if different.
146 pub local_name: Option<String>,
147 /// Byte offset of the export span start.
148 pub span_start: u32,
149 /// Byte offset of the export span end.
150 pub span_end: u32,
151 /// Members of this export (for enums and classes).
152 pub members: Vec<CachedMember>,
153 /// The local name of the parent class from `extends` clause, if any.
154 pub super_class: Option<String>,
155}
156
157/// Cached import data for a single import declaration.
158#[derive(Debug, Clone, Encode, Decode)]
159pub struct CachedImport {
160 /// The import specifier.
161 pub source: String,
162 /// For Named imports, the imported symbol name. Empty for other kinds.
163 pub imported_name: String,
164 /// The local binding name.
165 pub local_name: String,
166 /// Whether this is a type-only import.
167 pub is_type_only: bool,
168 /// Whether this import originated from an SFC `<style>` block / `<style src>` (CSS context).
169 pub from_style: bool,
170 /// Import kind: 0=Named, 1=Default, 2=Namespace, 3=SideEffect.
171 pub kind: u8,
172 /// Byte offset of the import span start.
173 pub span_start: u32,
174 /// Byte offset of the import span end.
175 pub span_end: u32,
176 /// Byte offset of the source string literal span start.
177 pub source_span_start: u32,
178 /// Byte offset of the source string literal span end.
179 pub source_span_end: u32,
180}
181
182/// Cached dynamic import data.
183#[derive(Debug, Clone, Encode, Decode)]
184pub struct CachedDynamicImport {
185 /// The import specifier.
186 pub source: String,
187 /// Byte offset of the span start.
188 pub span_start: u32,
189 /// Byte offset of the span end.
190 pub span_end: u32,
191 /// Names destructured from the import result.
192 pub destructured_names: Vec<String>,
193 /// Local variable name for namespace imports.
194 pub local_name: Option<String>,
195 /// True when this dynamic import was synthesised by fallow (see
196 /// `DynamicImportInfo::is_speculative`).
197 pub is_speculative: bool,
198}
199
200/// Cached `require()` call data.
201#[derive(Debug, Clone, Encode, Decode)]
202pub struct CachedRequireCall {
203 /// The require specifier.
204 pub source: String,
205 /// Byte offset of the span start.
206 pub span_start: u32,
207 /// Byte offset of the span end.
208 pub span_end: u32,
209 /// Names destructured from the require result.
210 pub destructured_names: Vec<String>,
211 /// Local variable name for namespace requires.
212 pub local_name: Option<String>,
213}
214
215/// Cached re-export data.
216#[derive(Debug, Clone, Encode, Decode)]
217pub struct CachedReExport {
218 /// The module being re-exported from.
219 pub source: String,
220 /// Name imported from the source.
221 pub imported_name: String,
222 /// Name exported from this module.
223 pub exported_name: String,
224 /// Whether this is a type-only re-export.
225 pub is_type_only: bool,
226 /// Byte offset of the re-export span start (for line-number reporting).
227 pub span_start: u32,
228 /// Byte offset of the re-export span end.
229 pub span_end: u32,
230}
231
232/// Cached enum or class member data.
233#[derive(Debug, Clone, Encode, Decode)]
234pub struct CachedMember {
235 /// Member name.
236 pub name: String,
237 /// Member kind (enum, method, or property).
238 pub kind: MemberKind,
239 /// Byte offset of the span start.
240 pub span_start: u32,
241 /// Byte offset of the span end.
242 pub span_end: u32,
243 /// Whether this member has decorators.
244 pub has_decorator: bool,
245 /// True when this is a static method that returns a fresh instance of
246 /// the class: body returns `new this()` / `new <SameClassName>()`, or the
247 /// declared return type matches the class name. Treated as a factory.
248 /// See issues #346, #387.
249 pub is_instance_returning_static: bool,
250 /// True when this instance method's call result is an instance of the
251 /// same class (declared return type matches the class name, or body's
252 /// last statement is `return this`). Drives fluent-chain credit. See
253 /// issue #387.
254 pub is_self_returning: bool,
255}
256
257/// Cached dynamic import pattern data (template literals, `import.meta.glob`).
258#[derive(Debug, Clone, Encode, Decode)]
259pub struct CachedDynamicImportPattern {
260 /// Static prefix of the import path.
261 pub prefix: String,
262 /// Static suffix, if any.
263 pub suffix: Option<String>,
264 /// Byte offset of the span start.
265 pub span_start: u32,
266 /// Byte offset of the span end.
267 pub span_end: u32,
268}