@sentry/warden 0.24.1 → 0.26.0

package/src/builtin-skills/code-review/references/javascript-typescript.md

@@ -0,0 +1,73 @@
+# JavaScript And TypeScript Bug Review Notes
+
+Use this when reviewing JavaScript, TypeScript, Node, React, Next.js, or browser code. These notes refine the core `code-review` skill; they do not add style, architecture, security, or performance-only scope.
+
+## Runtime Boundaries
+
+- TypeScript types disappear at runtime. Treat JSON, form data, URL params, cookies, local storage, external API responses, database rows, env vars, and message payloads as untrusted shape until parsed or validated.
+- `as`, `!`, `any`, unchecked indexed access, and broad generics are leads, not findings. Report only when a reachable runtime value can violate the assumption.
+- Generated types, Zod schemas, tRPC routers, OpenAPI clients, GraphQL fragments, ORM models, and serializer tests can prove the intended contract. Read them before reporting a mismatch.
+- React and Next.js can split server and client execution. Verify where the code actually runs before claiming a browser, server, hydration, or serialization bug.
+
+## High-Signal Patterns
+
+| Pattern | Bug Shape | Safer Shape |
+|---------|-----------|-------------|
+| Falsey fallback | `value || defaultValue` treats `0`, `false`, or `""` as absent when those are valid values. | Use `??` or explicit presence checks. |
+| Dropped async work | `forEach(async ...)`, `items.map(async ...)` without `await Promise.all`, missing `return` in promise chains, or fire-and-forget work inside request/CLI paths. | Await the work, return the promise, or intentionally detach with error handling. |
+| Swallowed async errors | `void fn()`, unhandled promise callbacks, or catch blocks convert failed writes to success responses. | Await and propagate errors, or surface partial failure explicitly. |
+| State mutation | In-place `sort`, `reverse`, `splice`, object mutation, cache mutation, or prop mutation changes data later reused by callers. | Clone before mutation or keep mutation local to newly created values. |
+| Stale React state | Closures, effects, memoization, or callbacks use stale props/state and produce wrong UI or wrong submitted data. | Use correct dependencies, functional updates, refs for mutable external state, or derive state at render time. |
+| Schema drift | Runtime schema, inferred type, serialized payload, or API response changed without matching callers. | Update schema and every consumer, or keep backward-compatible fields. |
+| Pagination and ordering | Filtering after slicing, unstable sort keys, cursor fields that are not unique, or changed default order skips or duplicates records. | Filter before paging, add deterministic tie-breakers, and preserve cursor contracts. |
+| Date and precision | Date-only strings, local timezone parsing, DST boundaries, milliseconds vs seconds, integer rounding, or currency precision changes produce wrong values. | Normalize units and timezones at boundaries and keep decimal math explicit. |
+| Import/export breakage | A value import points at a type-only export, a default import targets named exports, or an ESM/CJS boundary no longer matches runtime output. | Use `export type` for types and value exports for runtime symbols, matching the package format. |
+| Cleanup and cancellation | Abort handlers, timers, subscriptions, streams, temp files, or locks are not cleaned up on error or unmount. | Use finally blocks, cleanup functions, abort propagation, and scoped resource ownership. |
+
+## False-Positive Controls
+
+- `Promise.all`, `Promise.allSettled`, returned promise chains, and framework-managed async handlers can prove async work is awaited.
+- `value ?? defaultValue` preserves `0`, `false`, and `""`; do not report falsey collapse there.
+- In-place mutation is safe when the array or object was created locally and is not reused by callers.
+- Optional chaining is not a bug when downstream code intentionally handles absence.
+- Type assertions are safe when the value comes from a checked schema, trusted factory, or exhaustive discriminated union.
+- React hook dependency warnings are not findings by themselves. Show the stale value and user-visible wrong behavior.
+- TypeScript compile errors are findings only when the changed code deterministically breaks the build or emitted runtime behavior.
+
+## Minimal Examples
+
+**Report: falsey value regression**
+
+```ts
+const limit = Number(searchParams.get("limit")) || 50;
+```
+
+If `limit=0` is a documented way to disable fetching, this turns a valid value into `50`.
+
+**Report: dropped async writes**
+
+```ts
+users.forEach(async (user) => {
+  await sendInvite(user.id);
+});
+return { sent: users.length };
+```
+
+The function reports success before invites finish, and failures are detached from the response.
+
+**Report: schema drift**
+
+```ts
+const UserResponse = z.object({ id: z.string(), name: z.string() });
+return { id: user.id, displayName: user.name };
+```
+
+The returned payload no longer satisfies the runtime schema or callers expecting `name`.
+
+**Do not report: awaited async map**
+
+```ts
+await Promise.all(users.map((user) => sendInvite(user.id)));
+```
+
+The promises are joined and errors propagate through the awaited call.

