feat: implement Phase R Wave 1 — five cross-signal diagnostic rules

R.1 sync-in-hot-path: escalates readFileSync/writeFileSync to critical
when called inside an active request context (via AsyncLocalStorage).

R.2 missing-connection-pool: TypeScript AST walk at startup detects
new Client() / createConnection() inside function bodies, flags them
as warning with a fix suggestion to move to module scope.

R.3 correlated-slow-endpoint: emits anomaly when a slow outbound HTTP
request (>1s) and an active N+1 pattern share the same W3C traceId.

R.4 pool-starvation-by-slow-query: emits anomaly when pool-exhaustion
fires within 10s of a slow query on the same driver, surfacing the
likely culprit holding connections.

R.5 n-plus-one-in-transaction: escalates N+1 detection to critical
when the pattern fires inside an open transaction (same traceId/
correlationId), where repeated queries also delay COMMIT.

541 tests pass. 0 TS errors. 0 ESLint errors. Prettier clean.

Author: sharon77242

packages/agent/src/analysis/fs-analyzer.ts

@@ -5,7 +5,7 @@ export class FsAnalyzer {
   private readonly READ_WINDOW_MS = 1000;
   private readonly READ_THRESHOLD = 5;
 
-  public analyze(methodName: string, filePath: string): FixSuggestion[] {
+  public analyze(methodName: string, filePath: string, insideRequest?: boolean): FixSuggestion[] {
     const suggestions: FixSuggestion[] = [];
 
     // 1. Sync Method Detection - Event Loop Blockers
@@ -16,6 +16,15 @@ export class FsAnalyzer {
         message: `Usage of ${methodName} blocks the entire Node.js Event Loop. A slow disk read pauses all other requests.`,
         suggestedFix: `Replace ${methodName} with the equivalent promise-based fs.promises.${methodName.replace("Sync", "")}() and await it.`,
       });
+
+      if (insideRequest) {
+        suggestions.push({
+          severity: "critical",
+          rule: "sync-in-hot-path",
+          message: `${methodName} called inside a live request handler — blocks the event loop for every concurrent request.`,
+          suggestedFix: `Replace with fs.promises.${methodName.replace("Sync", "")}() and await it.`,
+        });
+      }
     }
 
     // 2. Path Traversal Risks

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

@@ -23,9 +23,19 @@ interface TsDiagnostic {
   code: number;
   messageText: string | TsDiagnosticMessageChain;
 }
+interface TsNode {
+  kind: number;
+  pos: number;
+  end: number;
+}
+interface TsSourceFile extends TsNode {
+  fileName: string;
+  getLineAndCharacterOfPosition(pos: number): { line: number; character: number };
+}
 interface TsProgram {
   getSyntacticDiagnostics(): readonly TsDiagnostic[];
   getSemanticDiagnostics(): readonly TsDiagnostic[];
+  getSourceFiles(): readonly TsSourceFile[];
 }
 interface TsApi {
   sys: TsSystem;
@@ -48,6 +58,16 @@ interface TsApi {
     messageText: string | TsDiagnosticMessageChain,
     newLine: string,
   ): string;
+  SyntaxKind: {
+    readonly NewExpression: number;
+    readonly CallExpression: number;
+    readonly FunctionDeclaration: number;
+    readonly FunctionExpression: number;
+    readonly ArrowFunction: number;
+    readonly MethodDeclaration: number;
+    readonly Constructor: number;
+  };
+  forEachChild<T>(node: TsNode, cbNode: (node: TsNode) => T | undefined): T | undefined;
 }
 
 /**
@@ -85,7 +105,7 @@ export class StaticScanner extends EventEmitter {
   }
 
   /**
-   * Run a full scan (TypeScript + ESLint if available).
+   * Run a full scan (TypeScript + ESLint + connection-pool static rules if available).
    */
   public async scan(): Promise<ScanResult[]> {
     const results: ScanResult[] = [];
@@ -98,6 +118,11 @@ export class StaticScanner extends EventEmitter {
       results.push(eslintResult);
     }
 
+    const poolResult = await this.runConnectionPoolScan();
+    if (poolResult && poolResult.totalIssues > 0) {
+      results.push(poolResult);
+    }
+
     this.emit("scan", results);
     return results;
   }
@@ -250,6 +275,113 @@ export class StaticScanner extends EventEmitter {
     });
   }
 
