brakit 0.8.5 → 0.8.7

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <b>AI writes your code. Brakit watches what it does.</b> <br />
-  Every request, query, and security issue, caught before you ship. <br />
+  Every request, query, and API call mapped to the action that triggered it. See your entire backend at a glance. <br />
   <b>Open source · Local first · Zero config · AI-native via MCP</b>
 </p>
 
@@ -32,6 +32,12 @@
 
 ---
 
+<p align="center">
+  <img width="700" src="docs/images/actions.png" alt="Brakit Actions — endpoints grouped by user action" />
+  <br />
+  <sub>Every endpoint grouped by the action that triggered it — see "Sign Up" and "Load Dashboard", not 47 raw requests</sub>
+</p>
+
 <p align="center">
   <img width="700" src="docs/images/dashboard.png" alt="Brakit Dashboard — issues surfaced automatically" />
   <br />
@@ -41,7 +47,7 @@
 <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>
+  <sub>Claude reads issues via MCP and fixes your code</sub>
 </p>
 
 ## Quick Start
@@ -56,7 +62,7 @@ That's it. Brakit detects your framework, adds itself as a devDependency, and cr
 npm run dev
 ```
 
-Dashboard at `http://localhost:<port>/__brakit`. Insights in the terminal.
+Dashboard at `http://localhost:<port>/__brakit`. Issues in the terminal.
 
 > **Requirements:** Node.js >= 18 and a project with `package.json`.
 
@@ -74,7 +80,7 @@ Dashboard at `http://localhost:<port>/__brakit`. Insights in the terminal.
 - **Full server tracing** — fetch calls, DB queries, console logs, errors — zero code changes
 - **Response overfetch** — large JSON responses with many fields your client doesn't use
 - **Performance tracking** — health grades and p95 trends across dev sessions
-- **AI-native via MCP** — Claude Code and Cursor can query findings, inspect endpoints, and verify fixes directly
+- **AI-native via MCP** — Claude Code and Cursor can query issues, inspect endpoints, and verify fixes directly
 
 ---
 

package/dist/api.d.ts

