verimu 0.0.14 → 0.0.16

package/dist/index.d.cts

@@ -108,6 +108,108 @@ interface CveCheckResult {
     /** Total time taken for all checks (ms) */
     checkDurationMs: number;
 }
+/** How confidently a vulnerable package is used in source code */
+type UsageContextStatus = 'direct_evidence' | 'indirect_no_evidence' | 'unsupported' | 'analysis_error';
+/** Match categories for usage snippets */
+type UsageSnippetMatchKind = 'import' | 'require' | 'dynamic_import' | 'export_from' | 'call';
+/** A code snippet where a vulnerable package appears to be used */
+interface UsageSnippet {
+    /** Project-relative path to the file */
+    filePath: string;
+    /** 1-based start line of the snippet in source file */
+    startLine: number;
+    /** 1-based end line of the snippet in source file */
+    endLine: number;
+    /** Snippet text including context lines */
+    code: string;
+    /** Kind of syntax match */
+    matchKind: UsageSnippetMatchKind;
+    /** Called symbol if this snippet is a call-site match */
+    calledSymbol?: string;
+    /** Confidence score in [0, 1] */
+    confidence: number;
+}
+/** Usage-context outcome for one vulnerability */
+interface UsageContextVulnerabilityFinding {
+    /** Vulnerability identifier (CVE/GHSA/etc.) */
+    vulnerabilityId: string;
+    /** Package name that is vulnerable */
+    packageName: string;
+    /** Ecosystem the package belongs to */
+    ecosystem: Ecosystem;
+    /** Whether dependency scanner marked it as direct, if known */
+    directDependency: boolean | null;
+    /** Resolution status for this package usage */
+    status: UsageContextStatus;
+    /** Matched snippets for this vulnerable package */
+    snippets: UsageSnippet[];
+    /** Number of snippets in this finding */
+    evidenceCount: number;
+    /** Optional explanatory note */
+    notes?: string;
+}
+/** LLM-friendly usage context payload for one vulnerability */
+interface UsageContextLlmPayload {
+    vulnerability: {
+        id: string;
+        aliases: string[];
+        severity: Severity;
+        summary: string;
+        affectedVersionRange?: string;
+        fixedVersion?: string;
+        referenceUrl?: string;
+    };
+    package: {
+        name: string;
+        ecosystem: Ecosystem;
+        directDependency: boolean | null;
+    };
+    status: UsageContextStatus;
+    evidenceCount: number;
+    snippets: UsageSnippet[];
+    notes?: string;
+}
+/** Analyzer-level status summary for one ecosystem */
+interface UsageContextEcosystemStatus {
+    ecosystem: Ecosystem;
+    analyzer: string;
+    status: 'analyzed' | 'unsupported' | 'error';
+    vulnerablePackages: number;
+    snippetsFound: number;
+    note?: string;
+}
+/** Non-fatal usage-context analysis error */
+interface UsageContextError {
+    analyzer: string;
+    ecosystem?: Ecosystem;
+    packageName?: string;
+    error: string;
+}
+/** Complete usage-context output for a scan */
+interface UsageContextResult {
+    /** Whether usage analysis was executed */
+    triggered: boolean;
+    /** Scan duration in milliseconds */
+    durationMs: number;
+    /** Effective context lines setting (±N around each match) */
+    numContextLines: number;
+    /** Package-level snippet cap */
+    maxSnippetsPerPackage: number;
+    /** Global snippet cap */
+    maxSnippetsTotal: number;
+    /** Total snippets emitted */
+    totalSnippets: number;
+    /** Artifact path if written to disk */
+    artifactPath?: string;
+    /** Per-vulnerability findings */
+    packageFindings: UsageContextVulnerabilityFinding[];
+    /** Ecosystem-level analyzer status */
+    ecosystemStatus: UsageContextEcosystemStatus[];
+    /** Non-fatal analysis errors */
+    errors: UsageContextError[];
+    /** LLM-ready payload entries */
+    llmPayload: UsageContextLlmPayload[];
+}
 /** Complete output of a Verimu scan */
 interface VerimuReport {
     /** Project info */
@@ -122,6 +224,8 @@ interface VerimuReport {
     artifacts?: SbomArtifacts;
     /** CVE check results */
     cveCheck: CveCheckResult;
+    /** Optional usage-context analysis for vulnerable packages */
+    usageContext?: UsageContextResult;
     /** Overall summary */
     summary: {
         totalDependencies: number;
@@ -155,6 +259,8 @@ interface VerimuConfig {
     apiBaseUrl?: string;
     /** Skip CVE checking (just generate SBOM) */
     skipCveCheck?: boolean;
+    /** Optional context lines around usage snippets (default: 4, clamped to 0..20) */
+    numContextLines?: number;
 }
 /** Input for the pure `generateSbom()` function */
 interface GenerateSbomInput {
@@ -264,6 +370,23 @@ declare function generateSpdxSbom(input: GenerateSbomInput): GenerateSpdxSbomRes
  */
 declare function generateSwidTag(input: GenerateSbomInput): GenerateSwidTagResult;
 
+/**
+ * Source detection for SBOM scans.
+ *
+ * Determines the scan source with the following priority:
+ *   1. VERIMU_SOURCE environment variable (explicit override)
+ *   2. Auto-detect CI/CD environment
+ *   3. Default to "cli"
+ */
+type SbomSource = 'cli' | 'cicd';
+/**
+ * Detects the scan source with priority:
+ *   1. VERIMU_SOURCE env var (explicit override)
+ *   2. Auto-detect CI/CD environment
+ *   3. Default to "cli"
+ */
+declare function detectSource(): SbomSource;
+
 /**
  * Verimu API client — communicates with the Verimu backend.
  *
@@ -315,6 +438,11 @@ interface SbomUploadBundle {
     cyclonedx: Record<string, unknown>;
     spdx?: Record<string, unknown>;
     swid?: string;
+    meta?: {
+        source?: SbomSource;
+        commit_sha?: string;
+    };
+    usage_context?: Omit<UsageContextResult, 'artifactPath'>;
 }
 declare class VerimuApiClient {
     private readonly baseUrl;
@@ -1321,4 +1449,54 @@ declare class ConsoleReporter implements Reporter {
     report(result: VerimuReport): string;
 }
 
-export { ApiKeyRequiredError, CargoScanner, type CiProvider, ComposerScanner, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, DenoScanner, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, type GenerateSpdxSbomResult, type GenerateSwidTagResult, GoScanner, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, PnpmScanner, RubyScanner, type Sbom, type SbomArtifacts, type SbomDependency, type SbomFormat, type ScanResult, ScannerRegistry, type Severity, SpdxJsonGenerator, SwidTagGenerator, type UploadResult, VerimuApiClient, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, YarnScanner, generateSbom, generateSbomArtifacts, generateSpdxSbom, generateSwidTag, printReport, scan, shouldFailCi, uploadToVerimu };
+interface VulnerablePackageInput {
+    packageName: string;
+    ecosystem: Ecosystem;
+    directDependency: boolean | null;
+    vulnerabilities: Vulnerability[];
+}
+interface PackageAnalysisResult {
+    packageName: string;
+    ecosystem: Ecosystem;
+    status: UsageContextStatus;
+    snippets: UsageSnippet[];
+    notes?: string;
+}
+interface AnalyzerRunContext {
+    projectPath: string;
+    ecosystem: Ecosystem;
+    packages: VulnerablePackageInput[];
+    numContextLines: number;
+    maxSnippetsPerPackage: number;
+    maxSnippetsTotal: number;
+}
+interface AnalyzerRunResult {
+    packages: PackageAnalysisResult[];
+    errors: UsageContextError[];
+    snippetsProduced: number;
+}
+interface UsageContextAnalyzer {
+    readonly name: string;
+    supports(ecosystem: Ecosystem): boolean;
+    analyze(context: AnalyzerRunContext): Promise<AnalyzerRunResult>;
+}
+
+interface UsageContextEngineInput {
+    projectPath: string;
+    dependencies: Dependency[];
+    vulnerabilities: Vulnerability[];
+    numContextLines?: number;
+    maxSnippetsPerPackage?: number;
+    maxSnippetsTotal?: number;
+}
+declare class UsageContextEngine {
+    private readonly analyzers;
+    constructor(analyzers?: UsageContextAnalyzer[]);
+    analyze(input: UsageContextEngineInput): Promise<UsageContextResult>;
+    private addFindingsForPackage;
+    private buildVulnerablePackages;
+    private pickAnalyzer;
+    private normalizePositiveInt;
+}
+
+export { ApiKeyRequiredError, CargoScanner, type CiProvider, ComposerScanner, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, DenoScanner, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, type GenerateSpdxSbomResult, type GenerateSwidTagResult, GoScanner, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, PnpmScanner, RubyScanner, type Sbom, type SbomArtifacts, type SbomDependency, type SbomFormat, type SbomSource, type ScanResult, ScannerRegistry, type Severity, SpdxJsonGenerator, SwidTagGenerator, type UploadResult, type UsageContextEcosystemStatus, UsageContextEngine, type UsageContextError, type UsageContextLlmPayload, type UsageContextResult, type UsageContextStatus, type UsageContextVulnerabilityFinding, type UsageSnippet, type UsageSnippetMatchKind, VerimuApiClient, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, YarnScanner, detectSource, generateSbom, generateSbomArtifacts, generateSpdxSbom, generateSwidTag, printReport, scan, shouldFailCi, uploadToVerimu };

package/dist/index.d.ts

@@ -108,6 +108,108 @@ interface CveCheckResult {
     /** Total time taken for all checks (ms) */
     checkDurationMs: number;
 }
+/** How confidently a vulnerable package is used in source code */
+type UsageContextStatus = 'direct_evidence' | 'indirect_no_evidence' | 'unsupported' | 'analysis_error';
+/** Match categories for usage snippets */
+type UsageSnippetMatchKind = 'import' | 'require' | 'dynamic_import' | 'export_from' | 'call';
+/** A code snippet where a vulnerable package appears to be used */
+interface UsageSnippet {
+    /** Project-relative path to the file */
+    filePath: string;
+    /** 1-based start line of the snippet in source file */
+    startLine: number;
+    /** 1-based end line of the snippet in source file */
+    endLine: number;
+    /** Snippet text including context lines */
+    code: string;
+    /** Kind of syntax match */
+    matchKind: UsageSnippetMatchKind;
+    /** Called symbol if this snippet is a call-site match */
+    calledSymbol?: string;
+    /** Confidence score in [0, 1] */
+    confidence: number;
+}
+/** Usage-context outcome for one vulnerability */
+interface UsageContextVulnerabilityFinding {
+    /** Vulnerability identifier (CVE/GHSA/etc.) */
+    vulnerabilityId: string;
+    /** Package name that is vulnerable */
+    packageName: string;
+    /** Ecosystem the package belongs to */
+    ecosystem: Ecosystem;
+    /** Whether dependency scanner marked it as direct, if known */
+    directDependency: boolean | null;
+    /** Resolution status for this package usage */
+    status: UsageContextStatus;
+    /** Matched snippets for this vulnerable package */
+    snippets: UsageSnippet[];
+    /** Number of snippets in this finding */
+    evidenceCount: number;
+    /** Optional explanatory note */
+    notes?: string;
+}
+/** LLM-friendly usage context payload for one vulnerability */
+interface UsageContextLlmPayload {
+    vulnerability: {
+        id: string;
+        aliases: string[];
+        severity: Severity;
+        summary: string;
+        affectedVersionRange?: string;
+        fixedVersion?: string;
+        referenceUrl?: string;
+    };
+    package: {
+        name: string;
+        ecosystem: Ecosystem;
+        directDependency: boolean | null;
+    };
+    status: UsageContextStatus;
+    evidenceCount: number;
+    snippets: UsageSnippet[];
+    notes?: string;
+}
+/** Analyzer-level status summary for one ecosystem */
+interface UsageContextEcosystemStatus {
+    ecosystem: Ecosystem;
+    analyzer: string;
+    status: 'analyzed' | 'unsupported' | 'error';
+    vulnerablePackages: number;
+    snippetsFound: number;
+    note?: string;
+}
+/** Non-fatal usage-context analysis error */
+interface UsageContextError {
+    analyzer: string;
+    ecosystem?: Ecosystem;
+    packageName?: string;
+    error: string;
+}
+/** Complete usage-context output for a scan */
+interface UsageContextResult {
+    /** Whether usage analysis was executed */
+    triggered: boolean;
+    /** Scan duration in milliseconds */
+    durationMs: number;
+    /** Effective context lines setting (±N around each match) */
+    numContextLines: number;
+    /** Package-level snippet cap */
+    maxSnippetsPerPackage: number;
+    /** Global snippet cap */
+    maxSnippetsTotal: number;
+    /** Total snippets emitted */
+    totalSnippets: number;
+    /** Artifact path if written to disk */
+    artifactPath?: string;
+    /** Per-vulnerability findings */
+    packageFindings: UsageContextVulnerabilityFinding[];
+    /** Ecosystem-level analyzer status */
+    ecosystemStatus: UsageContextEcosystemStatus[];
+    /** Non-fatal analysis errors */
+    errors: UsageContextError[];
+    /** LLM-ready payload entries */
+    llmPayload: UsageContextLlmPayload[];
+}
 /** Complete output of a Verimu scan */
 interface VerimuReport {
     /** Project info */
@@ -122,6 +224,8 @@ interface VerimuReport {
     artifacts?: SbomArtifacts;
     /** CVE check results */
     cveCheck: CveCheckResult;
+    /** Optional usage-context analysis for vulnerable packages */
+    usageContext?: UsageContextResult;
     /** Overall summary */
     summary: {
         totalDependencies: number;
@@ -155,6 +259,8 @@ interface VerimuConfig {
     apiBaseUrl?: string;
     /** Skip CVE checking (just generate SBOM) */
     skipCveCheck?: boolean;
+    /** Optional context lines around usage snippets (default: 4, clamped to 0..20) */
+    numContextLines?: number;
 }
 /** Input for the pure `generateSbom()` function */
 interface GenerateSbomInput {
@@ -264,6 +370,23 @@ declare function generateSpdxSbom(input: GenerateSbomInput): GenerateSpdxSbomRes
  */
 declare function generateSwidTag(input: GenerateSbomInput): GenerateSwidTagResult;
 
+/**
+ * Source detection for SBOM scans.
+ *
+ * Determines the scan source with the following priority:
+ *   1. VERIMU_SOURCE environment variable (explicit override)
+ *   2. Auto-detect CI/CD environment
+ *   3. Default to "cli"
+ */
+type SbomSource = 'cli' | 'cicd';
+/**
+ * Detects the scan source with priority:
+ *   1. VERIMU_SOURCE env var (explicit override)
+ *   2. Auto-detect CI/CD environment
+ *   3. Default to "cli"
+ */
+declare function detectSource(): SbomSource;
+
 /**
  * Verimu API client — communicates with the Verimu backend.
  *
@@ -315,6 +438,11 @@ interface SbomUploadBundle {
     cyclonedx: Record<string, unknown>;
     spdx?: Record<string, unknown>;
     swid?: string;
+    meta?: {
+        source?: SbomSource;
+        commit_sha?: string;
+    };
+    usage_context?: Omit<UsageContextResult, 'artifactPath'>;
 }
 declare class VerimuApiClient {
     private readonly baseUrl;
@@ -1321,4 +1449,54 @@ declare class ConsoleReporter implements Reporter {
     report(result: VerimuReport): string;
 }
 
-export { ApiKeyRequiredError, CargoScanner, type CiProvider, ComposerScanner, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, DenoScanner, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, type GenerateSpdxSbomResult, type GenerateSwidTagResult, GoScanner, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, PnpmScanner, RubyScanner, type Sbom, type SbomArtifacts, type SbomDependency, type SbomFormat, type ScanResult, ScannerRegistry, type Severity, SpdxJsonGenerator, SwidTagGenerator, type UploadResult, VerimuApiClient, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, YarnScanner, generateSbom, generateSbomArtifacts, generateSpdxSbom, generateSwidTag, printReport, scan, shouldFailCi, uploadToVerimu };
+interface VulnerablePackageInput {
+    packageName: string;
+    ecosystem: Ecosystem;
+    directDependency: boolean | null;
+    vulnerabilities: Vulnerability[];
+}
+interface PackageAnalysisResult {
+    packageName: string;
+    ecosystem: Ecosystem;
+    status: UsageContextStatus;
+    snippets: UsageSnippet[];
+    notes?: string;
+}
+interface AnalyzerRunContext {
+    projectPath: string;
+    ecosystem: Ecosystem;
+    packages: VulnerablePackageInput[];
+    numContextLines: number;
+    maxSnippetsPerPackage: number;
+    maxSnippetsTotal: number;
+}
+interface AnalyzerRunResult {
+    packages: PackageAnalysisResult[];
+    errors: UsageContextError[];
+    snippetsProduced: number;
+}
+interface UsageContextAnalyzer {
+    readonly name: string;
+    supports(ecosystem: Ecosystem): boolean;
+    analyze(context: AnalyzerRunContext): Promise<AnalyzerRunResult>;
+}
+
+interface UsageContextEngineInput {
+    projectPath: string;
+    dependencies: Dependency[];
+    vulnerabilities: Vulnerability[];
+    numContextLines?: number;
+    maxSnippetsPerPackage?: number;
+    maxSnippetsTotal?: number;
+}
+declare class UsageContextEngine {
+    private readonly analyzers;
+    constructor(analyzers?: UsageContextAnalyzer[]);
+    analyze(input: UsageContextEngineInput): Promise<UsageContextResult>;
+    private addFindingsForPackage;
+    private buildVulnerablePackages;
+    private pickAnalyzer;
+    private normalizePositiveInt;
+}
+
+export { ApiKeyRequiredError, CargoScanner, type CiProvider, ComposerScanner, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, DenoScanner, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, type GenerateSpdxSbomResult, type GenerateSwidTagResult, GoScanner, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, PnpmScanner, RubyScanner, type Sbom, type SbomArtifacts, type SbomDependency, type SbomFormat, type SbomSource, type ScanResult, ScannerRegistry, type Severity, SpdxJsonGenerator, SwidTagGenerator, type UploadResult, type UsageContextEcosystemStatus, UsageContextEngine, type UsageContextError, type UsageContextLlmPayload, type UsageContextResult, type UsageContextStatus, type UsageContextVulnerabilityFinding, type UsageSnippet, type UsageSnippetMatchKind, VerimuApiClient, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, YarnScanner, detectSource, generateSbom, generateSbomArtifacts, generateSpdxSbom, generateSwidTag, printReport, scan, shouldFailCi, uploadToVerimu };