solidity-argus 0.1.8 → 0.3.0

package/src/knowledge/scvd-client.ts

@@ -1,79 +1,79 @@
 export interface ScvdFinding {
-  scvd_id: string;
-  doc_id: string;
-  title: string;
-  description_md: string;
-  severity: "Critical" | "High" | "Medium" | "Low" | "Informational";
-  taxonomy: { swc: string[]; cwe: string[] };
-  repo: { url: string; commit?: string; lines?: [number, number] };
-  sections: { recommendation_md?: string; poc_md?: string };
+  scvd_id: string
+  doc_id: string
+  title: string
+  description_md: string
+  severity: "Critical" | "High" | "Medium" | "Low" | "Informational"
+  taxonomy: { swc: string[]; cwe: string[] }
+  repo: { url: string; commit?: string; lines?: [number, number] }
+  sections: { recommendation_md?: string; poc_md?: string }
 }
 
 export interface ScvdStats {
-  total: number;
-  by_severity: Record<string, number>;
-  last_updated: string;
+  total: number
+  by_severity: Record<string, number>
+  last_updated: string
 }
 
-const DEFAULT_PAGE_SIZE = 100;
+const DEFAULT_PAGE_SIZE = 100
 
 function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
+  return typeof value === "object" && value !== null
 }
 
 function toStringArray(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 toNumberRecord(value: unknown): Record<string, number> {
   if (!isRecord(value)) {
-    return {};
+    return {}
   }
 
-  const output: Record<string, number> = {};
+  const output: Record<string, number> = {}
   for (const [key, rawValue] of Object.entries(value)) {
     if (typeof rawValue === "number" && Number.isFinite(rawValue)) {
-      output[key] = rawValue;
+      output[key] = rawValue
     }
   }
 
-  return output;
+  return output
 }
 
 function parseLines(value: unknown): [number, number] | undefined {
   if (!Array.isArray(value) || value.length !== 2) {
-    return undefined;
+    return undefined
   }
 
-  const start = value[0];
-  const end = value[1];
+  const start = value[0]
+  const end = value[1]
 
   if (typeof start !== "number" || typeof end !== "number") {
-    return undefined;
+    return undefined
   }
 
-  return [start, end];
+  return [start, end]
 }
 
 function parseFinding(raw: unknown): ScvdFinding | null {
   if (!isRecord(raw)) {
-    return null;
+    return null
   }
 
-  const taxonomyRaw = isRecord(raw.taxonomy) ? raw.taxonomy : {};
-  const repoRaw = isRecord(raw.repo) ? raw.repo : {};
-  const sectionsRaw = isRecord(raw.sections) ? raw.sections : {};
+  const taxonomyRaw = isRecord(raw.taxonomy) ? raw.taxonomy : {}
+  const repoRaw = isRecord(raw.repo) ? raw.repo : {}
+  const sectionsRaw = isRecord(raw.sections) ? raw.sections : {}
 
-  const scvdId = raw.scvd_id;
-  const docId = raw.doc_id;
-  const title = raw.title;
-  const description = raw.description_md;
-  const severity = raw.severity;
-  const repoUrl = repoRaw.url;
+  const scvdId = raw.scvd_id
+  const docId = raw.doc_id
+  const title = raw.title
+  const description = raw.description_md
+  const severity = raw.severity
+  const repoUrl = repoRaw.url
 
   if (
     typeof scvdId !== "string" ||
@@ -82,7 +82,7 @@ function parseFinding(raw: unknown): ScvdFinding | null {
     typeof description !== "string" ||
     typeof repoUrl !== "string"
   ) {
-    return null;
+    return null
   }
 
   if (
@@ -92,7 +92,7 @@ function parseFinding(raw: unknown): ScvdFinding | null {
     severity !== "Low" &&
     severity !== "Informational"
   ) {
-    return null;
+    return null
   }
 
   return {
@@ -117,126 +117,146 @@ function parseFinding(raw: unknown): ScvdFinding | null {
           : undefined,
       poc_md: typeof sectionsRaw.poc_md === "string" ? sectionsRaw.poc_md : undefined,
     },
-  };
+  }
 }
 
 function parseFindings(raw: unknown): ScvdFinding[] {
   if (!Array.isArray(raw)) {
     if (isRecord(raw) && Array.isArray(raw.data)) {
-      return raw.data.map(parseFinding).filter((value): value is ScvdFinding => value !== null);
+      return raw.data.map(parseFinding).filter((value): value is ScvdFinding => value !== null)
     }
-    return [];
+    return []
   }
 
-  return raw.map(parseFinding).filter((value): value is ScvdFinding => value !== null);
+  return raw.map(parseFinding).filter((value): value is ScvdFinding => value !== null)
 }
 
 function parseStats(raw: unknown): ScvdStats {
   if (!isRecord(raw)) {
-    throw new Error("Invalid SCVD stats response payload");
+    throw new Error("Invalid SCVD stats response payload")
   }
 
-  const total = raw.total;
-  const lastUpdated = raw.last_updated;
+  const total = raw.total
+  const lastUpdated = raw.last_updated
 
   if (typeof total !== "number" || typeof lastUpdated !== "string") {
-    throw new Error("Invalid SCVD stats fields in response");
+    throw new Error("Invalid SCVD stats fields in response")
   }
 
   return {
     total,
     by_severity: toNumberRecord(raw.by_severity),
     last_updated: lastUpdated,
-  };
+  }
+}
+
+export class ScvdNetworkError extends Error {
+  override readonly name = "ScvdNetworkError" as const
+}
+
+export class ScvdApiError extends Error {
+  override readonly name = "ScvdApiError" as const
+  readonly httpStatus: number
+
+  constructor(httpStatus: number, message?: string) {
+    super(message ?? `SCVD API error: HTTP ${httpStatus}`)
+    this.httpStatus = httpStatus
+  }
 }
 
 export class ScvdClient {
-  private readonly baseUrl: string;
-  private readonly signal?: AbortSignal;
+  private readonly baseUrl: string
+  private readonly signal?: AbortSignal
 
   constructor(apiUrl: string, signal?: AbortSignal) {
-    this.baseUrl = apiUrl.replace(/\/$/, "");
-    this.signal = signal;
+    this.baseUrl = apiUrl.replace(/\/$/, "")
+    this.signal = signal
   }
 
   async fetchStats(): Promise<ScvdStats> {
-    const url = `${this.baseUrl}/stats`;
+    const url = `${this.baseUrl}/stats`
 
-    let response: Response;
+    let response: Response
     try {
-      response = await fetch(url, { signal: this.signal });
+      response = await fetch(url, { signal: this.signal })
     } catch (error) {
-      const message = error instanceof Error ? error.message : "unknown network error";
-      throw new Error(`Failed to fetch SCVD stats from ${url}: ${message}`);
+      const message = error instanceof Error ? error.message : "unknown network error"
+      throw new ScvdNetworkError(`Failed to fetch SCVD stats from ${url}: ${message}`)
     }
 
     if (!response.ok) {
-      throw new Error(`Failed to fetch SCVD stats from ${url}: HTTP ${response.status}`);
+      throw new ScvdApiError(
+        response.status,
+        `Failed to fetch SCVD stats from ${url}: HTTP ${response.status}`,
+      )
     }
 
-    const body = (await response.json()) as unknown;
-    return parseStats(body);
+    const body = (await response.json()) as unknown
+    return parseStats(body)
   }
 
   async fetchFindings(params: {
-    severity?: string;
-    limit?: number;
-    offset?: number;
+    severity?: string
+    limit?: number
+    offset?: number
   }): Promise<ScvdFinding[]> {
-    const searchParams = new URLSearchParams();
+    const searchParams = new URLSearchParams()
 
     if (params.severity) {
-      searchParams.set("severity", params.severity);
+      searchParams.set("severity", params.severity)
     }
     if (typeof params.limit === "number") {
-      searchParams.set("limit", String(params.limit));
+      searchParams.set("limit", String(params.limit))
     }
     if (typeof params.offset === "number") {
-      searchParams.set("offset", String(params.offset));
+      searchParams.set("offset", String(params.offset))
     }
 
-    const query = searchParams.toString();
-    const url = `${this.baseUrl}/findings${query.length > 0 ? `?${query}` : ""}`;
+    const query = searchParams.toString()
+    const url = `${this.baseUrl}/findings${query.length > 0 ? `?${query}` : ""}`
 
+    let response: Response
     try {
-      const response = await fetch(url, { signal: this.signal });
-      if (!response.ok) {
-        return [];
-      }
+      response = await fetch(url, { signal: this.signal })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "unknown network error"
+      throw new ScvdNetworkError(`Failed to fetch SCVD findings from ${url}: ${message}`)
+    }
 
-      const body = (await response.json()) as unknown;
-      return parseFindings(body);
-    } catch {
-      return []; // network error — treat as empty page
+    if (!response.ok) {
+      throw new ScvdApiError(response.status, `SCVD API error: HTTP ${response.status} for ${url}`)
     }
+
+    const body = (await response.json()) as unknown
+    return parseFindings(body)
   }
 
   async fetchAllFindings(onProgress?: (count: number) => void): Promise<ScvdFinding[]> {
-    const results: ScvdFinding[] = [];
-    let offset = 0;
+    const results: ScvdFinding[] = []
+    let offset = 0
 
     while (true) {
       const page = await this.fetchFindings({
         limit: DEFAULT_PAGE_SIZE,
         offset,
-      });
+      })
 
       if (page.length === 0) {
-        break;
+        break
       }
 
-      results.push(...page);
-      offset += page.length;
+      results.push(...page)
+      offset += page.length
 
       if (onProgress) {
-        onProgress(results.length);
+        onProgress(results.length)
       }
 
       if (page.length < DEFAULT_PAGE_SIZE) {
-        break;
+        break
       }
     }
 
-    return results;
+    return results
   }
 }

