qleaner 1.2.0 → 1.3.0

package/README.md

@@ -1,21 +1,23 @@
 # Qleaner
 
-**Qleaner** (v1.2.0) is a powerful CLI tool for analyzing and cleaning up React, TypeScript, and JavaScript projects. It helps you identify unused files, images, dependencies, and dead code to optimize your bundle size and maintain a clean codebase.
+**Qleaner** (v1.3.0) is a powerful CLI tool for analyzing and cleaning up React, TypeScript, and JavaScript projects. It helps you identify unused files, images, dependencies, and dead code to optimize your bundle size and maintain a clean codebase.
 
-## ✨ Features
+## Features
 
-- 🔍 **Find Unused Code Files** - Identify files that aren't imported or used anywhere
-- 🖼️ **Find Unused Images** - Detect image assets that are never referenced in your code
-- 📦 **Unused Dependencies** - Discover npm/yarn packages that are installed but not used
-- 🔗 **Dead Image Links** - Find image references in code that point to non-existent files
-- 📊 **Project Summary** - Get comprehensive statistics about your codebase
-- 📈 **File Size Analysis** - Identify the largest files and potential optimization targets
-- 🎯 **Dependency Analysis** - See which files have heavy dependencies and hotspots
-- 💾 **Smart Caching** - Fast incremental scans with intelligent cache invalidation
-- 🧪 **Dry-Run Mode** - Preview what would be deleted without actually deleting anything
-- 🗑️ **Interactive Deletion** - Choose to delete files permanently or move them to `.trash`
+- **Find Unused Code Files** - Identify files that aren't imported or used anywhere
+- **Find Unused Images** - Detect image assets that are never referenced in your code
+- **Unused Dependencies** - Discover npm/yarn packages that are installed but not used
+- **Dead Image Links** - Find image references in code that point to non-existent files
+- **Project Summary** - Get comprehensive statistics about your codebase
+- **File Size Analysis** - Identify the largest files and potential optimization targets
+- **Dependency Analysis** - See which files have heavy dependencies and hotspots
+- **Smart Caching** - Fast incremental scans with intelligent cache invalidation
+- **Dry-Run Mode** - Preview what would be deleted without actually deleting anything
+- **Interactive Deletion** - Choose to delete files permanently or move them to `.trash`
+- **Enhanced File Finding** - Advanced path resolution using jsconfig/tsconfig for accurate dependency tracking in large codebases with complex import structures
+- **Advanced Image Detection** - Sophisticated AST parsing extracts image references from imports, requires, JSX, CSS, styled-components, template literals, arrays, and more
 
-## 🚀 Installation
+## Installation
 
 ### Global Installation
 
@@ -37,20 +39,32 @@ yarn add qleaner --dev
 npm install qleaner --save-dev
 ```
 
-## 📖 Quick Start
+## Quick Start
 
 ### 1. Initialize Configuration
 
+**IMPORTANT:** Proper configuration is critical for Qleaner to accurately find and resolve files in your project, especially for large codebases. Take time to get this right!
+
 First, set up Qleaner for your project:
 
 ```bash
 qleaner init
 ```
 
-This interactive command will:
-- Ask about your package manager (npm/yarn/pnpm)
-- Configure image path resolution (aliases or root-referenced paths)
-- Detect your framework (React/Next.js) to set appropriate entry points
+This interactive command will ask you:
+1. **Package manager** (npm/yarn/pnpm)
+2. **Image path resolution** - How you reference images (relative paths vs absolute paths from public/)
+3. **Framework type** (React or Next.js) - Sets appropriate entry points
+4. **Configuration file for path aliases** - **This is crucial!** Select which config file Qleaner should use to resolve import aliases:
+   - `tsconfig.json` (most common for TypeScript projects)
+   - `jsconfig.json` (for JavaScript projects)
+   - `tsconfig.app.json` (for monorepos or specific app configs)
+   - `tsconfig.base.json` (for monorepo base configs)
+   - `none` (if you don't use path aliases or want to configure manually)
+
+**Why this matters:** Qleaner uses your project's `jsconfig.json` or `tsconfig.json` file to understand how import paths are resolved. This enables accurate file finding even in large codebases with complex path aliases (e.g., `@/components`, `~/utils`, etc.). Selecting the correct config file ensures Qleaner can properly trace dependencies and find all file references.
+
+**If you don't use jsconfig/tsconfig:** Select "none" during initialization, then manually add your path aliases to the `paths` field in `qleaner.config.json` (see Configuration section below).
 
 This creates a `qleaner.config.json` file in your project root with sensible defaults.
 
@@ -81,24 +95,47 @@ qleaner image public/images src -a --dry-run
 qleaner image public/images src -r --dry-run
 ```
 
