vetguard 0.0.0 → 0.2.0

package/dist/cli.js

@@ -1,13 +1,21 @@
 #!/usr/bin/env node
 import {
+  BaselineError,
+  ConfigError,
   VERSION,
   checkPackage,
+  diffScan,
+  loadConfig,
+  readBaseline,
   renderJson,
+  renderMarkdown,
   renderSarif,
   renderTerminal,
   resolveExitCode,
-  scanProject
-} from "./chunk-XXICU3EZ.js";
+  scanProject,
+  toBaselineEntries,
+  writeBaseline
+} from "./chunk-2DIOTV5P.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -18,14 +26,23 @@ Usage:
   vetguard scan [dir]        Scan a project's dependencies (defaults to cwd)
   vetguard check <pkg>       Vet a single package before installing
                              (e.g. vetguard check react-codeshift, foo@1.2.3)
+  vetguard diff --base <lockfile> [--head <lockfile>]
+                             Scan only the dependencies a change introduces
+                             (head defaults to ./package-lock.json)
+  vetguard baseline [dir]    Record current findings to .vetguard-baseline.json;
+                             later scans report those as baselined and fail only
+                             on new findings (adopt on a messy repo, ratchet down)
   vetguard --help            Show this help
   vetguard --version         Show version
 
 Options:
   --offline                  Do not contact the registry; unverifiable facts
                              are reported as "could not verify", never "safe".
-  --json                     Print the report as JSON instead of text.
+  --json                     Print the report as JSON.
   --sarif                    Print SARIF 2.1.0 for GitHub code scanning.
+  --markdown                 Print compact markdown for a PR comment or summary.
+  --quiet                    Print only findings and the verdict.
+  --no-color                 Disable ANSI colors (also respects NO_COLOR).
   --fail-on <severity>       Exit non-zero only when a finding at or above this
                              severity exists (critical|high|medium|low|info).
                              Default: any finding exits non-zero.
@@ -43,7 +60,12 @@ async function main(argv) {
       offline: { type: "boolean" },
       json: { type: "boolean" },
       sarif: { type: "boolean" },
-      "fail-on": { type: "string" }
+      markdown: { type: "boolean" },
+      quiet: { type: "boolean" },
+      "no-color": { type: "boolean" },
+      "fail-on": { type: "string" },
+      base: { type: "string" },
+      head: { type: "string" }
     }
   });
   if (values.version) {
@@ -60,14 +82,22 @@ async function main(argv) {
     console.error(`Invalid --fail-on value: ${failOnRaw} (expected ${SEVERITIES.join(", ")})`);
     return 2;
   }
+  const color = process.stdout.isTTY === true && !process.env.NO_COLOR && values["no-color"] !== true && values.json !== true && values.sarif !== true && values.markdown !== true;
   const options = {
     offline: values.offline === true,
     json: values.json === true,
     sarif: values.sarif === true,
+    markdown: values.markdown === true,
+    quiet: values.quiet === true,
+    color,
     failOn: failOnRaw
   };
   if (command === "scan") {
-    return runScan(positionals[1] ?? process.cwd(), options);
+    const dir = positionals[1] ?? process.cwd();
+    return runReport(dir, options, (opts) => scanProject(dir, opts), dir);
+  }
+  if (command === "baseline") {
+    return runBaseline(positionals[1] ?? process.cwd(), options);
   }
   if (command === "check") {
     const spec = positionals[1];
@@ -76,31 +106,85 @@ async function main(argv) {
       console.error(HELP);
       return 2;
     }
-    return runCheck(spec, options);
+    return runReport(process.cwd(), options, (opts) => checkPackage(spec, opts));
+  }
+  if (command === "diff") {
+    if (values.base === void 0) {
+      console.error("diff requires --base <lockfile> (the base package-lock.json)\n");
+      console.error(HELP);
+      return 2;
+    }
+    const head = values.head ?? "package-lock.json";
+    return runReport(process.cwd(), options, (opts) => diffScan(values.base, head, opts));
   }
   console.error(`Unknown command: ${command}
 `);
   console.error(HELP);
   return 2;
 }
