feat: implement Phase R Wave 2 and demo app Phase R scenarios

Wave 2 — three new cross-codebase diagnostic rules:

R.4 query-in-loop (source-analyzer.ts):
  TypeScript AST walker detects DB method calls (query, execute,
  findMany, find, etc.) inside any loop or iteration callback
  (.map, .forEach, .filter, .reduce, …). Integrated into
  StaticScanner.runQueryInLoopScan() → fires at startup alongside
  the existing tsc/ESLint/pool-scan passes.

R.5 missing-index-hint (migration-scanner.ts + index-hint-analyzer.ts):
  MigrationScanner parses CREATE INDEX / CREATE UNIQUE INDEX from SQL
  files and @@index([…]) from Prisma schemas into a table→columns
  index map. IndexHintAnalyzer tracks per-query frequency in a sliding
  window; when a query exceeds the threshold (default 100/min) against
  an un-indexed WHERE column it emits a concrete CREATE INDEX
  suggestion. Zero false positives when no migration files exist.
  Enabled via .withIndexHints(dir?).

R.6 endpoint-never-called (route-tracker.ts):
  RouteTracker accepts registered routes detected by a regex scanner
  (Express/Fastify patterns) and records inbound hits via
  createMiddleware(). After a configurable warmup it emits an
  endpoint-never-called anomaly for every route with zero traffic.
  Enabled via .withRouteTracking(dir?, warmupMs?). Auto-wired for
  web app type in dev/test via profile-factory.

Demo app — Phase R live scenarios:
  - app.js wires agent.createMiddleware() for W3C traceId propagation.
  - GET /debug/correlated-slow: N+1 × 6 + 1 100ms delay on same
    traceId → correlated-slow-endpoint (critical).
  - GET /debug/n-plus-one-in-txn: BEGIN + N+1 × 6 + COMMIT →
    n-plus-one-in-transaction (critical).
  - GET /debug/sync-read now also fires sync-in-hot-path (critical)
    because createMiddleware() makes the request context visible.
  - diagnostic.js anomaly handler prints full suggestions array.
  - traffic.js updated with three new Phase R traffic scenarios.

Quality: 570 tests, 0 TS errors, 0 ESLint errors, Prettier clean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sharon77242

CHANGELOG.md

@@ -10,6 +10,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Phase R Wave 2 — Static + runtime intelligence rules**: Three new rules that combine
+  static codebase knowledge with runtime frequency data to surface issues no single monitor
+  can detect alone.
+  - **`query-in-loop`** (`warning`) — `SourceAnalyzer` walks the TypeScript AST of every
+    source file at startup. When a known DB method call (`query`, `execute`, `findMany`,
+    `find`, etc.) appears inside a loop (`for`, `while`, `do`, `for…of`, `for…in`) or an
+    iteration callback (`.map()`, `.forEach()`, `.filter()`, `.reduce()`, …), it emits a
+    `query-in-loop` suggestion with the exact file:line location. Wired into
+    `StaticScanner.scan()` via the new `runQueryInLoopScan()` method.
+  - **`missing-index-hint`** (`warning`) — `MigrationScanner` parses SQL migration files
+    (`CREATE INDEX` / `CREATE UNIQUE INDEX`) and Prisma schema files (`@@index([…])`) at
+    startup to build a `table → Set<column>` index map. `IndexHintAnalyzer` then tracks
+    per-query execution frequency in a sliding window; when a query exceeds the threshold
+    (default 100/min) against an un-indexed `WHERE` column, it emits a concrete
+    `CREATE INDEX` suggestion. Only fires when migration files were found — no false
+    positives when the index map is empty. Enabled via `.withIndexHints(dir?)`.
+  - **`endpoint-never-called`** (`info`) — `RouteTracker` accepts a list of registered
+    routes (extracted by a regex scanner from Express/Fastify source files) and records
+    inbound request hits via `createMiddleware()`. After the warmup period (default 5 min)
+    a `'anomaly'` event is emitted listing routes that never received a request. Enabled
+    via `.withRouteTracking(dir?, warmupMs?)`. Wired automatically in `profile-factory.ts`
+    for `web` app type in dev/test environments.
+
+- **Demo app — Phase R scenarios** (`quotes-demo-app/`):
+  - W3C trace context is now propagated into every request via `agent.createMiddleware()` —
+    wired in `app.js` so all cross-signal rules can correlate DB calls with their
+    originating HTTP request.
+  - `GET /debug/correlated-slow` — runs 6 N+1 queries + 1 100 ms deliberate delay within
+    one request, triggering `correlated-slow-endpoint` (critical).
+  - `GET /debug/n-plus-one-in-txn` — `BEGIN` + 6 identical-template SELECTs + `COMMIT`,
+    triggering `n-plus-one-in-transaction` (critical).
+  - `GET /debug/sync-read` already demonstrates `sync-in-hot-path` now that the middleware
+    is active (both `synchronous-fs` and `sync-in-hot-path` fire simultaneously).
+  - The `anomaly` event handler in `diagnostic.js` now prints the full `suggestions` array
+    (rule name, severity, message, suggestedFix) for all Phase R compound events.
+  - `traffic.js` updated with three new Phase R traffic scenarios.
+
 - **Phase R Wave 1 — Cross-signal diagnostic rules**: Five new rules that correlate events
   from multiple subsystems to produce high-signal compound anomalies that no single monitor
   can produce alone.

