solidity-argus 0.3.4 → 0.3.6

package/src/state/finding-aggregation.ts

@@ -0,0 +1,100 @@
+import type { CanonicalFinding } from "./schemas"
+
+const SEVERITY_RANK: Record<CanonicalFinding["severity"], number> = {
+  Critical: 0,
+  High: 1,
+  Medium: 2,
+  Low: 3,
+  Informational: 4,
+}
+
+function uniqueSorted(values: string[]): string[] {
+  return Array.from(new Set(values)).sort((left, right) => left.localeCompare(right))
+}
+
+function compareObservations(left: CanonicalFinding, right: CanonicalFinding): number {
+  if (left.seq !== right.seq) return left.seq - right.seq
+  return left.observation_id.localeCompare(right.observation_id)
+}
+
+function compareFinalFindings(left: CanonicalFinding, right: CanonicalFinding): number {
+  const bySeverity = SEVERITY_RANK[left.severity] - SEVERITY_RANK[right.severity]
+  if (bySeverity !== 0) return bySeverity
+
+  const byFile = left.file.localeCompare(right.file)
+  if (byFile !== 0) return byFile
+
+  const byLine = left.lines[0] - right.lines[0]
+  if (byLine !== 0) return byLine
+
+  return left.issue_fingerprint.localeCompare(right.issue_fingerprint)
+}
+
+export function dedupeFindingsForFinalOutput(findings: CanonicalFinding[]): CanonicalFinding[] {
+  const byIssue = new Map<string, CanonicalFinding[]>()
+  for (const finding of findings) {
+    const group = byIssue.get(finding.issue_fingerprint)
+    if (group) {
+      group.push(finding)
+    } else {
+      byIssue.set(finding.issue_fingerprint, [finding])
+    }
+  }
+
+  const merged: CanonicalFinding[] = []
+
+  for (const [issueFingerprint, observations] of byIssue.entries()) {
+    const sortedObservations = observations.slice().sort(compareObservations)
+    const base = sortedObservations[0]
+    if (!base) continue
+
+    const reportedByAgents = uniqueSorted(
+      sortedObservations.map((finding) => finding.reported_by_agent),
+    )
+    const sources = uniqueSorted(sortedObservations.map((finding) => finding.source))
+    const observationIds = sortedObservations
+      .map((finding) => finding.observation_id)
+      .sort((left, right) => left.localeCompare(right))
+
+    merged.push({
+      ...base,
+      id: issueFingerprint,
+      sources,
+      reported_by_agents: reportedByAgents,
+      observation_ids: observationIds,
+      observation_count: sortedObservations.length,
+    })
+  }
+
+  return merged.sort(compareFinalFindings)
+}
+
+export function issueFingerprintSet(findings: CanonicalFinding[]): Set<string> {
+  const set = new Set<string>()
+  for (const finding of findings) {
+    set.add(finding.issue_fingerprint)
+  }
+  return set
+}
+
+export function compareIssueFingerprintSets(
+  expected: CanonicalFinding[],
+  actual: CanonicalFinding[],
+): { missing: string[]; extra: string[]; matches: boolean } {
+  const expectedSet = issueFingerprintSet(expected)
+  const actualSet = issueFingerprintSet(actual)
+
+  const missing = Array.from(expectedSet)
+    .filter((fingerprint) => !actualSet.has(fingerprint))
+    .sort((left, right) => left.localeCompare(right))
+
+  const extra = Array.from(actualSet)
+    .filter((fingerprint) => !expectedSet.has(fingerprint))
+    .sort((left, right) => left.localeCompare(right))
+
+  return {
+    missing,
+    extra,
+    matches: missing.length === 0 && extra.length === 0,
+  }
+}

