solidity-argus 0.3.7 → 0.5.6

package/src/solodit-lifecycle.ts

@@ -19,10 +19,16 @@ export interface LifecycleStatus {
 
 let soloditChild: SoloditChildProcess | null = null
 let monitorTimer: ReturnType<typeof setInterval> | null = null
-let isRestarting = false
+let restartPromise: Promise<boolean | undefined> | null = null
+let startupPromise: Promise<void> | null = null
 
 /** Whether the Solodit MCP server is currently available for tool calls. */
-export let soloditAvailable = false
+let _soloditAvailable = false
+
+/** Returns whether the Solodit MCP server is currently available. */
+export function isSoloditAvailable(): boolean {
+  return _soloditAvailable
+}
 
 let lifecycleState: LifecycleState = "stopped"
 let lifecycleError: string | undefined
@@ -34,13 +40,31 @@ const HEALTH_CHECK_INTERVAL_MS = 60_000
 let restartSettleMs = DEFAULT_RESTART_SETTLE_MS
 let retryBaseDelayMs = DEFAULT_RETRY_BASE_DELAY_MS
 
+function withSuppressedParentOutput<T>(fn: () => T): T {
+  const savedStdoutWrite = process.stdout.write.bind(process.stdout)
+  const savedStderrWrite = process.stderr.write.bind(process.stderr)
+  const noop = (() => true) as typeof process.stdout.write
+
+  process.stdout.write = noop
+  process.stderr.write = noop
+
+  try {
+    return fn()
+  } finally {
+    process.stdout.write = savedStdoutWrite
+    process.stderr.write = savedStderrWrite
+  }
+}
+
 const defaultSpawnFn = (port: number): SoloditChildProcess =>
-  Bun.spawn(["npx", "-y", "@lyuboslavlyubenov/solodit-mcp"], {
-    stdin: "ignore",
-    stdout: "ignore",
-    stderr: "ignore",
-    env: { ...process.env, PORT: String(port) },
-  })
+  withSuppressedParentOutput(() =>
+    Bun.spawn(["npx", "-y", "@lyuboslavlyubenov/solodit-mcp"], {
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+      env: { ...process.env, PORT: String(port) },
+    }),
+  )
 
 let spawnFn: (port: number) => SoloditChildProcess = defaultSpawnFn
 
@@ -78,7 +102,9 @@ function classifySpawnError(err: unknown, port: number): string {
 function spawnSoloditChild(port: number): SoloditChildProcess {
   try {
     const child = spawnFn(port)
-    child.unref()
+    // Do NOT unref() — child must die with the parent process.
+    // unref() lets the parent exit without waiting for the child,
+    // creating orphaned solodit-mcp processes that hoard ports.
     return child
   } catch (err) {
     const message = classifySpawnError(err, port)
@@ -90,14 +116,56 @@ function spawnSoloditChild(port: number): SoloditChildProcess {
 
 function trackChildExit(child: SoloditChildProcess): void {
   const logger = createLogger()
-  child.exited.then((code) => {
-    if (code !== 0 && code !== null) {
-      logger.warn(`Solodit MCP exited with code ${code}`)
-    }
-    if (soloditChild === child) {
-      soloditChild = null
+  child.exited
+    .then((code) => {
+      if (code !== 0 && code !== null) {
+        logger.warn(`Solodit MCP exited with code ${code}`)
+      }
+      if (soloditChild === child) {
+        soloditChild = null
+      }
+    })
+    .catch((error) => {
+      logger.warn(
+        `Solodit MCP exit tracking failed: ${error instanceof Error ? error.message : String(error)}`,
+      )
+      if (soloditChild === child) {
+        soloditChild = null
+      }
+    })
+}
+
+/** Kill the solodit-mcp child process. Called on parent exit to prevent orphans. */
+function killSoloditChild(): void {
+  if (soloditChild) {
+    try {
+      soloditChild.kill()
+    } catch {
+      // Process already dead — ignore.
     }
-  })
+    soloditChild = null
+  }
+}
+
+// Register once: kill child on parent exit to prevent orphaned processes.
+let exitHandlerRegistered = false
+let sigintHandler: (() => void) | null = null
+let sigtermHandler: (() => void) | null = null
+
+function ensureExitHandler(): void {
+  if (exitHandlerRegistered) return
+  exitHandlerRegistered = true
+  process.on("exit", killSoloditChild)
+  sigintHandler = () => {
+    killSoloditChild()
+    process.exit(130)
+  }
+  sigtermHandler = () => {
+    killSoloditChild()
+    process.exit(143)
+  }
+  process.on("SIGINT", sigintHandler)
+  process.on("SIGTERM", sigtermHandler)
 }
 
 async function restartSoloditMcp(port: number): Promise<boolean> {
@@ -106,7 +174,7 @@ async function restartSoloditMcp(port: number): Promise<boolean> {
   // Pre-check: if existing instance recovered, skip restart entirely
   const preCheck = await checkSoloditHealth(port, true)
   if (preCheck.reachable) {
-    soloditAvailable = true
+    _soloditAvailable = true
     lifecycleState = "running"
     lifecycleError = undefined
     logger.info("Solodit MCP already healthy — skipping restart")
@@ -132,7 +200,7 @@ async function restartSoloditMcp(port: number): Promise<boolean> {
     logger.warn(`Solodit MCP spawn failed: ${message}`)
     lifecycleState = "failed"
     lifecycleError = message
-    soloditAvailable = false
+    _soloditAvailable = false
     return false
   }
 
@@ -153,7 +221,7 @@ async function restartSoloditMcp(port: number): Promise<boolean> {
   )
 
   if (result.success) {
-    soloditAvailable = true
+    _soloditAvailable = true
     lifecycleState = "running"
     lifecycleError = undefined
     logger.info("Solodit MCP restarted successfully")
@@ -167,26 +235,29 @@ async function restartSoloditMcp(port: number): Promise<boolean> {
 }
 
 export async function _runMonitoringCycle(port: number): Promise<void> {
-  if (isRestarting) return
+  // Use a promise-based mutex to prevent concurrent restart attempts.
+  // If a restart is already in flight, wait for it rather than starting another.
+  if (restartPromise) {
+    await restartPromise.catch(() => {})
+    return
+  }
   const logger = createLogger()
   try {
     const health = await checkSoloditHealth(port, true)
     if (health.reachable) {
-      if (!soloditAvailable) {
-        soloditAvailable = true
+      if (!_soloditAvailable) {
+        _soloditAvailable = true
         lifecycleState = "running"
         lifecycleError = undefined
         logger.info("Solodit MCP recovered — now available")
       }
-    } else if (soloditAvailable) {
-      soloditAvailable = false
+    } else if (_soloditAvailable) {
+      _soloditAvailable = false
       logger.warn("Solodit MCP health check failed, attempting restart...")
-      isRestarting = true
-      try {
-        await restartSoloditMcp(port)
-      } finally {
-        isRestarting = false
-      }
+      restartPromise = restartSoloditMcp(port).finally(() => {
+        restartPromise = null
+      })
+      await restartPromise
     }
   } catch {
     logger.debug("Monitoring cycle encountered an error")
@@ -214,8 +285,9 @@ export function stopSoloditMonitoring(): void {
 /** Reset all Solodit state — for testing only. */
 export function _resetSoloditState(): void {
   stopSoloditMonitoring()
-  soloditAvailable = false
-  isRestarting = false
+  _soloditAvailable = false
+  restartPromise = null
+  startupPromise = null
   lifecycleState = "stopped"
   lifecycleError = undefined
   restartSettleMs = DEFAULT_RESTART_SETTLE_MS
@@ -229,17 +301,35 @@ export function _resetSoloditState(): void {
     }
     soloditChild = null
   }
+  // Remove registered signal/exit handlers to prevent accumulation
+  process.removeListener("exit", killSoloditChild)
+  if (sigintHandler) {
+    process.removeListener("SIGINT", sigintHandler)
+    sigintHandler = null
+  }
+  if (sigtermHandler) {
+    process.removeListener("SIGTERM", sigtermHandler)
+    sigtermHandler = null
+  }
+  // Reset exit handler so tests can re-register cleanly
+  exitHandlerRegistered = false
+}
+
+/** Set _soloditAvailable flag — for testing only. */
+export function _setSoloditAvailable(value: boolean): void {
+  _soloditAvailable = value
 }
 
-export async function startSoloditMcp(port: number): Promise<void> {
+async function startSoloditMcpInternal(port: number): Promise<void> {
   const logger = createLogger()
   lifecycleState = "starting"
   lifecycleError = undefined
+  ensureExitHandler()
 
   const health = await checkSoloditHealth(port, true)
   if (health.reachable) {
     logger.debug(`Solodit MCP already running on port ${port} — skipping spawn`)
-    soloditAvailable = true
+    _soloditAvailable = true
     lifecycleState = "running"
     startMonitoring(port)
     return
@@ -253,7 +343,7 @@ export async function startSoloditMcp(port: number): Promise<void> {
     logger.warn(`Solodit MCP startup failed: ${message}`)
     lifecycleState = "failed"
     lifecycleError = message
-    soloditAvailable = false
+    _soloditAvailable = false
     startMonitoring(port)
     return
   }
@@ -266,13 +356,13 @@ export async function startSoloditMcp(port: number): Promise<void> {
     if (deadline.aborted) break
     const healthResult = await checkSoloditHealth(port, true)
     if (healthResult.reachable) {
-      soloditAvailable = true
+      _soloditAvailable = true
       lifecycleState = "running"
       logger.debug(`Solodit MCP healthy on port ${port}`)
       break
     }
   }
-  if (!soloditAvailable) {
+  if (!_soloditAvailable) {
     lifecycleState = "failed"
     lifecycleError = "Solodit MCP not reachable after startup — monitoring will retry"
     logger.warn(lifecycleError)
@@ -280,3 +370,29 @@ export async function startSoloditMcp(port: number): Promise<void> {
 
   startMonitoring(port)
 }
+
+export async function startSoloditMcp(
+  port: number,
+  options: { waitForHealth?: boolean } = {},
+): Promise<void> {
+  const waitForHealth = options.waitForHealth ?? true
+
+  if (startupPromise) {
+    if (waitForHealth) {
+      await startupPromise
+    }
+    return
+  }
+
+  let promise!: Promise<void>
+  promise = startSoloditMcpInternal(port).finally(() => {
+    if (startupPromise === promise) {
+      startupPromise = null
+    }
+  })
+  startupPromise = promise
+
+  if (waitForHealth) {
+    await promise
+  }
+}

package/src/state/adapters.ts

@@ -1,3 +1,11 @@
+import { normalizeFilePath } from "../shared/path-utils"
+import { isRecord } from "../shared/type-guards"
+import {
+  VALID_AGENTS,
+  VALID_CONFIDENCES,
+  VALID_SEVERITIES,
+  VALID_SOURCES,
+} from "../shared/validation-constants"
 import { computeIssueFingerprint, computeObservationFingerprint } from "./finding-fingerprint"
 import {
   type CanonicalFinding,
@@ -5,7 +13,7 @@ import {
   type ValidationError,
   validateCanonicalFinding,
 } from "./schemas"
-import type { ArgusAgentName, AuditPhase, Finding, FindingSeverity } from "./types"
+import type { ArgusAgentName, AuditPhase, Finding } from "./types"
 
 export interface Diagnostic {
   level: "warn" | "error"
@@ -16,38 +24,12 @@ export interface Diagnostic {
 
 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 VALID_REPORTED_AGENTS: ReadonlySet<ArgusAgentName> = new Set([
-  "argus",
-  "sentinel",
-  "pythia",
-  "scribe",
-  "unknown",
-])
-
 const KNOWN_INPUT_FIELDS = new Set([
   "id",
   "check",
   "detector",
+  "title",
+  "name",
   "severity",
   "confidence",
   "description",
@@ -59,6 +41,9 @@ const KNOWN_INPUT_FIELDS = new Set([
   "line_start",
   "line_end",
   "source",
+  "recommendation",
+  "proofOfConcept",
+  "proof_of_concept",
   "remediation",
   "exploitReference",
   "provenance",
@@ -78,6 +63,7 @@ const KNOWN_INPUT_FIELDS = new Set([
   "observationFingerprint",
   "issueFingerprint",
   "elements",
+  "location",
 ])
 
 export interface NormalizeFindingOptions {
@@ -87,10 +73,6 @@ export interface NormalizeFindingOptions {
   observationId?: string
 }
 
-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()
@@ -140,6 +122,17 @@ function normalizeLines(
   return undefined
 }
 
+function extractFileFromLocation(location: string): string {
+  const colonIndex = location.lastIndexOf(":")
+  if (colonIndex > 0) {
+    const afterColon = location.substring(colonIndex + 1)
+    if (/^\d+(-\d+)?$/.test(afterColon)) {
+      return location.substring(0, colonIndex)
+    }
+  }
+  return location
+}
+
 function slitherElementFileAlias(input: Record<string, unknown>): string | undefined {
   if (!Array.isArray(input.elements) || input.elements.length === 0) {
     return undefined
@@ -169,6 +162,7 @@ export function normalizeToCanonicalFinding(
   runId: string,
   seq: number,
   options: NormalizeFindingOptions = {},
+  projectDir?: string,
 ): AdapterResult<CanonicalFinding> {
   const diagnostics: Diagnostic[] = []
   const input = isRecord(raw) ? raw : {}
@@ -189,7 +183,11 @@ export function normalizeToCanonicalFinding(
       ? input.check
       : typeof input.detector === "string" && input.detector.length > 0
         ? input.detector
-        : ""
+        : typeof input.title === "string" && input.title.length > 0
+          ? input.title
+          : typeof input.name === "string" && input.name.length > 0
+            ? input.name
+            : ""
 
   const description =
     typeof input.description === "string" && input.description.length > 0
@@ -201,12 +199,23 @@ export function normalizeToCanonicalFinding(
           ? input.first_markdown_element
           : check
 
-  const file =
+  const rawFile =
     typeof input.file === "string" && input.file.length > 0
       ? input.file
-      : (slitherElementFileAlias(input) ?? "")
-
-  const lines = normalizeLines(input.lines, input)
+      : typeof input.location === "string" && input.location.length > 0
+        ? extractFileFromLocation(input.location)
+        : (slitherElementFileAlias(input) ?? "")
+  const file = projectDir ? normalizeFilePath(rawFile, projectDir) : rawFile
+
+  let lines = normalizeLines(input.lines, input)
+  if (!lines && typeof input.location === "string") {
+    const match = input.location.match(/:(\d+)(?:-(\d+))?$/)
+    if (match) {
+      const start = parseInt(match[1] ?? "0", 10)
+      const end = match[2] ? parseInt(match[2], 10) : start
+      lines = [start, end] as [number, number]
+    }
+  }
   const severity = normalizeSeverity(input.severity)
   const confidence = normalizeConfidence(input.confidence)
   const source =
@@ -220,9 +229,7 @@ export function normalizeToCanonicalFinding(
     (typeof input.reportedByAgent === "string" ? input.reportedByAgent : undefined) ??
     options.reportedByAgent ??
     "unknown"
-  const reportedByAgent: ArgusAgentName = VALID_REPORTED_AGENTS.has(
-    reportedByAgentRaw as ArgusAgentName,
-  )
+  const reportedByAgent: ArgusAgentName = VALID_AGENTS.has(reportedByAgentRaw as ArgusAgentName)
     ? (reportedByAgentRaw as ArgusAgentName)
     : "unknown"
 
@@ -295,6 +302,18 @@ export function normalizeToCanonicalFinding(
     issue_fingerprint: issueFingerprint,
     observation_fingerprint: observationFingerprint,
     observation_id: observationId,
+    impact: typeof input.impact === "string" && input.impact.length > 0 ? input.impact : undefined,
+    recommendation:
+      typeof input.recommendation === "string" && input.recommendation.length > 0
+        ? input.recommendation
+        : undefined,
+    proofOfConcept:
+      (typeof input.proofOfConcept === "string" && input.proofOfConcept.length > 0
+        ? input.proofOfConcept
+        : undefined) ??
+      (typeof input.proof_of_concept === "string" && input.proof_of_concept.length > 0
+        ? input.proof_of_concept
+        : undefined),
     remediation: typeof input.remediation === "string" ? input.remediation : undefined,
     exploitReference:
       typeof input.exploitReference === "string" ? input.exploitReference : undefined,
@@ -329,28 +348,3 @@ export function normalizeToCanonicalFinding(
 
   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/finding-aggregation.ts

@@ -1,13 +1,6 @@
+import { SEVERITY_RANK } from "../shared/validation-constants"
 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))
 }
@@ -48,6 +41,10 @@ export function dedupeFindingsForFinalOutput(findings: CanonicalFinding[]): Cano
     const base = sortedObservations[0]
     if (!base) continue
 
+    const highestSeverityObservation = sortedObservations.reduce((best, obs) =>
+      SEVERITY_RANK[obs.severity] < SEVERITY_RANK[best.severity] ? obs : best,
+    )
+
     const reportedByAgents = uniqueSorted(
       sortedObservations.map((finding) => finding.reported_by_agent),
     )
@@ -58,6 +55,7 @@ export function dedupeFindingsForFinalOutput(findings: CanonicalFinding[]): Cano
 
     merged.push({
       ...base,
+      severity: highestSeverityObservation.severity,
       id: issueFingerprint,
       sources,
       reported_by_agents: reportedByAgents,

package/src/state/finding-fingerprint.ts

@@ -21,7 +21,7 @@ function hash(parts: string[]): string {
   return createHash("sha256").update(parts.join("|"), "utf8").digest("hex")
 }
 
-function normalizeText(value: string): string {
+export function normalizeText(value: string): string {
   return value.trim().toLowerCase()
 }
 

package/src/state/finding-store.ts

@@ -1,6 +1,16 @@
-import { createHash } from "node:crypto"
+import crypto from "node:crypto"
+import { isAbsolute, normalize, relative } from "node:path"
+import { normalizeText } from "./finding-fingerprint"
 import type { AuditState, Finding, FindingSeverity } from "./types"
 
+function normalizeStorePath(filePath: string, projectDir: string): string {
+  if (!filePath || !projectDir) return filePath
+  const n = normalize(filePath)
+  if (!isAbsolute(n)) return n.replace(/^\.\//, "")
+  const rel = relative(projectDir, n)
+  return rel.startsWith("..") ? n : rel
+}
+
 export interface FindingStore {
   addFinding(finding: Omit<Finding, "id">): Finding
   getFindings(filter?: { severity?: FindingSeverity; source?: Finding["source"] }): Finding[]
@@ -24,21 +34,31 @@ function isValidHydrationFinding(f: unknown): f is Finding {
 }
 
 export function createFindingStore(state: AuditState): FindingStore {
-  let observationCounter = state.findings.length
+  const projectDir = state.projectDir
 
   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)
+    return crypto
+      .createHash("sha256")
+      .update(`${normalizeText(check)}:${normalizeText(file)}:${lines[0]}-${lines[1]}`)
+      .digest("hex")
+      .substring(0, 16)
   }
 
   const hydratedFindings = state.findings.filter(isValidHydrationFinding)
 
   function addFinding(finding: Omit<Finding, "id">): Finding {
-    const id = generateObservationId(finding.check, finding.file, finding.lines)
+    const normalizedFile = normalizeStorePath(finding.file, projectDir)
+    const normalized =
+      normalizedFile !== finding.file ? { ...finding, file: normalizedFile } : finding
+    const id = generateObservationId(normalized.check, normalized.file, normalized.lines)
+
+    const existing = hydratedFindings.find((f) => f.id === id)
+    if (existing) {
+      return existing
+    }
 
     const newFinding: Finding = {
-      ...finding,
+      ...normalized,
       id,
     }
 
@@ -70,10 +90,12 @@ export function createFindingStore(state: AuditState): FindingStore {
   }
 
   function hasFinding(check: string, file: string, lines: [number, number]): boolean {
+    const normalizedCheck = normalizeText(check)
+    const normalizedFile = normalizeText(file)
     return hydratedFindings.some(
       (finding) =>
-        finding.check === check &&
-        finding.file === file &&
+        normalizeText(finding.check) === normalizedCheck &&
+        normalizeText(finding.file) === normalizedFile &&
         finding.lines[0] === lines[0] &&
         finding.lines[1] === lines[1],
     )

package/src/state/index.ts

@@ -1,3 +1,4 @@
+export { SEVERITY_RANK } from "../shared/validation-constants"
 export * from "./adapters"
 export { createAuditState } from "./audit-state"
 export { createFindingStore } from "./finding-store"
@@ -7,7 +8,6 @@ export {
   projectFindings,
   projectReportInput,
   projectToolExecutions,
-  SEVERITY_RANK,
   stableHash,
   validateEventSequence,
 } from "./projectors"