+  /**
+   * R.2 — Scan TypeScript source files for connection constructors called inside
+   * function bodies (missing-connection-pool). Uses the TypeScript Compiler API
+   * to walk the AST; returns null if TypeScript is not available.
+   */
+  public async runConnectionPoolScan(): Promise<ScanResult | null> {
+    const start = performance.now();
+
+    try {
+      const tsId = "typescript";
+      const tsModule: unknown = await import(tsId);
+      const ts = ((tsModule as { default?: TsApi }).default ?? tsModule) as TsApi;
+
+      const configPath = ts.findConfigFile(
+        this.targetDir,
+        (p: string) => ts.sys.fileExists(p),
+        "tsconfig.json",
+      );
+      if (!configPath) return null;
+
+      const { config, error: readError } = ts.readConfigFile(
+        configPath,
+        (p: string, enc?: string) => ts.sys.readFile(p, enc),
+      );
+      if (readError) return null;
+
+      const parsed = ts.parseJsonConfigFileContent(config as object, ts.sys, dirname(configPath));
+      const program = ts.createProgram(parsed.fileNames, { ...parsed.options, noEmit: true });
+
+      const suggestions = this.detectConnectionInFunction(ts, program);
+
+      return {
+        tool: "argus-static",
+        totalIssues: suggestions.length,
+        suggestions,
+        durationMs: performance.now() - start,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  private detectConnectionInFunction(ts: TsApi, program: TsProgram): FixSuggestion[] {
+    const suggestions: FixSuggestion[] = [];
+
+    const CONNECTION_CTORS = new Set([
+      "Client",
+      "Connection",
+      "Sequelize",
+      "MongoClient",
+      "createConnection",
+      "createPool",
+    ]);
+
+    const FUNCTION_KINDS = new Set([
+      ts.SyntaxKind.FunctionDeclaration,
+      ts.SyntaxKind.FunctionExpression,
+      ts.SyntaxKind.ArrowFunction,
+      ts.SyntaxKind.MethodDeclaration,
+      ts.SyntaxKind.Constructor,
+    ]);
+
+    const walk = (node: TsNode, sourceFile: TsSourceFile, insideFunction: boolean): void => {
+      const enterFunction = FUNCTION_KINDS.has(node.kind);
+      const nowInside = insideFunction || enterFunction;
+      const kindNew = ts.SyntaxKind.NewExpression;
+      const kindCall = ts.SyntaxKind.CallExpression;
+
+      if (insideFunction && (node.kind === kindNew || node.kind === kindCall)) {
+        const expr = (node as { expression?: { text?: string } }).expression;
+        const name = expr?.text;
+
+        if (name && CONNECTION_CTORS.has(name)) {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.pos);
+          const prefix = node.kind === kindNew ? `new ${name}()` : `${name}()`;
+          suggestions.push({
+            severity: "warning",
+            rule: "missing-connection-pool",
+            message: `${prefix} called inside a function body — creates a new connection per call instead of reusing a pool.`,
+            suggestedFix:
+              "Move the client/pool instantiation to module scope and reuse it across requests.",
+            location: `${sourceFile.fileName}:${line + 1}:${character + 1}`,
+          });
+        }
+      }
+
+      ts.forEachChild(node, (child) => {
+        walk(child, sourceFile, nowInside);
+        return undefined;
+      });
+    };
+
+    for (const sourceFile of program.getSourceFiles()) {
+      if (
+        sourceFile.fileName.includes("node_modules") ||
+        sourceFile.fileName.endsWith(".d.ts") ||
+        sourceFile.fileName.endsWith(".test.ts") ||
+        sourceFile.fileName.endsWith(".spec.ts")
+      )
+        continue;
+
+      walk(sourceFile as TsNode, sourceFile, false);
+    }
+
+    return suggestions;
+  }
+
   /**
    * Parse TypeScript compiler output into FixSuggestions.
    * Format: `filepath(line,col): error TSxxxx: message`