solidity-argus 0.3.3 → 0.3.5

package/src/shared/drop-diagnostics.ts

@@ -0,0 +1,108 @@
+import { createLogger } from "./logger"
+
+const logger = createLogger()
+
+/**
+ * "warn": log and continue (default). "error": collect, continue, surface.
+ * "strict-fail": collect, then throw after all diagnostics gathered.
+ */
+export type DropPolicy = "warn" | "error" | "strict-fail"
+
+export type DropReason = {
+  code: string
+  field?: string
+  message: string
+  policy: DropPolicy
+}
+
+export type DropDiagnostic = {
+  type: "drop"
+  source: string
+  tool?: string
+  reason: DropReason
+  timestamp: number
+}
+
+export type DropDiagnosticsCollector = {
+  warn(code: string, message: string, field?: string): void
+  error(code: string, message: string, field?: string): void
+  getDiagnostics(): DropDiagnostic[]
+  hasErrors(): boolean
+  throwIfStrict(): void
+}
+
+/** Thrown in strict-fail mode when error-level diagnostics exist. */
+export class DropDiagnosticsError extends Error {
+  public readonly diagnostics: DropDiagnostic[]
+
+  constructor(diagnostics: DropDiagnostic[]) {
+    const errorDiags = diagnostics.filter(
+      (d) => d.reason.policy === "strict-fail" || d.reason.policy === "error",
+    )
+    const summary = errorDiags.map((d) => `[${d.reason.code}] ${d.reason.message}`).join("; ")
+    super(`Drop diagnostics: ${errorDiags.length} error(s) — ${summary}`)
+    this.name = "DropDiagnosticsError"
+    this.diagnostics = diagnostics
+  }
+}
+
+export function createDropDiagnosticsCollector(
+  policy: DropPolicy,
+  source: string,
+  tool?: string,
+): DropDiagnosticsCollector {
+  const diagnostics: DropDiagnostic[] = []
+  let errorCount = 0
+
+  function push(code: string, message: string, level: "warn" | "error", field?: string): void {
+    const effectivePolicy: DropPolicy = level === "error" ? policy : "warn"
+    const diagnostic: DropDiagnostic = {
+      type: "drop",
+      source,
+      tool,
+      reason: {
+        code,
+        message,
+        policy: effectivePolicy,
+        ...(field !== undefined ? { field } : {}),
+      },
+      timestamp: Date.now(),
+    }
+    diagnostics.push(diagnostic)
+
+    if (level === "error") {
+      errorCount++
+    }
+
+    const logMsg = `[${source}${tool ? `:${tool}` : ""}] ${code}${field ? ` (field: ${field})` : ""}: ${message}`
+    if (level === "error") {
+      logger.warn(logMsg)
+    } else {
+      logger.info(logMsg)
+    }
+  }
+
+  return {
+    warn(code: string, message: string, field?: string): void {
+      push(code, message, "warn", field)
+    },
+
+    error(code: string, message: string, field?: string): void {
+      push(code, message, "error", field)
+    },
+
+    getDiagnostics(): DropDiagnostic[] {
+      return [...diagnostics]
+    },
+
+    hasErrors(): boolean {
+      return errorCount > 0
+    },
+
+    throwIfStrict(): void {
+      if (policy === "strict-fail" && errorCount > 0) {
+        throw new DropDiagnosticsError(diagnostics)
+      }
+    },
+  }
+}

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 {
@@ -9,3 +15,11 @@ export {
 export { stripJsoncComments } from "./jsonc-parser"
 export { createLogger, type Logger, type LoggerConfig } from "./logger"
 export { findFoundryProjectDir, resolveProjectDir } from "./project-utils"
+export {
+  formatReportDate,
+  ReportPathError,
+  type ReportPathOptions,
+  type ResolvedReportPath,
+  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/report-path-resolver.ts

@@ -0,0 +1,70 @@
+import { join } from "node:path"
+
+export class ReportPathError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ReportPathError"
+  }
+}
+
+export interface ReportPathOptions {
+  /** Contract name, e.g. "VulnerableVault" */
+  contractName: string
+  /** If not provided, use new Date() */
+  date?: Date
+  /** Canonical output directory (from config or default) */
+  outputDir: string
+  /** Optional run_id for run-scoped naming */
+  runId?: string
+}
+
+export interface ResolvedReportPath {
+  /** "VulnerableVault-security-audit-2026-02-21.md" */
+  filename: string
+  /** Full absolute path */
+  filePath: string
+  /** The directory used */
+  outputDir: string
+  /** runId if provided, else filename (deterministic identity) */
+  canonicalId: string
+}
+
+export function formatReportDate(date: Date): string {
+  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}`
+}
+
+export function sanitizeContractName(name: string): string {
+  return name
+    .replace(/\s+/g, "-")
+    .replace(/[^a-zA-Z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+export function resolveReportPath(options: ReportPathOptions): ResolvedReportPath {
+  const { contractName, date, outputDir, runId } = options
+
+  if (!contractName || contractName.trim() === "") {
+    throw new ReportPathError("contractName must not be empty")
+  }
+  if (!outputDir || outputDir.trim() === "") {
+    throw new ReportPathError("outputDir must not be empty")
+  }
+
+  const resolvedDate = date ?? new Date()
+  const dateStr = formatReportDate(resolvedDate)
+  const sanitizedName = sanitizeContractName(contractName)
+  const filename = `${sanitizedName}-security-audit-${dateStr}.md`
+  const filePath = join(outputDir, filename)
+  const canonicalId = runId ?? filename
+
+  return {
+    filename,
+    filePath,
+    outputDir,
+    canonicalId,
+  }
+}

package/src/solodit-lifecycle.ts

@@ -6,6 +6,15 @@ interface SoloditChildProcess {
   kill(signal?: number): void
   unref(): void
   readonly exited: Promise<number | null>
+  readonly pid?: number
+}
+
+export type LifecycleState = "starting" | "running" | "failed" | "stopped"
+
+export interface LifecycleStatus {
+  state: LifecycleState
+  error?: string
+  pid?: number
 }
 
 let soloditChild: SoloditChildProcess | null = null
@@ -15,6 +24,9 @@ let isRestarting = false
 /** Whether the Solodit MCP server is currently available for tool calls. */
 export let soloditAvailable = false
 
+let lifecycleState: LifecycleState = "stopped"
+let lifecycleError: string | undefined
+
 const DEFAULT_RESTART_SETTLE_MS = 2_000
 const DEFAULT_RETRY_BASE_DELAY_MS = 1_000
 const HEALTH_CHECK_INTERVAL_MS = 60_000
@@ -43,10 +55,37 @@ export function _setTestConfig(config: {
   if (config.spawnFn !== undefined) spawnFn = config.spawnFn
 }
 
+/** Returns the current lifecycle status of the Solodit MCP server. */
+export function getLifecycleStatus(): LifecycleStatus {
+  const status: LifecycleStatus = { state: lifecycleState }
+  if (lifecycleError) status.error = lifecycleError
+  if (soloditChild?.pid !== undefined) status.pid = soloditChild.pid
+  return status
+}
+
+function classifySpawnError(err: unknown, port: number): string {
+  const error = err instanceof Error ? err : new Error(String(err))
+  const code = (error as NodeJS.ErrnoException).code
+  if (code === "EADDRINUSE") {
+    return `Port ${port} already in use — cannot spawn Solodit MCP (EADDRINUSE)`
+  }
+  if (code === "ENOENT") {
+    return `Solodit MCP binary not found — ensure npx and @lyuboslavlyubenov/solodit-mcp are available (ENOENT)`
+  }
+  return `Failed to spawn Solodit MCP on port ${port}: ${error.message}`
+}
+
 function spawnSoloditChild(port: number): SoloditChildProcess {
-  const child = spawnFn(port)
-  child.unref()
-  return child
+  try {
+    const child = spawnFn(port)
+    child.unref()
+    return child
+  } catch (err) {
+    const message = classifySpawnError(err, port)
+    lifecycleState = "failed"
+    lifecycleError = message
+    throw new Error(message)
+  }
 }
 
 function trackChildExit(child: SoloditChildProcess): void {
@@ -64,6 +103,16 @@ function trackChildExit(child: SoloditChildProcess): void {
 async function restartSoloditMcp(port: number): Promise<boolean> {
   const logger = createLogger()
 
+  // Pre-check: if existing instance recovered, skip restart entirely
+  const preCheck = await checkSoloditHealth(port, true)
+  if (preCheck.reachable) {
+    soloditAvailable = true
+    lifecycleState = "running"
+    lifecycleError = undefined
+    logger.info("Solodit MCP already healthy — skipping restart")
+    return true
+  }
+
   if (soloditChild) {
     try {
       soloditChild.kill()
@@ -74,10 +123,16 @@ async function restartSoloditMcp(port: number): Promise<boolean> {
   }
 
   try {
+    lifecycleState = "starting"
+    lifecycleError = undefined
     soloditChild = spawnSoloditChild(port)
     trackChildExit(soloditChild)
   } catch (err) {
-    logger.warn("Failed to spawn Solodit MCP:", err)
+    const message = err instanceof Error ? err.message : String(err)
+    logger.warn(`Solodit MCP spawn failed: ${message}`)
+    lifecycleState = "failed"
+    lifecycleError = message
+    soloditAvailable = false
     return false
   }
 
@@ -99,10 +154,14 @@ async function restartSoloditMcp(port: number): Promise<boolean> {
 
   if (result.success) {
     soloditAvailable = true
+    lifecycleState = "running"
+    lifecycleError = undefined
     logger.info("Solodit MCP restarted successfully")
     return true
   }
 
+  lifecycleState = "failed"
+  lifecycleError = "Solodit MCP not reachable after restart attempts"
   logger.warn("Solodit MCP restart failed — will retry next cycle")
   return false
 }
@@ -115,6 +174,8 @@ export async function _runMonitoringCycle(port: number): Promise<void> {
     if (health.reachable) {
       if (!soloditAvailable) {
         soloditAvailable = true
+        lifecycleState = "running"
+        lifecycleError = undefined
         logger.info("Solodit MCP recovered — now available")
       }
     } else if (soloditAvailable) {
@@ -155,6 +216,8 @@ export function _resetSoloditState(): void {
   stopSoloditMonitoring()
   soloditAvailable = false
   isRestarting = false
+  lifecycleState = "stopped"
+  lifecycleError = undefined
   restartSettleMs = DEFAULT_RESTART_SETTLE_MS
   retryBaseDelayMs = DEFAULT_RETRY_BASE_DELAY_MS
   spawnFn = defaultSpawnFn
@@ -170,17 +233,30 @@ export function _resetSoloditState(): void {
 
 export async function startSoloditMcp(port: number): Promise<void> {
   const logger = createLogger()
+  lifecycleState = "starting"
+  lifecycleError = undefined
 
   const health = await checkSoloditHealth(port, true)
   if (health.reachable) {
     logger.debug(`Solodit MCP already running on port ${port} — skipping spawn`)
     soloditAvailable = true
+    lifecycleState = "running"
     startMonitoring(port)
     return
   }
 
-  soloditChild = spawnSoloditChild(port)
-  trackChildExit(soloditChild)
+  try {
+    soloditChild = spawnSoloditChild(port)
+    trackChildExit(soloditChild)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    logger.warn(`Solodit MCP startup failed: ${message}`)
+    lifecycleState = "failed"
+    lifecycleError = message
+    soloditAvailable = false
+    startMonitoring(port)
+    return
+  }
 
   const deadline = AbortSignal.timeout(5000)
   const delays = [1000, 2000]
@@ -191,12 +267,15 @@ export async function startSoloditMcp(port: number): Promise<void> {
     const healthResult = await checkSoloditHealth(port, true)
     if (healthResult.reachable) {
       soloditAvailable = true
+      lifecycleState = "running"
       logger.debug(`Solodit MCP healthy on port ${port}`)
       break
     }
   }
   if (!soloditAvailable) {
-    logger.warn(`Solodit MCP not reachable after startup — monitoring will retry`)
+    lifecycleState = "failed"
+    lifecycleError = "Solodit MCP not reachable after startup — monitoring will retry"
+    logger.warn(lifecycleError)
   }
 
   startMonitoring(port)

package/src/state/adapters.ts

@@ -0,0 +1,262 @@
+import {
+  type CanonicalFinding,
+  SCHEMA_VERSION,
+  type ValidationError,
+  validateCanonicalFinding,
+} from "./schemas"
+import type { AuditPhase, Finding, FindingSeverity } from "./types"
+
+export interface Diagnostic {
+  level: "warn" | "error"
+  code: string
+  message: string
+  field?: string
+}
+
+export type AdapterResult<T> = { data: T; diagnostics: Diagnostic[] }
+
+const VALID_SEVERITIES: ReadonlySet<FindingSeverity> = new Set([
+  "Critical",
+  "High",
+  "Medium",
+  "Low",
+  "Informational",
+])
+const VALID_CONFIDENCES: ReadonlySet<CanonicalFinding["confidence"]> = new Set([
+  "High",
+  "Medium",
+  "Low",
+])
+const VALID_SOURCES: ReadonlySet<CanonicalFinding["source"]> = new Set([
+  "slither",
+  "manual",
+  "pattern",
+  "scvd",
+  "solodit",
+  "fuzz",
+])
+
+const KNOWN_INPUT_FIELDS = new Set([
+  "id",
+  "check",
+  "detector",
+  "severity",
+  "confidence",
+  "description",
+  "impact",
+  "first_markdown_element",
+  "file",
+  "lines",
+  "line",
+  "line_start",
+  "line_end",
+  "source",
+  "remediation",
+  "exploitReference",
+  "provenance",
+  "run_id",
+  "seq",
+  "session_id",
+  "tool_call_id",
+  "schema_version",
+  "elements",
+])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function normalizeSeverity(value: unknown): CanonicalFinding["severity"] {
+  if (typeof value !== "string") return "Informational"
+  const lower = value.toLowerCase()
+  const map: Record<string, CanonicalFinding["severity"]> = {
+    critical: "Critical",
+    high: "High",
+    medium: "Medium",
+    low: "Low",
+    informational: "Informational",
+    info: "Informational",
+  }
+  return map[lower] ?? "Informational"
+}
+
+function normalizeConfidence(value: unknown): CanonicalFinding["confidence"] {
+  if (typeof value !== "string") return "Low"
+  const lower = value.toLowerCase()
+  const map: Record<string, CanonicalFinding["confidence"]> = {
+    high: "High",
+    medium: "Medium",
+    low: "Low",
+  }
+  return map[lower] ?? "Low"
+}
+
+function normalizeLines(
+  value: unknown,
+  input: Record<string, unknown>,
+): [number, number] | undefined {
+  if (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    typeof value[0] === "number" &&
+    typeof value[1] === "number"
+  ) {
+    return [value[0], value[1]]
+  }
+
+  if (typeof input.line === "number") {
+    return [input.line, input.line]
+  }
+
+  if (typeof input.line_start === "number" && typeof input.line_end === "number") {
+    return [input.line_start, input.line_end]
+  }
+
+  return undefined
+}
+
+function slitherElementFileAlias(input: Record<string, unknown>): string | undefined {
+  if (!Array.isArray(input.elements) || input.elements.length === 0) {
+    return undefined
+  }
+
+  const first = input.elements[0]
+  if (!isRecord(first)) return undefined
+  const sourceMapping = first.source_mapping
+  if (!isRecord(sourceMapping)) return undefined
+  const filenameRelative = sourceMapping.filename_relative
+  return typeof filenameRelative === "string" && filenameRelative.length > 0
+    ? filenameRelative
+    : undefined
+}
+
+function pushValidationDiagnostics(errors: ValidationError[]): Diagnostic[] {
+  return errors.map((error) => ({
+    level: "error",
+    code: `validation.${error.code}`,
+    message: error.message,
+    field: error.field,
+  }))
+}
+
+export function normalizeToCanonicalFinding(
+  raw: Finding | Record<string, unknown>,
+  runId: string,
+  seq: number,
+): AdapterResult<CanonicalFinding> {
+  const diagnostics: Diagnostic[] = []
+  const input = isRecord(raw) ? raw : {}
+
+  for (const key of Object.keys(input)) {
+    if (!KNOWN_INPUT_FIELDS.has(key)) {
+      diagnostics.push({
+        level: "warn",
+        code: "field.dropped",
+        message: `Dropped unknown field: ${key}`,
+        field: key,
+      })
+    }
+  }
+
+  const check =
+    typeof input.check === "string" && input.check.length > 0
+      ? input.check
+      : typeof input.detector === "string" && input.detector.length > 0
+        ? input.detector
+        : ""
+
+  const description =
+    typeof input.description === "string" && input.description.length > 0
+      ? input.description
+      : typeof input.impact === "string" && input.impact.length > 0
+        ? input.impact
+        : typeof input.first_markdown_element === "string" &&
+            input.first_markdown_element.length > 0
+          ? input.first_markdown_element
+          : check
+
+  const file =
+    typeof input.file === "string" && input.file.length > 0
+      ? input.file
+      : (slitherElementFileAlias(input) ?? "")
+
+  const lines = normalizeLines(input.lines, input)
+  const severity = normalizeSeverity(input.severity)
+  const confidence = normalizeConfidence(input.confidence)
+  const source =
+    typeof input.source === "string" &&
+    VALID_SOURCES.has(input.source as CanonicalFinding["source"])
+      ? (input.source as CanonicalFinding["source"])
+      : "manual"
+
+  const canonical: CanonicalFinding = {
+    id:
+      typeof input.id === "string" && input.id.length > 0
+        ? input.id
+        : `${check}:${file}:${lines?.[0] ?? 0}`,
+    check,
+    severity: VALID_SEVERITIES.has(severity) ? severity : "Informational",
+    confidence: VALID_CONFIDENCES.has(confidence) ? confidence : "Low",
+    description,
+    file,
+    lines: lines ?? [0, 0],
+    source,
+    remediation: typeof input.remediation === "string" ? input.remediation : undefined,
+    exploitReference:
+      typeof input.exploitReference === "string" ? input.exploitReference : undefined,
+    provenance: isRecord(input.provenance)
+      ? {
+          timestamp:
+            typeof input.provenance.timestamp === "number"
+              ? input.provenance.timestamp
+              : Date.now(),
+          toolVersion:
+            typeof input.provenance.toolVersion === "string"
+              ? input.provenance.toolVersion
+              : undefined,
+          phase:
+            typeof input.provenance.phase === "string"
+              ? (input.provenance.phase as AuditPhase)
+              : undefined,
+        }
+      : undefined,
+    run_id: runId,
+    seq,
+    schema_version:
+      typeof input.schema_version === "string" && input.schema_version.length > 0
+        ? input.schema_version
+        : SCHEMA_VERSION,
+  }
+
+  const validation = validateCanonicalFinding(canonical)
+  if (!validation.success) {
+    diagnostics.push(...pushValidationDiagnostics(validation.errors))
+  }
+
+  return { data: canonical, diagnostics }
+}
+
+export function normalizeLegacyFindingsArray(
+  raw: unknown[],
+  runId: string,
+): { findings: CanonicalFinding[]; diagnostics: Diagnostic[] } {
+  const findings: CanonicalFinding[] = []
+  const diagnostics: Diagnostic[] = []
+
+  for (const [index, item] of raw.entries()) {
+    const normalized = normalizeToCanonicalFinding(isRecord(item) ? item : {}, runId, index + 1)
+    diagnostics.push(
+      ...normalized.diagnostics.map((d) => ({
+        ...d,
+        message: `[index:${index}] ${d.message}`,
+      })),
+    )
+
+    const hasErrors = normalized.diagnostics.some((d) => d.level === "error")
+    if (!hasErrors) {
+      findings.push(normalized.data)
+    }
+  }
+
+  return { findings, diagnostics }
+}