prr-kit 1.1.2 → 1.2.0

package/src/prr/data/stacks/cpp.md

@@ -0,0 +1,57 @@
+# C++ — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.cpp` · `*.cc` · `*.cxx` · `*.hpp` · `*.h` with `#include <` · `namespace` · `std::` · `CMakeLists.txt` · `Makefile`
+
+---
+
+## Security
+
+- **[CRITICAL]** `strcpy`, `sprintf`, `gets`, `strcat` with user-controlled input → buffer overflow. Use `strncpy`, `snprintf`, `fgets`, `strncat` with explicit size limits, or C++ `std::string`.
+- **[CRITICAL]** `system(userInput)` → command injection. Avoid `system()`; use `exec*()` family with sanitized argv array.
+- **[HIGH]** Integer overflow in buffer size calculation (e.g., `malloc(count * sizeof(T))`) → heap overflow if multiplication wraps. Use checked arithmetic or `std::vector`.
+- **[HIGH]** `printf(userInput)` — untrusted string used as format specifier → format string attack. Always use `printf("%s", userInput)`.
+- **[MEDIUM]** Reading from uninitialized memory → undefined behavior, potential info leak. Initialize all variables at declaration.
+
+---
+
+## Performance
+
+- **[HIGH]** Large object passed by value to function → unnecessary copy. Use `const T&` or `T&&` (move semantics).
+- **[HIGH]** `new` / `delete` in tight loop → heap fragmentation and allocator overhead. Use stack allocation, `std::vector` with `reserve()`, or a pool allocator.
+- **[HIGH]** Virtual function calls in performance-critical inner loop → vtable dispatch per call. Consider templates (CRTP) or `final` to enable devirtualization.
+- **[MEDIUM]** `std::map` / `std::set` where `std::unordered_map` / `std::unordered_set` suffices → O(log n) vs O(1) average lookup.
+- **[MEDIUM]** Missing `std::move` when returning named local variable (before NRVO applies) → unnecessary copy.
+- **[LOW]** `std::endl` in output loop → flushes buffer every iteration. Use `'\n'` unless flush is explicitly needed.
+
+---
+
+## Architecture
+
+- **[CRITICAL]** Raw owning pointer without RAII wrapper → manual `delete` easily missed, double-free, or leak. Use `std::unique_ptr` for exclusive ownership, `std::shared_ptr` for shared.
+- **[HIGH]** Memory leak: `new` allocated object not `delete`d on all code paths (including exceptions) → use smart pointers or stack allocation.
+- **[HIGH]** Use-after-free: accessing pointer after `delete` → undefined behavior. Set pointer to `nullptr` after delete (or eliminate raw `delete` entirely).
+- **[HIGH]** Double-free: `delete` called twice on same pointer → heap corruption. Smart pointers prevent this automatically.
+- **[MEDIUM]** Global / static mutable state → thread safety issues without synchronization. Use `std::mutex` or `thread_local`.
+- **[LOW]** Deep inheritance hierarchy → prefer composition over inheritance for non-polymorphic designs.
+
+---
+
+## Code Quality
+
+- **[HIGH]** `using namespace std;` in a header file → pollutes namespace of every translation unit that includes it. Limit to `.cpp` files or use explicit `std::` prefix.
+- **[MEDIUM]** Member function that doesn't modify state not marked `const` → prevents use with `const` objects, hides intent.
+- **[MEDIUM]** Implicit conversion between signed and unsigned integers without explicit cast → subtle overflow or wrap-around bugs. Enable `-Wsign-conversion`.
+- **[MEDIUM]** Missing `override` on virtual method override → if base signature changes, override silently becomes a new function.
+- **[LOW]** Long function > 50 lines with complex control flow → decompose into smaller functions.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[CRITICAL]** Undefined behavior: signed integer overflow, null pointer dereference, out-of-bounds array access, data race → UB cannot be relied upon to "just work" even if it appears to.
+- **[HIGH]** Iterator invalidation: modifying `std::vector` / `std::map` while iterating (erase, push_back) → UB. Collect indices/iterators first or use erase-remove idiom.
+- **[HIGH]** `std::vector::operator[]` without bounds check in production code → UB on out-of-bounds. Use `.at()` during development/testing; add assertion in production.
+- **[MEDIUM]** Object slicing: assigning derived-class object to base-class by value → vtable and derived members are lost silently.
+- **[MEDIUM]** `#pragma once` vs include guards mixed in same codebase → inconsistency. Pick one convention.
+- **[LOW]** Comparing floating-point values with `==` → imprecise. Use epsilon comparison: `std::abs(a - b) < epsilon`.

package/src/prr/data/stacks/csharp.md