README.md

@@ -188,6 +188,14 @@ cd quotes-demo-app && docker compose -f docker-compose-pg-only.yml up -d && npm
 node simulate.js   # scripted traffic sequence — watch the agent fire in real time
 ```
 
+The scripted traffic sequence exercises every monitoring feature, including the Phase R cross-signal rules:
+
+| Route | Phase R rule triggered | Severity |
+|---|---|---|
+| `GET /debug/sync-read` (×3, with `createMiddleware`) | `sync-in-hot-path` — sync FS inside live request | critical |
+| `GET /debug/correlated-slow` | `correlated-slow-endpoint` — N+1 + slow HTTP on same traceId | critical |
+| `GET /debug/n-plus-one-in-txn` | `n-plus-one-in-transaction` — N+1 inside BEGIN/COMMIT | critical |
+
 See [`quotes-demo-app/README.md`](quotes-demo-app/README.md) for the full setup guide, annotated terminal output, and curl examples.
 
 ---
@@ -719,8 +727,12 @@ packages/agent/
       http-analyzer.ts               → Insecure URL & slow request detection
       log-analyzer.ts                → Log storm & payload size detection
       circuit-breaker-detector.ts    → Sustained error-rate detection across drivers
-      static-scanner.ts              → Background tsc / ESLint issue tracking
+      static-scanner.ts              → Background tsc / ESLint / query-in-loop static analysis
       audit-scanner.ts               → npm audit CVE scanning
+      source-analyzer.ts             → R.4: TypeScript AST scan for DB calls inside loops
+      migration-scanner.ts           → R.5: SQL & Prisma migration parser → index map
+      index-hint-analyzer.ts         → R.5: Runtime high-frequency missing-index detection
+      route-tracker.ts               → R.6: Endpoint-never-called detection after warmup
 
     export/
       aggregator.ts                  → p99 sliding window metric aggregation

packages/agent/src/analysis/index-hint-analyzer.ts

@@ -0,0 +1,87 @@
+import type { FixSuggestion } from "./types.ts";
+
+export interface IndexHintOptions {
+  /** Minimum query executions per window before checking for missing indexes. Default: 100. */
+  frequencyThreshold?: number;
+  /** Sliding window duration in ms. Default: 60 000. */
+  windowMs?: number;
+}
+
+// Extracts the table name from the FROM clause of a sanitized SQL query.
+const FROM_RE = /\bFROM\s+["'`]?(\w+)["'`]?/i;
+
+// Extracts column names from WHERE / AND / OR conditions.
+const WHERE_COL_RE =
+  /(?:\bWHERE\b|\bAND\b|\bOR\b)\s+["'`]?(\w+)["'`]?\s*(?:=|>|<|>=|<=|<>|!=|LIKE|IN\s*\()/gi;
+
+function extractTable(query: string): string | undefined {
+  return FROM_RE.exec(query)?.[1];
+}
+
+function extractWhereCols(query: string): string[] {
+  const cols: string[] = [];
+  WHERE_COL_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = WHERE_COL_RE.exec(query)) !== null) {
+    cols.push(m[1]);
+  }
+  return cols;
+}
+
+/**
+ * Tracks query execution frequency and emits missing-index-hint suggestions
+ * when a high-frequency query targets un-indexed columns.
+ *
+ * Only fires when the caller has provided a non-empty index map (from MigrationScanner).
+ * With an empty map there is no ground truth, so the rule stays silent to avoid
+ * false positives.
+ */
+export class IndexHintAnalyzer {
+  private readonly frequencyThreshold: number;
+  private readonly windowMs: number;
+  private readonly freq = new Map<string, { count: number; windowStart: number }>();
+  private readonly indexMap: Map<string, Set<string>>;
+
+  constructor(indexMap: Map<string, Set<string>>, opts: IndexHintOptions = {}) {
+    this.indexMap = indexMap;
+    this.frequencyThreshold = opts.frequencyThreshold ?? 100;
+    this.windowMs = opts.windowMs ?? 60_000;
+  }
+
+  analyze(sanitizedQuery: string): FixSuggestion[] {
+    // No ground truth — stay silent
+    if (this.indexMap.size === 0) return [];
+
+    const key = sanitizedQuery.slice(0, 200);
+    const now = Date.now();
+
+    const entry = this.freq.get(key);
+    if (!entry || now - entry.windowStart > this.windowMs) {
+      // Start a fresh window
+      this.freq.set(key, { count: 1, windowStart: now });
+      return [];
+    }
+
+    entry.count++;
+    if (entry.count < this.frequencyThreshold) return [];
+
+    // Threshold reached — check for missing indexes
+    const table = extractTable(sanitizedQuery);
+    if (!table) return [];
+
+    const indexedCols = this.indexMap.get(table);
+    // Table not found in migration files — no ground truth, stay silent
+    if (!indexedCols) return [];
+
+    const whereCols = extractWhereCols(sanitizedQuery);
+    const missing = whereCols.filter((c) => !indexedCols.has(c));
+    if (missing.length === 0) return [];
+
+    return missing.map((col) => ({
+      severity: "warning" as const,
+      rule: "missing-index-hint",
+      message: `Query on ${table}.${col} fired ${entry.count}x in ${this.windowMs}ms but column has no index.`,
+      suggestedFix: `CREATE INDEX idx_${table.toLowerCase()}_${col} ON ${table} (${col});`,
+    }));
+  }
+}

