@codebaz/nextdoctor-agent 0.1.0-beta.1

package/src/detectors/cold-start-threshold.detector.ts

@@ -0,0 +1,95 @@
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { BaseDetector } from './base-detector.js';
+import type { DetectedIssue, DetectorContext } from './types.js';
+
+export class ColdStartThresholdDetector extends BaseDetector {
+  readonly id = 'COLD_START_THRESHOLD';
+  readonly name = 'Cold Start Threshold Detector';
+  private readonly threshold = 800; // ms
+  private readonly minSamplesForVariance = 20;
+
+  detect(spans: ReadableSpan[], context: DetectorContext): DetectedIssue[] {
+    const issues: DetectedIssue[] = [];
+
+    // Check startup time if provided
+    if (context.startupTimeMs && context.startupTimeMs > this.threshold) {
+      issues.push({
+        id: this.id,
+        severity: 'critical',
+        message: `Edge cold start ${context.startupTimeMs}ms > ${this.threshold}ms → users are paying this cost on every cold invocation`,
+        suggestion: `Options in order of impact:
+
+1. Move heavy imports outside the handler:
+// ❌ Inside the handler
+export default async function handler(req, res) {
+  const { heavy } = await import('./heavy-lib');
+  return handleRequest(heavy, req);
+}
+
+// ✅ Outside the handler
+const heavyPromise = import('./heavy-lib');
+export default async function handler(req, res) {
+  const { heavy } = await heavyPromise;
+  return handleRequest(heavy, req);
+}
+
+2. Consider switching to Node.js runtime if Edge is not required:
+export const runtime = 'nodejs';
+
+3. Use route warming via a cron job to keep instances warm.`,
+        route: context.route,
+        attributes: {
+          startupTimeMs: context.startupTimeMs,
+          threshold: this.threshold,
+          runtime: context.runtime,
+        },
+        detectedAt: Date.now(),
+      });
+    }
+
+    // Detect intermittent cold starts via span latency variance
+    const routeSpans = context.route
+      ? spans.filter(s => s.attributes?.['http.route'] === context.route)
+      : spans.filter(s => s.attributes?.['http.route']);
+
+    if (routeSpans.length >= this.minSamplesForVariance) {
+      const durations = routeSpans.map(s => this.getSpanDurationMs(s));
+      const sorted = [...durations].sort((a, b) => a - b);
+      const p50 = this.percentile(sorted, 50);
+      const p99 = this.percentile(sorted, 99);
+      const variance = p99 - p50;
+
+      if (variance > 2000) {
+        issues.push({
+          id: 'COLD_START_INTERMITTENT',
+          severity: 'warning',
+          message: `Route "${context.route || 'unknown'}" has high latency variance: P50=${Math.round(p50)}ms vs P99=${Math.round(p99)}ms → likely intermittent cold starts`,
+          suggestion: `A difference > 2000ms between P50 and P99 indicates periodic cold starts. Consider these strategies:
+
+1. Keep-warm via external cron job (call your endpoint every 5 minutes)
+2. Migrate to Node.js runtime if Edge Runtime is optional:
+export const runtime = 'nodejs';
+
+3. Use Next.js Middleware to keep the runtime warm — middleware runs on every
+   request and prevents full cold starts on subsequent edge invocations:
+
+// middleware.ts
+export const config = { matcher: '/api/:path*' };
+export function middleware() {
+  // Intentionally lightweight — presence keeps runtime warm
+}`,
+          route: context.route,
+          attributes: {
+            p50: Math.round(p50),
+            p99: Math.round(p99),
+            variance: Math.round(variance),
+            sampleCount: sorted.length,
+          },
+          detectedAt: Date.now(),
+        });
+      }
+    }
+
+    return issues;
+  }
+}

package/src/detectors/dynamic-route-candidate.detector.ts

