/configure:dead-code

Check and configure dead code detection tools.

Context

This command validates dead code detection configuration and sets up analysis tools.

Dead code detection tools:

• JavaScript/TypeScript: Knip (finds unused files, exports, dependencies)
• Python: Vulture or deadcode (finds unused code)
• Rust: cargo-machete (finds unused dependencies)

Version Checking

CRITICAL: Before configuring dead code detection tools, verify latest versions:

1. Knip: Check knip.dev or npm
2. Vulture: Check PyPI
3. cargo-machete: Check crates.io

Use WebSearch or WebFetch to verify current versions before configuring dead code detection.

Workflow

Phase 1: Language Detection

Detect project language and existing dead code detection tools:

Indicator	Language	Tool
knip.json or knip.config.*	JavaScript/TypeScript	Knip
package.json with knip	JavaScript/TypeScript	Knip
pyproject.toml [tool.vulture]	Python	Vulture
.vulture or vulture.ini	Python	Vulture
Cargo.toml	Rust	cargo-machete

Phase 2: Current State Analysis

For each detected tool, check configuration:

Knip:

• knip.json or config file exists
• Entry points configured
• Ignore patterns set
• Plugin configurations
• Workspace support (monorepo)
• CI integration

Vulture:

• Configuration file exists
• Minimum confidence set
• Paths configured
• Ignore patterns
• Allowlist file (if needed)

deadcode (Python):

• pyproject.toml configuration
• Exclude patterns
• Dead code detection rules

cargo-machete (Rust):

• Installed as cargo subcommand
• Workspace configuration
• CI integration

Phase 3: Compliance Report

Generate formatted compliance report:

Dead Code Detection Compliance Report
======================================
Project: [name]
Language: [TypeScript | Python | Rust]
Tool: [Knip 5.x | Vulture 2.x | cargo-machete 0.6.x]

Configuration:
  Config file             knip.json                  [✅ EXISTS | ❌ MISSING]
  Entry points            configured                 [✅ CONFIGURED | ⚠️ AUTO-DETECTED]
  Ignore patterns         node_modules, dist         [✅ CONFIGURED | ⚠️ INCOMPLETE]
  Plugin support          enabled                    [✅ ENABLED | ⏭️ N/A]

Detection Scope:
  Unused files            enabled                    [✅ ENABLED | ❌ DISABLED]
  Unused exports          enabled                    [✅ ENABLED | ❌ DISABLED]
  Unused dependencies     enabled                    [✅ ENABLED | ❌ DISABLED]
  Unused types            enabled                    [✅ ENABLED | ❌ DISABLED]
  Duplicate exports       enabled                    [✅ ENABLED | ⏭️ N/A]

Scripts:
  dead-code command       package.json scripts       [✅ CONFIGURED | ❌ MISSING]
  dead-code:fix           package.json scripts       [⏭️ N/A | ❌ MISSING]

Integration:
  Pre-commit hook         .pre-commit-config.yaml    [⚠️ OPTIONAL | ❌ MISSING]
  CI/CD check             .github/workflows/         [✅ CONFIGURED | ❌ MISSING]

Current Analysis (if available):
  Unused files            [X files]                  [✅ NONE | ⚠️ FOUND]
  Unused exports          [X exports]                [✅ NONE | ⚠️ FOUND]
  Unused dependencies     [X packages]               [✅ NONE | ⚠️ FOUND]

Overall: [X issues found]

Recommendations:
  - Remove unused dependencies to reduce bundle size
  - Clean up unused exports to improve maintainability
  - Add allowlist for intentionally unused code

Phase 4: Configuration (if --fix or user confirms)

Knip Configuration (JavaScript/TypeScript)

Install Knip:

npm install --save-dev knip
# or
bun add --dev knip

Create knip.json:

