brakit 0.8.0 → 0.8.1

package/README.md

@@ -22,6 +22,9 @@
   <a href="https://typescriptlang.org">
     <img src="https://img.shields.io/badge/built%20with-TypeScript-3178c6.svg" alt="TypeScript" />
   </a>
+  <a href="https://www.npmjs.com/package/brakit">
+    <img src="https://img.shields.io/npm/v/brakit" alt="npm version" />
+  </a>
   <a href="CONTRIBUTING.md">
     <img src="https://img.shields.io/badge/PRs-Welcome-brightgreen" alt="PRs welcome!" />
   </a>
@@ -30,7 +33,15 @@
 ---
 
 <p align="center">
-  <img width="700" src="docs/images/dashboard.png" alt="Brakit Dashboard" />
+  <img width="700" src="docs/images/dashboard.png" alt="Brakit Dashboard — issues surfaced automatically" />
+  <br />
+  <sub>Brakit catches N+1 queries, PII leaks, and slow endpoints as you develop</sub>
+</p>
+
+<p align="center">
+  <img width="700" src="docs/images/vscode.png" alt="Claude reading Brakit findings in VS Code" />
+  <br />
+  <sub>Claude reads findings via MCP and fixes your code</sub>
 </p>
 
 ## Quick Start

package/dist/api.d.ts

@@ -149,7 +149,9 @@ interface RequestMetrics {
     fetchTimeMs: number;
 }
 