@@ -0,0 +1,107 @@
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { BaseDetector } from './base-detector.js';
+import type { DetectedIssue, DetectorContext } from './types.js';
+
+/**
+ * DYNAMIC_ROUTE_CANDIDATE Detector
+ *
+ * Detects routes that call cookies() or headers() without reading any value,
+ * forcing unnecessary dynamic rendering.
+ *
+ * ⚠️ KNOWN LIMITATION: Next.js does not emit granular OTel spans for individual
+ * cookie key reads (e.g. cookies().get('key')). This detector uses a conservative
+ * heuristic: if the cookies/headers span has no child spans, the call is considered
+ * unused. This may produce false negatives (misses cases where a key is read) but
+ * avoids false positives (incorrectly flagging correct usage).
+ *
+ * Severity is 'info' until validated with real production traces.
+ */
+export class DynamicRouteCandidateDetector extends BaseDetector {
+  readonly id = 'DYNAMIC_ROUTE_CANDIDATE';
+  readonly name = 'Dynamic Route Candidate Detector';
+
+  detect(spans: ReadableSpan[], context: DetectorContext): DetectedIssue[] {
+    const issues: DetectedIssue[] = [];
+
+    if (!context.route) {
+      return issues;
+    }
+
+    // Find spans that indicate reading of cookies/headers
+    const cookiesSpans = spans.filter(s => s.name === 'cookies');
+    const headersSpans = spans.filter(s => s.name === 'headers');
+
+    const dynamicTriggerSpans = [...cookiesSpans, ...headersSpans];
+
+    dynamicTriggerSpans.forEach(span => {
+      const children = this.getChildSpans(span, spans);
+
+      // Conservative heuristic: if there are NO child spans at all,
+      // cookies()/headers() was called but nothing was read from it.
+      // If there ARE children, assume the value was used (safer default).
+      const hasAnyChildActivity = children.length > 0;
+
+      if (!hasAnyChildActivity) {
+        const spanName = span.name === 'cookies' ? 'cookies()' : 'headers()';
+        
+        issues.push({
+          id: this.id,
+          severity: 'info',
+          message: `Route "${context.route}" may be unnecessarily dynamic: ${spanName} called with no subsequent reads detected`,
+          suggestion: `This route is paying the dynamic rendering cost without reading any actual values.
+
+Option 1 — Remove the ${spanName}() call:
+// ❌ Before
+export default async function Page() {
+  const cookies = cookies(); // forces dynamic but never used
+  return <div>Static content</div>;
+}
+
+// ✅ After
+export default function Page() {
+  return <div>Static content</div>;
+}
+
+Option 2 — Move to a Server Action:
+'use client';
+import { getSessionCookie } from './actions';
+
+export default function Page() {
+  const handleClick = async () => {
+    const session = await getSessionCookie();
+    // ...
+  };
+  return <button onClick={handleClick}>Click me</button>;
+}
+
+// app/actions.ts
+'use server';
+import { cookies } from 'next/headers';
+
+export async function getSessionCookie() {
+  const c = cookies();
+  return c.get('session')?.value;
+}
+
+Option 3 — If the route is fully static and shouldn't trigger dynamic rendering:
+export const dynamic = 'force-static';
+
+export default function Page() {
+  // ... static content
+}
+
+See: https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic`,
+          route: context.route,
+          spanId: span.spanContext().spanId,
+          attributes: {
+            trigger: span.name,
+            childrenCount: children.length,
+          },
+          detectedAt: Date.now(),
+        });
+      }
+    });
+
+    return issues;
+  }
+}

package/src/detectors/fetch-no-cache.detector.ts