{
  "$schema": "https://unpkg.com/knip@5/schema.json",
  "entry": [
    "src/index.ts",
    "src/cli.ts",
    "src/server.ts"
  ],
  "project": [
    "src/**/*.ts",
    "src/**/*.tsx"
  ],
  "ignore": [
    "src/**/*.test.ts",
    "src/**/*.spec.ts",
    "dist/**",
    "coverage/**"
  ],
  "ignoreDependencies": [
    "@types/*"
  ],
  "ignoreExportsUsedInFile": true,
  "ignoreBinaries": [
    "tsc",
    "tsx"
  ],
  "workspaces": {
    ".": {
      "entry": "src/index.ts",
      "project": "src/**/*.ts"
    }
  }
}

Alternative TypeScript config (knip.config.ts):

import type { KnipConfig } from 'knip';

const config: KnipConfig = {
  entry: [
    'src/index.ts',
    'src/cli.ts',
  ],
  project: [
    'src/**/*.ts',
    'src/**/*.tsx',
  ],
  ignore: [
    'src/**/*.test.ts',
    'dist/**',
    'coverage/**',
  ],
  ignoreDependencies: [
    '@types/*',
  ],
  ignoreExportsUsedInFile: true,
};

export default config;

Add npm scripts to package.json:

{
  "scripts": {
    "knip": "knip",
    "knip:production": "knip --production",
    "knip:dependencies": "knip --dependencies",
    "knip:exports": "knip --exports",
    "knip:files": "knip --files"
  }
}

Vulture Configuration (Python)

Install Vulture:

uv add --group dev vulture

Create pyproject.toml section:

[tool.vulture]
min_confidence = 80
paths = ["src", "tests"]
exclude = [
    "*/migrations/*",
    "*/tests/fixtures/*",
]
ignore_decorators = ["@app.route", "@celery.task"]
ignore_names = ["setUp", "tearDown", "setUpClass", "tearDownClass"]
make_whitelist = true

Alternative: Create .vulture config:

[vulture]
min_confidence = 80
paths = src,tests
exclude = migrations,fixtures

Create allowlist file vulture-allowlist.py:

"""
Vulture allowlist for intentionally unused code.

This file is referenced by Vulture to ignore known false positives.
"""

# Intentionally unused for future use
future_feature
placeholder_function

# Framework-required but appears unused
class Meta:
    pass

Add scripts (manual command):

uv run vulture src/ --min-confidence 80

deadcode Configuration (Python Alternative)

Install deadcode:

uv add --group dev deadcode

Create pyproject.toml section:

[tool.deadcode]
exclude = [
    "tests",
    "migrations",
]
ignore-names = [
    "Meta",
    "setUp",
    "tearDown",
]

Run deadcode:

uv run deadcode src/

cargo-machete Configuration (Rust)

Install cargo-machete:

cargo install cargo-machete --locked

Run cargo-machete:

cargo machete

Optional: Create .cargo-machete.toml:

[workspace]
# Exclude specific packages
exclude = ["example-package"]

# Ignore specific dependencies
ignore = ["tokio"]  # Used in proc macros

For workspace:

[workspace.metadata.cargo-machete]
ignored = ["serde"]  # Used by derive macros

Phase 5: Usage Examples

Knip Usage

Find all unused code:

npm run knip

Production mode (ignore devDependencies):

npm run knip:production

Find unused dependencies only:

npm run knip:dependencies

Find unused exports only:

npm run knip:exports

Fix automatically (remove unused dependencies):

knip --fix

Vulture Usage

Basic scan:

uv run vulture src/ --min-confidence 80

Generate allowlist:

uv run vulture src/ --make-whitelist > vulture-allowlist.py

With allowlist:

uv run vulture src/ vulture-allowlist.py

Sorted by confidence:

uv run vulture src/ --sort-by-size

cargo-machete Usage

Find unused dependencies:

cargo machete

Fix automatically:

cargo machete --fix

Check specific package:

cargo machete --package my-crate

Phase 6: CI/CD Integration

GitHub Actions - Knip

Add to workflow:

- name: Install dependencies
  run: npm ci

- name: Run Knip
  run: npm run knip
  continue-on-error: true  # Don't fail CI, just warn