@@ -63,6 +63,7 @@ interface TelemetryEntry {
     timestamp: number;
 }
 interface TracedFetch extends TelemetryEntry {
+    fetchId?: string;
     url: string;
     method: string;
     statusCode: number;
@@ -75,11 +76,11 @@ interface TracedLog extends TelemetryEntry {
 interface TracedError extends TelemetryEntry {
     name: string;
     message: string;
-    stack: string;
+    stack?: string;
 }
 type NormalizedOp = "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "OTHER";
 interface TracedQuery extends TelemetryEntry {
-    driver: "pg" | "mysql2" | "prisma" | "sdk";
+    driver: "pg" | "mysql2" | "prisma" | "asyncpg" | "sqlalchemy" | "sdk";
     sql?: string;
     model?: string;
     operation?: string;
@@ -88,6 +89,7 @@ interface TracedQuery extends TelemetryEntry {
     normalizedOp?: NormalizedOp;
     table?: string;
     source?: string;
+    parentFetchId?: string;
 }
 type TelemetryEvent = {
     type: "fetch";
@@ -160,117 +162,81 @@ interface SecurityFinding {
     count: number;
 }
 
-declare const FINDINGS_DATA_VERSION = 1;
-
-type FindingState = "open" | "fixing" | "resolved";
-type FindingSource = "passive";
+type IssueState = "open" | "fixing" | "resolved" | "stale" | "regressed";
+type IssueSource = "passive";
+type IssueCategory = "security" | "performance" | "reliability";
 type AiFixStatus = "fixed" | "wont_fix";
-interface StatefulFinding {
-    /** Stable ID derived from rule + endpoint + description hash */
-    findingId: string;
-    state: FindingState;
-    source: FindingSource;
-    finding: SecurityFinding;
-    firstSeenAt: number;
-    lastSeenAt: number;
-    resolvedAt: number | null;
-    occurrences: number;
-    /** What AI reported after attempting a fix */
-    aiStatus: AiFixStatus | null;
-    /** AI's summary of what was done or why it can't be fixed */
-    aiNotes: string | null;
-}
-interface FindingsData {
-    version: typeof FINDINGS_DATA_VERSION;
-    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;
+interface Issue {
+    category: IssueCategory;
+    /** Rule identifier: "slow", "n1", "exposed-secret", etc. */
+    rule: string;
+    severity: Severity;
     title: string;
     desc: string;
     hint: string;
     detail?: string;
+    /** Explicit endpoint key (e.g., "GET /api/users"). */
+    endpoint?: string;
+    /** Dashboard tab to link to (e.g., "requests", "queries", "security"). */
     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 = FindingState;
-interface StatefulInsight {
-    key: string;
-    state: InsightState;
-    insight: Insight;
+interface StatefulIssue {
+    /** Stable ID derived from rule + endpoint + description hash. */
+    issueId: string;
+    state: IssueState;
+    source: IssueSource;
+    category: IssueCategory;
+    issue: Issue;
     firstSeenAt: number;
     lastSeenAt: number;
     resolvedAt: number | null;
-    /** Consecutive recompute cycles where the insight was not detected. */
-    consecutiveAbsences: number;
+    occurrences: number;
+    /**
+     * Number of requests to this endpoint that did NOT reproduce the issue
+     * since it was last seen. Used for evidence-based resolution.
+     */
+    cleanHitsSinceLastSeen: number;
+    /** What AI reported after attempting a fix. */
     aiStatus: AiFixStatus | null;
+    /** AI's summary of what was done or why it can't be fixed. */
     aiNotes: string | null;
 }
+interface IssuesData {
+    version: 2;
+    issues: StatefulIssue[];
+}
 
-declare class FindingStore {
-    private rootDir;
-    private findings;
+declare class IssueStore {
+    private dataDir;
+    private issues;
     private flushTimer;
     private dirty;
     private readonly writer;
-    private readonly findingsPath;
-    constructor(rootDir: string);
+    private readonly issuesPath;
+    constructor(dataDir: string);
     start(): void;
     stop(): void;
-    upsert(finding: SecurityFinding, source: FindingSource): StatefulFinding;
-    transition(findingId: string, state: FindingState): boolean;
-    reportFix(findingId: string, status: AiFixStatus, notes: string): boolean;
+    upsert(issue: Issue, source: IssueSource): StatefulIssue;
     /**
-     * Reconcile passive findings against the current analysis results.
+     * Reconcile issues against the current analysis results using evidence-based resolution.
      *
-     * Passive findings are detected by continuous scanning (not user-triggered).
-     * When a previously-seen finding is absent from the current results, it means
-     * the issue has been fixed — transition it to "resolved" automatically.
-     * Active findings (from MCP verify-fix) are not auto-resolved because they
-     * require explicit verification.
+     * @param currentIssueIds - IDs of issues detected in the current analysis cycle
+     * @param activeEndpoints - Endpoints that had requests in the current cycle
      */
-    reconcilePassive(currentFindings: readonly SecurityFinding[]): void;
-    getAll(): readonly StatefulFinding[];
-    getByState(state: FindingState): readonly StatefulFinding[];
-    get(findingId: string): StatefulFinding | undefined;
+    reconcile(currentIssueIds: Set<string>, activeEndpoints: Set<string>): void;
+    transition(issueId: string, state: IssueState): boolean;
+    reportFix(issueId: string, status: AiFixStatus, notes: string): boolean;
+    getAll(): readonly StatefulIssue[];
+    getByState(state: IssueState): readonly StatefulIssue[];
+    getByCategory(category: IssueCategory): readonly StatefulIssue[];
+    get(issueId: string): StatefulIssue | undefined;
     clear(): void;
+    isDirty(): boolean;
     private loadAsync;
     /** Sync load for tests only — not used in production paths. */
     loadSync(): void;
+    /** Parse and populate issues from a raw JSON string. */
+    private hydrate;
     private flush;
     private flushSync;
     private serialize;
@@ -283,9 +249,15 @@ interface BrakitAdapter {
     unpatch?(): void;
 }
 
+/** Pre-parsed JSON bodies keyed by request ID, built once per scan cycle. */
+interface ParsedBodyCache {
+    response: Map<string, unknown>;
+    request: Map<string, unknown>;
+}
 interface SecurityContext {
     requests: readonly TracedRequest[];
     logs: readonly TracedLog[];
+    parsedBodies: ParsedBodyCache;
 }
 interface SecurityRule {
     id: string;
@@ -298,11 +270,56 @@ interface SecurityRule {
 declare class SecurityScanner {
     private rules;
     register(rule: SecurityRule): void;
-    scan(ctx: SecurityContext): SecurityFinding[];
+    scan(input: {
+        requests: readonly TracedRequest[];
+        logs: readonly TracedLog[];
+    }): SecurityFinding[];
     getRules(): readonly SecurityRule[];
 }
 declare function createDefaultScanner(): SecurityScanner;
 
+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>;
+}
+
 interface InsightRule {
     id: InsightType;
     check(ctx: PreparedInsightContext): Insight[];
@@ -331,8 +348,7 @@ declare class AdapterRegistry {
 interface AnalysisUpdate {
     insights: readonly Insight[];
     findings: readonly SecurityFinding[];
-    statefulFindings: readonly StatefulFinding[];
-    statefulInsights: readonly StatefulInsight[];
+    issues: readonly StatefulIssue[];
 }
 interface ChannelMap {
     "telemetry:fetch": Omit<TracedFetch, "id">;
@@ -341,7 +357,7 @@ interface ChannelMap {
     "telemetry:error": Omit<TracedError, "id">;
     "request:completed": TracedRequest;
     "analysis:updated": AnalysisUpdate;
-    "findings:changed": readonly StatefulFinding[];
+    "issues:changed": readonly StatefulIssue[];
     "store:cleared": undefined;
 }
 type Listener<T> = (data: T) => void;
@@ -367,6 +383,10 @@ interface CaptureInput {
     config: Pick<BrakitConfig, "maxBodyCapture">;
 }
 
+interface Lifecycle {
+    start(): void;
+    stop(): void;
+}
 interface TelemetryStoreInterface<T extends TelemetryEntry> {
     add(data: Omit<T, "id">): T;
     getAll(): readonly T[];
@@ -379,36 +399,28 @@ interface RequestStoreInterface {
     getAll(): readonly TracedRequest[];
     clear(): void;
 }
-interface MetricsStoreInterface {
+interface MetricsStoreInterface extends Lifecycle {
     recordRequest(req: TracedRequest, metrics: RequestMetrics): void;
     getAll(): readonly EndpointMetrics[];
     getEndpoint(endpoint: string): EndpointMetrics | undefined;
     getLiveEndpoints(): LiveEndpointData[];
     reset(): void;
-    start(): void;
-    stop(): void;
 }
-interface FindingStoreInterface {
-    upsert(finding: SecurityFinding, source: FindingSource): StatefulFinding;
-    transition(findingId: string, state: FindingState): boolean;
-    reportFix(findingId: string, status: AiFixStatus, notes: string): boolean;
-    reconcilePassive(findings: readonly SecurityFinding[]): void;
-    getAll(): readonly StatefulFinding[];
-    getByState(state: FindingState): readonly StatefulFinding[];
-    get(findingId: string): StatefulFinding | undefined;
+interface IssueStoreInterface extends Lifecycle {
+    upsert(issue: Issue, source: IssueSource): StatefulIssue;
+    transition(issueId: string, state: IssueState): boolean;
+    reportFix(issueId: string, status: AiFixStatus, notes: string): boolean;
+    reconcile(currentIssueIds: Set<string>, activeEndpoints: Set<string>): void;
+    getAll(): readonly StatefulIssue[];
+    getByState(state: IssueState): readonly StatefulIssue[];
+    getByCategory(category: IssueCategory): readonly StatefulIssue[];
+    get(issueId: string): StatefulIssue | undefined;
     clear(): void;
-    start(): void;
-    stop(): void;
 }
-interface AnalysisEngineInterface {
-    start(): void;
-    stop(): void;
+interface AnalysisEngineInterface extends Lifecycle {
     recompute(): void;
     getInsights(): readonly Insight[];
     getFindings(): readonly SecurityFinding[];
-    getStatefulInsights(): readonly StatefulInsight[];
-    getStatefulFindings(): readonly StatefulFinding[];
-    reportInsightFix(enrichedId: string, status: AiFixStatus, notes: string): boolean;
 }
 
 interface ServiceMap {
@@ -419,7 +431,7 @@ interface ServiceMap {
     "log-store": TelemetryStoreInterface<TracedLog>;
     "error-store": TelemetryStoreInterface<TracedError>;
     "metrics-store": MetricsStoreInterface;
-    "finding-store": FindingStoreInterface;
+    "issue-store": IssueStoreInterface;
     "analysis-engine": AnalysisEngineInterface;
 }
 declare class ServiceRegistry {
@@ -433,10 +445,8 @@ declare class AnalysisEngine {
     private registry;
     private debounceMs;
     private scanner;
-    private insightTracker;
     private cachedInsights;
     private cachedFindings;
-    private cachedStatefulInsights;
     private debounceTimer;
     private subs;
     constructor(registry: ServiceRegistry, debounceMs?: number);
@@ -444,13 +454,10 @@ declare class AnalysisEngine {
     stop(): void;
     getInsights(): readonly Insight[];
     getFindings(): readonly SecurityFinding[];
-    getStatefulFindings(): readonly StatefulFinding[];
-    getStatefulInsights(): readonly StatefulInsight[];
-    reportInsightFix(enrichedId: string, status: AiFixStatus, notes: string): boolean;
     private scheduleRecompute;
     recompute(): void;
 }
 
 declare const VERSION: string;
 
-export { AdapterRegistry, AnalysisEngine, type BrakitAdapter, type BrakitConfig, type DetectedProject, type FindingSource, type FindingState, FindingStore, type FindingsData, type FlatHeaders, type Framework, type HttpMethod, type Insight, type InsightContext, type InsightRule, InsightRunner, type NormalizedOp, type RequestCategory, type RequestListener, type SecurityContext, type SecurityFinding, type SecurityRule, SecurityScanner, type SecuritySeverity, type StatefulFinding, type TracedRequest, VERSION, computeInsights, createDefaultInsightRunner, createDefaultScanner, detectProject };
+export { AdapterRegistry, AnalysisEngine, type BrakitAdapter, type BrakitConfig, type DetectedProject, type FlatHeaders, type Framework, type HttpMethod, type Insight, type InsightContext, type InsightRule, InsightRunner, type IssueCategory, type IssueSource, type IssueState, IssueStore, type IssuesData, type NormalizedOp, type RequestCategory, type RequestListener, type SecurityContext, type SecurityFinding, type SecurityRule, SecurityScanner, type SecuritySeverity, type StatefulIssue, type TracedRequest, VERSION, computeInsights, createDefaultInsightRunner, createDefaultScanner, detectProject };