@@ -0,0 +1,95 @@
+# C# / .NET — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.cs` files · `*.csproj` · `*.sln` · `using System` · `namespace` · `dotnet` CLI · `appsettings.json` · ASP.NET Core · Entity Framework
+
+---
+
+## Security
+
+- **[CRITICAL]** SQL built with string interpolation: `$"SELECT * WHERE id = {id}"` → SQL injection. Use parameterized queries (`SqlParameter`) or EF Core.
+- **[CRITICAL]** `Process.Start(new ProcessStartInfo { UseShellExecute = true, FileName = input })` with user input → command injection. Use argument arrays, not shell strings.
+- **[CRITICAL]** `BinaryFormatter.Deserialize()` on untrusted data → arbitrary code execution (CVE-class). Use `System.Text.Json` or `XmlSerializer` with safe settings.
+- **[HIGH]** Missing `[ValidateAntiForgeryToken]` on ASP.NET Core POST/PUT/DELETE → CSRF.
+- **[HIGH]** Hardcoded connection strings / API keys in `appsettings.json` committed to VCS → use `dotnet user-secrets`, Azure Key Vault, or environment variables.
+- **[HIGH]** `Path.Combine(baseDir, userInput)` without `Path.GetFullPath()` + prefix check → path traversal.
+- **[HIGH]** `JsonConvert.DeserializeObject<T>(input)` with `TypeNameHandling.All` → remote code execution via `$type`.
+- **[HIGH]** Sensitive data logged via `_logger.LogInformation()` with string interpolation → log injection.
+- **[HIGH]** `RNGCryptoServiceProvider` deprecated → use `RandomNumberGenerator.Fill()` (static, .NET 6+).
+- **[MEDIUM]** `Math.Random` used for security purposes → use `RandomNumberGenerator` from `System.Security.Cryptography`.
+- **[MEDIUM]** CORS configured too permissively (`AllowAnyOrigin + AllowCredentials`) → CORS misconfiguration.
+- **[MEDIUM]** `HttpContext.Request.Headers["X-Forwarded-For"]` trusted without proxy validation → IP spoofing.
+- **[MEDIUM]** Passwords stored as `string` → immutable, lingers in memory. Use `SecureString` or clear char arrays.
+- **[LOW]** Exception details returned in API response in production → configure `app.UseExceptionHandler` properly.
+
+---
+
+## Performance
+
+- **[HIGH]** `async void` method (not event handler) → exceptions unobservable, swallowed silently. Use `async Task`.
+- **[HIGH]** `.Result` or `.Wait()` on Task in ASP.NET context → deadlock on synchronization context. Always `await`.
+- **[HIGH]** `string +=` in loop → O(n²). Use `StringBuilder` or `string.Join`.
+- **[HIGH]** `await` inside loop instead of batching with `Task.WhenAll()` → sequential async = unnecessary latency.
+- **[HIGH]** Entity Framework `Include()` loading entire related collection when only count or single field needed → select projection.
+- **[HIGH]** Synchronous EF Core calls (`.ToList()` without `Async`) in ASP.NET Core → blocking thread pool thread.
+- **[HIGH]** Missing `AsNoTracking()` on read-only EF Core queries → change tracker overhead.
+- **[MEDIUM]** `.ToList()` called on `IQueryable` before further LINQ operations → materializes entire result prematurely.
+- **[MEDIUM]** Missing `ConfigureAwait(false)` in library code → captures unnecessary sync context.
+- **[MEDIUM]** `IEnumerable<T>` iterated multiple times → if `IQueryable`, triggers multiple DB calls. Materialize once.
+- **[MEDIUM]** Large object allocation in hot path without pooling → GC pressure. Use `ArrayPool<T>` or `MemoryPool<T>`.
+- **[MEDIUM]** Not using `Span<T>` / `Memory<T>` for buffer operations → unnecessary heap allocations.
+- **[MEDIUM]** LINQ `GroupBy` on large in-memory collections → O(n) memory → push to DB if possible.
+- **[LOW]** Not using `HttpClient` with `IHttpClientFactory` → socket exhaustion with `new HttpClient()`.
+- **[LOW]** `Task.Run` wrapping CPU-bound work then awaiting → thread pool overhead for short tasks.
+
+---
+
+## Architecture
+
+- **[HIGH]** `static` mutable fields in ASP.NET Core services → shared across requests, race conditions without sync.
+- **[HIGH]** `IDisposable` object created without `using` or `await using` → resource leak (DB connections, streams).
+- **[HIGH]** Service registered with wrong DI lifetime: `Scoped` injected into `Singleton` → captive dependency.
+- **[HIGH]** `DbContext` used as singleton → EF Core `DbContext` is not thread-safe, designed for scoped lifetime.
+- **[HIGH]** Business logic in ASP.NET Core controllers → move to service/domain layer.
+- **[HIGH]** Not using Repository/Unit of Work pattern with EF Core → testability and coupling issues.
+- **[MEDIUM]** Catching `Exception` too broadly → masks unrelated bugs. Catch specific exceptions.
+- **[MEDIUM]** `HttpClient` instantiated per request → socket exhaustion. Use `IHttpClientFactory`.
+- **[MEDIUM]** Not using `CancellationToken` propagation in async chain → operations can't be cancelled.
+- **[MEDIUM]** God class with >500 lines → decompose by responsibility.
+- **[MEDIUM]** Domain model leaking persistence concerns (EF navigation properties in API contracts).
+- **[LOW]** Not using `record` types (C# 9+) for DTOs and value objects → verbose boilerplate equality.
+- **[LOW]** Not using `sealed` on classes not designed for inheritance → unintended extension.
+
+---
+
+## Code Quality
+
+- **[HIGH]** Nullable reference types disabled (`<Nullable>disable</Nullable>`) → NullReferenceException not caught at compile time. Enable and fix warnings.
+- **[HIGH]** `throw ex` instead of `throw` in catch block → resets stack trace, hides origin.
+- **[HIGH]** `int.Parse(input)` without `TryParse` → `FormatException` on invalid input crashes request.
+- **[HIGH]** Not using `pattern matching` for type checks → verbose `is`/`as` + null check.
+- **[MEDIUM]** `var` used where type not obvious from RHS → readability suffers.
+- **[MEDIUM]** Missing cancellation token propagation in async call chain.
+- **[MEDIUM]** Magic strings for configuration keys instead of typed options with `IOptions<T>`.
+- **[MEDIUM]** `?.` null conditional chaining producing `null` result silently used without null check.
+- **[MEDIUM]** Not using C# 10+ features (`record struct`, global using, file-scoped namespace) in modern projects.
+- **[MEDIUM]** Event subscription not unsubscribed → memory leak via event handler reference.
+- **[LOW]** Public method without XML doc comment on public API.
+- **[LOW]** Not using `nameof()` for property names in validation/logging → typo-prone string literals.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `DateTime.Now` for storage/cross-system → timezone-dependent. Use `DateTime.UtcNow` or `DateTimeOffset.UtcNow`.
+- **[HIGH]** `LINQ` deferred execution not understood → query executed multiple times or after `DbContext` disposed.
+- **[HIGH]** EF Core `SaveChangesAsync()` not called after mutations → changes not persisted silently.
+- **[HIGH]** `lock(this)` or `lock(typeof(Foo))` → public lock objects can be acquired externally → deadlock.
+- **[HIGH]** `Task.WhenAll()` not awaited → exceptions swallowed.
+- **[MEDIUM]** Struct implementing `IDisposable` boxed via interface → `Dispose` called on copy.
+- **[MEDIUM]** Enum default value (0) not explicitly named → uninitialized enum has valid meaningless value.
+- **[MEDIUM]** `string.Compare` for equality → use `string.Equals` with `StringComparison`.
+- **[MEDIUM]** EF Core lazy loading enabled without understanding → N+1 queries via navigation property access.
+- **[MEDIUM]** `ConcurrentDictionary.GetOrAdd` with factory that has side effects → factory may run multiple times.
+- **[LOW]** `StringBuilder.Append()` returning `this` for chaining not used → verbose multi-line appends.
+- **[LOW]** `Encoding.UTF8.GetString` on bytes from wrong encoding → mojibake.

package/src/prr/data/stacks/css.md

@@ -0,0 +1,55 @@
+# CSS / SCSS / SASS — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.css`, `*.scss`, `*.sass`, `*.less`, `*.styl` files
+
+---
+
+## Security
+
+- **[HIGH]** `url()` with user-controlled value → CSS injection loading external resources. Never interpolate user data into CSS.
+- **[MEDIUM]** `expression()` (IE legacy) in CSS → executes JavaScript. Never use.
+- **[MEDIUM]** Missing `Content-Security-Policy: style-src 'self'` allowing inline styles that could be injected.
+
+---
+
+## Performance
+
+- **[HIGH]** Universal selector `*` with expensive properties (`box-shadow`, `transform`) → applied to every element, layout thrash.
+- **[HIGH]** `@import` in CSS (not SCSS) → blocking serial HTTP requests. Use `<link>` or bundler imports.
+- **[HIGH]** Triggering layout thrash — reading layout properties (`offsetWidth`, `getBoundingClientRect`) then writing in same frame (JS + CSS combo). Use `transform` for animations.
+- **[MEDIUM]** Overly specific selectors (`div > ul > li > a.link`) → slow browser matching, hard to override.
+- **[MEDIUM]** `position: fixed` elements on scroll-heavy pages without `will-change: transform` → repaints entire page.
+- **[MEDIUM]** Animating `width`/`height`/`top`/`left` → triggers layout recalculation. Use `transform: translate()` / `scale()` instead.
+- **[LOW]** Large unused CSS from third-party libraries not purged → bundle bloat.
+
+---
+
+## Architecture
+
+- **[HIGH]** Deeply nested SCSS selectors (>4 levels) → high specificity, hard to override, fragile.
+- **[MEDIUM]** Color/spacing values duplicated as magic numbers instead of CSS custom properties / SCSS variables.
+- **[MEDIUM]** `!important` overuse → specificity war, maintainability nightmare.
+- **[MEDIUM]** Class names not following a convention (BEM, utility-first) → inconsistent, hard to predict.
+- **[LOW]** Vendor prefixes added manually instead of using Autoprefixer → out-of-date, missing prefixes.
+- **[LOW]** SCSS `@extend` used with placeholder selectors — can cause unexpected selector bloat.
+
+---
+
+## Accessibility
+
+- **[HIGH]** `outline: none` / `outline: 0` on focusable elements without alternative focus indicator → keyboard navigation broken (WCAG 2.4.7).
+- **[HIGH]** Text contrast below WCAG AA (4.5:1 for normal text, 3:1 for large text).
+- **[MEDIUM]** `display: none` used on content that should be accessible to screen readers → use visually-hidden pattern instead.
+- **[MEDIUM]** `pointer-events: none` on interactive elements without disabling them in HTML → keyboard still reaches them.
+- **[LOW]** `user-select: none` on body/large containers → breaks copy-paste for users.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `z-index` wars — arbitrary large values (`z-index: 9999`) without documented stacking context.
+- **[MEDIUM]** Margin collapsing not accounted for — `margin-top` on child collapses with parent without overflow/padding/border.
+- **[MEDIUM]** `height: 100%` on child without parent having explicit height → renders as 0.
+- **[MEDIUM]** Flexbox/Grid item `flex: 1` without `min-width: 0` → overflow issues with long text content.
+- **[LOW]** `calc()` with missing spaces around operators (`calc(100%-20px)`) → invalid in some browsers.

package/src/prr/data/stacks/cypress.md

@@ -0,0 +1,53 @@
+# Cypress — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `cypress`, `cy.visit(`, `cy.get(`, `cy.intercept(`, `cypress.config.*`, `describe(` in `cypress/`
+
+---
+
+## Security
+- **[HIGH]** Hardcoded test credentials in Cypress test files committed to the repository → credentials exposed in version control and CI logs. Use `Cypress.env()` with environment variables injected at CI time; store secrets in your CI secret manager.
+- **[HIGH]** `cy.request()` calling authenticated API endpoints without proper auth token setup → tests may inadvertently call real external services or bypass auth unexpectedly. Always set the auth token via `cy.session()` or `Authorization` header in `cy.request()` explicitly.
+- **[MEDIUM]** Secrets placed in `cypress.env.json` and committed to the repository → sensitive values in version control. Add `cypress.env.json` to `.gitignore` and inject values via CI environment variables only.
+- **[MEDIUM]** Test data including PII from seeded users not cleaned up after test runs → leftover PII accumulates in the staging database. Add an `afterEach` or `after` hook that deletes or resets test data via a `cy.task()` DB call.
+- **[LOW]** `chromeWebSecurity: false` set in `cypress.config` to allow cross-origin requests → disables browser same-origin protections, letting cross-origin attacks go undetected. Remove `chromeWebSecurity: false` and use `cy.origin()` for legitimate cross-origin testing.
+
+---
+
+## Performance
+- **[HIGH]** `cy.wait(5000)` hard-coded time waits instead of waiting on network requests → tests are slow and flaky; the wait may not be enough on slow CI. Replace with `cy.intercept()` aliases and `cy.wait('@aliasName')` to wait for the actual request.
+- **[HIGH]** `cy.session()` not used for authentication state → login UI flow executed on every test, adding seconds per test. Cache login state with `cy.session('user', loginFn)` so auth is established once per session.
+- **[HIGH]** `cy.visit()` called for every test when tests could share a single page load → full navigation and app initialization overhead per test. Visit once in `before()` and reset state between tests without full reloads where possible.
+- **[MEDIUM]** `cy.get('.selector')` traversing the entire DOM when a scoped query is possible → selector resolution slows on large DOMs. Chain `.within()` to scope: `cy.get('#parent').within(() => { cy.get('button') })`.
+- **[MEDIUM]** `cy.task()` not used for database seeding → seeding done via UI or `cy.request()`, which depends on the app being fully functional. Use `cy.task('db:seed', data)` to insert directly into the DB via Node.js.
+- **[LOW]** Screenshots and videos enabled in CI without artifact retention policy → disk fills up and artifact uploads slow pipelines. Set `video: false` in CI and enable `screenshotOnRunFailure: true` only.
+
+---
+
+## Architecture
+- **[HIGH]** Selectors based on CSS classes or visible text → tests break whenever the UI is restyled or copy changes. Use `data-cy` attributes: `cy.get('[data-cy="submit-button"]')`.
+- **[HIGH]** Repeated auth, navigation, or interaction logic not extracted to custom commands → duplication across tests; one UI change breaks dozens. Extract sequences to `Cypress.Commands.add('login', ...)`.
+- **[MEDIUM]** Tests not organized by feature or page → test files become hundreds of lines, slow to scan. Organize into subdirectories: `cypress/e2e/auth/login.cy.ts`, `cypress/e2e/dashboard/overview.cy.ts`.
+- **[MEDIUM]** Cypress commands chained after native Promises without returning the Cypress chain → commands run out of order. Always return the Cypress chain from inside `.then()` callbacks; avoid mixing native Promises with Cypress commands.
+- **[MEDIUM]** No page object pattern for complex multi-step user flows → test code directly manipulates selectors; refactoring requires editing every test. Create helper functions or custom commands that encapsulate multi-step flows.
+- **[LOW]** Cypress configuration not split into base config plus environment-specific overrides → CI and local configs are identical; developers must manually change settings. Use `defineConfig` with environment-specific override files.
+
+---
+
+## Code Quality
+- **[HIGH]** `cy.get(sel).then(el => cy.get(sel2))` anti-pattern instead of `.within()` → creates unnecessary nested chains that are hard to read. Use `cy.get('#container').within(() => { cy.get('button').click() })`.
+- **[HIGH]** Assertions missing from tests → test passes even when the feature is broken because no assertion checks the expected state. Every test must end with at least one `.should()` assertion verifying the intended UI state.
+- **[MEDIUM]** `.should('be.visible')` not asserted before interacting with an element → Cypress may try to click a hidden or detached element, causing flaky failures. Use `cy.get(sel).should('be.visible').click()`.
+- **[MEDIUM]** Test data hardcoded inline instead of using fixtures → same data duplicated across tests; changing it requires editing multiple files. Extract to `cypress/fixtures/` JSON files and load with `cy.fixture()`.
+- **[MEDIUM]** No TypeScript types for custom commands in `cypress/support/index.d.ts` → custom commands typed as `any`; autocomplete absent. Extend the `Chainable` interface with type declarations for every custom command.
+- **[LOW]** No Cypress lint rules (eslint-plugin-cypress) configured → Cypress-specific anti-patterns not caught automatically. Add `eslint-plugin-cypress` with the recommended rule set to the ESLint config.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** `cy.get()` matching multiple elements when only one is expected → Cypress acts on the first match silently; tests pass against the wrong element. Assert `.should('have.length', 1)` or use a more specific selector.
+- **[HIGH]** Async code (Promises, async/await) in `before()` or `beforeEach()` without returning the Cypress chain → setup completes after tests begin; state is missing when tests run. Return the Cypress chain from setup hooks or use `cy.wrap(promise)`.
+- **[MEDIUM]** `cy.intercept()` alias defined after `cy.visit()` → network request fires before intercept is registered; alias never resolves. Always define `cy.intercept()` aliases before `cy.visit()` or the action that triggers the request.
+- **[MEDIUM]** `cy.contains()` matching hidden text nodes (e.g., inside a tooltip or offscreen element) → test passes but the visible text the user sees is different. Add `.should('be.visible')` after `cy.contains()`.
+- **[MEDIUM]** "detached from DOM" error when an element re-renders between `cy.get()` and the subsequent action → element reference becomes stale after React or Vue re-render. Re-query the element inside `.then()` after re-render-triggering actions.
+- **[LOW]** `cy.clock()` and `cy.tick()` not restored after tests that manipulate timers → fake clock bleeds into subsequent tests causing unexpected timing behavior. Call `cy.clock().then(c => c.restore())` in `afterEach`.

package/src/prr/data/stacks/d3.md

@@ -0,0 +1,53 @@
+# D3.js — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `from 'd3'`, `import * as d3`, `d3.select`, `d3.scaleLinear`, `d3.axisBottom`, `.enter().append`
+
+---
+
+## Security
+- **[CRITICAL]** `.html(userContent)` called on a D3 selection with unencoded user data → XSS; D3 sets `innerHTML` directly. Use `.text(userContent)` for text content, or sanitize HTML with DOMPurify before passing to `.html()`.
+- **[HIGH]** `d3.json(userUrl)` or `d3.csv(userUrl)` called with a URL derived from user input without validation → SSRF or loading of malicious data. Validate and allowlist URLs before passing to D3 fetch helpers.
+- **[HIGH]** Dynamic SVG `<foreignObject>` elements populated with user-controlled HTML → XSS vector that bypasses SVG's normal escaping. Sanitize all HTML content placed inside `<foreignObject>` elements.
+- **[MEDIUM]** Axis tick labels or tooltip content bound directly to raw user data values → unencoded strings rendered as SVG `text` content. D3 `.text()` is safe, but `.html()` or `innerHTML` on tooltip containers is not; sanitize before inserting.
+- **[LOW]** D3 charts embedding data from external sources in SVG `<title>` or `<desc>` elements without encoding → minor content injection risk. Encode all external data used in SVG metadata.
+
+---
+
+## Performance
+- **[HIGH]** Not using `selection.join()` (D3 v5+) for enter/update/exit pattern → manual three-phase code is verbose, error-prone, and slower to execute. Replace `.selectAll().data().enter().append()` chains with `.join()`.
+- **[HIGH]** Rebuilding the entire chart (re-running enter/append on all elements) on every data update instead of updating existing elements → O(n) DOM operations on each change. Use the update selection to modify existing elements; only enter new ones and exit removed ones.
+- **[HIGH]** No transition throttling or debouncing on resize-driven re-renders → chart redraws on every pixel of window resize. Debounce resize handlers with at least 100ms delay.
+- **[MEDIUM]** Rendering thousands of SVG `<circle>` or `<path>` elements for large datasets → SVG DOM overhead causes frame drops. Switch to `<canvas>` rendering (D3 + Canvas API) or use `d3-tile` with WebGL for datasets above ~5,000 points.
+- **[MEDIUM]** D3 scale functions (`d3.scaleLinear`, `d3.scaleBand`) recreated on every render without memoization in React → recalculation overhead and new references causing child re-renders. Memoize scales with `useMemo` keyed on data and dimensions.
+- **[LOW]** `d3.csv` or `d3.json` called inside a render or effect without caching result → network request repeated on every render cycle. Load data once, store in state or ref, pass as prop.
+
+---
+
+## Architecture
+- **[HIGH]** D3 DOM manipulation (`.append()`, `.attr()`, `.style()`) running alongside React rendering on the same elements → virtual DOM and actual DOM desync causing lost updates and React warnings. Let React own the DOM; use D3 only for math (scales, axes, path generators) and render SVG elements via JSX.
+- **[MEDIUM]** Chart dimensions hardcoded as magic numbers instead of measured from the container → chart overflows or underutilizes space on different screen sizes. Use `ResizeObserver` on the container element and pass measured `width`/`height` to the chart.
+- **[MEDIUM]** Data transformation (filtering, aggregation, normalization) mixed with rendering logic in the same function → hard to test and reuse. Separate data pipeline (pure functions) from rendering (D3/SVG operations).
+- **[MEDIUM]** Axes, legends, and tooltips tightly coupled to chart internals → cannot reuse or test independently. Extract as separate components or factory functions receiving scales as arguments.
+- **[LOW]** Using deprecated D3 v4 or v5 API patterns (`.on('zoom')` without `d3.zoom()`, old nest API) in a v7 codebase → subtle behavioral differences. Audit imports and replace deprecated patterns with v7 equivalents.
+
+---
+
+## Code Quality
+- **[HIGH]** `d3.select<ElementType, Datum>()` called without TypeScript generics → selection typed as `Selection<BaseType, unknown, ...>`, losing all type safety on datum and element properties. Always provide element and datum type parameters.
+- **[MEDIUM]** Chart margins defined as magic numbers inline → hardcoded values repeated across multiple chart files. Extract to a named config object `const margin = { top: 20, right: 30, bottom: 40, left: 50 }`.
+- **[MEDIUM]** Transitions across charts using inconsistent durations and easing → jarring UX. Define shared transition presets and apply via `d3.transition('name')` named transitions.
+- **[MEDIUM]** Tooltip element created via `d3.select('body').append('div')` without cleanup → orphaned tooltip `<div>` elements accumulate in the DOM. Remove tooltip in component cleanup/teardown.
+- **[LOW]** Not using D3's built-in color schemes (`d3.schemeTableau10`, `d3.interpolateViridis`) → custom color arrays duplicated and inconsistent across charts. Use D3 ordinal and sequential color scales with built-in schemes.
+- **[LOW]** SVG not given explicit `viewBox` and `preserveAspectRatio` attributes → SVG does not scale correctly in flexible containers. Always set `viewBox="0 0 ${width} ${height}"` on the root SVG element.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** Data join key function omitted from `.data(dataset, d => d.id)` → D3 matches elements by index, causing wrong enter/exit assignment when data order changes. Always provide a key function that uniquely identifies each datum.
+- **[HIGH]** `d3.scaleLinear().domain([d3.min(data), d3.max(data)])` when `data` contains non-numeric or `undefined` values → domain becomes `[NaN, NaN]`, all positions render at 0. Validate and filter data before computing domain; use `d3.extent` for safety.
+- **[MEDIUM]** SVG y-axis inverted (y increases downward) not accounted for in scale range → chart renders upside down. Set scale range as `[height, 0]` for y-axis scales to flip the coordinate system.
+- **[MEDIUM]** Tooltip not hidden on `mouseleave` from chart element → tooltip stays visible indefinitely after cursor exits. Always pair `mouseover`/`mouseenter` handlers with `mouseleave` handlers that hide the tooltip.
+- **[MEDIUM]** `d3.zoom` transform applied to the wrong parent element → pan/zoom causes jumpy or offset behavior. Apply the transform to the inner `<g>` element, not the `<svg>`, and account for margin offset.
+- **[MEDIUM]** `d3.brushX` selection not cleared when data updates → stale brush extent filters new data unexpectedly. Reset brush programmatically with `brush.move(brushGroup, null)` on data change.
+- **[LOW]** `path.attr('d', lineGenerator)` called before data is bound to the selection → generator receives `undefined`, rendering an empty or broken path. Ensure data is joined before calling path generators.

package/src/prr/data/stacks/deno.md

@@ -0,0 +1,49 @@
+# Deno — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `deno.json` / `deno.jsonc` · `deno.lock` · `Deno.` namespace usage · `import_map.json` · `jsr:` / `npm:` / `https://` import specifiers · `deno run` scripts
+
+---
+
+## Security
+
+- **[CRITICAL]** Running with `--allow-all` (or `-A`) flag → defeats Deno's permission model entirely. Grant only the minimum required permissions (`--allow-net=api.example.com`, `--allow-read=./data`).
+- **[HIGH]** `--allow-run` without specifying allowed commands → grants permission to execute any process. Restrict with `--allow-run=git,node` allowlist.
+- **[HIGH]** Dynamic `import()` from a user-controlled URL or string → arbitrary code execution. Never construct import URLs from external input.
+- **[MEDIUM]** `--allow-net` without domain restriction → can connect to any host. Restrict to required domains.
+- **[MEDIUM]** `--allow-env` without variable allowlist → exposes all environment variables including secrets to the script. Use `--allow-env=SPECIFIC_VAR`.
+
+---
+
+## Performance
+
+- **[HIGH]** `Deno.readFileSync` / `Deno.writeFileSync` on large files in an async context → blocks the event loop. Use async `await Deno.readFile()` / `Deno.writeFile()`.
+- **[MEDIUM]** `for await ... of` on `Deno.readDir` without early exit → iterates entire directory. Break early when target is found.
+- **[LOW]** Not using Deno's native `Deno.serve()` (Deno 1.35+) → older `serve()` from `std/http` has more overhead. Prefer the native API for new code.
+
+---
+
+## Architecture
+
+- **[HIGH]** Node.js `require()` used without `npm:` specifier → `require` is not available in Deno by default. Use `import` with `npm:package-name` or `jsr:@scope/package`.
+- **[HIGH]** Dependencies imported from raw `https://` URLs without version pinning → non-reproducible builds; upstream URL changes silently break code. Use `jsr:` or `npm:` specifiers with versions.
+- **[MEDIUM]** `deno.lock` file not committed to version control → dependency versions not reproducible across environments. Commit the lockfile.
+- **[MEDIUM]** Permissions requested at CLI level too broadly for a library → libraries should not prescribe permissions; they should document what permissions callers must grant.
+
+---
+
+## Code Quality
+
+- **[HIGH]** `// @ts-nocheck` or `any` type used extensively → Deno enforces strict TypeScript by default; suppressing type checking defeats the safety guarantee.
+- **[MEDIUM]** `Deno.env.get("VAR")` result used without null check → returns `undefined` for missing variables. Always validate or use a default: `Deno.env.get("PORT") ?? "8000"`.
+- **[LOW]** `import * as foo from "module"` when only one or two exports are needed → increases bundle size in compiled output. Use named imports.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** Network request attempted without `--allow-net` → `Deno.errors.PermissionDenied` thrown at runtime, not at startup. Test with the exact set of permissions you intend to deploy with.
+- **[HIGH]** Top-level `await` in a module imported by many others → delays the entire import chain. Use `await` inside functions or limit top-level `await` to entry points.
+- **[MEDIUM]** `import 'https://deno.land/...'` from the Deno third-party module registry → `deno.land/x` is no longer receiving new modules; prefer `jsr:` for new dependencies.
+- **[MEDIUM]** `Deno.cwd()` used to construct file paths → returns the working directory at runtime, which may differ from the script's location. Use `import.meta.url` + `new URL('./file', import.meta.url).pathname` for script-relative paths.
+- **[LOW]** `Deno.exit()` called in a library function → terminates the entire process; callers cannot handle the error. Throw an error instead.

package/src/prr/data/stacks/django.md

@@ -0,0 +1,92 @@
+# Django — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `from django`, `models.Model`, `views.py`, `urls.py`, `settings.py`, `manage.py`, `INSTALLED_APPS`, DRF `serializers.py`, `djangorestframework`
+
+---
+
+## Security
+
+- **[CRITICAL]** Raw SQL via `raw()` or `cursor.execute()` with string formatting → SQL injection. Use `%s` parameterized or ORM.
+- **[CRITICAL]** `mark_safe()` on user-controlled content → XSS. Only use on strings you fully control.
+- **[CRITICAL]** `DEBUG = True` in production → detailed error pages with source code exposed.
+- **[CRITICAL]** `SECRET_KEY` hardcoded in `settings.py` → version control exposure. Use `os.environ.get()` or `django-environ`.
+- **[HIGH]** Missing `@login_required` or DRF `permission_classes` → unauthenticated access.
+- **[HIGH]** `@csrf_exempt` without justification on state-changing endpoints.
+- **[HIGH]** `ALLOWED_HOSTS = ['*']` in production → HTTP Host header injection.
+- **[HIGH]** Object-level permission not checked → `get_object_or_404` without ownership verification → IDOR.
+- **[HIGH]** Missing `is_staff`/`is_superuser` check on admin-equivalent views.
+- **[HIGH]** File upload without content-type validation → execute malicious file via misconfigured server.
+- **[HIGH]** Open redirect via unvalidated `next` parameter in login views.
+- **[MEDIUM]** Missing `HttpOnly`/`Secure`/`SameSite` flags on session cookie (`SESSION_COOKIE_*` settings).
+- **[MEDIUM]** `MEDIA_ROOT` served by Django in production → should be served by Nginx/CDN with correct content-type.
+- **[MEDIUM]** DRF `TokenAuthentication` over HTTP → tokens transmitted in plaintext. Enforce HTTPS.
+- **[LOW]** Django admin accessible at default `/admin/` path in production → known attack target; change with custom URL.
+
+---
+
+## Performance
+
+- **[CRITICAL]** N+1 ORM queries — accessing related objects in loop without `select_related()` or `prefetch_related()`.
+- **[HIGH]** `QuerySet.all()` without filtering → loads entire table.
+- **[HIGH]** Missing database indexes on frequently filtered/ordered fields (`db_index=True` or `Meta.indexes`).
+- **[HIGH]** `len(queryset)` instead of `queryset.count()` → loads all records into memory.
+- **[HIGH]** Synchronous external API calls in view → blocks Django worker. Use Celery for async work.
+- **[HIGH]** DRF serializer with `many=True` on unfiltered QuerySet → serializing entire table.
+- **[HIGH]** Missing Celery/task queue for email sending, image processing in request-response cycle.
+- **[MEDIUM]** Missing pagination on list views (ListView or DRF `pagination_class`).
+- **[MEDIUM]** Missing `only()` / `defer()` on queries that don't need all fields → SELECT *.
+- **[MEDIUM]** `values()` / `values_list()` not used for read-only aggregation → full ORM overhead.
+- **[MEDIUM]** QuerySet not cached via `django.core.cache` for expensive repeated reads.
+- **[MEDIUM]** Database queries in template rendering (lazy ORM evaluation).
+- **[LOW]** `annotate()` not used for counting related objects → N+1 Python-side counting.
+- **[LOW]** Not using `bulk_create()` / `bulk_update()` for batch DB operations.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic in views or templates → move to model methods, managers, or service layer.
+- **[HIGH]** Fat models >500 lines → split into service classes or managers.
+- **[HIGH]** Django signals used for critical business logic → hard to trace, test. Prefer explicit service calls.
+- **[HIGH]** Not using `AbstractBaseUser` for custom auth → `AUTH_USER_MODEL` migration headaches later.
+- **[HIGH]** `settings.py` not split by environment (base/dev/prod) → debug settings leaked to production.
+- **[MEDIUM]** Missing `related_name` on FK/M2M → reverse accessor is `<model>_set`, confusing.
+- **[MEDIUM]** Direct `settings` import in reusable apps → use `AppConfig`.
+- **[MEDIUM]** Missing migration for model change → `makemigrations` not run, production schema drift.
+- **[MEDIUM]** DRF `ModelSerializer` used with `fields = '__all__'` → over-exposing fields.
+- **[MEDIUM]** DRF view doing too much (validation + business logic + serialization) → extract to service.
+- **[LOW]** Not using Django's `AbstractModel` for common fields (created_at, updated_at).
+- **[LOW]** App-level URLs not included in project `urls.py` via `include()`.
+
+---
+
+## Code Quality
+
+- **[HIGH]** Missing `__str__` on Model → `<Model object (1)>` in admin and logs.
+- **[HIGH]** Missing `Meta.ordering` on models used in list views → non-deterministic order.
+- **[HIGH]** DRF serializer `validate_<field>` not raising `serializers.ValidationError` → validation silently ignored.
+- **[MEDIUM]** `get_or_create` without checking `created` flag → unaware if object was newly created.
+- **[MEDIUM]** `filter().get()` instead of `get()` → extra unnecessary query.
+- **[MEDIUM]** Hardcoded URLs in templates/views instead of `{% url %}` or `reverse()`.
+- **[MEDIUM]** Not using `get_object_or_404` in views → raw `Model.objects.get()` raises 500 on miss.
+- **[MEDIUM]** `null=True` on `CharField`/`TextField` → two empty values (empty string + NULL). Use `blank=True` only.
+- **[MEDIUM]** DRF not using `@action` decorator for custom actions → awkward URL patterns.
+- **[LOW]** Missing `verbose_name`/`verbose_name_plural` on models → ugly admin.
+- **[LOW]** Missing `app_name` in `urls.py` → namespace conflicts.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** QuerySet as default argument (`def fn(qs=Model.objects.all())`) → evaluated once at definition, stale data.
+- **[HIGH]** Transaction not used around multiple related DB writes → partial failure leaves inconsistent state.
+- **[HIGH]** `update()` on QuerySet bypasses `save()` and signals → `pre_save`/`post_save` not triggered.
+- **[HIGH]** `delete()` on QuerySet bypasses model `delete()` and `post_delete` signals.
+- **[HIGH]** `request.user` accessed in model or service layer → breaking separation of concerns and testability.
+- **[MEDIUM]** Timezone-naive `datetime.now()` instead of `timezone.now()` → bugs in non-UTC deployments.
+- **[MEDIUM]** `get_or_create` in concurrent requests → race condition, unique constraint violations.
+- **[MEDIUM]** Signal `sender` not specified → signal fires for all models of that event.
+- **[MEDIUM]** Migration squashing not done → extremely slow migration history.
+- **[LOW]** `on_delete=models.CASCADE` default assumed without considering orphan behavior.
+- **[LOW]** `choices` on CharField not enforced at DB level → only validated in forms/serializers.

package/src/prr/data/stacks/docker.md

@@ -0,0 +1,79 @@
+# Docker — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `Dockerfile*`, `docker-compose*.yml`, `.dockerignore`, `FROM `, `RUN `, `COPY `, `EXPOSE`, `docker` in CI, `compose.yml`
+
+---
+
+## Security
+
+- **[CRITICAL]** Container running as `root` (default) → container escape = root on host. Add `USER nonroot` after creating non-root user.
+- **[CRITICAL]** Secrets passed as `ENV` or `ARG` in Dockerfile → visible in image layers and `docker inspect`. Use Docker BuildKit secrets (`--secret`) or runtime env injection.
+- **[CRITICAL]** `.env` file copied into image via `COPY . .` without `.dockerignore` → secrets in image layer.
+- **[HIGH]** Base image tagged as `latest` → non-deterministic builds, unexpected CVEs from upstream updates. Use `node:20.11.1-alpine3.19`.
+- **[HIGH]** Outdated base image with known CVEs → scan with `docker scout cves` or Trivy.
+- **[HIGH]** `docker-compose.yml` with `privileged: true` without justification → container escapes host namespaces.
+- **[HIGH]** `volumes: /:/host` or similar host root mount → full filesystem access from container.
+- **[HIGH]** Ports bound to `0.0.0.0` for internal services → exposed to all interfaces. Use `127.0.0.1:port:port`.
+- **[HIGH]** Hardcoded credentials in `docker-compose.yml` committed to VCS → credential exposure.
+- **[MEDIUM]** `--cap-add SYS_ADMIN` or `--security-opt seccomp=unconfined` → elevated privileges.
+- **[MEDIUM]** No read-only filesystem (`--read-only`) for containers that don't need write access.
+- **[LOW]** Docker socket (`/var/run/docker.sock`) mounted in container → full Docker daemon access = host escape.
+
+---
+
+## Performance
+
+- **[HIGH]** Layer order wrong — source code copied before `package.json` + install → cache invalidated every code change. Copy lockfile + install first, then source.
+- **[HIGH]** No multi-stage build for compiled languages → dev deps and build tools in production image.
+- **[HIGH]** Large files/directories not in `.dockerignore` → slow build context transfer on every build.
+- **[MEDIUM]** `RUN apt-get install` without `--no-install-recommends` → bloated image with unnecessary packages.
+- **[MEDIUM]** Multiple separate `RUN` commands → extra layers. Chain with `&&` and `\`.
+- **[MEDIUM]** Not using `--mount=type=cache` for package manager cache in BuildKit → re-downloading packages.
+- **[MEDIUM]** Base image not using Alpine/distroless → unnecessarily large image.
+- **[MEDIUM]** `COPY . .` before `npm install` → code changes invalidate dependency cache.
+- **[LOW]** Not squashing layers in final image → history reveals sensitive intermediate steps.
+- **[LOW]** `apt-get` without `apt-get clean && rm -rf /var/lib/apt/lists/*` → package cache in layer.
+
+---
+
+## Architecture
+
+- **[HIGH]** Application state written to container filesystem → lost on restart. Use named volumes for persistent data.
+- **[HIGH]** Missing `HEALTHCHECK` → orchestrator can't detect unhealthy container, continues sending traffic.
+- **[HIGH]** Single container running multiple services → violates SRP, harder to scale, complicated restarts.
+- **[HIGH]** Secret rotation requires image rebuild → use runtime secret injection (Vault, K8s Secrets, AWS SSM).
+- **[MEDIUM]** `docker-compose.yml` used in production without orchestration → no auto-scaling, rolling updates.
+- **[MEDIUM]** Config hardcoded in Dockerfile → image not portable across environments. Use env vars + config files.
+- **[MEDIUM]** `depends_on` used without health check condition → service starts before dependency is ready.
+- **[MEDIUM]** Not using `restart: unless-stopped` / `restart: on-failure` → container doesn't recover from crashes.
+- **[LOW]** Missing `ENTRYPOINT` — only `CMD` → command accidentally overridden at runtime.
+- **[LOW]** Not pinning Docker Compose version in CI → behavior changes with compose updates.
+
+---
+
+## Code Quality
+
+- **[HIGH]** No `.dockerignore` file → unpredictable, large build context (`.git`, `node_modules`, `.env`).
+- **[HIGH]** `ADD url ./` instead of `RUN curl + COPY` → `ADD` fetches during build, no verification.
+- **[MEDIUM]** `ADD` used when `COPY` sufficient — `ADD` has implicit tar extraction and remote URL fetching; `COPY` is explicit.
+- **[MEDIUM]** `ENV` variables not documented → unclear what configuration is available.
+- **[MEDIUM]** `EXPOSE` port not matching actual application port → confusing, may break port mapping.
+- **[MEDIUM]** Non-deterministic `apt-get` package versions → builds differ over time. Pin package versions.
+- **[LOW]** Missing `LABEL` annotations (maintainer, version, description) → untracked images in registry.
+- **[LOW]** Long `RUN` command without line continuation `\` → unreadable Dockerfile.
+- **[LOW]** Not using `WORKDIR` → inconsistent working directory, fragile relative paths.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** Process not handling `SIGTERM` → container doesn't stop gracefully, killed after timeout. Use `exec` form `["node", "app.js"]` not shell form.
+- **[HIGH]** PID 1 not reaping zombie processes → memory leak. Use `--init` flag or `tini` as init process.
+- **[HIGH]** `CMD ["npm", "start"]` without shell → environment variables from `ENV` not available in some contexts. Test both.
+- **[MEDIUM]** Container timezone different from host → cron jobs run at wrong time. Set `TZ` env var.
+- **[MEDIUM]** `COPY --chown` not used → files owned by root inside container, non-root user can't write.
+- **[MEDIUM]** DNS resolution failing in container → missing `--dns` or network mode mismatch.
+- **[MEDIUM]** Build arg (`ARG`) vs environment variable (`ENV`) confusion — `ARG` only available during build, `ENV` persists.
+- **[LOW]** Port already in use on host → `docker run` fails with `bind: address already in use`.
+- **[LOW]** Volume mount overwriting container files → `node_modules` from host overlays container's installed deps.

package/src/prr/data/stacks/drizzle.md

@@ -0,0 +1,54 @@
+# Drizzle ORM — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `drizzle-orm`, `from 'drizzle-orm'`, `drizzle()`, `pgTable`, `mysqlTable`, `sqliteTable`, `migrate()`, `drizzle-kit`
+
+---
+
+## Security
+- **[CRITICAL]** Raw SQL via `sql` tagged template literal with user input not parameterized (e.g., `sql\`WHERE name = '${userInput}'\``) → SQL injection. Use Drizzle's query builder or pass user values as parameterized bindings: `sql\`WHERE name = ${userInput}\`` (Drizzle auto-parameterizes interpolated values in the `sql` tag).
+- **[HIGH]** Drizzle schema file imported and exposed via an API route response → internal table structure, column names, and types leaked to clients. Never serialize schema objects into HTTP responses; expose only shaped DTOs.
+- **[HIGH]** No row-level access control in query layer → any authenticated user can query any row by guessing IDs. Add a `WHERE userId = currentUserId` (or equivalent tenant filter) to every query that returns user-owned data.
+- **[MEDIUM]** Database credentials stored in `drizzle.config.ts` and committed to the repository → credentials exposed in version control history. Read credentials from environment variables (`process.env.DATABASE_URL`) in the config file.
+- **[MEDIUM]** Migrations run with superuser DB credentials in production CI/CD pipeline → accidental schema destruction possible. Use a migration-only role with `CREATE`, `ALTER`, `DROP` on the app schema; separate from the runtime role.
+
+---
+
+## Performance
+- **[HIGH]** N+1 queries from nested `.findMany()` calls without using `.with()` for relations → one query fired per parent row to load children. Switch to Drizzle's relational query API with `.with({ relation: true })` to load related data in a single query.
+- **[HIGH]** No `.limit()` on list queries → full table scan returned to application memory, OOM risk on large tables. Every `findMany` or `select` on an unbounded table must include `.limit(n)`.
+- **[HIGH]** `db.select()` without column projection (no `{ field: table.field }` shape) → all columns fetched; breaks index-only scans and sends unnecessary data over the wire. Pass a columns object to `db.select({ id: table.id, name: table.name })` for every query.
+- **[MEDIUM]** Multi-table mutations (insert + update across tables) not wrapped in a transaction → partial failure leaves data inconsistent. Use `db.transaction(async (tx) => { ... })` for all operations that must be atomic.
+- **[MEDIUM]** Indexes not defined in the Drizzle schema alongside the table → indexes exist only in migration SQL but not tracked in the schema, causing drift. Define all indexes using `.index()` or `.uniqueIndex()` in the same schema file as the table.
+- **[MEDIUM]** `drizzle-kit push` used in staging or production to apply schema changes → `push` may drop and recreate columns, causing data loss. Use `drizzle-kit generate` to produce migration SQL files, review them, then apply with `drizzle-kit migrate`.
+- **[LOW]** Connection not pooled (no PgBouncer or application-level pool like `pg-pool`) → new TCP connection opened per request; connection exhaustion under load. Configure a connection pool and pass the pooled client to `drizzle()`.
+
+---
+
+## Architecture
+- **[HIGH]** Database queries written directly in API route handlers or controllers → no separation of data access from transport layer, making queries untestable in isolation. Extract all DB queries into a repository or data-access layer; import the repository into route handlers.
+- **[MEDIUM]** Drizzle's relational query API not used when related data is needed → developers write complex manual JOINs that are harder to maintain and more error-prone. Use `.query.table.findMany({ with: { relation: {} } })` for relation traversal.
+- **[MEDIUM]** Schema spread across many files without a barrel `schema.ts` export → Drizzle relations and `db` instance require all schema tables; missing tables cause runtime errors. Collect all table definitions in a single `schema.ts` (or `schema/index.ts`) barrel export passed to `drizzle()`.
+- **[MEDIUM]** No seed script for development database → developers set up data manually, causing environment divergence. Provide a `seed.ts` script using Drizzle inserts that can be run with `npx tsx seed.ts`.
+- **[LOW]** Table names in schema not matching actual database table names (no `{ name: 'actual_table' }` option) → Drizzle generates incorrect SQL, causing "relation does not exist" errors. Set the explicit table name string in `pgTable('actual_table_name', ...)` when it differs from the variable name.
+
+---
+
+## Code Quality
+- **[HIGH]** Column types in Drizzle schema not aligned with application TypeScript types (e.g., `text()` for a column that only holds enum values) → invalid values accepted at DB level. Use `text('col', { enum: ['a', 'b', 'c'] })` or add a Zod/Valibot parse step at the boundary.
+- **[HIGH]** `.returning()` omitted after `.insert()` when the generated ID or defaults are needed → `result` is an empty array, causing `undefined` reference on the next line. Chain `.returning()` to every INSERT that the application reads back.
+- **[MEDIUM]** `.notNull()` missing on columns that are logically required → `null` values accumulate and cause unexpected `null` checks throughout the codebase. Add `.notNull()` to every column the application treats as mandatory.
+- **[MEDIUM]** `.$type<T>()` not used for columns that hold branded or opaque types (e.g., `UserId`, `OrderId`) → plain `string` or `number` types allow mixing IDs across entities. Use `text('user_id').$type<UserId>()` to brand column types and catch cross-entity ID bugs at compile time.
+- **[MEDIUM]** Drizzle TypeScript types not inferred with `typeof table.$inferSelect` / `.$inferInsert` → manual type duplication drifts from schema over time. Use Drizzle's inferred types everywhere instead of hand-written interfaces.
+- **[LOW]** Table naming inconsistency between Drizzle variable name and the DB table name passed as first arg → confusion when reading error messages or raw SQL logs. Keep Drizzle variable name and table name string identical (both snake_case).
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** `.insert().values()` result used without `.returning()` → the return value is a result metadata object (rowCount), not the inserted row; accessing `.id` returns `undefined`. Always add `.returning({ id: table.id })` (or the needed fields) after `.insert().values()`.
+- **[HIGH]** Relations defined in the Drizzle schema with `relations()` but `.with()` not used in the actual query → N+1 still occurs because `relations()` only informs the query API; it does not automatically join. Use `db.query.table.findMany({ with: { relation: {} } })` to activate the relation.
+- **[MEDIUM]** `drizzle-kit push` used against a production database → push computes a diff and may drop columns or tables to match the schema, causing irreversible data loss. Enforce a CI policy that only `drizzle-kit migrate` (with reviewed migration files) runs in production.
+- **[MEDIUM]** Database connection created inside a request handler (e.g., `const db = drizzle(new Pool(...))` per request) → new pool created for every request, exhausting DB connections rapidly. Create the `db` instance once at module initialization and reuse it.
+- **[MEDIUM]** `eq(table.col, undefined)` passed to a WHERE clause when an optional filter is absent → Drizzle generates `WHERE col = NULL` (never matches). Guard optional filters: `...(value !== undefined ? [eq(table.col, value)] : [])` using `and()`.
+- **[LOW]** Drizzle type inference breaking on complex union or conditional columns → TypeScript errors cascade through the codebase. Pin Drizzle and `drizzle-kit` to the same exact semver version and upgrade them together.
+