brainblast 0.2.0 → 0.4.0

package/dist/cli.js

@@ -1,28 +1,142 @@
 #!/usr/bin/env node
 import {
+  analyzeCosts,
   audit,
+  buildTrustGraph,
+  cacheSize,
+  defaultCachePath,
+  isValidSolanaAddress,
+  loadProgramCache,
+  renderCostReportMd,
+  renderTrustGraphMd,
   resolveRules
-} from "./chunk-H2Y75CSH.js";
+} from "./chunk-WVHGN2HR.js";
 
 // src/cli.ts
-import { writeFileSync, mkdirSync } from "fs";
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/memory.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
+var EMPTY_MEMORY = { schemaVersion: "1.0", lastRun: [], fixHistory: [] };
+function memoryPath(targetDir2) {
+  return join(targetDir2, ".agent-research", "memory.json");
+}
+function loadMemory(targetDir2) {
+  const p = memoryPath(targetDir2);
+  if (!existsSync(p)) return { ...EMPTY_MEMORY, lastRun: [], fixHistory: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(p, "utf8"));
+    return {
+      schemaVersion: parsed.schemaVersion ?? "1.0",
+      lastRun: Array.isArray(parsed.lastRun) ? parsed.lastRun : [],
+      fixHistory: Array.isArray(parsed.fixHistory) ? parsed.fixHistory : []
+    };
+  } catch {
+    return { ...EMPTY_MEMORY, lastRun: [], fixHistory: [] };
+  }
+}
+function saveMemory(targetDir2, memory2) {
+  mkdirSync(join(targetDir2, ".agent-research"), { recursive: true });
+  writeFileSync(memoryPath(targetDir2), JSON.stringify(memory2, null, 2));
+}
+var snapshotKey = (e) => `${e.ruleId}::${e.file}::${e.exportName}`;
+function precedentKey(c) {
+  return `${c.ruleId}::${c.file}`;
+}
+function updateMemory(memory2, checks2, now = /* @__PURE__ */ new Date()) {
+  const prevByKey = new Map(memory2.lastRun.map((e) => [snapshotKey(e), e]));
+  const fixedAt = now.toISOString().slice(0, 10);
+  const newFixEvents = [];
+  for (const c of checks2) {
+    const prev = prevByKey.get(snapshotKey(c));
+    if (prev?.result === "fail" && c.result !== "fail") {
+      newFixEvents.push({
+        ruleId: c.ruleId,
+        file: c.file,
+        exportName: c.exportName,
+        fixedAt,
+        detail: prev.detail
+      });
+    }
+  }
+  const fixHistory = [...memory2.fixHistory, ...newFixEvents];
+  const precedents2 = /* @__PURE__ */ new Map();
+  for (const c of checks2) {
+    if (c.result !== "fail") continue;
+    const pk = precedentKey(c);
+    if (precedents2.has(pk)) continue;
+    const matches = fixHistory.filter((e) => e.ruleId === c.ruleId && e.file !== c.file).sort((a, b) => a.fixedAt < b.fixedAt ? 1 : a.fixedAt > b.fixedAt ? -1 : 0);
+    if (matches[0]) {
+      precedents2.set(pk, {
+        file: matches[0].file,
+        exportName: matches[0].exportName,
+        fixedAt: matches[0].fixedAt,
+        detail: matches[0].detail
+      });
+    }
+  }
+  const lastRun = checks2.map((c) => ({
+    ruleId: c.ruleId,
+    file: c.file,
+    exportName: c.exportName,
+    result: c.result,
+    detail: c.detail
+  }));
+  return { memory: { schemaVersion: "1.0", lastRun, fixHistory }, precedents: precedents2 };
+}
+
+// src/cli.ts
 var args = process.argv.slice(2);
+if (args[0] === "trust-graph") {
+  await runTrustGraph(args.slice(1));
+  process.exit(0);
+}
 var ci = args.includes("--ci");
 var strict = args.includes("--strict");
 var targetDir = args.find((a) => !a.startsWith("--")) ?? process.cwd();
 var rules = resolveRules(targetDir);
 var { checks, report } = audit(targetDir, rules);
