solidity-argus 0.2.0 → 0.3.2

package/src/knowledge/scvd-index.ts

@@ -1,50 +1,50 @@
-import type { ScvdFinding } from "./scvd-client";
+import type { ScvdFinding } from "./scvd-client"
 
 export interface ScvdIndexEntry {
-  id: string;
-  title: string;
-  severity: string;
-  swc: string[];
-  cwe: string[];
-  keywords: string[];
-  repoUrl: string;
+  id: string
+  title: string
+  severity: string
+  swc: string[]
+  cwe: string[]
+  keywords: string[]
+  repoUrl: string
 }
 
 export interface ScvdIndexMetadata {
-  lastSuccess: string | null;
-  lastAttempt: string | null;
-  errorCount: number;
-  lastError: string | null;
-  lastErrorReason: string | null;
+  lastSuccess: string | null
+  lastAttempt: string | null
+  errorCount: number
+  lastError: string | null
+  lastErrorReason: string | null
 }
 
 export interface ScvdIndex {
-  version: number;
-  lastSync: string;
-  totalFindings: number;
-  entries: ScvdIndexEntry[];
-  metadata?: ScvdIndexMetadata;
+  version: number
+  lastSync: string
+  totalFindings: number
+  entries: ScvdIndexEntry[]
+  metadata?: ScvdIndexMetadata
 }
 
-const INDEX_VERSION = 1;
-const DEFAULT_LIMIT = 10;
-let syncInProgress = false;
+const INDEX_VERSION = 1
+const DEFAULT_LIMIT = 10
+let syncInProgress = false
 
 export function acquireSyncLock(): boolean {
   if (syncInProgress) {
-    return false;
+    return false
   }
 
-  syncInProgress = true;
-  return true;
+  syncInProgress = true
+  return true
 }
 
 export function releaseSyncLock(): void {
-  syncInProgress = false;
+  syncInProgress = false
 }
 
 export function isSyncLocked(): boolean {
-  return syncInProgress;
+  return syncInProgress
 }
 
 function normalizeKeywordInput(value: string): string[] {
@@ -52,15 +52,15 @@ function normalizeKeywordInput(value: string): string[] {
     .toLowerCase()
     .split(/[^a-z0-9]+/g)
     .map((word) => word.trim())
-    .filter((word) => word.length > 1);
+    .filter((word) => word.length > 1)
 }
 
 function uniqueWords(words: string[]): string[] {
-  return Array.from(new Set(words));
+  return Array.from(new Set(words))
 }
 
 function findingToEntry(finding: ScvdFinding): ScvdIndexEntry {
-  const keywordSource = `${finding.title} ${finding.description_md}`;
+  const keywordSource = `${finding.title} ${finding.description_md}`
 
   return {
     id: finding.scvd_id,
@@ -70,86 +70,84 @@ function findingToEntry(finding: ScvdFinding): ScvdIndexEntry {
     cwe: finding.taxonomy.cwe,
     keywords: uniqueWords(normalizeKeywordInput(keywordSource)),
     repoUrl: finding.repo.url,
-  };
+  }
 }
 
 export function buildIndex(findings: ScvdFinding[]): ScvdIndex {
-  const now = new Date().toISOString();
-  const entries = findings.map(findingToEntry);
+  const now = new Date().toISOString()
+  const entries = findings.map(findingToEntry)
 
   return {
     version: INDEX_VERSION,
     lastSync: now,
     totalFindings: entries.length,
     entries,
-  };
+  }
 }
 
 export function searchIndex(
   index: ScvdIndex,
   query: {
-    swc?: string;
-    severity?: string;
-    keyword?: string;
-    limit?: number;
-  }
+    swc?: string
+    severity?: string
+    keyword?: string
+    limit?: number
+  },
 ): ScvdIndexEntry[] {
-  const normalizedKeyword = query.keyword?.toLowerCase().trim();
-  const limit = query.limit ?? DEFAULT_LIMIT;
+  const normalizedKeyword = query.keyword?.toLowerCase().trim()
+  const limit = query.limit ?? DEFAULT_LIMIT
 
   const filtered = index.entries.filter((entry) => {
     if (query.swc && !entry.swc.includes(query.swc)) {
-      return false;
+      return false
     }
 
     if (query.severity && entry.severity !== query.severity) {
-      return false;
+      return false
     }
 
     if (normalizedKeyword && normalizedKeyword.length > 0) {
-      const matchesKeyword = entry.keywords.some((keyword) =>
-        keyword.includes(normalizedKeyword)
-      );
+      const matchesKeyword = entry.keywords.some((keyword) => keyword.includes(normalizedKeyword))
 
       if (!matchesKeyword) {
-        return false;
+        return false
       }
     }
 
-    return true;
-  });
+    return true
+  })
 
