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 = 67;
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 = 2;
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 /// Local names of import bindings that are never referenced in this file.
55 pub unused_import_bindings: Vec<String>,
56 /// Local import bindings referenced from type positions.
57 pub type_referenced_import_bindings: Vec<String>,
58 /// Local import bindings referenced from value positions.
59 pub value_referenced_import_bindings: Vec<String>,
60 /// Inline suppression directives.
61 pub suppressions: Vec<CachedSuppression>,
62 /// Pre-computed line-start byte offsets for O(log N) byte-to-line/col conversion.
63 pub line_offsets: Vec<u32>,
64 /// Per-function complexity metrics.
65 pub complexity: Vec<fallow_types::extract::FunctionComplexity>,
66 /// Feature flag use sites.
67 pub flag_uses: Vec<fallow_types::extract::FlagUse>,
68 /// Heritage metadata for exported classes.
69 pub class_heritage: Vec<fallow_types::extract::ClassHeritageInfo>,
70 /// Local type-capable declarations.
71 pub local_type_declarations: Vec<CachedLocalTypeDeclaration>,
72 /// Type references from exported public signatures.
73 pub public_signature_type_references: Vec<CachedPublicSignatureTypeReference>,
74}
75
76/// Cached local type declaration.
77#[derive(Debug, Clone, Encode, Decode)]
78pub struct CachedLocalTypeDeclaration {
79 /// Local declaration name.
80 pub name: String,
81 /// Byte offset of the declaration span start.
82 pub span_start: u32,
83 /// Byte offset of the declaration span end.
84 pub span_end: u32,
85}
86
87/// Cached public signature type reference.
88#[derive(Debug, Clone, Encode, Decode)]
89pub struct CachedPublicSignatureTypeReference {
90 /// Exported symbol whose signature contains the reference.
91 pub export_name: String,
92 /// Referenced type name.
93 pub type_name: String,
94 /// Byte offset of the reference span start.
95 pub span_start: u32,
96 /// Byte offset of the reference span end.
97 pub span_end: u32,
98}
99
100/// Cached suppression directive.
101#[derive(Debug, Clone, Encode, Decode)]
102pub struct CachedSuppression {
103 /// 1-based line this suppression applies to. 0 = file-wide.
104 pub line: u32,
105 /// 1-based line where the comment itself appears.
106 pub comment_line: u32,
107 /// 0 = suppress all, 1-20 = `IssueKind` discriminant.
108 pub kind: u8,
109}
110
111/// Cached export data for a single export declaration.
112#[derive(Debug, Clone, Encode, Decode)]
113pub struct CachedExport {
114 /// Export name (or "default" for default exports).
115 pub name: String,
116 /// Whether this is a default export.
117 pub is_default: bool,
118 /// Whether this is a type-only export.
119 pub is_type_only: bool,
120 /// Whether this export is registered through a runtime side effect at
121 /// module load time (Lit `@customElement` decorator or
122 /// `customElements.define` call). Persisted so warm-cache runs continue
123 /// to skip unused-export reporting for these classes.
124 pub is_side_effect_used: bool,
125 /// Visibility tag discriminant (0=None, 1=Public, 2=Internal, 3=Beta, 4=Alpha).
126 pub visibility: u8,
127 /// The local binding name, if different.
128 pub local_name: Option<String>,
129 /// Byte offset of the export span start.
130 pub span_start: u32,
131 /// Byte offset of the export span end.
132 pub span_end: u32,
133 /// Members of this export (for enums and classes).
134 pub members: Vec<CachedMember>,
135 /// The local name of the parent class from `extends` clause, if any.
136 pub super_class: Option<String>,
137}
138
139/// Cached import data for a single import declaration.
140#[derive(Debug, Clone, Encode, Decode)]
141pub struct CachedImport {
142 /// The import specifier.
143 pub source: String,
144 /// For Named imports, the imported symbol name. Empty for other kinds.
145 pub imported_name: String,
146 /// The local binding name.
147 pub local_name: String,
148 /// Whether this is a type-only import.
149 pub is_type_only: bool,
150 /// Whether this import originated from an SFC `<style>` block / `<style src>` (CSS context).
151 pub from_style: bool,
152 /// Import kind: 0=Named, 1=Default, 2=Namespace, 3=SideEffect.
153 pub kind: u8,
154 /// Byte offset of the import span start.
155 pub span_start: u32,
156 /// Byte offset of the import span end.
157 pub span_end: u32,
158 /// Byte offset of the source string literal span start.
159 pub source_span_start: u32,
160 /// Byte offset of the source string literal span end.
161 pub source_span_end: u32,
162}
163
164/// Cached dynamic import data.
165#[derive(Debug, Clone, Encode, Decode)]
166pub struct CachedDynamicImport {
167 /// The import specifier.
168 pub source: String,
169 /// Byte offset of the span start.
170 pub span_start: u32,
171 /// Byte offset of the span end.
172 pub span_end: u32,
173 /// Names destructured from the import result.
174 pub destructured_names: Vec<String>,
175 /// Local variable name for namespace imports.
176 pub local_name: Option<String>,
177}
178
179/// Cached `require()` call data.
180#[derive(Debug, Clone, Encode, Decode)]
181pub struct CachedRequireCall {
182 /// The require specifier.
183 pub source: String,
184 /// Byte offset of the span start.
185 pub span_start: u32,
186 /// Byte offset of the span end.
187 pub span_end: u32,
188 /// Names destructured from the require result.
189 pub destructured_names: Vec<String>,
190 /// Local variable name for namespace requires.
191 pub local_name: Option<String>,
192}
193
194/// Cached re-export data.
195#[derive(Debug, Clone, Encode, Decode)]
196pub struct CachedReExport {
197 /// The module being re-exported from.
198 pub source: String,
199 /// Name imported from the source.
200 pub imported_name: String,
201 /// Name exported from this module.
202 pub exported_name: String,
203 /// Whether this is a type-only re-export.
204 pub is_type_only: bool,
205 /// Byte offset of the re-export span start (for line-number reporting).
206 pub span_start: u32,
207 /// Byte offset of the re-export span end.
208 pub span_end: u32,
209}
210
211/// Cached enum or class member data.
212#[derive(Debug, Clone, Encode, Decode)]
213pub struct CachedMember {
214 /// Member name.
215 pub name: String,
216 /// Member kind (enum, method, or property).
217 pub kind: MemberKind,
218 /// Byte offset of the span start.
219 pub span_start: u32,
220 /// Byte offset of the span end.
221 pub span_end: u32,
222 /// Whether this member has decorators.
223 pub has_decorator: bool,
224}
225
226/// Cached dynamic import pattern data (template literals, `import.meta.glob`).
227#[derive(Debug, Clone, Encode, Decode)]
228pub struct CachedDynamicImportPattern {
229 /// Static prefix of the import path.
230 pub prefix: String,
231 /// Static suffix, if any.
232 pub suffix: Option<String>,
233 /// Byte offset of the span start.
234 pub span_start: u32,
235 /// Byte offset of the span end.
236 pub span_end: u32,
237}