-var outDir = join(targetDir, ".agent-research");
-mkdirSync(outDir, { recursive: true });
-var reportPath = join(outDir, "report.json");
-writeFileSync(reportPath, JSON.stringify(report, null, 2));
+var memory = loadMemory(targetDir);
+var { memory: nextMemory, precedents } = updateMemory(memory, checks);
+for (const c of checks) {
+  const p = precedents.get(precedentKey(c));
+  if (p) c.precedent = p;
+}
+for (const rc of report.checks) {
+  const p = precedents.get(precedentKey(rc));
+  if (p) rc.precedent = p;
+}
+saveMemory(targetDir, nextMemory);
+var costReport = analyzeCosts(targetDir);
+report.costAnalysis = costReport;
+var outDir = join2(targetDir, ".agent-research");
+mkdirSync2(outDir, { recursive: true });
+var reportPath = join2(outDir, "report.json");
+writeFileSync2(reportPath, JSON.stringify(report, null, 2));
+var costMdPath = join2(outDir, "cost-analysis.md");
+writeFileSync2(costMdPath, renderCostReportMd(costReport));
 console.log(`brainblast: scanned ${targetDir} with ${rules.length} rule(s)`);
 if (checks.length === 0) console.log("  (no catastrophic components detected)");
 for (const c of checks) {
   const tag = c.result === "pass" ? "PASS " : c.result === "fail" ? "FAIL " : "WARN ";
   console.log(`  [${tag}] ${c.ruleId}  ${c.file}:${c.line}`);
   console.log(`          ${c.detail}`);
+  if (c.precedent) {
+    console.log(
+      `          memory: same issue (${c.ruleId}) was fixed in ${c.precedent.file} on ${c.precedent.fixedAt}`
+    );
+  }
+  if (c.fix) {
+    console.log(`          fix: ${c.fix.summary}`);
+    if (c.fix.diff) {
+      for (const line of c.fix.diff.split("\n")) console.log(`            ${line}`);
+    }
+    if (c.fix.suggestion) {
+      for (const line of c.fix.suggestion.split("\n")) console.log(`            ${line}`);
+    }
+  }
 }
 var fails = checks.filter((c) => c.result === "fail").length;
 var cantTell = checks.filter((c) => c.result === "cant_tell").length;
