solidity-argus 0.3.3 → 0.3.4

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

package/src/state/index.ts

@@ -0,0 +1,15 @@
+export * from "./adapters"
+export { createAuditState } from "./audit-state"
+export { createFindingStore } from "./finding-store"
+export {
+  ProjectorError,
+  projectAuditState,
+  projectFindings,
+  projectReportInput,
+  projectToolExecutions,
+  SEVERITY_RANK,
+  stableHash,
+  validateEventSequence,
+} from "./projectors"
+export * from "./schemas"
+export * from "./types"