vetguard 0.0.0

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import {
+  VERSION,
+  checkPackage,
+  renderJson,
+  renderSarif,
+  renderTerminal,
+  resolveExitCode,
+  scanProject
+} from "./chunk-XXICU3EZ.js";
+
+// src/cli.ts
+import { parseArgs } from "util";
+import process from "process";
+var HELP = `vetguard ${VERSION} - scan npm dependencies for AI-era supply-chain threats
+
+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 --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.
+  --sarif                    Print SARIF 2.1.0 for GitHub code scanning.
+  --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.
+
+vetguard never executes the code it scans. When it cannot verify something it
+says so rather than calling it safe.`;
+var SEVERITIES = ["critical", "high", "medium", "low", "info"];
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+      offline: { type: "boolean" },
+      json: { type: "boolean" },
+      sarif: { type: "boolean" },
+      "fail-on": { type: "string" }
+    }
+  });
+  if (values.version) {
+    console.log(VERSION);
+    return 0;
+  }
+  const command = positionals[0];
+  if (values.help || command === void 0 || command === "help") {
+    console.log(HELP);
+    return 0;
+  }
+  const failOnRaw = values["fail-on"];
+  if (failOnRaw !== void 0 && !SEVERITIES.includes(failOnRaw)) {
+    console.error(`Invalid --fail-on value: ${failOnRaw} (expected ${SEVERITIES.join(", ")})`);
+    return 2;
+  }
+  const options = {
+    offline: values.offline === true,
+    json: values.json === true,
+    sarif: values.sarif === true,
+    failOn: failOnRaw
+  };
+  if (command === "scan") {
+    return runScan(positionals[1] ?? process.cwd(), options);
+  }
+  if (command === "check") {
+    const spec = positionals[1];
+    if (spec === void 0) {
+      console.error("check requires a package name, e.g. vetguard check express\n");
+      console.error(HELP);
+      return 2;
+    }
+    return runCheck(spec, options);
+  }
+  console.error(`Unknown command: ${command}
+`);
+  console.error(HELP);
+  return 2;
+}
+async function runScan(dir, options) {
+  let report;
+  try {
+    report = await scanProject(dir, { offline: options.offline });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+  return emit(report, options);
+}
+async function runCheck(specInput, options) {
+  const report = await checkPackage(specInput, { offline: options.offline });
+  return emit(report, options);
+}
+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);
+}
+main(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
+  console.error(err instanceof Error ? err.stack : String(err));
+  process.exit(2);
+});

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Core data model. These types are the contract between collectors (which do
+ * all IO) and detectors (pure functions that judge). Nothing here does IO.
+ */
+type Severity = "critical" | "high" | "medium" | "low" | "info";
+/** How sure we are the finding is real, distinct from how bad it would be. */
+type Confidence = "high" | "medium" | "low";
+/** How a package entered the dependency graph, so findings can be traced back. */
+type DependencyKind = "prod" | "dev" | "peer" | "optional" | "bundled" | "transitive";
+/** How the version was specified, which decides what we can verify about it. */
+type DependencySource = "registry" | "git" | "file" | "link" | "alias" | "workspace" | "unknown";
+/**
+ * The facts a collector gathers about one resolved dependency. Detectors read
+ * these; they never reach out to the network or filesystem themselves. Fields
+ * are optional because a fact may be genuinely unknowable (offline, private
+ * registry, git dependency), and "unknown" must never be treated as "safe".
+ */
+interface PackageFacts {
+    name: string;
+    /** Resolved version from the lockfile, if any. */
+    version?: string;
+    requestedRange?: string;
+    kind: DependencyKind;
+    source: DependencySource;
+    /** Whether the registry has any record of this name at all. */
+    existsOnRegistry?: boolean;
+    /** Whether this exact version is still published. */
+    versionPublished?: boolean;
+    firstPublishAt?: string;
+    latestPublishAt?: string;
+    /** Days since the package name was first published, computed at collection time. */
+    ageDays?: number;
+    /** Number of published versions of this name. */
+    versionCount?: number;
+    weeklyDownloads?: number;
+    hasInstallScript?: boolean;
+    repositoryUrl?: string;
+    integrity?: string;
+    resolvedUrl?: string;
+    /** Where this fact set came from, for traceable verdicts. */
+    evidencePath?: string;
+}
+/** A single detector result. Evidence is always quoted, never live content. */
+interface Finding {
+    ruleId: string;
+    severity: Severity;
+    confidence: Confidence;
+    packageName: string;
+    packageVersion?: string;
+    title: string;
+    /** One line: why this matters. */
+    detail: string;
+    /** Concrete, escaped, truncated evidence backing the finding. */
+    evidence?: string;
+    location?: string;
+}
+/** A pure detector: facts in, findings out. No IO, no side effects. */
+interface Detector {
+    id: string;
+    description: string;
+    detect(pkg: PackageFacts): Finding[];
+}
+type ScanVerdict = "clean" | "findings" | "could-not-verify";
+interface Report {
+    verdict: ScanVerdict;
+    target: string;
+    ecosystem: string;
+    packagesScanned: number;
+    findings: Finding[];
+    /** Packages we could not fully verify (offline, unsupported source, etc.). */
+    unverified: string[];
+    generatedAt: string;
+    /** Whether the scan read a resolved lockfile tree or only the manifest. */
+    basis?: "lockfile" | "manifest";
+    /** Non-fatal notices, e.g. an unsupported lockfile that forced a manifest fallback. */
+    warnings?: string[];
+}
+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.
+ */
+declare function runDetectors(facts: PackageFacts[], detectors: Detector[], context: {
+    target: string;
+    ecosystem: string;
+    unverified: string[];
+    generatedAt: string;
+}): 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;
+
+/** Bumped when the JSON shape changes in a way consumers must adapt to. */
+declare const JSON_SCHEMA_VERSION = 1;
+/** Renders a report as stable, machine-readable JSON for CI and tooling. */
+declare function renderJson(report: Report, toolVersion: string): string;
+
+/**
+ * Renders a report as SARIF 2.1.0 for GitHub code scanning. Findings become
+ * results anchored to the manifest or lockfile; every built-in detector is
+ * advertised as a rule so the tool's coverage is discoverable.
+ */
+declare function renderSarif(report: Report, toolVersion: string, detectors?: Detector[]): 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
+ * severity is 1, so CI can gate on high-severity results alone.
+ */
+declare function resolveExitCode(report: Report, failOn: Severity | undefined): number;
+
+/**
+ * Classifies a version specifier into how we can verify it. A registry range
+ * is checkable against the registry; git/file/link/alias/workspace specifiers
+ * are not resolvable the same way and must be reported honestly, not assumed
+ * safe.
+ */
+declare function classifySource(spec: string): DependencySource;
+/**
+ * Reads declared dependencies from a package.json. This is manifest-level only
+ * (what was asked for), not the resolved lockfile graph; the lockfile collector
+ * (Phase 1) supplies resolved versions and the full transitive tree.
+ */
+declare function readManifestFacts(dir: string): Promise<PackageFacts[]>;
+
+/** Names of non-npm lockfiles present in `dir`, so the caller can warn instead of silently skipping. */
+declare function detectOtherLockfiles(dir: string): Promise<string[]>;
+type LockfileOutcome = {
+    status: "ok";
+    facts: PackageFacts[];
+    lockfileVersion: number;
+} | {
+    status: "unsupported";
+    reason: string;
+} | {
+    status: "absent";
+};
+/** 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.
+ */
+declare function readLockfile(dir: string): Promise<LockfileOutcome>;
+
+/**
+ * npm registry client. This is a collector: it does IO and returns facts. It
+ * never judges. Every path degrades honestly, a lookup that could not be
+ * completed returns status "unverified", never a value that reads as "safe".
+ */
+/** Parsed, flattened facts from a registry packument. */
+interface Packument {
+    name: string;
+    firstPublishAt?: string;
+    latestPublishAt?: string;
+    latestVersion?: string;
+    versionCount: number;
+    /** Whether the resolved version is still published, when a version is asked. */
+    requestedVersionPublished?: boolean;
+    hasInstallScript: boolean;
+    repositoryUrl?: string;
+}
+type RegistryLookup = {
+    status: "found";
+    packument: Packument;
+} | {
+    status: "not-found";
+} | {
+    status: "unverified";
+    reason: string;
+};
+interface RegistryClientOptions {
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    registryUrl?: string;
+    offline?: boolean;
+    timeoutMs?: number;
+}
+interface RegistryClient {
+    getPackument(name: string, version?: string): Promise<RegistryLookup>;
+}
+/** Scoped names keep the leading @ but the internal slash must be encoded. */
+declare function encodePackageName(name: string): string;
+declare function createRegistryClient(options?: RegistryClientOptions): RegistryClient;
+
+/**
+ * npm downloads API client. A collector: returns the last-week download count
+ * for a package, or `undefined` when the count cannot be established (offline,
+ * error, or an unsupported name such as a scoped package, which the point API
+ * does not serve). `undefined` means "unknown", never "zero" or "safe".
+ */
+interface DownloadsClientOptions {
+    fetchImpl?: typeof fetch;
+    apiUrl?: string;
+    offline?: boolean;
+    timeoutMs?: number;
+}
+interface DownloadsClient {
+    getWeeklyDownloads(name: string): Promise<number | undefined>;
+}
+declare function createDownloadsClient(options?: DownloadsClientOptions): DownloadsClient;
+
+interface EnrichmentResult {
+    facts: PackageFacts[];
+    /** Names whose registry facts could not be established (offline, error). */
+    unverified: string[];
+}
+interface EnrichOptions {
+    concurrency?: number;
+    downloads?: DownloadsClient;
+    /** Injected for a deterministic age computation in tests. */
+    now?: () => Date;
+}
+/**
+ * Enriches manifest facts with registry and downloads facts. A collector: it
+ * performs the IO and folds the results into `PackageFacts` for the pure
+ * detectors to judge. Only registry-sourced dependencies are looked up; git,
+ * file, link, alias, and workspace specifiers have no registry record and are
+ * left as they are.
+ */
+declare function enrichWithRegistry(input: PackageFacts[], client: RegistryClient, options?: EnrichOptions): Promise<EnrichmentResult>;
+
+interface PackageSpec {
+    name: string;
+    version?: string;
+}
+/**
+ * Parses a `check` argument like `express`, `express@4.18.2`, `@scope/pkg`, or
+ * `@scope/pkg@1.0.0`. The leading @ of a scope is not a version separator, so
+ * the split looks for an @ after the first character only.
+ */
+declare function parsePackageSpec(input: string): PackageSpec;
+
+interface ScanOptions {
+    offline?: boolean;
+    /** Injected in tests so the suite never touches the network. */
+    client?: RegistryClient;
+    downloads?: DownloadsClient;
+    detectors?: Detector[];
+    /** Injected for a deterministic `generatedAt` and age in tests. */
+    now?: () => Date;
+}
+/**
+ * Scans a project. Prefers the resolved package-lock.json tree (v2/v3); falls
+ * back to the manifest's declared dependencies when the lockfile is absent or
+ * an unsupported shape, recording a warning so the fallback is never silent.
+ */
+declare function scanProject(dir: 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>;
+
+/** Public library API. The CLI is a thin consumer of these exports. */
+
+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 };

