@exodus/stasis 1.0.0-beta.0 → 1.0.0-beta.10

package/package.json

@@ -1,54 +1,80 @@
 {
   "name": "@exodus/stasis",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.10",
   "description": "File-level source bundles and lockfiles",
   "type": "module",
   "exports": {
     "./esbuild": "./src/esbuild.js",
     "./webpack": "./src/webpack.js",
+    "./rollup": "./src/rollup.js",
     "./metro": "./src/metro.js",
     "./metro-transformer": "./src/metro-transformer.js",
     "./loader": "./src/loader.js",
     "./mock": "./src/mock.js",
     "./bundle": "./src/bundle.js",
+    "./bundle-reader": "./src/bundle-reader.js",
     "./cmd/bundle": "./src/cmd/bundle.js",
     "./cmd/build": "./src/cmd/build.js",
     "./diff": "./src/diff.js",
     "./lockfile": "./src/lockfile.js",
     "./prune": "./src/prune.js",
     "./sbom": "./src/sbom.js",
+    "./audit-corrections": "./src/audit-corrections.js",
+    "./vfs-bundle": "./src/vfs-bundle.js",
     "./logo.svg": "./logo.svg"
   },
   "files": [
     "bin/stasis.js",
     "logo.svg",
-    "src/apis/npm/index.js",
-    "src/apis/npm/semver.cjs",
+    "src/audit-corrections.js",
     "src/audit.js",
+    "src/babel.js",
+    "src/babel-worker.cjs",
     "src/bundle.js",
     "src/bundle-from-lockfile.js",
+    "src/bundle-reader.js",
     "src/cmd/bundle.js",
     "src/cmd/build.js",
     "src/cmd/diff.js",
-    "src/cmd/extract.js",
+    "src/cmd/github-bundle.js",
+    "src/cmd/output.js",
     "src/cmd/sbom.js",
     "src/diff.js",
     "src/esbuild.js",
+    "src/installed-commits.js",
+    "src/json-stream.js",
     "src/loader.js",
     "src/loader-mock.js",
     "src/loaders/bash.js",
+    "src/loaders/cargo.js",
+    "src/loaders/foundry.js",
     "src/loaders/rust.js",
     "src/loaders/solidity.js",
+    "src/loaders/solidity-ownership.js",
+    "src/loaders/toml.js",
     "src/loaders/php.js",
+    "src/loaders/paths.js",
     "src/lockfile.js",
     "src/metro.js",
+    "src/metro-resolver.js",
     "src/metro-transformer.js",
     "src/mock.js",
     "src/parse.js",
     "src/prune.js",
+    "src/resolve-fields.js",
+    "src/resolve-node.js",
+    "src/resolve-typescript.js",
+    "src/rollup.js",
     "src/sbom.js",
     "src/scan.js",
-    "src/webpack.js"
+    "src/vfs-bundle.js",
+    "src/vfs-bundle/entries.js",
+    "src/vfs-bundle/github.js",
+    "src/vfs-bundle/prisma.js",
+    "src/vfs-bundle/soldeer.js",
+    "src/vfs-bundle/tree.js",
+    "src/webpack.js",
+    "src/why.js"
   ],
   "engines": {
     "node": ">=24.14.0"
@@ -58,26 +84,40 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ExodusOSS/stasis.git",
+    "url": "git+https://github.com/PreventiveMeasures/stasis.git",
     "directory": "stasis"
   },
   "author": "Exodus Movement, Inc.",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/ExodusOSS/stasis/issues"
+    "url": "https://github.com/PreventiveMeasures/stasis/issues"
   },
-  "homepage": "https://github.com/ExodusOSS/stasis#readme",
+  "homepage": "https://github.com/PreventiveMeasures/stasis#readme",
   "dependencies": {
-    "@exodus/stasis-core": "1.0.0-beta.0",
-    "@exodus/stasis-plugins": "1.0.0-beta.0",
-    "oxc-parser": "^0.94.0"
+    "@exodus/bytes": "^1.16.0",
+    "@exodus/stasis-core": "1.0.0-beta.10",
+    "@exodus/stasis-plugins": "1.0.0-beta.10",
+    "@preventive/archive": "1.0.0-beta.4",
+    "@preventive/deptree": "1.0.0-alpha.11",
+    "@preventive/lockfile": "1.0.0-alpha.7",
+    "@preventive/upstream": "1.0.0-alpha.12",
+    "@preventive/vfs": "1.0.0-beta.4",
+    "oxc-parser": "^0.152.0"
   },
   "peerDependencies": {
-    "esbuild": "*"
+    "@prisma/client-generator-ts": "7.10.0",
+    "esbuild": "*",
+    "flow-remove-types": "*"
   },
   "peerDependenciesMeta": {
+    "@prisma/client-generator-ts": {
+      "optional": true
+    },
     "esbuild": {
       "optional": true
+    },
+    "flow-remove-types": {
+      "optional": true
     }
   }
 }

