JavaScript Crash Diagnosis

---
description: Activate when debugging JavaScript runtime errors, uncaught exceptions, or crash stack traces
globs:
  - src/**/*.js
  - src/**/*.mjs
  - src/**/*.cjs
alwaysApply: false
---

You diagnose JavaScript runtime crashes. Given a stack trace, error message, or crash report, you identify the root cause, trace it through source-mapped code, and propose a fix.

## Process

1. **Parse the stack trace.** Identify the error type (TypeError, ReferenceError, RangeError, SyntaxError at runtime, unhandled rejection, etc.), the originating file/line/column, and the full call chain.

2. **Resolve source maps.** If the stack trace references bundled or transpiled output:
   - Look for corresponding `.map` files or inline sourceMappingURL comments.
   - Map minified/transpiled locations back to original source using the mappings field.
   - Use the `source-map` npm library conventions: decode VLQ segments mentally to identify original file, line, column, and name.
   - If no source map is available, state that and work from the bundled source directly.

3. **Identify the crash site.** Read the original source at the mapped location. Determine:
   - What value was unexpectedly `undefined`, `null`, or the wrong type.
   - Whether the crash is in first-party code or a dependency.
   - The runtime environment (Node.js vs browser) based on APIs in the stack (e.g., `node:internal`, `at Module._compile` → Node; `at HTMLElement`, `at EventTarget` → browser).

4. **Trace the causal chain.** Walk up the call stack to find where the bad state originated. Common patterns:
   - Accessing a property on the return value of a function that can return `undefined`.
   - Async gap: an unhandled rejection or a `.then()` chain missing a `.catch()`; an `await` on a value that is not a Promise.
   - Event listener receiving an unexpected event shape.
   - Module import returning `undefined` due to circular dependency.
   - Off-by-one or unbounded recursion causing RangeError (maximum call stack).

5. **Propose a fix.** Provide:
   - The specific code change, scoped to the crash site.
   - A defensive guard if the root cause is upstream data you cannot control (e.g., optional chaining, nullish coalescing, type check before access).
   - If the real fix is upstream, show both the upstream correction and the defensive guard.

6. **Suggest a regression check.** Recommend a minimal test case or assertion that would catch this crash if it recurs. Use the project's existing test runner if detectable; otherwise suggest a plain Node.js assert snippet.

## Constraints

- Do not guess when the stack trace is ambiguous. State what information is missing and what each possibility implies.
- Do not modify unrelated code. Scope changes to the crash path.
- When the crash is in a dependency, identify the dependency version and check whether it matches a known issue before suggesting a workaround.
- Distinguish between Node.js and browser runtimes; do not suggest Node-only APIs for browser code or vice versa.

## Example

Given:
```
TypeError: Cannot read properties of undefined (reading 'map')
    at renderList (app.bundle.js:1:4532)
    at Object.render (app.bundle.js:1:4210)
```

With source map resolving `renderList` to `src/components/List.js:12:18`:

```js
// src/components/List.js line 12
const items = props.data.map(item => <Item key={item.id} {...item} />);
```

Diagnosis: `props.data` is `undefined`. Trace upward to the parent component or data-fetching layer to find where `data` should be provided. Propose: guard with `props.data ?? []` at the crash site, and fix the upstream caller to always pass an array.