cleanup-audit

What this skill does

# Cleanup Audit

Audits the codebase for accumulated dead weight: unused TypeScript/JS exports, orphaned source files, npm dependencies that are declared but never imported, and manifest entries that point to files that do not exist. Every finding carries a confidence rating. Only HIGH confidence findings are safe to auto-fix.

## Natural Language Triggers

Users may say:
- "cleanup audit"
- "dead code audit"
- "find dead code"
- "orphan files"
- "unused exports"
- "cleanup analysis"
- "find unused dependencies"
- "stale manifest entries"
- "what can I delete"
- "codebase cleanup"

## Parameters

### --scope `<path>`

Restrict analysis to a subtree. Default is the full repository root.

```bash
aiwg cleanup-audit --scope src/cli/
aiwg cleanup-audit --scope agentic/code/addons/
```

### --type `<exports|files|deps|manifests>`

Run only the specified audit type. Omit to run all four.

| Value | Audits |
|-------|--------|
| `exports` | TypeScript/JS exports with no importers |
| `files` | Source files not referenced by any import or manifest |
| `deps` | npm dependencies declared in package.json but not used in code |
| `manifests` | Manifest entries (skills, agents) whose source file does not exist |

Multiple types can be combined:
```bash
aiwg cleanup-audit --type exports --type deps
```

### --json

Emit findings as newline-delimited JSON to stdout instead of the formatted report. Useful for piping into other tools or CI scripts.

```bash
aiwg cleanup-audit --json | jq 'select(.confidence == "HIGH")'
```

### --fix

Auto-apply removals for all HIGH confidence findings. Has no effect without confirmation when any HIGH finding involves a non-trivial deletion (more than 10 lines or a full file). Combine with `--dry-run` to preview what `--fix` would remove.

### --dry-run

Show what `--fix` would remove without writing any changes. If used without `--fix`, behaves as the default read-only audit.

## Execution Flow

### Phase 1: Determine Analysis Scope

1. Parse `--scope` — default to repo root
2. Parse `--type` — default to all four types
3. Parse `--json`, `--fix`, `--dry-run` flags
4. Build file inventory for the scope:
   - All `.ts`, `.tsx`, `.js`, `.mjs` files (for exports and files audits)
   - `package.json` (for deps audit)
   - All `manifest.json` files under `agentic/` (for manifests audit)
5. Communicate scope before analysis begins

**Communicate**:
```
Cleanup Audit
Scope: {scope}
Types: {types}
Mode: {read-only | fix | dry-run fix}

Building file inventory...
  Source files: {N}
  Manifests: {N}
```

### Phase 2: Analyze Unused Exports

Applies to `--type exports`. Identifies TypeScript and JavaScript named exports that are never imported anywhere in the scope.

**Detection approach**:
1. Glob all source files in scope: `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.mjs`
2. Extract all export declarations: `export function`, `export class`, `export const`, `export type`, `export interface`, `export enum`
3. For each exported identifier, grep all source files for imports of that identifier
4. An export is unused if: zero import matches AND it is not referenced in a manifest entry AND it is not a re-export pattern (`export * from`)

**Confidence rules**:

| Signal | Confidence |
|--------|-----------|
| Zero imports found across entire scope | HIGH |
| Zero imports but identifier is a common name (e.g., `index`, `default`) | MEDIUM |
| Zero imports but file is an entry point (`index.ts`, `main.ts`) | LOW |
| Export appears in a barrel file (`index.ts` re-export) | LOW — skip |

**Output per finding**:
```
[UNUSED-EXPORT] HIGH
  File: src/extensions/registry.ts:45
  Export: registerExtension
  Declared: export function registerExtension(ext: Extension): void
  Importers found: 0
  Safe to remove: yes
```

### Phase 3: Detect Orphaned Files

Applies to `--type files`. Identifies source files that are not imported by any other file and not listed in any manifest.

**Detection approach**:
1. Build full file list for scope
2. For each file, check whether its path appears in:
   - Any `import` or `require` statement in any other source file
   - Any `manifest.json` `scripts` or `path` field
   - Any `package.json` `main`, `exports`, or `bin` field