@@ -0,0 +1,204 @@
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { BaseDetector } from './base-detector.js';
+import type { DetectedIssue, DetectorContext } from './types.js';
+
+interface FetchInfo {
+  url: string;
+  duration: number;
+  spanId: string;
+}
+
+export class FetchNoCacheDetector extends BaseDetector {
+  readonly id = 'FETCH_NO_CACHE';
+  readonly name = 'Fetch Without Cache Detector';
+  private readonly minDurationMs = 50;
+  private readonly nPlus1Threshold = 3;
+
+  detect(spans: ReadableSpan[], context: DetectorContext): DetectedIssue[] {
+    const issues: DetectedIssue[] = [];
+
+    // Find fetch spans without cache directive
+    const fetchSpans = spans.filter(span => {
+      const name = span.name.toLowerCase();
+      return name.includes('fetch') || name.includes('http.client');
+    });
+
+    const noCacheFetches: FetchInfo[] = [];
+    const urlCounts = new Map<string, FetchInfo[]>();
+
+    fetchSpans.forEach(span => {
+      const method = this.getSpanMethod(span);
+      const url = this.getSpanUrl(span);
+
+      // Ignore non-GET and non-POST (POST/PUT/DELETE shouldn't be cached anyway)
+      if (!method || !['GET', 'HEAD'].includes(method.toUpperCase())) {
+        return;
+      }
+
+      if (!url) {
+        return;
+      }
+
+      // Ignore internal URLs
+      if (this.isInternalUrl(url)) {
+        return;
+      }
+
+      // Check cache directive
+      const cacheAttr = this.getStringAttribute(span, 'fetch.cache');
+      const nextRevalidate = this.getNumberAttribute(span, 'next.revalidate');
+
+      // Has cache if:
+      // - has fetch.cache='force-cache' or 'force-revalidate'
+      // - has next.revalidate > 0
+      const hasCache = 
+        cacheAttr === 'force-cache' ||
+        cacheAttr === 'force-revalidate' ||
+        (nextRevalidate !== undefined && nextRevalidate > 0);
+
+      if (hasCache) {
+        return;
+      }
+
+      const duration = this.getSpanDurationMs(span);
+      if (duration < this.minDurationMs) {
+        return;
+      }
+
+      const fetchInfo = {
+        url,
+        duration,
+        spanId: span.spanContext().spanId,
+      };
+
+      noCacheFetches.push(fetchInfo);
+
+      // Track for N+1 detection
+      const existing = urlCounts.get(url);
+      if (existing) {
+        existing.push(fetchInfo);
+      } else {
+        urlCounts.set(url, [fetchInfo]);
+      }
+    });
+
+    // Report individual fetches and group N+1s
+    urlCounts.forEach((fetches, url) => {
+      if (fetches.length >= this.nPlus1Threshold) {
+        // N+1 detected
+        issues.push({
+          id: this.id,
+          severity: 'critical',
+          message: `Fetch "${url}" called ${fetches.length}x with no cache → likely fetch N+1 pattern`,
+          suggestion: `This endpoint is being called multiple times without caching. Add a cache directive:
+
+// Option 1: Force cache (recommended for static data)
+fetch("${url}", { cache: 'force-cache' })
+
+// Option 2: Revalidate after time (recommended for semi-dynamic data)
+fetch("${url}", { 
+  next: { revalidate: 3600 } // revalidate every hour
+})
+
+// Option 3: Use server-side data fetching instead
+// Move to a parent Server Component or Route Handler
+
+// Option 4: Use unstable_cache wrapper (experimental)
+import { unstable_cache } from 'next/cache';
+const cachedFetch = unstable_cache(
+  async () => fetch("${url}").then(r => r.json()),
+  [${JSON.stringify(url)}],
+  { revalidate: 3600 }
+);`,
+          route: context.route,
+          spanId: fetches[0]?.spanId,
+          attributes: {
+            url,
+            callCount: fetches.length,
+            totalDuration: Math.round(fetches.reduce((sum, f) => sum + f.duration, 0)),
+            avgDuration: Math.round(
+              fetches.reduce((sum, f) => sum + f.duration, 0) / fetches.length
+            ),
+          },
+          detectedAt: Date.now(),
+        });
+      } else if (fetches.length === 1) {
+        // Single slow fetch without cache
+        const fetch = fetches[0]!;
+        issues.push({
+          id: this.id,
+          severity: 'high',
+          message: `Fetch "${url}" has no cache → +${Math.round(fetch.duration)}ms per request`,
+          suggestion: `Add a cache directive to this fetch:
+
+// Option 1: Force cache (best for static APIs)
+fetch("${url}", { cache: 'force-cache' })
+
+// Option 2: Revalidate after time (better for semi-dynamic data)
+fetch("${url}", { 
+  next: { revalidate: 3600 } // revalidate every hour
+})
+
+// Option 3: Combine with other optimizations
+const data = await fetch("${url}", {
+  cache: 'force-cache',
+  headers: {
+    'User-Agent': 'NextDoctor-Agent/1.0'
+  }
+});`,
+          route: context.route,
+          spanId: fetch.spanId,
+          attributes: {
+            url,
+            duration: Math.round(fetch.duration),
+          },
+          detectedAt: Date.now(),
+        });
+      } else {
+        // 2 to nPlus1Threshold-1 calls: still suspicious
+        const totalDuration = Math.round(fetches.reduce((sum, f) => sum + f.duration, 0));
+        issues.push({
+          id: this.id,
+          severity: 'high',
+          message: `Fetch "${url}" called ${fetches.length}x with no cache → ${totalDuration}ms wasted per request`,
+          suggestion: `This endpoint is being called multiple times without caching. Consider adding a cache directive or deduplicating the request:
+
+// Option 1: Force cache
+fetch("${url}", { cache: 'force-cache' })
+
+// Option 2: Revalidate after time
+fetch("${url}", { next: { revalidate: 3600 } })`,
+          route: context.route,
+          spanId: fetches[0]?.spanId,
+          attributes: {
+            url,
+            callCount: fetches.length,
+            totalDuration,
+            avgDuration: Math.round(totalDuration / fetches.length),
+          },
+          detectedAt: Date.now(),
+        });
+      }
+    });
+
+    return issues;
+  }
+
+  private isInternalUrl(url: string): boolean {
+    try {
+      const parsed = new URL(url);
+      const hostname = parsed.hostname;
+      return (
+        hostname === 'localhost' ||
+        hostname === '127.0.0.1' ||
+        hostname === '::1' ||
+        hostname.endsWith('.local') ||
+        hostname.endsWith('.test') ||
+        hostname.startsWith('192.168.') ||
+        hostname.startsWith('10.')
+      );
+    } catch {
+      return false;
+    }
+  }
+}