packages/agent/src/analysis/migration-scanner.ts

@@ -0,0 +1,111 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, extname } from "node:path";
+
+// Matches: CREATE [UNIQUE] INDEX [IF NOT EXISTS] <name> ON <table> (<col1>, <col2>, ...)
+const SQL_INDEX_RE =
+  /CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?\S+\s+ON\s+["'`]?(\w+)["'`]?\s*\(([^)]+)\)/gi;
+
+// Matches Prisma: @@index([col1, col2]) or @@unique([col1])
+const PRISMA_INDEX_RE = /@@(?:index|unique)\(\[([^\]]+)\]\)/gi;
+
+// Matches the current Prisma model name: model <Name> {
+const PRISMA_MODEL_RE = /^model\s+(\w+)\s*\{/m;
+
+async function collectFiles(dir: string, ext: string, found: string[]): Promise<void> {
+  let entries: string[];
+  try {
+    const raw = await readdir(dir);
+    entries = raw.map(String);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, String(entry));
+    try {
+      const s = await stat(full);
+      if (s.isDirectory()) {
+        await collectFiles(full, ext, found);
+      } else if (extname(String(entry)) === ext) {
+        found.push(full);
+      }
+    } catch {
+      // skip unreadable entries
+    }
+  }
+}
+
+function parseSqlIndexes(sql: string, indexMap: Map<string, Set<string>>): void {
+  SQL_INDEX_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = SQL_INDEX_RE.exec(sql)) !== null) {
+    const table = m[1];
+    const cols = m[2].split(",").map((c) => c.trim().replace(/["'`]/g, ""));
+    let set = indexMap.get(table);
+    if (!set) {
+      set = new Set();
+      indexMap.set(table, set);
+    }
+    for (const col of cols) set.add(col);
+  }
+}
+
+function parsePrismaIndexes(content: string, indexMap: Map<string, Set<string>>): void {
+  // Split into model blocks and extract model name + @@index directives
+  const modelBlocks = content.split(/(?=\nmodel\s)/);
+  for (const block of modelBlocks) {
+    const modelMatch = PRISMA_MODEL_RE.exec(block);
+    if (!modelMatch) continue;
+    const modelName = modelMatch[1];
+
+    PRISMA_INDEX_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = PRISMA_INDEX_RE.exec(block)) !== null) {
+      const cols = m[1].split(",").map((c) => c.trim());
+      let set = indexMap.get(modelName);
+      if (!set) {
+        set = new Set();
+        indexMap.set(modelName, set);
+      }
+      for (const col of cols) set.add(col);
+    }
+  }
+}
+
+/**
+ * Scans migration files (SQL, Prisma schema) and returns a map of
+ * table/model names to their indexed column sets.
+ */
+export class MigrationScanner {
+  async scan(dir: string): Promise<Map<string, Set<string>>> {
+    const indexMap = new Map<string, Set<string>>();
+
+    const sqlFiles: string[] = [];
+    const prismaFiles: string[] = [];
+
+    await Promise.all([
+      collectFiles(dir, ".sql", sqlFiles),
+      collectFiles(dir, ".prisma", prismaFiles),
+    ]);
+
+    await Promise.all([
+      ...sqlFiles.map(async (f) => {
+        try {
+          const content = await readFile(f, "utf8");
+          parseSqlIndexes(content, indexMap);
+        } catch {
+          // skip unreadable
+        }
+      }),
+      ...prismaFiles.map(async (f) => {
+        try {
+          const content = await readFile(f, "utf8");
+          parsePrismaIndexes(content, indexMap);
+        } catch {
+          // skip unreadable
+        }
+      }),
+    ]);
+
+    return indexMap;
+  }
+}

