fallow_extract/
lib.rs

1//! Parsing and extraction engine for fallow codebase intelligence.
2//!
3//! This crate handles all file parsing: JS/TS via Oxc, Vue/Svelte SFC extraction,
4//! Astro frontmatter, MDX import/export extraction, CSS Module class name extraction,
5//! HTML asset reference extraction, and incremental caching of parse results.
6
7#![warn(missing_docs)]
8
9mod asset_url;
10pub mod astro;
11pub mod cache;
12pub(crate) mod complexity;
13pub mod css;
14pub mod flags;
15pub mod glimmer;
16pub mod graphql;
17pub mod html;
18pub mod inventory;
19pub mod mdx;
20mod parse;
21pub mod sfc;
22mod sfc_template;
23pub mod suppress;
24pub(crate) mod template_complexity;
25mod template_usage;
26pub mod visitor;
27
28use std::path::Path;
29
30use rayon::prelude::*;
31
32use cache::CacheStore;
33use fallow_types::discover::{DiscoveredFile, FileId};
34
35// Re-export all extract types from fallow-types
36pub use fallow_types::extract::{
37    ClassHeritageInfo, DynamicImportInfo, DynamicImportPattern, ExportInfo, ExportName, ImportInfo,
38    ImportedName, LocalTypeDeclaration, MemberAccess, MemberInfo, MemberKind, ModuleInfo,
39    ParseResult, PublicSignatureTypeReference, ReExportInfo, RequireCallInfo, VisibilityTag,
40    compute_line_offsets,
41};
42
43// Re-export extraction functions for internal use and fuzzing
44pub use astro::extract_astro_frontmatter;
45pub use css::extract_css_module_exports;
46pub use glimmer::{is_glimmer_file, strip_glimmer_templates};
47pub use mdx::extract_mdx_statements;
48pub use sfc::{extract_sfc_scripts, is_sfc_file};
49pub use sfc_template::angular::ANGULAR_TPL_SENTINEL;
50
51/// Synthetic member-access object used to carry exported-instance bindings.
52///
53/// `MemberAccess { object: format!("{INSTANCE_EXPORT_SENTINEL}{export_name}"), member: target }`
54/// means the exported value named `export_name` is an instance of the local
55/// class/interface symbol named `target`.
56pub const INSTANCE_EXPORT_SENTINEL: &str = "__fallow_instance_export__:";
57
58/// Synthetic member-access object prefix for typed Playwright fixtures.
59///
60/// `MemberAccess { object: format!("{PLAYWRIGHT_FIXTURE_DEF_SENTINEL}{test}:{fixture}"), member: type_name }`
61/// means the exported Playwright test object named `test` provides a fixture
62/// named `fixture` whose declared type is `type_name`.
63pub const PLAYWRIGHT_FIXTURE_DEF_SENTINEL: &str = "__fallow_playwright_fixture_def__:";
64
65/// Synthetic member-access object prefix for Playwright fixture member uses.
66///
67/// `MemberAccess { object: format!("{PLAYWRIGHT_FIXTURE_USE_SENTINEL}{test}:{fixture}"), member }`
68/// means a callback passed to the Playwright test object named `test`
69/// destructures `fixture` and accesses `fixture.member`.
70pub const PLAYWRIGHT_FIXTURE_USE_SENTINEL: &str = "__fallow_playwright_fixture_use__:";
71
72/// Synthetic member-access object prefix for static-factory call returns.
73///
74/// `MemberAccess { object: format!("{FACTORY_CALL_SENTINEL}{callee}:{method}"), member }`
75/// means a local binding was assigned from `<callee>.<method>()` and a member
76/// is accessed on the result. The analyze layer resolves `callee` through the
77/// consumer module's imports to a class export and credits `member` on the
78/// class when the matching method carries `is_instance_returning_static`.
79/// See issue #346.
80pub const FACTORY_CALL_SENTINEL: &str = "__fallow_factory_call__:";
81
82use parse::parse_source_to_module;
83
84/// Parse all files in parallel, extracting imports and exports.
85/// Uses the cache to skip reparsing files whose content hasn't changed.
86///
87/// When `need_complexity` is true, per-function cyclomatic/cognitive complexity
88/// metrics are computed during parsing (needed by the `health` command).
89/// Pass `false` for dead-code analysis where complexity data is unused.
90pub fn parse_all_files(
91    files: &[DiscoveredFile],
92    cache: Option<&CacheStore>,
93    need_complexity: bool,
94) -> ParseResult {
95    use std::sync::atomic::{AtomicUsize, Ordering};
96    let cache_hits = AtomicUsize::new(0);
97    let cache_misses = AtomicUsize::new(0);
98
99    let modules: Vec<ModuleInfo> = files
100        .par_iter()
101        .filter_map(|file| {
102            parse_single_file_cached(file, cache, &cache_hits, &cache_misses, need_complexity)
103        })
104        .collect();
105
106    let hits = cache_hits.load(Ordering::Relaxed);
107    let misses = cache_misses.load(Ordering::Relaxed);
108    if hits > 0 || misses > 0 {
109        tracing::info!(
110            cache_hits = hits,
111            cache_misses = misses,
112            "incremental cache stats"
113        );
114    }
115
116    ParseResult {
117        modules,
118        cache_hits: hits,
119        cache_misses: misses,
120    }
121}
122
123/// Parse a single file, consulting the cache first.
124///
125/// Cache validation strategy (fast path -> slow path):
126/// 1. `stat()` the file to get mtime + size (single syscall, no file read)
127/// 2. If mtime+size match the cached entry -> cache hit, return immediately
128/// 3. If mtime+size differ -> read file, compute content hash
129/// 4. If content hash matches cached entry -> cache hit (file was `touch`ed but unchanged)
130/// 5. Otherwise -> cache miss, full parse
131fn parse_single_file_cached(
132    file: &DiscoveredFile,
133    cache: Option<&CacheStore>,
134    cache_hits: &std::sync::atomic::AtomicUsize,
135    cache_misses: &std::sync::atomic::AtomicUsize,
136    need_complexity: bool,
137) -> Option<ModuleInfo> {
138    use std::sync::atomic::Ordering;
139
140    // Fast path: check mtime+size before reading file content.
141    // A single stat() syscall is ~100x cheaper than read()+hash().
142    if let Some(store) = cache
143        && let Ok(metadata) = std::fs::metadata(&file.path)
144    {
145        let mt = mtime_secs(&metadata);
146        let sz = metadata.len();
147        if let Some(cached) = store.get_by_metadata(&file.path, mt, sz) {
148            // When complexity is requested but the cached entry lacks it
149            // (populated by a prior `check` run), skip the cache and re-parse.
150            if !need_complexity || !cached.complexity.is_empty() {
151                cache_hits.fetch_add(1, Ordering::Relaxed);
152                return Some(cache::cached_to_module_opts(
153                    cached,
154                    file.id,
155                    need_complexity,
156                ));
157            }
158        }
159    }
160
161    // Slow path: read file content and compute content hash.
162    let source = std::fs::read_to_string(&file.path).ok()?;
163    let content_hash = xxhash_rust::xxh3::xxh3_64(source.as_bytes());
164
165    // Check cache by content hash (handles touch/save-without-change)
166    if let Some(store) = cache
167        && let Some(cached) = store.get(&file.path, content_hash)
168        && (!need_complexity || !cached.complexity.is_empty())
169    {
170        cache_hits.fetch_add(1, Ordering::Relaxed);
171        return Some(cache::cached_to_module_opts(
172            cached,
173            file.id,
174            need_complexity,
175        ));
176    }
177    cache_misses.fetch_add(1, Ordering::Relaxed);
178
179    // Cache miss, do a full parse
180    Some(parse_source_to_module(
181        file.id,
182        &file.path,
183        &source,
184        content_hash,
185        need_complexity,
186    ))
187}
188
189/// Extract mtime (seconds since epoch) from file metadata.
190/// Returns 0 if mtime cannot be determined (pre-epoch, unsupported OS, etc.).
191fn mtime_secs(metadata: &std::fs::Metadata) -> u64 {
192    metadata
193        .modified()
194        .ok()
195        .and_then(|t| t.duration_since(std::time::SystemTime::UNIX_EPOCH).ok())
196        .map_or(0, |d| d.as_secs())
197}
198
199/// Parse a single file and extract module information (without complexity).
200#[must_use]
201pub fn parse_single_file(file: &DiscoveredFile) -> Option<ModuleInfo> {
202    let source = std::fs::read_to_string(&file.path).ok()?;
203    let content_hash = xxhash_rust::xxh3::xxh3_64(source.as_bytes());
204    Some(parse_source_to_module(
205        file.id,
206        &file.path,
207        &source,
208        content_hash,
209        false,
210    ))
211}
212
213/// Parse from in-memory content (for LSP, includes complexity).
214#[must_use]
215pub fn parse_from_content(file_id: FileId, path: &Path, content: &str) -> ModuleInfo {
216    let content_hash = xxhash_rust::xxh3::xxh3_64(content.as_bytes());
217    parse_source_to_module(file_id, path, content, content_hash, true)
218}
219
220// Parser integration tests invoke Oxc under Miri which is ~1000x slower.
221// Unit tests in individual modules (visitor, suppress, sfc, css, etc.) still run.
222#[cfg(all(test, not(miri)))]
223mod tests;
fallow_extract/lib.rs

fallow_extract/
lib.rs
