npm package: @pamfilico/javascript-utils
Description: JavaScript utilities for component analysis and dead code management in React/Next.js projects
Author: Pamfilico
Latest version: 1.0.1

# @pamfilico/javascript-utils

JavaScript utilities for component analysis and dead code management in React/Next.js projects.

## Features

- **Component Usage Analyzer**: Automatically scans your codebase to find where React/Next.js components are imported and used
- **Dead Component Mover**: Identifies unused components (Usage Count: 0) and moves them to a `dead/` folder for cleanup
- **Automatic Script Injection**: Adds npm scripts to your project's `package.json` on installation

## Installation

```bash
npm install @pamfilico/javascript-utils
```

### Setup Scripts

The package attempts to automatically add npm scripts during installation. If the automatic setup doesn't work (common with `--legacy-peer-deps`), run the init command:

```bash
npx javascript-utils-init
```

This will add two scripts to your `package.json`:

```json
{
  "scripts": {
    "component-usage": "component-usage-analyzer",
    "move-dead-components": "move-dead-components"
  }
}
```

**Recommended installation command:**
```bash
npm install @pamfilico/javascript-utils && npx javascript-utils-init
```

## Usage

### Component Usage Analyzer

Analyzes all components in `src/components/` (root level only) and adds usage comments to the top of each file:

```bash
npm run component-usage
```

**What it does:**
- Scans all `.tsx` and `.ts` files in `src/components/` (excluding subdirectories)
- Searches for imports across your entire `src/` directory
- Adds a comment block at the top of each component with usage information
- Detects both production usage and Storybook stories
- Uses exact identifier matching (no false positives from substring matches)

**Example output in component file:**

```typescript
// START: COMPONENT USAGE TOOL
// Usage Count: 3
//
// Used in:
// - app/[locale]/dashboard/page.tsx:15
// - components/TimelineComponent.tsx:42
//
// Storybook stories:
// - components/MyComponent.stories.tsx:10
// END: COMPONENT USAGE TOOL

import React from 'react';
// ... rest of component
```

### Move Dead Components

Moves components with `Usage Count: 0` to `src/components/dead/` folder:

```bash
npm run move-dead-components
```

**What it does:**
- Reads the usage comment added by `component-usage-analyzer`
- Identifies components with `Usage Count: 0`
- Moves them to `src/components/dead/` folder
- Skips files that already exist in the dead folder
- Provides a summary of moved components

**Workflow:**

```bash
# Step 1: Analyze component usage
npm run component-usage

# Step 2: Review the unused components list in the terminal

# Step 3: Move unused components to dead folder
npm run move-dead-components
```

## How It Works

### Component Detection

The analyzer:
1. **Only scans root-level components** in `src/components/` (ignores subdirectories like `aade/`, `locale/`, etc.)
2. **Searches all files** in `src/` for imports
3. **Matches imports by**:
   - Exact path matching (`@/components/ComponentName`)
   - Relative path resolution (`./ComponentName`, `../../components/ComponentName`)
   - Exact identifier matching in named imports (no substring matching)

### Import Matching Examples

✅ **Detected:**
```typescript
import MyComponent from "@/components/MyComponent";
import { MyComponent } from "@/components/MyComponent";
import MyComponent from "./MyComponent";  // same folder
import MyComponent from "../../../../components/MyComponent";  // relative path
```

❌ **Not detected (different component):**
```typescript
import MyComponentVariant1 from "@/components/MyComponentVariant1";
// Won't match "MyComponent" because exact matching is used
```

### Why Only Root-Level Components?

Subdirectories in `components/` often contain organized feature modules (like `aade/`, `locale/`) where components import each other locally. These internal imports shouldn't be moved to the dead folder, so we only manage root-level components.

## Project Structure Requirements

Your project must have:
```
your-project/
├── src/
│   ├── components/  (this is what gets scanned)
│   │   ├── Component1.tsx
│   │   ├── Component2.tsx
│   │   ├── dead/  (created automatically if needed)
│   │   └── aade/  (subdirectories are ignored)
│   └── app/  (or pages/, or other directories - all searched for imports)
└── package.json
```

## Configuration

Currently, the tools use these defaults:
- **Components directory**: `src/components/`
- **Source directory**: `src/`
- **Dead folder**: `src/components/dead/`

These are hardcoded but can be made configurable in future versions.

## Tips & Best Practices

1. **Run `component-usage` frequently** to keep usage comments up to date
2. **Review unused components** before moving them - some might be new features in development
3. **Keep the dead folder** in version control as a backup before permanent deletion
4. **Re-run `component-usage`** after major refactoring to catch newly unused components

## Troubleshooting

### "Components directory not found"

Make sure you're running the scripts from your project root and you have a `src/components/` directory.

### Scripts not added to package.json

The postinstall script may not run automatically when using `--legacy-peer-deps` or `--force` flags.

**Solution 1: Run the init command**
```bash
npx javascript-utils-init
```

**Solution 2: Manually run postinstall**
```bash
node node_modules/@pamfilico/javascript-utils/scripts/postinstall.js
```

**Solution 3: Manually add scripts to package.json**
```json
{
  "scripts": {
    "component-usage": "component-usage-analyzer",
    "move-dead-components": "move-dead-components"
  }
}
```

### False positives in usage detection

If you see components marked as used when they're not, or vice versa, please check:
- The component name matches the filename exactly
- Imports use exact identifier names (we fixed substring matching issues)
- Relative imports resolve correctly

## Development

### Package Structure

```
@pamfilico/javascript-utils/
├── package.json
├── README.md
├── bin/
│   ├── component-usage-analyzer.js
│   └── move-dead-components.js
└── scripts/
    └── postinstall.js
```

### Local Testing

To test locally before publishing:

```bash
# In the package directory
npm link

# In your project directory
npm link @pamfilico/javascript-utils

# Run the scripts
npm run component-usage
npm run move-dead-components
```

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

MIT

## Author

Pamfilico

## Repository

https://github.com/pamfilico/javascript-utils

---

**Note**: This package modifies your `package.json` during installation to add npm scripts. If you're using this in a CI environment, set the `CI=true` environment variable to skip script injection.

## Publishing (for maintainers)

This package is published to the public npm registry.

### Prerequisites

1. You must be logged in to npm: `npm login`
2. You must have publish access to the `@pamfilico` scope

### Manual Publishing

```bash
# Make your changes and commit them
git add .
git commit -m "feat: your changes"

# Run the release script (bumps version, commits, tags, pushes, and publishes)
./deploy.sh

# Or with a custom message
./deploy.sh -m "feat: added new feature %s"
```

The `deploy.sh` script will:
1. Bump the patch version in package.json
2. Create a git commit with the version
3. Create a git tag (e.g., `v1.0.1`)
4. Push commits and tags to GitHub
5. Publish the package to npm

### First-Time Setup

If you haven't published the package yet:

```bash
# Login to npm
npm login

# Publish for the first time
npm publish --access public
```