-  return filtered.slice(0, limit);
+  return filtered.slice(0, limit)
 }
 
 export async function saveIndex(index: ScvdIndex, filePath: string): Promise<void> {
-  const tmpPath = `${filePath}.tmp.${Date.now()}`;
-  await Bun.write(tmpPath, JSON.stringify(index, null, 2));
-  const { renameSync } = await import("node:fs");
-  renameSync(tmpPath, filePath);
+  const tmpPath = `${filePath}.tmp.${Date.now()}`
+  const { renameSync } = await import("node:fs")
+  await Bun.write(tmpPath, JSON.stringify(index, null, 2))
+  renameSync(tmpPath, filePath)
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
+  return typeof value === "object" && value !== null
 }
 
 function parseStringArray(value: unknown): string[] {
   if (!Array.isArray(value)) {
-    return [];
+    return []
   }
 
-  return value.filter((item): item is string => typeof item === "string");
+  return value.filter((item): item is string => typeof item === "string")
 }
 
 function parseEntry(value: unknown): ScvdIndexEntry | null {
   if (!isRecord(value)) {
-    return null;
+    return null
   }
 
-  const id = value.id;
-  const title = value.title;
-  const severity = value.severity;
-  const repoUrl = value.repoUrl;
+  const id = value.id
+  const title = value.title
+  const severity = value.severity
+  const repoUrl = value.repoUrl
 
   if (
     typeof id !== "string" ||
@@ -157,7 +155,7 @@ function parseEntry(value: unknown): ScvdIndexEntry | null {
     typeof severity !== "string" ||
     typeof repoUrl !== "string"
   ) {
-    return null;
+    return null
   }
 
   return {
@@ -168,11 +166,11 @@ function parseEntry(value: unknown): ScvdIndexEntry | null {
     cwe: parseStringArray(value.cwe),
     keywords: parseStringArray(value.keywords),
     repoUrl,
-  };
+  }
 }
 
 function parseNullableString(value: unknown): string | null {
-  return typeof value === "string" ? value : null;
+  return typeof value === "string" ? value : null
 }
 
 function parseMetadata(raw: Record<string, unknown>): ScvdIndexMetadata {
@@ -182,27 +180,27 @@ function parseMetadata(raw: Record<string, unknown>): ScvdIndexMetadata {
     errorCount: typeof raw.errorCount === "number" ? raw.errorCount : 0,
     lastError: parseNullableString(raw.lastError),
     lastErrorReason: parseNullableString(raw.lastErrorReason),
-  };
+  }
 }
 
 export async function loadIndex(filePath: string): Promise<ScvdIndex | null> {
-  const file = Bun.file(filePath);
-  const exists = await file.exists();
+  const file = Bun.file(filePath)
+  const exists = await file.exists()
 
   if (!exists) {
-    return null;
+    return null
   }
 
-  const raw = (await file.json()) as unknown;
+  const raw = (await file.json()) as unknown
 
   if (!isRecord(raw)) {
-    return null;
+    return null
   }
 
-  const version = raw.version;
-  const lastSync = raw.lastSync;
-  const totalFindings = raw.totalFindings;
-  const rawEntries = raw.entries;
+  const version = raw.version
+  const lastSync = raw.lastSync
+  const totalFindings = raw.totalFindings
+  const rawEntries = raw.entries
 
   if (
     typeof version !== "number" ||
@@ -210,24 +208,24 @@ export async function loadIndex(filePath: string): Promise<ScvdIndex | null> {
     typeof totalFindings !== "number" ||
     !Array.isArray(rawEntries)
   ) {
-    return null;
+    return null
   }
 
   const entries = rawEntries
     .map(parseEntry)
-    .filter((entry): entry is ScvdIndexEntry => entry !== null);
+    .filter((entry): entry is ScvdIndexEntry => entry !== null)
 
   const index: ScvdIndex = {
     version,
     lastSync,
     totalFindings,
     entries,
-  };
+  }
 
-  const rawMetadata = raw.metadata;
+  const rawMetadata = raw.metadata
   if (isRecord(rawMetadata)) {
-    index.metadata = parseMetadata(rawMetadata);
+    index.metadata = parseMetadata(rawMetadata)
   }
 
-  return index;
+  return index
 }

