@gld5000-cli/dependency-finder 1.0.0 → 1.0.2

package/README.md

@@ -1,66 +1,185 @@
 # [@gld5000-cli/dependency-finder](https://www.npmjs.com/package/@gld5000-cli/dependency-finder)
 
-Finds how many dependents your components have.
+[![npm version](https://badge.fury.io/js/@gld5000-cli%2Fdependency-finder.svg)](https://www.npmjs.com/package/@gld5000-cli/dependency-finder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Install
+A CLI tool that analyzes your codebase to find component dependencies and identify unused components. Perfect for refactoring, deprecation planning, and keeping your codebase clean.
 
-```
-npm i -D @gld5000-cli/dependency-finder
-```
+## Features
+
+- 🔍 **Dependency Analysis** - Scans your components and finds all files that import them
+- 📊 **Usage Reports** - Generates detailed JSON reports categorizing components by usage
+- 🎯 **Dead Code Detection** - Identifies components with zero dependents (potential candidates for removal)
+- ⚙️ **Flexible Configuration** - Customize search patterns, target paths, and ignore patterns
+- 🚀 **Zero Config** - Works out of the box with sensible defaults for React/TypeScript projects
+- 📁 **Batch Analysis** - Analyze multiple component directories at once
+
+## Use Cases
 
-## Example Usage
+- **Identify Unused Components** - Find components that are never imported or used
+- **Refactoring Priorities** - Determine which components are most heavily used before making breaking changes
+- **Deprecation Planning** - Safely deprecate components by knowing exactly where they're used
+- **Code Cleanup** - Remove dead code with confidence
+- **Codebase Health** - Get insights into component coupling and usage patterns
 
-### Import (.mjs)
+## Prerequisites
+
+- Node.js 14.x or higher
+
+## Run with prompts
 
 ```
-import * as dependencyFinder from '@gld5000-cli/dependency-finder'
+npx @gld5000-cli/dependency-finder
 ```
 
-### Example Input
+## Run with arguments
 
 ```
-Add your code here...
+npx @gld5000-cli/dependency-finder [Component directory] [Dependents paths] [File ignore patterns]
 ```
 
-### Example Output
+### Arguments
+
+| Argument                 | Description                                                  | Default                                   | Example                         |
+| ------------------------ | ------------------------------------------------------------ | ----------------------------------------- | ------------------------------- |
+| **Component directory**  | Glob pattern for component files to analyze                  | `./components/**/*.tsx`                   | `./src/components/**/*.tsx`     |
+| **Dependents paths**     | Pipe-separated glob patterns for where to search for imports | `./components/**/*.tsx\|./pages/**/*.tsx` | `./src/**/*.tsx\|./app/**/*.ts` |
+| **File ignore patterns** | Pipe-separated patterns to exclude from analysis             | `.test\|.stories`                         | `.test\|.spec\|.mock`           |
+
+### Example Usage
 
+```bash
+# Analyze all TSX components in a specific structure
+npx @gld5000-cli/dependency-finder "./components/**/*.tsx" "./components/**/*.tsx|./pages/**/*.tsx" ".test|.stories"
+
+# Analyze TypeScript files across the entire src directory
+npx @gld5000-cli/dependency-finder "./src/components/**/*.ts" "./src/**/*.ts" ".test|.spec"
+
+# Analyze React components including JSX
+npx @gld5000-cli/dependency-finder "./components/**/*.{tsx,jsx}" "./src/**/*.{tsx,jsx}|./pages/**/*.{tsx,jsx}" ".test|.stories|.mock"
 ```
-Add your code here...
+
+## Output
+
+The tool generates a `dependents-report.json` file in your project root with the following structure:
+
+```json
+{
+  "noDependents": {
+    "count": 2,
+    "results": [
+      {
+        "matches": [],
+        "filePath": "components/Button/index.tsx",
+        "dependents": []
+      },
+      {
+        "matches": ["UnusedComponent"],
+        "filePath": "components/UnusedComponent.tsx",
+        "dependents": []
+      }
+    ]
+  },
+  "someDependents": {
+    "count": 1,
+    "results": [
+      {
+        "matches": ["Header"],
+        "filePath": "components/Header.tsx",
+        "dependents": [
+          {
+            "filePath": "pages/index.tsx",
+            "matches": ["import { Header } from '../components/Header'"]
+          },
+          {
+            "filePath": "pages/about.tsx",
+            "matches": ["import { Header } from '../components/Header'"]
+          }
+        ]
+      }
+    ]
+  }
+}
 ```
 
-## Update
+### Understanding the Output
 
+- **noDependents**: Components with zero imports (candidates for removal)
+  - `count`: Number of unused components
+  - `results`: Array of unused component details
+- **someDependents**: Components that are imported somewhere
+  - `count`: Number of used components
+  - `results`: Array of components with their import locations
+- **matches**: Export names found in the component file
+- **dependents**: List of files that import this component and the exact import statements
+
+## How It Works
+
+1. **Discover Components** - Scans your codebase using the component directory pattern to find all component files
+2. **Extract Exports** - Identifies exported components in each file
+3. **Search for Imports** - Searches target paths for import statements referencing each component
+4. **Categorize Results** - Groups components into those with dependents and those without
+5. **Generate Report** - Creates a detailed JSON report with all findings
+
+The tool uses glob patterns for flexible file matching and supports filtering to exclude test files, stories, and other non-production code.
+
+## Examples
+
+### Find Unused Components in a Large Project
+
+```bash
+npx @gld5000-cli/dependency-finder "./src/components/**/*.tsx" "./src/**/*.tsx|./app/**/*.tsx" ".test|.stories|.spec"
 ```
-npm update @gld5000-cli/dependency-finder
-```
 
-## Uninstall
+After running, check `dependents-report.json` and review the `noDependents` section for components that can be safely removed.
+
+### Audit Before Deprecating a Component Library
 
+```bash
+npx @gld5000-cli/dependency-finder "./components/**/*.tsx" "./pages/**/*.tsx|./features/**/*.tsx|./layouts/**/*.tsx" ".test"
 ```
-npm uninstall @gld5000-cli/dependency-finder
+
+Review the `someDependents` section to see exactly where each component is used before deprecating or refactoring.
+
+### Quick Check on Component Usage
+
+```bash
+# Run with defaults for standard React project structure
+npx @gld5000-cli/dependency-finder
 ```
 
+Follow the prompts to customize paths for your project structure.
+
+## Contributing
+
+Contributions are welcome! Feel free to:
+
+- Report bugs by opening an issue
+- Suggest new features
+- Submit pull requests
+
+Please ensure any changes include appropriate tests.
 
 ## License
 
-MIT License
-
-Copyright (c) 2026 Gareth L Devlin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 Gareth L Devlin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gld5000-cli/dependency-finder",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Finds how many dependents your components have.",
   "keywords": [
     "CLI",
@@ -22,6 +22,7 @@
   "license": "MIT",
   "author": "GLD5000",
   "type": "commonjs",
+  "bin": "bin/index.mjs",
   "main": "src/index.mjs",
   "scripts": {
     "test": "node test/test.mjs"

package/test/test-components/folder-a/test1.tsx

@@ -1,3 +0,0 @@
-export default function ComponentA() {
-  return <div>Test</div>;
-}

package/test/test-components/folder-b/test2.tsx

@@ -1,3 +0,0 @@
-export const ComponentB = () => {
-  return <div>Test</div>;
-};

package/test/test-components/folder-c/test3.tsx

@@ -1,5 +0,0 @@
-const ComponentC = () => {
-  return <div>Test</div>;
-};
-
-export default ComponentC;

package/test/test-components/index.tsx

@@ -1,3 +0,0 @@
-import ComponentA from "./folder-a/test1";
-import { ComponentA } from "./folder-a/test1";
-import { ComponentB } from "./folder-b/test2";

package/test/test.mjs

@@ -1,39 +0,0 @@
-import { runDependencyFinder } from "../src/index.mjs";
-import { answerStringQuestion } from "@gld5000-cli/readline";
-
-const args = process.argv.slice(2);
-const defaultSearchPattern = "./components/**/*.tsx";
-const searchPattern =
-  args[0] ||
-  (await answerStringQuestion(
-    "Where are your components?",
-    defaultSearchPattern,
-  ));
-
-const defaultTargetPaths = "./components/**/*.tsx|./pages/**/*.tsx";
-const targetPaths = `${
-  args[1] ||
-  (await answerStringQuestion(
-    "Which folders should we check for imports (pipe-separated)?",
-    defaultTargetPaths,
-  ))
-}`.split("|");
-
-const defaultIgnorePatterns = ".test|.stories";
-const ignorePatterns = `${
-  args[2] ||
-  (await answerStringQuestion(
-    "Which filename patterns should be ignored (pipe-separated)?",
-    defaultIgnorePatterns,
-  ))
-}`.split("|");
-// node test/test.mjs "test/test-components/**/*.tsx" "test/test-components/**/*.tsx" ".test|.stories"
-console.log(
-  "searchPattern:",
-  searchPattern,
-  "targetPaths:",
-  targetPaths,
-  "ignorePatterns:",
-  ignorePatterns,
-);
-runDependencyFinder(searchPattern, targetPaths, ignorePatterns);