solidity-argus 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solidity-argus",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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",

package/src/agents/scribe-prompt.ts

@@ -8,7 +8,7 @@ Your core responsibilities are:
 1.  **Aggregation**: Collecting findings from various tools and subagents.
 2.  **Deduplication**: Merging similar findings (e.g., multiple Slither warnings for the same issue).
 3.  **Contextualization**: Explaining *why* a finding matters in the context of the specific protocol.
-4.  **Report Generation**: Producing the final Markdown artifact using \`argus_generate_report\`.
+4.  **Report Generation**: Producing the final Markdown artifact and writing it to disk.
 
 ## REPORT STRUCTURE
 
@@ -41,34 +41,13 @@ You must adhere to these strict writing standards:
 
 ## HOW TO GENERATE THE REPORT
 
-You have two approaches. Use whichever fits the input you receive from Argus.
-
-### Approach 1: Use \`argus_generate_report\` tool
-If you have structured findings data, call the tool:
--   \`project_name\` (string): The name of the protocol or project.
--   \`scope\` (string[]): List of files or contracts that were audited.
--   \`include_executive_summary\` (boolean): Default \`true\`.
--   \`severity_threshold\` (string): "critical", "high", "medium", "low", or "informational". Usually "low" or "informational" to include everything.
--   \`audit_state\` (string): JSON string of findings. Format each finding as: \`{"id":"f1","check":"name","severity":"High","confidence":"High","description":"...","file":"Contract.sol","lines":[1,10],"source":"manual"}\`
-
-### Approach 2: Write the report directly as Markdown
-If Argus passes findings in natural language (which is common), write the full report yourself in Markdown following the Report Structure below. This is often faster and produces better results than trying to serialize findings into JSON for the tool.
-
-**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.
+Argus passes you findings in natural language. Write the full report yourself in Markdown following the Report Structure above.
 
 **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.
+1. Read the findings Argus provides. Deduplicate, cross-reference, and assess severity.
+2. Write the complete report in Markdown following the Report Structure and Output Format sections.
+3. Save the report to disk using the \`write\` tool. Path: \`.opencode/reports/{ProjectName}-audit-{YYYY-MM-DD}.md\` relative to the project root.
+4. Confirm the file path in your response to Argus: "Report written to: {filePath}".
 
 ## QUALITY STANDARDS
 

package/src/create-hooks.ts

@@ -176,11 +176,16 @@ export function createHooks(args: {
       }
 
       if (type === "session.deleted") {
+        await debouncedSave.flush()
+        if (auditState) {
+          await auditStateManager.save(auditState)
+        }
+        await auditStateManager.archive()
+
         if (sessionId) {
           agentTracker.clearSession(sessionId)
         }
 
-        await auditStateManager.archive()
         runJournal.log({
           type: "session.deleted",
           timestamp: Date.now(),

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

@@ -84,6 +84,118 @@ function emptyAuditState(findings: Finding[] = []): AuditState {
   }
 }
 
+/**
+ * Parse a location string like "File.sol:18-22" or "File.sol:18" into { file, lines }.
+ * Returns undefined if the string doesn't match a recognized format.
+ */
+export function parseLocationString(
+  location: string,
+): { file: string; lines: [number, number] } | undefined {
+  // "File.sol:18-22" or "File.sol:L18-L22"
+  const rangeMatch = location.match(/^(.+?):L?(\d+)\s*-\s*L?(\d+)$/)
+  if (rangeMatch) {
+    const file = rangeMatch.at(1)
+    const start = rangeMatch.at(2)
+    const end = rangeMatch.at(3)
+    if (file && start && end) {
+      return { file, lines: [Number(start), Number(end)] }
+    }
+  }
+  // "File.sol:18"
+  const singleMatch = location.match(/^(.+?):L?(\d+)$/)
+  if (singleMatch) {
+    const file = singleMatch.at(1)
+    const lineNum = singleMatch.at(2)
+    if (file && lineNum) {
+      const n = Number(lineNum)
+      return { file, lines: [n, n] }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Normalize a raw finding object from agent output into the canonical field format.
+ * Handles common aliases:
+ *   - title/name → check
+ *   - location (string) → file + lines
+ *   - case-insensitive severity → capitalized
+ */
+export function normalizeRawFinding(raw: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...raw }
+
+  // check: accept title, name as aliases
+  if (typeof result.check !== "string" || (result.check as string).length === 0) {
+    const alias = result.title ?? result.name
+    if (typeof alias === "string" && alias.length > 0) {
+      result.check = alias
+    }
+  }
+
+  // file + lines: accept location string as alias
+  if (typeof result.file !== "string" && typeof result.location === "string") {
+    const parsed = parseLocationString(result.location as string)
+    if (parsed) {
+      result.file = parsed.file
+      if (!Array.isArray(result.lines) || (result.lines as unknown[]).length !== 2) {
+        result.lines = parsed.lines
+      }
+    }
+  }
+
+  // lines: accept [start] as [start, start], accept line_start/line_end
+  if (!Array.isArray(result.lines) || (result.lines as unknown[]).length !== 2) {
+    if (Array.isArray(result.lines) && (result.lines as unknown[]).length === 1) {
+      const n = Number((result.lines as unknown[])[0])
+      if (!Number.isNaN(n)) {
+        result.lines = [n, n]
+      }
+    } else if (typeof result.line_start === "number" && typeof result.line_end === "number") {
+      result.lines = [result.line_start, result.line_end]
+    } else if (typeof result.line === "number") {
+      result.lines = [result.line, result.line]
+    }
+  }
+
+  // severity: case-insensitive normalization
+  if (typeof result.severity === "string") {
+    const lower = (result.severity as string).toLowerCase()
+    const SEVERITY_MAP: Record<string, string> = {
+      critical: "Critical",
+      high: "High",
+      medium: "Medium",
+      low: "Low",
+      informational: "Informational",
+      info: "Informational",
+    }
+    const mapped = SEVERITY_MAP[lower]
+    if (mapped) {
+      result.severity = mapped
+    }
+  }
+
+  // confidence: case-insensitive normalization
+  if (typeof result.confidence === "string") {
+    const lower = (result.confidence as string).toLowerCase()
+    const CONFIDENCE_MAP: Record<string, string> = {
+      high: "High",
+      medium: "Medium",
+      low: "Low",
+    }
+    const mapped = CONFIDENCE_MAP[lower]
+    if (mapped) {
+      result.confidence = mapped
+    }
+  }
+
+  // description: fall back to check if missing
+  if (typeof result.description !== "string" && typeof result.check === "string") {
+    result.description = result.check
+  }
+
+  return result
+}
+
 function hasMinimumFindingFields(
   f: unknown,
 ): f is { check: string; file: string; lines: [number, number] } {
@@ -153,10 +265,22 @@ export function parseAuditState(auditState: string): AuditState {
     )
   }
 
+  const logger = createLogger()
+
   if (Array.isArray(parsed)) {
-    const validFindings = (parsed as unknown[])
+    const rawItems = parsed as unknown[]
+    const normalized = rawItems
+      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
+      .map((item) => normalizeRawFinding(item))
+    const validFindings = normalized
       .filter(hasMinimumFindingFields)
       .map((f) => normalizeFinding(f as Record<string, unknown>))
+    const dropped = rawItems.length - validFindings.length
+    if (dropped > 0) {
+      logger.warn(
+        `parseAuditState: ${dropped}/${rawItems.length} findings dropped (missing required fields after normalization)`,
+      )
+    }
     return emptyAuditState(validFindings)
   }
 
@@ -166,9 +290,19 @@ export function parseAuditState(auditState: string): AuditState {
     Array.isArray((parsed as AuditState).findings)
   ) {
     const state = parsed as AuditState
-    const validFindings = state.findings
+    const rawFindings = state.findings as unknown[]
+    const normalized = rawFindings
+      .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
+      .map((item) => normalizeRawFinding(item))
+    const validFindings = normalized
       .filter(hasMinimumFindingFields)
-      .map((f) => normalizeFinding(f as unknown as Record<string, unknown>))
+      .map((f) => normalizeFinding(f as Record<string, unknown>))
+    const dropped = rawFindings.length - validFindings.length
+    if (dropped > 0) {
+      logger.warn(
+        `parseAuditState: ${dropped}/${rawFindings.length} findings dropped (missing required fields after normalization)`,
+      )
+    }
     return {
       ...emptyAuditState(),
       ...state,