package/src/detectors/index.ts

@@ -0,0 +1,127 @@
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { BaseDetector } from './base-detector.js';
+import { ColdStartThresholdDetector } from './cold-start-threshold.detector.js';
+import { FetchNoCacheDetector } from './fetch-no-cache.detector.js';
+import { DynamicRouteCandidateDetector } from './dynamic-route-candidate.detector.js';
+import type { DetectedIssue, DetectorContext, IssueDeduplicationKey, DedupedIssue } from './types.js';
+
+export class DetectionEngine {
+  private detectors: BaseDetector[];
+  private issueCache = new Map<string, DedupedIssue>();
+  private readonly dedupWindowMs = 60_000; // 60 seconds
+
+  constructor(config?: { disabledDetectors?: string[] }) {
+    const disabledSet = new Set(config?.disabledDetectors || []);
+
+    // Instantiate all detectors
+    const allDetectors: BaseDetector[] = [
+      new ColdStartThresholdDetector(),
+      new FetchNoCacheDetector(),
+      new DynamicRouteCandidateDetector(),
+    ];
+
+    this.detectors = allDetectors.filter(d => !disabledSet.has(d.id));
+  }
+
+  analyzeSpans(spans: ReadableSpan[], context: DetectorContext): DetectedIssue[] {
+    const allIssues: DetectedIssue[] = [];
+
+    // Run all detectors
+    for (const detector of this.detectors) {
+      const result = detector.run(spans, context);
+      allIssues.push(...result.issues);
+    }
+
+    // Deduplicate within the window
+    const deduped = this.deduplicateIssues(allIssues);
+
+    // Sort by severity: critical > high > warning > info
+    const severityOrder = { critical: 0, high: 1, warning: 2, info: 3 };
+    deduped.sort(
+      (a, b) => 
+        severityOrder[a.severity as keyof typeof severityOrder] -
+        severityOrder[b.severity as keyof typeof severityOrder]
+    );
+
+    return deduped;
+  }
+
+  private deduplicateIssues(issues: DetectedIssue[]): DetectedIssue[] {
+    const now = Date.now();
+    const dedupedMap = new Map<string, DedupedIssue>();
+
+    // Clean old entries from cache
+    for (const [key, cached] of this.issueCache.entries()) {
+      if (now - cached.lastDetectedAt > this.dedupWindowMs) {
+        this.issueCache.delete(key);
+      }
+    }
+
+    // Process new issues
+    for (const issue of issues) {
+      const key = this.getDeduplicationKey(issue);
+      const existingCached = this.issueCache.get(key);
+
+      if (existingCached) {
+        // Update cache
+        existingCached.lastDetectedAt = now;
+        existingCached.count++;
+        // Don't duplicate in output if already reported recently
+        continue;
+      }
+
+      // New issue - add to cache and output
+      const dedupedIssue: DedupedIssue = {
+        ...issue,
+        firstDetectedAt: now,
+        lastDetectedAt: now,
+        count: 1,
+      };
+
+      this.issueCache.set(key, dedupedIssue);
+      dedupedMap.set(key, dedupedIssue);
+    }
+
+    return Array.from(dedupedMap.values());
+  }
+
+  private getDeduplicationKey(issue: DetectedIssue): string {
+    const key: IssueDeduplicationKey = {
+      id: issue.id,
+      route: issue.route,
+    };
+    return JSON.stringify(key);
+  }
+
+  getDetectorById(id: string): BaseDetector | undefined {
+    return this.detectors.find(d => d.id === id);
+  }
+
+  listDetectors(): Array<{ id: string; name: string }> {
+    return this.detectors.map(d => ({
+      id: d.id,
+      name: d.name,
+    }));
+  }
+
+  clearCache(): void {
+    this.issueCache.clear();
+  }
+
+  getCacheSize(): number {
+    return this.issueCache.size;
+  }
+}
+
+// Singleton instance
+// MVP LIMITATION: In persistent Node.js environments (self-hosted), this cache 
+// is shared globally. Deduplication keys include 'id' and 'route', but lack 
+// project-level scope, which could cause cache collisions in multi-tenant usages.
+export const detectionEngine = new DetectionEngine();
+
+// Re-export all types and detectors for public API
+export type { DetectedIssue, DetectorContext, DetectorResult } from './types.js';
+export { BaseDetector } from './base-detector.js';
+export { ColdStartThresholdDetector } from './cold-start-threshold.detector.js';
+export { FetchNoCacheDetector } from './fetch-no-cache.detector.js';
+export { DynamicRouteCandidateDetector } from './dynamic-route-candidate.detector.js';