package/src/knowledge/scvd-sync.ts

@@ -1,6 +1,7 @@
-import type { ScvdClient } from "./scvd-client";
-import { ScvdApiError, ScvdNetworkError } from "./scvd-client";
-import { createLogger } from "../shared/logger";
+import { createLogger } from "../shared/logger"
+import { withRetry } from "./retry"
+import type { ScvdClient } from "./scvd-client"
+import { ScvdApiError, ScvdNetworkError } from "./scvd-client"
 import {
   createApiError,
   createNetworkError,
@@ -9,64 +10,60 @@ import {
   isRetryableError,
   type SyncError,
   type SyncOutcome,
-} from "./scvd-errors";
+} from "./scvd-errors"
 import {
   acquireSyncLock,
   buildIndex,
   loadIndex,
   releaseSyncLock,
-  saveIndex,
   type ScvdIndex,
   type ScvdIndexMetadata,
-} from "./scvd-index";
-import { withRetry } from "./retry";
+  saveIndex,
+} from "./scvd-index"
 
-export type SyncResult = SyncOutcome;
+export type SyncResult = SyncOutcome
 
-const RETRY_MAX_ATTEMPTS = 3;
-const RETRY_BASE_DELAY_MS = 1000;
+const RETRY_MAX_ATTEMPTS = 3
+const RETRY_BASE_DELAY_MS = 1000
 
 function buildErrorResult(error: unknown): SyncError {
-  const message = error instanceof Error ? error.message : "Unknown sync error";
+  const message = error instanceof Error ? error.message : "Unknown sync error"
 
   if (error instanceof ScvdNetworkError) {
-    return createNetworkError(message);
+    return createNetworkError(message)
   }
   if (error instanceof ScvdApiError) {
-    return createApiError(error.httpStatus, message);
+    return createApiError(error.httpStatus, message)
   }
-  return createParseError(message);
+  return createParseError(message)
 }
 
 function shouldRetrySyncError(error: unknown): boolean {
   if (!(error instanceof ScvdNetworkError)) {
-    return false;
+    return false
   }
 
-  return isRetryableError(buildErrorResult(error));
+  return isRetryableError(buildErrorResult(error))
 }
 
 function errorReasonFromResult(result: SyncError): string {
-  return result.reason;
+  return result.reason
 }
 
-async function persistErrorMetadata(
-  indexPath: string,
-  errorResult: SyncError
-): Promise<void> {
-  const existing = await loadIndex(indexPath);
-  if (!existing) return;
+async function persistErrorMetadata(indexPath: string, errorResult: SyncError): Promise<void> {
+  const existing = await loadIndex(indexPath)
+  if (!existing) return
 
-  const now = new Date().toISOString();
-  const prevMetadata = existing.metadata;
+  const now = new Date().toISOString()
+  const prevMetadata = existing.metadata
   existing.metadata = {
     lastSuccess: prevMetadata?.lastSuccess ?? null,
     lastAttempt: now,
     errorCount: (prevMetadata?.errorCount ?? 0) + 1,
     lastError: errorResult.message,
     lastErrorReason: errorReasonFromResult(errorResult),
-  };
-  await saveIndex(existing, indexPath);
+  }
+  await saveIndex(existing, indexPath)
 }
 
 async function syncAllUnlocked(client: ScvdClient, indexPath: string): Promise<SyncResult> {
@@ -74,81 +71,83 @@ async function syncAllUnlocked(client: ScvdClient, indexPath: string): Promise<S
     maxAttempts: RETRY_MAX_ATTEMPTS,
     baseDelayMs: RETRY_BASE_DELAY_MS,
     shouldRetry: shouldRetrySyncError,
-  });
+  })
 
   if (!fetchResult.success) {
-    const errorResult = buildErrorResult(fetchResult.error);
-    errorResult.attempts = fetchResult.attempts;
-    await persistErrorMetadata(indexPath, errorResult);
-    return errorResult;
+    const errorResult = buildErrorResult(fetchResult.error)
+    errorResult.attempts = fetchResult.attempts
+    await persistErrorMetadata(indexPath, errorResult)
+    return errorResult
   }
 
   if (fetchResult.value === undefined) {
-    const errorResult = createParseError("SCVD sync returned no findings payload");
-    errorResult.attempts = fetchResult.attempts;
-    await persistErrorMetadata(indexPath, errorResult);
-    return errorResult;
+    const errorResult = createParseError("SCVD sync returned no findings payload")
+    errorResult.attempts = fetchResult.attempts
+    await persistErrorMetadata(indexPath, errorResult)
+    return errorResult
   }
 