package/src/knowledge/scvd-errors.ts

@@ -0,0 +1,89 @@
+export type SyncError = {
+  status: "error"
+  success: false
+  reason: "network" | "api" | "parse"
+  message: string
+  error: string
+  httpStatus?: number
+  newFindings: 0
+  totalIndexed: 0
+  lastSync: string
+  attempts?: number
+}
+
+export type SyncSuccess = {
+  status: "success"
+  success: true
+  newFindings: number
+  totalIndexed: number
+  lastSync: string
+  error?: undefined
+  attempts?: number
+}
+
+export type SyncStale = {
+  status: "stale"
+  success: false
+  newFindings: 0
+  totalIndexed: 0
+  lastSync: string
+  error?: undefined
+  daysSinceSync: number
+  attempts?: number
+}
+
+export type SyncOutcome = SyncSuccess | SyncError | SyncStale
+
+export function createNetworkError(message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "network",
+    message,
+    error: message,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  }
+}
+
+export function createApiError(httpStatus: number, message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "api",
+    message,
+    error: message,
+    httpStatus,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  }
+}
+
+export function createParseError(message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "parse",
+    message,
+    error: message,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  }
+}
+
+export function createSyncSuccess(
+  data: Omit<SyncSuccess, "status" | "success" | "error"> & { attempts?: number },
+): SyncSuccess {
+  return {
+    status: "success",
+    success: true,
+    ...data,
+  }
+}
+
+export function isRetryableError(outcome: SyncOutcome): boolean {
+  return outcome.status === "error" && outcome.reason === "network"
+}