-async function runScan(dir, options) {
+async function runReport(configDir, cli, produce, baselineDir) {
+  let scanOptions;
+  let failOn;
+  try {
+    const config = await loadConfig(configDir);
+    const baseline = baselineDir ? await readBaseline(baselineDir) : void 0;
+    failOn = cli.failOn ?? config?.failOn;
+    scanOptions = {
+      offline: cli.offline || config?.offline === true,
+      ...config?.ignore ? { ignore: config.ignore } : {},
+      ...baseline ? { baseline } : {}
+    };
+  } catch (err) {
+    if (err instanceof ConfigError || err instanceof BaselineError) {
+      console.error(err.message);
+      return 2;
+    }
+    throw err;
+  }
   let report;
   try {
-    report = await scanProject(dir, { offline: options.offline });
+    report = await produce(scanOptions);
   } catch (err) {
     console.error(err instanceof Error ? err.message : String(err));
     return 2;
   }
-  return emit(report, options);
+  console.log(render(report, cli));
+  return resolveExitCode(report, failOn);
 }
-async function runCheck(specInput, options) {
-  const report = await checkPackage(specInput, { offline: options.offline });
-  return emit(report, options);
+async function runBaseline(dir, cli) {
+  let scanOptions;
+  try {
+    const config = await loadConfig(dir);
+    scanOptions = {
+      offline: cli.offline || config?.offline === true,
+      ...config?.ignore ? { ignore: config.ignore } : {}
+    };
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      console.error(err.message);
+      return 2;
+    }
+    throw err;
+  }
+  let report;
+  try {
+    report = await scanProject(dir, scanOptions);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+  const entries = toBaselineEntries(report.findings);
+  const filePath = await writeBaseline(dir, entries, (/* @__PURE__ */ new Date()).toISOString());
+  console.log(
+    `Recorded ${entries.length} finding(s) to ${filePath}. Future scans report these as baselined and fail only on new findings.`
+  );
+  return 0;
 }
-function emit(report, options) {
-  const output = options.sarif ? renderSarif(report, VERSION) : options.json ? renderJson(report, VERSION) : renderTerminal(report);
-  console.log(output);
-  return resolveExitCode(report, options.failOn);
+function render(report, options) {
+  if (options.sarif) return renderSarif(report, VERSION);
+  if (options.markdown) return renderMarkdown(report);
+  if (options.json) return renderJson(report, VERSION);
+  return renderTerminal(report, { color: options.color, quiet: options.quiet });
 }
 main(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
   console.error(err instanceof Error ? err.stack : String(err));

package/dist/index.d.ts

@@ -24,6 +24,12 @@ interface PackageFacts {
     source: DependencySource;
     /** Whether the registry has any record of this name at all. */
     existsOnRegistry?: boolean;
+    /**
+     * When existence is unknown, why: the registry was deliberately not consulted
+     * (`offline`) or a lookup failed (`error`). Lets a detector offer an
+     * offline-only heuristic without firing on a transient online failure.
+     */
+    existenceUnverifiedReason?: "offline" | "error";
     /** Whether this exact version is still published. */
     versionPublished?: boolean;
     firstPublishAt?: string;
@@ -60,6 +66,32 @@ interface Detector {
     description: string;
     detect(pkg: PackageFacts): Finding[];
 }
+/**
+ * A configured suppression. A finding matching `rule` and `package` is not
+ * counted toward the verdict, but is still reported as suppressed. The reason
+ * is mandatory: a suppression the team cannot explain is a suppression that
+ * should not exist.
+ */
+interface IgnoreRule {
+    rule: string;
+    package: string;
+    reason: string;
+}
+/** A finding that matched an ignore rule; shown as suppressed, never hidden. */
+type SuppressedFinding = Finding & {
+    suppressedReason: string;
+};
+/**
+ * One entry in a recorded baseline. A finding matching a baseline entry is
+ * pre-existing (it was present when the baseline was taken) and is reported as
+ * suppressed rather than failing the build; only findings absent from the
+ * baseline are new. Matched by rule, package, and exact version.
+ */
+interface BaselineEntry {
+    rule: string;
+    package: string;
+    version?: string;
+}
 type ScanVerdict = "clean" | "findings" | "could-not-verify";
 interface Report {
     verdict: ScanVerdict;
@@ -67,6 +99,8 @@ interface Report {
     ecosystem: string;
     packagesScanned: number;
     findings: Finding[];
+    /** Findings suppressed by a configured ignore rule; do not affect the verdict. */
+    suppressed?: SuppressedFinding[];
     /** Packages we could not fully verify (offline, unsupported source, etc.). */
     unverified: string[];
     generatedAt: string;
@@ -78,22 +112,86 @@ interface Report {
 declare const SEVERITY_ORDER: Record<Severity, number>;
 
 /**
- * Runs every detector over every package's facts and aggregates a report.
- * This is deliberately pure: given the same facts and detectors it produces
- * the same report, which is what makes CI runs deterministic and testable.
+ * Partitions findings into those that remain active and those a configured
+ * ignore rule suppresses. A suppressed finding keeps its data and gains the
+ * ignore's reason, so it is reported as suppressed rather than silently
+ * dropped. Active findings alone drive the verdict and exit code.
+ */
+declare function applyIgnores(findings: readonly Finding[], ignores: readonly IgnoreRule[]): {
+    active: Finding[];
+    suppressed: SuppressedFinding[];
+};
+
+/**
+ * Partitions findings into new (absent from the baseline) and pre-existing
+ * (present in it). A baselined finding is reported as suppressed, so the
+ * pre-existing state is visible but only genuinely new findings drive the
+ * verdict. This is what lets a project adopt vetguard on a messy tree today and
+ * ratchet the baseline down over time.
  */
-declare function runDetectors(facts: PackageFacts[], detectors: Detector[], context: {
+declare function applyBaseline(findings: readonly Finding[], baseline: readonly BaselineEntry[]): {
+    active: Finding[];
+    suppressed: SuppressedFinding[];
+};
+/** Reduces findings to baseline entries, the snapshot a `baseline` run records. */
+declare function toBaselineEntries(findings: readonly Finding[]): BaselineEntry[];
+
+declare const CONFIG_FILENAME = "vetguard.config.json";
+interface Config {
+    failOn?: Severity;
+    offline?: boolean;
+    ignore?: IgnoreRule[];
+}
+/** Thrown for an invalid config so the CLI can exit with a clear message. */
+declare class ConfigError extends Error {
+}
+/**
+ * Loads `vetguard.config.json` from a directory. Returns undefined when there
+ * is no config file; throws `ConfigError` when the file exists but is invalid,
+ * so a malformed config (or an ignore missing its reason) fails loudly.
+ */
+declare function loadConfig(dir: string): Promise<Config | undefined>;
+
+declare const BASELINE_FILENAME = ".vetguard-baseline.json";
+/** Thrown for an unreadable/invalid baseline so the CLI can exit with a clear message. */
+declare class BaselineError extends Error {
+}
+/**
+ * Reads baseline entries from a directory. Returns undefined when there is no
+ * baseline file; throws `BaselineError` when the file exists but is invalid, so
+ * a corrupt baseline is never silently treated as empty (which would fail every
+ * pre-existing finding).
+ */
+declare function readBaseline(dir: string): Promise<BaselineEntry[] | undefined>;
+/** Writes the baseline snapshot for a directory. */
+declare function writeBaseline(dir: string, findings: BaselineEntry[], generatedAt: string): Promise<string>;
+
+interface DetectContext {
     target: string;
     ecosystem: string;
     unverified: string[];
     generatedAt: string;
-}): Report;
+    ignore?: readonly IgnoreRule[];
+    baseline?: readonly BaselineEntry[];
+}
+/**
+ * Runs every detector over every package's facts and aggregates a report.
+ * This is deliberately pure: given the same facts and detectors it produces
+ * the same report, which is what makes CI runs deterministic and testable.
+ */
+declare function runDetectors(facts: PackageFacts[], detectors: Detector[], context: DetectContext): Report;
 
 /** All built-in detectors. New detectors are registered here. */
 declare const builtinDetectors: Detector[];
 
-/** Renders a report as plain text. No color codes yet; kept dependency-free. */
-declare function renderTerminal(report: Report): string;
+interface TerminalOptions {
+    /** ANSI colors; the CLI enables this only on a TTY without NO_COLOR. */
+    color?: boolean;
+    /** Print only findings and the verdict, no header or informational lines. */
+    quiet?: boolean;
+}
+/** Renders a report as text. Dependency-free; colors are opt-in and TTY-gated by the caller. */
+declare function renderTerminal(report: Report, options?: TerminalOptions): string;
 
 /** Bumped when the JSON shape changes in a way consumers must adapt to. */
 declare const JSON_SCHEMA_VERSION = 1;
@@ -107,6 +205,11 @@ declare function renderJson(report: Report, toolVersion: string): string;
  */
 declare function renderSarif(report: Report, toolVersion: string, detectors?: Detector[]): string;
 
+/** Marker so an automated PR comment can find and update its previous post in place. */
+declare const MARKDOWN_COMMENT_MARKER = "<!-- vetguard-report -->";
+/** Renders a report as compact markdown for a PR comment or CI job summary. */
+declare function renderMarkdown(report: Report): string;
+
 /**
  * The process exit code for a report. No findings is always 0. With no
  * threshold any finding is 1; with a threshold only a finding at or above that
@@ -114,6 +217,15 @@ declare function renderSarif(report: Report, toolVersion: string, detectors?: De
  */
 declare function resolveExitCode(report: Report, failOn: Severity | undefined): number;
 
+/**
+ * The facts present in `head` but not in `base`, keyed by resolved identity.
+ * This is every dependency a change introduces: a brand-new name, a new
+ * version, a downgrade, and a same-version repoint (changed integrity or
+ * resolved URL). An identical entry in both is dropped, so a diff scan judges
+ * only what the change actually adds.
+ */
+declare function introducedFacts(base: readonly PackageFacts[], head: readonly PackageFacts[]): PackageFacts[];
+
 /**
  * Classifies a version specifier into how we can verify it. A registry range
  * is checkable against the registry; git/file/link/alias/workspace specifiers
@@ -143,11 +255,13 @@ type LockfileOutcome = {
 /** Extracts the package name from a lockfile path key, handling nesting and scopes. */
 declare function nameFromLockPath(lockPath: string): string | undefined;
 /**
- * Reads resolved dependency facts from a package-lock.json (v2 or v3). Returns
- * `absent` when there is no lockfile and `unsupported` for a shape we do not
- * parse (v1, or a missing `packages` map), so the caller can fall back to the
- * manifest and say so rather than silently skipping.
+ * Reads resolved dependency facts from a specific package-lock.json file (v2 or
+ * v3). Returns `absent` when the file is missing and `unsupported` for a shape
+ * we do not parse (v1, or a missing `packages` map), so the caller can fall
+ * back or report rather than silently skipping.
  */
+declare function readLockfileFile(lockPath: string): Promise<LockfileOutcome>;
+/** Reads the `package-lock.json` in a project directory. */
 declare function readLockfile(dir: string): Promise<LockfileOutcome>;
 
 /**
@@ -244,6 +358,10 @@ interface ScanOptions {
     client?: RegistryClient;
     downloads?: DownloadsClient;
     detectors?: Detector[];
+    /** Suppressions from config; matched findings are reported but do not affect the verdict. */
+    ignore?: readonly IgnoreRule[];
+    /** Recorded baseline; matched (pre-existing) findings are reported but do not affect the verdict. */
+    baseline?: readonly BaselineEntry[];
     /** Injected for a deterministic `generatedAt` and age in tests. */
     now?: () => Date;
 }
@@ -253,6 +371,14 @@ interface ScanOptions {
  * an unsupported shape, recording a warning so the fallback is never silent.
  */
 declare function scanProject(dir: string, options?: ScanOptions): Promise<Report>;
+/**
+ * Scans only the dependencies a change introduces: those present in the head
+ * lockfile but not the base (a new name, a new version, or a downgrade). Both
+ * must be package-lock v2/v3; an absent or unsupported lockfile on either side
+ * throws, because a partial diff would silently under-report. This is the
+ * highest-signal moment, a dependency entering a pull request.
+ */
+declare function diffScan(basePath: string, headPath: string, options?: ScanOptions): Promise<Report>;
 /** Vets a single package spec (`name`, `name@version`, `@scope/name@version`). */
 declare function checkPackage(specInput: string, options?: ScanOptions): Promise<Report>;
 
@@ -260,4 +386,4 @@ declare function checkPackage(specInput: string, options?: ScanOptions): Promise
 
 declare const VERSION: string;
 
-export { type Confidence, type DependencyKind, type DependencySource, type Detector, type DownloadsClient, type DownloadsClientOptions, type EnrichOptions, type EnrichmentResult, type Finding, JSON_SCHEMA_VERSION, type LockfileOutcome, type PackageFacts, type PackageSpec, type Packument, type RegistryClient, type RegistryClientOptions, type RegistryLookup, type Report, SEVERITY_ORDER, type ScanOptions, type ScanVerdict, type Severity, VERSION, builtinDetectors, checkPackage, classifySource, createDownloadsClient, createRegistryClient, detectOtherLockfiles, encodePackageName, enrichWithRegistry, nameFromLockPath, parsePackageSpec, readLockfile, readManifestFacts, renderJson, renderSarif, renderTerminal, resolveExitCode, runDetectors, scanProject };
+export { BASELINE_FILENAME, type BaselineEntry, BaselineError, CONFIG_FILENAME, type Confidence, type Config, ConfigError, type DependencyKind, type DependencySource, type Detector, type DownloadsClient, type DownloadsClientOptions, type EnrichOptions, type EnrichmentResult, type Finding, type IgnoreRule, JSON_SCHEMA_VERSION, type LockfileOutcome, MARKDOWN_COMMENT_MARKER, type PackageFacts, type PackageSpec, type Packument, type RegistryClient, type RegistryClientOptions, type RegistryLookup, type Report, SEVERITY_ORDER, type ScanOptions, type ScanVerdict, type Severity, type SuppressedFinding, VERSION, applyBaseline, applyIgnores, builtinDetectors, checkPackage, classifySource, createDownloadsClient, createRegistryClient, detectOtherLockfiles, diffScan, encodePackageName, enrichWithRegistry, introducedFacts, loadConfig, nameFromLockPath, parsePackageSpec, readBaseline, readLockfile, readLockfileFile, readManifestFacts, renderJson, renderMarkdown, renderSarif, renderTerminal, resolveExitCode, runDetectors, scanProject, toBaselineEntries, writeBaseline };

package/dist/index.js

@@ -1,46 +1,76 @@
 import {
+  BASELINE_FILENAME,
+  BaselineError,
+  CONFIG_FILENAME,
+  ConfigError,
   JSON_SCHEMA_VERSION,
+  MARKDOWN_COMMENT_MARKER,
   SEVERITY_ORDER,
   VERSION,
+  applyBaseline,
+  applyIgnores,
   builtinDetectors,
   checkPackage,
   classifySource,
   createDownloadsClient,
   createRegistryClient,
   detectOtherLockfiles,
+  diffScan,
   encodePackageName,
   enrichWithRegistry,
+  introducedFacts,
+  loadConfig,
   nameFromLockPath,
   parsePackageSpec,
+  readBaseline,
   readLockfile,
+  readLockfileFile,
   readManifestFacts,
   renderJson,
+  renderMarkdown,
   renderSarif,
   renderTerminal,
   resolveExitCode,
   runDetectors,
-  scanProject
-} from "./chunk-XXICU3EZ.js";
+  scanProject,
+  toBaselineEntries,
+  writeBaseline
+} from "./chunk-2DIOTV5P.js";
 export {
+  BASELINE_FILENAME,
+  BaselineError,
+  CONFIG_FILENAME,
+  ConfigError,
   JSON_SCHEMA_VERSION,
+  MARKDOWN_COMMENT_MARKER,
   SEVERITY_ORDER,
   VERSION,
+  applyBaseline,
+  applyIgnores,
   builtinDetectors,
   checkPackage,
   classifySource,
   createDownloadsClient,
   createRegistryClient,
   detectOtherLockfiles,
+  diffScan,
   encodePackageName,
   enrichWithRegistry,
+  introducedFacts,
+  loadConfig,
   nameFromLockPath,
   parsePackageSpec,
+  readBaseline,
   readLockfile,
+  readLockfileFile,
   readManifestFacts,
   renderJson,
+  renderMarkdown,
   renderSarif,
   renderTerminal,
   resolveExitCode,
   runDetectors,
-  scanProject
+  scanProject,
+  toBaselineEntries,
+  writeBaseline
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vetguard",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "Local-first scanner for AI-era npm supply-chain threats: hallucinated (slopsquatted) dependencies, typosquats, malicious young packages, and prompt injection aimed at coding agents.",
   "keywords": [
     "npm",
@@ -67,6 +67,6 @@
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.10"
   }
 }