Skip to main content

import_lint_cli/
runner.rs

1//! Discovery + link orchestration (PLAN-v1.md §2.1 steps 2–4, §8, M2): walk, then
2//! parse+extract and resolve in parallel (rayon + `AllocatorPool`), producing a
3//! [`ModuleGraph`]. The check phase (PLAN-v1.md §2.1 step 5) is M3's job.
4//!
5//! M6 (watch mode, `docs/PLAN-v1.md` §7) needs these stages callable individually with a
6//! caller-supplied [`ExtractionCache`], so a content-only file edit can skip
7//! re-parsing every untouched file while still rebuilding the graph from scratch each
8//! cycle (`crates/cli/src/watch.rs`'s `WatchSession`). [`run`] is the simple one-shot
9//! entry point everything else (M2–M5 callers, tests) already uses; it is unchanged
10//! and just wraps [`run_with_cache`] with a fresh, empty cache.
11
12use std::collections::{HashMap, HashSet};
13use std::fs;
14use std::path::{Path, PathBuf};
15use std::sync::Arc;
16use std::time::SystemTime;
17
18use import_lint::{FileModuleInfo, ModuleGraph, ProjectResolver, Provenance, SelfReferenceMode};
19use oxc_allocator::AllocatorPool;
20use oxc_parser::Parser as OxcParser;
21use oxc_str::CompactStr;
22use rayon::prelude::*;
23
24use crate::overlay::Overlays;
25use crate::source_type::source_type_for_path;
26use crate::timing;
27
28/// Options for one pipeline run.
29#[derive(Debug, Clone, Default)]
30pub struct RunnerOptions {
31    /// Roots to walk for lint targets (PLAN-v1.md §2.1 step 2).
32    pub roots: Vec<PathBuf>,
33    /// Project root passed to the resolver (tsconfig discovery base, `cwd` option).
34    /// Default: the current working directory.
35    pub project_root: PathBuf,
36    /// Path to the project's `tsconfig.json`, if any. Default:
37    /// `<project_root>/tsconfig.json` if it exists, else `None` — see
38    /// [`RunnerOptions::default_tsconfig`].
39    pub tsconfig: Option<PathBuf>,
40    /// How bare specifiers matching the importer's own package name are classified
41    /// (spec §4.6, D5). Default: `SelfReferenceMode::External`.
42    pub self_reference_mode: SelfReferenceMode,
43    /// Extra glob patterns (config `exclude`, M5) applied on top of `.gitignore`
44    /// during discovery, rooted at `project_root`. Default: none.
45    pub exclude: Vec<String>,
46}
47
48impl RunnerOptions {
49    /// This struct's documented default for `tsconfig`: `<project_root>/tsconfig.json`
50    /// if it exists as a file, else `None`.
51    pub fn default_tsconfig(project_root: &Path) -> Option<PathBuf> {
52        let candidate = project_root.join("tsconfig.json");
53        candidate.is_file().then_some(candidate)
54    }
55}
56
57/// The signal a cache entry is validated against (L1, `docs/PLAN-lsp.md` §3): a disk
58/// file's `(mtime, size)`, or — when an overlay covers the path — its overlay
59/// version. Overlay content always wins over disk state when both could apply (an
60/// overlaid file's `stat()` is never consulted at all), so the two variants are
61/// mutually exclusive per path, never compared against each other: a file gaining or
62/// losing its overlay naturally changes which variant [`current_stamp`] returns, which
63/// already differs from any previously cached stamp and forces a re-extract.
64#[derive(PartialEq)]
65enum SourceStamp {
66    Disk { mtime: SystemTime, size: u64 },
67    Overlay { version: u64 },
68}
69
70/// One cached extraction result, keyed by file path (see [`ExtractionCache`]):
71/// the [`SourceStamp`] at the time of extraction, plus the owned result. A cache entry
72/// is reused only if a fresh [`current_stamp`] of the file still equals the cached
73/// stamp — good enough to detect any real edit (disk or overlay), and cheap (no
74/// content hashing).
75pub(crate) struct CachedExtraction {
76    stamp: SourceStamp,
77    info: Arc<FileModuleInfo>,
78}
79
80/// Extraction cache keyed by absolute file path (M6, `docs/PLAN-v1.md` §7, watch-mode
81/// brief D-W1): reused across pipeline runs so watch mode's content-only edit cycles
82/// only re-parse the files that actually changed. `WatchSession` owns one and
83/// invalidates entries for files it's told changed (belt-and-braces on top of the
84/// `mtime`/`size` check here, since some filesystems have coarse `mtime` resolution).
85pub(crate) type ExtractionCache = HashMap<PathBuf, CachedExtraction>;
86
87/// A batch of extraction results plus how many of them were actual cache misses
88/// (files that had to be re-parsed) — watch mode reports and tests this count
89/// directly (M6 brief D-W3). `pub(crate)` (not `pub`): only `watch.rs`'s
90/// content-only edit cycle needs to call [`extract_with_cache`] directly, to seed
91/// [`extract_and_link_from`] without going through [`run_with_cache`]'s "structural"
92/// (re-walk + fresh resolver) path.
93pub(crate) struct Extracted {
94    pub(crate) files: Vec<Arc<FileModuleInfo>>,
95    /// Number of `paths` that were NOT served from `cache` this call (i.e. were
96    /// missing, stale, or unreadable-for-stat and thus attempted for extraction).
97    pub(crate) extracted_files: usize,
98}
99
100/// Outcome of a full extract+link pass: the resulting graph plus the total number of
101/// files actually (re-)extracted (cache misses) across the whole pass, including any
102/// fixpoint-discovered files outside the walked set.
103pub struct RunOutcome {
104    pub graph: ModuleGraph,
105    pub extracted_files: usize,
106}
107
108/// Run the discovery + link pipeline: walk `options.roots`, parse+extract every file
109/// found, resolve every specifier they reference, and extract+resolve any internal
110/// resolution target outside the walked set too (so the one-hop check in M3 can look
111/// up its export table and, transitively, the files reachable through its own
112/// `star_exports`) — repeating until a fixpoint is reached. Never panics on a single
113/// file's read/parse/resolve failure; such files are skipped with a stderr warning.
114pub fn run(options: &RunnerOptions) -> ModuleGraph {
115    let mut cache = ExtractionCache::new();
116    run_with_cache(options, &mut cache, &Overlays::default()).graph
117}
118
119/// Same pipeline as [`run`], but extraction is served through `cache` (populated as
120/// it goes) instead of a throwaway one-shot cache. This is the "structural" build
121/// path (M6 brief D-W1): it walks `options.roots` from scratch and constructs a fresh
122/// [`ProjectResolver`], so it's what watch mode calls on startup and whenever the
123/// filesystem layout may have changed (file added/removed/renamed, `package.json`,
124/// config, or tsconfig edited).
125pub(crate) fn run_with_cache(
126    options: &RunnerOptions,
127    cache: &mut ExtractionCache,
128    overlays: &Overlays,
129) -> RunOutcome {
130    let lint_target_paths = timing::phase("walk", || {
131        crate::walk::walk_with_excludes(
132            &options.roots,
133            Some(options.project_root.as_path()),
134            &options.exclude,
135        )
136    });
137
138    let pool = AllocatorPool::new(rayon::current_num_threads());
139    let initial = extract_with_cache(&lint_target_paths, &pool, cache, overlays);
140    let resolver = build_resolver_from_files(options, &lint_target_paths, &initial.files);
141    extract_and_link_from(
142        &lint_target_paths,
143        initial,
144        &resolver,
145        &pool,
146        cache,
147        overlays,
148    )
149}
150
151/// Build a fresh [`ProjectResolver`] for `options`, seeding the ambient-module
152/// registry (D6) from `initial_files` — the already-extracted walked set, restricted
153/// to lint targets inside it (same rule as the original M2 `run`: a `.d.ts` only
154/// reached later via the fixpoint loop never contributes ambient declarations).
155///
156/// Split out from [`run_with_cache`] so watch mode's "structural" reload path
157/// (`crates/cli/src/watch.rs`) can build the resolver once and reuse the same
158/// `initial_files` extraction as the seed for [`extract_and_link_from`], instead of
159/// extracting the walked set twice.
160pub(crate) fn build_resolver_from_files(
161    options: &RunnerOptions,
162    lint_target_paths: &[PathBuf],
163    initial_files: &[Arc<FileModuleInfo>],
164) -> ProjectResolver {
165    let lint_targets: HashSet<PathBuf> = lint_target_paths.iter().cloned().collect();
166    let files_by_path: HashMap<PathBuf, Arc<FileModuleInfo>> = initial_files
167        .iter()
168        .map(|file| (file.path.clone(), file.clone()))
169        .collect();
170    let ambient_modules = build_ambient_registry(&files_by_path, &lint_targets);
171
172    ProjectResolver::new(
173        &options.project_root,
174        options.tsconfig.clone(),
175        ambient_modules,
176        options.self_reference_mode,
177    )
178}
179
180/// Extract+resolve `lint_target_paths` against `resolver` to a fixpoint (PLAN-v1.md
181/// §2.1 steps 3–4): any internal resolution target outside the walked set is
182/// extracted and resolved too, so the one-hop check (M3) can look up its export
183/// table. `initial` is the already-extracted walked set (from [`extract_with_cache`]
184/// on `lint_target_paths`) — passing it in rather than re-deriving it from
185/// `lint_target_paths` lets callers reuse whatever extraction they already did (e.g.
186/// [`build_resolver_from_files`]'s ambient-registry pass) without a second cache
187/// lookup/extraction round, and keeps `extracted_files` counts from being
188/// double-counted.
189///
190/// This is the piece watch mode's content-only edit cycles call directly, reusing the
191/// previous walk result and [`ProjectResolver`] across cycles (M6 brief D-W1): only
192/// `cache` changes between cycles (entries for edited files invalidated by the
193/// caller), so re-running this is cheap when nothing relevant changed.
194pub(crate) fn extract_and_link_from(
195    lint_target_paths: &[PathBuf],
196    initial: Extracted,
197    resolver: &ProjectResolver,
198    pool: &AllocatorPool,
199    cache: &mut ExtractionCache,
200    overlays: &Overlays,
201) -> RunOutcome {
202    let lint_targets: HashSet<PathBuf> = lint_target_paths.iter().cloned().collect();
203
204    // `attempted` guards the fixpoint loop against cycles and against retrying a
205    // file that failed to read/parse on a previous pass: once a path has been
206    // attempted (successfully or not) in this call, it's never re-extracted.
207    let mut attempted: HashSet<PathBuf> = lint_targets.clone();
208    let mut files: HashMap<PathBuf, Arc<FileModuleInfo>> = HashMap::new();
209    let mut resolutions: HashMap<(PathBuf, CompactStr), Provenance> = HashMap::new();
210    let mut extracted_files = initial.extracted_files;
211
212    let mut pending = initial.files;
213    timing::phase(&format!("files_index({} files)", pending.len()), || {
214        for file in &pending {
215            files.insert(file.path.clone(), file.clone());
216        }
217    });
218
219    loop {
220        let round = timing::phase(&format!("resolve({} files)", pending.len()), || {
221            resolve_pairs(&pending, resolver)
222        });
223        timing::phase(&format!("resolutions_merge({} pairs)", round.len()), || {
224            resolutions.extend(round);
225        });
226
227        // Non-TS internal targets (CSS modules, JSON, ...) are deliberately not
228        // extraction candidates: they have no export table to parse — the graph
229        // records them in `non_ts_files` and the rule engine checks them against
230        // the `nonTsFiles` option instead.
231        let mut new_targets: Vec<PathBuf> = resolutions
232            .values()
233            .filter_map(|provenance| match provenance {
234                Provenance::Internal(path)
235                    if !attempted.contains(path) && source_type_for_path(path).is_some() =>
236                {
237                    Some(path.clone())
238                }
239                _ => None,
240            })
241            .collect();
242        new_targets.sort();
243        new_targets.dedup();
244
245        if new_targets.is_empty() {
246            break;
247        }
248        attempted.extend(new_targets.iter().cloned());
249
250        let next = extract_with_cache(&new_targets, pool, cache, overlays);
251        extracted_files += next.extracted_files;
252        pending = next.files;
253        for file in &pending {
254            files.insert(file.path.clone(), file.clone());
255        }
256    }
257
258    let graph = timing::phase("graph_build", || {
259        ModuleGraph::build(files.into_values().collect(), resolutions, lint_targets)
260    });
261    RunOutcome {
262        graph,
263        extracted_files,
264    }
265}
266
267/// Extract every path in `paths`, serving already-extracted, unchanged files from
268/// `cache` and only actually parsing (rayon + `AllocatorPool`, PLAN-v1.md §8) the ones
269/// that are missing or whose `(mtime, size)` no longer matches the cached entry.
270/// Freshly extracted files are inserted into `cache` before returning.
271///
272/// `pub(crate)`: exposed so `watch.rs`'s content-only edit cycle can extract the
273/// (unchanged) walked set through the cache directly, as the seed for
274/// [`extract_and_link_from`], without re-walking or rebuilding the resolver.
275pub(crate) fn extract_with_cache(
276    paths: &[PathBuf],
277    pool: &AllocatorPool,
278    cache: &mut ExtractionCache,
279    overlays: &Overlays,
280) -> Extracted {
281    let mut files: Vec<Arc<FileModuleInfo>> = Vec::with_capacity(paths.len());
282    let mut miss_paths: Vec<PathBuf> = Vec::new();
283
284    timing::phase(&format!("stat({} paths)", paths.len()), || {
285        for path in paths {
286            match current_stamp(path, overlays) {
287                Some(stamp) => {
288                    let cache_hit = cache.get(path).is_some_and(|cached| cached.stamp == stamp);
289                    if cache_hit {
290                        // `cache_hit` guarantees `cache.get(path)` is `Some`.
291                        files.push(cache.get(path).unwrap().info.clone());
292                        continue;
293                    }
294                    miss_paths.push(path.clone());
295                }
296                None => {
297                    // Can't stat and no overlay covers it: vanished between walking
298                    // and extracting, a permission error, or (in principle) a platform
299                    // without `mtime` support. Always treat as a miss —
300                    // `extract_one`'s own read-error path reports/skips it — and drop
301                    // any stale entry so a later re-appearance of the file at this
302                    // path is picked up fresh rather than silently reusing old
303                    // content.
304                    cache.remove(path);
305                    miss_paths.push(path.clone());
306                }
307            }
308        }
309    });
310
311    let extracted_files = miss_paths.len();
312    let newly_extracted = timing::phase(&format!("parse({extracted_files} files)"), || {
313        extract_files(&miss_paths, pool, overlays)
314    });
315    for info in newly_extracted {
316        let arc = Arc::new(info);
317        if let Some(stamp) = current_stamp(&arc.path, overlays) {
318            cache.insert(
319                arc.path.clone(),
320                CachedExtraction {
321                    stamp,
322                    info: arc.clone(),
323                },
324            );
325        }
326        files.push(arc);
327    }
328
329    Extracted {
330        files,
331        extracted_files,
332    }
333}
334
335/// [`SourceStamp`] for `path` right now (L1, `docs/PLAN-lsp.md` §3): the overlay version
336/// if `overlays` covers `path`, else the disk `(mtime, size)` — overlay content always
337/// wins, so an overlaid file's `stat()` is never even consulted.
338fn current_stamp(path: &Path, overlays: &Overlays) -> Option<SourceStamp> {
339    if let Some(version) = overlays.version(path) {
340        return Some(SourceStamp::Overlay { version });
341    }
342    stat(path).map(|(mtime, size)| SourceStamp::Disk { mtime, size })
343}
344
345fn stat(path: &Path) -> Option<(SystemTime, u64)> {
346    let meta = fs::metadata(path).ok()?;
347    let mtime = meta.modified().ok()?;
348    Some((mtime, meta.len()))
349}
350
351/// Parse+extract `paths` in parallel (rayon + `AllocatorPool` arena reuse, PLAN-v1.md
352/// §8): one arena per worker, reset after each file, only the owned
353/// `FileModuleInfo` crosses the parallel boundary. A file that can't be read or
354/// fails to parse is skipped with a stderr warning rather than aborting the run.
355fn extract_files(
356    paths: &[PathBuf],
357    pool: &AllocatorPool,
358    overlays: &Overlays,
359) -> Vec<FileModuleInfo> {
360    paths
361        .par_iter()
362        .filter_map(|path| extract_one(path, pool, overlays))
363        .collect()
364}
365
366fn extract_one(path: &Path, pool: &AllocatorPool, overlays: &Overlays) -> Option<FileModuleInfo> {
367    // Every walked path already has a recognized extension (`walk()` filters for
368    // it), and the fixpoint loop filters non-TS resolution targets out before
369    // extraction, so this branch is defensive only — skip the file the same way
370    // an unparseable one is skipped.
371    let Some(source_type) = source_type_for_path(path) else {
372        eprintln!(
373            "import-lint: {}: unrecognized file extension, skipping",
374            path.display()
375        );
376        return None;
377    };
378
379    // An overlay (an open editor buffer's in-memory content, L1) always wins over
380    // disk content when both exist for `path`.
381    let source_text: Arc<str> = match overlays.content(path) {
382        Some(content) => content,
383        None => match fs::read_to_string(path) {
384            Ok(text) => Arc::from(text),
385            Err(err) => {
386                eprintln!(
387                    "import-lint: cannot read {}: {err}, skipping",
388                    path.display()
389                );
390                return None;
391            }
392        },
393    };
394
395    let allocator = pool.get();
396    // Pre-flight parse to detect syntax errors before handing the source to
397    // `extract_file` (which has no diagnostics in its return type by design — see
398    // `main.rs`'s `inspect` command for the same accepted double-parse trade-off).
399    let preflight = OxcParser::new(&allocator, &source_text, source_type).parse();
400    if preflight.panicked || preflight.diagnostics.has_errors() {
401        eprintln!("import-lint: failed to parse {}, skipping:", path.display());
402        for diagnostic in preflight.diagnostics.errors() {
403            eprintln!("  {diagnostic}");
404        }
405        return None;
406    }
407
408    Some(import_lint::extract_file(
409        path,
410        &source_text,
411        source_type,
412        &allocator,
413    ))
414}
415
416/// Resolve every distinct `(file, specifier)` pair reachable from `files` in
417/// parallel. `ProjectResolver::resolve` is thread-safe by design (PLAN-v1.md §8): one
418/// shared resolver, never a per-file one.
419fn resolve_pairs(
420    files: &[Arc<FileModuleInfo>],
421    resolver: &ProjectResolver,
422) -> HashMap<(PathBuf, CompactStr), Provenance> {
423    let pairs: Vec<(&Path, &CompactStr)> = files
424        .iter()
425        .flat_map(|file| {
426            file.specifiers
427                .iter()
428                .map(move |specifier| (file.path.as_path(), specifier))
429        })
430        .collect();
431
432    pairs
433        .par_iter()
434        .map(|(path, specifier)| {
435            let provenance = resolver.resolve(path, specifier);
436            ((path.to_path_buf(), (*specifier).clone()), provenance)
437        })
438        .collect()
439}
440
441/// Build the ambient-module registry (D6): specifier -> declaring `.d.ts` file,
442/// restricted to the walked (lint target) set. Deterministic on conflict — iterate
443/// candidate files sorted by path, first declaration wins.
444fn build_ambient_registry(
445    files: &HashMap<PathBuf, Arc<FileModuleInfo>>,
446    lint_targets: &HashSet<PathBuf>,
447) -> HashMap<CompactStr, PathBuf> {
448    let mut declaration_files: Vec<&Arc<FileModuleInfo>> = files
449        .values()
450        .filter(|file| lint_targets.contains(&file.path))
451        .filter(|file| {
452            source_type_for_path(&file.path).is_some_and(|t| t.is_typescript_definition())
453        })
454        .collect();
455    declaration_files.sort_by(|a, b| a.path.cmp(&b.path));
456
457    let mut registry = HashMap::new();
458    for file in declaration_files {
459        for specifier in &file.ambient_modules {
460            registry
461                .entry(specifier.clone())
462                .or_insert_with(|| file.path.clone());
463        }
464    }
465    registry
466}