-type SecuritySeverity = "critical" | "warning" | "info";
+/** Shared severity levels used by both security findings and insights. */
+type Severity = "critical" | "warning" | "info";
+type SecuritySeverity = Severity;
 interface SecurityFinding {
     severity: SecuritySeverity;
     rule: string;
@@ -178,6 +180,60 @@ interface FindingsData {
     findings: StatefulFinding[];
 }
 
+type InsightSeverity = Severity;
+type InsightType = "n1" | "cross-endpoint" | "redundant-query" | "error" | "error-hotspot" | "duplicate" | "slow" | "query-heavy" | "select-star" | "high-rows" | "large-response" | "response-overfetch" | "security" | "regression";
+interface Insight {
+    severity: InsightSeverity;
+    type: InsightType;
+    title: string;
+    desc: string;
+    hint: string;
+    detail?: string;
+    nav?: string;
+}
+interface InsightContext {
+    requests: readonly TracedRequest[];
+    queries: readonly TracedQuery[];
+    errors: readonly TracedError[];
+    flows: readonly RequestFlow[];
+    fetches: readonly TracedFetch[];
+    previousMetrics?: readonly EndpointMetrics[];
+    securityFindings?: readonly SecurityFinding[];
+}
+interface EndpointGroup {
+    total: number;
+    errors: number;
+    totalDuration: number;
+    queryCount: number;
+    totalSize: number;
+    totalQueryTimeMs: number;
+    totalFetchTimeMs: number;
+    queryShapeDurations: Map<string, {
+        totalMs: number;
+        count: number;
+        label: string;
+    }>;
+}
+interface PreparedInsightContext extends InsightContext {
+    nonStatic: readonly TracedRequest[];
+    queriesByReq: ReadonlyMap<string, TracedQuery[]>;
+    fetchesByReq: ReadonlyMap<string, TracedFetch[]>;
+    reqById: ReadonlyMap<string, TracedRequest>;
+    endpointGroups: ReadonlyMap<string, EndpointGroup>;
+}
+
+type InsightState = "open" | "resolved";
+interface StatefulInsight {
+    key: string;
+    state: InsightState;
+    insight: Insight;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    resolvedAt: number | null;
+    /** Consecutive recompute cycles where the insight was not detected. */
+    consecutiveAbsences: number;
+}
+
 declare class FindingStore {
     private rootDir;
     private findings;
@@ -231,48 +287,6 @@ declare class SecurityScanner {
 }
 declare function createDefaultScanner(): SecurityScanner;
 
-type InsightSeverity = "critical" | "warning" | "info";
-type InsightType = "n1" | "cross-endpoint" | "redundant-query" | "error" | "error-hotspot" | "duplicate" | "slow" | "query-heavy" | "select-star" | "high-rows" | "large-response" | "response-overfetch" | "security" | "regression";
-interface Insight {
-    severity: InsightSeverity;
-    type: InsightType;
-    title: string;
-    desc: string;
-    hint: string;
-    detail?: string;
-    nav?: string;
-}
-interface InsightContext {
-    requests: readonly TracedRequest[];
-    queries: readonly TracedQuery[];
-    errors: readonly TracedError[];
-    flows: readonly RequestFlow[];
-    fetches: readonly TracedFetch[];
-    previousMetrics?: readonly EndpointMetrics[];
-    securityFindings?: readonly SecurityFinding[];
-}
-interface EndpointGroup {
-    total: number;
-    errors: number;
-    totalDuration: number;
-    queryCount: number;
-    totalSize: number;
-    totalQueryTimeMs: number;
-    totalFetchTimeMs: number;
-    queryShapeDurations: Map<string, {
-        totalMs: number;
-        count: number;
-        label: string;
-    }>;
-}
-interface PreparedInsightContext extends InsightContext {
-    nonStatic: readonly TracedRequest[];
-    queriesByReq: ReadonlyMap<string, TracedQuery[]>;
-    fetchesByReq: ReadonlyMap<string, TracedFetch[]>;
-    reqById: ReadonlyMap<string, TracedRequest>;
-    endpointGroups: ReadonlyMap<string, EndpointGroup>;
-}
-
 interface InsightRule {
     id: InsightType;
     check(ctx: PreparedInsightContext): Insight[];
@@ -326,14 +340,22 @@ declare class MetricsStore {
     private getOrCreateEndpoint;
 }
 
-type AnalysisListener = (insights: Insight[], findings: SecurityFinding[]) => void;
+interface AnalysisUpdate {
+    insights: Insight[];
+    findings: SecurityFinding[];
+    statefulFindings: readonly StatefulFinding[];
+    statefulInsights: readonly StatefulInsight[];
+}
+type AnalysisListener = (update: AnalysisUpdate) => void;
 declare class AnalysisEngine {
     private metricsStore;
     private findingStore?;
     private debounceMs;
     private scanner;
+    private insightTracker;
     private cachedInsights;
     private cachedFindings;
+    private cachedStatefulInsights;
     private debounceTimer;
     private listeners;
     private boundRequestListener;
@@ -347,6 +369,8 @@ declare class AnalysisEngine {
     offUpdate(fn: AnalysisListener): void;
     getInsights(): readonly Insight[];
     getFindings(): readonly SecurityFinding[];
+    getStatefulFindings(): readonly StatefulFinding[];
+    getStatefulInsights(): readonly StatefulInsight[];
     private scheduleRecompute;
     recompute(): void;
 }

package/dist/api.js

@@ -15,6 +15,7 @@ var DASHBOARD_PREFIX = "/__brakit";
 // src/constants/limits.ts
 var MAX_REQUEST_ENTRIES = 1e3;
 var MAX_TELEMETRY_ENTRIES = 1e3;
+var MAX_INGEST_BYTES = 10 * 1024 * 1024;
 
 // src/constants/thresholds.ts
 var FLOW_GAP_MS = 5e3;
@@ -43,6 +44,9 @@ var QUERY_COUNT_REGRESSION_RATIO = 1.5;
 var OVERFETCH_MANY_FIELDS = 12;
 var OVERFETCH_UNWRAP_MIN_SIZE = 3;
 var MAX_DUPLICATE_INSIGHTS = 3;
+var INSIGHT_WINDOW_PER_ENDPOINT = 2;
+var RESOLVE_AFTER_ABSENCES = 3;
+var RESOLVED_INSIGHT_TTL_MS = 18e5;
 
 // src/constants/metrics.ts
 var METRICS_DIR = ".brakit";
@@ -970,6 +974,10 @@ import { randomUUID as randomUUID2 } from "crypto";
 function getEndpointKey(method, path) {
   return `${method} ${path}`;
 }
+var ENDPOINT_PREFIX_RE = /^(\S+\s+\S+)/;
+function extractEndpointFromDesc(desc) {
+  return desc.match(ENDPOINT_PREFIX_RE)?.[1] ?? null;
+}
 
 // src/store/metrics/persistence.ts
 import {
@@ -1410,6 +1418,23 @@ function createEndpointGroup() {
     queryShapeDurations: /* @__PURE__ */ new Map()
   };
 }
+function windowByEndpoint(requests) {
+  const byEndpoint = /* @__PURE__ */ new Map();
+  for (const r of requests) {
+    const ep = getEndpointKey(r.method, r.path);
+    let list = byEndpoint.get(ep);
+    if (!list) {
+      list = [];
+      byEndpoint.set(ep, list);
+    }
+    list.push(r);
+  }
+  const windowed = [];
+  for (const [, reqs] of byEndpoint) {
+    windowed.push(...reqs.slice(-INSIGHT_WINDOW_PER_ENDPOINT));
+  }
+  return windowed;
+}
 function prepareContext(ctx) {
   const nonStatic = ctx.requests.filter(
     (r) => !r.isStatic && (!r.path || !r.path.startsWith(DASHBOARD_PREFIX))
@@ -1417,8 +1442,9 @@ function prepareContext(ctx) {
   const queriesByReq = groupBy(ctx.queries, (q) => q.parentRequestId);
   const fetchesByReq = groupBy(ctx.fetches, (f) => f.parentRequestId);
   const reqById = new Map(nonStatic.map((r) => [r.id, r]));
+  const recent = windowByEndpoint(nonStatic);
   const endpointGroups = /* @__PURE__ */ new Map();
-  for (const r of nonStatic) {
+  for (const r of recent) {
     const ep = getEndpointKey(r.method, r.path);
     let g = endpointGroups.get(ep);
     if (!g) {
@@ -1990,6 +2016,61 @@ function computeInsights(ctx) {
   return createDefaultInsightRunner().run(ctx);
 }
 
+// src/analysis/insight-tracker.ts
+function computeInsightKey(insight) {
+  const identifier = extractEndpointFromDesc(insight.desc) ?? insight.title;
+  return `${insight.type}:${identifier}`;
+}
+var InsightTracker = class {
+  tracked = /* @__PURE__ */ new Map();
+  reconcile(current) {
+    const currentKeys = /* @__PURE__ */ new Set();
+    const now = Date.now();
+    for (const insight of current) {
+      const key = computeInsightKey(insight);
+      currentKeys.add(key);
+      const existing = this.tracked.get(key);
+      if (existing) {
+        existing.insight = insight;
+        existing.lastSeenAt = now;
+        existing.consecutiveAbsences = 0;
+        if (existing.state === "resolved") {
+          existing.state = "open";
+          existing.resolvedAt = null;
+        }
+      } else {
+        this.tracked.set(key, {
+          key,
+          state: "open",
+          insight,
+          firstSeenAt: now,
+          lastSeenAt: now,
+          resolvedAt: null,
+          consecutiveAbsences: 0
+        });
+      }
+    }
+    for (const [key, stateful] of this.tracked) {
+      if (stateful.state === "open" && !currentKeys.has(stateful.key)) {
+        stateful.consecutiveAbsences++;
+        if (stateful.consecutiveAbsences >= RESOLVE_AFTER_ABSENCES) {
+          stateful.state = "resolved";
+          stateful.resolvedAt = now;
+        }
+      } else if (stateful.state === "resolved" && stateful.resolvedAt !== null && now - stateful.resolvedAt > RESOLVED_INSIGHT_TTL_MS) {
+        this.tracked.delete(key);
+      }
+    }
+    return [...this.tracked.values()];
+  }
+  getAll() {
+    return [...this.tracked.values()];
+  }
+  clear() {
+    this.tracked.clear();
+  }
+};
+
 // src/analysis/engine.ts
 var AnalysisEngine = class {
   constructor(metricsStore, findingStore, debounceMs = 300) {
@@ -2003,8 +2084,10 @@ var AnalysisEngine = class {
     this.boundLogListener = () => this.scheduleRecompute();
   }
   scanner;
+  insightTracker = new InsightTracker();
   cachedInsights = [];
   cachedFindings = [];
+  cachedStatefulInsights = [];
   debounceTimer = null;
   listeners = [];
   boundRequestListener;
@@ -2040,6 +2123,12 @@ var AnalysisEngine = class {
   getFindings() {
     return this.cachedFindings;
   }
+  getStatefulFindings() {
+    return this.findingStore?.getAll() ?? [];
+  }
+  getStatefulInsights() {
+    return this.cachedStatefulInsights;
+  }
   scheduleRecompute() {
     if (this.debounceTimer) return;
     this.debounceTimer = setTimeout(() => {
@@ -2070,9 +2159,16 @@ var AnalysisEngine = class {
       previousMetrics: this.metricsStore.getAll(),
       securityFindings: this.cachedFindings
     });
+    this.cachedStatefulInsights = this.insightTracker.reconcile(this.cachedInsights);
+    const update = {
+      insights: this.cachedInsights,
+      findings: this.cachedFindings,
+      statefulFindings: this.getStatefulFindings(),
+      statefulInsights: this.cachedStatefulInsights
+    };
     for (const fn of this.listeners) {
       try {
-        fn(this.cachedInsights, this.cachedFindings);
+        fn(update);
       } catch {
       }
     }
@@ -2080,7 +2176,7 @@ var AnalysisEngine = class {
 };
 
 // src/index.ts
-var VERSION = "0.8.0";
+var VERSION = "0.8.1";
 export {
   AdapterRegistry,
   AnalysisEngine,

package/dist/bin/brakit.js

@@ -28,12 +28,13 @@ var init_routes = __esm({
 });
 
 // src/constants/limits.ts
-var MAX_REQUEST_ENTRIES, MAX_TELEMETRY_ENTRIES;
+var MAX_REQUEST_ENTRIES, MAX_TELEMETRY_ENTRIES, MAX_INGEST_BYTES;
 var init_limits = __esm({
   "src/constants/limits.ts"() {
     "use strict";
     MAX_REQUEST_ENTRIES = 1e3;
     MAX_TELEMETRY_ENTRIES = 1e3;
+    MAX_INGEST_BYTES = 10 * 1024 * 1024;
   }
 });
 
@@ -83,7 +84,7 @@ var init_mcp = __esm({
   "src/constants/mcp.ts"() {
     "use strict";
     MCP_SERVER_NAME = "brakit";
-    MCP_SERVER_VERSION = "0.8.0";
+    MCP_SERVER_VERSION = "0.8.1";
     INITIAL_DISCOVERY_TIMEOUT_MS = 5e3;
     LAZY_DISCOVERY_TIMEOUT_MS = 2e3;
     CLIENT_FETCH_TIMEOUT_MS = 1e4;
@@ -300,7 +301,9 @@ async function enrichFindings(client) {
       context
     });
   }
-  for (const i of insightsData.insights) {
+  for (const si of insightsData.insights) {
+    if (si.state === "resolved") continue;
+    const i = si.insight;
     if (!ENRICHMENT_SEVERITY_FILTER.includes(i.severity)) continue;
     const endpoint = i.nav ?? "global";
     enriched.push({
@@ -690,13 +693,14 @@ var init_get_report = __esm({
           (s, ep) => s + ep.summary.totalRequests,
           0
         );
+        const openInsightCount = insightsData.insights.filter((si) => si.state === "open").length;
         const lines = [
           "=== Brakit Report ===",
           "",
           `Endpoints observed: ${metricsData.endpoints.length}`,
           `Total requests captured: ${totalRequests}`,
           `Active security rules: ${securityData.findings.length} finding(s)`,
-          `Performance insights: ${insightsData.insights.length} insight(s)`,
+          `Performance insights: ${openInsightCount} open, ${insightsData.insights.length - openInsightCount} resolved`,
           "",
           "--- Finding Summary ---",
           `Total: ${findings.length}`,
@@ -1642,6 +1646,7 @@ init_constants();
 // src/analysis/insights/prepare.ts
 init_endpoint();
 init_constants();
+init_thresholds();
 
 // src/analysis/insights/rules/n1.ts
 init_endpoint();
@@ -1683,8 +1688,12 @@ init_thresholds();
 // src/analysis/insights/rules/regression.ts
 init_thresholds();
 
+// src/analysis/insight-tracker.ts
+init_endpoint();
+init_thresholds();
+
 // src/index.ts
-var VERSION = "0.8.0";
+var VERSION = "0.8.1";
 
 // src/cli/commands/install.ts
 var IMPORT_LINE = `import "brakit";`;

package/dist/mcp/server.js

@@ -22,7 +22,7 @@ var DASHBOARD_API_FINDINGS = "/__brakit/api/findings";
 
 // src/constants/mcp.ts
 var MCP_SERVER_NAME = "brakit";
-var MCP_SERVER_VERSION = "0.8.0";
+var MCP_SERVER_VERSION = "0.8.1";
 var INITIAL_DISCOVERY_TIMEOUT_MS = 5e3;
 var LAZY_DISCOVERY_TIMEOUT_MS = 2e3;
 var CLIENT_FETCH_TIMEOUT_MS = 1e4;
@@ -110,6 +110,9 @@ var BrakitClient = class {
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
 
+// src/constants/limits.ts
+var MAX_INGEST_BYTES = 10 * 1024 * 1024;
+
 // src/constants/metrics.ts
 var PORT_FILE = ".brakit/port";
 
@@ -204,7 +207,9 @@ async function enrichFindings(client) {
       context
     });
   }
-  for (const i of insightsData.insights) {
+  for (const si of insightsData.insights) {
+    if (si.state === "resolved") continue;
+    const i = si.insight;
     if (!ENRICHMENT_SEVERITY_FILTER.includes(i.severity)) continue;
     const endpoint = i.nav ?? "global";
     enriched.push({
@@ -553,13 +558,14 @@ var getReport = {
       (s, ep) => s + ep.summary.totalRequests,
       0
     );
+    const openInsightCount = insightsData.insights.filter((si) => si.state === "open").length;
     const lines = [
       "=== Brakit Report ===",
       "",
       `Endpoints observed: ${metricsData.endpoints.length}`,
       `Total requests captured: ${totalRequests}`,
       `Active security rules: ${securityData.findings.length} finding(s)`,
-      `Performance insights: ${insightsData.insights.length} insight(s)`,
+      `Performance insights: ${openInsightCount} open, ${insightsData.insights.length - openInsightCount} resolved`,
       "",
       "--- Finding Summary ---",
       `Total: ${findings.length}`,