# Dead Code Detection - Caveats and Limitations

This document describes known limitations and caveats of the dead code detection implementation.

## False Positives

Code may be flagged as dead even when it is actually used in the following scenarios:

### Reflection and Introspection

**TypeScript**
- Functions called via decorators or metaprogramming
- Protocol handlers and dynamic interfaces
- Module exports accessed via `eval()`, `new Function()`
- CLI commands registered at runtime
- Methods called only via `getattr`/`setattr` patterns

**Go**
- Methods used via the `reflect` package
- Database models with reflection-based field access
- Protocol implementations not directly referenced
- RPC/gRPC handler registration patterns

### Framework Entry Points

- Test files without explicit main/test functions
- React components rendered via lazy loading or code splitting
- API route handlers registered via decorators or framework registration
- Event listeners added dynamically at runtime
- Middleware and hook patterns
- Database migration files

### Interface and Protocol Implementations

- Interface method implementations never directly called
- Struct fields or properties accessed via reflection
- Protocol handler methods
- Generic type implementations
- Trait implementations

### Dynamic Exports

- `export { foo }` re-export patterns (parser tracks import_clause but not all export forms)
- `export default` expressions
- Symbols exported but only referenced from other files
- Namespace exports (`export * from 'module'`)

### Type-Only Declarations

- TypeScript: Type aliases, interfaces, type annotations
- Go: Type definitions used only for compile-time checking

## False Negatives

Dead code may not be detected in the following scenarios:

### Dynamic Calls

- `eval()`, `new Function()` in TypeScript
- `reflect` package usage in Go
- JSON schema-based function calls
- API handler registration patterns
- Template literal-based calls

### Framework-Specific Patterns

- React props passed but not directly used in component body
- GraphQL resolvers and schema definitions
- Database ORM relations and hooks
- Docker/Kubernetes configuration references
- OpenAPI/Swagger schema references

### Cross-File Limitations

- Doesn't track import chains (A → imports B → imports C)
- Re-exported symbols may not be fully followed
- Namespace import references (e.g., `utils.foo()`) require manual verification
- Indirect calls through module boundaries

### Language-Specific Gaps

#### TypeScript

- **Unsupported Syntax**:
  - TSX/JSX syntax
  - Decorators (not parsed or analyzed)
  - Property accessors (getters/setters)
  - Computed property names
  - Template literal type references
  - `export default Foo` expressions

- **Type Analysis**: Purely AST-based, no type information used
  - Symbol collisions across types not resolved
  - Interface vs class distinctions ignored
  - Type parameter tracking absent

#### Go

- **Unsupported Constructs**:
  - Interface method tracking (methods implementing interfaces)
  - Struct field names
  - Constant declarations (`const foo = 1`)
  - Build tags and constraints
  - Function literals and closures

- **Method Names**: Method tracking uses receiver type but may miss pointer vs value receiver distinctions

### Scope Limitations

- Block scoping not tracked (for loops, if statements, switch cases)
- Nested function scope shadows may cause misidentification
- Variable hoisting patterns not recognized (JavaScript/TypeScript legacy patterns)
- Closure captures not analyzed

## Implementation-Specific Issues

### All Identifiers Returned

The parsers return ALL identifiers including:
- Function names in declarations
- Parameter names
- Definition positions
- Local variable declarations

The core logic filters these, but this is inefficient and may lead to missed edge cases.

### Export Detection Limited

**TypeScript**:
- Only detects `export function foo()` or `export class Foo {}` patterns
- Does not detect:
  - `export { foo }` from re-exports
  - `export as namespace foo`
  - `export default` expressions
  - Exported functions called only from other files without explicit tracking

**Go**:
- Only uppercase first letter detection (convention-based)
- Does not check actual package-level visibility
- Does not handle unexported methods on exported types

### Type-Only Imports

TypeScript parser checks for `import type` keyword but may miss:
- Inline `import { type Foo }` patterns (TypeScript 5.0+)
- `import type * as T from 'foo'` patterns

### No Type Analysis

Purely AST-based approach without type information:
- Symbol collisions across types not resolved
- Cannot distinguish overloaded functions
- Generic type tracking absent
- Interface vs struct confusion in Go

### No Entry Point Detection

Does not identify:
- `main()` functions intended as entry points
- `app.start()` or similar initialization patterns
- Library exports that are always intended to be used

### Blank Identifier (_)

- TypeScript: `_` as intentional unused parameter
- Go: `_` identifiers for intentionally ignored return values
- Both: May not correctly distinguish intentional vs unintentional unused

## Configuration Recommendations

To improve accuracy, consider adding support for:

### 1. Entry Point Marking

```typescript
// @vibelexity entry-point
export function main() { ... }
```

```go
// @vibelexity entry-point
func main() { ... }
```

### 2. Always-Exported Symbols

Configuration file to specify symbols that are always considered used:

```yaml
 always-exported:
   - React.Component
   - express.Router
   - render.*
```

### 3. Framework-Specific Ignorance

Pattern-based exclusions:

```yaml
 ignore-patterns:
   - "test_*"
   - "*_test"
   - "*.test.*"
   - "*.spec.*"
```

### 4. Known Framework Patterns

```yaml
 frameworks:
   react:
     - Component props
     - useContext/hook usage
   graphql:
     - Field resolvers
     - Type definitions
   fastapi:
     - Route decorators
```

### 5. Cross-File Symbol Resolution

Full dependency graph analysis could:
- Track import chains across multiple files
- Follow re-exports through the dependency tree
- Better identify truly unused exports

### 6. Type Information Integration

Adding type analysis would improve:
- Distinguishing overlapping symbol names
- Generic type tracking
- Interface implementation detection

### 7. Test File Detection

Auto-detect and exclude:
- Files matching `*test*`
- Files in `tests/` directories
- Files in `__tests__/` directories
- Files with `.test.ts`, `.spec.ts` extensions

## When to Trust vs. Verify

### Trust the Analysis When:
- Pure utility libraries without framework magic
- Simple business logic modules
- Internal helper functions
- Well-structured monorepos with clear boundaries

### Verify Manually When:
- Code uses reflection/metaprogramming
- Framework-heavy application (React, Express, Gin, etc.)
- Plugin or extension systems
- Database ORM with complex relations
- API handlers registered dynamically
- Test files and fixtures