refactor tools and rank files in define scope

biome.json

@@ -1,55 +1,53 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
-	"vcs": {
-		"enabled": true,
-		"clientKind": "git",
-		"useIgnoreFile": true
-	},
-	"files": {
-		"includes": [
-			"**",
-			"!!**/dist"
-		]
-	},
-	"formatter": {
-		"enabled": true,
-		"lineWidth": 120,
-		"indentStyle": "space"
-	},
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"recommended": true,
-			"suspicious": {
-				"noUnknownAtRules": "off",
-				"noArrayIndexKey": "off",
-				"noExplicitAny": "off"
-			},
-			"complexity": {
-				"noStaticOnlyClass": "off"
-			},
-			"correctness": {
-				"useExhaustiveDependencies": "off",
-				"useParseIntRadix": "off"
-			},
-			"a11y": "off",
-			"style": {
-				"noNonNullAssertion": "off",
-				"useTemplate": "off"
-			}
-		}
-	},
-	"javascript": {
-		"formatter": {
-			"quoteStyle": "double"
-		}
-	},
-	"assist": {
-		"enabled": true,
-		"actions": {
-			"source": {
-				"organizeImports": "on"
-			}
-		}
-	}
+  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": ["**", "!!**/dist"]
+  },
+  "formatter": {
+    "enabled": true,
+    "lineWidth": 120,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noUnknownAtRules": "off",
+        "noArrayIndexKey": "off",
+        "noExplicitAny": "off",
+        "noAssignInExpressions": "off"
+      },
+      "complexity": {
+        "noStaticOnlyClass": "off"
+      },
+      "correctness": {
+        "useExhaustiveDependencies": "off",
+        "useParseIntRadix": "off"
+      },
+      "a11y": "off",
+      "style": {
+        "noNonNullAssertion": "off",
+        "useTemplate": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
 }

src/agents/auditor/agent.ts

@@ -5,12 +5,8 @@ import { HumanMessage, SystemMessage } from "@langchain/core/messages";
 import { END, type GraphNode, START, StateGraph } from "@langchain/langgraph";
 import { z } from "zod";
 
-import { logger } from "../../logger.ts";
 import { createLLM } from "../../config/llm.ts";
