solidity-argus 0.3.3 → 0.3.5

package/src/features/migration/parity-telemetry.ts

@@ -0,0 +1,133 @@
+import { stableHash } from "../../state/projectors"
+import type { CanonicalFinding } from "../../state/schemas"
+import type { Finding, FindingSeverity } from "../../state/types"
+
+const SEVERITIES: readonly FindingSeverity[] = [
+  "Critical",
+  "High",
+  "Medium",
+  "Low",
+  "Informational",
+] as const
+
+export interface SeverityDistribution {
+  Critical: number
+  High: number
+  Medium: number
+  Low: number
+  Informational: number
+}
+
+export interface ParityMetrics {
+  legacyFindingCount: number
+  canonicalFindingCount: number
+  findingCountDiff: number
+  legacySeverityDistribution: SeverityDistribution
+  canonicalSeverityDistribution: SeverityDistribution
+  severityDiffs: Partial<Record<FindingSeverity, number>>
+  legacyContentHash: string
+  canonicalContentHash: string
+  hashMatch: boolean
+  onlyInLegacy: string[]
+  onlyInCanonical: string[]
+  timestamp: number
+}
+
+function computeSeverityDistribution(
+  findings: Array<{ severity: FindingSeverity }>,
+): SeverityDistribution {
+  const dist: SeverityDistribution = {
+    Critical: 0,
+    High: 0,
+    Medium: 0,
+    Low: 0,
+    Informational: 0,
+  }
+  for (const f of findings) {
+    if (f.severity in dist) {
+      dist[f.severity]++
+    }
+  }
+  return dist
+}
+
+function findingIds(findings: Array<{ id: string }>): Set<string> {
+  return new Set(findings.map((f) => f.id))
+}
+
+export function computeParityMetrics(
+  legacyFindings: Finding[],
+  canonicalFindings: CanonicalFinding[],
+): ParityMetrics {
+  const legacySeverity = computeSeverityDistribution(legacyFindings)
+  const canonicalSeverity = computeSeverityDistribution(canonicalFindings)
+
+  const severityDiffs: Partial<Record<FindingSeverity, number>> = {}
+  for (const sev of SEVERITIES) {
+    const diff = canonicalSeverity[sev] - legacySeverity[sev]
+    if (diff !== 0) {
+      severityDiffs[sev] = diff
+    }
+  }
+
+  const legacyIds = findingIds(legacyFindings)
+  const canonicalIds = findingIds(canonicalFindings)
+
+  const onlyInLegacy = [...legacyIds].filter((id) => !canonicalIds.has(id))
+  const onlyInCanonical = [...canonicalIds].filter((id) => !legacyIds.has(id))
+
+  const legacyContentHash = stableHash(
+    legacyFindings.map((f) => ({ id: f.id, check: f.check, severity: f.severity, file: f.file })),
+  )
+  const canonicalContentHash = stableHash(
+    canonicalFindings.map((f) => ({
+      id: f.id,
+      check: f.check,
+      severity: f.severity,
+      file: f.file,
+    })),
+  )
+
+  return {
+    legacyFindingCount: legacyFindings.length,
+    canonicalFindingCount: canonicalFindings.length,
+    findingCountDiff: canonicalFindings.length - legacyFindings.length,
+    legacySeverityDistribution: legacySeverity,
+    canonicalSeverityDistribution: canonicalSeverity,
+    severityDiffs,
+    legacyContentHash,
+    canonicalContentHash,
+    hashMatch: legacyContentHash === canonicalContentHash,
+    onlyInLegacy,
+    onlyInCanonical,
+    timestamp: Date.now(),
+  }
+}
+
+export function formatParityReport(metrics: ParityMetrics): string {
+  const lines: string[] = [
+    "=== Migration Parity Report ===",
+    `Finding count: legacy=${metrics.legacyFindingCount} canonical=${metrics.canonicalFindingCount} diff=${metrics.findingCountDiff}`,
+    `Content hash match: ${metrics.hashMatch}`,
+  ]
+
+  const sevDiffs = Object.entries(metrics.severityDiffs)
+  if (sevDiffs.length > 0) {
+    lines.push(
+      `Severity diffs: ${sevDiffs.map(([k, v]) => `${k}=${v > 0 ? "+" : ""}${v}`).join(", ")}`,
+    )
+  }
+
+  if (metrics.onlyInLegacy.length > 0) {
+    lines.push(
+      `Only in legacy (${metrics.onlyInLegacy.length}): ${metrics.onlyInLegacy.join(", ")}`,
+    )
+  }
+  if (metrics.onlyInCanonical.length > 0) {
+    lines.push(
+      `Only in canonical (${metrics.onlyInCanonical.length}): ${metrics.onlyInCanonical.join(", ")}`,
+    )
+  }
+
+  return lines.join("\n")
+}

