solidity-argus 0.3.7 → 0.5.6

package/src/tools/read-findings-tool.ts

@@ -0,0 +1,390 @@
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { mkdir, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { createAuditArtifactResolver } from "../shared/audit-artifact-resolver"
+import { createLogger } from "../shared/logger"
+import { defaultRootResolver } from "../shared/path-root-resolver"
+import { resolveProjectDir } from "../shared/project-utils"
+import type { CanonicalFinding, CanonicalToolExecution, ReportInput } from "../state/schemas"
+import { SCHEMA_VERSION } from "../state/schemas"
+import type { AuditState } from "../state/types"
+
+type ReadFindingsArgs = {
+  run_id: string
+}
+
+type ReportFinding = Omit<
+  CanonicalFinding,
+  | "run_id"
+  | "seq"
+  | "schema_version"
+  | "observation_id"
+  | "issue_fingerprint"
+  | "observation_fingerprint"
+  | "reported_by_agent"
+  | "reported_by_session_id"
+>
+
+type ReportToolExecution = Omit<CanonicalToolExecution, "run_id" | "schema_version">
+
+type CompactReportInput = Omit<
+  ReportInput,
+  | "findings"
+  | "toolsExecuted"
+  | "run_id"
+  | "seq"
+  | "session_id"
+  | "tool_call_id"
+  | "source"
+  | "schema_version"
+> & {
+  run_id: string
+  findings: ReportFinding[]
+  toolsExecuted: ReportToolExecution[]
+}
+
+type ReadFindingsInlineResult = {
+  success: boolean
+  truncated: false
+  source: "report-input.json"
+  reportInput: CompactReportInput
+}
+
+type ReadFindingsFileResult = {
+  success: boolean
+  truncated: true
+  source: "report-input.json"
+  compactReportInputFile: string
+  summary: {
+    run_id: string
+    findingsCount: number
+    toolsExecutedCount: number
+    scope: string[]
+    severityDistribution: Record<string, number>
+    topFindings: Array<{ title: string; severity: string; category: string }>
+  }
+  instructions: string
+}
+
+export type ReadFindingsResult = ReadFindingsInlineResult | ReadFindingsFileResult
+
+/**
+ * OpenCode truncates plugin tool output above ~50KB (exact threshold unknown,
+ * but observed at 122KB). We use 40KB as a safe ceiling to avoid truncation.
+ */
+const OUTPUT_SIZE_THRESHOLD_BYTES = 40_000
+
+const FINDING_INTERNAL_KEYS: ReadonlySet<string> = new Set([
+  "run_id",
+  "seq",
+  "schema_version",
+  "observation_id",
+  "issue_fingerprint",
+  "observation_fingerprint",
+  "reported_by_agent",
+  "reported_by_session_id",
+])
+
+const TOOL_EXECUTION_INTERNAL_KEYS: ReadonlySet<string> = new Set(["run_id", "schema_version"])
+
+function stripInternalKeys(obj: object, keysToStrip: ReadonlySet<string>): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(obj)) {
+    if (!keysToStrip.has(key)) {
+      result[key] = value
+    }
+  }
+  return result
+}
+
+function buildCompactInput(reportInput: ReportInput): CompactReportInput {
+  return {
+    run_id: reportInput.run_id,
+    projectDir: reportInput.projectDir,
+    findings: reportInput.findings.map(
+      (f) => stripInternalKeys(f, FINDING_INTERNAL_KEYS) as ReportFinding,
+    ),
+    toolsExecuted: reportInput.toolsExecuted.map(
+      (t) => stripInternalKeys(t, TOOL_EXECUTION_INTERNAL_KEYS) as ReportToolExecution,
+    ),
+    scope: reportInput.scope,
+    ...(reportInput.soloditResults && { soloditResults: reportInput.soloditResults }),
+    ...(reportInput.fuzzCounterexamples && {
+      fuzzCounterexamples: reportInput.fuzzCounterexamples,
+    }),
+    ...(reportInput.coverageReport && { coverageReport: reportInput.coverageReport }),
+    ...(reportInput.gasHotspots && { gasHotspots: reportInput.gasHotspots }),
+    ...(reportInput.proxyContracts && { proxyContracts: reportInput.proxyContracts }),
+    ...(reportInput.patternVersion && { patternVersion: reportInput.patternVersion }),
+    ...(reportInput.skillsLoaded && { skillsLoaded: reportInput.skillsLoaded }),
+  }
+}
+
+function buildSeverityDistribution(findings: ReportFinding[]): Record<string, number> {
+  const dist: Record<string, number> = {}
+  for (const f of findings) {
+    const sev = (f as Record<string, unknown>).severity as string | undefined
+    const key = sev ?? "Unknown"
+    dist[key] = (dist[key] ?? 0) + 1
+  }
+  return dist
+}
+
+function buildTopFindings(
+  findings: ReportFinding[],
+  limit = 10,
+): Array<{ title: string; severity: string; category: string }> {
+  const severityOrder: Record<string, number> = {
+    Critical: 0,
+    High: 1,
+    Medium: 2,
+    Low: 3,
+    Informational: 4,
+  }
+  const sorted = [...findings].sort((a, b) => {
+    const ra = a as Record<string, unknown>
+    const rb = b as Record<string, unknown>
+    const sa = severityOrder[(ra.severity as string) ?? ""] ?? 5
+    const sb = severityOrder[(rb.severity as string) ?? ""] ?? 5
+    return sa - sb
+  })
+  return sorted.slice(0, limit).map((f) => {
+    const r = f as Record<string, unknown>
+    return {
+      title: (r.title as string) ?? (r.description as string)?.slice(0, 80) ?? "Untitled",
+      severity: (r.severity as string) ?? "Unknown",
+      category: (r.category as string) ?? "Unknown",
+    }
+  })
+}
+
+function convertAuditStateToReportInput(
+  state: AuditState,
+  runId: string,
+  projectDir: string,
+): ReportInput {
+  const findings: CanonicalFinding[] = (state.findings ?? []).map((f, i) => ({
+    ...f,
+    run_id: state.sessionId ?? runId,
+    seq: i + 1,
+    session_id: "audit",
+    tool_call_id: "",
+    source: f.source ?? ("unknown" as const),
+    schema_version: SCHEMA_VERSION,
+    issue_fingerprint: f.id ?? "",
+    observation_fingerprint: f.id ?? "",
+    observation_id: f.id ?? "",
+    reported_by_agent: f.reported_by_agent ?? ("unknown" as const),
+    reported_by_session_id: f.reported_by_session_id ?? "",
+  }))
+
+  return {
+    run_id: state.sessionId ?? runId,
+    seq: findings.length,
+    session_id: "audit",
+    tool_call_id: "",
+    source: "audit-state",
+    schema_version: SCHEMA_VERSION,
+    projectDir: state.projectDir ?? projectDir,
+    findings,
+    toolsExecuted: (state.toolsExecuted ?? []).map((t) => ({
+      ...t,
+      run_id: state.sessionId ?? runId,
+      schema_version: SCHEMA_VERSION,
+    })),
+    scope: state.scope?.length
+      ? state.scope
+      : [...new Set(findings.map((f) => f.file).filter(Boolean))],
+    soloditResults: state.soloditResults,
+    fuzzCounterexamples: state.fuzzCounterexamples,
+    coverageReport: state.coverageReport,
+    gasHotspots: state.gasHotspots,
+    proxyContracts: state.proxyContracts,
+  }
+}
+
+/**
+ * Scan .argus/sessions/ for the newest state file with findings.
+ * Mirrors the fallback logic in audit-state-manager.ts load().
+ */
+function readNewestSessionState(argusRoot: string): AuditState | null {
+  const sessionsDir = join(argusRoot, "sessions")
+  try {
+    const entries = readdirSync(sessionsDir)
+    const stateFiles = entries.filter((e) => e.startsWith("state-") && e.endsWith(".json"))
+    if (stateFiles.length === 0) return null
+
+    const ranked = stateFiles
+      .map((name) => {
+        const filePath = join(sessionsDir, name)
+        try {
+          return { name, path: filePath, mtime: statSync(filePath).mtimeMs }
+        } catch {
+          return null
+        }
+      })
+      .filter((entry): entry is NonNullable<typeof entry> => entry !== null)
+      .sort((a, b) => b.mtime - a.mtime)
+
+    for (const entry of ranked) {
+      try {
+        const state = JSON.parse(readFileSync(entry.path, "utf8")) as AuditState
+        if (state.findings && state.findings.length > 0) {
+          return state
+        }
+      } catch {
+        /* skip unreadable files */
+      }
+    }
+  } catch {
+    /* sessions dir doesn't exist */
+  }
+  return null
+}
+
+function readAuditStateAsReportInput(projectDir: string, runId: string): ReportInput {
+  const logger = createLogger()
+  const argusRoot = defaultRootResolver.writeRoot(projectDir)
+
+  const dedupedFile = createAuditArtifactResolver(runId, projectDir).paths().dedupedFindingsFile
+  try {
+    const dedupedRaw = JSON.parse(readFileSync(dedupedFile, "utf8")) as {
+      findings?: unknown[]
+      run_id?: string
+    }
+    if (Array.isArray(dedupedRaw.findings) && dedupedRaw.findings.length > 0) {
+      logger.debug(`Loaded deduped findings from: ${dedupedFile}`)
+
+      const perRunFile = createAuditArtifactResolver(runId, projectDir).paths().reportInputFile
+      let baseReportInput: Partial<ReportInput> = {}
+      try {
+        baseReportInput = JSON.parse(readFileSync(perRunFile, "utf8")) as Partial<ReportInput>
+      } catch {}
+
+      return {
+        ...baseReportInput,
+        run_id: dedupedRaw.run_id ?? runId,
+        findings: dedupedRaw.findings as CanonicalFinding[],
+        toolsExecuted: baseReportInput.toolsExecuted ?? [],
+        scope: baseReportInput.scope ?? [],
+        projectDir: baseReportInput.projectDir ?? projectDir,
+        seq: 0,
+        session_id: "audit",
+        tool_call_id: "",
+        source: "deduped-findings",
+        schema_version: SCHEMA_VERSION,
+      } as ReportInput
+    }
+  } catch {
+    logger.debug(`No deduped findings at ${dedupedFile}`)
+  }
+
+  // 1. Per-run report-input artifact (materialized by findings-materializer into runs/{runId}/)
+  const perRunFile = createAuditArtifactResolver(runId, projectDir).paths().reportInputFile
+  try {
+    const data = JSON.parse(readFileSync(perRunFile, "utf8")) as ReportInput
+    if (data.findings && data.findings.length > 0) {
+      logger.debug(`Loaded report-input from per-run artifact: ${perRunFile}`)
+      return data
+    }
+  } catch {
+    logger.debug(`No per-run report-input at ${perRunFile}`)
+  }
+
+  // 2. Flat report-input at argus root (legacy location)
+  const flatFile = join(argusRoot, "report-input.json")
+  try {
+    const data = JSON.parse(readFileSync(flatFile, "utf8")) as ReportInput
+    if (data.findings && data.findings.length > 0) {
+      logger.debug(`Loaded report-input from flat file: ${flatFile}`)
+      return data
+    }
+  } catch {
+    logger.debug(`No flat report-input at ${flatFile}`)
+  }
+
+  // 3. Per-session state files (per-session managers write to sessions/state-{sessionId}.json)
+  const sessionState = readNewestSessionState(argusRoot)
+  if (sessionState) {
+    logger.debug("Loaded audit state from newest session state file")
+    return convertAuditStateToReportInput(sessionState, runId, projectDir)
+  }
+
+  // 4. Shared audit state (legacy fallback)
+  const sharedStateFile = join(argusRoot, "argus-state.json")
+  try {
+    const state = JSON.parse(readFileSync(sharedStateFile, "utf8")) as AuditState
+    if (state.findings && state.findings.length > 0) {
+      logger.debug(`Loaded audit state from shared file: ${sharedStateFile}`)
+      return convertAuditStateToReportInput(state, runId, projectDir)
+    }
+  } catch {
+    /* shared state not available */
+  }
+
+  throw new Error(
+    `Cannot read findings from any source for run ${runId}. Checked: per-run artifact (${perRunFile}), flat file (${flatFile}), session state files, shared state (${sharedStateFile})`,
+  )
+}
+
+export async function executeReadFindings(
+  args: ReadFindingsArgs,
+  context: ToolContext,
+): Promise<string> {
+  const runId = args.run_id
+  if (!runId || runId.trim().length === 0) {
+    throw new Error("run_id is required")
+  }
+
+  const projectDir = resolveProjectDir(context)
+  const reportInput = readAuditStateAsReportInput(projectDir, runId)
+  const compactInput = buildCompactInput(reportInput)
+
+  const inlineJson = JSON.stringify({
+    success: true,
+    truncated: false,
+    source: "report-input.json" as const,
+    reportInput: compactInput,
+  })
+
+  if (Buffer.byteLength(inlineJson, "utf-8") <= OUTPUT_SIZE_THRESHOLD_BYTES) {
+    return inlineJson
+  }
+
+  const resolver = createAuditArtifactResolver(runId, projectDir)
+  const compactFilePath = resolver
+    .paths()
+    .reportInputFile.replace("report-input.json", "compact-report-input.json")
+  await mkdir(dirname(compactFilePath), { recursive: true })
+  await writeFile(compactFilePath, JSON.stringify(compactInput, null, 2))
+
+  const fileResult: ReadFindingsFileResult = {
+    success: true,
+    truncated: true,
+    source: "report-input.json",
+    compactReportInputFile: compactFilePath,
+    summary: {
+      run_id: runId,
+      findingsCount: compactInput.findings.length,
+      toolsExecutedCount: compactInput.toolsExecuted.length,
+      scope: compactInput.scope,
+      severityDistribution: buildSeverityDistribution(compactInput.findings),
+      topFindings: buildTopFindings(compactInput.findings),
+    },
+    instructions: `Output exceeds safe inline size (${Buffer.byteLength(inlineJson, "utf-8")} bytes). Full compact data written to: ${compactFilePath}. Use the read tool to access the file contents before generating the report.`,
+  }
+
+  return JSON.stringify(fileResult)
+}
+
+export const readFindingsTool = tool({
+  description:
+    "Read the materialized ReportInput artifact from disk for a given run. Returns the canonical findings, tools executed, scope, and all enrichment data. Scribe should call this before generating the report.",
+  args: {
+    run_id: tool.schema.string().describe("The run ID to read findings for."),
+  },
+  async execute(args, context) {
+    return executeReadFindings(args, context)
+  },
+})