- name: Run Knip (production mode)
  run: npm run knip:production

GitHub Actions - Vulture

Add to workflow:

- name: Install dependencies
  run: uv sync --group dev

- name: Run Vulture
  run: uv run vulture src/ --min-confidence 80
  continue-on-error: true  # Don't fail CI, just warn

GitHub Actions - cargo-machete

Add to workflow:

- name: Install cargo-machete
  run: cargo install cargo-machete --locked

- name: Check for unused dependencies
  run: cargo machete
  continue-on-error: true  # Don't fail CI, just warn

Phase 7: Allowlists and Ignores

Knip ignores:

{
  "ignoreDependencies": [
    "@types/*"
  ],
  "ignoreExportsUsedInFile": true,
  "ignoreMembers": [
    "then",
    "catch"
  ]
}

Vulture allowlist patterns:

# vulture-allowlist.py
"""Intentionally unused code."""

# Framework hooks
def setUp(self): pass
def tearDown(self): pass

# Future API
future_endpoint

# Exported for library users
public_api_function

cargo-machete ignores:

[workspace.metadata.cargo-machete]
ignored = [
    "serde",        # Used in derive macros
    "tokio",        # Used in proc macros
    "anyhow",       # Used via ? operator
]

Phase 8: Pre-commit Integration (Optional)

Knip (warning only):

repos:
  - repo: local
    hooks:
      - id: knip
        name: knip
        entry: npx knip
        language: node
        pass_filenames: false
        always_run: true
        stages: [manual]  # Only run manually, not on every commit

Vulture (warning only):

repos:
  - repo: local
    hooks:
      - id: vulture
        name: vulture
        entry: uv run vulture src/ --min-confidence 80
        language: system
        types: [python]
        pass_filenames: false
        stages: [manual]  # Only run manually

Phase 9: Standards Tracking

Update .fvh-standards.yaml:

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  dead_code: "2025.1"
  dead_code_tool: "[knip|vulture|deadcode|machete]"
  dead_code_ci: true

Phase 10: Updated Compliance Report

Dead Code Detection Configuration Complete
===========================================

Language: TypeScript
Tool: Knip 5.x

Configuration Applied:
  ✅ knip.json created
  ✅ Entry points configured
  ✅ Ignore patterns set
  ✅ Plugin support enabled

Scripts Added:
  ✅ npm run knip (full scan)
  ✅ npm run knip:production (production mode)
  ✅ npm run knip:dependencies (deps only)
  ✅ npm run knip:exports (exports only)

Integration:
  ✅ CI/CD check added (warning mode)

Initial Scan Results:
  📊 Unused files: 3
  📊 Unused exports: 12
  📊 Unused dependencies: 2

Next Steps:
  1. Run initial scan:
     npm run knip

  2. Review findings and clean up:
     - Remove unused files
     - Remove unused exports
     - Remove unused dependencies (npm uninstall)

  3. Add allowlist for false positives:
     Edit knip.json to ignore specific items

  4. Verify CI integration:
     Push changes and check workflow

Documentation: docs/DEAD_CODE.md

Flags

Flag	Description
--check-only	Report status without offering fixes
--fix	Apply all fixes automatically without prompting
--tool <tool>	Override tool detection (knip, vulture, deadcode, machete)

Examples

# Check compliance and offer fixes
/configure:dead-code

# Check only, no modifications
/configure:dead-code --check-only

# Auto-fix with Knip
/configure:dead-code --fix --tool knip

Error Handling

• No language detected: Cannot determine appropriate tool, error
• Tool installation fails: Report error, suggest manual installation
• Configuration conflicts: Warn about multiple tools, suggest consolidation
• High number of findings: Suggest starting with allowlist

See Also

• /configure:linting - Configure linting tools
• /configure:all - Run all FVH compliance checks
• Knip documentation: https://knip.dev
• Vulture documentation: https://github.com/jendrikseipp/vulture
• cargo-machete documentation: https://github.com/bnjbvr/cargo-machete