package/src/features/persistent-state/audit-state-manager.ts

@@ -2,10 +2,10 @@ import { mkdir, rename } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import type { AuditStateManager } from "../../managers/types"
 import { createLogger } from "../../shared/logger"
+import { type ArgusRootResolver, defaultRootResolver } from "../../shared/path-root-resolver"
 import { createAuditState } from "../../state/audit-state"
 import type { AuditState, PersistentAuditState } from "../../state/types"
 
-const STATE_FILE_DIR = ".opencode"
 const STATE_FILE_NAME = "argus-state.json"
 const STATE_VERSION = "2"
 
@@ -95,14 +95,21 @@ export function createDebouncedSave(
   }
 }
 
-export function createAuditStateManager(projectDir: string): AuditStateManager {
+export function createAuditStateManager(
+  projectDir: string,
+  resolver: ArgusRootResolver = defaultRootResolver,
+): AuditStateManager {
   const logger = createLogger()
-  const stateFilePath = join(projectDir, STATE_FILE_DIR, STATE_FILE_NAME)
+
+  const stateFilePath = join(resolver.writeRoot(projectDir), STATE_FILE_NAME)
   let currentState: AuditState = createAuditState(projectDir).state
 
   async function load(): Promise<AuditState | null> {
     try {
-      const file = Bun.file(stateFilePath)
+      const resolvedPath = resolver.resolveReadPath(projectDir, STATE_FILE_NAME)
+      const readPath = resolvedPath ?? stateFilePath
+
+      const file = Bun.file(readPath)
       if (!(await file.exists())) {
         return null
       }
@@ -114,11 +121,19 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
 
       const parsed: unknown = JSON.parse(content)
       if (!isPersistentAuditState(parsed)) {
-        logger.warn("Persistent audit state is invalid, ignoring", stateFilePath)
+        logger.warn("Persistent audit state is invalid, ignoring", readPath)
         return null
       }
 
-      const { savedAt: _savedAt, version, filePath: _filePath, ...state } = parsed
+      const {
+        savedAt: _savedAt,
+        version,
+        filePath: _filePath,
+        source_of_truth: _sourceOfTruth,
+        last_event_seq: snapshotSeq,
+        event_stream_hash: _eventStreamHash,
+        ...state
+      } = parsed
 
       if (version === "1") {
         if (!state.soloditResults) {
@@ -129,6 +144,11 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
         }
       }
 
+
+      if (snapshotSeq !== undefined) {
+        logger.debug(`Loaded snapshot with last_event_seq=${snapshotSeq} from ${readPath}`)
+      }
+
       currentState = state
       return currentState
     } catch (err) {
@@ -154,6 +174,7 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
           savedAt: Date.now(),
           version: STATE_VERSION,
           filePath: stateFilePath,
+          source_of_truth: "events",
         }
 
         const tempFilePath = `${stateFilePath}.${Date.now()}.tmp`
@@ -205,6 +226,7 @@ export function createAuditStateManager(projectDir: string): AuditStateManager {
           savedAt: Date.now(),
           version: STATE_VERSION,
           filePath: archivePath,
+          source_of_truth: "events",
         }
         await Bun.write(archivePath, `${JSON.stringify(persistentState, null, 2)}\n`)
       } catch {

package/src/features/persistent-state/event-sink.ts

@@ -0,0 +1,175 @@
+import { mkdir, rename } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import {
+  type ArgusRootResolver,
+  defaultRootResolver,
+} from "../../shared/path-root-resolver"
+import type { AuditEvent, AuditEventType } from "../../state/schemas"
+
+export type EventSinkErrorCode = "SEQUENCE_CONFLICT" | "INVALID_EVENT" | "IO_ERROR"
+
+export class EventSinkError extends Error {
+  readonly code: EventSinkErrorCode
+
+  constructor(code: EventSinkErrorCode, message: string) {
+    super(message)
+    this.name = "EventSinkError"
+    this.code = code
+  }
+}
+
+export interface EventSink {
+  append(event: AuditEvent): Promise<void>
+  readAll(): Promise<AuditEvent[]>
+}
+
+const VALID_EVENT_TYPES: ReadonlySet<string> = new Set<AuditEventType>([
+  "session.created",
+  "session.idle",
+  "session.deleted",
+  "tool.started",
+  "tool.completed",
+  "finding.added",
+  "phase.changed",
+  "run.finalized",
+])
+
+function createMutex() {
+  let chain = Promise.resolve()
+
+  return {
+    async run<T>(fn: () => Promise<T>): Promise<T> {
+      const prev = chain
+      let release!: () => void
+      chain = new Promise<void>((r) => {
+        release = r
+      })
+
+      await prev
+
+      try {
+        return await fn()
+      } finally {
+        release()
+      }
+    },
+  }
+}
+
+function buildJournalPath(runId: string, projectDir: string, resolver: ArgusRootResolver): string {
+  return join(resolver.writeRoot(projectDir), "runs", runId, "events.jsonl")
+}
+
+async function readRawContent(path: string): Promise<string> {
+  const file = Bun.file(path)
+  if (!(await file.exists())) {
+    return ""
+  }
+  return file.text()
+}
+
+function parseJournalLines(content: string): AuditEvent[] {
+  if (!content.trim()) return []
+
+  const lines = content.split("\n").filter(Boolean)
+  const events: AuditEvent[] = []
+
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line) as AuditEvent)
+    } catch {
+      /* skip malformed lines */
+    }
+  }
+
+  events.sort((a, b) => a.seq - b.seq)
+  return events
+}
+
+/**
+ * Replay-safe stateless read — returns all events for a run sorted by seq.
+ */
+export async function readEvents(runId: string, projectDir: string, resolver: ArgusRootResolver = defaultRootResolver): Promise<AuditEvent[]> {
+  const journalPath = buildJournalPath(runId, projectDir, resolver)
+  const content = await readRawContent(journalPath)
+  return parseJournalLines(content)
+}
+
+/**
+ * Append-only event sink with monotonic seq allocation, in-process mutex,
+ * and atomic temp-file-then-rename writes. Restart-safe via journal replay.
+ */
+export function createEventSink(runId: string, projectDir: string, resolver: ArgusRootResolver = defaultRootResolver): EventSink {
+  const journalPath = buildJournalPath(runId, projectDir, resolver)
+  const mutex = createMutex()
+  let lastSeq = 0
+  let initialized = false
+
+  async function ensureInitialized(): Promise<void> {
+    if (initialized) return
+
+    try {
+      const content = await readRawContent(journalPath)
+      const events = parseJournalLines(content)
+      const lastEvent = events.at(-1)
+      if (lastEvent) {
+        lastSeq = lastEvent.seq
+      }
+    } catch (err) {
+      throw new EventSinkError("IO_ERROR", `Failed to initialize event sink: ${String(err)}`)
+    }
+
+    initialized = true
+  }
+
+  return {
+    async append(event: AuditEvent): Promise<void> {
+      return mutex.run(async () => {
+        await ensureInitialized()
+
+        if (event.run_id !== runId) {
+          throw new EventSinkError(
+            "INVALID_EVENT",
+            `Event run_id "${event.run_id}" does not match sink run_id "${runId}"`,
+          )
+        }
+
+        if (!event.type || !VALID_EVENT_TYPES.has(event.type)) {
+          throw new EventSinkError("INVALID_EVENT", `Invalid event type "${String(event.type)}"`)
+        }
+
+        if (event.seq > 0 && event.seq <= lastSeq) {
+          throw new EventSinkError(
+            "SEQUENCE_CONFLICT",
+            `Event seq ${event.seq} conflicts with last assigned seq ${lastSeq}; must be > ${lastSeq}`,
+          )
+        }
+
+        const nextSeq = lastSeq + 1
+        const eventToWrite: AuditEvent = { ...event, seq: nextSeq }
+
+        const currentContent = await readRawContent(journalPath)
+        const newContent = `${currentContent}${JSON.stringify(eventToWrite)}\n`
+
+        await mkdir(dirname(journalPath), { recursive: true })
+
+        const suffix = `${Date.now()}.${Math.random().toString(36).slice(2)}`
+        const tempPath = `${journalPath}.${suffix}.tmp`
+
+        try {
+          await Bun.write(tempPath, newContent)
+          await rename(tempPath, journalPath)
+        } catch (err) {
+          throw new EventSinkError("IO_ERROR", `Failed to write event to journal: ${String(err)}`)
+        }
+
+        lastSeq = nextSeq
+      })
+    },
+
+    async readAll(): Promise<AuditEvent[]> {
+      const content = await readRawContent(journalPath)
+      return parseJournalLines(content)
+    },
+  }
+}

