@shubhambattoo/look-see 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 shubhambattoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# Look-See
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Look-See is a Node.js CLI that scans supported dependency lockfiles, identifies packages with PURLs, checks exact package versions against OSV, and enriches matching CVEs with NVD data. It writes JSON and HTML reports and opens the HTML report by default.
+
+> Early MVP: npm lockfiles and Go `go.mod` requirements are supported. Automated dependency fixes are not implemented yet.
+
+## Usage
+
+Requires Node.js 22 or newer. Use the CLI with `npx` without a global install, or install it globally to use the `look-see` command directly.
+
+### Run with npx
+
+```bash
+npx @shubhambattoo/look-see /path/to/project
+```
+
+### Install globally
+
+```bash
+npm install -g @shubhambattoo/look-see
+look-see /path/to/project
+```
+
+To run from this checkout:
+
+```bash
+npm install
+npm start -- /path/to/project --no-open
+```
+
+The default output directory is `<project>/.look-see/`:
+
+- `look-see-output.html`
+- `look-see-output.json`
+
+The CLI scans `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, and `go.mod` files below the project directory. It skips common generated/dependency directories such as `node_modules`, `vendor`, and `.git`.
+
+## Options
+
+```text
+look-see [project-directory]
+  --out <directory>     Report output directory
+  --format html,json    Select one or both report formats
+  --no-open             Do not open the HTML report
+  --no-nvd              Skip NVD CVE enrichment
+  --fail-on <severity>  Exit 1 if a finding meets the severity threshold
+  --help                Show help
+```
+
+Set `NVD_API_KEY` for higher NVD API request limits. Advisory responses are cached locally; use `LOOK_SEE_CACHE_DIR` to choose a cache location.
+
+## Matching and coverage
+
+Each locked dependency is represented by a Package URL. OSV is queried using the package identity and resolved version, which provides ecosystem-aware matching. Matching CVE IDs are then looked up in NVD for CVSS and reference enrichment. NVD is not used as a fuzzy package-name search: its CPE records do not reliably map to every package-manager coordinate.
+
+The npm lockfile parsers report resolved versions, including transitive packages. Go scanning currently reads requirements from `go.mod`; it does not run `go list`, resolve the complete selected/transitive module graph, or apply `replace` directives. Unsupported manifests are not scanned. Review the report's coverage and errors before interpreting an empty result as clean.
+
+NVD may rate-limit unauthenticated lookups. Enrichment errors are included in both reports; OSV matching results remain available if NVD is unavailable. The CLI does not modify project files.
+
+## Development
+
+```bash
+npm install
+npm test
+```

package/bin/look-see.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+process.exitCode = await run();

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@shubhambattoo/look-see",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Look-See scans locked project dependencies for known vulnerabilities",
+  "author": "shubhambattoo",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "look-see": "./bin/look-see.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node ./bin/look-see.js",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@yarnpkg/lockfile": "^1.1.0",
+    "chalk": "^6.0.1",
+    "yaml": "^2.8.1"
+  },
+  "license": "MIT",
+  "keywords": [
+    "dependency-audit",
+    "vulnerability-scanner",
+    "security",
+    "osv",
+    "nvd"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/advisories/nvd.js

@@ -0,0 +1,69 @@
+import { getCached, setCached } from '../cache.js';
+
+const NVD_URL = 'https://services.nvd.nist.gov/rest/json/cves/2.0';
+const CACHE_TTL = 7 * 24 * 60 * 60 * 1000;
+const NVD_API_KEY = process.env.NVD_API_KEY;
+const MIN_INTERVAL_MS = NVD_API_KEY ? 700 : 6_100;
+
+function cveIdsFrom(vulnerabilities) {
+  const ids = new Set();
+  for (const vulnerability of vulnerabilities) {
+    for (const alias of vulnerability.aliases ?? []) {
+      if (/^CVE-\d{4}-\d+$/i.test(alias)) ids.add(alias.toUpperCase());
+    }
+    if (/^CVE-\d{4}-\d+$/i.test(vulnerability.id ?? '')) ids.add(vulnerability.id.toUpperCase());
+  }
+  return [...ids].sort();
+}
+
+async function fetchCve(cveId) {
+  const url = new URL(NVD_URL);
+  url.searchParams.set('cveId', cveId);
+  const headers = { accept: 'application/json' };
+  if (NVD_API_KEY) headers.apiKey = NVD_API_KEY;
+  const response = await fetch(url, { headers, signal: AbortSignal.timeout(30_000) });
+  if (!response.ok) throw new Error(`NVD returned HTTP ${response.status}`);
+  const body = await response.json();
+  return body.vulnerabilities?.[0]?.cve ?? null;
+}
+
+export async function queryNvd(vulnerabilities, { onProgress } = {}) {
+  const ids = cveIdsFrom(vulnerabilities);
+  const byCve = new Map();
+  const errors = [];
+  let lastRequestAt = 0;
+  let completed = 0;
+  onProgress?.({ stage: 'nvd', completed, total: ids.length });
+  for (const cveId of ids) {
+    const cacheKey = `nvd:${cveId}`;
+    const cached = await getCached(cacheKey, CACHE_TTL);
+    if (cached !== null) {
+      byCve.set(cveId, cached && Object.hasOwn(cached, 'cve') ? cached.cve : cached);
+      completed += 1;
+      onProgress?.({ stage: 'nvd', completed, total: ids.length });
+      continue;
+    }
+    const waitMs = Math.max(0, MIN_INTERVAL_MS - (Date.now() - lastRequestAt));
+    if (waitMs) await new Promise((resolve) => setTimeout(resolve, waitMs));
+    try {
+      const cve = await fetchCve(cveId);
+      lastRequestAt = Date.now();
+      byCve.set(cveId, cve);
+      await setCached(cacheKey, { cve });
+      completed += 1;
+      onProgress?.({ stage: 'nvd', completed, total: ids.length });
+    } catch (error) {
+      lastRequestAt = Date.now();
+      errors.push({ source: 'NVD', cveId, message: error.message });
+      completed += 1;
+      onProgress?.({ stage: 'nvd', completed, total: ids.length });
+      if (/HTTP 403|HTTP 429/.test(error.message)) {
+        errors.push({ source: 'NVD', message: 'Stopped further NVD lookups after a rate-limit response.' });
+        break;
+      }
+    }
+  }
+  return { byCve, errors };
+}
+
+export const nvdHelpers = { cveIdsFrom };

package/src/advisories/osv.js

@@ -0,0 +1,111 @@
+import { getCached, setCached } from '../cache.js';
+import { packagePurlName } from '../purl.js';
+
+const OSV_URL = 'https://api.osv.dev/v1/querybatch';
+const OSV_VULN_URL = 'https://api.osv.dev/v1/vulns/';
+const CACHE_TTL = 24 * 60 * 60 * 1000;
+
+async function fetchBatch(queries) {
+  const response = await fetch(OSV_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify({ queries }),
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) throw new Error(`OSV returned HTTP ${response.status}`);
+  return response.json();
+}
+
+async function fetchAdvisory(id) {
+  const response = await fetch(`${OSV_VULN_URL}${encodeURIComponent(id)}`, {
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!response.ok) throw new Error(`OSV advisory lookup returned HTTP ${response.status}`);
+  return response.json();
+}
+
+async function hydrateAdvisories(byPackage, errors, onProgress) {
+  const unique = new Map();
+  for (const vulnerabilities of byPackage.values()) {
+    for (const vulnerability of vulnerabilities) {
+      if (vulnerability?.id) unique.set(vulnerability.id, vulnerability);
+    }
+  }
+
+  const details = new Map();
+  const missing = [];
+  for (const [id, fallback] of unique) {
+    const cached = await getCached(`osv-vuln:${id}`, CACHE_TTL);
+    if (cached) details.set(id, cached);
+    else missing.push([id, fallback]);
+  }
+
+  let completed = unique.size - missing.length;
+  onProgress?.({ stage: 'advisories', completed, total: unique.size });
+  for (let offset = 0; offset < missing.length; offset += 10) {
+    const chunk = missing.slice(offset, offset + 10);
+    const results = await Promise.all(chunk.map(async ([id, fallback]) => {
+      try {
+        const advisory = await fetchAdvisory(id);
+        await setCached(`osv-vuln:${id}`, advisory);
+        return [id, advisory];
+      } catch (error) {
+        errors.push({ source: 'OSV', advisoryId: id, message: error.message });
+        return [id, fallback];
+      }
+    }));
+    for (const [id, advisory] of results) details.set(id, advisory);
+    completed += chunk.length;
+    onProgress?.({ stage: 'advisories', completed, total: unique.size });
+  }
+
+  for (const [purl, vulnerabilities] of byPackage) {
+    byPackage.set(purl, vulnerabilities.map((vulnerability) => details.get(vulnerability.id) ?? vulnerability));
+  }
+}
+
+export async function queryOsv(packages, { onProgress } = {}) {
+  const byPackage = new Map();
+  const errors = [];
+  const missing = [];
+  for (const item of packages) {
+    const key = `osv:${item.purl}`;
+    const cached = await getCached(key, CACHE_TTL);
+    if (cached) byPackage.set(item.purl, cached);
+    else missing.push(item);
+  }
+
+  let packageCompleted = packages.length - missing.length;
+  onProgress?.({ stage: 'packages', completed: packageCompleted, total: packages.length });
+  for (let offset = 0; offset < missing.length; offset += 100) {
+    const batch = missing.slice(offset, offset + 100);
+    const queries = batch.map((item) => ({
+      version: item.version,
+      package: { purl: packagePurlName(item.ecosystem, item.name) },
+    }));
+    try {
+      const result = await fetchBatch(queries);
+      if (!Array.isArray(result.results) || result.results.length !== batch.length) {
+        throw new Error('OSV returned an unexpected batch response');
+      }
+      for (let index = 0; index < batch.length; index += 1) {
+        const item = batch[index];
+        const response = result.results[index];
+        if (response?.error) {
+          errors.push({ source: 'OSV', package: item.purl, message: response.error });
+          continue;
+        }
+        const vulnerabilities = response?.vulns ?? [];
+        byPackage.set(item.purl, vulnerabilities);
+        await setCached(`osv:${item.purl}`, vulnerabilities);
+      }
+    } catch (error) {
+      errors.push({ source: 'OSV', message: error.message });
+    }
+    packageCompleted += batch.length;
+    onProgress?.({ stage: 'packages', completed: packageCompleted, total: packages.length });
+  }
+  await hydrateAdvisories(byPackage, errors, onProgress);
+  return { byPackage, errors };
+}

package/src/analyze.js

@@ -0,0 +1,120 @@
+function highestNvdMetric(cve) {
+  const metrics = cve?.metrics ?? {};
+  const candidates = Object.values(metrics).flat().filter((metric) => metric?.cvssData?.baseScore != null);
+  candidates.sort((a, b) => b.cvssData.baseScore - a.cvssData.baseScore);
+  if (!candidates.length) return null;
+  const metric = candidates[0];
+  return {
+    score: metric.cvssData.baseScore,
+    severity: metric.cvssData.baseSeverity ?? metric.baseSeverity ?? null,
+    version: metric.cvssData.version ?? null,
+    vector: metric.cvssData.vectorString ?? null,
+  };
+}
+
+function englishDescription(entries = []) {
+  return entries.find((entry) => entry.lang === 'en')?.value ?? entries[0]?.value ?? null;
+}
+
+function nvdData(cve) {
+  if (!cve) return null;
+  return {
+    id: cve.id,
+    published: cve.published ?? null,
+    lastModified: cve.lastModified ?? null,
+    description: englishDescription(cve.descriptions),
+    severity: highestNvdMetric(cve),
+    references: (cve.references ?? []).map((reference) => reference.url).filter(Boolean),
+  };
+}
+
+function fixedVersions(vulnerability) {
+  const versions = new Set();
+  for (const affected of vulnerability.affected ?? []) {
+    for (const range of affected.ranges ?? []) {
+      for (const event of range.events ?? []) {
+        if (event.fixed) versions.add(event.fixed);
+      }
+    }
+    for (const version of affected.ecosystem_specific?.fixed ?? []) versions.add(version);
+  }
+  return [...versions];
+}
+
+function advisoryReferences(vulnerability, nvd) {
+  return [...new Set([
+    ...(vulnerability.references ?? []).map((reference) => reference.url),
+    ...(nvd?.references ?? []),
+  ].filter((url) => typeof url === 'string' && /^https?:\/\//i.test(url)))];
+}
+
+function severityOf(vulnerability, nvd) {
+  const nvdSeverity = nvd?.severity;
+  if (nvdSeverity?.severity) return { ...nvdSeverity, source: 'NVD' };
+  const databaseSeverity = vulnerability.database_specific?.severity;
+  if (databaseSeverity) {
+    const raw = String(databaseSeverity).toUpperCase();
+    const severity = ({ MODERATE: 'MEDIUM', IMPORTANT: 'HIGH', SEVERE: 'HIGH' })[raw] ?? raw;
+    return { severity, score: null, source: 'OSV' };
+  }
+  return { severity: 'UNKNOWN', score: null, source: null };
+}
+
+function guidance(versions) {
+  if (!versions.length) {
+    return 'Check the linked upstream advisory for a patched release. No fixed version was provided by the advisory data.';
+  }
+  return `Upgrade to ${versions.join(' or ')} (or a later compatible release), then rerun the scan. Review release notes for breaking changes.`;
+}
+
+export function buildFindings(packages, osvByPackage, nvdByCve) {
+  return packages.map((item) => {
+    const vulnerabilities = osvByPackage.get(item.purl) ?? [];
+    const findings = vulnerabilities.map((vulnerability) => {
+      const cveId = [vulnerability.id, ...(vulnerability.aliases ?? [])]
+        .find((id) => /^CVE-\d{4}-\d+$/i.test(id ?? ''))?.toUpperCase() ?? null;
+      const nvd = cveId ? nvdData(nvdByCve.get(cveId)) : null;
+      const fixes = fixedVersions(vulnerability);
+      return {
+        id: vulnerability.id,
+        aliases: vulnerability.aliases ?? [],
+        cveId,
+        match: { type: 'package-version', confidence: 'high', source: 'OSV' },
+        summary: vulnerability.summary ?? nvd?.description ?? vulnerability.id,
+        details: vulnerability.details ?? null,
+        severity: severityOf(vulnerability, nvd),
+        affected: (vulnerability.affected ?? []).map((affected) => ({
+          ranges: (affected.ranges ?? []).map((range) => ({
+            type: range.type,
+            events: range.events ?? [],
+          })),
+          versions: affected.versions ?? [],
+        })),
+        fixedVersions: fixes,
+        remediation: guidance(fixes),
+        references: advisoryReferences(vulnerability, nvd),
+        sources: [...new Set(['OSV', ...(nvd ? ['NVD'] : [])])],
+        nvd,
+      };
+    });
+    return { ...item, vulnerabilities: findings };
+  });
+}
+
+export function summarize(packages) {
+  const findings = packages.flatMap((item) => item.vulnerabilities);
+  const severities = ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'UNKNOWN'];
+  const counts = Object.fromEntries(severities.map((severity) => [severity, 0]));
+  for (const finding of findings) {
+    const severity = String(finding.severity?.severity ?? 'UNKNOWN').toUpperCase();
+    counts[Object.hasOwn(counts, severity) ? severity : 'UNKNOWN'] += 1;
+  }
+  return {
+    dependencies: packages.length,
+    vulnerableDependencies: packages.filter((item) => item.vulnerabilities.length).length,
+    vulnerabilities: findings.length,
+    severityCounts: counts,
+  };
+}
+
+export const analyzeHelpers = { fixedVersions, highestNvdMetric };

package/src/cache.js

@@ -0,0 +1,38 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+function cacheDirectory() {
+  if (process.env.LOOK_SEE_CACHE_DIR) return process.env.LOOK_SEE_CACHE_DIR;
+  if (process.env.XDG_CACHE_HOME) return path.join(process.env.XDG_CACHE_HOME, 'look-see');
+  if (process.platform === 'win32' && process.env.LOCALAPPDATA) {
+    return path.join(process.env.LOCALAPPDATA, 'look-see', 'cache');
+  }
+  return path.join(os.homedir(), '.cache', 'look-see');
+}
+
+function cachePath(key) {
+  const digest = crypto.createHash('sha256').update(key).digest('hex');
+  return path.join(cacheDirectory(), `${digest}.json`);
+}
+
+export async function getCached(key, maxAgeMs) {
+  try {
+    const value = JSON.parse(await fs.readFile(cachePath(key), 'utf8'));
+    if (Date.now() - value.cachedAt > maxAgeMs) return null;
+    return value.data;
+  } catch {
+    return null;
+  }
+}
+
+export async function setCached(key, data) {
+  try {
+    const file = cachePath(key);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify({ cachedAt: Date.now(), data }), 'utf8');
+  } catch {
+    // Cache failures should not interrupt a scan.
+  }
+}

package/src/cli.js

@@ -0,0 +1,215 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { discoverDependencies } from './discovery/index.js';
+import { queryOsv } from './advisories/osv.js';
+import { nvdHelpers, queryNvd } from './advisories/nvd.js';
+import { buildFindings, summarize } from './analyze.js';
+import { writeReports } from './report.js';
+import { createProgress } from './progress.js';
+
+const HELP = `Look-See - scan locked dependencies for known vulnerabilities
+
+Usage: look-see [project-directory] [options]
+
+Options:
+  --out <directory>     Report output directory (default: <project>/.look-see)
+  --format <formats>    html,json (default: html,json)
+  --no-open             Do not open the HTML report automatically
+  --no-nvd              Skip NVD CVE enrichment
+  --fail-on <severity>  Exit with code 1 for this severity or higher
+  -h, --help            Show this help
+  -v, --version         Show the version
+
+Environment:
+  NVD_API_KEY           Optional NVD API key for higher request limits
+  LOOK_SEE_CACHE_DIR    Override the local advisory cache directory`;
+
+const VERSION = '0.1.0';
+const SEVERITY_RANK = { UNKNOWN: 0, LOW: 1, MEDIUM: 2, HIGH: 3, CRITICAL: 4 };
+
+function parseArgs(args) {
+  const options = {
+    root: process.cwd(), out: null, formats: ['html', 'json'], open: true,
+    nvd: true, failOn: null, help: false, version: false,
+  };
+  let rootWasSet = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '-h' || arg === '--help') options.help = true;
+    else if (arg === '-v' || arg === '--version') options.version = true;
+    else if (arg === '--no-open') options.open = false;
+    else if (arg === '--no-nvd') options.nvd = false;
+    else if (arg === '--out' || arg === '--format' || arg === '--fail-on') {
+      const value = args[++index];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+      if (arg === '--out') options.out = value;
+      if (arg === '--format') {
+        options.formats = value.split(',').map((format) => format.trim().toLowerCase());
+        if (!options.formats.length || options.formats.some((format) => !['html', 'json'].includes(format))) {
+          throw new Error('--format must contain html, json, or both (comma-separated)');
+        }
+        options.formats = [...new Set(options.formats)];
+      }
+      if (arg === '--fail-on') {
+        const severity = value.toUpperCase();
+        if (!(severity in SEVERITY_RANK) || severity === 'UNKNOWN') {
+          throw new Error('--fail-on must be low, medium, high, or critical');
+        }
+        options.failOn = severity;
+      }
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else if (!rootWasSet) {
+      options.root = arg;
+      rootWasSet = true;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function openInBrowser(file) {
+  const absolute = path.resolve(file);
+  const target = process.platform === 'win32' ? absolute : pathToFileURL(absolute).href;
+  const command = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'cmd'
+      : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', target] : [target];
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    child.once('error', () => resolve(false));
+    child.once('spawn', () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+}
+
+function allOsvVulnerabilities(byPackage) {
+  return [...byPackage.values()].flat();
+}
+
+export async function run(args = process.argv.slice(2), io = console) {
+  let options;
+  try {
+    options = parseArgs(args);
+  } catch (error) {
+    io.error(`look-see: ${error.message}\nUse --help for usage.`);
+    return 2;
+  }
+  if (options.help) {
+    io.log(HELP);
+    return 0;
+  }
+  if (options.version) {
+    io.log(VERSION);
+    return 0;
+  }
+
+  const root = path.resolve(options.root);
+  let stats;
+  try {
+    stats = await fs.stat(root);
+    if (!stats.isDirectory()) throw new Error('Project path must be a directory');
+  } catch (error) {
+    io.error(`look-see: cannot read project directory ${root}: ${error.message}`);
+    return 2;
+  }
+
+  const outputDirectory = options.out
+    ? path.resolve(options.out)
+    : path.join(root, '.look-see');
+  const progress = createProgress(io);
+  progress.banner();
+  progress.start(`Scanning ${root}`);
+  let discovery;
+  try {
+    discovery = await discoverDependencies(root);
+    progress.complete(`Discovered ${discovery.packages.length} locked dependency version(s) across ${discovery.lockfiles.length} file(s).`);
+  } catch (error) {
+    progress.warn(`Dependency discovery failed: ${error.message}`);
+    return 2;
+  }
+
+  progress.start(`Checking ${discovery.packages.length} dependency version(s) against OSV`);
+  const osv = await queryOsv(discovery.packages, {
+    onProgress: ({ stage, completed, total }) => {
+      if (stage === 'packages' && total > 0) progress.update(`OSV package checks: ${completed}/${total}`);
+      if (stage === 'advisories' && total > 0) progress.update(`Loading advisory details: ${completed}/${total}`);
+    },
+  });
+  const osvVulnerabilities = allOsvVulnerabilities(osv.byPackage);
+  progress.complete(`OSV checks complete: ${osvVulnerabilities.length} advisory finding(s).`);
+
+  const cveIds = nvdHelpers.cveIdsFrom(osvVulnerabilities);
+  let nvd = { byCve: new Map(), errors: [] };
+  if (!options.nvd) {
+    progress.skip('NVD enrichment disabled (--no-nvd).');
+  } else if (cveIds.length === 0) {
+    progress.skip('No CVE IDs found for NVD enrichment.');
+  } else {
+    progress.start(`Enriching ${cveIds.length} CVE(s) with NVD data`);
+    nvd = await queryNvd(osvVulnerabilities, {
+      onProgress: ({ completed, total }) => progress.update(`NVD CVE enrichment: ${completed}/${total}`),
+    });
+    const enriched = [...nvd.byCve.values()].filter(Boolean).length;
+    progress.complete(`NVD enrichment complete: ${enriched}/${cveIds.length} CVE record(s) retrieved.`);
+  }
+  const packages = buildFindings(discovery.packages, osv.byPackage, nvd.byCve);
+  const summary = summarize(packages);
+  const errors = [
+    ...discovery.errors.map((error) => ({ source: 'Discovery', ...error })),
+    ...osv.errors,
+    ...nvd.errors,
+  ];
+  if (!discovery.lockfiles.length) {
+    errors.push({ source: 'Discovery', message: 'No supported lockfiles were found; no dependencies were checked.' });
+  }
+  const report = {
+    schemaVersion: '1.0.0',
+    tool: { name: 'look-see', version: VERSION },
+    generatedAt: new Date().toISOString(),
+    project: root,
+    summary,
+    coverage: {
+      lockfiles: discovery.lockfiles,
+      packagesScanned: discovery.packages.length,
+      advisoryMatching: 'OSV package and version matching using PURLs',
+      nvdEnrichment: options.nvd ? 'NVD CVE enrichment for OSV advisories with CVE aliases' : 'disabled by --no-nvd',
+      dependencyResolution: 'npm lockfiles provide resolved dependency versions; Go scans go.mod requirements without resolving the full module graph or applying replace directives.',
+      errors,
+    },
+    packages,
+  };
+
+  progress.start('Writing HTML and JSON reports');
+  let written;
+  try {
+    written = await writeReports(report, outputDirectory, options.formats);
+  } catch (error) {
+    progress.warn(`Could not write reports: ${error.message}`);
+    return 2;
+  }
+  progress.complete('Reports written.');
+  for (const [format, file] of Object.entries(written)) progress.note(`${format.toUpperCase()} report: ${file}`);
+  progress.complete(`Scan complete: ${summary.vulnerabilities} finding(s) in ${summary.vulnerableDependencies} dependency version(s).`);
+  if (errors.length) progress.warn(`${errors.length} scan/data-source issue(s); review coverage.errors in the JSON report.`);
+
+  if (options.open && written.html) {
+    const opened = await openInBrowser(written.html);
+    if (!opened) progress.warn('Could not open a browser automatically. Open the HTML report path above.');
+  }
+
+  if (options.failOn) {
+    const threshold = SEVERITY_RANK[options.failOn];
+    if (packages.some((item) => item.vulnerabilities.some((finding) =>
+      SEVERITY_RANK[String(finding.severity?.severity ?? 'UNKNOWN').toUpperCase()] >= threshold))) return 1;
+  }
+  if (discovery.errors.length || osv.errors.length || !discovery.lockfiles.length) return 2;
+  return 0;
+}
+
+export const cliHelpers = { parseArgs, openInBrowser };

package/src/discovery/go.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { addPackage } from './helpers.js';
+
+function cleanGoVersion(version) {
+  return version?.trim();
+}
+
+export async function scanGoModules(goModPaths) {
+  const packages = new Map();
+  const errors = [];
+  for (const file of goModPaths) {
+    try {
+      const content = await fs.readFile(file, 'utf8');
+      for (const item of parseGoMod(content, file)) {
+        addPackage(packages, item);
+      }
+    } catch (error) {
+      errors.push({ file, message: error.message });
+    }
+  }
+  return { packages: [...packages.values()], errors };
+}
+
+export function parseGoMod(content, file = 'go.mod') {
+  const packages = new Map();
+  let inRequire = false;
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.replace(/\/\/.*$/, '').trim();
+    if (!line) continue;
+    if (/^require\s+\($/.test(line)) {
+      inRequire = true;
+      continue;
+    }
+    if (inRequire && line === ')') {
+      inRequire = false;
+      continue;
+    }
+    if (line.startsWith('require ')) {
+      const fields = line.slice('require '.length).trim().split(/\s+/);
+      if (fields.length >= 2) {
+        addPackage(packages, {
+          ecosystem: 'Go', name: fields[0], version: cleanGoVersion(fields[1]),
+          direct: !rawLine.includes('// indirect'), file,
+        });
+      }
+      continue;
+    }
+    if (inRequire) {
+      const fields = line.split(/\s+/);
+      if (fields.length >= 2) {
+        addPackage(packages, {
+          ecosystem: 'Go', name: fields[0], version: cleanGoVersion(fields[1]),
+          direct: !rawLine.includes('// indirect'), file,
+        });
+      }
+    }
+  }
+  return [...packages.values()];
+}
+
+export const goParser = { cleanGoVersion };

package/src/discovery/helpers.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+
+export function dependencyNames(manifest) {
+  return new Set([
+    ...Object.keys(manifest.dependencies ?? {}),
+    ...Object.keys(manifest.devDependencies ?? {}),
+    ...Object.keys(manifest.optionalDependencies ?? {}),
+    ...Object.keys(manifest.peerDependencies ?? {}),
+  ]);
+}
+
+export function packageNameFromNodeModulesPath(packagePath) {
+  const marker = 'node_modules/';
+  const index = packagePath.lastIndexOf(marker);
+  if (index < 0) return null;
+  const remainder = packagePath.slice(index + marker.length).split('/');
+  if (!remainder[0]) return null;
+  return remainder[0].startsWith('@')
+    ? (remainder[1] ? `${remainder[0]}/${remainder[1]}` : null)
+    : remainder[0];
+}
+
+export function addPackage(packages, { ecosystem, name, version, direct = false, file }) {
+  if (!name || !version || typeof name !== 'string' || typeof version !== 'string') return;
+  const key = `${ecosystem}\0${name}\0${version}`;
+  const current = packages.get(key) ?? {
+    ecosystem,
+    name,
+    version,
+    direct: false,
+    files: [],
+  };
+  current.direct ||= direct;
+  if (file && !current.files.includes(file)) current.files.push(file);
+  packages.set(key, current);
+}
+
+export async function findFiles(root, wantedNames) {
+  const found = [];
+  const ignored = new Set([
+    '.git', '.hg', '.svn', 'node_modules', 'vendor', 'dist', 'build',
+    '.next', '.nuxt', 'coverage', '.look-see',
+  ]);
+
+  async function visit(directory) {
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const fullPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!ignored.has(entry.name)) await visit(fullPath);
+      } else if (entry.isFile() && wantedNames.has(entry.name)) {
+        found.push(fullPath);
+      }
+    }
+  }
+
+  await visit(root);
+  return found.sort();
+}

package/src/discovery/index.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { findFiles } from './helpers.js';
+import { scanNpmLocks } from './npm.js';
+import { scanGoModules } from './go.js';
+import { createPurl } from '../purl.js';
+
+export async function discoverDependencies(root) {
+  const [npmFiles, goFiles] = await Promise.all([
+    findFiles(root, new Set(['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'])),
+    findFiles(root, new Set(['go.mod'])),
+  ]);
+  const [npmResult, goResult] = await Promise.all([
+    scanNpmLocks(npmFiles), scanGoModules(goFiles),
+  ]);
+  const packages = [...npmResult.packages, ...goResult.packages].map((item) => ({
+    ...item,
+    files: item.files.map((file) => path.relative(root, file) || '.'),
+    purl: createPurl(item.ecosystem, item.name, item.version),
+  }));
+  return {
+    packages,
+    lockfiles: [...npmFiles, ...goFiles].map((file) => path.relative(root, file)),
+    errors: [...npmResult.errors, ...goResult.errors].map((error) => ({
+      ...error, file: path.relative(root, error.file),
+    })),
+  };
+}

package/src/discovery/npm.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import lockfile from '@yarnpkg/lockfile';
+import YAML from 'yaml';
+import { addPackage, dependencyNames, packageNameFromNodeModulesPath, readJson } from './helpers.js';
+
+function walkNpmV1(dependencies, packages, file, directNames, isDirect = false) {
+  for (const [name, dependency] of Object.entries(dependencies ?? {})) {
+    if (dependency?.version) {
+      addPackage(packages, {
+        ecosystem: 'npm', name, version: dependency.version,
+        direct: isDirect && directNames.has(name), file,
+      });
+    }
+    walkNpmV1(dependency?.dependencies, packages, file, directNames, false);
+  }
+}
+
+function parseNpmPackageLock(lock, file) {
+  const packages = new Map();
+  const directNames = dependencyNames(lock.packages?.[''] ?? lock);
+  if (lock.packages && typeof lock.packages === 'object') {
+    for (const [packagePath, metadata] of Object.entries(lock.packages)) {
+      if (!packagePath || !metadata || metadata.link || !metadata.version) continue;
+      const name = metadata.name ?? packageNameFromNodeModulesPath(packagePath);
+      if (!name) continue;
+      addPackage(packages, {
+        ecosystem: 'npm', name, version: String(metadata.version),
+        direct: directNames.has(name) && !packagePath.slice(1).includes('node_modules/'),
+        file,
+      });
+    }
+  } else {
+    walkNpmV1(lock.dependencies, packages, file, directNames, true);
+  }
+  return [...packages.values()];
+}
+
+function nameFromYarnDescriptor(descriptor) {
+  const value = descriptor.trim().replace(/^['"]|['"]$/g, '');
+  const at = value.lastIndexOf('@');
+  if (at <= 0) return null;
+  return value.slice(0, at);
+}
+
+function parseYarnLock(content, file, directNames) {
+  const packages = new Map();
+  if (content.startsWith('__metadata:')) {
+    const parsed = YAML.parse(content);
+    for (const [descriptor, metadata] of Object.entries(parsed ?? {})) {
+      if (descriptor === '__metadata' || !metadata?.version) continue;
+      const name = nameFromYarnDescriptor(metadata.resolution ?? descriptor.split(',')[0]);
+      if (!name) continue;
+      addPackage(packages, {
+        ecosystem: 'npm', name, version: String(metadata.version),
+        direct: directNames.has(name), file,
+      });
+    }
+  } else {
+    const parsed = lockfile.parse(content);
+    if (parsed.type !== 'success') throw new Error(`Could not parse Yarn lockfile: ${parsed.type}`);
+    for (const [descriptor, metadata] of Object.entries(parsed.object)) {
+      if (!metadata?.version) continue;
+      const name = nameFromYarnDescriptor(descriptor.split(',')[0]);
+      if (!name) continue;
+      addPackage(packages, {
+        ecosystem: 'npm', name, version: String(metadata.version),
+        direct: directNames.has(name), file,
+      });
+    }
+  }
+  return [...packages.values()];
+}
+
+function parsePnpmPackageKey(key, metadata) {
+  if (metadata?.name && metadata?.version) return { name: metadata.name, version: String(metadata.version) };
+  let value = key.replace(/^\//, '');
+  value = value.replace(/\([^)]*\)$/g, '');
+  const at = value.lastIndexOf('@');
+  if (at > value.indexOf('/')) {
+    const name = value.slice(0, at);
+    const version = value.slice(at + 1).split('_')[0];
+    if (name && version) return { name, version };
+  }
+  const slash = value.lastIndexOf('/');
+  if (slash > 0) {
+    const name = value.slice(0, slash);
+    const version = value.slice(slash + 1).split('_')[0];
+    if (name && version && /^\d|^v\d/.test(version)) return { name, version };
+  }
+  return null;
+}
+
+function parsePnpmLock(content, file, directNames) {
+  const parsed = YAML.parse(content) ?? {};
+  const packages = new Map();
+  for (const [key, metadata] of Object.entries(parsed.packages ?? {})) {
+    const item = parsePnpmPackageKey(key, metadata);
+    if (!item) continue;
+    addPackage(packages, {
+      ecosystem: 'npm', ...item, direct: directNames.has(item.name), file,
+    });
+  }
+  return [...packages.values()];
+}
+
+async function readDirectNames(lockPath) {
+  const manifestPath = path.join(path.dirname(lockPath), 'package.json');
+  try {
+    return dependencyNames(await readJson(manifestPath));
+  } catch {
+    return new Set();
+  }
+}
+
+export async function scanNpmLocks(lockPaths) {
+  const combined = new Map();
+  const errors = [];
+  for (const file of lockPaths) {
+    try {
+      let found;
+      if (path.basename(file) === 'package-lock.json') {
+        found = parseNpmPackageLock(await readJson(file), file);
+      } else {
+        const content = await fs.readFile(file, 'utf8');
+        const directNames = await readDirectNames(file);
+        found = path.basename(file) === 'pnpm-lock.yaml'
+          ? parsePnpmLock(content, file, directNames)
+          : parseYarnLock(content, file, directNames);
+      }
+      for (const item of found) {
+        const key = `${item.ecosystem}\0${item.name}\0${item.version}`;
+        const current = combined.get(key) ?? { ...item, files: [] };
+        current.direct ||= item.direct;
+        if (!current.files.includes(file)) current.files.push(file);
+        combined.set(key, current);
+      }
+    } catch (error) {
+      errors.push({ file, message: error.message });
+    }
+  }
+  return { packages: [...combined.values()], errors };
+}
+
+export const npmParsers = { parseNpmPackageLock, parsePnpmLock, parseYarnLock, parsePnpmPackageKey };

package/src/progress.js

@@ -0,0 +1,82 @@
+import chalk from 'chalk';
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const BANNER = String.raw`
+ ___        ______      ______    __   ___       ________  _______   _______  
+|"  |      /    " \    /    " \  |/"| /  ")     /"       )/"     "| /"     "| 
+||  |     // ____  \  // ____  \ (: |/   /     (:   \___/(: ______)(: ______) 
+|:  |    /  /    ) :)/  /    ) :)|    __/       \___  \   \/    |   \/    |   
+ \  |___(: (____/ //(: (____/ // (// _  \        __/  \\  // ___)_  // ___)_  
+( \_|:  \\        /  \        /  |: | \  \      /" \   :)(:      "|(:      "| 
+ \_______)"\_____/    "\_____/   (__|  \__)    (_______/  \_______) \_______)  
+`.trim();
+
+export function createProgress(io = console, { interactive = Boolean(process.stdout.isTTY) } = {}) {
+  let timer = null;
+  let frame = 0;
+  let label = '';
+
+  function clearLine() {
+    process.stdout.write('\r\u001b[2K');
+  }
+
+  function stopSpinner() {
+    if (timer) clearInterval(timer);
+    timer = null;
+    if (interactive) clearLine();
+  }
+
+  function render() {
+    if (!interactive || !label) return;
+    const icon = FRAMES[frame++ % FRAMES.length];
+    process.stdout.write(`\r\u001b[2K${chalk.cyan(icon)} ${label}`);
+  }
+
+  function start(message) {
+    stopSpinner();
+    label = message;
+    if (interactive) {
+      render();
+      timer = setInterval(render, 90);
+      timer.unref?.();
+    } else {
+      io.log(chalk.cyan(`› ${message}`));
+    }
+  }
+
+  function banner() {
+    io.log(chalk.bold.cyan(BANNER));
+  }
+
+  function update(message) {
+    label = message;
+    if (interactive) render();
+    else io.log(chalk.dim(`  ${message}`));
+  }
+
+  function complete(message) {
+    stopSpinner();
+    label = '';
+    io.log(chalk.green(`✓ ${message}`));
+  }
+
+  function warn(message) {
+    stopSpinner();
+    label = '';
+    io.warn?.(chalk.yellow(`! ${message}`));
+  }
+
+  function skip(message) {
+    stopSpinner();
+    label = '';
+    io.log(chalk.dim(`– ${message}`));
+  }
+
+  function note(message) {
+    io.log(message);
+  }
+
+  return { banner, start, update, complete, warn, skip, note, stop: stopSpinner };
+}
+
+export const progressHelpers = { BANNER };

package/src/purl.js

@@ -0,0 +1,24 @@
+function encodePathSegment(segment) {
+  return encodeURIComponent(segment).replaceAll('%3A', ':');
+}
+
+function escapeGoPath(path) {
+  return path
+    .split('/')
+    .map((part) => [...part].map((char) => {
+      if (char >= 'A' && char <= 'Z') return `!${char.toLowerCase()}`;
+      return char;
+    }).join(''))
+    .join('/');
+}
+
+export function packagePurlName(ecosystem, name) {
+  const type = ecosystem === 'Go' ? 'golang' : ecosystem.toLowerCase();
+  const normalizedName = ecosystem === 'Go' ? escapeGoPath(name) : name;
+  const encodedName = normalizedName.split('/').map(encodePathSegment).join('/');
+  return `pkg:${type}/${encodedName}`;
+}
+
+export function createPurl(ecosystem, name, version) {
+  return `${packagePurlName(ecosystem, name)}@${encodeURIComponent(version)}`;
+}

package/src/report.js

@@ -0,0 +1,116 @@
+import fs from 'node:fs/promises';
+
+function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (character) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  })[character]);
+}
+
+function safeLink(url) {
+  return /^https?:\/\//i.test(url ?? '') ? url : null;
+}
+
+function formatGeneratedAt(value) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleString(undefined, { dateStyle: 'medium', timeStyle: 'short' });
+}
+
+function findingMarkup(item, finding) {
+  const severity = String(finding.severity?.severity ?? 'UNKNOWN').toUpperCase();
+  const score = finding.severity?.score ?? '';
+  const refs = finding.references.map((url) => safeLink(url)).filter(Boolean);
+  const aliases = [...new Set([finding.id, ...finding.aliases].filter(Boolean))];
+  const ranges = finding.affected.flatMap((affected) => affected.ranges.map((range) => {
+    const events = range.events.map((event) => {
+      const [kind, version] = Object.entries(event)[0] ?? [];
+      return kind ? `${kind}: ${version}` : null;
+    }).filter(Boolean);
+    return `${range.type ?? 'version'} (${events.join(', ')})`;
+  }));
+  return `<article class="finding" data-severity="${escapeHtml(severity)}" data-package="${escapeHtml(item.name)}" data-score="${escapeHtml(score)}">
+    <div class="finding-heading"><span class="badge ${escapeHtml(severity.toLowerCase())}">${escapeHtml(severity)}</span><strong>${escapeHtml(item.name)}@${escapeHtml(item.version)}</strong><span class="ids">${escapeHtml(aliases.join(' · '))}</span></div>
+    <p>${escapeHtml(finding.summary)}</p>
+    <p class="meta">${escapeHtml(item.purl)} · ${escapeHtml(item.direct ? 'Direct' : 'Transitive / indirect')} · Sources: ${escapeHtml(finding.sources.join(', '))}</p>
+    ${ranges.length ? `<p><strong>Affected range:</strong> ${escapeHtml(ranges.join('; '))}</p>` : ''}
+    <p><strong>Fix guidance:</strong> ${escapeHtml(finding.remediation)}</p>
+    ${finding.details ? `<details><summary>Advisory details</summary><p>${escapeHtml(finding.details)}</p></details>` : ''}
+    ${refs.length ? `<p class="refs">${refs.map((url) => `<a href="${escapeHtml(url)}" target="_blank" rel="noopener noreferrer">Reference</a>`).join(' ')}</p>` : ''}
+  </article>`;
+}
+
+export function renderHtml(report) {
+  const { summary, packages, coverage } = report;
+  const rows = packages.flatMap((item) => item.vulnerabilities.map((finding) => findingMarkup(item, finding)));
+  const body = rows.length
+    ? rows.join('\n')
+    : '<p class="empty">No vulnerabilities were returned for the dependencies scanned. Check scan coverage below before treating this as a clean bill of health.</p>';
+  const severityRows = Object.entries(summary.severityCounts)
+    .map(([severity, count]) => `<li><span class="badge ${escapeHtml(severity.toLowerCase())}">${escapeHtml(severity)}</span> ${count}</li>`)
+    .join('');
+  const coverageErrors = coverage.errors.length
+    ? `<ul>${coverage.errors.map((error) => `<li><strong>${escapeHtml(error.source ?? 'Discovery')}:</strong> ${escapeHtml(error.file ? `${error.file}: ` : '')}${escapeHtml(error.message)}</li>`).join('')}</ul>`
+    : '<p>No scan or data-source errors were reported.</p>';
+  const lockfiles = coverage.lockfiles.length
+    ? `<ul>${coverage.lockfiles.map((file) => `<li><code>${escapeHtml(file)}</code></li>`).join('')}</ul>`
+    : '<p>No supported lockfiles or module files were found.</p>';
+
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Look-See dependency vulnerability report</title>
+<style>
+:root{color-scheme:light dark;font:15px/1.55 system-ui,sans-serif;--bg:#fff;--fg:#202124;--muted:#5f6368;--card:#f6f8fa;--border:#d0d7de;--link:#0969da}
+@media(prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--muted:#9198a1;--card:#161b22;--border:#30363d;--link:#58a6ff}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg)}main{max-width:1100px;margin:auto;padding:32px 20px}h1{margin-bottom:4px}.muted,.meta{color:var(--muted)}.summary{display:flex;gap:12px;flex-wrap:wrap;margin:24px 0}.stat,details,.finding{background:var(--card);border:1px solid var(--border);border-radius:8px}.stat{padding:12px 16px;min-width:140px}.stat strong{display:block;font-size:1.35rem}.finding{padding:16px;margin:12px 0}.finding-heading{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.ids{color:var(--muted);font-size:.9rem}.badge{border-radius:4px;padding:2px 7px;font-size:.75rem;font-weight:700;background:#8b949e;color:#fff}.critical,.high{background:#cf222e}.medium{background:#bf8700}.low{background:#0969da}.unknown{background:#6e7781}.meta{font-size:.85rem;overflow-wrap:anywhere}.refs a{margin-right:12px}a{color:var(--link)}details{padding:12px;margin:10px 0}summary{cursor:pointer}.empty{padding:20px;background:var(--card);border-radius:8px}code{overflow-wrap:anywhere}section{margin-top:32px}.controls{display:flex;align-items:end;flex-wrap:wrap;gap:18px;margin:16px 0 20px}.controls label{display:flex;flex-direction:column;gap:6px;font-size:1.05rem;font-weight:500}.controls input,.controls select{min-height:40px;padding:8px 11px;font:inherit;font-size:1.05rem;border:1px solid var(--border);border-radius:6px;background:var(--bg);color:var(--fg)}.controls input[type=search]{min-width:260px}
+</style></head><body><main>
+<h1>Look-See dependency vulnerability report</h1>
+<p class="muted">Project: <code>${escapeHtml(report.project)}</code> · Generated: ${escapeHtml(formatGeneratedAt(report.generatedAt))}</p>
+<div class="summary"><div class="stat"><strong>${summary.dependencies}</strong>dependencies scanned</div><div class="stat"><strong>${summary.vulnerableDependencies}</strong>with findings</div><div class="stat"><strong>${summary.vulnerabilities}</strong>vulnerabilities</div></div>
+<h2>Severity</h2><ul>${severityRows}</ul>
+<section><h2>Findings</h2><div class="controls"><label>Filter <input id="filter" type="search" placeholder="Package, CVE, or text"></label><label>Severity <select id="severity-filter"><option value="">All severities</option><option>CRITICAL</option><option>HIGH</option><option>MEDIUM</option><option>LOW</option><option>UNKNOWN</option></select></label><label>Sort <select id="sort"><option value="severity">Severity</option><option value="package">Package</option><option value="score">CVSS score</option></select></label></div><div id="findings">${body}</div></section>
+<section><h2>Scan coverage</h2><p>Advisory matching uses OSV package/version records. NVD records enrich matching CVEs where available. This report does not imply coverage of ecosystems without a supported lockfile parser.</p><p>Dependency resolution: ${escapeHtml(coverage.dependencyResolution)}</p><h3>Files scanned</h3>${lockfiles}<h3>Errors and limitations</h3>${coverageErrors}</section>
+<footer class="muted"><p>Generated by Look-See. Verify fixes against upstream advisories and rerun the scan.</p></footer>
+</main><script>
+(() => {
+  const list = document.getElementById('findings');
+  const search = document.getElementById('filter');
+  const severity = document.getElementById('severity-filter');
+  const sort = document.getElementById('sort');
+  const rank = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, UNKNOWN: 0 };
+  const update = () => {
+    const query = search.value.toLowerCase();
+    const cards = [...list.querySelectorAll('.finding')];
+    for (const card of cards) {
+      card.hidden = (query && !card.textContent.toLowerCase().includes(query)) || (severity.value && card.dataset.severity !== severity.value);
+    }
+    cards.sort((a, b) => {
+      if (sort.value === 'package') return a.dataset.package.localeCompare(b.dataset.package);
+      if (sort.value === 'score') return (Number(b.dataset.score) || -1) - (Number(a.dataset.score) || -1);
+      return (rank[b.dataset.severity] ?? 0) - (rank[a.dataset.severity] ?? 0);
+    }).forEach((card) => list.append(card));
+  };
+  search.addEventListener('input', update);
+  severity.addEventListener('change', update);
+  sort.addEventListener('change', update);
+  update();
+})();
+</script></body></html>`;
+}
+
+export async function writeReports(report, outputDirectory, formats) {
+  await fs.mkdir(outputDirectory, { recursive: true });
+  const written = {};
+  if (formats.includes('json')) {
+    const file = `${outputDirectory}/look-see-output.json`;
+    await fs.writeFile(file, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    written.json = file;
+  }
+  if (formats.includes('html')) {
+    const file = `${outputDirectory}/look-see-output.html`;
+    await fs.writeFile(file, renderHtml(report), 'utf8');
+    written.html = file;
+  }
+  return written;
+}
+
+export const reportHelpers = { escapeHtml, safeLink, formatGeneratedAt };