solidity-argus 0.3.4 → 0.3.6

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

@@ -12,7 +12,14 @@ import type { FindingStore } from "../state/finding-store"
 import { createFindingStore } from "../state/finding-store"
 import type { AuditEvent } from "../state/schemas"
 import { SCHEMA_VERSION } from "../state/schemas"
-import type { AuditState, FindingSeverity, FuzzCounterexample, SoloditResult } from "../state/types"
+import type {
+  ArgusAgentName,
+  AuditState,
+  Finding,
+  FindingSeverity,
+  FuzzCounterexample,
+  SoloditResult,
+} from "../state/types"
 
 const logger = createLogger()
 
@@ -30,6 +37,7 @@ type ToolExecutionMetadata = {
 export type ToolTrackingOptions = {
   getEventSink?: () => EventSink | null
   getSessionId?: () => string
+  getAgentName?: () => ArgusAgentName | undefined
   dropPolicy?: DropPolicy
   onChildSessionDetected?: (parentSessionId: string, childSessionId: string) => void
 }
@@ -77,13 +85,35 @@ function toRecord(value: unknown): Record<string, unknown> | undefined {
   return undefined
 }
 
-async function emitToSink(sink: EventSink, event: AuditEvent): Promise<void> {
+function toFindingSource(value: unknown): Finding["source"] {
+  if (
+    value === "slither" ||
+    value === "manual" ||
+    value === "pattern" ||
+    value === "scvd" ||
+    value === "solodit" ||
+    value === "fuzz"
+  ) {
+    return value
+  }
+
+  return "manual"
+}
+
+async function emitToSink(
+  sink: EventSink,
+  event: AuditEvent,
+  options?: { failFast?: boolean },
+): Promise<void> {
   try {
     await sink.append(event)
   } catch (error) {
-    logger.error(
-      `Failed to emit ${event.type} event to sink: ${error instanceof Error ? error.message : String(error)}`,
-    )
+    const message = `Failed to emit ${event.type} event to sink: ${error instanceof Error ? error.message : String(error)}`
+    logger.error(message)
+
+    if (options?.failFast) {
+      throw new Error(message)
+    }
   }
 }
 
@@ -155,11 +185,13 @@ function identifyMissingFields(
 
 const SLITHER_REQUIRED = ["check", "description", "file", "lines"] as const
 const PATTERN_REQUIRED = ["pattern", "description", "file", "lines"] as const
+const MANUAL_REQUIRED = ["check", "description", "file", "lines"] as const
 
 function processSlitherResult(
   parsed: Record<string, unknown>,
   store: FindingStore,
   diag: DropDiagnosticsCollector,
+  metadata: { reportedByAgent: ArgusAgentName; reportedBySessionId: string },
 ): number {
   const findings = parsed.findings
   if (!Array.isArray(findings)) return 0
@@ -197,6 +229,8 @@ function processSlitherResult(
       file,
       lines,
       source: "slither",
+      reported_by_agent: metadata.reportedByAgent,
+      reported_by_session_id: metadata.reportedBySessionId,
     })
     count++
   }
@@ -208,6 +242,7 @@ function processPatternResult(
   parsed: Record<string, unknown>,
   store: FindingStore,
   diag: DropDiagnosticsCollector,
+  metadata: { reportedByAgent: ArgusAgentName; reportedBySessionId: string },
 ): number {
   const sources = parsed.sources
   if (!Array.isArray(sources)) return 0
@@ -252,6 +287,8 @@ function processPatternResult(
         file,
         lines,
         source: "pattern",
+        reported_by_agent: metadata.reportedByAgent,
+        reported_by_session_id: metadata.reportedBySessionId,
       })
       count++
     }
@@ -260,6 +297,89 @@ function processPatternResult(
   return count
 }
 
+function processRecordedFindingResult(
+  parsed: Record<string, unknown>,
+  store: FindingStore,
+  diag: DropDiagnosticsCollector,
+  metadata: { reportedByAgent: ArgusAgentName; reportedBySessionId: string },
+): number {
+  const findings = parsed.findings
+  if (!Array.isArray(findings)) {
+    diag.error(
+      "MISSING_REQUIRED_FIELD",
+      "argus_record_finding result missing findings array",
+      "findings",
+    )
+    return 0
+  }
+
+  let count = 0
+  for (const raw of findings) {
+    const finding = toRecord(raw)
+    if (!finding) continue
+
+    const check = finding.check
+    const description = finding.description
+    const file = finding.file
+    const lines = toLines(finding.lines)
+
+    if (
+      typeof check !== "string" ||
+      typeof description !== "string" ||
+      typeof file !== "string" ||
+      !lines
+    ) {
+      const missing = identifyMissingFields(finding, MANUAL_REQUIRED)
+      diag.error(
+        "MISSING_REQUIRED_FIELD",
+        `Recorded finding skipped: missing ${missing.join(", ")}`,
+        missing[0],
+      )
+      continue
+    }
+
+    const reportedByAgentRaw = finding.reported_by_agent
+    const reportedByAgent =
+      reportedByAgentRaw === "argus" ||
+      reportedByAgentRaw === "sentinel" ||
+      reportedByAgentRaw === "pythia" ||
+      reportedByAgentRaw === "scribe" ||
+      reportedByAgentRaw === "unknown"
+        ? (reportedByAgentRaw as ArgusAgentName)
+        : metadata.reportedByAgent
+
+    store.addFinding({
+      check,
+      severity: toSeverity(finding.severity),
+      confidence: toConfidence(finding.confidence),
+      description,
+      file,
+      lines,
+      source: toFindingSource(finding.source),
+      remediation: typeof finding.remediation === "string" ? finding.remediation : undefined,
+      exploitReference:
+        typeof finding.exploitReference === "string" ? finding.exploitReference : undefined,
+      reported_by_agent: reportedByAgent,
+      reported_by_session_id:
+        typeof finding.reported_by_session_id === "string" &&
+        finding.reported_by_session_id.length > 0
+          ? finding.reported_by_session_id
+          : metadata.reportedBySessionId,
+      issue_fingerprint:
+        typeof finding.issue_fingerprint === "string" ? finding.issue_fingerprint : undefined,
+      observation_fingerprint:
+        typeof finding.observation_fingerprint === "string"
+          ? finding.observation_fingerprint
+          : undefined,
+      observation_id:
+        typeof finding.observation_id === "string" ? finding.observation_id : undefined,
+    })
+    count++
+  }
+
+  return count
+}
+
 function processContractAnalyzerResult(parsed: Record<string, unknown>, state: AuditState): void {
   if (typeof parsed.filePath === "string") {
     if (!state.contractsReviewed.includes(parsed.filePath)) {
@@ -427,6 +547,10 @@ export function createToolTrackingHook(
 
     const resolved = resolveStateAndStore()
     if (!resolved) {
+      if (input.tool === "argus_record_finding") {
+        throw new Error("argus_record_finding requires active audit state")
+      }
+
       const sinkForNoState = options?.getEventSink?.()
       if (sinkForNoState) {
         const toolCallId = randomUUID()
@@ -453,6 +577,11 @@ export function createToolTrackingHook(
     const sink = options?.getEventSink?.()
     const runId = auditState.sessionId
     const sessionId = options?.getSessionId?.() ?? ""
+    const reportedByAgent = options?.getAgentName?.() ?? "unknown"
+    const findingMetadata = {
+      reportedByAgent,
+      reportedBySessionId: sessionId,
+    }
     const toolCallId = randomUUID()
     const policy = options?.dropPolicy ?? "warn"
     const diag = createDropDiagnosticsCollector(policy, "tool-tracking-hook", input.tool)
@@ -464,6 +593,7 @@ export function createToolTrackingHook(
           tool: input.tool,
           args: input.args,
         }),
+        { failFast: input.tool === "argus_record_finding" },
       )
     }
 
@@ -502,6 +632,9 @@ export function createToolTrackingHook(
     } catch {
       diag.error("MALFORMED_JSON", `Failed to parse JSON result from ${input.tool}`)
       lastDiagnostics = diag.getDiagnostics()
+      if (input.tool === "argus_record_finding") {
+        throw new Error("argus_record_finding returned malformed JSON")
+      }
       diag.throwIfStrict()
       return
     }
@@ -509,6 +642,9 @@ export function createToolTrackingHook(
     const record = toRecord(parsed)
     if (!record) {
       lastDiagnostics = diag.getDiagnostics()
+      if (input.tool === "argus_record_finding") {
+        throw new Error("argus_record_finding response must be a JSON object")
+      }
       return
     }
 
@@ -516,10 +652,13 @@ export function createToolTrackingHook(
 
     switch (input.tool) {
       case "argus_slither_analyze":
-        findingsCount = processSlitherResult(record, store, diag)
+        findingsCount = processSlitherResult(record, store, diag, findingMetadata)
         break
       case "argus_check_patterns":
-        findingsCount = processPatternResult(record, store, diag)
+        findingsCount = processPatternResult(record, store, diag, findingMetadata)
+        break
+      case "argus_record_finding":
+        findingsCount = processRecordedFindingResult(record, store, diag, findingMetadata)
         break
       case "argus_analyze_contract":
         processContractAnalyzerResult(record, auditState)
@@ -595,14 +734,32 @@ export function createToolTrackingHook(
     lastDiagnostics = diag.getDiagnostics()
     diag.throwIfStrict()
 
+    if (input.tool === "argus_record_finding" && findingsCount === 0) {
+      throw new Error("argus_record_finding did not persist any findings")
+    }
+
     recordToolExecution(auditState, input.tool, findingsCount)
     onStateChanged?.({ tool: input.tool, findingsCount })
 
+    if (input.tool === "argus_record_finding" && !sink) {
+      throw new Error("argus_record_finding requires an active event sink for durable persistence")
+    }
+
     if (sink) {
+      const failFast = input.tool === "argus_record_finding"
       const newFindings = auditState.findings.slice(findingsCountBefore)
-      for (const finding of newFindings) {
-        const { data: canonical } = normalizeToCanonicalFinding(finding, runId, 0)
-        await emitToSink(sink, buildEvent("finding.added", runId, sessionId, toolCallId, canonical))
+      for (const [index, finding] of newFindings.entries()) {
+        const { data: canonical } = normalizeToCanonicalFinding(finding, runId, 0, {
+          reportedByAgent,
+          reportedBySessionId: sessionId,
+          toolCallId,
+          observationId: `${toolCallId}:${index + 1}`,
+        })
+        await emitToSink(
+          sink,
+          buildEvent("finding.added", runId, sessionId, toolCallId, canonical),
+          { failFast },
+        )
       }
 
       await emitToSink(
@@ -612,6 +769,7 @@ export function createToolTrackingHook(
           findingsCount,
           success: true,
         }),
+        { failFast },
       )
     }
   }

package/src/shared/audit-artifact-resolver.ts

@@ -1,4 +1,5 @@
 import { join } from "node:path"
+import { defaultRootResolver } from "./path-root-resolver"
 
 export class ArtifactResolverError extends Error {
   constructor(message: string) {
@@ -8,19 +9,19 @@ export class ArtifactResolverError extends Error {
 }
 
 export interface AuditArtifactPaths {
-  /** {projectDir}/.opencode/argus-state.json (legacy compat) */
+  /** {projectDir}/.argus/argus-state.json */
   stateFile: string
-  /** {projectDir}/.opencode/runs/{runId}/events.jsonl */
+  /** {projectDir}/.argus/runs/{runId}/events.jsonl */
   journalFile: string
-  /** {projectDir}/.opencode/runs/{runId}/findings.json */
+  /** {projectDir}/.argus/runs/{runId}/findings.json */
   findingsFile: string
-  /** {projectDir}/.opencode/reports */
+  /** {projectDir}/.argus/reports */
   reportDir: string
-  /** {projectDir}/.opencode/runs/{runId}/evidence */
+  /** {projectDir}/.argus/runs/{runId}/evidence */
   evidenceDir: string
-  /** {projectDir}/.opencode/archives */
+  /** {projectDir}/.argus/archives */
   archiveDir: string
-  /** {projectDir}/.opencode/runs/{runId} */
+  /** {projectDir}/.argus/runs/{runId} */
   runDir: string
 }
 
@@ -45,16 +46,16 @@ export function createAuditArtifactResolver(
     throw new ArtifactResolverError("projectDir must not be empty")
   }
 
-  const opencodeDir = join(projectDir, ".opencode")
-  const runDir = join(opencodeDir, "runs", runId)
+  const writeRoot = defaultRootResolver.writeRoot(projectDir)
+  const runDir = join(writeRoot, "runs", runId)
 
   const cachedPaths: AuditArtifactPaths = {
-    stateFile: join(opencodeDir, "argus-state.json"),
+    stateFile: join(writeRoot, "argus-state.json"),
     journalFile: join(runDir, "events.jsonl"),
     findingsFile: join(runDir, "findings.json"),
-    reportDir: join(opencodeDir, "reports"),
+    reportDir: join(writeRoot, "reports"),
     evidenceDir: join(runDir, "evidence"),
-    archiveDir: join(opencodeDir, "archives"),
+    archiveDir: join(writeRoot, "archives"),
     runDir,
   }
 

package/src/shared/file-utils.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 import { stripJsoncComments } from "./jsonc-parser"
+import { defaultRootResolver } from "./path-root-resolver"
 
 export type ConfigFormat = "json" | "jsonc" | "none"
 
@@ -10,9 +11,13 @@ export interface ConfigFileInfo {
 }
 
 export function detectConfigFile(basePath: string): ConfigFileInfo {
+  const rootCandidates = defaultRootResolver.readRoots(basePath).flatMap((rootPath) => [
+    { path: join(rootPath, "solidity-argus.jsonc"), format: "jsonc" as const },
+    { path: join(rootPath, "solidity-argus.json"), format: "json" as const },
+  ])
+
   const candidates = [
-    { path: join(basePath, ".opencode", "solidity-argus.jsonc"), format: "jsonc" as const },
-    { path: join(basePath, ".opencode", "solidity-argus.json"), format: "json" as const },
+    ...rootCandidates,
     { path: join(basePath, "solidity-argus.jsonc"), format: "jsonc" as const },
     { path: join(basePath, "solidity-argus.json"), format: "json" as const },
   ]

package/src/shared/index.ts

@@ -1,3 +1,9 @@
+export {
+  ArtifactResolverError,
+  type AuditArtifactPaths,
+  type AuditArtifactResolver,
+  createAuditArtifactResolver,
+} from "./audit-artifact-resolver"
 export { extractContractNames, hasBinary, parseSolcVersion } from "./binary-utils"
 export { deepMerge } from "./deep-merge"
 export {
@@ -10,16 +16,10 @@ export { stripJsoncComments } from "./jsonc-parser"
 export { createLogger, type Logger, type LoggerConfig } from "./logger"
 export { findFoundryProjectDir, resolveProjectDir } from "./project-utils"
 export {
-  ArtifactResolverError,
-  type AuditArtifactPaths,
-  type AuditArtifactResolver,
-  createAuditArtifactResolver,
-} from "./audit-artifact-resolver"
-export {
+  formatReportDate,
   ReportPathError,
   type ReportPathOptions,
   type ResolvedReportPath,
-  formatReportDate,
-  sanitizeContractName,
   resolveReportPath,
+  sanitizeContractName,
 } from "./report-path-resolver"

package/src/shared/path-root-resolver.ts

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+
+export interface ArgusRootResolver {
+  writeRoot(projectDir: string): string
+  readRoots(projectDir: string): string[]
+  resolveReadPath(projectDir: string, relativePath: string): string | null
+}
+
+class DefaultArgusRootResolver implements ArgusRootResolver {
+  writeRoot(projectDir: string): string {
+    return join(projectDir, ".argus")
+  }
+
+  readRoots(projectDir: string): string[] {
+    return [this.writeRoot(projectDir), join(projectDir, ".opencode")]
+  }
+
+  resolveReadPath(projectDir: string, relativePath: string): string | null {
+    for (const root of this.readRoots(projectDir)) {
+      const candidatePath = join(root, relativePath)
+      if (existsSync(candidatePath)) {
+        return candidatePath
+      }
+    }
+    return null
+  }
+}
+
+export function createArgusRootResolver(): ArgusRootResolver {
+  return new DefaultArgusRootResolver()
+}
+
+export const defaultRootResolver: ArgusRootResolver = createArgusRootResolver()

package/src/shared/plugin-metadata.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+function resolvePluginVersion(): string {
+  try {
+    const currentDir = dirname(fileURLToPath(import.meta.url))
+    const packageJsonPath = resolve(currentDir, "../../package.json")
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      version?: unknown
+    }
+
+    if (typeof packageJson.version === "string" && packageJson.version.length > 0) {
+      return packageJson.version
+    }
+  } catch (_error) {
+    return "unknown"
+  }
+
+  return "unknown"
+}
+
+export const ARGUS_PLUGIN_VERSION = resolvePluginVersion()

package/src/shared/report-path-resolver.ts

@@ -30,9 +30,9 @@ export interface ResolvedReportPath {
 }
 
 export function formatReportDate(date: Date): string {
-  const year = date.getFullYear()
-  const month = String(date.getMonth() + 1).padStart(2, "0")
-  const day = String(date.getDate()).padStart(2, "0")
+  const year = date.getUTCFullYear()
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0")
+  const day = String(date.getUTCDate()).padStart(2, "0")
   return `${year}-${month}-${day}`
 }
 

package/src/state/adapters.ts

@@ -1,10 +1,11 @@
+import { computeIssueFingerprint, computeObservationFingerprint } from "./finding-fingerprint"
 import {
   type CanonicalFinding,
   SCHEMA_VERSION,
   type ValidationError,
   validateCanonicalFinding,
 } from "./schemas"
-import type { AuditPhase, Finding, FindingSeverity } from "./types"
+import type { ArgusAgentName, AuditPhase, Finding, FindingSeverity } from "./types"
 
 export interface Diagnostic {
   level: "warn" | "error"
@@ -35,6 +36,13 @@ const VALID_SOURCES: ReadonlySet<CanonicalFinding["source"]> = new Set([
   "solodit",
   "fuzz",
 ])
+const VALID_REPORTED_AGENTS: ReadonlySet<ArgusAgentName> = new Set([
+  "argus",
+  "sentinel",
+  "pythia",
+  "scribe",
+  "unknown",
+])
 
 const KNOWN_INPUT_FIELDS = new Set([
   "id",
@@ -59,9 +67,26 @@ const KNOWN_INPUT_FIELDS = new Set([
   "session_id",
   "tool_call_id",
   "schema_version",
+  "observation_id",
+  "observation_fingerprint",
+  "issue_fingerprint",
+  "reported_by_agent",
+  "reported_by_session_id",
+  "reportedByAgent",
+  "reportedBySessionId",
+  "observationId",
+  "observationFingerprint",
+  "issueFingerprint",
   "elements",
 ])
 
+export interface NormalizeFindingOptions {
+  reportedByAgent?: ArgusAgentName
+  reportedBySessionId?: string
+  toolCallId?: string
+  observationId?: string
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }
@@ -143,6 +168,7 @@ export function normalizeToCanonicalFinding(
   raw: Finding | Record<string, unknown>,
   runId: string,
   seq: number,
+  options: NormalizeFindingOptions = {},
 ): AdapterResult<CanonicalFinding> {
   const diagnostics: Diagnostic[] = []
   const input = isRecord(raw) ? raw : {}
@@ -189,11 +215,74 @@ export function normalizeToCanonicalFinding(
       ? (input.source as CanonicalFinding["source"])
       : "manual"
 
+  const reportedByAgentRaw =
+    (typeof input.reported_by_agent === "string" ? input.reported_by_agent : undefined) ??
+    (typeof input.reportedByAgent === "string" ? input.reportedByAgent : undefined) ??
+    options.reportedByAgent ??
+    "unknown"
+  const reportedByAgent: ArgusAgentName = VALID_REPORTED_AGENTS.has(
+    reportedByAgentRaw as ArgusAgentName,
+  )
+    ? (reportedByAgentRaw as ArgusAgentName)
+    : "unknown"
+
+  const reportedBySessionId =
+    (typeof input.reported_by_session_id === "string" && input.reported_by_session_id.length > 0
+      ? input.reported_by_session_id
+      : undefined) ??
+    (typeof input.reportedBySessionId === "string" && input.reportedBySessionId.length > 0
+      ? input.reportedBySessionId
+      : undefined) ??
+    options.reportedBySessionId
+
+  const issueFingerprint =
+    (typeof input.issue_fingerprint === "string" && input.issue_fingerprint.length > 0
+      ? input.issue_fingerprint
+      : undefined) ??
+    (typeof input.issueFingerprint === "string" && input.issueFingerprint.length > 0
+      ? input.issueFingerprint
+      : undefined) ??
+    computeIssueFingerprint({
+      check,
+      file,
+      lines: lines ?? [0, 0],
+      severity: VALID_SEVERITIES.has(severity) ? severity : "Informational",
+    })
+
+  const observationId =
+    (typeof input.observation_id === "string" && input.observation_id.length > 0
+      ? input.observation_id
+      : undefined) ??
+    (typeof input.observationId === "string" && input.observationId.length > 0
+      ? input.observationId
+      : undefined) ??
+    options.observationId ??
+    `${runId}:${seq}:${computeObservationFingerprint({
+      issueFingerprint,
+      source,
+      reportedByAgent,
+      toolCallId: options.toolCallId,
+      sessionId: reportedBySessionId,
+    })}`
+
+  const observationFingerprint =
+    (typeof input.observation_fingerprint === "string" && input.observation_fingerprint.length > 0
+      ? input.observation_fingerprint
+      : undefined) ??
+    (typeof input.observationFingerprint === "string" && input.observationFingerprint.length > 0
+      ? input.observationFingerprint
+      : undefined) ??
+    computeObservationFingerprint({
+      issueFingerprint,
+      source,
+      reportedByAgent,
+      toolCallId: options.toolCallId,
+      sessionId: reportedBySessionId,
+      observationId,
+    })
+
   const canonical: CanonicalFinding = {
-    id:
-      typeof input.id === "string" && input.id.length > 0
-        ? input.id
-        : `${check}:${file}:${lines?.[0] ?? 0}`,
+    id: observationId,
     check,
     severity: VALID_SEVERITIES.has(severity) ? severity : "Informational",
     confidence: VALID_CONFIDENCES.has(confidence) ? confidence : "Low",
@@ -201,6 +290,11 @@ export function normalizeToCanonicalFinding(
     file,
     lines: lines ?? [0, 0],
     source,
+    reported_by_agent: reportedByAgent,
+    reported_by_session_id: reportedBySessionId,
+    issue_fingerprint: issueFingerprint,
+    observation_fingerprint: observationFingerprint,
+    observation_id: observationId,
     remediation: typeof input.remediation === "string" ? input.remediation : undefined,
     exploitReference:
       typeof input.exploitReference === "string" ? input.exploitReference : undefined,