phantom-limb（幻肢）

Phantom Limb

"The most dangerous dependency is the one that used to exist."

What It Does

Phantom Limb detects ghost references — code that reaches for things that aren't there anymore. Not broken imports (your linter catches those). The subtle kind: environment variables nobody sets, config keys that were renamed three sprints ago, API endpoints that were deprecated but never removed from the client, file paths that point to directories that exist only on the original developer's machine.

Every codebase accumulates phantoms. They don't cause errors — they cause *mystery*. They're the reason a feature "works everywhere except production." They're the reason onboarding takes two weeks instead of two days.

Why This Exists

Static analysis catches what's wrong. Linters catch what's ugly. Phantom Limb catches what's missing — the negative space between your code and reality.

The Six Classes of Phantoms

1. Environmental Phantoms

References to environment variables, config files, or system state that no process ever sets.

// This worked when we ran Redis locally
const cache = process.env.REDIS_URL || 'redis://localhost:6379';
// Redis was replaced with Memcached 8 months ago.
// Nobody removed this. The fallback silently runs. Against nothing.

Detection method: Cross-reference every process.env, os.environ, ENV[] read against actual .env, .env.example, CI/CD configs, and deployment manifests.

2. Referential Phantoms

Code that references functions, classes, or modules that were moved, renamed, or deleted — but the reference still "works" because a shim, re-export, or fallback catches it.

# utils.py re-exports calculate_tax for "backwards compatibility"
# Nobody imports calculate_tax from the original location anymore
# But nobody removed the re-export either
# And the original calculate_tax was rewritten. The re-export points to the old version.
from legacy.tax import calculate_tax  # pragma: no cover

Detection method: Trace every import chain to its terminal definition. Flag chains longer than 2 hops. Flag anything with "legacy", "compat", "old", or "deprecated" in the path that has no deprecation deadline.

3. Temporal Phantoms

Code that depends on timing, ordering, or sequencing that was true under a previous architecture but is no longer guaranteed.

// This worked when auth was synchronous middleware
// After the async rewrite, user might not be populated yet
app.get('/dashboard', (req, res) => {
  const name = req.user.displayName; // Sometimes undefined. Sometimes not.
});

Detection method: Map all implicit ordering assumptions. Flag any data access that assumes a prior middleware/hook/lifecycle event has already completed without explicit await/guard.

4. Contractual Phantoms

API contracts, database schemas, or wire formats that the code expects but the other side no longer honors.

# The payments API v2 removed the 'discount_code' field
# Our code still sends it. The API silently ignores it.
# Nobody knows the discount feature has been broken for 3 months.
payload = {
    "amount": total,
    "discount_code": user.discount,  # Phantom. Silently ignored.
}

Detection method: Compare every outbound payload construction against the latest API schema/docs. Compare every database query against the current schema. Flag fields that are constructed but never consumed.

5. Intentional Phantoms

Comments, TODOs, and documentation that describe behavior the code no longer exhibits. The specification has become a ghost story.

/**
 * Retries up to 3 times with exponential backoff.
 * Falls back to cache on failure.
 */
// Retry logic was removed in PR #847. Cache fallback was never implemented.
public Response fetchData() {
    return client.get(url); // One shot. No retry. No fallback.
}

Detection method: Parse doc comments and compare claimed behavior against actual implementation. Flag docstrings that mention patterns (retry, cache, fallback, queue, batch) that don't appear in the method body.

6. Identity Phantoms

Variables, functions, or modules whose names describe something they no longer do. The name is a phantom of their original purpose.

// This was a temporary cache. Three years ago.
func getTempCache() *PermanentStore {
    return &PermanentStore{ttl: 0} // TTL of zero = lives forever
}

Detection method: Semantic analysis of identifier names vs. their actual behavior. Flag contradictions between name semantics and implementation semantics (e.g., temp + no expiry, async + synchronous execution, safe + no error handling).

How It Works

Phase 1: EXCAVATION
├── Scan all source files for external references
├── Build a reference graph (what reaches for what)
├── Map all environment reads, config lookups, API calls
└── Catalog all import chains and their terminal definitions

Phase 2: REALITY CHECK
├── Cross-reference against actual environment state
├── Compare API contracts against current schemas
├── Trace import chains to detect phantom re-exports
└── Compare documentation claims against implementation

Phase 3: PHANTOM CLASSIFICATION
├── Classify each phantom by type (1-6 above)
├── Score severity (silent failure vs. loud failure vs. latent)
├── Estimate blast radius (how many codepaths are affected)
└── Calculate haunting duration (how long has this been phantom)

Phase 4: EXORCISM REPORT
├── Prioritized list of phantoms by severity × blast radius
├── For each phantom: what it references, what's actually there, and what to do
├── Quick-fix suggestions for each class
└── Dependency reality map (what your code thinks exists vs. what does)

Severity Scoring

Output Format

╔══════════════════════════════════════════════════════════════╗
║                    PHANTOM LIMB SCAN                        ║
║                    12 phantoms detected                     ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  CRITICAL (2)                                                ║
║  ├── [Contractual] POST /api/payments sends 'discount_code'  ║
║  │   → Field removed in API v2 (2024-11-03)                 ║
║  │   → 3 months of silent discount failures                  ║
║  │   → Fix: Remove field from payload builder                ║
║  │                                                           ║
║  ├── [Environmental] REDIS_URL referenced in 4 files         ║
║  │   → No process sets this variable                         ║
║  │   → Fallback to localhost:6379 connects to nothing        ║
║  │   → Fix: Remove Redis references, use Memcached client    ║
║  │                                                           ║
║  HIGH (3)                                                    ║
║  ├── [Temporal] req.user accessed before auth middleware      ║
║  │   ...                                                     ║
╚══════════════════════════════════════════════════════════════╝

Integration

Invoke when:

• Onboarding a new developer (show them where the ghosts live)
• After a major refactor (find what the refactor left behind)
• Before a production deploy (catch phantoms before users do)
• During architecture review (map the gap between intent and reality)

Why It Matters

Every codebase has a phantom architecture — the system it *thinks* it is, layered on top of the system it *actually* is. The gap between these two architectures is where bugs hide, onboarding stalls, and technical debt compounds silently.

Phantom Limb doesn't find bugs. It finds the *conditions* that make bugs inevitable.

Zero external dependencies. Zero API calls. Pure structural analysis.