solidity-argus 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Solidity smart contract security auditing plugin for OpenCode — 4 specialized agents, 12 tools (11 core + optional Solodit), and a curated vulnerability knowledge base",
   "keywords": [
     "solidity",
@@ -51,6 +51,7 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.2.10",
+    "@solidity-parser/parser": "^0.20.2",
     "yaml": "^2.8.2",
     "zod": "^4.1.8"
   },

package/src/agents/argus-prompt.ts

@@ -225,6 +225,16 @@ Task(subagent_type="scribe", prompt="Generate the final audit report for Project
   \`\`\`
 - Wait for both to complete before synthesizing their results.
 
+## TASK COMPLETION TRACKING
+
+You must track which audit phases are complete to avoid redundant work and tool re-execution.
+
+- **Read the context**: At the start of each response, check the \`<argus-context>\` block injected by the system. It contains the current phase (Reconnaissance, Automated Scanning, Manual Review, etc.) and a list of completed phases.
+- **Skip completed phases**: If a phase is marked complete in the context, do NOT re-run it. Proceed directly to the next incomplete phase.
+- **Avoid tool re-execution**: If Slither, Forge, or Solodit results already appear in the \`Tools:\` section of the context, do not re-dispatch the same tool. Reference the existing results instead.
+- **Mark phase completion**: After completing a phase, explicitly state "Phase X complete" in your response before moving to the next phase. This signals to the system that the phase is done.
+- **Example flow**: If context shows "Reconnaissance: complete, Automated Scanning: complete", skip both and begin Manual Review. After Manual Review, state "Phase 3 (Manual Review) complete" before proceeding to Attack Surface Mapping.
+
 ## TOOL AWARENESS & USAGE
 
 Your subagents have access to these specialized tools. Know when to delegate each.

package/src/agents/pythia-prompt.ts

@@ -84,6 +84,16 @@ You have two primary tools. Master them.
 - Returns a list of matches with line numbers.
 - **Crucial**: You must verify the context. A regex match for \`selfdestruct\` is not a bug if it's in a test file or a legitimate upgrade mechanism (though still risky).
 
+## EMPTY RESULTS STRATEGY
+
+When \`argus_solodit_search\` returns zero results for a query:
+
+1.  **Retry with alternative keywords** (2-3 variations). Example: If "ERC4626 inflation" returns nothing, try "vault share manipulation" or "exchange rate attack".
+2.  **If still empty**, fall back to \`argus_check_patterns\` with relevant pattern categories (e.g., \`["access-control", "logic-error"]\`).
+3.  **Never report empty-handed**. Pattern-based findings are valid research output. Combine them with manual code review to provide actionable intelligence.
+
+This ensures Pythia always delivers research value, even when Solodit has no direct precedent.
+
 ## SKILLS SYSTEM
 
 OpenCode has a powerful **Skills** system that allows you to load specialized knowledge modules. The Argus knowledge base includes 75+ curated SKILL.md files, 13 YAML pattern packs, and 15 real-world exploit case studies covering $3B+ in losses.

package/src/agents/scribe-prompt.ts

@@ -57,6 +57,19 @@ If Argus passes findings in natural language (which is common), write the full r
 **Choose Approach 2 when**: Argus gives you a natural language list of findings, descriptions, and context. Just write the report.
 **Choose Approach 1 when**: You have structured JSON finding data ready to pass.
 
+## FILE PERSISTENCE
+
+**Critical Operational Block**: You must ALWAYS use the \`argus_generate_report\` tool to write the audit report to disk. This tool now automatically writes the report to the filesystem via \`Bun.write()\` and returns the file path in its result.
+
+**Your workflow**:
+1. Prepare your findings data (either structured JSON or natural language context).
+2. Call \`argus_generate_report\` with the appropriate parameters.
+3. After the tool returns, extract the \`filePath\` field from the result.
+4. **Always confirm the file path in your response to Argus**: "Report written to: {filePath}".
+5. If the result does not include a \`filePath\` field, warn Argus: "Warning: filePath missing from tool result. The report may not have been written to disk."
+
+This ensures the audit report is persisted and Argus can verify the output location.
+
 ## QUALITY STANDARDS
 
 Before generating the report, verify:

package/src/agents/sentinel-prompt.ts

@@ -31,8 +31,19 @@ You operate in a loop of **Scan -> Analyze -> Verify**.
     - Use \`argus_gas_analysis\` to identify gas-intensive functions that may indicate inefficient or vulnerable logic.
 
 4.  **Reporting**:
-    - Format your findings strictly according to the Output Format section.
-    - Report back to Argus with confirmed findings.
+     - Format your findings strictly according to the Output Format section.
+     - Report back to Argus with confirmed findings.
+
+## POC VERIFICATION
+
+After writing a Proof of Concept test to reproduce a suspected vulnerability:
+
+1.  **Always run \`argus_forge_test\`** on the PoC test file immediately after writing it.
+2.  **Report the result** to Argus: pass count, fail count, and any revert reasons.
+3.  **If the PoC fails** (test does not trigger the bug as expected), revise the test logic and retry. Do not assume the bug exists if the PoC cannot reproduce it.
+4.  **If the PoC passes**, the vulnerability is confirmed. Escalate to Argus with full details.
+
+This ensures every PoC is verified before reporting, eliminating false positives.
 
 ## TOOL USAGE GUIDE
 

package/src/config/schema.ts

@@ -31,6 +31,7 @@ const ReportingConfigSchema = z.object({
   format: z.enum(["markdown"]).default("markdown"),
   severityThreshold: z.enum(["critical", "high", "medium", "low", "informational"]).default("low"),
   gasAnalysis: z.boolean().default(false),
+  output_dir: z.string().default(".opencode/reports/"),
 })
 
 const SoloditConfigSchema = z.object({
@@ -69,6 +70,7 @@ export const ArgusConfigSchema = z.object({
     format: "markdown",
     severityThreshold: "low",
     gasAnalysis: false,
+    output_dir: ".opencode/reports/",
   }),
   solodit: SoloditConfigSchema.default({
     enabled: true,

package/src/hooks/system-prompt-hook.ts

@@ -3,6 +3,15 @@ import type { AuditState, FindingSeverity } from "../state/types"
 const DEFAULT_TOKEN_BUDGET = 2000
 const TOKENS_PER_CHAR = 4
 
+const TOOL_SHORT_NAMES: Record<string, string> = {
+  argus_slither_analyze: "slither",
+  argus_forge_test: "forge-test",
+  argus_check_patterns: "patterns",
+  argus_solodit_search: "solodit",
+  argus_analyze_contract: "analyzer",
+}
+const KEY_TOOLS = ["slither", "forge-test", "patterns", "solodit", "analyzer"]
+
 export interface SystemPromptHookDeps {
   getAuditState: () => AuditState | null
   getAgentForSession: (sessionID: string) => string | undefined
@@ -52,7 +61,13 @@ export function buildDynamicContext(
     severityCounts[finding.severity]++
   }
 
+  const executedToolNames = new Set(
+    auditState.toolsExecuted.map((t) => TOOL_SHORT_NAMES[t.tool] ?? t.tool),
+  )
   const tools = auditState.toolsExecuted.map((tool) => tool.tool).join(", ") || "none"
+  const taskStatus = KEY_TOOLS.map(
+    (t) => `${t}=${executedToolNames.has(t) ? "done" : "pending"}`,
+  ).join(" ")
   const unavailable = auditState.unavailableTools ?? []
   const lines: string[] = [
     `<argus-context agent="${agent}">`,
@@ -60,6 +75,7 @@ export function buildDynamicContext(
     `Contracts: ${auditState.contractsReviewed.length} reviewed`,
     `Findings: Critical=${severityCounts.Critical} High=${severityCounts.High} Medium=${severityCounts.Medium} Low=${severityCounts.Low} Info=${severityCounts.Informational}`,
     `Tools: ${tools}`,
+    `Tasks: ${taskStatus}`,
   ]
 
   if (unavailable.length > 0) {
@@ -72,9 +88,10 @@ export function buildDynamicContext(
   let summary = lines.join("\n")
 
   if (estimateTokens(summary) > tokenBudget) {
+    const doneCount = KEY_TOOLS.filter((t) => executedToolNames.has(t)).length
     summary = [
       `<argus-context agent="${agent}">`,
-      `Phase: ${auditState.currentPhase} | Findings: ${auditState.findings.length} | Contracts: ${auditState.contractsReviewed.length}`,
+      `Phase: ${auditState.currentPhase} | Findings: ${auditState.findings.length} | Contracts: ${auditState.contractsReviewed.length} | Tasks: ${doneCount}/${KEY_TOOLS.length} done`,
       "</argus-context>",
     ].join("\n")
   }

package/src/hooks/tool-tracking-hook.ts

@@ -321,8 +321,13 @@ export function createToolTrackingHook(
       case "argus_solodit_search":
         processSoloditResult(record, auditState)
         break
-      case "argus_forge_test":
+      case "argus_forge_test": {
+        const summary = toRecord(record.summary)
+        if (summary && typeof summary.failed === "number") {
+          findingsCount = summary.failed
+        }
         break
+      }
       case "argus_forge_fuzz":
         processFuzzResult(record, auditState)
         break

package/src/index.ts

@@ -13,7 +13,7 @@ const ArgusPlugin: Plugin = async (ctx) => {
   const config = loadArgusConfig(projectDir)
 
   if (config.solodit?.enabled !== false) {
-    startSoloditMcp(config.solodit?.port ?? 3000)
+    await startSoloditMcp(config.solodit?.port ?? 3000)
   }
 
   const isHookEnabled = createHookGuard(config.disabled_hooks)

package/src/solodit-lifecycle.ts

@@ -182,21 +182,22 @@ export async function startSoloditMcp(port: number): Promise<void> {
   soloditChild = spawnSoloditChild(port)
   trackChildExit(soloditChild)
 
-  ;(async () => {
-    const delays = [2000, 4000, 8000]
-    for (const delay of delays) {
-      await Bun.sleep(delay)
-      const health = await checkSoloditHealth(port, true)
-      if (health.reachable) {
-        soloditAvailable = true
-        logger.debug(`Solodit MCP healthy on port ${port}`)
-        return
-      }
+  const deadline = AbortSignal.timeout(5000)
+  const delays = [1000, 2000]
+  for (const delay of delays) {
+    if (deadline.aborted) break
+    await Bun.sleep(delay)
+    if (deadline.aborted) break
+    const healthResult = await checkSoloditHealth(port, true)
+    if (healthResult.reachable) {
+      soloditAvailable = true
+      logger.debug(`Solodit MCP healthy on port ${port}`)
+      break
     }
-    logger.debug(
-      `Solodit MCP not reachable after 3 retries on port ${port} — will retry on first use`,
-    )
-  })()
+  }
+  if (!soloditAvailable) {
+    logger.warn(`Solodit MCP not reachable after startup — monitoring will retry`)
+  }
 
   startMonitoring(port)
 }

package/src/tools/contract-analyzer-tool.ts

@@ -3,7 +3,7 @@ import { basename } from "node:path"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { findFoundryProjectDir } from "../shared/project-utils"
 import type { ContractProfile } from "../state/types"
-import { extractContractInfo } from "../utils/solidity-parser"
+import { extractContractInfo, parseExternalCalls } from "../utils/solidity-parser"
 
 type ContractAnalyzerArgs = {
   file_path: string
@@ -56,6 +56,24 @@ function collectRiskIndicators(source: string, existing: string[]): string[] {
   if (/\btx\.origin\b/.test(normalized)) {
     indicators.add("uses-tx-origin")
   }
+  if (/\.call\s*\{\s*value\s*:/.test(normalized)) {
+    indicators.add("uses-low-level-value-call")
+  }
+  if (normalized.includes(".call(")) {
+    indicators.add("uses-low-level-call")
+  }
+  if (normalized.includes("block.timestamp")) {
+    indicators.add("uses-block-timestamp")
+  }
+  if (normalized.includes("block.number")) {
+    indicators.add("uses-block-number")
+  }
+  if (normalized.includes("abi.encodepacked")) {
+    indicators.add("uses-abi-encode-packed")
+  }
+  if (/\becrecover\b/.test(normalized)) {
+    indicators.add("uses-ecrecover")
+  }
 
   const importLines = source
     .split("\n")
@@ -129,10 +147,74 @@ export async function executeContractAnalyzer(
       return createFailureProfile(contractName, filePath, "contract analysis aborted")
     }
 
+    const inheritanceRegex = /contract\s+(\w+)\s+is\s+([^{]+)/g
+    let sourceInheritance: string[] = []
+    let firstMatchParents: string[] | undefined
+    let regexMatch: RegExpExecArray | null = null
+
+    regexMatch = inheritanceRegex.exec(sourceText)
+    while (regexMatch !== null) {
+      const matchedName = regexMatch.at(1) ?? ""
+      const parents = (regexMatch.at(2) ?? "")
+        .split(",")
+        .map((p) => p.trim())
+        .filter(Boolean)
+
+      if (!firstMatchParents) {
+        firstMatchParents = parents
+      }
+
+      if (matchedName === contractName) {
+        sourceInheritance = parents
+        break
+      }
+
+      regexMatch = inheritanceRegex.exec(sourceText)
+    }
+
+    if (sourceInheritance.length === 0 && firstMatchParents) {
+      sourceInheritance = firstMatchParents
+    }
+
+    const mergedInheritance = [...new Set([...contractProfile.inheritance, ...sourceInheritance])]
+    const mergedExternalCalls = [
+      ...new Set([...contractProfile.externalCalls, ...parseExternalCalls(sourceText)]),
+    ]
+
+    // Extract modifiers from source text for each function
+    const visibilityKeywords = new Set([
+      "external",
+      "public",
+      "internal",
+      "private",
+      "view",
+      "pure",
+      "payable",
+      "virtual",
+      "override",
+      "returns",
+    ])
+    for (const fn of contractProfile.functions) {
+      if (!fn.name) continue
+      const escapedName = fn.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+      const fnPattern = new RegExp(`function\\s+${escapedName}\\s*\\([^)]*\\)\\s*([^{;]*)`)
+      const fnMatch = fnPattern.exec(sourceText)
+      if (!fnMatch?.[1]) continue
+
+      const afterParams = fnMatch[1]
+        .replace(/returns\s*\([^)]*\)/g, "")
+        .replace(/\([^)]*\)/g, "")
+        .trim()
+      const tokens = afterParams.match(/\b\w+\b/g) ?? []
+      fn.modifiers = tokens.filter((t) => !visibilityKeywords.has(t))
+    }
+
     return {
       ...contractProfile,
       name: contractProfile.name || contractName,
       filePath,
+      inheritance: mergedInheritance,
+      externalCalls: mergedExternalCalls,
       riskIndicators: collectRiskIndicators(sourceText, contractProfile.riskIndicators),
     }
   } catch (error) {

package/src/tools/forge-test-tool.ts

@@ -1,5 +1,6 @@
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { resolveProjectDir } from "../shared/project-utils"
+import { extractJson } from "../utils/solidity-parser"
 
 type ForgeTestArgs = {
   target?: string
@@ -106,7 +107,53 @@ function parseTests(payload: ForgeTestPayload): {
 } {
   const collected: Array<ForgeTestItem | { skipped: true }> = []
 
-  if (Array.isArray(payload.tests)) {
+  const topLevelEntries = Object.entries(payload as unknown as Record<string, unknown>)
+  if (topLevelEntries.some(([key]) => key.includes(":"))) {
+    for (const [topLevelKey, suite] of topLevelEntries) {
+      if (!suite || typeof suite !== "object") {
+        continue
+      }
+
+      const suiteRecord = suite as Record<string, unknown>
+      const testResults = suiteRecord.test_results
+      if (!testResults || typeof testResults !== "object") {
+        continue
+      }
+
+      const contract = topLevelKey.split(":").at(1) ?? topLevelKey
+      for (const [name, details] of Object.entries(testResults)) {
+        if (!details || typeof details !== "object") {
+          continue
+        }
+
+        const detailsRecord = details as Record<string, unknown>
+        const statusValue =
+          typeof detailsRecord.status === "string" ? detailsRecord.status : undefined
+        const status = mapStatus(statusValue)
+        if (status === "skip") {
+          collected.push({ skipped: true })
+          continue
+        }
+
+        const kind = detailsRecord.kind
+        const kindRecord =
+          kind && typeof kind === "object" ? (kind as Record<string, unknown>) : undefined
+        const unit = kindRecord?.Unit
+        const unitRecord =
+          unit && typeof unit === "object" ? (unit as Record<string, unknown>) : undefined
+        const fuzz = kindRecord?.Fuzz
+        const fuzzRecord =
+          fuzz && typeof fuzz === "object" ? (fuzz as Record<string, unknown>) : undefined
+
+        collected.push({
+          name,
+          contract,
+          status,
+          gas: toNumber(unitRecord?.gas ?? fuzzRecord?.mean_gas),
+        })
+      }
+    }
+  } else if (Array.isArray(payload.tests)) {
     for (const item of payload.tests) {
       const status = mapStatus(item.status)
       if (status === "skip") {
@@ -311,7 +358,7 @@ export async function executeForgeTest(
 
     let payload: ForgeTestPayload
     try {
-      payload = JSON.parse(testResult.stdout) as ForgeTestPayload
+      payload = JSON.parse(extractJson(testResult.stdout, "{")) as ForgeTestPayload
     } catch {
       return fail("Invalid JSON output from forge test")
     }

package/src/tools/pattern-checker-tool.ts

@@ -62,7 +62,7 @@ type PatternCheckDependencies = {
   ) => ScvdIndexEntry[]
 }
 
-type LoadedPattern = {
+export type LoadedPattern = {
   name: string
   category: string
   severity: Match["severity"]
@@ -70,6 +70,9 @@ type LoadedPattern = {
   description: string
   exploitReference?: string
   source?: PatternSource
+  confidence?: "High" | "Medium" | "Low"
+  applies_to?: string[]
+  exclude_if?: string[]
 }
 
 export const PATTERN_PACK_VERSION = "1.0.0"
@@ -107,6 +110,9 @@ function normalizePatternDefinitions(
     regex: new RegExp(patternDef.regex),
     description: patternDef.description,
     ...(patternDef.exploit_ref ? { exploitReference: patternDef.exploit_ref } : {}),
+    ...(patternDef.confidence ? { confidence: patternDef.confidence } : {}),
+    ...(patternDef.applies_to ? { applies_to: patternDef.applies_to } : {}),
+    ...(patternDef.exclude_if ? { exclude_if: patternDef.exclude_if } : {}),
     source,
   }))
 }
@@ -235,16 +241,27 @@ function lineWindow(content: string, index: number): [number, number] {
   return [start, end]
 }
 
-function findMatches(file: string, patterns: LoadedPattern[]): Match[] {
+export function findMatches(file: string, patterns: LoadedPattern[]): Match[] {
   const content = readFileSync(file, "utf8")
   const matches: Match[] = []
 
+  // Strip comments and string literals to reduce false positives.
+  // Use a space-preserving approach so line numbers remain valid.
+  // Order: multi-line comments first (can contain //), then single-line, then strings.
+  const stripped = content
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(/\/\/[^\n]*/g, (m) => " ".repeat(m.length))
+    .replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, (m) => {
+      const quote = m[0]
+      return `${quote}${" ".repeat(Math.max(0, m.length - 2))}${quote}`
+    })
+
   for (const pattern of patterns) {
     const regex = new RegExp(
       pattern.regex.source,
       pattern.regex.flags.includes("g") ? pattern.regex.flags : `${pattern.regex.flags}g`,
     )
-    for (const found of content.matchAll(regex)) {
+    for (const found of stripped.matchAll(regex)) {
       const index = found.index ?? 0
       matches.push({
         pattern: pattern.name,

package/src/tools/pattern-schema.ts

@@ -37,6 +37,9 @@ export const PatternDefinitionSchema = z.object({
   description: z.string().min(1),
   exploit_ref: z.string().url().optional(),
   remediation: z.string().optional(),
+  context: z.enum(["function-body", "contract-body", "file-level"]).optional(),
+  applies_to: z.array(z.string()).optional(),
+  exclude_if: z.array(z.string()).optional(),
 })
 
 export type PatternDefinition = z.infer<typeof PatternDefinitionSchema>

package/src/tools/report-generator-tool.ts

@@ -1,4 +1,9 @@
+import path from "node:path"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { loadArgusConfig } from "../config/loader"
+import type { ArgusConfig } from "../config/types"
+import { createLogger } from "../shared/logger"
+import { resolveProjectDir } from "../shared/project-utils"
 import type { AuditState, Finding, FindingSeverity } from "../state/types"
 
 type SeverityThreshold = "critical" | "high" | "medium" | "low" | "informational"
@@ -23,6 +28,11 @@ export type ReportGenerationResult = {
   report: string
   findingsCount: FindingsCount
   filename: string
+  filePath?: string
+}
+
+export type ReportGenerationDependencies = {
+  loadConfig?: (projectDir: string) => ArgusConfig
 }
 
 const SEVERITY_ORDER: FindingSeverity[] = ["Critical", "High", "Medium", "Low", "Informational"]
@@ -414,6 +424,7 @@ export function buildProvenanceAppendix(
 export async function executeReportGeneration(
   args: ReportGeneratorArgs,
   context: ToolContext,
+  deps: ReportGenerationDependencies = {},
 ): Promise<ReportGenerationResult> {
   const includeExecutiveSummary = args.include_executive_summary ?? true
   const threshold = args.severity_threshold ?? "low"
@@ -473,11 +484,31 @@ export async function executeReportGeneration(
 
   sections.push(buildProvenanceAppendix(state, threshold, findings.length))
 
-  return {
-    report: sections.join("\n\n"),
+  const reportMarkdown = sections.join("\n\n")
+  const safeName = args.project_name.replace(/[^a-zA-Z0-9-_]/g, "-")
+  const diskFilename = `${safeName}-${Date.now()}.md`
+
+  const result: ReportGenerationResult = {
+    report: reportMarkdown,
     findingsCount: counts,
     filename: `${args.project_name}-audit-report-${auditDate}.md`,
   }
+
+  try {
+    const loadConfig = deps.loadConfig ?? loadArgusConfig
+    const projectDir = resolveProjectDir(context)
+    const config = loadConfig(projectDir)
+    const outputDir = config.reporting?.output_dir ?? ".opencode/reports/"
+    const fullPath = path.join(projectDir, outputDir, diskFilename)
+    await Bun.write(fullPath, reportMarkdown)
+    result.filePath = fullPath
+  } catch (err: unknown) {
+    const logger = createLogger()
+    const message = err instanceof Error ? err.message : String(err)
+    logger.warn(`Failed to write report to disk: ${message}`)
+  }
+
+  return result
 }
 
 export const reportGeneratorTool = tool({

package/src/tools/solodit-search-tool.ts

@@ -1,6 +1,7 @@
 import type { ToolDefinition } from "@opencode-ai/plugin"
 import { type ToolContext, tool } from "@opencode-ai/plugin"
 import { createLogger } from "../shared/logger"
+import { soloditAvailable } from "../solodit-lifecycle"
 
 const logger = createLogger()
 
@@ -244,6 +245,24 @@ export async function executeSoloditSearch(
 
   context.metadata({ title: `Solodit search: ${query}` })
 
+  // Belt-and-suspenders: check if Solodit MCP is available, with 3s retry
+  // Skip check in test environment
+  if (!soloditAvailable && process.env.NODE_ENV !== "test") {
+    // Wait up to 3s for monitoring to flip the flag
+    for (let i = 0; i < 3 && !soloditAvailable; i++) {
+      await Bun.sleep(1000)
+    }
+    if (!soloditAvailable) {
+      return {
+        results: [],
+        totalFound: 0,
+        query,
+        error:
+          "Solodit MCP not available — server did not start. Results limited to local patterns.",
+      }
+    }
+  }
+
   const mcpCaller = callMcpTool ?? (hasMcpCapability(context) ? context.callMcpTool : undefined)
 
   if (!mcpCaller) {

package/src/utils/solidity-parser.ts

@@ -1,5 +1,8 @@
+import * as parser from "@solidity-parser/parser"
 import type { ContractProfile } from "../state/types"
 
+const EXTERNAL_CALL_METHODS = new Set(["call", "transfer", "send", "delegatecall", "staticcall"])
+
 interface ABIFunction {
   type: string
   name: string
@@ -24,8 +27,7 @@ interface StorageLayout {
  * prefix (e.g. forge table-format output, compilation progress).
  * Falls back to the original string if no JSON delimiter is found.
  */
-function extractJson(raw: string, opener: "[" | "{"): string {
-  const _closer = opener === "[" ? "]" : "}"
+export function extractJson(raw: string, opener: "[" | "{"): string {
   const start = raw.indexOf(opener)
   if (start === -1) return raw
 
@@ -69,6 +71,75 @@ function extractJson(raw: string, opener: "[" | "{"): string {
   return raw
 }
 
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === "object" && value !== null) {
+    return value as Record<string, unknown>
+  }
+
+  return undefined
+}
+
+function extractNodeExpressionName(node: unknown): string | undefined {
+  const record = toRecord(node)
+  if (!record) return undefined
+
+  const type = typeof record.type === "string" ? record.type : undefined
+  if (!type) return undefined
+
+  if (type === "Identifier") {
+    return typeof record.name === "string" ? record.name : undefined
+  }
+
+  if (type === "ThisExpression") {
+    return "this"
+  }
+
+  if (type === "MemberAccess") {
+    const expressionName = extractNodeExpressionName(record.expression)
+    const memberName = typeof record.memberName === "string" ? record.memberName : undefined
+
+    if (expressionName && memberName) {
+      return `${expressionName}.${memberName}`
+    }
+
+    return expressionName ?? memberName
+  }
+
+  if (type === "IndexAccess") {
+    return extractNodeExpressionName(record.base)
+  }
+
+  if (type === "FunctionCall") {
+    return extractNodeExpressionName(record.expression)
+  }
+
+  return undefined
+}
+
+export function parseExternalCalls(sourceText: string): string[] {
+  try {
+    const ast = parser.parse(sourceText, { tolerant: true, loc: false, range: false })
+    const externalCalls = new Set<string>()
+
+    parser.visit(ast, {
+      MemberAccess(node: unknown) {
+        const record = toRecord(node)
+        if (!record) return
+
+        const memberName = typeof record.memberName === "string" ? record.memberName : undefined
+        if (!memberName || !EXTERNAL_CALL_METHODS.has(memberName)) return
+
+        const expressionName = extractNodeExpressionName(record.expression)
+        externalCalls.add(expressionName ? `${expressionName}.${memberName}` : memberName)
+      },
+    })
+
+    return [...externalCalls]
+  } catch {
+    return []
+  }
+}
+
 /**
  * Extract contract information using forge inspect
  * Runs forge inspect <contractName> abi and storage-layout