package/src/detectors/types.ts

@@ -0,0 +1,38 @@
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+
+export type IssueSeverity = 'info' | 'warning' | 'high' | 'critical';
+
+export interface DetectedIssue {
+  id: string;
+  severity: IssueSeverity;
+  message: string;
+  suggestion: string;
+  route?: string;
+  spanId?: string;
+  attributes?: Record<string, unknown>;
+  detectedAt: number;
+}
+
+export interface DetectorResult {
+  issues: DetectedIssue[];
+  detectorId: string;
+  analyzedSpans: number;
+  durationMs: number;
+}
+
+export interface DetectorContext {
+  route?: string;
+  runtime: 'nodejs' | 'edge';
+  startupTimeMs?: number;
+}
+
+export interface IssueDeduplicationKey {
+  id: string;
+  route?: string;
+}
+
+export interface DedupedIssue extends DetectedIssue {
+  firstDetectedAt: number;
+  lastDetectedAt: number;
+  count: number;
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+export {
+  initNextDoctor,
+  shutdownNextDoctor,
+  getNextDoctorAgent,
+  reportMetric,
+  getHealthStatus,
+  getDetectedIssues,
+  getSystemMetrics,
+  getSystemHealth,
+  getSystemSummary,
+} from './init.js';
+
+export type {
+  NextDoctorConfig,
+  DetectedIssue,
+  AgentHealth,
+  RetryPolicy,
+  ExporterConfig,
+} from './types.js';
+
+export {
+  LogLevel,
+  ExporterType,
+} from './types.js';
+
+export {
+  withNextDoctorMonitoring,
+  withNextDoctorTiming,
+} from './middleware.js';
+
+export {
+  IntelligentSampler,
+  BatchProcessor,
+  CircuitBreaker,
+} from './optimization.js';
+
+export {
+  SystemMonitor,
+  CPUMonitor,
+  MemoryMonitor,
+} from './system-monitor.js';
+
+export type {
+  CPUMetrics,
+  MemoryMetrics,
+  SystemMetrics,
+} from './system-monitor.js';
+
+export {
+  detectionEngine,
+  ColdStartThresholdDetector,
+  FetchNoCacheDetector,
+  DynamicRouteCandidateDetector,
+} from './detectors/index.js';
+
+export type {
+  DetectorContext,
+  DetectorResult,
+  IssueSeverity,
+} from './detectors/types.js';