dead-code

name	dead-code
description	Find and remove dead code (unused files, exports, class members) using Knip as a candidate generator, then verify each candidate through AST-level analysis and interface tracing before removing anything. Use when the user asks to clean up unused code, find dead code, or reduce the codebase.

/dead-code — Find and Remove Dead Code

Use this skill to find unused files, exports, and class members in the codebase. It uses Knip as a candidate generator, then verifies each candidate through AST-level analysis and interface tracing before removing anything.

NEVER use knip --fix — it has previously deleted code that was actually in use, breaking the editor and tests.

Phase 1: Discovery

Run Knip to generate candidates:

pnpm deadcode 2>&1        # unused files + exports
pnpm deadcode:class 2>&1  # unused class members

Parse the output into three categories:

• Unused files — files with zero imports
• Unused exports — exported symbols with no consumers
• Unused class members — class methods/properties reported as unused

Phase 2: Verification

For each candidate, apply the appropriate checks below. Use scripts/find-refs.ts when reading code alone is insufficient.

Verifying Unused Files

1. Grep for the filename (without extension) across the codebase
2. Check config references: tsconfig.json, vite.*.config.ts, forge.config.ts
3. Check if it's a test helper imported by test files (Knip may miss test-only imports)
4. Check if it's referenced in package.json scripts or CI workflows

Verifying Unused Exports

1. Check if re-exported by a barrel file (index.ts) consumed by another package
2. Check if used in extends/implements clauses
3. Check if used only in test files (Knip sometimes misses test imports)
4. Run npx tsx scripts/find-refs.ts <file> <symbol> for compiler-level reference count

Verifying Unused Class Members (Main Pain Point)

This is where most false positives occur. Knip cannot trace usage through interfaces, composite types, or dep interfaces.

Check these patterns in order:

1. Interface contract — Is the member defined on an interface the class implements? Check the known interface contracts below.
2. Composite type — Is the class consumed through a type intersection? e.g., ShiftEditor = EditorAPI & CanvasCoordinatorContext means all EditorAPI members on Editor are used.
3. Dep interface — Is the member part of a dependency injection interface? Classes implement dep interfaces that are consumed by managers.
4. Base class — Is the member defined on a base class (BaseCommand, BaseTool) and used by subclasses?
5. Abstract member — Is it an abstract method that subclasses must implement?
6. Find References — Run npx tsx scripts/find-refs.ts <file> <memberName> for compiler confirmation.

Known Interface Contracts (Always False Positives)

Members that satisfy any of these interfaces are NOT dead code, even if Knip reports them:

EditorAPI sub-interfaces (apps/desktop/src/renderer/src/lib/tools/core/EditorAPI.ts):

• Viewport: zoomLevel, panX, panY, screenToUpm, upmToScreen, screenToUpmDistance, viewportBounds
• Selection: selectedPointIds, selectedSegmentIds, selectPoints, selectSegments, clearSelection, marqueePreviewPointIds, setMarqueePreview
• HitTesting: hitTestPoint, hitTestSegment, hitTestContour, hitTestBoundingBox, hitTestContourEndpoint, hitTestHandle
• Snapping: createDragSnapSession, createRotateSnapSession, setSnapIndicator
• Editing: startEdit, commitEdit, cancelEdit, isEditing
• Commands: execute
• ToolLifecycle: activeTool, setActiveTool, activeToolSettings
• VisualState: hoveredPoint, setHoveredPoint, hoveredSegment, setHoveredSegment, cursor, setCursor

Font interface (apps/desktop/src/renderer/src/lib/editor/Font.ts):

• getMetrics, getMetadata, getSvgPath, getAdvance, getBbox

Command interface (apps/desktop/src/renderer/src/lib/commands/core/):

• execute, undo, redo, name

Behavior interface (apps/desktop/src/renderer/src/lib/tools/core/):

• canHandle, transition, onTransition

BaseTool abstract members:

• behaviors, render, executeAction, onStateChange, preTransition

Dep interfaces (consumed by managers, implemented by FontEngine or Editor):

• EditingEngineDeps — apps/desktop/src/renderer/src/engine/editing.ts
• SessionEngineDeps — apps/desktop/src/renderer/src/engine/session.ts
• InfoEngineDeps — apps/desktop/src/renderer/src/engine/info.ts
• IOEngineDeps — apps/desktop/src/renderer/src/engine/io.ts
• Snap — apps/desktop/src/renderer/src/managers/SnapManager.ts
• Clipboard — apps/desktop/src/renderer/src/managers/ClipboardManager.ts
• CanvasCoordinatorContext — apps/desktop/src/renderer/src/lib/editor/rendering/CanvasCoordinator.ts

Using the Find References Script

# Check if a symbol has any non-definition references
npx tsx scripts/find-refs.ts apps/desktop/src/renderer/src/lib/editor/Editor.ts undo

# Output shows: file, line, kind (definition vs reference)
# Zero non-definition references = confirmed dead
# >0 references = inspect them to confirm usage

Phase 3: Action

Categorize Results

Present a categorized report:

Category	Meaning	Action
Confirmed dead	No references, not on any interface	Remove with confirmation
Likely dead	Ambiguous — few references, possibly test-only	Flag for human review
False positive	Interface-mediated, dep interface, or base class	Tag with @knipclassignore

Removing Confirmed Dead Code

1. Remove the dead code manually (NEVER use knip --fix)
2. Run verification after each batch of removals:

   pnpm typecheck && pnpm test && pnpm lint:check
   

3. If tests fail, revert the removal and recategorize as "likely dead"

Tagging False Positives

For confirmed false positive class members, add the @knipclassignore JSDoc tag:

/** @knipclassignore */
undo(): void {
    // ...
}

After tagging, decrease the --max-issues threshold in package.json's deadcode:class script:

# Current threshold
pnpm deadcode:class  # check current --max-issues value

# After tagging N false positives, reduce by N
# Edit package.json: --max-issues (current - N)

# Verify the new threshold holds
pnpm deadcode:class

The goal is to drive --max-issues toward 0, at which point CI catches any new dead code with zero tolerance.

Safety Protocol

1. NEVER use knip --fix or deadcode:fix
2. NEVER remove code without verifying it's not used through interfaces
3. ALWAYS run pnpm typecheck && pnpm test && pnpm lint:check after removals
4. ALWAYS check interface contracts before declaring a class member dead
5. If in doubt, categorize as "likely dead" rather than "confirmed dead"