package/src/features/persistent-state/findings-materializer.ts

@@ -0,0 +1,51 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import { dirname } from "node:path"
+import { createAuditArtifactResolver } from "../../shared/audit-artifact-resolver"
+import { projectFindings, projectToolExecutions, stableHash } from "../../state/projectors"
+import type { CanonicalFinding, CanonicalToolExecution } from "../../state/schemas"
+import { SCHEMA_VERSION } from "../../state/schemas"
+import { readEvents } from "./event-sink"
+
+export interface FindingsArtifact {
+  run_id: string
+  session_id: string
+  schema_version: string
+  seq_first: number
+  seq_last: number
+  event_count: number
+  content_hash: string
+  generated_at: number
+  findings: CanonicalFinding[]
+  toolsExecuted: CanonicalToolExecution[]
+}
+
+export async function materializeFindings(
+  runId: string,
+  projectDir: string,
+  sessionId?: string,
+): Promise<FindingsArtifact> {
+  const events = await readEvents(runId, projectDir)
+  const findings = projectFindings(events)
+  const toolsExecuted = projectToolExecutions(events)
+  const contentHash = stableHash(JSON.stringify(findings))
+  const generatedAt = events.at(-1)?.timestamp ?? 0
+
+  const artifact: FindingsArtifact = {
+    run_id: runId,
+    session_id: sessionId ?? events[0]?.session_id ?? "",
+    schema_version: SCHEMA_VERSION,
+    seq_first: events[0]?.seq ?? 0,
+    seq_last: events.at(-1)?.seq ?? 0,
+    event_count: events.length,
+    content_hash: contentHash,
+    generated_at: generatedAt,
+    findings,
+    toolsExecuted,
+  }
+
+  const findingsFile = createAuditArtifactResolver(runId, projectDir).paths().findingsFile
+  await mkdir(dirname(findingsFile), { recursive: true })
+  await writeFile(findingsFile, JSON.stringify(artifact, null, 2))
+
+  return artifact
+}