package/src/state/finding-fingerprint.ts

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto"
+import type { ArgusAgentName, FindingSeverity } from "./types"
+
+type IssueFingerprintInput = {
+  check: string
+  file: string
+  lines: [number, number]
+  severity: FindingSeverity
+}
+
+type ObservationFingerprintInput = {
+  issueFingerprint: string
+  source: string
+  reportedByAgent: ArgusAgentName
+  toolCallId?: string
+  sessionId?: string
+  observationId?: string
+}
+
+function hash(parts: string[]): string {
+  return createHash("sha256").update(parts.join("|"), "utf8").digest("hex")
+}
+
+function normalizeText(value: string): string {
+  return value.trim().toLowerCase()
+}
+
+export function computeIssueFingerprint(input: IssueFingerprintInput): string {
+  return hash([
+    normalizeText(input.check),
+    normalizeText(input.file),
+    String(input.lines[0]),
+    String(input.lines[1]),
+    input.severity,
+  ])
+}
+
+export function computeObservationFingerprint(input: ObservationFingerprintInput): string {
+  return hash([
+    input.issueFingerprint,
+    normalizeText(input.source),
+    input.reportedByAgent,
+    input.toolCallId ?? "",
+    input.sessionId ?? "",
+    input.observationId ?? "",
+  ])
+}

package/src/state/finding-store.ts

@@ -8,10 +8,6 @@ export interface FindingStore {
   serialize(): string
 }
 
