qleaner 1.1.3 → 1.1.5

package/README.md

@@ -1,6 +1,19 @@
 # Qleaner
 
-A powerful CLI tool to analyze and clean up your React codebase by finding unused files and images, providing project insights, and analyzing dependencies.
+❌ Afraid to delete files in a React project?  
+❌ Unsure what's still used?  
+❌ Large repos slowing down devs?
+
+**Qleaner answers those questions safely.**
+
+Qleaner scans your entire codebase with precision, finding unused files, dead assets, and architectural rot—without the risk. It tells you exactly what's safe to delete, backed by comprehensive dependency analysis.
+
+**Developers star tools that:**
+
+- **Save them time** — No more manual hunting through imports and references
+- **Reduce fear** — Dry-run mode shows you exactly what would be deleted before you commit
+- **Prevent mistakes** — Smart caching and incremental scans catch everything
+- **Make them look smart at work** — Clean codebases speak volumes
 
 ## Features
 
@@ -17,6 +30,9 @@ A powerful CLI tool to analyze and clean up your React codebase by finding unuse
 - 💾 **Smart caching**: Caches scan results for faster subsequent runs (automatically invalidates on file changes)
 - 🎨 **CSS and styled-components support**: Detects images used in CSS files and styled-components
 - 🔧 **Configuration file**: Use `qleaner init` to create a `qleaner.config.json` file with default settings for your project
+- 🔗 **Dead link detection**: Identifies images referenced in code but not found in the file system
+- 🔥 **File hotspot analysis**: Discover the most imported files and image hotspots in your codebase
+- ⚠️ **Large file warnings**: Automatically flags code files exceeding 100KB for optimization
 
 ## Installation
 
@@ -43,31 +59,81 @@ qleaner init
 
 This creates a configuration file with default settings for exclusions and image scanning options. You can then modify `qleaner.config.json` to customize your settings.
 
+## Configuration
+
+**Configuration is key!** A good setup saves a lot of time when typing commands. Instead of repeatedly typing long command-line options, configure your defaults once in `qleaner.config.json` and they'll be used automatically.
+
+Qleaner supports configuration through both command-line options and a configuration file (`qleaner.config.json`). Use `qleaner init` to create a default configuration file.
+
+### Configuration File
+
+The `qleaner.config.json` file allows you to set default options that will be merged with command-line options. Command-line options take precedence over configuration file options.
+
+**Configuration options:**
+- `excludeDir` - Array of directories to exclude from scans
+- `excludeFile` - Array of file names to exclude from scans (just use the file name, e.g., `["test.js", "config.js"]`)
+- `excludeExtensions` - Array of file extensions to exclude (e.g., `["test.tsx", "test.ts"]`)
+- `excludeFilePrint` - Array of file names to scan but not print in results (just use the file name). These are also known as **entrypoints** - files that are entry points to your application (like `page.tsx`, `route.ts`, `layout.tsx` in Next.js) that may not be directly imported but are still used by the framework
+- `excludeDirAssets` - Array of directories to exclude from asset scans
+- `excludeFileAssets` - Array of file names to exclude from asset scans (just use the file name)
+- `excludeDirCode` - Array of directories to exclude from code scans
+- `excludeFileCode` - Array of file names to exclude from code scans (just use the file name)
+- `isRootFolderReferenced` - Boolean indicating if images are referenced relative to the file path (e.g., `/img/a.png` where `img` is the root folder and the path is relative to the file location)
+- `alias` - Boolean indicating if aliases are used in image paths (e.g., `@/assets/images/a.png`)
+
+**Common exclusions:**
+- Test files: `-f test.js spec.js` or `excludeExtensions: ["test.tsx", "test.ts"]`
+- Storybook files: `-f stories.js`
+- Test directories: `-e __tests__ __mocks__ test`
+- Build outputs: `-e dist build .next`
+- Configuration files: `-f config.js`
+- Third-party code: `-e node_modules vendor`
+
+**Example configuration file:**
+```json
+{
+  "excludeDir": ["node_modules", "dist", "build"],
+  "excludeFile": [],
+  "excludeExtensions": ["test.tsx", "test.ts"],
+  "excludeFilePrint": ["page.tsx", "route.ts", "layout.tsx"],
+  "isRootFolderReferenced": false,
+  "alias": true
+}
+```
+
 ### Project Summary
 
-Get a comprehensive summary of your project including file counts, unused files/images, and dependencies:
+Get a comprehensive summary of your project including file counts, unused files/images, dead links, dependencies, and file hotspots:
 
 ```bash
 qleaner summary [options]
 ```
 
 **Options:**
