trawly 0.0.1 → 0.1.1

package/dist/index.d.ts

@@ -1,30 +1,48 @@
 type Severity = "critical" | "high" | "moderate" | "low" | "unknown";
-type Ecosystem = "npm";
-type FindingType = "vulnerability" | "malware" | "risk-signal" | "integrity";
+type Ecosystem = string;
+type FindingType = "vulnerability" | "malware" | "secret" | "risk-signal" | "integrity";
+type FindingSource = "osv" | "trawly";
+type InputKind = "lockfile" | "sbom" | "adhoc";
 declare const SEVERITY_RANK: Record<Severity, number>;
 interface PackageInstance {
     name: string;
     version: string;
     ecosystem: Ecosystem;
-    /** Path within the lockfile's `packages` map (e.g. "node_modules/foo"). */
+    /** Path within the source manifest, e.g. "node_modules/foo" or an SBOM ref. */
     path: string;
     direct: boolean;
     dev: boolean;
     optional: boolean;
+    inputKind?: InputKind;
+    purl?: string;
+    sourceFile?: string;
+    line?: number;
+    manager?: "npm" | "pnpm" | "yarn" | "sbom" | string;
     resolved?: string;
     integrity?: string;
+    registry?: string;
+    hasInstallScript?: boolean;
+    publishedAt?: string;
+    packagePublishedAt?: string;
 }
 interface Finding {
     id: string;
-    source: "osv";
+    source: FindingSource;
     type: FindingType;
     severity: Severity;
+    ecosystem: Ecosystem;
     packageName: string;
     installedVersion: string;
     summary: string;
     url?: string;
     fixedVersions: string[];
     affectedPaths: string[];
+    fingerprint: string;
+    aliases: string[];
+    sourceFile?: string;
+    line?: number;
+    ignored?: boolean;
+    baseline?: "new" | "existing";
 }
 interface ScanError {
     message: string;
@@ -34,24 +52,75 @@ interface ScanResult {
     scannedAt: string;
     packagesScanned: number;
     findings: Finding[];
+    ignoredFindings: Finding[];
     summary: Record<Severity, number>;
     errors: ScanError[];
+    warnings: string[];
+    baseline?: BaselineResult;
+}
+interface IgnoreEntry {
+    id: string;
+    package?: string;
+    ecosystem?: string;
+    version?: string;
+    expires: string;
+    reason: string;
+}
+interface TrawlyConfig {
+    failOn?: FailOnLevel;
+    policy?: PolicyPresetName;
+    risk?: boolean;
+    env?: boolean;
+    allowedRegistries?: string[];
+    ignore: IgnoreEntry[];
+}
+interface BaselineFile {
+    version: 1;
+    generatedAt: string;
+    findings: string[];
+}
+interface BaselineResult {
+    path?: string;
+    loaded: boolean;
+    written?: string;
+    total: number;
+    existing: number;
+    new: number;
 }
 interface ScanProjectOptions {
     cwd?: string;
-    lockfile?: string;
+    lockfile?: string | string[];
+    sbom?: string | string[];
+    config?: string;
+    policy?: PolicyPresetName;
+    baseline?: string;
+    writeBaseline?: string;
+    risk?: boolean;
+    env?: boolean;
+    allowedRegistries?: string[];
     includeDev?: boolean;
     prodOnly?: boolean;
-    cache?: boolean;
     fetchImpl?: typeof fetch;
+    now?: Date;
 }
 interface ScanLockfileOptions {
-    lockfilePath: string;
+    lockfilePath: string | string[];
+    sbom?: string | string[];
+    cwd?: string;
+    config?: string;
+    policy?: PolicyPresetName;
+    baseline?: string;
+    writeBaseline?: string;
+    risk?: boolean;
+    env?: boolean;
+    allowedRegistries?: string[];
     includeDev?: boolean;
     prodOnly?: boolean;
     fetchImpl?: typeof fetch;
+    now?: Date;
 }
 type FailOnLevel = Severity | "none";
+type PolicyPresetName = "ci" | "strict" | "library" | "app";
 
 declare function scanProject(options?: ScanProjectOptions): Promise<ScanResult>;
 declare function scanLockfile(options: ScanLockfileOptions): Promise<ScanResult>;
@@ -66,6 +135,81 @@ declare function summarize(findings: Finding[]): Record<Severity, number>;
  */
 declare function meetsThreshold(findings: Finding[], threshold: Severity | "none"): boolean;
 
+type EnvIssueKind = "tracked-by-git" | "not-gitignored" | "would-be-published" | "secret-in-example" | "no-gitignore";
+interface EnvIssue {
+    kind: EnvIssueKind;
+    severity: Severity;
+    file: string;
+    message: string;
+    detail?: string;
+}
+interface EnvScanResult$1 {
+    scannedAt: string;
+    cwd: string;
+    envFiles: string[];
+    issues: EnvIssue[];
+    summary: Record<Severity, number>;
+    errors: {
+        message: string;
+        cause?: string;
+    }[];
+}
+interface EnvScanOptions {
+    cwd?: string;
+    /** Cap on directory recursion depth from cwd. Default 6. */
+    maxDepth?: number;
+    /** Override directory skip list (replaces the default). */
+    skipDirs?: string[];
+}
+declare function scanEnv(options?: EnvScanOptions): Promise<EnvScanResult$1>;
+declare function envIssuesMeetThreshold(issues: EnvIssue[], threshold: Severity | "none"): boolean;
+
+interface InitOptions {
+    cwd?: string;
+    config?: string;
+    baseline?: string;
+    policy?: PolicyPresetName;
+    risk?: boolean;
+    env?: boolean;
+    writeBaseline?: boolean;
+    overwrite?: boolean;
+    fetchImpl?: typeof fetch;
+}
+interface InitResult {
+    configPath: string;
+    configWritten: boolean;
+    baselinePath?: string;
+    baselineWritten: boolean;
+    scan?: ScanResult;
+    warnings: string[];
+}
+declare function initProject(options?: InitOptions): Promise<InitResult>;
+
+interface WhyOptions {
+    cwd?: string;
+    lockfile?: string | string[];
+}
+interface WhyMatch {
+    package: PackageInstance;
+    chain: string[];
+    note?: string;
+}
+interface WhyResult {
+    packageName: string;
+    lockfiles: string[];
+    matches: WhyMatch[];
+}
+declare function explainWhy(packageName: string, options?: WhyOptions): WhyResult;
+
+interface PolicyPreset {
+    failOn: FailOnLevel;
+    risk: boolean;
+    env: boolean;
+    includeDev: boolean;
+}
+declare const POLICY_PRESETS: Record<PolicyPresetName, PolicyPreset>;
+declare function resolvePolicy(requested: PolicyPresetName | undefined, configured: PolicyPresetName | undefined): PolicyPreset | undefined;
+
 /**
  * Parse an npm `package-lock.json` (v2 or v3) and return one
  * PackageInstance per node in the `packages` map.
@@ -74,12 +218,51 @@ declare function meetsThreshold(findings: Finding[], threshold: Severity | "none
  */
 declare function parseNpmPackageLock(filePath: string): PackageInstance[];
 
+declare function parsePnpmLock(filePath: string): PackageInstance[];
+declare function parsePnpmPackageKey(key: string): {
+    name: string;
+    version: string;
+} | null;
+
+declare function parseYarnLock(filePath: string): PackageInstance[];
+declare function parseYarnDescriptorName(descriptor: string): string | null;
+
+declare function parseLockfile(filePath: string): PackageInstance[];
+
+interface PurlPackage {
+    name: string;
+    version: string;
+    ecosystem: Ecosystem;
+    purl: string;
+}
+declare function parseSbom(filePath: string): PackageInstance[];
+declare function parsePurlPackage(purl: string): PurlPackage | null;
+
+interface EnvScanResult {
+    findings: Finding[];
+    warnings: string[];
+    filesScanned: number;
+}
+declare function scanEnvFiles(cwd: string): EnvScanResult;
+
+interface AppliedBaseline {
+    result: BaselineResult;
+    findings: Finding[];
+}
+declare class BaselineError extends Error {
+    constructor(message: string);
+}
+declare function applyBaseline(findings: Finding[], cwd: string, baselinePath?: string): AppliedBaseline | undefined;
+declare function writeBaseline(findings: Finding[], cwd: string, baselinePath: string, existing?: BaselineResult): BaselineResult;
+
 interface OsvQueryDeps {
     fetchImpl?: typeof fetch;
 }
 interface UniquePackage {
     name: string;
     version: string;
+    ecosystem?: Ecosystem;
+    purl?: string;
 }
 /**
  * Build the deduplicated list of unique name@version pairs to query OSV with.
@@ -91,4 +274,15 @@ declare function dedupeForQuery(packages: PackageInstance[]): UniquePackage[];
  */
 declare function queryOsv(packages: PackageInstance[], deps?: OsvQueryDeps): Promise<Finding[]>;
 
-export { type Ecosystem, type FailOnLevel, type Finding, type FindingType, type PackageInstance, SEVERITY_RANK, type ScanError, ScanInputError, type ScanLockfileOptions, type ScanProjectOptions, type ScanResult, type Severity, compareFindings, dedupeForQuery, meetsThreshold, parseNpmPackageLock, queryOsv, scanLockfile, scanProject, summarize };
+interface LoadedConfig {
+    path?: string;
+    config: TrawlyConfig;
+}
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+declare function loadConfig(cwd: string, explicitPath?: string): LoadedConfig;
+
+declare const TRAWLY_VERSION: string;
+
+export { type AppliedBaseline, BaselineError, type BaselineFile, type BaselineResult, ConfigError, type Ecosystem, type EnvIssue, type EnvIssueKind, type EnvScanOptions, type EnvScanResult$1 as EnvScanResult, type FailOnLevel, type Finding, type FindingSource, type FindingType, type IgnoreEntry, type InputKind, POLICY_PRESETS, type PackageInstance, type PolicyPresetName, SEVERITY_RANK, type ScanError, ScanInputError, type ScanLockfileOptions, type ScanProjectOptions, type ScanResult, type Severity, TRAWLY_VERSION, type TrawlyConfig, applyBaseline, compareFindings, dedupeForQuery, envIssuesMeetThreshold, explainWhy, initProject, loadConfig, meetsThreshold, parseLockfile, parseNpmPackageLock, parsePnpmLock, parsePnpmPackageKey, parsePurlPackage, parseSbom, parseYarnDescriptorName, parseYarnLock, queryOsv, resolvePolicy, scanEnv, scanEnvFiles, scanLockfile, scanProject, summarize, writeBaseline };