chore: improve doc

Author: edvincandon

README.md

@@ -4,6 +4,7 @@
 
 <h2 align="center">barrel-reaper</h2>
 <p align="center"><em>Barrel files sunt diabolus. Amen.</em><br>Rewrites barrel imports as direct imports at the source. </p>
+<p align="center"><sub>Parses with <a href="https://oxc.rs">oxc</a>, walks files in parallel with <a href="https://github.com/rayon-rs/rayon">rayon</a>.</sub></p>
 
 
 --- 
@@ -33,7 +34,7 @@ Options:
 ## Examples
 
 ```sh
-# dry run — show what would change
+# dry run: show what would change
 barrel-reaper -b src/lib/index.ts -a @lib -d
 
 # rewrite in place, scoped to a subtree
@@ -43,6 +44,27 @@ barrel-reaper -b src/lib/index.ts -a @lib -g 'src/app/**'
 barrel-reaper -b src/lib/index.ts
 ```
 
+## Monorepos & path aliases
+
+Resolution is delegated to the nearest `tsconfig.json` discovered per-file,
+falling back to `node_modules` for bare specifiers outside of `paths`.
+**Install your dependencies first** (`pnpm install`, `yarn`, etc.) so
+workspace packages are symlinked under `node_modules`. Without this, bare
+aliases like `@scope/pkg` can't be resolved and those imports are silently
+treated as non-barrel.
+
+If reaper finds fewer files than expected, run with `--debug`:
+
+```sh
+barrel-reaper -b packages/components/index.ts -g 'apps/account/**' \
+  -a @scope/components -d --debug
+```
+
+For every file that *mentions* the barrel but whose imports didn't classify,
+it prints each specifier's resolver outcome on stderr: enough to pinpoint
+whether it's a missing `paths` entry, a sub-path import, or an uninstalled
+workspace package.
+
 ## Library
 
 ```rust

src/exports.rs

@@ -67,6 +67,9 @@ fn collect_into(
             Statement::ExportNamedDeclaration(decl) => {
                 handle_export_named(decl, file, barrel_dir, alias, resolver, exports);
             }
+            // Only the barrel's own `export default` becomes the published
+            // default. Defaults re-exported from deeper files arrive as
+            // named specifiers and are handled by `handle_export_named`.
             Statement::ExportDefaultDeclaration(_) if file == barrel => {
                 exports.insert(
                     "default".to_string(),
@@ -96,6 +99,7 @@ fn handle_export_all(
     let resolved = resolver.resolve(from_module, file);
 
     match &decl.exported {
+        // `export * as ns from './x'`: publishes `ns` as a single namespace.
         Some(name_node) => {
             exports.insert(
                 name_node.name().to_string(),
@@ -106,6 +110,7 @@ fn handle_export_all(
                 },
             );
         }
+        // `export * from './x'`: recurse and hoist every named export.
         None => {
             if let Some(target) = resolved {
                 collect_into(&target, barrel, alias, resolver, exports, visited);

src/imports.rs

@@ -13,6 +13,8 @@ use rayon::prelude::*;
 use crate::resolver::ModuleResolver;
 use crate::{Context, SymbolKind};
 
+/// Skipped even when not in `.gitignore` (common build outputs that
+/// projects routinely forget to ignore).
 const DEFAULT_IGNORED_DIRS: &[&str] = &[
     "node_modules",
     "target",
@@ -55,11 +57,10 @@ pub fn find_barrel_imports(ctx: &Context, resolver: &ModuleResolver) -> Vec<Barr
     })
 }
 
-/// Shared walker + discover pipeline. Canonicalizes once, streams entries
-/// through rayon via `par_bridge`, reads each file a single time, pre-filters
-/// by needle, parses, extracts barrel-import statements, then hands
-/// `(path, source, statements)` to `process`. Files with no barrel imports
-/// are dropped before `process` runs.
+/// Discovery pipeline: walk, fast-string pre-filter, parse, extract barrel
+/// import statements, then hand `(path, source, statements)` to `process`.
+/// Each file is read exactly once; files with no barrel imports are dropped
+/// before `process` runs.
 pub(crate) fn walk_barrel_candidates<T, F>(
     ctx: &Context,
     resolver: &ModuleResolver,
@@ -72,9 +73,8 @@ where
     let Ok(barrel_path) = fs::canonicalize(&ctx.barrel_file) else {
         return Vec::new();
     };
-    // Canonicalize root once so walker entries are absolute — oxc_resolver's
-    // per-file tsconfig walk-up needs an absolute anchor, and this avoids a
-    // syscall per candidate.
+    // oxc_resolver's per-file tsconfig walk-up needs absolute paths.
+    // Canonicalizing the root once avoids a syscall per candidate.
     let Ok(root) = fs::canonicalize(&ctx.root_dir) else {
         return Vec::new();
     };
@@ -137,6 +137,9 @@ where
     results
 }
 
+/// Short strings any barrel-importing file must contain. The alias catches
+/// `@lib`-style imports; the parent dir name catches relative imports like
+/// `../lib` (index files are referenced by their folder).
 fn build_needles(ctx: &Context) -> Vec<String> {
     let mut needles = Vec::with_capacity(2);
     if let Some(alias) = &ctx.barrel_alias {
@@ -247,6 +250,8 @@ fn extract_specifiers(decl: &ImportDeclaration) -> Vec<BarrelImport> {
                     type_import: stmt_type_only || s.import_kind.is_type(),
                 })
             }
+            // `import * as X from barrel` pulls in the whole module;
+            // nothing to split, so we leave it untouched.
             ImportDeclarationSpecifier::ImportNamespaceSpecifier(_) => None,
         })
         .collect()

src/path.rs

@@ -14,6 +14,9 @@ pub fn resolve_export_path(from_module: &str, alias: Option<&str>) -> String {
     }
 }
 
+/// Relative import string between two files. Always prefixed with `./` when
+/// not climbing with `../`, since bare paths would parse as bare-package
+/// specifiers.
 pub fn get_import_path(from_file: &Path, to_file: &Path) -> String {
     let from_dir = from_file.parent().unwrap_or(Path::new(""));
     let rel = pathdiff::diff_paths(to_file, from_dir).unwrap_or_else(|| to_file.to_path_buf());

src/reaper.rs

@@ -26,10 +26,9 @@ pub fn rewrite(
             .iter()
             .any(|imp| resolves(ctx, exports, &imp.import_name));
 
-        // If no specifier in this statement resolves, leaving it intact
-        // keeps the consumer compilable (it would fail the same way it did
-        // before reaper ran) — dropping it gains nothing. Still flag each
-        // name so the CLI can surface the mismatch.
+        // Leave the statement intact when nothing resolves: the consumer
+        // stays as-broken-as-before, and dropping it would only mask the
+        // mismatch. Names still flow into `unresolved` for the CLI.
         if !any_resolvable {
             unresolved.extend(stmt.imports.iter().map(|i| i.import_name.clone()));
             continue;
@@ -102,6 +101,8 @@ fn format_import(
     }
 }
 
+/// Swallow the trailing newline so removing the statement doesn't leave a
+/// blank line behind.
 fn expand_to_line_end(source: &str, span: Span) -> Span {
     let end = span.end as usize;
     let new_end = source[end..]
@@ -110,6 +111,7 @@ fn expand_to_line_end(source: &str, span: Span) -> Span {
     Span::new(span.start, new_end as u32)
 }
 
+/// Assumes `spans` is sorted ascending and non-overlapping.
 fn remove_spans(source: &str, spans: &[Span]) -> String {
     let mut out = String::with_capacity(source.len());
     let mut cursor = 0;

src/resolver.rs

@@ -12,6 +12,8 @@ impl ModuleResolver {
             extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]
                 .map(String::from)
                 .to_vec(),
+            // Auto walks up from each resolved file to find the nearest
+            // tsconfig. Required for monorepos where `paths` differ per package.
             tsconfig: Some(TsconfigDiscovery::Auto),
             ..ResolveOptions::default()
         };
@@ -20,6 +22,8 @@ impl ModuleResolver {
         }
     }
 
+    /// Must use `resolve_file` (not the dir-form API): `TsconfigDiscovery::Auto`
+    /// is silently ignored by the dir form.
     pub fn resolve(&self, specifier: &str, from_file: &Path) -> Option<PathBuf> {
         self.inner
             .resolve_file(from_file, specifier)