-- `-l, --largest-files` - List the largest files in the project
-- `-d, --dependencies` - List the dependencies in the project
+- `-l, --largest-files` - List the largest files in the project (top 10 code files, top 10 image files, files above 100KB, and total sizes)
+- `-d, --dependencies` - List dependency analysis (heavy/light dependencies, file hotspots, dead/alive image hotspots)
 
 **Examples:**
 
 ```bash
 # Get project summary (default)
+# Shows: total code files, total image files, unused files, unused images, dead image links
 qleaner summary
 
 # List the largest files
+# Shows: top 10 largest code files, top 10 largest image files, files above 100KB, total sizes
 qleaner summary --largest-files
 
 # List dependencies
+# Shows: files with heavy/light dependencies, file hotspots (most imported files), dead/alive image hotspots
 qleaner summary --dependencies
 ```
 
+**Summary includes:**
+- **Default summary**: Total code/image files, unused files/images count, dead image links count
+- **Largest files** (`--largest-files`): Top 10 largest code files, top 10 largest image files, code files exceeding 100KB, total code/image sizes
+- **Dependencies** (`--dependencies`): Top 10 files with heavy dependencies, top 10 files with light dependencies, top 10 file hotspots (most imported), top 10 dead/alive image hotspots
+
 **Important:** Before viewing the summary, make sure to run a fresh scan with `--clear-cache` to ensure accurate results. The summary reads from the cache, so outdated cache data will show outdated results.
 
 ### Scan for Unused Files