package/src/builtin-skills/code-review/references/python.md

@@ -0,0 +1,77 @@
+# Python Bug Review Notes
+
+Use this when reviewing Python, Django, Flask, FastAPI, Celery, or Python service code. These notes refine the core `code-review` skill; they do not add style, architecture, security, or performance-only scope.
+
+## Runtime Boundaries
+
+- Type hints are not runtime validation. Treat request data, query params, env vars, external API responses, database rows, task payloads, and deserialized files as shape-unknown until validated.
+- Pydantic models, DRF serializers, dataclasses, typed dicts, Django model fields, migrations, and existing tests can prove the intended contract. Read them before reporting a mismatch.
+- Decorators and framework hooks can change call order, transaction scope, auth context, and exception behavior. Verify the effective path.
+- Background tasks and management commands often run outside request transactions and sessions. Check idempotency, tenant/account context, and retry behavior before reporting.
+
+## High-Signal Patterns
+
+| Pattern | Bug Shape | Safer Shape |
+|---------|-----------|-------------|
+| Mutable defaults | Function, dataclass, or model defaults reuse lists, dicts, sets, or objects across calls or instances. | Use `None` plus initialization, `default_factory`, or framework-specific callable defaults. |
+| Falsey fallback | `value or default` treats `0`, `False`, or `""` as absent when those are valid values. | Check `is None`, missing keys, or explicit sentinel values. |
+| Missing `None` handling | `.first()`, `.get()`, optional config, env values, cache reads, or external responses are dereferenced without proving presence. | Add explicit absence handling or enforce presence at the boundary. |
+| Swallowed errors | Broad `except` returns success, empty data, or partial defaults that callers treat as complete. | Propagate failure, return explicit partial state, or compensate rolled-back work. |
+| Transaction gaps | Multiple writes, task enqueues, cache updates, or file operations can partially succeed when a later step fails. | Use transactions, `on_commit`, idempotency keys, or compensation. |
+| Async mismatch | Coroutine is not awaited, blocking I/O runs in an async endpoint, or async context managers are entered incorrectly. | Await coroutines, use async clients, and keep blocking work out of event-loop paths. |
+| Iterator exhaustion | Generators, queryset iterators, request streams, or file objects are consumed once and then reused as if still populated. | Materialize intentionally or pass a fresh iterator/stream. |
+| Timezone and precision | Naive and aware datetimes are mixed, date boundaries use server local time, or decimal money is converted to float. | Normalize timezone and use `Decimal` or integer minor units for money. |
+| Query and migration drift | Renamed fields, changed defaults, non-null constraints, data migrations, or backfills miss existing rows or write wrong records. | Include backward-compatible migrations and scoped update filters. |
+| Task retry side effects | Celery or queue retries duplicate emails, charges, state transitions, or external calls. | Make side effects idempotent or persist completion before retryable boundaries. |
+
+## False-Positive Controls
+
+- Django ORM, SQLAlchemy, and Pydantic can enforce contracts. Verify the exact model, serializer, or schema before reporting.
+- `get_or_create`, `update_or_create`, database constraints, and transactions can mitigate duplicate or partial-write paths.
+- A broad `except` is not a finding if the caller receives explicit failure state and no partial success is claimed.
+- Mutable values are safe when created inside the function or supplied by a documented immutable factory.
+- QuerySet laziness is not a bug by itself. Show the changed evaluation order that produces wrong data.
+- Type-checker-only issues are findings only when they deterministically break runtime behavior, packaging, or CI.
+
+## Minimal Examples
+
+**Report: mutable default**
+
+```python
+def collect_errors(error, bucket=[]):
+    bucket.append(error)
+    return bucket
+```
+
+Every call shares the same list, so unrelated requests can see stale errors.
+
+**Report: swallowed partial failure**
+
+```python
+try:
+    charge_customer(invoice)
+    mark_paid(invoice)
+except Exception:
+    return {"ok": True}
+```
+
+The caller receives success even if charging or persistence failed.
+
+**Report: missing absence handling**
+
+```python
+profile = Profile.objects.filter(user_id=user_id).first()
+return profile.timezone
+```
+
+If profiles are optional or not yet created, this crashes instead of following the expected fallback.
+
+**Do not report: dataclass default factory**
+
+```python
+@dataclass
+class Batch:
+    items: list[str] = field(default_factory=list)
+```
+
+Each instance receives a fresh list.