-## 📋 Commands
+## Commands
 
 ### `qleaner init`
 
 Initialize Qleaner with an interactive configuration wizard. This command asks you a series of questions to set up Qleaner for your project and creates a `qleaner.config.json` file in your project root with sensible defaults.
 
+**Configuration is Critical:** Getting the configuration right, especially the jsconfig/tsconfig selection, is essential for Qleaner to accurately find files in large codebases. Incorrect configuration may result in false positives (files reported as unused when they're actually used) or missed dependencies.
+
 **Questions asked:**
-1. Package manager (npm, yarn, or pnpm)
-2. Whether you use path aliases for images (e.g., `@/assets/...`)
-3. Framework type (React or Next.js)
+1. **Package manager** (npm, yarn, or pnpm)
+2. **Image path resolution** - How you reference images:
+   - Relative paths (e.g., `./assets/logo.png`)
+   - Absolute paths from public/ (e.g., `/images/logo.png`)
+3. **Framework type** (React or Next.js) - Determines entry point files
+4. **Configuration file for path aliases** - **Most important question!** Select which config file Qleaner should use:
+   - `tsconfig.json` - Standard TypeScript configuration
+   - `jsconfig.json` - Standard JavaScript configuration  
+   - `tsconfig.app.json` - App-specific config (common in monorepos)
+   - `tsconfig.base.json` - Base config (common in monorepos)
+   - `none` - No config file (use manual path configuration)
+
+**Why the config file matters:**
+- Qleaner reads path aliases from your `jsconfig.json` or `tsconfig.json` to resolve imports like `@/components/Button` or `~/utils/helpers`
+- This enables accurate dependency tracking even in large projects with complex import structures
+- Without the correct config file, Qleaner may not properly resolve aliased imports, leading to incorrect results
+
+**If you don't have a jsconfig/tsconfig file:**
+- Select "none" during initialization
+- Manually configure path aliases in the `paths` field of `qleaner.config.json` (see Configuration section)
+- Example: `"paths": { "@/*": ["./src/*"], "~/*": ["./src/*"] }`
 
 **Examples:**
 ```bash
 # Initialize with interactive prompts
 qleaner init
 
-# After initialization, you can run scans
-qleaner scan src
+# After initialization, verify your config
+cat qleaner.config.json
+
+# Then run your first scan
+qleaner scan src --dry-run
 ```
 
 **Note:** If you already have a `qleaner.config.json` file, this command will prompt you before overwriting it. You can manually edit the config file instead if needed.
@@ -309,7 +346,7 @@ qleaner summary --dependencies
 
 **Note:** Requires a cache file. Run `qleaner scan <path>` to generate code cache and/or `qleaner image <dir> <root>` to generate image cache first.
 
-## ⚙️ Configuration
+## Configuration
 
 Qleaner can be configured via `qleaner.config.json` or CLI flags. CLI flags always override config file values.
 
@@ -317,6 +354,8 @@ Qleaner can be configured via `qleaner.config.json` or CLI flags. CLI flags alwa
 
 ```json
 {
+  "codeAlias": "tsconfig.json",
+  "paths": {},
   "packageManager": "yarn",
   "excludeDir": ["node_modules", "dist", "build", ".next"],
   "excludeFile": ["payload-types.ts"],
@@ -335,6 +374,8 @@ Qleaner can be configured via `qleaner.config.json` or CLI flags. CLI flags alwa
 
 | Option | Type | Description |
 |--------|------|-------------|
+| `codeAlias` | string \| null | **Critical!** Config file to use for path alias resolution. Options: `"tsconfig.json"`, `"jsconfig.json"`, `"tsconfig.app.json"`, `"tsconfig.base.json"`, or `null` for manual configuration. Qleaner reads path aliases from this file to resolve imports (e.g., `@/components`, `~/utils`). |
+| `paths` | object | **Manual path aliases** (only used if `codeAlias` is `null`). Object mapping alias patterns to file paths. Example: `{ "@/*": ["./src/*"], "~/*": ["./src/*"] }`. If `codeAlias` is set, this field is ignored and paths are read from the config file instead. |
 | `packageManager` | string | Package manager used: `npm`, `yarn`, or `pnpm` |
 | `excludeDir` | string[] | Directories to exclude from code scans |
 | `excludeFile` | string[] | Files to exclude by name from code scans |
@@ -347,7 +388,36 @@ Qleaner can be configured via `qleaner.config.json` or CLI flags. CLI flags alwa
 | `isRootFolderReferenced` | boolean | `true` if image paths are root-referenced (e.g., `/images/logo.png`) |
 | `alias` | boolean | `true` if image paths use aliases (e.g., `@/assets/images/logo.png`) |
 
-**Important:** `isRootFolderReferenced` and `alias` should not both be `true` or both be `false`. Set one to `true` and the other to `false`.
+**Important Configuration Notes:**
+
+1. **`codeAlias` and `paths`:** 
+   - If `codeAlias` is set (e.g., `"tsconfig.json"`), Qleaner will read path aliases from that config file. The `paths` field will be ignored.
+   - If `codeAlias` is `null`, Qleaner will use the `paths` field for manual path alias configuration.
+   - **Getting this right is crucial** for accurate file resolution in large codebases!
+
+2. **`isRootFolderReferenced` and `alias`:** These should not both be `true` or both be `false`. Set one to `true` and the other to `false`.
+
+### Manual Path Configuration
+
+If you don't use `jsconfig.json` or `tsconfig.json`, or need custom path resolution, you can manually configure paths in `qleaner.config.json`:
+
+```json
+{
+  "codeAlias": null,
+  "paths": {
+    "@/*": ["./src/*"],
+    "~/*": ["./src/*"],
+    "components/*": ["./src/components/*"],
+    "utils/*": ["./src/utils/*"]
+  }
+}
+```
+
+The `paths` object follows the same format as TypeScript's path mapping:
+- **Key:** The alias pattern (e.g., `"@/*"` matches `@/components`, `@/utils`, etc.)
+- **Value:** Array of actual file paths to resolve to (relative to project root)
+
+**Example:** If you have `import Button from '@/components/Button'` in your code, and your config has `"@/*": ["./src/*"]`, Qleaner will resolve it to `./src/components/Button.tsx` (or `.ts`, `.jsx`, `.js`).
 
 ### Default Exclusions
 
@@ -373,7 +443,7 @@ Qleaner automatically excludes common build and generated directories:
 - `_app.tsx`, `_app.jsx`, `_document.tsx`, `_document.jsx`
 - `_error.tsx`, `_error.jsx`
 
-## 💾 Caching
+## Caching
 
 Qleaner uses intelligent caching to speed up subsequent scans:
 
@@ -391,7 +461,7 @@ Qleaner uses intelligent caching to speed up subsequent scans:
 qleaner scan src --clear-cache
 ```
 
-## 🗑️ File Deletion
+## File Deletion
 
 When you run a scan without `--dry-run`, Qleaner will prompt you to:
 
@@ -408,59 +478,77 @@ When you run a scan without `--dry-run`, Qleaner will prompt you to:
 5. Test your application
 6. Empty `.trash` when confident
 
-## 🔧 How It Works
+## How It Works
 
 ### Code Analysis
-1. **File Discovery** - Uses `fast-glob` to find all code files matching patterns
-2. **AST Parsing** - Parses JavaScript/TypeScript with Babel to extract imports
-3. **Module Resolution** - Uses `enhanced-resolve` to resolve import paths (supports aliases)
-4. **Dependency Graph** - Builds a graph of file dependencies
-5. **Unused Detection** - Identifies files with no incoming imports (except entry points)
+1. **File Discovery** - Uses `fast-glob` to find all code files matching patterns with intelligent exclusion handling
+2. **Path Alias Resolution** - Reads path aliases from your `jsconfig.json` or `tsconfig.json` (or manual `paths` config) to understand how imports are resolved. This enables accurate file finding even in large codebases with complex import structures.
+3. **AST Parsing** - Parses JavaScript/TypeScript with Babel to extract imports and exports from code files
+4. **Module Resolution** - Uses `enhanced-resolve` with your project's path aliases to resolve import paths accurately. Supports:
+   - Path aliases (e.g., `@/components`, `~/utils`)
+   - Relative imports (`./component`, `../utils`)
+   - Node modules (`react`, `lodash`)
+   - Directory index files (automatically resolves `./components` to `./components/index.ts`)
+5. **Dependency Graph** - Builds a comprehensive graph of file dependencies, tracking both imports and exports
+6. **Unused Detection** - Identifies files with no incoming imports (except entry points defined in `excludeFilePrint`)
 
 ### Image Analysis
-1. **Image Discovery** - Finds all image files (png, jpg, jpeg, svg, gif, webp)
-2. **Code Scanning** - Extracts image references from:
-   - Import statements
-   - Require calls
-   - JSX attributes (`<img src>`)
-   - CSS files (`url()`)
-   - Styled-components
-   - Template literals
-   - Arrays
-   - String literals
-3. **Path Normalization** - Normalizes paths based on alias/root configuration
-4. **Unused Detection** - Compares image files against references
+1. **Image Discovery** - Finds all image files (png, jpg, jpeg, svg, gif, webp) using glob patterns with exclusion support
+2. **Advanced Code Scanning** - Uses sophisticated AST traversal to extract image references from:
+   - ES6 import statements (`import logo from './logo.png'`)
+   - CommonJS require (`require('./logo.png')`)
+   - Dynamic imports (`import('./logo.png')`)
+   - JSX attributes (`<img src="./logo.png" />`)
+   - React style props (`style={{ backgroundImage: "url('./logo.png')" }}`)
+   - CSS files (`url('./logo.png')` or `url('/images/logo.png')`)
+   - Styled-components (`` css`background-image: url('./logo.png')` ``)
+   - Arrays (`const images = ['./logo.png', './icon.png']`)
+   - Template literals (`` `./logo-${name}.png` ``)
+   - String literals (any string containing an image path pattern)
+   - Spread elements in arrays
+3. **Path Normalization** - Normalizes paths based on alias/root configuration, handling both relative and absolute paths
+4. **Unused Detection** - Compares image files against all discovered references to identify truly unused images
 
 ## 📊 Example Workflow
 
 ```bash
-# 1. Initialize configuration
+# 1. Initialize configuration (CRITICAL STEP - get this right!)
 qleaner init
+# Make sure to select the correct jsconfig.json or tsconfig.json file
+# Verify the generated qleaner.config.json has the correct codeAlias
+
+# 2. Verify your configuration
+cat qleaner.config.json
+# Check that codeAlias matches your project's config file
 
-# 2. Scan for unused code files (dry run)
+# 3. Scan for unused code files (dry run first!)
 qleaner scan src --dry-run --table
 
-# 3. Scan for unused images (dry run)
+# 4. Review results - if you see false positives, check your config
+# Fix codeAlias or paths if needed, then clear cache and rescan:
+qleaner scan src --clear-cache --dry-run --table
+
+# 5. Scan for unused images (dry run)
 qleaner image public/images src -r --dry-run --table
 
-# 4. Check for unused dependencies
+# 6. Check for unused dependencies
 qleaner dep --table
 
-# 5. Get project summary
+# 7. Get project summary
 qleaner summary
 
-# 6. Get largest files report
+# 8. Get largest files report
 qleaner summary --largest-files
 
-# 7. Get dependency analysis
+# 9. Get dependency analysis
 qleaner summary --dependencies
 
-# 8. Once confident, run actual scans and delete files
+# 10. Once confident with results, run actual scans and delete files
 qleaner scan src
 qleaner image public/images src -r
 ```
 
-## 🎯 Use Cases
+## Use Cases
 
 - **Before Deployment** - Clean up unused files to reduce bundle size
 - **Code Review** - Verify no unused files are being added
@@ -468,12 +556,12 @@ qleaner image public/images src -r
 - **Optimization** - Identify large files and dependency hotspots
 - **Maintenance** - Regular cleanup to keep codebase healthy
 
-## 📝 Requirements
+## Requirements
 
 - Node.js 14+ (LTS recommended)
 - npm or yarn
 
-## 🤝 Contributing
+## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
@@ -487,7 +575,7 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 MIT
 
-## 🔗 Links
+## Links
 
 - **Repository:** [https://github.com/trevismurithi/react-cleaner](https://github.com/trevismurithi/react-cleaner)
 - **Issues:** [https://github.com/trevismurithi/react-cleaner/issues](https://github.com/trevismurithi/react-cleaner/issues)
@@ -497,13 +585,16 @@ MIT
 
 ### Tips for Best Results
 
-1. **Run scans regularly** - Set up a cron job or CI check to catch unused files early
-2. **Use dry-run first** - Always preview with `--dry-run` before deleting anything
-3. **Review entry points** - Make sure `excludeFilePrint` in config includes all entry point files (index.tsx, main.js, etc.)
-4. **Clear cache when needed** - After major refactoring or dependency changes, use `--clear-cache` for accurate results
-5. **Test after deletion** - Always test your application thoroughly after removing files
-6. **Use table format for large outputs** - The `-t` flag makes results easier to read
-7. **Check summary regularly** - Use `qleaner summary` to monitor project health
+1. **Get configuration right first** - **Most important!** Ensure `codeAlias` points to the correct `jsconfig.json` or `tsconfig.json` file, or manually configure `paths` if you don't use these config files. Incorrect configuration leads to false positives and missed dependencies.
+2. **Verify your config file** - After running `qleaner init`, check that `codeAlias` matches your project's actual config file. For monorepos, you may need `tsconfig.app.json` or `tsconfig.base.json` instead of `tsconfig.json`.
+3. **Run scans regularly** - Set up a cron job or CI check to catch unused files early
+4. **Use dry-run first** - Always preview with `--dry-run` before deleting anything
+5. **Review entry points** - Make sure `excludeFilePrint` in config includes all entry point files (index.tsx, main.js, etc.)
+6. **Clear cache when needed** - After major refactoring, dependency changes, or config file updates, use `--clear-cache` for accurate results
+7. **Test after deletion** - Always test your application thoroughly after removing files
+8. **Use table format for large outputs** - The `-t` flag makes results easier to read
+9. **Check summary regularly** - Use `qleaner summary` to monitor project health
+10. **For large codebases** - The enhanced file finding mechanism with proper config ensures accurate results even in projects with thousands of files and complex import structures
 
 ### Command Dependencies
 
@@ -520,7 +611,14 @@ Some commands require cache files from other commands:
 ### Common Issues
 
 **Q: Qleaner reports files as unused that are actually used.**
-A: These are likely entry points. Add them to `excludeFilePrint` in your config or use `-F` flag. Also verify the file is actually imported somewhere - check with `qleaner list <file-path>`.
+A: 
+1. **Check your configuration** - Most commonly, this happens when `codeAlias` is incorrect or `paths` is not configured properly. Verify that Qleaner can resolve your import aliases:
+   - Ensure `codeAlias` points to the correct config file (check if it exists and has the right path mappings)
+   - If using manual `paths`, verify the alias patterns match your imports
+   - Try running with `--clear-cache` after fixing config
+2. These might be entry points - Add them to `excludeFilePrint` in your config or use `-F` flag
+3. Verify the file is actually imported - Check with `qleaner list <file-path>` to see if it's referenced
+4. Check for dynamic imports - Some dynamic imports may not be detected
 
 **Q: Images aren't being detected.**
 A: 
@@ -533,8 +631,20 @@ A:
 A: 
 - First scan is always slower - it builds the complete dependency graph
 - Subsequent scans use caching and are much faster (only changed files are re-analyzed)
+- The enhanced file finding mechanism with proper config ensures accurate and efficient resolution even in large codebases
 - Exclude more directories with `-e` flag to speed up scans
 - Consider scanning smaller subdirectories separately
+- Ensure your `codeAlias` config is correct - incorrect config can cause unnecessary resolution attempts
+
+**Q: How do I know if my configuration is correct?**
+A:
+- After `qleaner init`, verify `codeAlias` in `qleaner.config.json` matches your project's config file
+- Run a test scan: `qleaner scan src --dry-run` and check if files you know are used are incorrectly reported as unused
+- If you see false positives, check:
+  1. Does your `jsconfig.json`/`tsconfig.json` exist and have correct `paths` configuration?
+  2. Is `codeAlias` pointing to the right file?
+  3. If using manual `paths`, do the patterns match your import statements?
+- For monorepos, you may need `tsconfig.app.json` or `tsconfig.base.json` instead of `tsconfig.json`
 
 **Q: How do I undo deletions?**
 A: 
@@ -556,4 +666,4 @@ A:
 
 ---
 
-**Made with ❤️ for clean codebases**
+**Made with love for clean codebases**