package/src/tools/record-finding-tool.ts

@@ -1,4 +1,5 @@
 import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { isNonEmptyString } from "../shared/type-guards"
 import { normalizeToCanonicalFinding } from "../state/adapters"
 import { SCHEMA_VERSION } from "../state/schemas"
 import type { ArgusAgentName } from "../state/types"
@@ -11,33 +12,47 @@ type RecordFindingArgs = {
 type RecordFindingResponse = {
   success: boolean
   count: number
-  findings: ReturnType<typeof normalizeToCanonicalFinding>["data"][]
+  findings: Array<{
+    id: string
+    check: string
+    severity: string
+    file: string
+    description: string
+    lines: [number, number]
+    source: string
+  }>
   schema_version: string
+  note: string
 }
 
-function parseFindingObject(raw: string, label: "finding" | "findings"): Record<string, unknown>[] {
+type ParseResult = { ok: true; data: Record<string, unknown>[] } | { ok: false; error: string }
+
+function parseFindingObject(raw: string, label: "finding" | "findings"): ParseResult {
   let parsed: unknown
   try {
     parsed = JSON.parse(raw)
   } catch {
-    throw new Error(`${label} must be valid JSON`)
+    return { ok: false, error: `${label} must be valid JSON` }
   }
 
   if (label === "finding") {
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-      throw new Error("finding must be a JSON object")
+      return { ok: false, error: "finding must be a JSON object" }
     }
-    return [parsed as Record<string, unknown>]
+    return { ok: true, data: [parsed as Record<string, unknown>] }
   }
 
   if (!Array.isArray(parsed)) {
-    throw new Error("findings must be a JSON array")
+    return { ok: false, error: "findings must be a JSON array" }
   }
 
-  return parsed.filter(
-    (item): item is Record<string, unknown> =>
-      typeof item === "object" && item !== null && !Array.isArray(item),
-  )
+  return {
+    ok: true,
+    data: parsed.filter(
+      (item): item is Record<string, unknown> =>
+        typeof item === "object" && item !== null && !Array.isArray(item),
+    ),
+  }
 }
 
 function normalizeAgent(value: string): ArgusAgentName {
@@ -48,36 +63,80 @@ function normalizeAgent(value: string): ArgusAgentName {
   return "unknown"
 }
 
+function errorResponse(error: string): string {
+  return JSON.stringify({
+    success: false,
+    count: 0,
+    findings: [],
+    schema_version: SCHEMA_VERSION,
+    note: error,
+    error,
+  })
+}
+
 export async function executeRecordFinding(
   args: RecordFindingArgs,
   context: ToolContext,
 ): Promise<string> {
   const rawFindings: Record<string, unknown>[] = []
 
-  if (typeof args.finding === "string" && args.finding.trim().length > 0) {
-    rawFindings.push(...parseFindingObject(args.finding, "finding"))
+  if (isNonEmptyString(args.finding)) {
+    const result = parseFindingObject(args.finding, "finding")
+    if (!result.ok) return errorResponse(result.error)
+    rawFindings.push(...result.data)
   }
-  if (typeof args.findings === "string" && args.findings.trim().length > 0) {
-    rawFindings.push(...parseFindingObject(args.findings, "findings"))
+  if (isNonEmptyString(args.findings)) {
+    const result = parseFindingObject(args.findings, "findings")
+    if (!result.ok) return errorResponse(result.error)
+    rawFindings.push(...result.data)
   }
 
   if (rawFindings.length === 0) {
-    throw new Error("Provide at least one finding via finding or findings")
+    return errorResponse("Provide at least one finding via finding or findings")
+  }
+
+  for (const f of rawFindings) {
+    if (!f.check && typeof f.title === "string") f.check = f.title
+    if (!f.check && typeof f.name === "string") f.check = f.name
+    if (!f.file && typeof f.location === "string") {
+      const loc = f.location as string
+      const colonIdx = loc.lastIndexOf(":")
+      if (colonIdx > 0 && /^\d+(-\d+)?$/.test(loc.substring(colonIdx + 1))) {
+        f.file = loc.substring(0, colonIdx)
+        if (!f.lines) {
+          const match = loc.substring(colonIdx + 1).match(/^(\d+)(?:-(\d+))?$/)
+          if (match)
+            f.lines = [
+              Number.parseInt(match[1] ?? "0", 10),
+              Number.parseInt(match[2] ?? match[1] ?? "0", 10),
+            ]
+        }
+      } else {
+        f.file = loc
+      }
+    }
   }
 
   const reportedByAgent = normalizeAgent(context.agent)
   const reportedBySessionId = context.sessionID
-  const runId = context.sessionID || "manual-run"
+  const runId = "tool-local"
+  const projectDir = context.directory ?? process.cwd()
 
   const findings: ReturnType<typeof normalizeToCanonicalFinding>["data"][] = []
   const errors: string[] = []
 
   for (const [index, rawFinding] of rawFindings.entries()) {
-    const normalized = normalizeToCanonicalFinding(rawFinding, runId, index + 1, {
-      reportedByAgent,
-      reportedBySessionId,
-      observationId: `${reportedBySessionId}:${index + 1}`,
-    })
+    const normalized = normalizeToCanonicalFinding(
+      rawFinding,
+      runId,
+      index + 1,
+      {
+        reportedByAgent,
+        reportedBySessionId,
+        observationId: `${reportedBySessionId}:${index + 1}`,
+      },
+      projectDir,
+    )
 
     const diagnosticsErrors = normalized.diagnostics.filter((diag) => diag.level === "error")
     if (diagnosticsErrors.length > 0) {
@@ -93,14 +152,46 @@ export async function executeRecordFinding(
   }
 
   if (errors.length > 0) {
-    throw new Error(`Failed to record finding(s): ${errors.join("; ")}`)
+    return errorResponse(`Failed to record finding(s): ${errors.join("; ")}`)
+  }
+
+  // Warn when Critical/High findings are missing enrichment fields
+  const enrichmentWarnings: string[] = []
+  const HIGH_SEVERITIES = new Set(["Critical", "High"])
+  for (const f of findings) {
+    if (!HIGH_SEVERITIES.has(f.severity)) continue
+    const missing: string[] = []
+    if (!f.impact) missing.push("impact")
+    if (!f.recommendation) missing.push("recommendation")
+    if (!f.proofOfConcept) missing.push("proofOfConcept")
+    if (missing.length > 0) {
+      enrichmentWarnings.push(
+        `[${f.severity}] ${f.check} in ${f.file} is missing: ${missing.join(", ")}. Quality gate will flag this.`,
+      )
+    }
   }
 
   const response: RecordFindingResponse = {
     success: true,
     count: findings.length,
-    findings,
+    findings: findings.map((f) => ({
+      id: f.id,
+      check: f.check,
+      severity: f.severity,
+      file: f.file,
+      description: f.description,
+      lines: f.lines,
+      source: f.source,
+    })),
     schema_version: SCHEMA_VERSION,
+    note: "Findings recorded to event journal. The system assigns the canonical run_id automatically — use the run_id from <argus-context> for Scribe dispatch.",
+    ...(enrichmentWarnings.length > 0
+      ? {
+          enrichment_warnings: enrichmentWarnings,
+          enrichment_hint:
+            "Critical and High findings MUST include impact, recommendation, and proofOfConcept fields. Re-submit with these fields to pass the quality gate.",
+        }
+      : {}),
   }
 
   return JSON.stringify(response)
@@ -113,11 +204,15 @@ export const recordFindingTool = tool({
     finding: tool.schema
       .string()
       .optional()
-      .describe("Serialized JSON object containing a single finding payload."),
+      .describe(
+        'Serialized JSON object for a single finding. Required fields: check (string, e.g. "reentrancy-eth"), severity (Critical|High|Medium|Low|Informational), confidence (High|Medium|Low), description (string), file (relative path, e.g. "src/Vault.sol"), lines ([startLine, endLine] tuple), source ("manual"). Optional: impact, recommendation, proofOfConcept (mandatory for Critical/High).',
+      ),
     findings: tool.schema
       .string()
       .optional()
-      .describe("Serialized JSON array containing one or more finding payload objects."),
+      .describe(
+        "Serialized JSON array of finding objects. Each object requires the same fields as the finding parameter: check, severity, confidence, description, file, lines, source. Aliases title/name → check and location → file are accepted but canonical names are preferred.",
+      ),
   },
   async execute(args, context) {
     return executeRecordFinding(args, context)