Approachability Audit

• Real parse boundaries at JSON, file, or network edges
• Runtime validation that protects unsafe input
• Shared contracts that genuinely belong in one place
• Repetition that is cheaper than an extra abstraction

Review Method

1. Start with the entrypoint a caller uses first.
2. Trace the minimum path needed to understand the behavior.
3. Count the hops:
   • if understanding one field or behavior requires jumping across multiple files, ask whether that indirection earns its keep
4. Mark each abstraction as one of:
   • earns its keep
   • probably inlineable
   • wrong ownership boundary
   • misleading name
   • type-system workaround
5. Prefer fixes that:
   • move code to the right owner
   • rename things honestly
   • collapse fake layers
   • replace cleverness with one explicit boundary

Output Shape

When reporting findings, prioritize:

1. The one or two biggest readability or ownership smells
2. Why a new TypeScript developer would stumble there
3. The smallest fix that improves trust in the code

When editing code:

• keep commits surgical
• add or improve JSDoc on public boundaries
• do not add a new abstraction unless it reduces total cognitive load
• prefer explicit names like *Bridge, *Contract, *Parser, *Factory, *State

Heuristics

Good smell

export type SessionContract = { ... };

Portable type, honest name, obvious job.

Bad smell

export type AppAuth = {
  options: { plugins: [...] }
};

If this is not the real auth type, do not name it like it is.

Good workaround

export type CustomSessionClientBridge = { ... };

If a library forces a type trick, keep it local and name it as a bridge.

Success Criteria

The code should leave a new teammate thinking:

• "I know which file owns this concept."
• "I know which type is a real contract and which one is just library glue."
• "I don't have to reverse-engineer the architecture from naming accidents."