-  const findings = fetchResult.value;
-  const index = buildIndex(findings);
-  const now = new Date().toISOString();
+  const findings = fetchResult.value
+  const index = buildIndex(findings)
+  const now = new Date().toISOString()
   index.metadata = {
     lastSuccess: now,
     lastAttempt: now,
     errorCount: 0,
     lastError: null,
     lastErrorReason: null,
-  };
-  await saveIndex(index, indexPath);
+  }
+  await saveIndex(index, indexPath)
 
   return createSyncSuccess({
     newFindings: findings.length,
     totalIndexed: index.totalFindings,
     lastSync: index.lastSync,
     attempts: fetchResult.attempts,
-  });
+  })
 }
 
 export async function syncAll(client: ScvdClient, indexPath: string): Promise<SyncResult> {
-  const logger = createLogger();
+  const logger = createLogger()
 
   if (!acquireSyncLock()) {
-    return createParseError("Sync already in progress");
+    return createParseError("Sync already in progress")
   }
 
-  logger.debug("[sync] starting", "source=scvd mode=full");
+  logger.debug("[sync] starting", "source=scvd mode=full")
 
   try {
-    const result = await syncAllUnlocked(client, indexPath);
+    const result = await syncAllUnlocked(client, indexPath)
     if (result.success) {
-      logger.debug("[sync] complete", `source=scvd newFindings=${result.newFindings} totalIndexed=${result.totalIndexed}`);
+      logger.debug(
+        "[sync] complete",
+        `source=scvd newFindings=${result.newFindings} totalIndexed=${result.totalIndexed}`,
+      )
     } else {
-      const reason = result.status === "error" ? result.reason : result.status;
-      logger.debug("[sync] failed", `source=scvd reason=${reason}`);
+      const reason = result.status === "error" ? result.reason : result.status
+      logger.debug("[sync] failed", `source=scvd reason=${reason}`)
     }
-    return result;
+    return result
   } catch (error) {
-    const errorResult = buildErrorResult(error);
-    logger.debug("[sync] failed", `source=scvd reason=${errorResult.reason}`);
-    await persistErrorMetadata(indexPath, errorResult).catch(() => {});
-    return errorResult;
+    const errorResult = buildErrorResult(error)
+    logger.debug("[sync] failed", `source=scvd reason=${errorResult.reason}`)
+    await persistErrorMetadata(indexPath, errorResult).catch(() => {
+      logger.debug("Failed to persist sync error metadata")
+    })
+    return errorResult
   } finally {
-    releaseSyncLock();
+    releaseSyncLock()
   }
 }
 
-export async function syncIncremental(
-  client: ScvdClient,
-  indexPath: string
-): Promise<SyncResult> {
-  const logger = createLogger();
+export async function syncIncremental(client: ScvdClient, indexPath: string): Promise<SyncResult> {
+  const logger = createLogger()
 
   if (!acquireSyncLock()) {
-    return createParseError("Sync already in progress");
+    return createParseError("Sync already in progress")
   }
 
-  logger.debug("[sync] starting", "source=scvd mode=incremental");
+  logger.debug("[sync] starting", "source=scvd mode=incremental")
 
   try {
     const [statsResult, existingIndex] = await Promise.all([
@@ -158,65 +157,71 @@ export async function syncIncremental(
         shouldRetry: shouldRetrySyncError,
       }),
       loadIndex(indexPath),
-    ]);
+    ])
 
     if (!statsResult.success) {
-      const errorResult = buildErrorResult(statsResult.error);
-      errorResult.attempts = statsResult.attempts;
-      await persistErrorMetadata(indexPath, errorResult).catch(() => {});
-      return errorResult;
+      const errorResult = buildErrorResult(statsResult.error)
+      errorResult.attempts = statsResult.attempts
+      await persistErrorMetadata(indexPath, errorResult).catch(() => {
+        logger.debug("Failed to persist sync error metadata")
+      })
+      return errorResult
     }
 
     if (statsResult.value === undefined) {
-      const errorResult = createParseError("SCVD sync returned no stats payload");
-      errorResult.attempts = statsResult.attempts;
-      await persistErrorMetadata(indexPath, errorResult).catch(() => {});
-      return errorResult;
+      const errorResult = createParseError("SCVD sync returned no stats payload")
+      errorResult.attempts = statsResult.attempts
+      await persistErrorMetadata(indexPath, errorResult).catch(() => {
+        logger.debug("Failed to persist sync error metadata")
+      })
+      return errorResult
     }
 