package/dist/index.js

@@ -0,0 +1,46 @@
+import {
+  JSON_SCHEMA_VERSION,
+  SEVERITY_ORDER,
+  VERSION,
+  builtinDetectors,
+  checkPackage,
+  classifySource,
+  createDownloadsClient,
+  createRegistryClient,
+  detectOtherLockfiles,
+  encodePackageName,
+  enrichWithRegistry,
+  nameFromLockPath,
+  parsePackageSpec,
+  readLockfile,
+  readManifestFacts,
+  renderJson,
+  renderSarif,
+  renderTerminal,
+  resolveExitCode,
+  runDetectors,
+  scanProject
+} from "./chunk-XXICU3EZ.js";
+export {
+  JSON_SCHEMA_VERSION,
+  SEVERITY_ORDER,
+  VERSION,
+  builtinDetectors,
+  checkPackage,
+  classifySource,
+  createDownloadsClient,
+  createRegistryClient,
+  detectOtherLockfiles,
+  encodePackageName,
+  enrichWithRegistry,
+  nameFromLockPath,
+  parsePackageSpec,
+  readLockfile,
+  readManifestFacts,
+  renderJson,
+  renderSarif,
+  renderTerminal,
+  resolveExitCode,
+  runDetectors,
+  scanProject
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "vetguard",
+  "version": "0.0.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",
+    "security",
+    "supply-chain",
+    "slopsquatting",
+    "typosquatting",
+    "vulnerability",
+    "sca",
+    "cli"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/tallyguard/vetguard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tallyguard/vetguard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tallyguard/vetguard/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "vetguard": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "scan": "tsx src/cli.ts scan",
+    "check": "npm run build && node dist/cli.js",
+    "refresh:popular": "node scripts/refresh-popular.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/node": "^22.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "eslint": "^9.17.0",
+    "globals": "^17.7.0",
+    "prettier": "^3.4.2",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}