solidity-argus 0.3.5 → 0.3.7

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,7 +308,6 @@ export function validateCanonicalFinding(raw: unknown): ValidationResult<Canonic
   return { success: true, data: raw as unknown as CanonicalFinding }
 }
 
-
 export function validateCanonicalToolExecution(
   raw: unknown,
 ): ValidationResult<CanonicalToolExecution> {

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?: {

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)
+  },
+})

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

@@ -10,7 +10,11 @@ import { createLogger } from "../shared/logger"
 import { resolveProjectDir } from "../shared/project-utils"
 import { resolveReportPath } from "../shared/report-path-resolver"
 import { normalizeToCanonicalFinding } from "../state/adapters"
-import { stableHash } from "../state/projectors"
+import {
+  compareIssueFingerprintSets,
+  dedupeFindingsForFinalOutput,
+} from "../state/finding-aggregation"
+import { projectFindings, stableHash } from "../state/projectors"
 import { type ReportInput, SCHEMA_VERSION, validateReportInput } from "../state/schemas"
 import type { AuditState, Finding, FindingSeverity } from "../state/types"
 import { checkReportPreflight } from "./report-preflight"
@@ -40,6 +44,7 @@ export type ReportGenerationResult = {
   report: string
   findingsCount: FindingsCount
   filename: string
+  run_id: string
   contentHash: string
   qualityGates: ReportQualityValidation
   contractDiagnostics: DropDiagnostic[]
@@ -1009,7 +1014,7 @@ export function buildProvenanceAppendix(
         exec.endTime != null &&
         typeof exec.endTime === "number" &&
         !Number.isNaN(exec.endTime)
-      const duration = hasTimes ? formatDuration(exec.endTime! - exec.startTime) : "N/A"
+      const duration = hasTimes ? formatDuration((exec.endTime as number) - exec.startTime) : "N/A"
       const status =
         typeof exec.success === "boolean"
           ? exec.success
@@ -1033,7 +1038,10 @@ export function buildProvenanceAppendix(
       lines.push(`- Pattern pack version: \`${state.patternVersion}\``)
     }
     if (syncExec) {
-      const syncTime = typeof syncExec.startTime === "number" && !Number.isNaN(syncExec.startTime) ? new Date(syncExec.startTime).toISOString() : "N/A"
+      const syncTime =
+        typeof syncExec.startTime === "number" && !Number.isNaN(syncExec.startTime)
+          ? new Date(syncExec.startTime).toISOString()
+          : "N/A"
       lines.push(`- SCVD last synced: ${syncTime}`)
     }
   }
@@ -1094,6 +1102,7 @@ export async function executeReportGeneration(
   const { reportInput, diagnostics } = parseReportInputPayload(args, context)
   const preflightPolicy = args.preflight_policy ?? "warn"
   let preflightWarningSection: string | null = null
+  const warningBullets: string[] = []
   try {
     const readEventsFn = deps.readEvents ?? readEvents
     const events = await readEventsFn(reportInput.run_id, reportInput.projectDir)
@@ -1109,21 +1118,37 @@ export async function executeReportGeneration(
           parts.push(`missing required tools: ${preflightResult.missingRequiredTools.join(", ")}`)
         throw new Error(`Preflight failed (strict-fail): ${parts.join("; ")}`)
       }
-      const lines: string[] = [
-        "## \u26A0 Completeness Warning",
-        "",
-        "This report was generated with incomplete orchestration state.",
-        "",
-      ]
       if (preflightResult.orphanedTools.length > 0)
-        lines.push(`- Orphaned tools: ${preflightResult.orphanedTools.join(", ")}`)
+        warningBullets.push(`- Orphaned tools: ${preflightResult.orphanedTools.join(", ")}`)
       if (preflightResult.missingLifecycle.length > 0)
-        lines.push(`- Missing lifecycle: ${preflightResult.missingLifecycle.join(", ")}`)
+        warningBullets.push(`- Missing lifecycle: ${preflightResult.missingLifecycle.join(", ")}`)
       if (preflightResult.missingRequiredTools.length > 0)
-        lines.push(`- Missing required tools: ${preflightResult.missingRequiredTools.join(", ")}`)
+        warningBullets.push(
+          `- Missing required tools: ${preflightResult.missingRequiredTools.join(", ")}`,
+        )
       if (preflightResult.warnings.length > 0)
-        lines.push(`- Warnings: ${preflightResult.warnings.join(", ")}`)
-      preflightWarningSection = lines.join("\n")
+        warningBullets.push(`- Warnings: ${preflightResult.warnings.join(", ")}`)
+    }
+
+    const eventFindings = dedupeFindingsForFinalOutput(projectFindings(events))
+    const inputFindings = dedupeFindingsForFinalOutput(reportInput.findings)
+    const parity = compareIssueFingerprintSets(eventFindings, inputFindings)
+
+    if (!parity.matches) {
+      const mismatchSummary = `missing=${parity.missing.length}, extra=${parity.extra.length}`
+      if (preflightPolicy === "strict-fail") {
+        throw new Error(
+          `Preflight failed (strict-fail): finding parity mismatch (${mismatchSummary})`,
+        )
+      }
+
+      warningBullets.push(`- Finding parity mismatch: ${mismatchSummary}`)
+      if (parity.missing.length > 0) {
+        warningBullets.push(`- Missing issue fingerprints: ${parity.missing.join(", ")}`)
+      }
+      if (parity.extra.length > 0) {
+        warningBullets.push(`- Extra issue fingerprints: ${parity.extra.join(", ")}`)
+      }
     }
   } catch (err) {
     if (err instanceof Error && err.message.startsWith("Preflight failed (strict-fail)")) {
@@ -1134,10 +1159,22 @@ export async function executeReportGeneration(
     }
     // warn mode: skip preflight when events cannot be read
   }
+
+  if (warningBullets.length > 0) {
+    preflightWarningSection = [
+      "## \u26A0 Completeness Warning",
+      "",
+      "This report was generated with incomplete orchestration state.",
+      "",
+      ...warningBullets,
+    ].join("\n")
+  }
+
   const state = reportInputToAuditState(reportInput)
   const scope = args.scope.length > 0 ? args.scope : reportInput.scope
+  const finalFindings = dedupeFindingsForFinalOutput(reportInput.findings)
   const findings = sortFindingsDeterministically(
-    state.findings.filter((finding) => shouldIncludeFinding(finding, threshold)),
+    finalFindings.filter((finding) => shouldIncludeFinding(finding, threshold)),
   )
   const qualityGates = validateReportQuality(findings, qualityGatePolicy)
   if (!qualityGates.passed && qualityGatePolicy === "strict-fail") {
@@ -1222,6 +1259,7 @@ export async function executeReportGeneration(
     report: reportMarkdown,
     findingsCount: counts,
     filename: canonicalFilename,
+    run_id: runId,
     contentHash,
     qualityGates,
     contractDiagnostics: diagnostics,