-    const stats = statsResult.value;
+    const stats = statsResult.value
 
     if (existingIndex && existingIndex.totalFindings === stats.total) {
       return createSyncSuccess({
         newFindings: 0,
         totalIndexed: existingIndex.totalFindings,
         lastSync: existingIndex.lastSync,
-      });
+      })
     }
 
-    return await syncAllUnlocked(client, indexPath);
+    return await syncAllUnlocked(client, indexPath)
   } catch (error) {
-    const errorResult = buildErrorResult(error);
-    await persistErrorMetadata(indexPath, errorResult).catch(() => {});
-    return errorResult;
+    const errorResult = buildErrorResult(error)
+    await persistErrorMetadata(indexPath, errorResult).catch(() => {
+      logger.debug("Failed to persist sync error metadata")
+    })
+    return errorResult
   } finally {
-    releaseSyncLock();
+    releaseSyncLock()
   }
 }
-const STALE_THRESHOLD_DAYS = 7;
+const STALE_THRESHOLD_DAYS = 7
 
 export function isSyncStale(
   index: ScvdIndex | null,
-  thresholdDays: number = STALE_THRESHOLD_DAYS
+  thresholdDays: number = STALE_THRESHOLD_DAYS,
 ): boolean {
-  if (!index || !index.lastSync) return true;
-  const lastSyncDate = new Date(index.lastSync);
-  const now = new Date();
-  const diffMs = now.getTime() - lastSyncDate.getTime();
-  const diffDays = diffMs / (1000 * 60 * 60 * 24);
-  return diffDays > thresholdDays;
+  if (!index || !index.lastSync) return true
+  const lastSyncDate = new Date(index.lastSync)
+  const now = new Date()
+  const diffMs = now.getTime() - lastSyncDate.getTime()
+  const diffDays = diffMs / (1000 * 60 * 60 * 24)
+  return diffDays > thresholdDays
 }
 
 export async function getSyncStatus(indexPath: string): Promise<{
-  lastSync: string | null;
-  totalFindings: number;
-  healthy: boolean;
-  stale: boolean;
-  metadata: ScvdIndexMetadata | null;
-  hint?: string;
+  lastSync: string | null
+  totalFindings: number
+  healthy: boolean
+  stale: boolean
+  metadata: ScvdIndexMetadata | null
+  hint?: string
 }> {
-  const logger = createLogger();
-  const index = await loadIndex(indexPath);
+  const logger = createLogger()
+  const index = await loadIndex(indexPath)
 
   if (!index) {
     return {
@@ -226,15 +231,15 @@ export async function getSyncStatus(indexPath: string): Promise<{
       stale: true,
       metadata: null,
       hint: "SCVD data is missing. Run argus_sync_knowledge to populate.",
-    };
+    }
   }
 
-  const stale = isSyncStale(index);
+  const stale = isSyncStale(index)
 
   if (stale) {
-    const lastSyncDate = new Date(index.lastSync);
-    const daysSince = Math.floor((Date.now() - lastSyncDate.getTime()) / (1000 * 60 * 60 * 24));
-    logger.debug("[sync] stale", `source=scvd daysSince=${daysSince}`);
+    const lastSyncDate = new Date(index.lastSync)
+    const daysSince = Math.floor((Date.now() - lastSyncDate.getTime()) / (1000 * 60 * 60 * 24))
+    logger.debug("[sync] stale", `source=scvd daysSince=${daysSince}`)
 
     return {
       lastSync: index.lastSync,
@@ -243,7 +248,7 @@ export async function getSyncStatus(indexPath: string): Promise<{
       stale: true,
       metadata: index.metadata ?? null,
       hint: "SCVD data is stale. Run argus_sync_knowledge to update.",
-    };
+    }
   }
 
   return {
@@ -252,5 +257,5 @@ export async function getSyncStatus(indexPath: string): Promise<{
     healthy: true,
     stale: false,
     metadata: index.metadata ?? null,
-  };
+  }
 }

package/src/managers/index.ts

@@ -1 +1 @@
-export type { BackgroundManager, AuditStateManager, Managers } from "./types";
+export type { AuditStateManager, BackgroundManager, Managers } from "./types"