3. A file is orphaned if none of the above references exist

**Confidence rules**:

| Signal | Confidence |
|--------|-----------|
| No references found anywhere | HIGH |
| No references but filename matches common entry point pattern | MEDIUM |
| No references but file is in root of package (may be undiscovered entry) | LOW |
| Test file with no corresponding source file | MEDIUM (orphaned test) |

**Output per finding**:
```
[ORPHANED-FILE] HIGH
  File: src/legacy/old-config-reader.ts
  References found: 0 (imports: 0, manifests: 0, package.json: 0)
  Last modified: 2025-11-02
  Safe to remove: yes
```

### Phase 4: Audit Dependencies

Applies to `--type deps`. Finds npm packages declared in `package.json` that have no `import` or `require` usage anywhere in the codebase.

**Detection approach**:
1. Read `dependencies` and `devDependencies` from `package.json`
2. For each package name, grep source files for:
   - `import ... from '{package}'`
   - `require('{package}')`
   - `import('{package}')`
   - Scoped sub-path imports: `import ... from '{package}/...'`
3. Also check config files for tool references: `.eslintrc`, `jest.config.*`, `tsconfig.json`

**Confidence rules**:

| Signal | Confidence |
|--------|-----------|
| No import/require in source, no config reference | HIGH |
| No import in source but referenced in a config file | LOW — tool dependency, do not remove |
| No import but package name matches a `peerDependency` | LOW — required by consumers |
| No import but package is a type declaration (`@types/...`) | MEDIUM — check if corresponding package is used |

**Output per finding**:
```
[UNUSED-DEP] HIGH
  Package: lodash
  Version: ^4.17.21
  Type: dependency
  Usage in source: 0 files
  Config references: 0
  Safe to remove: yes (run: npm uninstall lodash)
```

### Phase 5: Check Manifest Entries

Applies to `--type manifests`. Finds entries in `manifest.json` files (skills, agents, commands) whose referenced source files or directories do not exist on disk.

**Detection approach**:
1. Glob all `manifest.json` files: `**/manifest.json`
2. For each manifest, inspect entries that reference file paths:
   - `skills[].scripts[]`
   - `agents[].path`
   - `commands[].handler`
   - Any field ending in `path`, `file`, or `script`
3. Resolve each path relative to the manifest file location
4. Check whether the resolved path exists on disk
5. Also flag entries where the declared `name` has no corresponding `{name}/SKILL.md` or `{name}/AGENT.md` directory

**Confidence rules**:

| Signal | Confidence |
|--------|-----------|
| Declared path does not exist | HIGH |
| Declared path exists but is empty directory | MEDIUM |
| Name entry has no corresponding directory | HIGH |
| Script listed but containing skill directory has no SKILL.md | HIGH |

**Output per finding**:
```
[STALE-MANIFEST] HIGH
  Manifest: agentic/code/addons/aiwg-utils/skills/manifest.json
  Entry: skills[12].name = "old-voice-converter"
  Expected path: skills/old-voice-converter/
  Path exists: no
  Safe to remove: yes (remove entry from manifest)
```

### Phase 6: Compile Confidence-Rated Report

Aggregate all findings from Phases 2–5 into a unified report. Sort by confidence (HIGH first), then by type, then by file path.

**Report format**:
```markdown
# Cleanup Audit Report
Generated: {timestamp}
Scope: {scope}
Types: {types}

## Summary

| Type | HIGH | MEDIUM | LOW | Total |
|------|------|--------|-----|-------|
| Unused exports | {N} | {N} | {N} | {N} |
| Orphaned files | {N} | {N} | {N} | {N} |
| Unused deps | {N} | {N} | {N} | {N} |
| Stale manifests | {N} | {N} | {N} | {N} |
| **Total** | **{N}** | **{N}** | **{N}** | **{N}** |

Auto-fixable (HIGH confidence): {N} findings

## HIGH Confidence Findings

### Unused Exports