-/**
- * Creates a finding store with deduplication by check+file+lines
- * Deduplication key: `${check}:${file}:${lines[0]}-${lines[1]}`
- */
 function isValidHydrationFinding(f: unknown): f is Finding {
   if (typeof f !== "object" || f === null) return false
   const obj = f as Record<string, unknown>
@@ -28,39 +24,26 @@ function isValidHydrationFinding(f: unknown): f is Finding {
 }
 
 export function createFindingStore(state: AuditState): FindingStore {
-  const findingMap = new Map<string, Finding>()
+  let observationCounter = state.findings.length
 
-  function generateId(check: string, file: string, lines: [number, number]): string {
-    const key = `${check}:${file}:${lines[0]}-${lines[1]}`
-    // Use deterministic hash for stable IDs
+  function generateObservationId(check: string, file: string, lines: [number, number]): string {
+    const key = `${check}:${file}:${lines[0]}-${lines[1]}:${observationCounter}`
+    observationCounter += 1
     return createHash("sha256").update(key).digest("hex").substring(0, 16)
   }
 
-  // Hydrate findingMap from persisted state.findings
-  for (const f of state.findings) {
-    if (!isValidHydrationFinding(f)) continue
-    const id = generateId(f.check, f.file, f.lines)
-    if (!findingMap.has(id)) {
-      findingMap.set(id, { ...f, id })
-    }
-  }
+  const hydratedFindings = state.findings.filter(isValidHydrationFinding)
 
   function addFinding(finding: Omit<Finding, "id">): Finding {
-    const id = generateId(finding.check, finding.file, finding.lines)
-
-    // Check if finding already exists (deduplication)
-    const existing = findingMap.get(id)
-    if (existing) {
-      return existing
-    }
+    const id = generateObservationId(finding.check, finding.file, finding.lines)
 
     const newFinding: Finding = {
       ...finding,
       id,
     }
 
-    findingMap.set(id, newFinding)
     state.findings.push(newFinding)
+    hydratedFindings.push(newFinding)
 
     return newFinding
   }
@@ -69,11 +52,13 @@ export function createFindingStore(state: AuditState): FindingStore {
     severity?: FindingSeverity
     source?: Finding["source"]
   }): Finding[] {
+    const findings = hydratedFindings.slice()
+
     if (!filter) {
-      return Array.from(findingMap.values())
+      return findings
     }
 
-    return Array.from(findingMap.values()).filter((finding) => {
+    return findings.filter((finding) => {
       if (filter.severity && finding.severity !== filter.severity) {
         return false
       }
@@ -85,12 +70,17 @@ export function createFindingStore(state: AuditState): FindingStore {
   }
 
   function hasFinding(check: string, file: string, lines: [number, number]): boolean {
-    const id = generateId(check, file, lines)
-    return findingMap.has(id)
+    return hydratedFindings.some(
+      (finding) =>
+        finding.check === check &&
+        finding.file === file &&
+        finding.lines[0] === lines[0] &&
+        finding.lines[1] === lines[1],
+    )
   }
 
   function serialize(): string {
-    const findings = Array.from(findingMap.values())
+    const findings = hydratedFindings.slice()
     const contractCount = state.contractsReviewed.length
     const findingCount = findings.length
 

package/src/state/projectors.ts

@@ -245,7 +245,7 @@ export function validateEventSequence(events: AuditEvent[]): void {
 export function projectFindings(events: AuditEvent[]): CanonicalFinding[] {
   validateEventSequence(events)
 
-  const byId = new Map<string, CanonicalFinding>()
+  const findings: CanonicalFinding[] = []
 
   for (const event of events) {
     if (event.type !== "finding.added") continue
@@ -258,10 +258,15 @@ export function projectFindings(events: AuditEvent[]): CanonicalFinding[] {
       )
     }
 
-    byId.set(validation.data.id, validation.data)
+    findings.push({
+      ...validation.data,
+      seq: event.seq,
+      run_id: event.run_id,
+      schema_version: event.schema_version,
+    })
   }
 
-  return Array.from(byId.values()).sort((left, right) => {
+  return findings.sort((left, right) => {
     const bySeverity = SEVERITY_RANK[left.severity] - SEVERITY_RANK[right.severity]
     if (bySeverity !== 0) return bySeverity
 
@@ -271,7 +276,16 @@ export function projectFindings(events: AuditEvent[]): CanonicalFinding[] {
     const byLine = left.lines[0] - right.lines[0]
     if (byLine !== 0) return byLine
 
-    return left.id.localeCompare(right.id)
+    const byIssue = left.issue_fingerprint.localeCompare(right.issue_fingerprint)
+    if (byIssue !== 0) return byIssue
+
+    const byObservation = left.observation_fingerprint.localeCompare(right.observation_fingerprint)
+    if (byObservation !== 0) return byObservation
+
+    const byId = left.id.localeCompare(right.id)
+    if (byId !== 0) return byId
+
+    return left.seq - right.seq
   })
 }
 

package/src/state/schemas.ts

@@ -1,4 +1,5 @@
 import type {
+  ArgusAgentName,
   AuditPhase,
   Finding,
   FindingSeverity,
@@ -7,7 +8,7 @@ import type {
   ToolExecution,
 } from "./types"
 
-export const SCHEMA_VERSION = "1.0.0"
+export const SCHEMA_VERSION = "2.0.0"
 
 export type AuditEventType =
   | "session.created"
@@ -45,6 +46,11 @@ export interface CanonicalFinding extends Finding {
   run_id: string
   seq: number
   schema_version: string
+  observation_id: string
+  issue_fingerprint: string
+  observation_fingerprint: string
+  reported_by_agent: ArgusAgentName
+  reported_by_session_id?: string
 }
 
 export interface CanonicalToolExecution extends ToolExecution {
@@ -156,6 +162,13 @@ const VALID_SOURCES: ReadonlySet<CanonicalFinding["source"]> = new Set([
   "solodit",
   "fuzz",
 ])
+const VALID_AGENTS: ReadonlySet<ArgusAgentName> = new Set([
+  "argus",
+  "sentinel",
+  "pythia",
+  "scribe",
+  "unknown",
+])
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
@@ -197,6 +210,10 @@ export function validateCanonicalFinding(raw: unknown): ValidationResult<Canonic
   pushRequiredStringError(errors, raw, "file")
   pushRequiredStringError(errors, raw, "run_id")
   pushRequiredStringError(errors, raw, "schema_version")
+  pushRequiredStringError(errors, raw, "observation_id")
+  pushRequiredStringError(errors, raw, "issue_fingerprint")
+  pushRequiredStringError(errors, raw, "observation_fingerprint")
+  pushRequiredStringError(errors, raw, "reported_by_agent")
 
   if (typeof raw.seq !== "number" || !Number.isInteger(raw.seq) || raw.seq < 0) {
     errors.push({
@@ -253,6 +270,37 @@ export function validateCanonicalFinding(raw: unknown): ValidationResult<Canonic
     })
   }
 
+  if (
+    typeof raw.reported_by_agent !== "string" ||
+    !VALID_AGENTS.has(raw.reported_by_agent as ArgusAgentName)
+  ) {
+    errors.push({
+      field: "reported_by_agent",
+      code: "enum",
+      message: "reported_by_agent must be one of: argus, sentinel, pythia, scribe, unknown",
+    })
+  }
+
+  if (
+    raw.reported_by_session_id != null &&
+    (typeof raw.reported_by_session_id !== "string" ||
+      raw.reported_by_session_id.trim().length === 0)
+  ) {
+    errors.push({
+      field: "reported_by_session_id",
+      code: "invalid",
+      message: "reported_by_session_id must be a non-empty string when provided",
+    })
+  }
+
+  if (raw.schema_version !== SCHEMA_VERSION) {
+    errors.push({
+      field: "schema_version",
+      code: "version_mismatch",
+      message: `schema_version must be ${SCHEMA_VERSION}`,
+    })
+  }
+
   if (errors.length > 0) {
     return { success: false, errors }
   }
@@ -260,6 +308,90 @@ export function validateCanonicalFinding(raw: unknown): ValidationResult<Canonic
   return { success: true, data: raw as unknown as CanonicalFinding }
 }
 
+export function validateCanonicalToolExecution(
+  raw: unknown,
+): ValidationResult<CanonicalToolExecution> {
+  if (!isRecord(raw)) {
+    return {
+      success: false,
+      errors: [
+        {
+          field: "$root",
+          code: "type",
+          message: "canonical tool execution must be an object",
+        },
+      ],
+    }
+  }
+
+  const errors: ValidationError[] = []
+
+  if (typeof raw.tool !== "string" || raw.tool.trim().length === 0) {
+    errors.push({
+      field: "tool",
+      code: "required",
+      message: "tool is required and must be a non-empty string",
+    })
+  }
+
+  if (typeof raw.startTime !== "number" || !Number.isInteger(raw.startTime) || raw.startTime <= 0) {
+    errors.push({
+      field: "startTime",
+      code: "invalid",
+      message: "startTime must be a positive integer",
+    })
+  }
+
+  if (raw.endTime != null && (typeof raw.endTime !== "number" || !Number.isInteger(raw.endTime))) {
+    errors.push({
+      field: "endTime",
+      code: "invalid",
+      message: "endTime must be an integer when provided",
+    })
+  }
+
+  if (typeof raw.success !== "boolean") {
+    errors.push({
+      field: "success",
+      code: "required",
+      message: "success is required and must be a boolean",
+    })
+  }
+
+  if (
+    typeof raw.findingsCount !== "number" ||
+    !Number.isInteger(raw.findingsCount) ||
+    raw.findingsCount < 0
+  ) {
+    errors.push({
+      field: "findingsCount",
+      code: "invalid",
+      message: "findingsCount must be a non-negative integer",
+    })
+  }
+
+  if (typeof raw.run_id !== "string" || raw.run_id.trim().length === 0) {
+    errors.push({
+      field: "run_id",
+      code: "required",
+      message: "run_id is required and must be a non-empty string",
+    })
+  }
+
+  if (typeof raw.schema_version !== "string" || raw.schema_version.trim().length === 0) {
+    errors.push({
+      field: "schema_version",
+      code: "required",
+      message: "schema_version is required and must be a non-empty string",
+    })
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors }
+  }
+
+  return { success: true, data: raw as unknown as CanonicalToolExecution }
+}
 export function validateReportInput(raw: unknown): ValidationResult<ReportInput> {
   if (!isRecord(raw)) {
     return {
@@ -306,6 +438,18 @@ export function validateReportInput(raw: unknown): ValidationResult<ReportInput>
       code: "invalid",
       message: "toolsExecuted must be an array",
     })
+  } else {
+    for (const [index, entry] of raw.toolsExecuted.entries()) {
+      const toolValidation = validateCanonicalToolExecution(entry)
+      if (toolValidation.success) continue
+      for (const toolError of toolValidation.errors) {
+        errors.push({
+          field: `toolsExecuted[${index}].${toolError.field}`,
+          code: toolError.code,
+          message: toolError.message,
+        })
+      }
+    }
   }
 
   if (raw.patternVersion != null && typeof raw.patternVersion !== "string") {

package/src/state/types.ts

@@ -1,4 +1,5 @@
 export type FindingSeverity = "Critical" | "High" | "Medium" | "Low" | "Informational"
+export type ArgusAgentName = "argus" | "sentinel" | "pythia" | "scribe" | "unknown"
 export type AuditPhase =
   | "reconnaissance"
   | "scanning"
@@ -10,7 +11,7 @@ export type AuditPhase =
   | "complete"
 
 export interface Finding {
-  id: string // unique hash: check+file+lines
+  id: string
   check: string // detector name e.g. "reentrancy-eth"
   severity: FindingSeverity
   confidence: "High" | "Medium" | "Low"
@@ -18,6 +19,15 @@ export interface Finding {
   file: string // relative file path
   lines: [number, number] // [start, end]
   source: "slither" | "manual" | "pattern" | "scvd" | "solodit" | "fuzz"
+  reported_by_agent?: ArgusAgentName
+  reported_by_session_id?: string
+  issue_fingerprint?: string
+  observation_fingerprint?: string
+  observation_id?: string
+  observation_ids?: string[]
+  reported_by_agents?: string[]
+  sources?: string[]
+  observation_count?: number
   remediation?: string
   exploitReference?: string
   provenance?: {
@@ -110,4 +120,10 @@ export interface PersistentAuditState extends AuditState {
   savedAt: number
   version: string
   filePath: string
+  /** Whether this snapshot was projected from events or loaded from a prior snapshot */
+  source_of_truth?: "events" | "snapshot"
+  /** Sequence number of the last event included in this snapshot */
+  last_event_seq?: number
+  /** Hash of the event stream for staleness detection */
+  event_stream_hash?: string
 }

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

@@ -0,0 +1,125 @@
+import { type ToolContext, tool } from "@opencode-ai/plugin"
+import { normalizeToCanonicalFinding } from "../state/adapters"
+import { SCHEMA_VERSION } from "../state/schemas"
+import type { ArgusAgentName } from "../state/types"
+
+type RecordFindingArgs = {
+  finding?: string
+  findings?: string
+}
+
+type RecordFindingResponse = {
+  success: boolean
+  count: number
+  findings: ReturnType<typeof normalizeToCanonicalFinding>["data"][]
+  schema_version: string
+}
+
+function parseFindingObject(raw: string, label: "finding" | "findings"): Record<string, unknown>[] {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new 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 [parsed as Record<string, unknown>]
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw new Error("findings must be a JSON array")
+  }
+
+  return parsed.filter(
+    (item): item is Record<string, unknown> =>
+      typeof item === "object" && item !== null && !Array.isArray(item),
+  )
+}
+
+function normalizeAgent(value: string): ArgusAgentName {
+  if (value === "argus" || value === "sentinel" || value === "pythia" || value === "scribe") {
+    return value
+  }
+
+  return "unknown"
+}
+
+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 (typeof args.findings === "string" && args.findings.trim().length > 0) {
+    rawFindings.push(...parseFindingObject(args.findings, "findings"))
+  }
+
+  if (rawFindings.length === 0) {
+    throw new Error("Provide at least one finding via finding or findings")
+  }
+
+  const reportedByAgent = normalizeAgent(context.agent)
+  const reportedBySessionId = context.sessionID
+  const runId = context.sessionID || "manual-run"
+
+  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 diagnosticsErrors = normalized.diagnostics.filter((diag) => diag.level === "error")
+    if (diagnosticsErrors.length > 0) {
+      errors.push(
+        ...diagnosticsErrors.map(
+          (diag) => `[index:${index}] ${diag.field ?? "$root"}: ${diag.message}`,
+        ),
+      )
+      continue
+    }
+
+    findings.push(normalized.data)
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Failed to record finding(s): ${errors.join("; ")}`)
+  }
+
+  const response: RecordFindingResponse = {
+    success: true,
+    count: findings.length,
+    findings,
+    schema_version: SCHEMA_VERSION,
+  }
+
+  return JSON.stringify(response)
+}
+
+export const recordFindingTool = tool({
+  description:
+    "Record manually identified findings in canonical format for durable event-backed tracking.",
+  args: {
+    finding: tool.schema
+      .string()
+      .optional()
+      .describe("Serialized JSON object containing a single finding payload."),
+    findings: tool.schema
+      .string()
+      .optional()
+      .describe("Serialized JSON array containing one or more finding payload objects."),
+  },
+  async execute(args, context) {
+    return executeRecordFinding(args, context)
+  },
+})