package/src/audit-corrections.js

@@ -0,0 +1,96 @@
+import { satisfies, valid } from '@preventive/upstream/semver.js'
+
+// Manual corrections to audit findings: files that must NOT count as evidence
+// that a (potentially vulnerable) package's code is present. An import edge whose
+// target is one of these files is not evidence the package is really used, so a
+// package pulled in only through corrected files is skipped by the audit (see
+// collectPackagesFromFile) -- none of its real code ships, so no advisory applies.
+//
+// Exported as `@exodus/stasis/audit-corrections`, as plain data, so a tool that
+// lays out or reads packages without stasis -- a tree @preventive/deptree builds,
+// a server reading bundles -- can apply the same corrections without its own copy.
+// Each entry names a package of `ecosystem`, one audit-irrelevant `file` (relative
+// to the module dir), `range` -- the semver range VERIFIED to match the rationale --
+// and `integrity`, the sha512 of every distinct copy of `file` the versions in
+// `range` publish, as a stasis lockfile records a file: a holder of the file's bytes
+// can tell they are one of the copies verified. The correction never applies outside
+// the range: a release could change the file, so the range is widened only after
+// re-checking the file in the new versions, adding any new copy's integrity. Frozen,
+// as the audit reads these very objects.
+export const CORRECTIONS = Object.freeze([
+  {
+    // ws's browser build is a noop stub -- `module.exports = function () { throw
+    // new Error('ws does not work in the browser...') }` -- with none of the
+    // WebSocket implementation in it. browser.js ships from 6.0.0 on; every copy
+    // through 8.22.0 (latest at the time of writing) is one of these two, which
+    // differ only in a space; re-check browser.js before widening.
+    ecosystem: 'npm',
+    name: 'ws',
+    file: 'browser.js',
+    range: '<=8.22.0',
+    integrity: [
+      'sha512-98uEc4/THUpHCA7AQwBKLHHmxV6leyGmPkDAYZsoBiigxjKL8//TIb/oUKDUJLc+s/pwdGA9LR0F9e7nZHfXUQ==', // `function ()`: 6.0.0 - 6.1.1, 7.3.1 - 8.22.0
+      'sha512-F7vx6oiX9vsFoxNPTudk20Hjp7IzJePAJCYaSoX9FMJ2JaGVcFx4Bkw5W7+I3a1DsonitnosbpuG1qAMsUwH7w==', // `function()`: 6.1.2 - 7.3.0
+    ],
+  },
+  {
+    // node-fetch's browser build re-exports the environment's native fetch
+    // (`module.exports = globalObject.fetch`, plus Headers/Request/Response) --
+    // none of the node-fetch implementation, where its advisories live, is in it.
+    // browser.js ships only from 2.0.0 through 2.7.0 (3.x dropped it); every copy
+    // in the range is one of these, which differ in how they find the global.
+    ecosystem: 'npm',
+    name: 'node-fetch',
+    file: 'browser.js',
+    range: '<=2.7.0',
+    integrity: [
+      'sha512-uCZB0X6rUVIf5lZU2NN9/Z1Fd6cPCLg4M9eduYxOgSP3QZNwi0/xSa/s6AUFtvLz4y4MK02SJihOIhDoFIzdiA==', // 2.0.0 - 2.1.1
+      'sha512-toQ4RDdyjsAxTaxnaLs2AE56rXws+jMZV896U8pP0MSuKRiq8ZGKkOTMsvyCJoAJTbrgoQpr89H2n8+Z1ALcYA==', // 2.1.2
+      'sha512-LOd+I1R3xYSCHFN9oj3xeN3wa7fYYx5XQKTiKkvWn4dSYVgHI2jsXZp0mJt5KlQg3ECXXh5UtpEW7kGu1dG/aQ==', // 2.2.0 - 2.2.1
+      'sha512-2yo4Ysl+g09ocycwEBcN7IkSvM/KPpO9CW+1FI+0QfzvWJfaQepo+WEqn1/o5Og1weM14flcdv23hqZtxFXFUw==', // 2.3.0 - 2.6.0
+      'sha512-WgHaZJVwFovVrKVySaKzxzXssn5kY8y3x8NJThodDRL9nwUxV7Q1z/RRzuLZ2lNkxabHLpG/l+vu7KQ2tGbP8g==', // 2.6.1 - 2.6.7
+      'sha512-84sQFcu3uzgEsJOjIhz6tE8vInV1STCA4sX5EI9NK3Tt8n/Kb1serbKMz+YkdOAuCspHRiSUW2qV01z0wOgIXg==', // 2.6.8
+      'sha512-SkBfLO20d2Ngr6nhxgh/Pt6Yqe6oW8EB99KSPq0lrW0se8jIiRF3YpOe7hHbfNWxuNCsKoZZT98uCJI9OJAa/Q==', // 2.6.9 - 2.7.0
+    ],
+  },
+].map((correction) => Object.freeze({ ...correction, integrity: Object.freeze(correction.integrity) })))
+
+// Is `rel` (a file path relative to the module dir) audit-irrelevant for
+// `name@version` of `ecosystem`? Unknown or unparsable versions are never
+// corrected (fail closed: the package stays audited).
+function isCorrectedFile(name, version, rel, ecosystem) {
+  for (const correction of CORRECTIONS) {
+    if (correction.ecosystem !== ecosystem || correction.name !== name || correction.file !== rel) continue
+    if (valid(version) && satisfies(version, correction.range)) return true
+  }
+  return false
+}
+
+// A manifest (top-level or nested) is never code: the resolution graph records
+// resolver/metadata reads of `package.json` as edges (react-native scans sibling
+// packages' manifests for Haste/asset resolution) and consumers record them
+// alongside bundled files, but no package code ships through one. So too for the
+// manifests the other ecosystems' bundles carry beside a dependency's code
+// (--cargo-manifests, --manifests): its Cargo.toml and the checksums cargo vendored
+// it with (a registry's copy, a git checkout's, or one whose source isn't known),
+// its composer.json, a Solidity dependency's foundry.toml and remappings.
+const CARGO_MANIFESTS = new Set(['Cargo.toml', 'Cargo.lock', '.cargo-checksum.json'])
+const MANIFESTS = {
+  npm: new Set(['package.json']),
+  cargo: CARGO_MANIFESTS,
+  'cargo-git': CARGO_MANIFESTS,
+  'cargo-unknown': CARGO_MANIFESTS,
+  composer: new Set(['composer.json', 'composer.lock']),
+  soldeer: new Set(['package.json', 'foundry.toml', 'remappings.txt', 'soldeer.toml']),
+  github: new Set(['package.json', 'foundry.toml', 'remappings.txt', 'soldeer.toml']),
+}
+const isManifest = (rel, ecosystem) => MANIFESTS[ecosystem]?.has(rel.slice(rel.lastIndexOf('/') + 1)) ?? false
+
+// Is `rel` evidence that `name@version`'s REAL code is present, of a dependency of
+// `ecosystem` (npm by default)? This is the one rule every audit surface shares --
+// package presence, the reason column, and the --why chain graph all count a file
+// (or an edge targeting it) only when it passes. Manifests never do; CORRECTIONS'
+// files don't within their verified range.
+export function isEvidenceFile(name, version, rel, ecosystem = 'npm') {
+  return !isManifest(rel, ecosystem) && !isCorrectedFile(name, version, rel, ecosystem)
+}