@@ -30,8 +144,58 @@ console.log(`  verdict: ${report.summary.verdict}  (fail=${fails}, cant_tell=${c
 if (cantTell > 0 && !strict) {
   console.log(`  warning: ${cantTell} cant_tell (not gating \u2014 pass --strict to fail on these)`);
 }
-console.log(`  report:  ${reportPath}`);
+console.log("\n\u2500\u2500 Cost & Rent \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+if (!costReport.priorityFee.found) {
+  console.log("  [HIGH ] priority fee not configured \u2014 add setComputeUnitPrice to critical paths");
+}
+if (costReport.accountFlows.length === 0) {
+  console.log("  (no account-creation flows from tracked modules detected)");
+} else {
+  for (const f of costReport.accountFlows) {
+    const file = f.file.split("/").slice(-2).join("/");
+    const scaleMark = f.scalable ? " [SCALABLE]" : "";
+    console.log(`  ${f.accountType}${scaleMark}  ${file}:${f.line}  +${f.lamports.toLocaleString()} lamports (${f.sol} SOL)`);
+  }
+  if (costReport.totalLockupLamports > 0) {
+    console.log(`  \u2500\u2500\u2500 static lockup total: ${costReport.totalLockupLamports.toLocaleString()} lamports (~${costReport.totalLockupSol} SOL)`);
+  }
+}
+console.log(`  cost report: ${costMdPath}`);
+console.log(`  report:      ${reportPath}`);
 if (ci) {
   const gateFail = fails > 0 || strict && cantTell > 0;
   process.exit(gateFail ? 1 : 0);
 }
+async function runTrustGraph(argv) {
+  const rpcIdx = argv.indexOf("--rpc");
+  const rpcUrl = rpcIdx >= 0 ? argv[rpcIdx + 1] : void 0;
+  const noProbe = argv.includes("--no-probe");
+  const jsonOut = argv.includes("--json");
+  const ids = argv.filter((a) => !a.startsWith("--") && a !== rpcUrl);
+  if (ids.length === 0) {
+    console.error("usage: brainblast trust-graph <programId> [<programId>...] [--rpc URL] [--no-probe] [--json]");
+    process.exit(1);
+  }
+  for (const id of ids) {
+    if (!isValidSolanaAddress(id)) {
+      console.error(`error: '${id}' is not a valid Solana address`);
+      process.exit(1);
+    }
+  }
+  const noCache = argv.includes("--no-cache");
+  const graph = await buildTrustGraph(ids, {
+    rpcUrl,
+    probeRpc: !noProbe,
+    cachePath: noCache ? null : void 0
+  });
+  if (jsonOut) {
+    console.log(JSON.stringify(graph, null, 2));
+  } else {
+    console.log(renderTrustGraphMd(graph));
+  }
+  if (!noCache) {
+    const cp = defaultCachePath();
+    const count = cacheSize(loadProgramCache(cp));
+    console.error(`  program-cache: ${count} entries  (${cp})`);
+  }
+}

package/dist/index.d.ts

@@ -1,5 +1,43 @@
 import { FunctionDeclaration, ArrowFunction } from 'ts-morph';
 
+declare function rentExemptMinimum(dataLen: number): number;
+declare function lamportsToSol(lamports: number): string;
+type Recoverability = "recoverable" | "non-recoverable" | "conditionally-recoverable";
+interface AccountFlow {
+    call: string;
+    module: string;
+    accountType: string;
+    file: string;
+    line: number;
+    dataLen: number;
+    lamports: number;
+    sol: string;
+    recoverability: Recoverability;
+    recoverabilityNote: string;
+    /** Call appears inside a loop or .map()/.forEach() — cost scales with N */
+    scalable: boolean;
+    scalableNote?: string;
+}
+interface PriorityFeePosture {
+    /** true = setComputeUnitPrice call detected somewhere in the target */
+    found: boolean;
+    file?: string;
+    line?: number;
+    detail: string;
+}
+interface CostReport {
+    accountFlows: AccountFlow[];
+    priorityFee: PriorityFeePosture;
+    /** Sum of lamports across non-scalable flows (static lower bound) */
+    totalLockupLamports: number;
+    totalLockupSol: string;
+    /** Subset of flows that grow with N */
+    scalableFlows: AccountFlow[];
+    generatedAt: string;
+}
+declare function analyzeCosts(targetDir: string): CostReport;
+declare function renderCostReportMd(r: CostReport): string;
+
 type Severity = "critical" | "high" | "medium" | "low";
 type CheckResultKind = "pass" | "fail" | "cant_tell";
 interface Candidate {
@@ -8,10 +46,49 @@ interface Candidate {
     params: string[];
     fn: FunctionDeclaration | ArrowFunction;
 }
+interface RustAccountField {
+    /** Rust field identifier, e.g. "counter" */
+    name: string;
+    /** Raw type text, e.g. "Account<'info, Counter>", "Signer<'info>" */
+    typeName: string;
+    /** Full text of every #[account(...)] attribute on this field */
+    attrText: string;
+    /** Whether init_if_needed is present in attrText */
+    hasInitIfNeeded: boolean;
+}
+interface RustCandidate {
+    /** Source .rs file */
+    filePath: string;
+    /** Instruction handler name, e.g. "initialize" */
+    fnName: string;
+    /** Anchor Accounts struct name resolved from Context<X>, e.g. "Initialize" */
+    accountStructName: string;
+    /** All fields extracted from the Accounts struct */
+    accountFields: RustAccountField[];
+    /**
+     * Raw text of the instruction handler body block `{ ... }` — used by
+     * checkers that need to inspect companion calls (require!, data_is_empty, etc.)
+     * without a full tree-sitter traversal.
+     */
+    fnBodyText: string;
+    /** tree-sitter SyntaxNode for the function body — available for precise queries */
+    fnBodyNode: any;
+}
 interface CheckOutcome {
     result: CheckResultKind;
     detail: string;
 }
+interface Fix {
+    summary: string;
+    diff?: string;
+    suggestion?: string;
+}
+interface Precedent {
+    file: string;
+    exportName: string;
+    fixedAt: string;
+    detail: string;
+}
 interface CheckResult extends CheckOutcome {
     ruleId: string;
     severity: Severity;
@@ -19,6 +96,10 @@ interface CheckResult extends CheckOutcome {
     file: string;
     line: number;
     exportName: string;
+    /** Present when result === "fail" and a vetted fixer for check.kind produced one. */
+    fix?: Fix;
+    /** Present when result === "fail" and the same rule was previously fixed elsewhere. */
+    precedent?: Precedent;
 }
 interface Rule {
     id: string;
@@ -34,6 +115,21 @@ interface Rule {
         modules: string[];
         nameRegex: string;
         triggerCalls: string[];
+        /** Defaults to "typescript". Set to "rust" for Anchor/Rust checker kinds. */
+        lang?: "typescript" | "rust";
+        /**
+         * When true, a module import from `modules` is a REQUIRED condition for
+         * detection: a candidate must be in a file that imports one of the listed
+         * modules, AND either its name matches nameRegex or its body calls a
+         * triggerCall.  This prevents generic name-only matches (e.g. a Fastify
+         * middleware named "verifyJwt" that calls `request.jwtVerify()`) from
+         * triggering jose-specific rules.
+         *
+         * When false or omitted (default), detection is: nameRegex match OR
+         * triggerCall in body.  Module import is not required, so rules like
+         * stripe-webhook can still catch handlers that don't import stripe directly.
+         */
+        requiresImport?: boolean;
     };
     check: {
         kind: string;
@@ -82,6 +178,8 @@ declare function audit(targetDir: string, rules: Rule[]): {
             low: number;
         };
         checks: {
+            precedent?: Precedent | undefined;
+            fix?: Fix | undefined;
             ruleId: string;
             severity: Severity;
             result: CheckResultKind;
@@ -96,6 +194,7 @@ declare function audit(targetDir: string, rules: Rule[]): {
             cant_tell: number;
         };
         openQuestions: never[];
+        costAnalysis: CostReport | null;
     };
 };
 
@@ -114,9 +213,138 @@ declare function renderTest(kind: string, opts: {
 }): string;
 declare const testKinds: string[];
 
-declare function runChecker(kind: string, c: Candidate, params: any): CheckOutcome;
+declare function runChecker(kind: string, c: Candidate | RustCandidate, params: any): CheckOutcome;
 declare const checkerKinds: string[];
 
 declare function findCandidates(targetDir: string, rule: Rule): Candidate[];
 
-export { type Candidate, type CheckOutcome, type CheckResult, type CheckResultKind, type Rule, type Severity, audit, auditWithRule, rules as bundledRules, checkerKinds, findCandidates, generateTestForResult, loadRules, renderTest, resolveRules, runChecker, testKinds };
+type UpgradeAuthorityKind = "renounced" | "single-key" | "multisig" | "dao" | "unknown";
+type UpgradeAuthoritySource = "directory" | "rpc" | "research";
+interface UpgradeAuthority {
+    kind: UpgradeAuthorityKind;
+    address: string | null;
+    source: UpgradeAuthoritySource;
+    checkedAt?: string;
+}
+type VerifiedBuildState = {
+    state: "verified";
+    registryUrl: string;
+    commit?: string;
+} | {
+    state: "unverified";
+} | {
+    state: "unknown";
+};
+interface AuditRef {
+    firm: string;
+    date: string;
+    reportUrl: string;
+    auditedCommit?: string;
+}
+interface ParityNote {
+    mainnet: "present" | "absent" | "different" | "unknown";
+    devnet: "present" | "absent" | "different" | "unknown";
+    testnet?: "present" | "absent" | "different" | "unknown";
+    notes?: string;
+}
+interface OnChainProgram {
+    programId: string;
+    name: string;
+    kind?: string;
+    upgradeAuthority: UpgradeAuthority;
+    verifiedBuild: VerifiedBuildState;
+    audits: AuditRef[];
+    parity: ParityNote;
+    invokes?: string[];
+    provenance?: {
+        directoryFile?: string;
+        rpcUrl?: string;
+        researchRun?: string;
+        notes?: string;
+    };
+}
+interface TrustGraph {
+    programs: OnChainProgram[];
+    unresolved: Array<{
+        programId: string;
+        reason: string;
+    }>;
+    generatedAt: string;
+}
+
+interface RpcOpts {
+    rpcUrl?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+
+interface BuildOpts extends RpcOpts {
+    probeRpc?: boolean;
+    directoryPath?: string;
+    cachePath?: string | null;
+}
+declare function buildTrustGraph(programIds: string[], opts?: BuildOpts): Promise<TrustGraph>;
+
+declare function renderTrustGraphMd(g: TrustGraph): string;
+
+declare function loadDirectory(path?: string): Map<string, OnChainProgram>;
+
+declare function base58Encode(bytes: Uint8Array): string;
+declare function base58Decode(s: string): Uint8Array;
+declare function isValidSolanaAddress(s: string): boolean;
+
+declare const DEFAULT_TTL_HOURS = 168;
+declare const SCHEMA_VERSION = "1.0";
+interface ProgramCacheEntry {
+    program: OnChainProgram;
+    /** ISO 8601 timestamp of when this entry was written. */
+    cachedAt: string;
+    /** The run.id from the brainblast report that produced this entry. */
+    sourceRun: string;
+    /** Hours until this entry expires. Defaults to DEFAULT_TTL_HOURS. */
+    ttlHours?: number;
+}
+interface ProgramCache {
+    schemaVersion: typeof SCHEMA_VERSION;
+    entries: Record<string, ProgramCacheEntry>;
+}
+declare function defaultCachePath(): string;
+/**
+ * Load the program cache from disk.
+ *
+ * Returns an empty cache if the file does not exist, is unreadable, or has an
+ * incompatible schemaVersion. Never throws on missing/corrupt files — callers
+ * can always start fresh.
+ */
+declare function loadProgramCache(cachePath?: string): ProgramCache;
+/**
+ * Persist the program cache to disk, creating parent directories as needed.
+ * Throws only on unrecoverable write errors (e.g. permission denied on the
+ * home directory itself).
+ */
+declare function saveProgramCache(cache: ProgramCache, cachePath?: string): void;
+/**
+ * Return the cached OnChainProgram for programId, or null if:
+ *   - the entry does not exist
+ *   - the entry has exceeded its TTL
+ *
+ * @param ttlHoursOverride - optional override for the TTL check (e.g. for tests)
+ */
+declare function getCacheEntry(cache: ProgramCache, programId: string, ttlHoursOverride?: number): OnChainProgram | null;
+/**
+ * Write (or overwrite) a cache entry for programId.
+ * Mutates the cache object in place and returns it for chaining.
+ */
+declare function putCacheEntry(cache: ProgramCache, programId: string, program: OnChainProgram, sourceRun: string, ttlHours?: number): ProgramCache;
+/**
+ * Return the raw ProgramCacheEntry for programId (including metadata), or null.
+ * Useful for rendering provenance to users ("cached 3 days ago by run X").
+ */
+declare function getCacheEntryMeta(cache: ProgramCache, programId: string): ProgramCacheEntry | null;
+declare function isEntryExpired(entry: ProgramCacheEntry, ttlHoursOverride?: number): boolean;
+/**
+ * Count of non-expired entries in the cache (useful for status lines).
+ */
+declare function cacheSize(cache: ProgramCache, ttlHoursOverride?: number): number;
+
+export { type AccountFlow, type AuditRef, type BuildOpts, type Candidate, type CheckOutcome, type CheckResult, type CheckResultKind, type CostReport, DEFAULT_TTL_HOURS, type OnChainProgram, type ParityNote, type PriorityFeePosture, type ProgramCache, type ProgramCacheEntry, type Recoverability, type Rule, type RustAccountField, type RustCandidate, type Severity, type TrustGraph, type UpgradeAuthority, type UpgradeAuthorityKind, type UpgradeAuthoritySource, type VerifiedBuildState, analyzeCosts, audit, auditWithRule, base58Decode, base58Encode, buildTrustGraph, rules as bundledRules, cacheSize, checkerKinds, defaultCachePath, findCandidates, generateTestForResult, getCacheEntry, getCacheEntryMeta, isEntryExpired, isValidSolanaAddress, lamportsToSol, loadDirectory, loadProgramCache, loadRules, putCacheEntry, renderCostReportMd, renderTest, renderTrustGraphMd, rentExemptMinimum, resolveRules, runChecker, saveProgramCache, testKinds };

package/dist/index.js

@@ -1,15 +1,34 @@
 import {
+  DEFAULT_TTL_HOURS,
+  analyzeCosts,
   audit,
   auditWithRule,
+  base58Decode,
+  base58Encode,
+  buildTrustGraph,
+  cacheSize,
   checkerKinds,
+  defaultCachePath,
   findCandidates,
+  getCacheEntry,
+  getCacheEntryMeta,
+  isEntryExpired,
+  isValidSolanaAddress,
+  lamportsToSol,
+  loadDirectory,
+  loadProgramCache,
   loadRules,
+  putCacheEntry,
+  renderCostReportMd,
   renderTest,
+  renderTrustGraphMd,
+  rentExemptMinimum,
   resolveRules,
   rules,
   runChecker,
+  saveProgramCache,
   testKinds
-} from "./chunk-H2Y75CSH.js";
+} from "./chunk-WVHGN2HR.js";
 
 // src/generate.ts
 import { writeFileSync, mkdirSync } from "fs";
@@ -25,15 +44,34 @@ function generateTestForResult(result, rule, outPath) {
   return outPath;
 }
 export {
+  DEFAULT_TTL_HOURS,
+  analyzeCosts,
   audit,
   auditWithRule,
+  base58Decode,
+  base58Encode,
+  buildTrustGraph,
   rules as bundledRules,
+  cacheSize,
   checkerKinds,
+  defaultCachePath,
   findCandidates,
   generateTestForResult,
+  getCacheEntry,
+  getCacheEntryMeta,
+  isEntryExpired,
+  isValidSolanaAddress,
+  lamportsToSol,
+  loadDirectory,
+  loadProgramCache,
   loadRules,
+  putCacheEntry,
+  renderCostReportMd,
   renderTest,
+  renderTrustGraphMd,
+  rentExemptMinimum,
   resolveRules,
   runChecker,
+  saveProgramCache,
   testKinds
 };