verimu 0.0.2 → 0.0.3

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { execSync } from 'child_process';
+
 /**
  * Core types for the Verimu scanning pipeline.
  *
@@ -6,7 +8,7 @@
  *                                     → CveSource → Vulnerability[]
  */
 /** Supported package ecosystems */
-type Ecosystem = 'npm' | 'nuget' | 'cargo' | 'maven' | 'pip' | 'go';
+type Ecosystem = 'npm' | 'nuget' | 'cargo' | 'maven' | 'pip' | 'go' | 'ruby';
 /** Supported CI/CD providers */
 type CiProvider = 'github' | 'gitlab' | 'bitbucket';
 /** A single resolved dependency from a lockfile */
@@ -307,6 +309,342 @@ declare class NpmScanner implements DependencyScanner {
     private parseDependenciesV1;
 }
 
+/**
+ * C# / NuGet dependency scanner.
+ *
+ * Parses `packages.lock.json` (NuGet lock file, generated by
+ * `dotnet restore --use-lock-file`) to extract the full resolved
+ * dependency tree. The lock file itself tracks Direct vs Transitive.
+ *
+ * Lock file format (NuGet v1):
+ * ```json
+ * {
+ *   "version": 1,
+ *   "dependencies": {
+ *     "net8.0": {
+ *       "PackageName": {
+ *         "type": "Direct" | "Transitive",
+ *         "resolved": "13.0.3",
+ *         "contentHash": "..."
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class NugetScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses packages.lock.json and extracts dependencies across all
+     * target frameworks. Deduplicates by package name (keeps highest version
+     * if the same package appears under multiple frameworks).
+     */
+    private parseLockfile;
+    /**
+     * Builds a purl for a NuGet package.
+     * NuGet purls are straightforward: pkg:nuget/Name@Version
+     */
+    private buildPurl;
+}
+
+/**
+ * Python / pip dependency scanner.
+ *
+ * Supports multiple Python dependency file formats (in priority order):
+ *   1. `requirements.txt` — flat list of pinned dependencies
+ *   2. `Pipfile.lock` — Pipenv lock file with exact versions
+ *
+ * For `requirements.txt`, all listed packages are treated as direct
+ * dependencies (the file doesn't distinguish direct vs transitive).
+ * For `Pipfile.lock`, `default` packages are direct and `develop`
+ * packages are dev dependencies.
+ *
+ * Limitation: `requirements.txt` doesn't capture transitive deps unless
+ * generated with `pip freeze`. If using `pip freeze` output, all deps
+ * are listed but we can't distinguish direct vs transitive.
+ */
+declare class PipScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses `requirements.txt` format.
+     *
+     * Supports:
+     *   - `package==1.2.3` (pinned)
+     *   - `package>=1.2.0` (minimum — uses the specified version)
+     *   - `package~=1.2.0` (compatible release)
+     *   - Comments (`#`) and blank lines are skipped
+     *   - `-r other-file.txt` (include directive) — skipped for now
+     *   - `--index-url` and other pip flags — skipped
+     */
+    private parseRequirementsTxt;
+    /**
+     * Parses `Pipfile.lock` (JSON format from Pipenv).
+     *
+     * Structure:
+     * ```json
+     * {
+     *   "_meta": { ... },
+     *   "default": {
+     *     "requests": { "version": "==2.31.0", ... }
+     *   },
+     *   "develop": {
+     *     "pytest": { "version": "==7.4.0", ... }
+     *   }
+     * }
+     * ```
+     */
+    private parsePipfileLock;
+    /**
+     * Extracts the version number from a pip version specifier.
+     * "1.2.3" → "1.2.3"
+     * "1.2.3,<2.0" → "1.2.3"
+     */
+    private extractVersion;
+    /**
+     * Normalizes a pip package name per PEP 503.
+     * Converts to lowercase and replaces any run of [-_.] with a single hyphen.
+     */
+    private normalizePipName;
+    /**
+     * Builds a purl for a PyPI package.
+     * Per purl spec, the type is "pypi" (not "pip").
+     */
+    private buildPurl;
+}
+
+/**
+ * Rust / Cargo dependency scanner.
+ *
+ * Parses `Cargo.lock` (TOML format) to extract the full resolved
+ * dependency tree. Reads `Cargo.toml` to determine which packages
+ * are direct dependencies vs transitive.
+ *
+ * Cargo.lock format (v3):
+ * ```toml
+ * [[package]]
+ * name = "serde"
+ * version = "1.0.195"
+ * source = "registry+https://github.com/rust-lang/crates.io-index"
+ * checksum = "abc123..."
+ * dependencies = [
+ *   "serde_derive",
+ * ]
+ * ```
+ *
+ * Note: We use a simple TOML parser since Cargo.lock has a very
+ * regular structure (just [[package]] entries). No need for a full
+ * TOML library.
+ */
+declare class CargoScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses Cargo.lock by splitting on [[package]] blocks.
+     * This is a lightweight parser that handles the regular structure
+     * of Cargo.lock without needing a full TOML parser.
+     */
+    private parseLockfile;
+    /**
+     * Extracts a string field value from a TOML block.
+     * Handles: `name = "value"` format.
+     */
+    private extractField;
+    /**
+     * Parses Cargo.toml to extract direct dependency names.
+     * Looks for [dependencies] and [dev-dependencies] sections.
+     */
+    private parseCargoToml;
+    /**
+     * Builds a purl for a Cargo (crates.io) package.
+     */
+    private buildPurl;
+}
+
+/**
+ * Java / Maven dependency scanner.
+ *
+ * Maven doesn't have a lockfile. This scanner uses two strategies:
+ *
+ *   1. **Primary (auto)**: If `mvn` is on `$PATH`, runs
+ *      `mvn dependency:list -DoutputType=text` to get the resolved
+ *      dependency tree including transitive dependencies.
+ *
+ *   2. **Fallback (pre-generated)**: Looks for a `dependency-tree.txt`
+ *      file in the project root. Users can generate this with:
+ *      ```
+ *      mvn dependency:list -DoutputFile=dependency-tree.txt -DoutputType=text
+ *      ```
+ *
+ * The scanner detects a Maven project by the presence of `pom.xml`.
+ *
+ * Maven dependency:list output format (one per line):
+ * ```
+ *    com.google.guava:guava:jar:32.1.3-jre:compile
+ *    org.slf4j:slf4j-api:jar:2.0.9:compile
+ *    junit:junit:jar:4.13.2:test
+ * ```
+ * Fields: groupId:artifactId:type:version:scope
+ */
+declare class MavenScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    /** Allow injection for testing */
+    private execSyncFn;
+    constructor(execSyncImpl?: typeof execSync);
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, _lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses Maven `dependency:list` output.
+     *
+     * Each dependency line has the format:
+     *   groupId:artifactId:type:version:scope
+     *   groupId:artifactId:type:classifier:version:scope
+     *
+     * Lines are typically indented with leading whitespace.
+     */
+    private parseDependencyList;
+    /** Checks if `mvn` is available on PATH */
+    private isMavenAvailable;
+    /**
+     * Runs `mvn dependency:list` and returns the output.
+     */
+    private runMavenDependencyList;
+    /**
+     * Builds a purl for a Maven package.
+     * Format: pkg:maven/groupId/artifactId@version
+     */
+    private buildPurl;
+    private buildResult;
+}
+
+/**
+ * Go module dependency scanner.
+ *
+ * Parses `go.sum` to extract the full resolved dependency list, and
+ * cross-references `go.mod` to distinguish direct vs indirect (transitive)
+ * dependencies.
+ *
+ * go.sum format (one or two lines per module):
+ * ```
+ * github.com/gin-gonic/gin v1.9.1 h1:abc123...=
+ * github.com/gin-gonic/gin v1.9.1/go.mod h1:def456...=
+ * ```
+ *
+ * Lines ending in `/go.mod` are checksums of the module's go.mod file —
+ * we skip those and only keep the `h1:` lines (source archive checksums).
+ *
+ * go.mod `require` block format:
+ * ```
+ * require (
+ *     github.com/gin-gonic/gin v1.9.1
+ *     golang.org/x/text v0.14.0 // indirect
+ * )
+ * ```
+ *
+ * Dependencies marked `// indirect` are transitive.
+ */
+declare class GoScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses go.sum and extracts unique module dependencies.
+     *
+     * Each module may appear twice in go.sum (once for the source archive,
+     * once for go.mod). We deduplicate by module path + version, keeping
+     * only the `h1:` entry (not the `/go.mod` entry).
+     */
+    private parseGoSum;
+    /**
+     * Parses go.mod to extract direct and indirect dependency names.
+     *
+     * Handles both single-line and block `require` directives:
+     * ```
+     * require github.com/pkg/errors v0.9.1
+     *
+     * require (
+     *     github.com/gin-gonic/gin v1.9.1
+     *     golang.org/x/text v0.14.0 // indirect
+     * )
+     * ```
+     */
+    private parseGoMod;
+    /**
+     * Builds a purl for a Go module.
+     *
+     * Per purl spec, the type is "golang" and the module path
+     * uses `/` separators (no encoding needed for path segments).
+     *
+     * Example: `pkg:golang/github.com/gin-gonic/gin@v1.9.1`
+     */
+    private buildPurl;
+}
+
+/**
+ * Ruby dependency scanner (Bundler).
+ *
+ * Parses `Gemfile.lock` to extract the full resolved dependency list,
+ * and cross-references the `DEPENDENCIES` section to distinguish
+ * direct vs transitive gems.
+ *
+ * Gemfile.lock format:
+ * ```
+ * GEM
+ *   remote: https://rubygems.org/
+ *   specs:
+ *     actioncable (7.1.2)
+ *       actionpack (= 7.1.2)
+ *       activesupport (= 7.1.2)
+ *     rack (3.0.8)
+ *
+ * PLATFORMS
+ *   ruby
+ *
+ * DEPENDENCIES
+ *   puma (>= 5.0)
+ *   rails (~> 7.1.2)
+ *
+ * BUNDLED WITH
+ *   2.5.3
+ * ```
+ *
+ * The `GEM > specs:` section lists all resolved gems with exact versions.
+ * The `DEPENDENCIES` section lists direct gems (from the Gemfile).
+ */
+declare class RubyScanner implements DependencyScanner {
+    readonly ecosystem: Ecosystem;
+    readonly lockfileNames: string[];
+    detect(projectPath: string): Promise<string | null>;
+    scan(projectPath: string, lockfilePath: string): Promise<ScanResult>;
+    /**
+     * Parses the GEM > specs section to extract all resolved gems.
+     *
+     * Gems at the top level of the specs section (indented 4 spaces) are
+     * resolved packages. Their sub-dependencies (indented 6+ spaces) are
+     * constraints, not separate entries — those sub-deps appear as their
+     * own top-level spec entries elsewhere.
+     *
+     * Format: `    gem-name (1.2.3)`
+     */
+    private parseSpecs;
+    /**
+     * Parses the DEPENDENCIES section to get direct dependency names.
+     *
+     * Format: `  gem-name (>= 1.0)` or `  gem-name`
+     * The version constraint is optional and we only need the name.
+     */
+    private parseDependencies;
+}
+
 /**
  * Registry of all available dependency scanners.
  * Auto-detects the correct scanner for a given project.
@@ -472,4 +810,4 @@ declare class ConsoleReporter implements Reporter {
     report(result: VerimuReport): string;
 }
 
-export { ApiKeyRequiredError, type CiProvider, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, LockfileParseError, NoLockfileError, NpmScanner, OsvSource, type Sbom, type SbomDependency, type SbomFormat, type ScanResult, ScannerRegistry, type Severity, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, generateSbom, printReport, scan, shouldFailCi };
+export { ApiKeyRequiredError, CargoScanner, type CiProvider, ConsoleReporter, CveAggregator, type CveCheckResult, CveSourceError, CycloneDxGenerator, type Dependency, type Ecosystem, type GenerateSbomInput, type GenerateSbomResult, GoScanner, LockfileParseError, MavenScanner, NoLockfileError, NpmScanner, NugetScanner, OsvSource, PipScanner, RubyScanner, type Sbom, type SbomDependency, type SbomFormat, type ScanResult, ScannerRegistry, type Severity, type VerimuConfig, VerimuError, type VerimuReport, type Vulnerability, type VulnerabilitySource, generateSbom, printReport, scan, shouldFailCi };