package/src/audit.js

@@ -1,112 +1,337 @@
-import { advisories } from './apis/npm/index.js'
-import semver from './apis/npm/semver.cjs'
-import { parseFile } from './parse.js'
+import { packageRepo } from '@exodus/stasis-core/bundle-util'
+import { dependencyEcosystem, moduleFileKey, sameGithub } from '@exodus/stasis-core/util'
+import { advisories } from '@preventive/upstream/advisories.js'
+import { compareVersions, valid } from '@preventive/upstream/semver.js'
+import { isEvidenceFile } from './audit-corrections.js'
+import { parseFile, parseFileWithKind } from './parse.js'
+import { collectWhy, invertReason } from './why.js'
 
-// Only audit installed dependencies; workspace/first-party packages live under
-// non-`node_modules` keys in .modules (Lockfile/Bundle merge sources in) and
-// shouldn't be sent to the public registry — they leak names and produce noise.
+// Where advisories() asks for each ecosystem's advisories: npm's registry; OSV for crates (those
+// vendored from a registry, which OSV takes for crates.io's) and Composer packages; for Soldeer
+// packages and GitHub repos (Foundry's lib/ submodules), the advisories their GitHub repository
+// publishes, a Soldeer package's as Soldeer names it.
+const SOURCES = { npm: ['npm'], cargo: ['OSV'], composer: ['OSV'], soldeer: ['Soldeer', 'GitHub'], github: ['GitHub'] }
+
+// Why a vendored crate that may not be crates.io's is asked nowhere: by its name, crates.io's
+// advisories would be another crate's, and a private git dependency's name must not reach a public
+// database at all.
+const UNREGISTERED_CRATES = {
+  'cargo-git': 'a crate vendored from a git repository, not crates.io',
+  'cargo-unknown': 'a vendored crate with no .cargo-checksum.json, which may be a git checkout, not crates.io\'s',
+}
+
+// A dependency's version as it is audited: a GitHub repo's `.gitmodules` branch `.`, git's for the
+// superproject's own branch, which the bundle does not know and advisories() takes for no branch, is
+// the 0.0.0 stasis versions a repo with no version of its own by. Every advisory range covers both,
+// as it does a branch name.
+const versionOf = (ecosystem, version) => (ecosystem === 'github' && version === '.' ? '0.0.0' : version)
+
+// A package's key across the audit: `name@version` for npm, as collectWhy keys its chains, and
+// prefixed by the ecosystem for the others, whose names may be npm's too.
+const keyOf = (ecosystem, name, version) => `${ecosystem === 'npm' ? '' : `${ecosystem}:`}${name}@${version}`
+
+// Composer's dev versions (`dev-main`, `1.x-dev`), as Composer tells them, a `#ref` dropped: no
+// advisory database lists those, and advisories() takes releases alone.
+const isComposerDev = (version) => /^dev-|-dev$/iu.test(version.replace(/#.*$/su, ''))
+
+// Why `pkg` cannot be audited, or undefined where it can.
+function unaudited({ ecosystem, version }) {
+  if (Object.hasOwn(UNREGISTERED_CRATES, ecosystem)) return UNREGISTERED_CRATES[ecosystem]
+  if (!Object.hasOwn(SOURCES, ecosystem)) return `no advisories are looked up for ${ecosystem}`
+  if (ecosystem === 'composer' && isComposerDev(version)) return 'a Composer dev version, which no advisory database lists'
+  return undefined
+}
+
+// Only audit installed dependencies, `{ ecosystem, name, version }`: an npm package, a vendored
+// crate, a Composer package, a Soldeer package or a GitHub repo, as the bundle tags it (a crate
+// vendored from git, or from where no `.cargo-checksum.json` tells, is listed but never asked about).
+//
+// A package counts as present only when its REAL code is, and recorded = present:
+// an artifact records exactly the files it ships or attested -- imported, entry,
+// or `add`-ed (the last two have no in-edge in the resolution graph, so presence
+// must NOT be derived from edges). The package is audited only if some recorded
+// file is code evidence (see audit-corrections.js) -- not a corrected file (ws's
+// noop browser.js stub), not a manifest (package.json, recorded for resolver /
+// metadata reads; Cargo.toml). So a ws shipped only as browser.js (+ manifest) is
+// skipped, while one whose real code was bundled stays. Which consumers and import
+// EDGES reach that code is the reason column's concern -- collectReasons and
+// why.js apply the same evidence rule per file/edge there.
+//
+// A package's `github` is the repository its artifact records for it (its package.json's), where
+// one does; else, for an npm package a bundle carries the package.json of (one built before builds
+// recorded `repo`), the one that names, read by the rule builds record it by. A GitHub repo is its
+// own, and has none.
 export function collectPackagesFromFile(file) {
   const out = []
-  for (const [dir, { name, version }] of parseFile(file).modules) {
-    if (!dir.includes('node_modules')) continue
-    if (name && version) out.push({ name, version })
+  const { kind, artifact } = parseFileWithKind(file)
+  for (const [dir, { name, version, ecosystem: tagged, repo, files }] of artifact.modules) {
+    const ecosystem = dependencyEcosystem(dir, tagged)
+    // First-party code is never sent to a public registry (leaks names, adds noise).
+    if (ecosystem === undefined) continue
+    if (!name || !version) continue
+    if (!Object.keys(files).some((rel) => isEvidenceFile(name, version, rel, ecosystem))) continue
+    let github = ecosystem === 'github' ? undefined : repo?.github
+    if (github === undefined && ecosystem === 'npm' && kind === 'bundle') github = manifestRepo(files['package.json'])
+    out.push({ ecosystem, name, version: versionOf(ecosystem, version), ...(github === undefined ? {} : { github }) })
   }
   return out
 }
 
+// The GitHub repository a bundled package.json's text names (packageRepo), or undefined where it
+// names none or doesn't parse. Read as Node reads one, past a byte order mark (packageJSONText),
+// which a bundle keeps in the text. A lockfile holds the file's digest alone, never asked here.
+function manifestRepo(text) {
+  if (typeof text !== 'string') return undefined
+  try {
+    return packageRepo(JSON.parse(text.replace(/^\uFEFF/u, '')))?.github
+  } catch {
+    return undefined
+  }
+}
+
+// Versions in semver's order where both are semver's, else as numbers in text compare.
+const byNumbers = new Intl.Collator('en', { numeric: true }).compare
+const byVersion = (a, b) => (valid(a) && valid(b) ? compareVersions(a, b) : byNumbers(a, b))
+
+// Each package once, with the GitHub repository its artifacts record for its name, which
+// advisories() asks instead of looking one up. It takes one repository a name, so a name recorded
+// with two, by two of its versions (a package that moved) or by two artifacts, has none, and is
+// looked up as before.
 export function collectPackages(files) {
-  const seen = new Set()
-  const out = []
+  const byKey = new Map()
+  const repos = new Map() // `ecosystem:name` -> the one repository recorded for it, or null
   for (const file of files) {
-    for (const { name, version } of collectPackagesFromFile(file)) {
-      const key = `${name}@${version}`
-      if (seen.has(key)) continue
-      seen.add(key)
-      out.push({ name, version })
+    for (const { github, ...pkg } of collectPackagesFromFile(file)) {
+      const key = keyOf(pkg.ecosystem, pkg.name, pkg.version)
+      if (!byKey.has(key)) byKey.set(key, pkg)
+      if (github === undefined) continue
+      const name = `${pkg.ecosystem}:${pkg.name}`
+      const known = repos.get(name)
+      // The first spelling stands.
+      if (known === undefined) repos.set(name, github)
+      else if (known !== null && !sameGithub(known, github)) repos.set(name, null)
     }
   }
-  return out.toSorted((a, b) => a.name.localeCompare(b.name) || semver.compare(a.version, b.version))
+  return [...byKey.values()]
+    .map((pkg) => {
+      const github = repos.get(`${pkg.ecosystem}:${pkg.name}`)
+      return github ? { ...pkg, github } : pkg
+    })
+    .toSorted((a, b) => a.ecosystem.localeCompare(b.ecosystem) || a.name.localeCompare(b.name) || byVersion(a.version, b.version))
+}
+
+// Map each audited package (keyOf it) to the bundle consumers ("reasons") that recorded its files.
+// Only bundles carry a reason map ({ consumer: [file, ...] }); lockfiles omit it. Each file is
+// resolved back to its owning package via the module file listing. Only evidence files attribute
+// (see audit-corrections.js): a consumer that recorded nothing of a package but a corrected file or
+// its manifest carries none of its real code and is NOT a reason -- e.g. webpack shipping only ws's
+// noop browser.js stub, while `run` bundles the real ws.
+export function collectReasons(files) {
+  const byPkg = new Map()
+  for (const file of files) {
+    const artifact = parseFile(file)
+    const fileReasons = invertReason(artifact.reason)
+    if (!fileReasons) continue
+    const fileToPkg = new Map()
+    for (const [dir, { name, version, ecosystem: tagged, files: modFiles }] of artifact.modules) {
+      const ecosystem = dependencyEcosystem(dir, tagged)
+      if (ecosystem === undefined || !name || !version) continue
+      for (const rel of Object.keys(modFiles)) {
+        if (!isEvidenceFile(name, version, rel, ecosystem)) continue
+        fileToPkg.set(moduleFileKey(dir, rel), keyOf(ecosystem, name, versionOf(ecosystem, version)))
+      }
+    }
+    for (const [f, consumers] of fileReasons) {
+      const key = fileToPkg.get(f)
+      if (key === undefined) continue
+      let set = byPkg.get(key)
+      if (set === undefined) byPkg.set(key, (set = new Set()))
+      for (const consumer of consumers) set.add(consumer)
+    }
+  }
+  return byPkg
 }
 
 const SEVERITY_ORDER = { critical: 0, high: 1, moderate: 2, low: 3, info: 4, none: 5 }
 
-export function flattenAdvisories(result, packages = []) {
-  const installed = new Map()
-  for (const { name, version } of packages) {
-    if (!installed.has(name)) installed.set(name, [])
-    installed.get(name).push(version)
+// Consumer display order: bundler plugins (metro, webpack, esbuild, ...) first,
+// then `run`, then `add`. Ties broken alphabetically.
+const CONSUMER_RANK = { run: 1, add: 2 }
+const consumerRank = (c) => CONSUMER_RANK[c] ?? 0
+const byConsumerOrder = (a, b) => consumerRank(a) - consumerRank(b) || a.localeCompare(b)
+
+// Build a row's `reason` cell by unioning over exactly the affected versions it
+// covers. Without `--why` that's the `, `-joined set of bundle consumers; with
+// `--why` it's the newline-joined `consumer: a -> b -> c` import-path lines
+// (which REPLACE the consumer list). Consumers are ordered plugins -> run -> add.
+// `reasonFilter`, when set, narrows the cell to a single consumer: the `--why`
+// chains are already filtered upstream (see collectWhy), so only the consumer
+// list needs pruning here. collectWhy follows npm's import graph alone, so an
+// advisory of another ecosystem keeps its consumer list under `--why` too.
+function reasonCell({ ecosystem, name, versions: affected }, reasonsByPkg, whyByPkg, reasonFilter) {
+  const chains = whyByPkg !== null && ecosystem === 'npm'
+  const parts = new Set()
+  const source = chains ? whyByPkg : reasonsByPkg
+  for (const v of affected) {
+    for (const p of source.get(keyOf(ecosystem, name, v)) ?? []) parts.add(p)
+  }
+  // --why: group `consumer: path` lines by consumer and order the groups
+  // plugins -> run -> add (this also re-unites a consumer's lines when they were
+  // split across affected versions); within a group collectWhy's compressed order
+  // is preserved. Otherwise: the `, `-joined consumer set in the same order.
+  if (chains) {
+    const byConsumer = Map.groupBy(parts, (line) => {
+      const i = line.indexOf(': ')
+      return i === -1 ? '' : line.slice(0, i)
+    })
+    return [...byConsumer.keys()].toSorted(byConsumerOrder).flatMap((c) => byConsumer.get(c)).join('\n')
   }
+  const consumers = reasonFilter ? [...parts].filter((c) => c === reasonFilter) : [...parts]
+  return consumers.toSorted(byConsumerOrder).join(', ')
+}
+
+// `found` is what @preventive/upstream's advisories() answers: one row per advisory range, whose
+// `versions` are the audited versions it covers (never empty -- a range covering none is dropped
+// there, so the table and exit code reflect only real hits).
+export function flattenAdvisories(found, reasonsByPkg = new Map(), whyByPkg = null, reasonFilter = null) {
   const rows = []
-  for (const [pkg, list] of Object.entries(result)) {
-    if (!Array.isArray(list)) continue
-    const installedVersions = installed.get(pkg) ?? []
-    for (const adv of list) {
-      const range = adv.vulnerable_versions ?? ''
-      const affected = range
-        ? installedVersions.filter((v) => semver.satisfies(v, range))
-        : installedVersions
-      // npm occasionally returns advisories whose vulnerable range matches none
-      // of the versions we submitted; drop them so the table (and the CLI exit
-      // code) reflect only real hits.
-      if (installedVersions.length > 0 && affected.length === 0) continue
-      rows.push({
-        package: pkg,
-        installed: affected.join(', '),
-        vulnerable: range,
-        severity: adv.severity ?? '',
-        title: adv.title ?? '',
-        url: adv.url ?? '',
-      })
-    }
+  for (const adv of found) {
+    const reason = reasonCell(adv, reasonsByPkg, whyByPkg, reasonFilter)
+    // --reason keeps only advisories tied to that consumer: once the cell is
+    // narrowed to it, an empty cell means this package isn't related to it.
+    if (reasonFilter && reason === '') continue
+    rows.push({
+      ecosystem: adv.ecosystem,
+      package: adv.name,
+      installed: adv.versions.join(', '),
+      vulnerable: adv.range ?? '',
+      severity: adv.severity ?? '',
+      title: adv.title ?? '',
+      id: adv.id,
+      reason,
+    })
   }
   rows.sort((a, b) => {
     const sa = SEVERITY_ORDER[a.severity] ?? 99
     const sb = SEVERITY_ORDER[b.severity] ?? 99
     if (sa !== sb) return sa - sb
     if (a.package !== b.package) return a.package < b.package ? -1 : 1
+    if (a.ecosystem !== b.ecosystem) return a.ecosystem < b.ecosystem ? -1 : 1
     return a.title < b.title ? -1 : 1
   })
   return rows
 }
 
-// Line breaks in npm advisory titles would otherwise break the box layout.
-// Covers LF, bare CR (and CRLF), and U+2028 / U+2029 line/paragraph separators.
+// Strip line breaks (LF/CR/CRLF, U+2028/U+2029) from advisory titles so they can't break the box layout.
 const cell = (v) => String(v ?? '').replace(/[\r\n\u2028\u2029]+/gu, ' ')
 
-export function formatTable(rows, columns) {
+// Split a value into the physical lines a cell occupies. Non-multiline columns
+// collapse every line break to a space via `cell` (one line). A column named in
+// `multiline` (the `--why` reason column) keeps intentional `\n` breaks -- one
+// physical line per entry -- while still flattening stray CR/separators in each.
+const cellLines = (v, multiline) =>
+  multiline ? String(v ?? '').split('\n').map((s) => cell(s)) : [cell(v)]
+
+export function formatTable(rows, columns, { multiline = [] } = {}) {
   if (rows.length === 0) return ''
-  const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => cell(r[c]).length)))
+  const ml = new Set(multiline)
+  const linesOf = (obj) => columns.map((c) => cellLines(obj[c], ml.has(c)))
+  const header = columns.map((c) => [c])
+  const body = rows.map((r) => linesOf(r))
+  const widths = columns.map((c, i) =>
+    Math.max(c.length, ...body.map((cells) => Math.max(0, ...cells[i].map((l) => l.length))))
+  )
   const pad = (s, w) => s.padEnd(w)
   const line = (l, m, r, fill) => l + widths.map((w) => fill.repeat(w + 2)).join(m) + r
-  const row = (vals) => '│ ' + vals.map((v, i) => pad(cell(v), widths[i])).join(' │ ') + ' │'
+  // A row spans as many physical lines as its tallest cell; shorter cells pad
+  // out with blanks so the borders stay aligned.
+  const render = (cells) => {
+    const height = Math.max(...cells.map((c) => c.length))
+    const out = []
+    for (let i = 0; i < height; i++) {
+      out.push('│ ' + cells.map((c, j) => pad(c[i] ?? '', widths[j])).join(' │ ') + ' │')
+    }
+    return out.join('\n')
+  }
   return [
     line('┌', '┬', '┐', '─'),
-    row(columns),
+    render(header),
     line('├', '┼', '┤', '─'),
-    ...rows.map((r) => row(columns.map((c) => r[c]))),
+    ...body.map(render),
     line('└', '┴', '┘', '─'),
   ].join('\n')
 }
 
-export async function audit(files) {
+// `repoAdvisories` and `github` (a @preventive/upstream/github.js client) go to advisories() as they
+// are; a Soldeer package or a GitHub repo needs the client, their repository being their only source.
+// A package that cannot be audited is `skipped`, with why (`because`), and asked for nothing.
+export async function audit(files, { why = false, whyDeep = false, whyFull = false, reason = null, repoAdvisories = false, github } = {}) {
+  // --why-deep and --why-full imply --why. Deep keeps every chain instead of the
+  // default pruning of chains whose full suffix is already a chain (see
+  // collectWhy/dropSuffixed); full spells chains out with no `...` collapse.
+  why = why || whyDeep || whyFull
   const packages = collectPackages(files)
-  if (packages.length === 0) {
-    return { packages, advisories: {}, rows: [] }
+  const skipped = packages.flatMap((pkg) => {
+    const because = unaudited(pkg)
+    return because === undefined ? [] : [{ ...pkg, because }]
+  })
+  const asked = packages.filter((pkg) => unaudited(pkg) === undefined)
+  if (asked.length === 0) {
+    return { packages, skipped, advisories: [], rows: [], why }
+  }
+  let result
+  try {
+    result = await advisories(asked.map(({ version, ...pkg }) => ({ ...pkg, versions: [version] })), { repoAdvisories, github })
+  } catch (cause) {
+    // Refused input or a malformed answer is an assertion that says so itself; a transport or
+    // HTTP failure gets the context of which request it was.
+    if (cause?.code === 'ERR_ASSERTION') throw cause
+    const sources = new Set([...asked.flatMap((pkg) => SOURCES[pkg.ecosystem]), ...(repoAdvisories ? ['GitHub'] : [])])
+    throw new Error(`${[...sources].join('/')} advisories request failed: ${cause.message}`, { cause })
+  }
+  // `--why` REPLACES the consumer list with per-consumer import paths, so only
+  // one of the two is computed for npm's advisories, the only ones collectWhy has
+  // paths for: another ecosystem's keep their consumers. Restrict the (potentially
+  // expensive) path search to the packages that actually carry an advisory.
+  // `reason` (--reason) narrows both the paths (in collectWhy) and the consumer
+  // list (in flattenAdvisories) to a single consumer, dropping advisories
+  // unrelated to it.
+  let rows
+  if (why) {
+    const npm = result.filter((adv) => adv.ecosystem === 'npm')
+    const targetKeys = new Set(npm.flatMap((adv) => adv.versions.map((v) => keyOf(adv.ecosystem, adv.name, v))))
+    const reasons = npm.length < result.length ? collectReasons(files) : undefined
+    rows = flattenAdvisories(result, reasons, collectWhy(files, targetKeys, reason, { deep: whyDeep, full: whyFull }), reason)
+  } else {
+    rows = flattenAdvisories(result, collectReasons(files), null, reason)
   }
-  const result = await advisories(packages)
-  const rows = flattenAdvisories(result, packages)
-  return { packages, advisories: result, rows }
+  return { packages, skipped, advisories: result, rows, why, whyDeep, whyFull, reason }
 }
 
-export function printAuditReport({ packages, rows }, { out = process.stdout, err = process.stderr } = {}) {
-  err.write(`Scanned ${packages.length} package${packages.length === 1 ? '' : 's'}\n`)
+// `10 alerts, 1 critical, 5 high, 3 moderate, 1 low`: the rows, then each severity present, in the
+// rows' own order (most severe first); a row without one is `unrated`, so the parts add up.
+function alertStats(rows) {
+  const bySeverity = Map.groupBy(rows, (r) => r.severity || 'unrated')
+  return [`${rows.length} alert${rows.length === 1 ? '' : 's'}`, ...[...bySeverity].map(([severity, list]) => `${list.length} ${severity}`)].join(', ')
+}
+
+export function printAuditReport({ packages, skipped = [], rows, why = false, reason = null }, { out = process.stdout, err = process.stderr } = {}) {
+  const scanned = `Scanned ${packages.length} package${packages.length === 1 ? '' : 's'}`
   if (packages.length === 0) {
-    err.write('No node_modules entries found in the input files\n')
-    return
-  }
-  if (rows.length === 0) {
-    err.write('No advisories found\n')
+    err.write(`${scanned}\nNo dependencies found in the input files\n`)
     return
   }
-  out.write(formatTable(rows, ['severity', 'package', 'installed', 'vulnerable', 'title', 'url']) + '\n')
+  err.write(`${scanned}: ${alertStats(rows)}\n`)
+  for (const pkg of skipped) err.write(`Not audited: ${pkg.ecosystem} ${pkg.name}@${pkg.version}, ${pkg.because}\n`)
+  if (rows.length === 0) return
+  // The ecosystem column only where one is not npm's, which the others were all once.
+  const columns = ['severity', ...(rows.some((r) => r.ecosystem !== 'npm') ? ['ecosystem'] : []), 'package', 'installed', 'vulnerable', 'title', 'id']
+  // Surface the reason column only when some advisory has provenance -- bundle
+  // consumers, or (with --why) import paths. Under --reason WITHOUT --why every
+  // cell is just the filter value repeated, so drop the column then; --why still
+  // earns it (the import chains differ per row).
+  if (rows.some((r) => r.reason) && !(reason && !why)) columns.splice(columns.indexOf('installed') + 1, 0, 'reason')
+  // Under --why the reason cell is a list of `consumer: path` lines; let it span
+  // multiple physical rows instead of collapsing to one.
+  out.write(formatTable(rows, columns, { multiline: why ? ['reason'] : [] }) + '\n')
 }