@@ -186,13 +252,15 @@ qleaner image public/images src --clear-cache
 ```
 
 **What it detects:**
-- Images imported via `import` statements
+- Images imported via `import` statements (static and dynamic imports)
 - Images required via `require()` calls
-- Images used in JSX `src` attributes
+- Images used in JSX `src` attributes (string literals and expressions)
 - Images in CSS `url()` functions (CSS and SCSS files)
 - Images in styled-components and CSS-in-JS template literals
-- Images in inline styles (backgroundImage, etc.)
-- Images referenced in string literals and template literals
+- Images in inline styles (backgroundImage, background, mask, and other image-related properties)
+- Images referenced in string literals and template literals anywhere in code
+- Images in array expressions and spread elements
+- **Dead links**: Images referenced in code but not found in the file system
 
 ## Output Formats
 
@@ -207,7 +275,7 @@ Qleaner provides two output formats:
 2. **Table output**: Formatted tables with organized columns (use `--table` flag)
    - Unused files table shows: Unused file paths with sizes (or "Would Delete" in dry run mode)
    - Unused images table shows: Unused image paths with information about whether they exist and are referenced in code (or "Would Delete" in dry run mode)
-   - Summary tables show: Project statistics, largest files, dependencies, and more
+   - Summary tables show: Project statistics, largest files, dependencies, file hotspots, dead/alive image hotspots, and more
 
 ## How It Works
 
@@ -228,12 +296,15 @@ Qleaner provides two output formats:
 2. **Code Scanning**: Scans all code files (`.js`, `.jsx`, `.ts`, `.tsx`) for image references
 3. **Image Detection**: Detects images through multiple methods:
    - Import statements (`import img from './image.png'`)
+   - Dynamic imports (`import('./image.png')`)
    - Require calls (`require('./image.png')`)
-   - JSX src attributes (`<img src="./image.png" />`)
+   - JSX src attributes (`<img src="./image.png" />` and expressions)
    - CSS url() functions in CSS/SCSS files
    - Styled-components and CSS-in-JS template literals
-   - Inline styles (backgroundImage, etc.)
-   - String and template literals containing image paths
+   - Inline styles (backgroundImage, background, mask, etc.)
+   - String and template literals containing image paths (anywhere in code)
+   - Array expressions with image paths (`['/img/a.png', '/img/b.png']`)
+   - Spread elements in arrays with image references
 4. **Path Normalization**: Normalizes all detected image paths for consistent matching
 5. **Analysis**: Compares discovered image files with detected references to identify unused images
 6. **Reporting**: Outputs the results in standard or table format
@@ -265,49 +336,12 @@ Qleaner provides two output formats:
 - 📊 **Code analysis**: Understand import patterns and dependencies in your codebase through the summary command
 - 🔍 **Project audit**: Identify orphaned files and assets that may have been forgotten
 - 📦 **Bundle optimization**: Find files and images that can be removed to reduce bundle size
-- 📈 **Project insights**: Analyze largest files, dependency patterns, and project statistics
+- 📈 **Project insights**: Analyze largest files, dependency patterns, file hotspots, and project statistics
+- 🔗 **Dead link detection**: Find broken image references (images in code that don't exist on disk)
+- 🔥 **Architecture insights**: Discover which files are most imported (hotspots) and identify dependency-heavy files
+- ⚠️ **Performance warnings**: Get alerted about large files (100KB+) that may impact performance
 - 🎯 **Maintenance**: Keep your codebase clean and maintainable
 
-## Configuration
-
-Qleaner supports configuration through both command-line options and a configuration file (`qleaner.config.json`). Use `qleaner init` to create a default configuration file.
-
-### Configuration File
-
-The `qleaner.config.json` file allows you to set default options that will be merged with command-line options. Command-line options take precedence over configuration file options.
-
-**Configuration options:**
-- `excludeDir` - Array of directories to exclude from scans
-- `excludeFile` - Array of file names to exclude from scans (just use the file name, e.g., `["test.js", "config.js"]`)
-- `excludeExtensions` - Array of file extensions to exclude (e.g., `["test.tsx", "test.ts"]`)
-- `excludeFilePrint` - Array of file names to scan but not print in results (just use the file name)
-- `excludeDirAssets` - Array of directories to exclude from asset scans
-- `excludeFileAssets` - Array of file names to exclude from asset scans (just use the file name)
-- `excludeDirCode` - Array of directories to exclude from code scans
-- `excludeFileCode` - Array of file names to exclude from code scans (just use the file name)
-- `isRootFolderReferenced` - Boolean indicating if root folder is referenced in image paths
-- `alias` - Boolean indicating if aliases are used in image paths
-
-**Common exclusions:**
-- Test files: `-f test.js spec.js` or `excludeExtensions: ["test.tsx", "test.ts"]`
-- Storybook files: `-f stories.js`
-- Test directories: `-e __tests__ __mocks__ test`
-- Build outputs: `-e dist build .next`
-- Configuration files: `-f config.js`
-- Third-party code: `-e node_modules vendor`
-
-**Example configuration file:**
-```json
-{
-  "excludeDir": ["node_modules", "dist", "build"],
-  "excludeFile": [],
-  "excludeExtensions": ["test.tsx", "test.ts"],
-  "excludeFilePrint": ["page.tsx", "route.ts", "layout.tsx"],
-  "isRootFolderReferenced": false,
-  "alias": true
-}
-```
-
 ## Tips and Best Practices
 
 1. **Start with a small scope**: Begin by scanning a specific directory before scanning the entire project
@@ -365,4 +399,4 @@ MIT
 
 ## Version
 
-Current version: 1.0.34
+Current version: 1.1.3

package/command.js

@@ -10,7 +10,6 @@ const {
   getFileHash,
   needsRebuild,
   saveCache,
-  clearCache,
 } = require("./utils/cache");
 const { isExcludedFile, createStepBar } = require("./utils/utils");
 
@@ -114,13 +113,8 @@ async function getFiles(directory = "src", options, chalk) {
 
 // Initializes the cache by clearing it (if requested) and loading it from disk
 function initializeCache(spinner, options, code = true) {
-  if (options.clearCache) {
-    spinner.text = "🔍 Clearing cache...";
-    clearCache(process.cwd());
-    spinner.succeed("Cache cleared successfully");
-  }
   spinner.text = "🔍 Loading cache...";
-  const cache = loadCache(process.cwd());
+  const cache = loadCache(process.cwd(), {code, clearCache: options.clearCache});
   let graph = null;
   let imageGraph = null;
   if (code) {
@@ -182,7 +176,7 @@ async function extractImportsFromFiles(files, graph, resolver, chalk) {
     if (isNeedsRebuild) {
       const ast = parser.parse(code, {
         sourceType: "module",
-        plugins: ["jsx", "typescript"],
+        plugins: ["jsx", "typescript", "decorators-legacy"],
       });
       // check if file is already in graph
       if (graph.has(filePath)) {

package/controllers/image.js

@@ -361,7 +361,7 @@ async function scanCodeFilesForImages(
     if (needsRebuild(filePath, code, imageGraph)) {
       const ast = parser.parse(code, {
         sourceType: "module",
-        plugins: ["jsx", "typescript"],
+        plugins: ["jsx", "typescript", "decorators-legacy"],
       });
       if (imageGraph.has(filePath)) {
         const oldFiles = new Set(imageGraph.get(filePath).imports);

package/controllers/initialize.js

@@ -13,6 +13,8 @@ async function init(chalk) {
         excludeExtensions: [
             "test.tsx",
             "test.ts",
+            "test.js",
+            "test.jsx",
         ], // Exclude file extensions from the scan like .test.tsx, .test.ts, .test.js, .test.jsx
         excludeFilePrint: [
             "page.tsx",
@@ -27,9 +29,7 @@ async function init(chalk) {
             "dist",
             "build",
         ], // Exclude directories from the code scan
-        excludeFileCode: [
-            "index.tsx",
-        ], // Exclude files from the code scan
+        excludeFileCode: [], // Exclude files from the code scan
         isRootFolderReferenced: false, // Is the root folder referenced in the image path eg /img/a.png where img is the image root folder
         alias: true, // Is the alias referenced in the image path eg @/assets/images/a.png
     }, null, 2));

package/controllers/summary.js

@@ -11,7 +11,8 @@ const {
   findCodeFilesAbove100KB,
   getTop10FilesWithHeavyDependencies,
   getTop10FilesWithLightDependencies,
-  getTop10FilesHotspots
+  getTop10FilesHotspots,
+  getTotalImageFiles
 } = require("../utils/summary");
 
 function formatFilePath(filePath, maxLength = 70) {
@@ -96,15 +97,15 @@ function summarizeAll(chalk) {
     console.log(chalk.yellow("   Use the scan command to generate project data.\n"));
     return;
   }
-
+  const totalImageFiles = getTotalImageFiles(imageGraph.graph);
   // summarize the graph
   const summary = {
     totalCodeFiles: codeGraph.graph.size,
-    totalImageFiles: imageGraph.graph.size,
+    totalImageFiles: totalImageFiles,
     totalUnusedFiles: codeGraph.unusedFiles.size,
     totalUnusedImages: imageGraph.unusedImages.size - deadImageLinks.size,
     totalDeadImageLinks: deadImageLinks.size,
-    totalFiles: codeGraph.graph.size + imageGraph.graph.size,
+    totalFiles: codeGraph.graph.size + totalImageFiles,
   };
 
   console.log(chalk.green.bold("\n📋 Project Summary"));

package/package.json

@@ -2,7 +2,7 @@
   "name": "qleaner",
   "description": "A CLI tool for analyzing and identifying unused files, images, imports, and dead code in React, TypeScript, and JavaScript projects to help optimize bundle size and maintain clean codebases",
   "packageManager": "yarn@4.6.0",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "license": "MIT",
   "main": "command.js",
   "bin": "bin/cli.js",

package/qleaner.config.json

@@ -7,7 +7,9 @@
   "excludeFile": [],
   "excludeExtensions": [
     "test.tsx",
-    "test.ts"
+    "test.ts",
+    "test.js",
+    "test.jsx"
   ],
   "excludeFilePrint": [
     "page.tsx",
@@ -22,9 +24,7 @@
     "dist",
     "build"
   ],
-  "excludeFileCode": [
-    "index.tsx"
-  ],
+  "excludeFileCode": [],
   "isRootFolderReferenced": false,
   "alias": true
 }

package/utils/cache.js

@@ -46,7 +46,7 @@ function serializeGraph({ parentGraph, imageParentGraph, isCode = true }) {
     };
 }
 
-function loadCache(rootPath) {
+function loadCache(rootPath, {clearCache, code}) {
   const file = path.join(rootPath, "unused-check-cache.json");
   if (!fs.existsSync(file))
     return {
@@ -62,6 +62,14 @@ function loadCache(rootPath) {
         imageParentGraph: { imageGraph: {}, unusedImages: [] },
       };
     }
+    if(clearCache) {
+      if(code) {
+        cache.parentGraph = { graph: {}, unusedFiles: [] };
+      } else {
+        cache.imageParentGraph = { imageGraph: {}, unusedImages: [] };
+      }
+      fs.writeFileSync(file, JSON.stringify(cache, null, 2));
+    }
     return cache;
   } catch {
     return {

package/utils/summary.js

@@ -89,6 +89,16 @@ function getTop10FilesHotspots(graph, isCheck = true) {
   }
 }
 
+function getTotalImageFiles(graph) {
+  let totalFiles = 0;
+  for (const [filePath, node] of graph.entries()) {
+    if (node.isImage === true) {
+      totalFiles++;
+    }
+  }
+  return totalFiles;
+}
+
 module.exports = {
   getDeadLinks,
   getTotalImageSize,
@@ -99,4 +109,5 @@ module.exports = {
   getTop10FilesWithHeavyDependencies,
   getTop10FilesWithLightDependencies,
   getTop10FilesHotspots,
+  getTotalImageFiles,
 };