# Angular Clean

A CLI tool to detect unused Angular components, services, pipes, modules, and directives in your Angular projects.

## Features

- 🔍 **Smart Detection**: Understands Angular-specific usage patterns
- 🎯 **Accurate Analysis**: Components in modules but with unused selectors are marked as unused
- 📊 **Clear Reports**: Shows unused code grouped by type with file paths
- 🚀 **Fast**: Efficiently scans and analyzes large Angular projects
- 🔧 **Flexible**: Supports both standalone and module-based components (Angular 20+)
- 💡 **Detailed Mode**: Optionally shows where each artifact IS used

## Installation

### Global Installation

```bash
npm install -g angular-clean
```

### Local Installation (per project)

```bash
npm install --save-dev angular-clean
```

### Use with npx (no installation)

```bash
npx angular-clean
```

## Usage

### Basic Usage

Run in your Angular project directory:

```bash
ng-clean
```

Or specify a path:

```bash
ng-clean /path/to/angular/project
```

### Options

- **`[path]`**: Path to Angular project (default: current directory)
- **`-d, --detailed`**: Show detailed usage information for used artifacts
- **`-t, --type <type>`**: Filter by artifact type (`component|service|pipe|module|directive`)
- **`-e, --exclude <patterns...>`**: Additional exclude patterns
- **`-h, --help`**: Display help information
- **`-V, --version`**: Display version number

### Examples

**Show all unused code:**
```bash
ng-clean
```

**Show only unused components:**
```bash
ng-clean --type component
```

**Show detailed usage information:**
```bash
ng-clean --detailed
```

**Analyze specific project:**
```bash
ng-clean ~/projects/my-angular-app
```

**Exclude additional patterns:**
```bash
ng-clean --exclude "**/*.stories.ts" "**/*.example.ts"
```

## How It Works

Angular Clean performs intelligent analysis to detect truly unused code:

### Components & Directives
- ✅ Marked as **used** if:
  - Selector appears in any template (HTML or inline)
  - Class is referenced in routes
  - Imported by standalone component
- ❌ Marked as **unused** if:
  - Only declared in a module but selector never used
  - Class never imported

### Services
- ✅ Marked as **used** if:
  - Injected in any component/service/directive
  - Provided in module or standalone component
- ❌ Marked as **unused** if:
  - Never injected anywhere

### Pipes
- ✅ Marked as **used** if:
  - Used in any template with pipe syntax (`| pipeName`)
  - Imported by standalone component
- ❌ Marked as **unused** if:
  - Only declared in module but never used in templates

### Modules
- ✅ Marked as **used** if:
  - Imported by other modules or standalone components
- ❌ Marked as **unused** if:
  - Never imported anywhere

## Output Example

```
🔍 Angular Clean - Unused Code Analyzer

Analyzing project at: /Users/dev/my-angular-app

📁 Scanning TypeScript files...
✓ Found 145 Angular artifacts
🔍 Analyzing template usage...
🔍 Analyzing code usage...
📊 Generating report...

═════════════════════════════════════════════════════════════════════
  Angular Unused Code Analysis Report
═════════════════════════════════════════════════════════════════════

Summary:
──────────────────────────────────────────────────
  Components        5 unused / 42 total  (88.1% used)
  Services          2 unused / 28 total  (92.9% used)
  Pipes             0 unused / 8 total   (100.0% used)
  Modules           1 unused / 12 total  (91.7% used)
  Directives        1 unused / 5 total   (80.0% used)
──────────────────────────────────────────────────
  Total Unused: 9

Components (5):
────────────────────────────────────────────────────────────────────────────
  🧩 UnusedHeaderComponent
     src/app/components/unused-header/unused-header.component.ts
     selector: app-unused-header
     standalone: false

  ...

⚠️  Found 9 unused artifact(s)
```

## CI/CD Integration

Angular Clean exits with code `1` if unused code is detected, making it perfect for CI/CD pipelines:

```json
{
  "scripts": {
    "lint:unused": "ng-clean"
  }
}
```

Add to your GitHub Actions, GitLab CI, or other CI/CD:

```yaml
- name: Check for unused code
  run: npm run lint:unused
```

## Programmatic Usage

You can also use Angular Clean programmatically in your Node.js scripts:

```typescript
import { analyzeAngularProject } from 'angular-clean';

const report = await analyzeAngularProject({
  path: './my-angular-app',
  detailed: true,
});

console.log(`Found ${report.totalUnused} unused artifacts`);
```

## Default Exclusions

The following patterns are excluded by default:
- `**/node_modules/**`
- `**/dist/**`
- `**/build/**`
- `**/*.spec.ts`
- `**/*.test.ts`
- `**/e2e/**`

## Requirements

- Node.js 18 or higher
- Angular 20 or higher (with support for standalone components)
- TypeScript 5.0 or higher

## Limitations

- Does not analyze dynamic component loading (e.g., `ComponentFactoryResolver`)
- Does not track usage through string references
- May not detect usage in complex Angular patterns (multi-level lazy loading, etc.)

## Contributing

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

## License

MIT

## Author

Created with ❤️ for the Angular community
