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 html;
16pub mod inventory;
17pub mod mdx;
18mod parse;
19pub mod sfc;
20mod sfc_template;
21pub mod suppress;
22pub(crate) mod template_complexity;
23mod template_usage;
24pub mod visitor;
25
26use std::path::Path;
27
28use rayon::prelude::*;
29
30use cache::CacheStore;
31use fallow_types::discover::{DiscoveredFile, FileId};
32
33// Re-export all extract types from fallow-types
34pub use fallow_types::extract::{
35    ClassHeritageInfo, DynamicImportInfo, DynamicImportPattern, ExportInfo, ExportName, ImportInfo,
36    ImportedName, MemberAccess, MemberInfo, MemberKind, ModuleInfo, ParseResult, ReExportInfo,
37    RequireCallInfo, VisibilityTag, compute_line_offsets,
38};
39
40// Re-export extraction functions for internal use and fuzzing
41pub use astro::extract_astro_frontmatter;
42pub use css::extract_css_module_exports;
43pub use mdx::extract_mdx_statements;
44pub use sfc::{extract_sfc_scripts, is_sfc_file};
45pub use sfc_template::angular::ANGULAR_TPL_SENTINEL;
46
47/// Synthetic member-access object used to carry exported-instance bindings.
48///
49/// `MemberAccess { object: format!("{INSTANCE_EXPORT_SENTINEL}{export_name}"), member: target }`
50/// means the exported value named `export_name` is an instance of the local
51/// class/interface symbol named `target`.
52pub const INSTANCE_EXPORT_SENTINEL: &str = "__fallow_instance_export__:";
53
54use parse::parse_source_to_module;
55
56/// Parse all files in parallel, extracting imports and exports.
57/// Uses the cache to skip reparsing files whose content hasn't changed.
58///
59/// When `need_complexity` is true, per-function cyclomatic/cognitive complexity
60/// metrics are computed during parsing (needed by the `health` command).
61/// Pass `false` for dead-code analysis where complexity data is unused.
62pub fn parse_all_files(
63    files: &[DiscoveredFile],
64    cache: Option<&CacheStore>,
65    need_complexity: bool,
66) -> ParseResult {
67    use std::sync::atomic::{AtomicUsize, Ordering};
68    let cache_hits = AtomicUsize::new(0);
69    let cache_misses = AtomicUsize::new(0);
70
71    let modules: Vec<ModuleInfo> = files
72        .par_iter()
73        .filter_map(|file| {
74            parse_single_file_cached(file, cache, &cache_hits, &cache_misses, need_complexity)
75        })
76        .collect();
77
78    let hits = cache_hits.load(Ordering::Relaxed);
79    let misses = cache_misses.load(Ordering::Relaxed);
80    if hits > 0 || misses > 0 {
81        tracing::info!(
82            cache_hits = hits,
83            cache_misses = misses,
84            "incremental cache stats"
85        );
86    }
87
88    ParseResult {
89        modules,
90        cache_hits: hits,
91        cache_misses: misses,
92    }
93}
94
95/// Extract mtime (seconds since epoch) from file metadata.
96/// Returns 0 if mtime cannot be determined (pre-epoch, unsupported OS, etc.).
97fn mtime_secs(metadata: &std::fs::Metadata) -> u64 {
98    metadata
99        .modified()
100        .ok()
101        .and_then(|t| t.duration_since(std::time::SystemTime::UNIX_EPOCH).ok())
102        .map_or(0, |d| d.as_secs())
103}
104
105/// Parse a single file, consulting the cache first.
106///
107/// Cache validation strategy (fast path -> slow path):
108/// 1. `stat()` the file to get mtime + size (single syscall, no file read)
109/// 2. If mtime+size match the cached entry -> cache hit, return immediately
110/// 3. If mtime+size differ -> read file, compute content hash
111/// 4. If content hash matches cached entry -> cache hit (file was `touch`ed but unchanged)
112/// 5. Otherwise -> cache miss, full parse
113fn parse_single_file_cached(
114    file: &DiscoveredFile,
115    cache: Option<&CacheStore>,
116    cache_hits: &std::sync::atomic::AtomicUsize,
117    cache_misses: &std::sync::atomic::AtomicUsize,
118    need_complexity: bool,
119) -> Option<ModuleInfo> {
120    use std::sync::atomic::Ordering;
121
122    // Fast path: check mtime+size before reading file content.
123    // A single stat() syscall is ~100x cheaper than read()+hash().
124    if let Some(store) = cache
125        && let Ok(metadata) = std::fs::metadata(&file.path)
126    {
127        let mt = mtime_secs(&metadata);
128        let sz = metadata.len();
129        if let Some(cached) = store.get_by_metadata(&file.path, mt, sz) {
130            // When complexity is requested but the cached entry lacks it
131            // (populated by a prior `check` run), skip the cache and re-parse.
132            if !need_complexity || !cached.complexity.is_empty() {
133                cache_hits.fetch_add(1, Ordering::Relaxed);
134                return Some(cache::cached_to_module(cached, file.id));
135            }
136        }
137    }
138
139    // Slow path: read file content and compute content hash.
140    let source = std::fs::read_to_string(&file.path).ok()?;
141    let content_hash = xxhash_rust::xxh3::xxh3_64(source.as_bytes());
142
143    // Check cache by content hash (handles touch/save-without-change)
144    if let Some(store) = cache
145        && let Some(cached) = store.get(&file.path, content_hash)
146        && (!need_complexity || !cached.complexity.is_empty())
147    {
148        cache_hits.fetch_add(1, Ordering::Relaxed);
149        return Some(cache::cached_to_module(cached, file.id));
150    }
151    cache_misses.fetch_add(1, Ordering::Relaxed);
152
153    // Cache miss, do a full parse
154    Some(parse_source_to_module(
155        file.id,
156        &file.path,
157        &source,
158        content_hash,
159        need_complexity,
160    ))
161}
162
163/// Parse a single file and extract module information (without complexity).
164#[must_use]
165pub fn parse_single_file(file: &DiscoveredFile) -> Option<ModuleInfo> {
166    let source = std::fs::read_to_string(&file.path).ok()?;
167    let content_hash = xxhash_rust::xxh3::xxh3_64(source.as_bytes());
168    Some(parse_source_to_module(
169        file.id,
170        &file.path,
171        &source,
172        content_hash,
173        false,
174    ))
175}
176
177/// Parse from in-memory content (for LSP, includes complexity).
178#[must_use]
179pub fn parse_from_content(file_id: FileId, path: &Path, content: &str) -> ModuleInfo {
180    let content_hash = xxhash_rust::xxh3::xxh3_64(content.as_bytes());
181    parse_source_to_module(file_id, path, content, content_hash, true)
182}
183
184// Parser integration tests invoke Oxc under Miri which is ~1000x slower.
185// Unit tests in individual modules (visitor, suppress, sfc, css, etc.) still run.
186#[cfg(all(test, not(miri)))]
187mod tests;
fallow_extract/lib.rs

fallow_extract/
lib.rs