packages/agent/src/analysis/route-tracker.ts

@@ -0,0 +1,77 @@
+import type { FixSuggestion } from "./types.ts";
+
+export interface RouteInfo {
+  method: string;
+  pattern: string;
+  sourceLine: string;
+}
+
+/**
+ * Converts a route pattern (e.g. `/users/:id`) into a RegExp that matches
+ * concrete URLs (e.g. `/users/123` or `/users/abc-def`).
+ */
+function patternToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.*+?^${}()|[\]\\]/g, "\\$&") // escape special chars
+    .replace(/:\\[^/]+/g, "([^/]+)") // :param → ([^/]+)  (after escaping colons become :\)
+    .replace(/:\w+/g, "([^/]+)"); // :param → ([^/]+)  (unescaped colons)
+  return new RegExp(`^${escaped}/?$`, "i");
+}
+
+function routeKey(method: string, pattern: string): string {
+  return `${method.toUpperCase()} ${pattern}`;
+}
+
+/**
+ * R.6 — Tracks which registered routes have been called at least once.
+ * After `check()` is called (e.g. after a warmup period), any route with zero
+ * hits is reported as an `endpoint-never-called` suggestion.
+ */
+export class RouteTracker {
+  private readonly hitKeys = new Set<string>();
+  private readonly routes: RouteInfo[];
+  private readonly routeRegexes: { key: string; regex: RegExp; info: RouteInfo }[];
+
+  constructor(knownRoutes: RouteInfo[]) {
+    this.routes = knownRoutes;
+    this.routeRegexes = knownRoutes.map((r) => ({
+      key: routeKey(r.method, r.pattern),
+      regex: patternToRegex(r.pattern),
+      info: r,
+    }));
+  }
+
+  /**
+   * Record that an inbound HTTP request hit a given method + URL.
+   * Matches against all registered route patterns; parameterized routes
+   * (e.g. `/users/:id`) match concrete URLs (e.g. `/users/123`).
+   */
+  recordHit(method: string, url: string): void {
+    const upperMethod = method.toUpperCase();
+    // Strip query string for matching
+    const path = url.split("?")[0];
+
+    for (const { key, regex, info } of this.routeRegexes) {
+      if (info.method.toUpperCase() === upperMethod && regex.test(path)) {
+        this.hitKeys.add(key);
+      }
+    }
+  }
+
+  /**
+   * Returns suggestions for routes that have never been hit.
+   * Call this after the warmup period has elapsed.
+   */
+  check(): FixSuggestion[] {
+    return this.routes
+      .filter((r) => !this.hitKeys.has(routeKey(r.method, r.pattern)))
+      .map((r) => ({
+        severity: "info" as const,
+        rule: "endpoint-never-called",
+        message: `${r.method.toUpperCase()} ${r.pattern} has never been called since startup.`,
+        suggestedFix:
+          "Consider removing this route if it is no longer needed, or add a health check / integration test that exercises it.",
+        location: r.sourceLine,
+      }));
+  }
+}