-import { JUDGE_FINDINGS_PROMPT, FIND_VULNERABILITIES_PROMPT, GATHER_CONTEXT_PROMPT } from "./prompts.ts";
-import { AuditorState, JudgeReviewSchema, CandidateFindingSchema } from "./state.ts";
-import { analyzeSolidityFile } from "./tools/solidity-analyzer-tool.ts";
-import { buildRepoTree } from "./tools/repo-tree-tool.ts";
+import { logger } from "../../logger.ts";
 import {
   DOC_BASENAMES,
   DOC_EXTS,
@@ -22,6 +18,15 @@ import {
   SOL_EXT,
   SOL_TEST_SUFFIXES,
 } from "./config.ts";
+import {
+  FIND_VULNERABILITIES_PROMPT,
+  GATHER_CONTEXT_PROMPT,
+  JUDGE_FINDINGS_PROMPT,
+  RANK_FILES_PROMPT,
+} from "./prompts.ts";
+import { AuditorState, CandidateFindingSchema, FileRankingSchema, JudgeReviewSchema } from "./state.ts";
+import { buildRepoTree } from "./tools/repo-tree/tool.ts";
+import { analyzeSolidityFile } from "./tools/solidity-analyzer/tool.ts";
 import { matchLines } from "./utils.ts";
 
 const llm = createLLM();
@@ -71,7 +76,24 @@ const defineScope: GraphNode<typeof AuditorState> = async (state) => {
   logger.debug(`defineScope: doc files: ${JSON.stringify(docFiles)}`);
   logger.debug(`defineScope: file tree:\n${fileTree}`);
 
-  return { scope: solFiles, docs: docFiles, fileTree };
+  logger.info("defineScope: ranking files by importance");
+
+  const RankFilesSchema = z.object({ rankings: z.array(FileRankingSchema) });
+  const rankingModel = llm.withStructuredOutput(RankFilesSchema);
+
+  const { rankings } = await rankingModel.invoke([
+    new SystemMessage(RANK_FILES_PROMPT),
+    new HumanMessage(
+      `File tree:\n\`\`\`\n${fileTree}\n\`\`\`\n\nSolidity files to rank:\n${solFiles.map((f) => `- ${f}`).join("\n")}`,
+    ),
+  ]);
+
+  const sorted = [...rankings].sort((a, b) => b.importance - a.importance);
+  logger.info(
+    `defineScope: rankings:\n${sorted.map((r) => `  [${r.importance}/5] ${r.filePath} — ${r.reasoning}`).join("\n")}`,
+  );
+
+  return { scope: solFiles, docs: docFiles, fileTree, fileRankings: sorted };
 };
 
 const gatherContext: GraphNode<typeof AuditorState> = async (state) => {
@@ -85,23 +107,23 @@ const gatherContext: GraphNode<typeof AuditorState> = async (state) => {
     }
   };
 
-  // Read and analyze each Solidity file
   const solidityEntries: { filePath: string; source: string; analysis: string }[] = [];
   for (const filePath of state.scope) {
     const source = readFile(filePath).slice(0, MAX_SOL_CHARS);
     if (!source) continue;
-    const analysis = await analyzeSolidityFile(source, "full");
+
+    const ranking = state.fileRankings.find((r) => r.filePath === filePath);
+    const mode = ranking && ranking.importance >= 4 ? "full" : "short";
+    const analysis = await analyzeSolidityFile(source, mode, filePath, ranking?.importance);
     solidityEntries.push({ filePath, source, analysis });
   }
 
-  // Read documentation files
   const docEntries: { filePath: string; content: string }[] = [];
   for (const filePath of state.docs) {
     const content = readFile(filePath).slice(0, MAX_DOC_CHARS);
     if (content) docEntries.push({ filePath, content });
   }
 
-  // Build the LLM input
   const parts: string[] = [];
 
   if (docEntries.length > 0) {
@@ -111,21 +133,17 @@ const gatherContext: GraphNode<typeof AuditorState> = async (state) => {
     }
   }
 
-  parts.push("## Structural Analysis (auto-generated)\n");
-  for (const { filePath, analysis } of solidityEntries) {
-    parts.push(`### ${filePath}\n${analysis}`);
-  }
-
-  parts.push("## Contract Source Code\n");
-  for (const { filePath, source } of solidityEntries) {
-    parts.push(`### ${filePath}\n\`\`\`solidity\n${source}\n\`\`\``);
+  parts.push("## Structural Analysis\n");
+  for (const { analysis } of solidityEntries) {
+    parts.push(analysis);
   }
 
   const model = llm.withStructuredOutput(z.object({ context: z.string() }));
   const result = await model.invoke([new SystemMessage(GATHER_CONTEXT_PROMPT), new HumanMessage(parts.join("\n\n"))]);
 
-  logger.info(`gatherContext: context built (${parts.join("\n\n").length} chars)`);
   logger.debug(`gatherContext: full context:\n${parts.join("\n\n")}`);
+  logger.info(`gatherContext: context built (${result.context.length} chars)`);
+  logger.debug(`gatherContext: compact context:\n${result.context}`);
 
   return { repoContext: result.context };
 };

src/agents/auditor/prompts.ts

@@ -1,26 +1,46 @@
-export const GATHER_CONTEXT_PROMPT = `Você é um especialista em segurança de smart contracts. Você receberá documentação, uma análise estrutural e o código-fonte completo de todos os contratos Solidity em escopo. Produza um contexto detalhado do protocolo que guiará a descoberta de vulnerabilidades.
+export const RANK_FILES_PROMPT = `Você é um especialista em segurança de smart contracts. Dado o arquivo tree de um repositório e uma lista de contratos Solidity, classifique cada arquivo pela sua importância para a descoberta de vulnerabilidades de segurança.
 
-Estruture sua resposta nas seguintes seções:
+Para cada arquivo atribua:
+- importance: inteiro de 1 (menos importante) a 5 (mais importante)
+- reasoning: uma frase concisa justificando a classificação
 
-## 1. Visão Geral dos Contratos
-Para cada contrato: seu propósito, tipo (contract/interface/library/abstract), cadeia de herança e principais dependências de outros contratos em escopo ou protocolos externos.
+Importância 5: lógica central do protocolo, vaults de tokens, contratos de custódia, mecanismos de upgrade/proxy, cálculos financeiros, controle de acesso.
+Importância 4: fluxos significativos de valor, contratos que interagem diretamente com os de importância 5, máquinas de estado complexas, distribuição de taxas/recompensas.
+Importância 3: helpers periféricos, bibliotecas, funcionalidades secundárias, governança com timelocks.
+Importância 2: interfaces simples, wrappers triviais, contratos utilitários menores.
+Importância 1: views somente-leitura, configuração pura, arquivos apenas com constantes.
 
-## 2. Mapa de Estado e Armazenamento
-Liste todas as variáveis de estado relevantes entre os contratos, o que representam e quais funções as leem ou escrevem. Sinalize armazenamento compartilhado ou herdado.
+Retorne a classificação de TODOS os arquivos fornecidos.`;
 
-## 3. Fluxos Principais
-Trace os principais caminhos de execução e transições de estado de ponta a ponta entre contratos (ex.: depósito → cunhar shares → atualizar recompensas; saque → queimar shares → transferir ETH). Inclua chamadas entre contratos.
+export const GATHER_CONTEXT_PROMPT = `Você é um especialista em segurança de smart contracts. Você receberá documentação, uma análise estrutural e o código-fonte completo de todos os contratos Solidity em escopo.
 
-## 4. Invariantes
-Condições que devem sempre ser verdadeiras (ex.: "o supply total deve ser igual à soma de todos os saldos", "o saldo de ETH do contrato ≥ soma de todos os depósitos dos usuários"). Derive-as tanto do código-fonte quanto da documentação.
+Produza um contexto conciso e denso do protocolo — ele será antecedido por código e análises, então seja econômico: sem introduções, sem padding, sem repetições. Máximo de **800 palavras no total**.
+
+---
+
+## 1. Contratos (3–5 linhas por contrato)
+Para cada contrato: propósito em uma frase, tipo (contract/interface/library/abstract), herança relevante e dependências externas críticas (oráculos, tokens, protocolos).
+
+## 2. Estado Crítico (bullet por variável relevante)
+Variáveis de estado que afetam lógica de negócio, segurança ou contabilidade interna. Formato: \`nomeVar — o que representa — quem lê/escreve\`. Omita getters triviais e variáveis puramente administrativas sem impacto em segurança.
+
+## 3. Fluxos Principais (máx. 4 fluxos, 3–5 passos cada)
+Somente os caminhos críticos de ponta a ponta. Formato: \`ação → efeito → estado alterado\`. Inclua chamadas cross-contract apenas quando materiais para entender riscos.
+
+## 4. Invariantes e Propriedades
+Liste em bullets as condições que **sempre** devem ser verdadeiras. Separe em dois grupos:
+- **Contábeis**: balanços, totais, proporções (ex.: \`totalSupply == Σ balances\`)
+- **De controle**: acesso, sequência de operações, estados permitidos
 
 ## 5. Premissas de Design
-O que o protocolo assume sobre chamadores, contratos externos, oráculos, chaves de administrador e comportamento de tokens (ex.: "tokens são compatíveis com ERC-20", "o admin é confiável", "sem tokens com taxa de transferência").
+O que o protocolo assume sobre o mundo externo — em bullets curtos: confiança em admin/owner, comportamento esperado de tokens (sem fee-on-transfer, sem rebase), confiabilidade de oráculos, atomicidade de operações.
+
+## 6. Regras de Negócio e Restrições
+Em bullets: controles de acesso (roles/modifiers), limites numéricos (caps, mínimos, máximos), taxas e destinatários, timelocks, pausabilidade e condições de upgrade. Inclua apenas regras com impacto direto em vetores de ataque.
 
-## 6. Regras de Negócio
-Controles de acesso, estruturas de taxas, timelocks, limites, mecanismos de pausa, padrões de atualização e quaisquer outras restrições de domínio.
+---
 
-Seja preciso e exaustivo — quanto mais rico o contexto, com mais precisão as vulnerabilidades podem ser identificadas e validadas.`;
+**Formato obrigatório**: bullets e frases curtas. Sem prosa explicativa. Dados concretos (nomes de funções, variáveis, valores) sempre que disponíveis.`;
 
 export const FIND_VULNERABILITIES_PROMPT = `Você é um auditor especialista em segurança de smart contracts com foco em Solidity. Analise sistematicamente o código-fonte do contrato e o contexto do protocolo para identificar vulnerabilidades de segurança.
 

src/agents/auditor/state.ts

@@ -1,6 +1,12 @@
 import { StateSchema } from "@langchain/langgraph";
 import { z } from "zod";
 
+export const FileRankingSchema = z.object({
+  filePath: z.string(),
+  importance: z.number().int().min(1).max(5),
+  reasoning: z.string(),
+});
+
 export const CandidateFindingSchema = z.object({
   title: z.string(),
   description: z.string(),
@@ -34,6 +40,7 @@ export const AuditorState = new StateSchema({
   scope: z.array(z.string()).default([]),
   docs: z.array(z.string()).default([]),
   fileTree: z.string().default(""),
+  fileRankings: z.array(FileRankingSchema).default([]),
   repoContext: z.string().default(""),
   candidateFindings: z.array(LocatedFindingSchema).default([]),
   judgeReviews: z.array(JudgeReviewSchema).default([]),

src/agents/auditor/tools/{repo-tree-tool.ts → repo-tree/tool.ts}

@@ -4,7 +4,7 @@ import path from "node:path";
 import { tool } from "langchain";
 import { z } from "zod";
 
-import { DOC_BASENAMES, DOC_EXTS, MAX_DEPTH, SKIP_DIRS, SOL_EXT, SOL_TEST_SUFFIXES } from "../config.ts";
+import { DOC_BASENAMES, DOC_EXTS, MAX_DEPTH, SKIP_DIRS, SOL_EXT, SOL_TEST_SUFFIXES } from "../../config.ts";
 
 const CONFIG_FILES = new Set([
   "foundry.toml",
@@ -90,14 +90,11 @@ export const buildRepoTree = (repoPath: string): string => {
   return `${repoName}/\n${renderTree(nodes, "")}`;
 };
 
-export const repoTreeTool = tool(
-  async ({ repoPath }) => buildRepoTree(repoPath),
-  {
-    name: "repo_tree",
-    description:
-      "Walk a repository and return a file-system tree of relevant files tagged by kind: [sol] for auditable Solidity contracts, [test] for Solidity test files, [doc] for documentation, and [config] for project config files. Use this during Define Scope to understand repository layout before selecting which files to audit.",
-    schema: z.object({
-      repoPath: z.string().describe("Absolute path to the repository root."),
-    }),
-  },
-);
+export const repoTreeTool = tool(async ({ repoPath }) => buildRepoTree(repoPath), {
+  name: "repo_tree",
+  description:
+    "Walk a repository and return a file-system tree of relevant files tagged by kind: [sol] for auditable Solidity contracts, [test] for Solidity test files, [doc] for documentation, and [config] for project config files. Use this during Define Scope to understand repository layout before selecting which files to audit.",
+  schema: z.object({
+    repoPath: z.string().describe("Absolute path to the repository root."),
+  }),
+});

src/agents/auditor/tools/solidity-analyzer-tool.ts

@@ -1,567 +0,0 @@
-import { parse, visit } from "@solidity-parser/parser";
-import { tool } from "langchain";
-import { z } from "zod";
-
-const ASSIGNMENT_OPS = new Set(["=", "+=", "-=", "*=", "/=", "%=", "|=", "&=", "^=", "<<=", ">>=", "**="]);
-const BUILTIN_NAMESPACES = new Set(["abi", "block", "msg", "tx", "bytes", "string", "type"]);
-
-interface StateVar {
-  name: string;
-  type: string;
-  visibility: string;
-  constant: boolean;
-  immutable: boolean;
-}
-
-interface EventDef {
-  name: string;
-  params: string[];
-  anonymous: boolean;
-}
-
-interface ModifierDef {
-  name: string;
-  params: string[];
-}
-
-interface FunctionDef {
-  name: string;
-  isConstructor: boolean;
-  isReceive: boolean;
-  isFallback: boolean;
-  visibility: string;
-  mutability: string;
-  params: string[];
-  returns: string[];
-  modifiers: string[];
-  internalCalls: string[];
-  externalCalls: string[];
-  stateReads: string[];
-  stateWrites: string[];
-}
-
-interface ContractAnalysis {
-  name: string;
-  kind: string;
-  baseContracts: string[];
-  usingFor: string[];
-  stateVars: StateVar[];
-  events: EventDef[];
-  modifiers: ModifierDef[];
-  functions: FunctionDef[];
-}
-
-const typeToString = (node: any): string => {
-  if (!node) return "unknown";
-
-  switch (node.type) {
-    case "ElementaryTypeName":
-      return node.name as string;
-    case "UserDefinedTypeName":
-      return (node.namePath ?? node.name) as string;
-    case "ArrayTypeName":
-      return `${typeToString(node.baseTypeName)}[${node.length ?? ""}]`;
-    case "Mapping":
-      return `mapping(${typeToString(node.keyType)} => ${typeToString(node.valueType)})`;
-    case "FunctionTypeName":
-      return "function";
-    default:
-      return "unknown";
-  }
-};
-
-const paramToString = (p: any) => {
-  if (!p) return "?";
-  const type = typeToString(p.typeName);
-  return p.name ? `${type} ${p.name}` : type;
-};
-
-const collectLHSRoots = (node: any, targets: Set<string>) => {
-  if (!node) return;
-  switch (node.type) {
-    case "Identifier":
-      targets.add(node.name as string);
-      break;
-    case "MemberAccess":
-      collectLHSRoots(node.expression, targets);
-      break;
-    case "IndexAccess":
-      collectLHSRoots(node.base, targets);
-      break;
-    case "TupleExpression":
-      for (const c of node.components ?? []) collectLHSRoots(c, targets);
-      break;
-  }
-};
-
-const analyzeFunction = (funcNode: any, stateVarNames: Set<string>) => {
-  const internalCalls = new Set<string>();
-  const externalCalls = new Set<string>();
-  const writeTargets = new Set<string>();
-  const allStateAccesses = new Set<string>();
-  const localVars = new Set<string>();
-
-  if (!funcNode.body) {
-    return { internalCalls: [], externalCalls: [], stateReads: [], stateWrites: [] };
-  }
-
-  // Collect function params and return params as locals so they don't shadow state vars
-  for (const p of funcNode.parameters ?? []) {
-    if (p?.name) localVars.add(p.name as string);
-  }
-  for (const p of funcNode.returnParameters ?? []) {
-    if (p?.name) localVars.add(p.name as string);
-  }
-
-  // Collect local variable declarations
-  visit(funcNode.body, {
-    VariableDeclarationStatement: (node: any) => {
-      for (const v of node.variables ?? []) {
-        if (v?.name) localVars.add(v.name as string);
-      }
-    },
-  });
-
-  const effectiveStateVars = new Set([...stateVarNames].filter((v) => !localVars.has(v)));
-
-  // Collect write targets from assignment LHS, unary mutations, and delete
-  visit(funcNode.body, {
-    ExpressionStatement: (node: any) => {
-      const expr = node.expression;
-      if (expr?.type === "BinaryOperation" && ASSIGNMENT_OPS.has(expr.operator as string)) {
-        collectLHSRoots(expr.left, writeTargets);
-      }
-      // Handle ++, --, and delete — all work on any lvalue (arr[i]++, delete s.field, etc.)
-      if (
-        expr?.type === "UnaryOperation" &&
-        (expr.operator === "++" || expr.operator === "--" || expr.operator === "delete")
-      ) {
-        collectLHSRoots(expr.subExpression, writeTargets);
-      }
-    },
-  });
-
-  // Collect calls and state-var identifier accesses
-  visit(funcNode.body, {
-    FunctionCall: (node: any) => {
-      const expr = node.expression;
-      if (expr?.type === "Identifier") {
-        internalCalls.add(expr.name as string);
-      } else if (expr?.type === "MemberAccess") {
-        const base = expr.expression;
-        if (base?.type === "Identifier" && (base.name === "this" || base.name === "super")) {
-          internalCalls.add(expr.memberName as string);
-        } else if (base?.type === "Identifier" && BUILTIN_NAMESPACES.has(base.name as string)) {
-          // abi.encode, block.xxx, msg.xxx, etc. — not external calls
-        } else {
-          const baseStr = base?.type === "Identifier" ? (base.name as string) : "<expr>";
-          externalCalls.add(`${baseStr}.${expr.memberName as string}`);
-        }
-      }
-    },
-    Identifier: (node: any) => {
-      if (effectiveStateVars.has(node.name as string)) {
-        allStateAccesses.add(node.name as string);
-      }
-    },
-  });
-
-  const stateWrites = [...allStateAccesses].filter((v) => writeTargets.has(v));
-  // A var can be in both — e.g. x = x + 1 is both a read and a write.
-  const stateReads = [...allStateAccesses];
-
-  return {
-    internalCalls: [...internalCalls],
-    externalCalls: [...externalCalls],
-    stateReads,
-    stateWrites,
-  };
-};
-
-const hasCycle = (start: string, current: string, callMap: Map<string, string[]>, visited: Set<string>) => {
-  for (const callee of callMap.get(current) ?? []) {
-    if (callee === start) return true;
-    if (!visited.has(callee)) {
-      visited.add(callee);
-      if (hasCycle(start, callee, callMap, visited)) return true;
-    }
-  }
-
-  return false;
-};
-
-const fnLabel = (fn: FunctionDef) => {
-  if (fn.isConstructor) return "constructor";
-  if (fn.isReceive) return "receive";
-  if (fn.isFallback) return "fallback";
-  return fn.name;
-};
-
-const generateShortMarkdown = (imports: string[], contracts: ContractAnalysis[]) => {
-  const lines: string[] = [];
-  lines.push("# Solidity Analysis\n");
-
-  if (imports.length > 0) {
-    lines.push(`**Imports:** ${imports.map((i) => `\`${i}\``).join(", ")}\n`);
-  }
-
-  for (const contract of contracts) {
-    const inheritance =
-      contract.baseContracts.length > 0 ? ` : ${contract.baseContracts.map((b) => `\`${b}\``).join(", ")}` : "";
-    lines.push(`---\n\n## \`${contract.name}\` (${contract.kind})${inheritance}\n`);
-
-    // State variables — one line, name:type
-    if (contract.stateVars.length > 0) {
-      const vars = contract.stateVars.map((v) => {
-        const flags = [v.constant && "constant", v.immutable && "immutable"].filter(Boolean);
-        const suffix = flags.length > 0 ? `, ${flags.join(", ")}` : "";
-        return `\`${v.name}: ${v.type}\` (${v.visibility}${suffix})`;
-      });
-      lines.push(`**State:** ${vars.join(", ")}\n`);
-    }
-
-    // Modifiers — names only
-    if (contract.modifiers.length > 0) {
-      const mods = contract.modifiers.map(
-        (m) => `\`${m.name}${m.params.length > 0 ? `(${m.params.join(", ")})` : ""}\``,
-      );
-      lines.push(`**Modifiers:** ${mods.join(", ")}\n`);
-    }
-
-    // Events — name + params, one line each
-    if (contract.events.length > 0) {
-      const evts = contract.events.map((e) => `\`${e.name}(${e.params.join(", ")})\``);
-      lines.push(`**Events:** ${evts.join(", ")}\n`);
-    }
-
-    // Function list — compact, one line per function
-    if (contract.functions.length > 0) {
-      lines.push("**Functions:**");
-      for (const fn of contract.functions) {
-        const label = fnLabel(fn);
-        const params = fn.params.join(", ");
-        const ret = fn.returns.length > 0 ? ` → ${fn.returns.join(", ")}` : "";
-        const mods = fn.modifiers.length > 0 ? ` [${fn.modifiers.join(", ")}]` : "";
-        lines.push(`- \`${label}(${params})${ret}\` — ${fn.visibility} ${fn.mutability}${mods}`);
-      }
-      lines.push("");
-    }
-
-    // External calls — only functions that make them
-    const externalFuncs = contract.functions.filter((f) => f.externalCalls.length > 0);
-    if (externalFuncs.length > 0) {
-      lines.push("**External Calls:**");
-      for (const fn of externalFuncs) {
-        lines.push(`- \`${fnLabel(fn)}\`: ${fn.externalCalls.map((c) => `\`${c}\``).join(", ")}`);
-      }
-      lines.push("");
-    }
-  }
-
-  return lines.join("\n");
-};
-
-const generateMarkdown = (imports: string[], contracts: ContractAnalysis[]) => {
-  const lines: string[] = [];
-  lines.push("# Solidity Contract Analysis\n");
-
-  // Imports
-  lines.push("## Imports\n");
-  if (imports.length === 0) {
-    lines.push("_No imports._\n");
-  } else {
-    for (const imp of imports) lines.push(`- \`${imp}\``);
-    lines.push("");
-  }
-
-  for (const contract of contracts) {
-    const kindLabel = contract.kind.charAt(0).toUpperCase() + contract.kind.slice(1);
-    lines.push(`---\n\n## ${kindLabel}: \`${contract.name}\`\n`);
-
-    // Inheritance
-    lines.push("### Inheritance\n");
-    if (contract.baseContracts.length === 0) {
-      lines.push("_None._\n");
-    } else {
-      for (const base of contract.baseContracts) lines.push(`- \`${base}\``);
-      lines.push("");
-    }
-
-    // Using For
-    if (contract.usingFor.length > 0) {
-      lines.push("### Using For\n");
-      for (const u of contract.usingFor) lines.push(`- ${u}`);
-      lines.push("");
-    }
-
-    // Storage layout
-    lines.push("### Storage Layout (State Variables)\n");
-    if (contract.stateVars.length === 0) {
-      lines.push("_No state variables._\n");
-    } else {
-      lines.push("| Slot | Name | Type | Visibility | Flags |");
-      lines.push("|------|------|------|------------|-------|");
-      contract.stateVars.forEach((v, i) => {
-        const flags = [v.constant && "constant", v.immutable && "immutable"].filter(Boolean).join(", ");
-        lines.push(`| ${i} | \`${v.name}\` | \`${v.type}\` | ${v.visibility} | ${flags} |`);
-      });
-      lines.push("");
-    }
-
-    // Events
-    lines.push("### Events\n");
-    if (contract.events.length === 0) {
-      lines.push("_No events._\n");
-    } else {
-      for (const evt of contract.events) {
-        const params = evt.params.join(", ");
-        lines.push(`- **\`${evt.name}\`**\`(${params})\`${evt.anonymous ? " _(anonymous)_" : ""}`);
-      }
-      lines.push("");
-    }
-
-    // Modifiers
-    lines.push("### Modifiers\n");
-    if (contract.modifiers.length === 0) {
-      lines.push("_No modifiers._\n");
-    } else {
-      for (const mod of contract.modifiers) {
-        lines.push(`- **\`${mod.name}\`**\`(${mod.params.join(", ")})\``);
-      }
-      lines.push("");
-    }
-
-    // Function list
-    lines.push("### Function List\n");
-    if (contract.functions.length === 0) {
-      lines.push("_No functions._\n");
-    } else {
-      lines.push("| Name | Visibility | Mutability | Parameters | Returns | Modifiers |");
-      lines.push("|------|------------|------------|------------|---------|-----------|");
-      for (const fn of contract.functions) {
-        lines.push(
-          `| \`${fnLabel(fn)}\` | ${fn.visibility} | ${fn.mutability} | \`${fn.params.join(", ")}\` | \`${fn.returns.join(", ")}\` | ${fn.modifiers.join(", ")} |`,
-        );
-      }
-      lines.push("");
-    }
-
-    // Call graph
-    lines.push("### Call Graph\n");
-    const hasCalls = contract.functions.some((f) => f.internalCalls.length > 0 || f.externalCalls.length > 0);
-    if (!hasCalls) {
-      lines.push("_No function calls detected._\n");
-    } else {
-      for (const fn of contract.functions) {
-        if (fn.internalCalls.length === 0 && fn.externalCalls.length === 0) continue;
-        lines.push(`**\`${fnLabel(fn)}\`**`);
-        for (const call of fn.internalCalls) lines.push(`  - → \`${call}\` _(internal)_`);
-        for (const call of fn.externalCalls) lines.push(`  - → \`${call}\` _(external)_`);
-      }
-      lines.push("");
-    }
-
-    // External calls
-    lines.push("### External Calls\n");
-    const externalFuncs = contract.functions.filter((f) => f.externalCalls.length > 0);
-    if (externalFuncs.length === 0) {
-      lines.push("_No external calls detected._\n");
-    } else {
-      for (const fn of externalFuncs) {
-        lines.push(`**\`${fnLabel(fn)}\`**`);
-        for (const call of fn.externalCalls) lines.push(`  - \`${call}\``);
-      }
-      lines.push("");
-    }
-
-    // Internal recursion
-    lines.push("### Internal Recursion\n");
-    const callMap = new Map(contract.functions.map((f) => [fnLabel(f), f.internalCalls]));
-    const recursiveFns = contract.functions.filter((fn) => hasCycle(fnLabel(fn), fnLabel(fn), callMap, new Set()));
-    if (recursiveFns.length === 0) {
-      lines.push("_No recursive functions detected._\n");
-    } else {
-      for (const fn of recursiveFns) lines.push(`- **\`${fnLabel(fn)}\`** is recursive`);
-      lines.push("");
-    }
-
-    // State variable touchpoints
-    lines.push("### State Variable Touchpoints\n");
-    const touchedFns = contract.functions.filter((f) => f.stateReads.length > 0 || f.stateWrites.length > 0);
-    if (touchedFns.length === 0) {
-      lines.push("_No state variable accesses detected._\n");
-    } else {
-      lines.push("| Function | Reads | Writes |");
-      lines.push("|----------|-------|--------|");
-      for (const fn of touchedFns) {
-        const reads = fn.stateReads.map((r) => `\`${r}\``).join(", ");
-        const writes = fn.stateWrites.map((w) => `\`${w}\``).join(", ");
-        lines.push(`| \`${fnLabel(fn)}\` | ${reads} | ${writes} |`);
-      }
-      lines.push("");
-    }
-  }
-
-  // External dependencies summary
-  lines.push("---\n\n## External Dependencies\n");
-
-  lines.push("### Import Paths\n");
-  if (imports.length === 0) {
-    lines.push("_No imports._\n");
-  } else {
-    for (const imp of imports) lines.push(`- \`${imp}\``);
-    lines.push("");
-  }
-
-  const externalTargets = new Set<string>();
-  for (const contract of contracts) {
-    for (const fn of contract.functions) {
-      for (const call of fn.externalCalls) {
-        const target = call.split(".")[0];
-        if (target && target !== "<expr>") externalTargets.add(target);
-      }
-    }
-  }
-
-  lines.push("### External Contract Interactions\n");
-  if (externalTargets.size === 0) {
-    lines.push("_No external contract interactions detected._\n");
-  } else {
-    for (const dep of externalTargets) lines.push(`- \`${dep}\``);
-    lines.push("");
-  }
-
-  return lines.join("\n");
-};
-
-export const analyzeSolidityFile = async (soliditySource: string, mode: "full" | "short") => {
-  let ast: any;
-
-  try {
-    ast = parse(soliditySource, { tolerant: true, loc: true, range: true });
-  } catch (e: any) {
-    return `# Parse Error\n\nFailed to parse Solidity source: ${e.message as string}`;
-  }
-
-  const imports: string[] = [];
-  const contracts: ContractAnalysis[] = [];
-
-  for (const node of ast.children ?? []) {
-    if (node.type === "ImportDirective") {
-      imports.push(node.path as string);
-    }
-  }
-
-  for (const node of ast.children ?? []) {
-    if (node.type !== "ContractDefinition") continue;
-
-    const contract: ContractAnalysis = {
-      name: node.name as string,
-      kind: (node.kind as string) ?? "contract",
-      baseContracts: (node.baseContracts ?? []).map(
-        (bc: any) => (bc.baseName?.namePath ?? bc.baseName?.name ?? "?") as string,
-      ),
-      usingFor: [],
-      stateVars: [],
-      events: [],
-      modifiers: [],
-      functions: [],
-    };
-
-    const stateVarNames = new Set<string>();
-
-    for (const member of node.subNodes ?? []) {
-      switch (member.type) {
-        case "StateVariableDeclaration":
-          for (const v of member.variables ?? []) {
-            stateVarNames.add(v.name as string);
-            contract.stateVars.push({
-              name: v.name as string,
-              type: typeToString(v.typeName),
-              visibility: (v.visibility as string) ?? "internal",
-              constant: (v.isDeclaredConst as boolean) ?? false,
-              immutable: (v.isImmutable as boolean) ?? false,
-            });
-          }
-          break;
-
-        case "EventDefinition": {
-          const params = (member.parameters ?? []).map((p: any) => {
-            const indexed = p.isIndexed ? "indexed " : "";
-            const name = p.name ? ` ${p.name as string}` : "";
-            return `${indexed}${typeToString(p.typeName)}${name}`;
-          });
-          contract.events.push({
-            name: member.name as string,
-            params,
-            anonymous: (member.isAnonymous as boolean) ?? false,
-          });
-          break;
-        }
-
-        case "ModifierDefinition":
-          contract.modifiers.push({
-            name: member.name as string,
-            params: (member.parameters ?? []).map(paramToString),
-          });
-          break;
-
-        case "FunctionDefinition": {
-          const { internalCalls, externalCalls, stateReads, stateWrites } = analyzeFunction(member, stateVarNames);
-          contract.functions.push({
-            name: (member.name as string) ?? "",
-            isConstructor: (member.isConstructor as boolean) ?? false,
-            isReceive: (member.isReceiveEther as boolean) ?? false,
-            isFallback: (member.isFallback as boolean) ?? false,
-            visibility: (member.visibility as string) ?? "internal",
-            mutability: (member.stateMutability as string) ?? "nonpayable",
-            params: (member.parameters ?? []).map(paramToString),
-            returns: (member.returnParameters ?? []).map(paramToString),
-            modifiers: (member.modifiers ?? []).map((m: any) => m.name as string),
-            internalCalls,
-            externalCalls,
-            stateReads,
-            stateWrites,
-          });
-          break;
-        }
-
-        case "UsingForDeclaration": {
-          const forType = member.typeName ? typeToString(member.typeName) : "*";
-          if (member.libraryName) {
-            contract.usingFor.push(`\`${member.libraryName as string}\` for \`${forType}\``);
-          } else {
-            // New-style: using {fn1, fn2, ...} for T
-            const fns = (member.functions ?? [])
-              .map((f: any) => (f.typeName?.namePath ?? f.typeName?.name ?? f.path ?? "?") as string)
-              .join(", ");
-            contract.usingFor.push(`{${fns}} for \`${forType}\``);
-          }
-          break;
-        }
-      }
-    }
-
-    contracts.push(contract);
-  }
-
-  return mode === "short" ? generateShortMarkdown(imports, contracts) : generateMarkdown(imports, contracts);
-};
-
-export const solidityAnalyzerTool = tool(
-  async ({ solidityFile, mode }) => {
-    return analyzeSolidityFile(solidityFile, mode);
-  },
-  {
-    name: "solidity_analyzer",
-    description:
-      "Parse a Solidity source file and generate a markdown report. Use mode='short' for a compact token-efficient summary (imports, state, modifiers, events, function signatures, external calls). Use mode='full' for the complete report including storage layout table, call graph, recursion detection, state variable touchpoints, and external dependencies.",
-    schema: z.object({
-      solidityFile: z.string().describe("The full Solidity source code to analyze."),
-      mode: z
-        .enum(["full", "short"])
-        .default("full")
-        .describe("Report verbosity. 'short' saves tokens; 'full' provides the complete analysis."),
-    }),
-  },
-);

src/agents/auditor/tools/solidity-analyzer/tool.ts

@@ -0,0 +1,172 @@
+import { parse } from "@solidity-parser/parser";
+import { tool } from "langchain";
+import { z } from "zod";
+
+import {
+  analyzeFunction,
+  buildCommentBlocks,
+  type ContractAnalysis,
+  extractSolcVersion,
+  findCommentFor,
+  generateBriefMarkdown,
+  generateFullMarkdown,
+  paramToString,
+  type RenderOptions,
+  typeToString,
+} from "./utils.ts";
+
+export const analyzeSolidityFile = async (
+  soliditySource: string,
+  mode: "full" | "short",
+  filePath?: string,
+  importance?: number,
+): Promise<string> => {
+  let ast: any;
+  try {
+    ast = parse(soliditySource, { tolerant: true, loc: true, range: true });
+  } catch (e: any) {
+    return `# Parse Error\n\nFailed to parse Solidity source: ${e.message as string}`;
+  }
+
+  const comments = buildCommentBlocks(soliditySource);
+  const imports: string[] = [];
+  const contracts: ContractAnalysis[] = [];
+
+  for (const node of ast.children ?? []) {
+    if (node.type === "ImportDirective") imports.push(node.path as string);
+  }
+
+  for (const node of ast.children ?? []) {
+    if (node.type !== "ContractDefinition") continue;
+
+    const contractComment = node.loc ? findCommentFor(node.loc.start.line, comments) : undefined;
+
+    const contract: ContractAnalysis = {
+      name: node.name as string,
+      kind: (node.kind as string) ?? "contract",
+      baseContracts: (node.baseContracts ?? []).map(
+        (bc: any) => (bc.baseName?.namePath ?? bc.baseName?.name ?? "?") as string,
+      ),
+      usingFor: [],
+      stateVars: [],
+      events: [],
+      errors: [],
+      modifiers: [],
+      functions: [],
+      natspec: contractComment?.natspec,
+    };
+
+    const stateVarNames = new Set<string>();
+
+    for (const member of node.subNodes ?? []) {
+      const memberComment = member.loc ? findCommentFor(member.loc.start.line, comments) : undefined;
+
+      switch (member.type) {
+        case "StateVariableDeclaration":
+          for (const v of member.variables ?? []) {
+            stateVarNames.add(v.name as string);
+            contract.stateVars.push({
+              name: v.name as string,
+              type: typeToString(v.typeName),
+              visibility: (v.visibility as string) ?? "internal",
+              constant: (v.isDeclaredConst as boolean) ?? false,
+              immutable: (v.isImmutable as boolean) ?? false,
+              natspec: memberComment?.natspec,
+            });
+          }
+          break;
+
+        case "EventDefinition": {
+          const params = (member.parameters ?? []).map((p: any) => {
+            const indexed = p.isIndexed ? "indexed " : "";
+            const name = p.name ? ` ${p.name as string}` : "";
+            return `${indexed}${typeToString(p.typeName)}${name}`;
+          });
+          contract.events.push({
+            name: member.name as string,
+            params,
+            anonymous: (member.isAnonymous as boolean) ?? false,
+            natspec: memberComment?.natspec,
+          });
+          break;
+        }
+
+        case "CustomErrorDefinition":
+          contract.errors.push({
+            name: member.name as string,
+            params: (member.parameters ?? []).map((p: any) => paramToString(p)),
+            natspec: memberComment?.natspec,
+          });
+          break;
+
+        case "ModifierDefinition":
+          contract.modifiers.push({
+            name: member.name as string,
+            params: (member.parameters ?? []).map(paramToString),
+            natspec: memberComment?.natspec,
+          });
+          break;
+
+        case "FunctionDefinition": {
+          const { internalCalls, externalCalls, stateReads, stateWrites } = analyzeFunction(member, stateVarNames);
+          contract.functions.push({
+            name: (member.name as string) ?? "",
+            isConstructor: (member.isConstructor as boolean) ?? false,
+            isReceive: (member.isReceiveEther as boolean) ?? false,
+            isFallback: (member.isFallback as boolean) ?? false,
+            visibility: (member.visibility as string) ?? "internal",
+            mutability: (member.stateMutability as string) ?? "nonpayable",
+            params: (member.parameters ?? []).map(paramToString),
+            returns: (member.returnParameters ?? []).map(paramToString),
+            modifiers: (member.modifiers ?? []).map((m: any) => m.name as string),
+            internalCalls,
+            externalCalls,
+            stateReads,
+            stateWrites,
+            natspec: memberComment?.natspec,
+          });
+          break;
+        }
+
+        case "UsingForDeclaration": {
+          const forType = member.typeName ? typeToString(member.typeName) : "*";
+          if (member.libraryName) {
+            contract.usingFor.push(`\`${member.libraryName as string}\` for \`${forType}\``);
+          } else {
+            const fns = (member.functions ?? [])
+              .map((f: any) => (f.typeName?.namePath ?? f.typeName?.name ?? f.path ?? "?") as string)
+              .join(", ");
+            contract.usingFor.push(`{${fns}} for \`${forType}\``);
+          }
+          break;
+        }
+      }
+    }
+
+    contracts.push(contract);
+  }
+
+  const opts: RenderOptions = {
+    filePath,
+    importance,
+    lineCount: soliditySource.split("\n").length,
+    solcVersion: extractSolcVersion(soliditySource),
+  };
+
+  return mode === "short"
+    ? generateBriefMarkdown(imports, contracts, opts)
+    : generateFullMarkdown(imports, contracts, opts);
+};
+
+export const solidityAnalyzerTool = tool(async ({ solidityFile, mode }) => analyzeSolidityFile(solidityFile, mode), {
+  name: "solidity_analyzer",
+  description:
+    "Parse a Solidity source file and generate a markdown report. Use mode='short' for a compact summary (meta, external calls, function table). Use mode='full' for the complete report including storage, events, errors, per-function call graph, recursion detection, and state variable touchpoints.",
+  schema: z.object({
+    solidityFile: z.string().describe("The full Solidity source code to analyze."),
+    mode: z
+      .enum(["full", "short"])
+      .default("full")
+      .describe("Report verbosity. 'short' saves tokens; 'full' provides the complete analysis."),
+  }),
+});

src/agents/auditor/tools/solidity-analyzer/utils.ts

@@ -0,0 +1,522 @@
+import { visit } from "@solidity-parser/parser";
+
+const ASSIGNMENT_OPS = new Set(["=", "+=", "-=", "*=", "/=", "%=", "|=", "&=", "^=", "<<=", ">>=", "**="]);
+const BUILTIN_NAMESPACES = new Set(["abi", "block", "msg", "tx", "bytes", "string", "type"]);
+
+export interface NatSpec {
+  title?: string;
+  author?: string;
+  notice?: string;
+  dev?: string;
+  params: Record<string, string>;
+  returns: string[];
+  inheritdoc?: string;
+  custom: Record<string, string>;
+}
+
+export interface ParsedComment {
+  text: string;
+  startLine: number;
+  endLine: number;
+  isNatSpec: boolean;
+  natspec?: NatSpec;
+}
+
+export interface StateVar {
+  name: string;
+  type: string;
+  visibility: string;
+  constant: boolean;
+  immutable: boolean;
+  natspec?: NatSpec;
+}
+
+export interface EventDef {
+  name: string;
+  params: string[];
+  anonymous: boolean;
+  natspec?: NatSpec;
+}
+
+export interface ErrorDef {
+  name: string;
+  params: string[];
+  natspec?: NatSpec;
+}
+
+export interface ModifierDef {
+  name: string;
+  params: string[];
+  natspec?: NatSpec;
+}
+
+export interface FunctionDef {
+  name: string;
+  isConstructor: boolean;
+  isReceive: boolean;
+  isFallback: boolean;
+  visibility: string;
+  mutability: string;
+  params: string[];
+  returns: string[];
+  modifiers: string[];
+  internalCalls: string[];
+  externalCalls: string[];
+  stateReads: string[];
+  stateWrites: string[];
+  natspec?: NatSpec;
+}
+
+export interface ContractAnalysis {
+  name: string;
+  kind: string;
+  baseContracts: string[];
+  usingFor: string[];
+  stateVars: StateVar[];
+  events: EventDef[];
+  errors: ErrorDef[];
+  modifiers: ModifierDef[];
+  functions: FunctionDef[];
+  natspec?: NatSpec;
+}
+
+export interface RenderOptions {
+  filePath?: string;
+  importance?: number;
+  lineCount: number;
+  solcVersion: string;
+}
+
+export const extractSolcVersion = (source: string): string => {
+  const match = source.match(/pragma\s+solidity\s+([^;]+);/);
+  return match ? match[1].trim() : "—";
+};
+
+const parseNatSpecTags = (text: string): NatSpec => {
+  const result: NatSpec = { params: {}, returns: [], custom: {} };
+
+  const firstTag = text.search(/@(?:title|author|notice|dev|param|return|inheritdoc|custom:)/);
+  if (firstTag > 0) {
+    const implicit = text.slice(0, firstTag).trim();
+    if (implicit) result.notice = implicit.replace(/\n\s*/g, " ");
+  } else if (firstTag === -1 && text.trim()) {
+    result.notice = text.trim().replace(/\n\s*/g, " ");
+  }
+
+  const tagRe = /@(custom:\S+|\w+)([^@]*)/g;
+  let m: RegExpExecArray | null;
+  while ((m = tagRe.exec(text)) !== null) {
+    const tag = m[1];
+    const value = m[2].trim().replace(/\n\s*/g, " ");
+    if (tag === "title") result.title = value;
+    else if (tag === "author") result.author = value;
+    else if (tag === "notice") result.notice = value;
+    else if (tag === "dev") result.dev = value;
+    else if (tag === "inheritdoc") result.inheritdoc = value;
+    else if (tag === "param") {
+      const sp = value.indexOf(" ");
+      if (sp > 0) result.params[value.slice(0, sp)] = value.slice(sp + 1);
+      else if (value) result.params[value] = "";
+    } else if (tag === "return") result.returns.push(value);
+    else if (tag.startsWith("custom:")) result.custom[tag.slice(7)] = value;
+  }
+
+  return result;
+};
+
+export const buildCommentBlocks = (source: string): ParsedComment[] => {
+  const blocks: ParsedComment[] = [];
+  const lines = source.split("\n");
+  let i = 0;
+
+  while (i < lines.length) {
+    const raw = lines[i];
+    const trimmed = raw.trimStart();
+
+    if (trimmed.startsWith("///")) {
+      const startLine = i + 1;
+      const texts: string[] = [];
+      while (i < lines.length && lines[i].trimStart().startsWith("///")) {
+        texts.push(lines[i].trimStart().slice(3).replace(/^ /, ""));
+        i++;
+      }
+      const text = texts.join("\n");
+      blocks.push({ text, startLine, endLine: i, isNatSpec: true, natspec: parseNatSpecTags(text) });
+      continue;
+    }
+
+    const mlStart = raw.indexOf("/*");
+    if (mlStart !== -1) {
+      const isNatSpec = raw[mlStart + 2] === "*" && raw[mlStart + 3] !== "/";
+      const startLine = i + 1;
+      const closeOnSame = raw.indexOf("*/", mlStart + 2);
+
+      if (closeOnSame !== -1) {
+        const inner = raw.slice(mlStart + (isNatSpec ? 3 : 2), closeOnSame).trim();
+        blocks.push({
+          text: inner,
+          startLine,
+          endLine: startLine,
+          isNatSpec,
+          natspec: isNatSpec ? parseNatSpecTags(inner) : undefined,
+        });
+        i++;
+        continue;
+      }
+
+      const rawLines: string[] = [raw.slice(mlStart + (isNatSpec ? 3 : 2))];
+      i++;
+      while (i < lines.length) {
+        const closeIdx = lines[i].indexOf("*/");
+        if (closeIdx !== -1) {
+          rawLines.push(lines[i].slice(0, closeIdx));
+          i++;
+          break;
+        }
+        rawLines.push(lines[i]);
+        i++;
+      }
+      const text = rawLines
+        .map((l) => l.replace(/^\s*\*\s?/, ""))
+        .join("\n")
+        .trim();
+      blocks.push({ text, startLine, endLine: i, isNatSpec, natspec: isNatSpec ? parseNatSpecTags(text) : undefined });
+      continue;
+    }
+
+    if (trimmed.startsWith("//")) {
+      blocks.push({ text: trimmed.slice(2).trim(), startLine: i + 1, endLine: i + 1, isNatSpec: false });
+    }
+
+    i++;
+  }
+
+  return blocks;
+};
+
+export const findCommentFor = (line: number, comments: ParsedComment[]): ParsedComment | undefined =>
+  comments.find((c) => c.endLine === line - 1) ?? comments.find((c) => c.startLine === line && !c.isNatSpec);
+
+export const typeToString = (node: any): string => {
+  if (!node) return "unknown";
+  switch (node.type) {
+    case "ElementaryTypeName":
+      return node.name as string;
+    case "UserDefinedTypeName":
+      return (node.namePath ?? node.name) as string;
+    case "ArrayTypeName":
+      return `${typeToString(node.baseTypeName)}[${node.length ?? ""}]`;
+    case "Mapping":
+      return `mapping(${typeToString(node.keyType)} => ${typeToString(node.valueType)})`;
+    case "FunctionTypeName":
+      return "function";
+    default:
+      return "unknown";
+  }
+};
+
+export const paramToString = (p: any): string => {
+  if (!p) return "?";
+  const type = typeToString(p.typeName);
+  return p.name ? `${type} ${p.name}` : type;
+};
+
+const collectLHSRoots = (node: any, targets: Set<string>) => {
+  if (!node) return;
+  switch (node.type) {
+    case "Identifier":
+      targets.add(node.name as string);
+      break;
+    case "MemberAccess":
+      collectLHSRoots(node.expression, targets);
+      break;
+    case "IndexAccess":
+      collectLHSRoots(node.base, targets);
+      break;
+    case "TupleExpression":
+      for (const c of node.components ?? []) collectLHSRoots(c, targets);
+      break;
+  }
+};
+
+export const analyzeFunction = (funcNode: any, stateVarNames: Set<string>) => {
+  const internalCalls = new Set<string>();
+  const externalCalls = new Set<string>();
+  const writeTargets = new Set<string>();
+  const allStateAccesses = new Set<string>();
+  const localVars = new Set<string>();
+
+  if (!funcNode.body) {
+    return { internalCalls: [], externalCalls: [], stateReads: [], stateWrites: [] };
+  }
+
+  for (const p of funcNode.parameters ?? []) {
+    if (p?.name) localVars.add(p.name as string);
+  }
+  for (const p of funcNode.returnParameters ?? []) {
+    if (p?.name) localVars.add(p.name as string);
+  }
+
+  visit(funcNode.body, {
+    VariableDeclarationStatement: (node: any) => {
+      for (const v of node.variables ?? []) {
+        if (v?.name) localVars.add(v.name as string);
+      }
+    },
+  });
+
+  const effectiveStateVars = new Set([...stateVarNames].filter((v) => !localVars.has(v)));
+
+  visit(funcNode.body, {
+    ExpressionStatement: (node: any) => {
+      const expr = node.expression;
+      if (expr?.type === "BinaryOperation" && ASSIGNMENT_OPS.has(expr.operator as string)) {
+        collectLHSRoots(expr.left, writeTargets);
+      }
+      if (
+        expr?.type === "UnaryOperation" &&
+        (expr.operator === "++" || expr.operator === "--" || expr.operator === "delete")
+      ) {
+        collectLHSRoots(expr.subExpression, writeTargets);
+      }
+    },
+  });
+
+  visit(funcNode.body, {
+    FunctionCall: (node: any) => {
+      const expr = node.expression;
+      if (expr?.type === "Identifier") {
+        internalCalls.add(expr.name as string);
+      } else if (expr?.type === "MemberAccess") {
+        const base = expr.expression;
+        if (base?.type === "Identifier" && (base.name === "this" || base.name === "super")) {
+          internalCalls.add(expr.memberName as string);
+        } else if (base?.type === "Identifier" && BUILTIN_NAMESPACES.has(base.name as string)) {
+          // builtin namespace — skip
+        } else {
+          const baseStr = base?.type === "Identifier" ? (base.name as string) : "<expr>";
+          externalCalls.add(`${baseStr}.${expr.memberName as string}`);
+        }
+      }
+    },
+    Identifier: (node: any) => {
+      if (effectiveStateVars.has(node.name as string)) {
+        allStateAccesses.add(node.name as string);
+      }
+    },
+  });
+
+  const stateWrites = [...allStateAccesses].filter((v) => writeTargets.has(v));
+
+  return {
+    internalCalls: [...internalCalls],
+    externalCalls: [...externalCalls],
+    stateReads: [...allStateAccesses],
+    stateWrites,
+  };
+};
+
+export const hasCycle = (
+  start: string,
+  current: string,
+  callMap: Map<string, string[]>,
+  visited: Set<string>,
+): boolean => {
+  for (const callee of callMap.get(current) ?? []) {
+    if (callee === start) return true;
+    if (!visited.has(callee)) {
+      visited.add(callee);
+      if (hasCycle(start, callee, callMap, visited)) return true;
+    }
+  }
+  return false;
+};
+
+export const fnLabel = (fn: FunctionDef): string => {
+  if (fn.isConstructor) return "constructor";
+  if (fn.isReceive) return "receive";
+  if (fn.isFallback) return "fallback";
+  return fn.name;
+};
+
+const renderNatSpec = (ns: NatSpec | undefined): string => {
+  if (!ns) return "—";
+  const parts: string[] = [];
+  if (ns.title) parts.push(`@title "${ns.title}"`);
+  if (ns.author) parts.push(`@author "${ns.author}"`);
+  if (ns.notice) parts.push(`@notice "${ns.notice}"`);
+  if (ns.dev) parts.push(`@dev "${ns.dev}"`);
+  for (const [k, v] of Object.entries(ns.params)) {
+    parts.push(v ? `@param ${k}: "${v}"` : `@param ${k}`);
+  }
+  for (const r of ns.returns) {
+    if (r) parts.push(`@return "${r}"`);
+  }
+  return parts.length > 0 ? parts.join(" · ") : "—";
+};
+
+const renderContractFull = (contract: ContractAnalysis, imports: string[], lines: string[]) => {
+  lines.push("## Meta");
+  const inherits = contract.baseContracts.length > 0 ? `[${contract.baseContracts.join(", ")}]` : "—";
+  lines.push(`- kind: ${contract.kind} · inherits: ${inherits}`);
+  if (contract.usingFor.length > 0) lines.push(`- uses: [${contract.usingFor.join(", ")}]`);
+  lines.push(`- imports: ${imports.length > 0 ? imports.map((i) => `\`${i}\``).join(", ") : "—"}`);
+  lines.push(`- docs: ${renderNatSpec(contract.natspec)}`);
+  lines.push("");
+
+  if (contract.stateVars.length > 0) {
+    lines.push("## Storage");
+    lines.push("| name | type | vis | flags | desc |");
+    lines.push("|------|------|-----|-------|------|");
+    for (const v of contract.stateVars) {
+      const flags = [v.constant && "constant", v.immutable && "immutable"].filter(Boolean).join(", ") || "—";
+      const desc = v.natspec?.notice ?? v.natspec?.dev ?? "—";
+      lines.push(`| \`${v.name}\` | \`${v.type}\` | ${v.visibility} | ${flags} | ${desc} |`);
+    }
+    lines.push("");
+  }
+
+  if (contract.events.length > 0) {
+    lines.push("## Events");
+    for (const e of contract.events) {
+      const notice = e.natspec?.notice ? ` — ${e.natspec.notice}` : "";
+      lines.push(`- \`${e.name}(${e.params.join(", ")})\`${e.anonymous ? " _(anon)_" : ""}${notice}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Errors");
+  if (contract.errors.length === 0) {
+    lines.push("- None");
+  } else {
+    for (const e of contract.errors) lines.push(`- \`${e.name}(${e.params.join(", ")})\``);
+  }
+  lines.push("");
+
+  if (contract.modifiers.length > 0) {
+    lines.push("## Modifiers");
+    for (const m of contract.modifiers) {
+      const notice = m.natspec?.notice ? ` — ${m.natspec.notice}` : "";
+      lines.push(`- \`${m.name}(${m.params.join(", ")})\`${notice}`);
+    }
+    lines.push("");
+  }
+
+  const allExternalCalls = new Set(contract.functions.flatMap((f) => f.externalCalls));
+  if (allExternalCalls.size > 0) {
+    lines.push("## External Calls");
+    for (const call of allExternalCalls) lines.push(`- \`${call}\``);
+    lines.push("");
+  }
+
+  if (contract.functions.length > 0) {
+    lines.push("## Functions");
+    lines.push("");
+
+    const callMap = new Map(contract.functions.map((f) => [fnLabel(f), f.internalCalls]));
+
+    for (const fn of contract.functions) {
+      const label = fnLabel(fn);
+      lines.push(`### ${label}`);
+
+      const modsStr = fn.modifiers.length > 0 ? ` · modifiers: [${fn.modifiers.join(", ")}]` : "";
+      lines.push(`- visibility: ${fn.visibility} · mutability: ${fn.mutability}${modsStr}`);
+
+      const paramsStr = fn.params.length > 0 ? fn.params.join(", ") : "—";
+      const returnsStr = fn.returns.length > 0 ? `\`${fn.returns.join(", ")}\`` : "—";
+      lines.push(`- parameters: \`(${paramsStr})\` · returns: ${returnsStr}`);
+
+      if (fn.externalCalls.length > 0) {
+        lines.push(`- calls: [${fn.externalCalls.map((c) => `\`${c}\``).join(", ")}]`);
+      }
+      if (fn.internalCalls.length > 0) {
+        lines.push(`- graph: \`${fn.internalCalls.map((c) => `${label} → ${c}`).join(", ")}\``);
+      }
+
+      lines.push(`- recurse: ${hasCycle(label, label, callMap, new Set()) ? "yes ⚠" : "no"}`);
+
+      if (fn.stateReads.length > 0 || fn.stateWrites.length > 0) {
+        const reads = fn.stateReads.length > 0 ? fn.stateReads.map((r) => `\`${r}\``).join(", ") : "—";
+        const writes = fn.stateWrites.length > 0 ? fn.stateWrites.map((w) => `\`${w}\``).join(", ") : "—";
+        lines.push(`- state: reads [${reads}] · writes [${writes}]`);
+      }
+
+      lines.push(`- docs: ${renderNatSpec(fn.natspec)}`);
+      lines.push("");
+    }
+  }
+};
+
+const renderContractBrief = (contract: ContractAnalysis, imports: string[], lines: string[]) => {
+  lines.push("## Meta");
+  const inherits = contract.baseContracts.length > 0 ? `[${contract.baseContracts.join(", ")}]` : "—";
+  const importsList = imports.length > 0 ? imports.map((i) => `\`${i}\``).join(", ") : "—";
+  lines.push(`- kind: ${contract.kind} · inherits: ${inherits}`);
+  lines.push(`- imports: ${importsList}`);
+  lines.push(`- docs: ${renderNatSpec(contract.natspec)}`);
+  lines.push("");
+
+  const allExternalCalls = new Set(contract.functions.flatMap((f) => f.externalCalls));
+  if (allExternalCalls.size > 0) {
+    lines.push("## External Calls");
+    lines.push([...allExternalCalls].map((c) => `\`${c}\``).join(" · "));
+    lines.push("");
+  }
+
+  if (contract.functions.length > 0) {
+    lines.push("## Functions");
+    lines.push("| function | visibility | mutability | parameters | returns | modifiers |");
+    lines.push("|----------|------------|------------|------------|---------|-----------|");
+    for (const fn of contract.functions) {
+      const label = fnLabel(fn);
+      const params = fn.params.length > 0 ? fn.params.join(", ") : "—";
+      const returns = fn.returns.length > 0 ? fn.returns.join(", ") : "—";
+      const mods = fn.modifiers.length > 0 ? fn.modifiers.join(", ") : "—";
+      lines.push(`| \`${label}\` | ${fn.visibility} | ${fn.mutability} | ${params} | ${returns} | ${mods} |`);
+    }
+    lines.push("");
+  }
+};
+
+const fileHeader = (contracts: ContractAnalysis[], mode: "full" | "short", opts: RenderOptions): string[] => {
+  const names = contracts.map((c) => c.name).join(", ");
+  const label = mode === "full" ? "FULL" : "BRIEF";
+  const rankStr = opts.importance !== undefined ? ` | importance: ${opts.importance}/5` : "";
+  return [
+    `# ${names} · ${label}`,
+    `> path: \`${opts.filePath ?? "—"}\` | lines: ${opts.lineCount} | solc: ${opts.solcVersion}${rankStr}`,
+    "",
+  ];
+};
+
+export const generateFullMarkdown = (imports: string[], contracts: ContractAnalysis[], opts: RenderOptions): string => {
+  const lines: string[] = fileHeader(contracts, "full", opts);
+
+  for (let i = 0; i < contracts.length; i++) {
+    if (contracts.length > 1) {
+      if (i > 0) lines.push("---", "");
+      lines.push(`## ◆ ${contracts[i].name}`, "");
+    }
+    renderContractFull(contracts[i], imports, lines);
+  }
+
+  return lines.join("\n");
+};
+
+export const generateBriefMarkdown = (
+  imports: string[],
+  contracts: ContractAnalysis[],
+  opts: RenderOptions,
+): string => {
+  const lines: string[] = fileHeader(contracts, "short", opts);
+
+  for (let i = 0; i < contracts.length; i++) {
+    if (contracts.length > 1) {
+      if (i > 0) lines.push("---", "");
+      lines.push(`## ◆ ${contracts[i].name}`, "");
+    }
+    renderContractBrief(contracts[i], imports, lines);
+  }
+
+  return lines.join("\n");
+};