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}