package/src/knowledge/scvd-index.ts

@@ -1,39 +1,66 @@
-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
 }
 
 export interface ScvdIndex {
-  version: number;
-  lastSync: string;
-  totalFindings: number;
-  entries: ScvdIndexEntry[];
+  version: number
+  lastSync: string
+  totalFindings: number
+  entries: ScvdIndexEntry[]
+  metadata?: ScvdIndexMetadata
 }
 
-const INDEX_VERSION = 1;
-const DEFAULT_LIMIT = 10;
+const INDEX_VERSION = 1
+const DEFAULT_LIMIT = 10
+let syncInProgress = false
+
+export function acquireSyncLock(): boolean {
+  if (syncInProgress) {
+    return false
+  }
+
+  syncInProgress = true
+  return true
+}
+
+export function releaseSyncLock(): void {
+  syncInProgress = false
+}
+
+export function isSyncLocked(): boolean {
+  return syncInProgress
+}
 
 function normalizeKeywordInput(value: string): string[] {
   return value
     .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,
@@ -43,84 +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 json = JSON.stringify(index, null, 2);
-  await Bun.write(filePath, json);
+  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" ||
@@ -128,7 +155,7 @@ function parseEntry(value: unknown): ScvdIndexEntry | null {
     typeof severity !== "string" ||
     typeof repoUrl !== "string"
   ) {
-    return null;
+    return null
   }
 
   return {
@@ -139,27 +166,41 @@ 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
+}
+
+function parseMetadata(raw: Record<string, unknown>): ScvdIndexMetadata {
+  return {
+    lastSuccess: parseNullableString(raw.lastSuccess),
+    lastAttempt: parseNullableString(raw.lastAttempt),
+    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" ||
@@ -167,17 +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)
 
-  return {
+  const index: ScvdIndex = {
     version,
     lastSync,
     totalFindings,
     entries,
-  };
+  }
+
+  const rawMetadata = raw.metadata
+  if (isRecord(rawMetadata)) {
+    index.metadata = parseMetadata(rawMetadata)
+  }
+
+  return index
 }