package/src/features/persistent-state/index.ts

@@ -1 +1,3 @@
 export { createAuditStateManager } from "./audit-state-manager"
+export type { EventSink, EventSinkErrorCode } from "./event-sink"
+export { createEventSink, EventSinkError, readEvents } from "./event-sink"

package/src/features/persistent-state/run-finalizer.ts

@@ -0,0 +1,192 @@
+import { validateEventSequence } from "../../state/projectors"
+import type { AuditEvent } from "../../state/schemas"
+import { SCHEMA_VERSION } from "../../state/schemas"
+import type { EventSink } from "./event-sink"
+import { readEvents } from "./event-sink"
+
+export type FinalizationResult = {
+  success: boolean
+  invariantsPassed: boolean
+  errors: string[]
+  runId: string
+  timestamp: number
+}
+
+export function hasSessionCreated(events: AuditEvent[]): boolean {
+  return events.some((event) => event.type === "session.created")
+}
+
+export function hasSessionDeleted(events: AuditEvent[]): boolean {
+  return events.some((event) => event.type === "session.deleted")
+}
+
+export type ToolLifecycleCheckResult = {
+  orphanedToolCallIds: string[]
+  malformedEvents: string[]
+}
+
+export function collectToolLifecycleIssues(events: AuditEvent[]): ToolLifecycleCheckResult {
+  const startedCallIds = new Set<string>()
+  const completedCallIds = new Set<string>()
+  const malformedEvents: string[] = []
+
+  for (const event of events) {
+    if (event.type !== "tool.started" && event.type !== "tool.completed") {
+      continue
+    }
+
+    if (typeof event.tool_call_id !== "string" || event.tool_call_id.length === 0) {
+      malformedEvents.push(`${event.type} at seq ${event.seq} missing tool_call_id`)
+      continue
+    }
+
+    if (event.type === "tool.started") {
+      startedCallIds.add(event.tool_call_id)
+    }
+
+    if (event.type === "tool.completed") {
+      completedCallIds.add(event.tool_call_id)
+    }
+  }
+
+  const orphanedToolCallIds: string[] = []
+  for (const toolCallId of startedCallIds) {
+    if (!completedCallIds.has(toolCallId)) {
+      orphanedToolCallIds.push(toolCallId)
+    }
+  }
+
+  return {
+    orphanedToolCallIds,
+    malformedEvents,
+  }
+}
+
+function collectOrphanedToolStarts(events: AuditEvent[]): string[] {
+  const { orphanedToolCallIds, malformedEvents } = collectToolLifecycleIssues(events)
+  const orphanedErrors = orphanedToolCallIds.map(
+    (toolCallId) => `orphaned tool.started without matching tool.completed: ${toolCallId}`,
+  )
+  return [...malformedEvents, ...orphanedErrors]
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return null
+}
+
+function collectParentChildIntegrityErrors(events: AuditEvent[]): string[] {
+  const errors: string[] = []
+  const parentByChild = new Map<string, string>()
+  const correlationByChild = new Map<string, string>()
+
+  for (const event of events) {
+    const payload = asRecord(event.payload)
+    if (!payload) {
+      continue
+    }
+
+    const childSessionId = payload.child_session_id
+    if (typeof childSessionId !== "string" || childSessionId.length === 0) {
+      continue
+    }
+
+    const parentSessionId = event.session_id
+    if (!parentSessionId) {
+      errors.push(`child session edge at seq ${event.seq} missing parent session_id`)
+      continue
+    }
+
+    if (parentSessionId === childSessionId) {
+      errors.push(`child session edge at seq ${event.seq} is self-referential`)
+    }
+
+    const correlationId = payload.correlation_id
+    if (typeof correlationId !== "string" || correlationId.length === 0) {
+      errors.push(`child session edge at seq ${event.seq} missing correlation_id`)
+      continue
+    }
+
+    const existingParent = parentByChild.get(childSessionId)
+    if (existingParent && existingParent !== parentSessionId) {
+      errors.push(
+        `child session ${childSessionId} mapped to multiple parents: ${existingParent}, ${parentSessionId}`,
+      )
+    } else {
+      parentByChild.set(childSessionId, parentSessionId)
+    }
+
+    const existingCorrelation = correlationByChild.get(childSessionId)
+    if (existingCorrelation && existingCorrelation !== correlationId) {
+      errors.push(
+        `child session ${childSessionId} has inconsistent correlation_id: ${existingCorrelation}, ${correlationId}`,
+      )
+    } else {
+      correlationByChild.set(childSessionId, correlationId)
+    }
+  }
+
+  return errors
+}
+
+function collectInvariantErrors(events: AuditEvent[]): string[] {
+  const errors: string[] = []
+
+  try {
+    validateEventSequence(events)
+  } catch (error) {
+    errors.push(`invalid event sequence: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  if (!hasSessionCreated(events)) {
+    errors.push("missing required lifecycle event: session.created")
+  }
+
+  if (!hasSessionDeleted(events)) {
+    errors.push("missing required lifecycle event: session.deleted")
+  }
+
+  errors.push(...collectOrphanedToolStarts(events))
+  errors.push(...collectParentChildIntegrityErrors(events))
+  return errors
+}
+
+export async function finalizeRun(
+  runId: string,
+  projectDir: string,
+  sink: EventSink | null,
+): Promise<FinalizationResult> {
+  const timestamp = Date.now()
+  const events = sink ? await sink.readAll() : await readEvents(runId, projectDir)
+  const errors = collectInvariantErrors(events)
+  const invariantsPassed = errors.length === 0
+  const sessionId = events.at(-1)?.session_id ?? ""
+
+  if (sink) {
+    await sink.append({
+      type: "run.finalized",
+      run_id: runId,
+      seq: 0,
+      session_id: sessionId,
+      source: "run-finalizer",
+      schema_version: SCHEMA_VERSION,
+      timestamp,
+      payload: {
+        finalized: invariantsPassed,
+        invariantsPassed,
+        errors,
+        status: invariantsPassed ? "finalized" : "failed-finalization",
+      },
+    })
+  }
+
+  return {
+    success: invariantsPassed,
+    invariantsPassed,
+    errors,
+    runId,
+    timestamp,
+  }
+}

package/src/features/persistent-state/run-journal.ts

@@ -1,10 +1,13 @@
 import { appendFile, mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
+import {
+  type ArgusRootResolver,
+  defaultRootResolver,
+} from "../../shared/path-root-resolver"
 import { createLogger } from "../../shared/logger"
 
 const logger = createLogger()
 
-const JOURNAL_DIR = ".opencode"
 const JOURNAL_FILE = "argus-journal.jsonl"
 
 export type JournalEvent =
@@ -15,7 +18,12 @@ export type JournalEvent =
       findingsCount: number
       toolsExecutedCount: number
     }
-  | { type: "session.deleted"; timestamp: number; archived: boolean }
+  | {
+      type: "session.deleted"
+      timestamp: number
+      archived: boolean
+      finalizationPassed: boolean | null
+    }
   | {
       type: "tool.executed"
       tool: string
@@ -30,12 +38,15 @@ export type JournalEvent =
       findingsCount: number
     }
 
-export function createRunJournal(projectDir: string): {
+export function createRunJournal(
+  projectDir: string,
+  resolver: ArgusRootResolver = defaultRootResolver,
+): {
   log(event: JournalEvent): void
   close(): Promise<void>
   getPath(): string
 } {
-  const journalPath = join(projectDir, JOURNAL_DIR, JOURNAL_FILE)
+  const journalPath = join(resolver.writeRoot(projectDir), JOURNAL_FILE)
   let ensureDirPromise: Promise<void> | null = null
   const pendingWrites = new Set<Promise<void>>()