@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/package-scan.cjs

@@ -0,0 +1,919 @@
+/**
+ * package-scan.cjs -- Phase 150 orchestrator for /dgs:package-scan
+ *
+ * Composes the Phase 149 leaf modules (package-ecosystems, package-runner,
+ * package-adapters) into a scan pipeline: iterates REPOS.md + product root,
+ * resolves each target via resolveCodeContext so active worktrees are scanned,
+ * applies the Snyk->OSV->native tool cascade (honouring testing.packages.tool
+ * pins with install-hint failures), invokes the runner, normalises adapter
+ * output, merges findings with pkg-NNN ids, and returns a structured result.
+ *
+ * Does NOT: write reports (Phase 151), wire the /dgs:package-scan command
+ * (Phase 151), normalise severities (Phase 152), extract licences (Phase 153),
+ * dedupe cross-repo (Phase 153).
+ *
+ * Exports: cmdPackageScan, runScan, collectScanTargets, selectTool, resolveSnykAuth.
+ *
+ * Covers roadmap requirements: PKG-01..PKG-05, PKG-15..PKG-18, PKG-40.
+ *
+ * Finding id ordering: target-order -> ecosystem-group-order -> workspace-loop-order -> adapter-emitted-order.
+ * Ids assigned AFTER all targets scanned, as pkg-NNN (zero-padded 3-digit).
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { getPlanningRoot } = require('./paths.cjs');
+const { output, error, loadConfig } = require('./core.cjs');
+const { parseReposMd } = require('./repos.cjs');
+const { resolveCodeContext } = require('./context.cjs');
+const { getLocalConfigPath } = require('./config.cjs');
+
+const { writePackageScanReport, _collapseSeverity } = require('./package-scan-report.cjs');
+const { provenanceLookup } = require('./package-scan-provenance.cjs');
+const { detectEcosystems } = require('./package-ecosystems.cjs');
+const {
+  runTool,
+  ECOSYSTEM_OVERRIDES,
+  DEFAULT_TIMEOUT_MS,
+} = require('./package-runner.cjs');
+const {
+  adapterSnyk, adapterOsv, adapterNpmAudit,
+  adapterPipAudit, adapterGovulncheck, adapterBundlerAudit,
+} = require('./package-adapters.cjs');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** Map ecosystem -> native-tool key (null = no native tool in P0 cascade). */
+const NATIVE_TOOL_FOR_ECOSYSTEM = Object.freeze({
+  node:   'npm-audit',
+  python: 'pip-audit',
+  go:     'govulncheck',
+  ruby:   'bundler-audit',
+  java:   null,         // PKG-03: Maven/Gradle have no native in P0; Snyk/OSV only
+  yarn:   'npm-audit',  // ECOSYSTEM_OVERRIDES forces yarn -> osv when available
+});
+
+/** Map toolKey -> adapter function. */
+const ADAPTER_FOR_TOOL = Object.freeze({
+  'snyk':          adapterSnyk,
+  'osv-scanner':   adapterOsv,
+  'npm-audit':     adapterNpmAudit,
+  'pip-audit':     adapterPipAudit,
+  'govulncheck':   adapterGovulncheck,
+  'bundler-audit': adapterBundlerAudit,
+});
+
+// Phase 153: severity_threshold is overridable via --threshold; include_dev_dependencies via
+// --include-dev-deps / --no-include-dev-deps; both fall back to the DEFAULTS below when no
+// CLI flag and no config key is present.
+/** Defaults for testing.packages.* keys (read via loadConfig(cwd)). */
+const DEFAULTS = Object.freeze({
+  tool: 'auto',
+  severity_threshold: 'low',
+  include_dev_dependencies: true,
+  timeout_seconds: 300,
+  // UAT Bug 2: Snyk org UUID (nullable). When truthy + tool===snyk,
+  // _buildArgv appends --org=<ID> so multi-org accounts resolve to the
+  // correct organisation without SNYK_CFG_ORG env plumbing.
+  snyk_org: null,
+});
+
+// Phase 153 PKG-27: severity rank table for threshold filtering.
+const SEVERITY_RANK = Object.freeze({
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1,
+});
+
+function _severityRank(tier) {
+  if (tier === null || tier === undefined) return 0;
+  const key = String(tier).toLowerCase();
+  return SEVERITY_RANK[key] || 0;
+}
+
+function _filterByThreshold(findings, threshold) {
+  if (!Array.isArray(findings) || findings.length === 0) return [];
+  if (threshold === null || threshold === undefined) return findings.slice();
+  const min = _severityRank(threshold);
+  if (min === 0) return findings.slice(); // unknown threshold = no filter (be conservative)
+  return findings.filter(f => _severityRank(_collapseSeverity(f.severity)) >= min);
+}
+
+// Phase 153 PKG-32: detect a `.snyk` policy file in the given directory.
+function _detectSnykPolicy(dir) {
+  try {
+    return !!dir && fs.existsSync(path.join(dir, '.snyk'));
+  } catch { return false; }
+}
+
+function _parseArgs(args) {
+  const out = { threshold: null, only_repo: null, include_dev_dependencies: null, json: false, raw: false };
+  const valid = ['critical', 'high', 'medium', 'low'];
+  const arr = Array.isArray(args) ? args : [];
+  for (let i = 0; i < arr.length; i++) {
+    const a = arr[i];
+    if (a === '--threshold') {
+      const v = arr[i + 1];
+      if (v === undefined || (typeof v === 'string' && v.startsWith('--'))) {
+        throw new Error('Missing value for --threshold. Valid: ' + valid.join(', '));
+      }
+      if (!valid.includes(String(v).toLowerCase())) {
+        throw new Error("Invalid threshold '" + v + "'. Valid: critical, high, medium, low.");
+      }
+      out.threshold = String(v).toLowerCase();
+      i++;
+    } else if (a === '--repo') {
+      const v = arr[i + 1];
+      if (v === undefined || (typeof v === 'string' && v.startsWith('--'))) {
+        throw new Error('Missing value for --repo.');
+      }
+      out.only_repo = v;
+      i++;
+    } else if (a === '--include-dev-deps') {
+      out.include_dev_dependencies = true;
+    } else if (a === '--no-include-dev-deps') {
+      out.include_dev_dependencies = false;
+    } else if (a === '--json') {
+      out.json = true;
+    } else if (a === '--raw') {
+      out.raw = true;
+    }
+    // Unknown flags ignored for forward-compat.
+  }
+  return out;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Probe whether a binary is available on PATH. Per-invocation (no caching).
+ */
+function _checkToolOnPath(binName) {
+  const cmd = process.platform === 'win32' ? 'where' : 'command';
+  const argv = process.platform === 'win32' ? [binName] : ['-v', binName];
+  const result = spawnSync(cmd, argv, { encoding: 'utf-8', timeout: 2000, shell: process.platform !== 'win32' });
+  const available = result && result.status === 0 && typeof result.stdout === 'string' && result.stdout.trim().length > 0;
+  return { available, path: available ? result.stdout.trim().split(/\r?\n/)[0] : null };
+}
+
+/**
+ * Read testing.packages.* from config.json + config.local.json without going through
+ * loadConfig (which flattens to a canonical shape that omits the testing section).
+ * Local overrides shared for overlapping keys; snyk_token only comes from config.local.json.
+ */
+function _readPackagesConfig(cwd) {
+  const root = getPlanningRoot(cwd);
+  const sharedPath = path.join(root, 'config.json');
+  const localPath = getLocalConfigPath(cwd);
+  let shared = {};
+  let local = {};
+  try {
+    if (fs.existsSync(sharedPath)) shared = JSON.parse(fs.readFileSync(sharedPath, 'utf-8'));
+  } catch { /* ignore */ }
+  try {
+    if (fs.existsSync(localPath)) local = JSON.parse(fs.readFileSync(localPath, 'utf-8'));
+  } catch { /* ignore */ }
+  const sharedPkg = (shared.testing && shared.testing.packages) || {};
+  const localPkg = (local.testing && local.testing.packages) || {};
+  return { ...sharedPkg, ...localPkg };
+}
+
+// ─── Public: resolveSnykAuth ──────────────────────────────────────────────────
+
+/**
+ * Detects Snyk auth presence without invoking `snyk auth` (spec success criterion 3).
+ * Precedence: config.local.json -> SNYK_TOKEN env -> `snyk config get api` ->
+ *             `snyk whoami` (configstore-OAuth via `snyk auth`) -> none.
+ *
+ * UAT Bug 1 (PACKAGE-SCAN-2026-04-20-0928.md): the fourth probe (`snyk whoami`
+ * exit 0) catches users who authenticated via the browser-OAuth flow (credential
+ * stored in ~/.config/configstore/snyk.json) — `snyk config get api` returns
+ * empty for these users. When whoami succeeds, we do NOT return a token (the
+ * configstore credential is not revealed); runScan's env block at line 555
+ * correctly handles this by setting env={}, which lets the snyk CLI read its
+ * own configstore at invocation time.
+ *
+ * @param {string} cwd
+ * @param {{_spawnSync?: function}} [deps] - test seam; defaults to the imported spawnSync.
+ * @returns {{
+ *   available: boolean,
+ *   source: 'config.local.json'|'env'|'snyk-cli-config'|'snyk-cli-whoami'|'none',
+ *   auth_source: 'dgs_local'|'env_token'|'api_config'|'oauth_configstore'|null,
+ *   token?: string
+ * }}
+ */
+function resolveSnykAuth(cwd, deps = {}) {
+  const _spawn = deps._spawnSync || spawnSync;
+
+  // 1. config.local.json (highest precedence)
+  try {
+    const pkg = _readPackagesConfig(cwd);
+    const token = pkg.snyk_token;
+    if (typeof token === 'string' && token.length > 0) {
+      return { available: true, source: 'config.local.json', auth_source: 'dgs_local', token };
+    }
+  } catch { /* fall through */ }
+
+  // 2. SNYK_TOKEN env var
+  const envToken = process.env.SNYK_TOKEN;
+  if (typeof envToken === 'string' && envToken.length > 0) {
+    return { available: true, source: 'env', auth_source: 'env_token', token: envToken };
+  }
+
+  // 3. `snyk config get api` -- NEVER call `snyk auth` (pitfall 6)
+  try {
+    const probe = _spawn('snyk', ['config', 'get', 'api'], { encoding: 'utf-8', timeout: 5000 });
+    if (probe && probe.status === 0 && typeof probe.stdout === 'string') {
+      const stdout = probe.stdout.trim();
+      if (stdout.length > 0) {
+        return { available: true, source: 'snyk-cli-config', auth_source: 'api_config', token: stdout };
+      }
+    }
+  } catch { /* fall through */ }
+
+  // 4. `snyk whoami` -- configstore-OAuth (set by `snyk auth` browser flow).
+  // Do NOT invoke `snyk auth` itself (pitfall 6 — opens a browser).
+  // whoami does not yield a token, so we omit the token field; runScan detects
+  // `!snyk.token` and omits SNYK_TOKEN from the spawn env, which lets the snyk
+  // CLI consult its own configstore on the next invocation.
+  try {
+    const whoami = _spawn('snyk', ['whoami'], { encoding: 'utf-8', timeout: 5000 });
+    if (whoami && whoami.status === 0) {
+      return { available: true, source: 'snyk-cli-whoami', auth_source: 'oauth_configstore' };
+    }
+  } catch { /* fall through */ }
+
+  return { available: false, source: 'none', auth_source: null };
+}
+
+// ─── Public: selectTool ───────────────────────────────────────────────────────
+
+/**
+ * Given { configTool, entryEcosystem, snykAuth, toolsOnPath }, return tier decision.
+ * Pure function — no side effects, no I/O. toolsOnPath is a function (binName) -> { available }.
+ *
+ * ECOSYSTEM_OVERRIDES (e.g., yarn -> osv) takes precedence over configTool.
+ */
+function selectTool(ctx) {
+  const { configTool, entryEcosystem, snykAuth, toolsOnPath } = ctx;
+  const isOnPath = (bin) => {
+    const r = toolsOnPath(bin);
+    return r && r.available;
+  };
+
+  // Ecosystem override first
+  const override = ECOSYSTEM_OVERRIDES[entryEcosystem];
+  if (override && override.force_tool) {
+    const forced = override.force_tool;
+    if (forced === 'osv') {
+      if (isOnPath('osv-scanner')) {
+        return { tier: 'osv', toolKey: 'osv-scanner', reason: 'forced_by_ecosystem_override' };
+      }
+      return {
+        tier: 'unavailable',
+        reason: 'forced_tool_unavailable',
+        details: { ecosystem: entryEcosystem, tool_forced: forced }
+      };
+    }
+    if (forced === 'snyk') {
+      if (snykAuth && snykAuth.available && isOnPath('snyk')) {
+        return { tier: 'snyk', toolKey: 'snyk', reason: 'forced_by_ecosystem_override' };
+      }
+      return {
+        tier: 'unavailable',
+        reason: 'forced_tool_unavailable',
+        details: { ecosystem: entryEcosystem, tool_forced: forced }
+      };
+    }
+  }
+
+  // Pins
+  if (configTool === 'snyk') {
+    if (snykAuth && snykAuth.available && isOnPath('snyk')) {
+      return { tier: 'snyk', toolKey: 'snyk', reason: 'pinned' };
+    }
+    return { tier: 'unavailable', reason: 'tool_unavailable_on_pin', tool: 'snyk' };
+  }
+
+  if (configTool === 'osv') {
+    if (isOnPath('osv-scanner')) {
+      return { tier: 'osv', toolKey: 'osv-scanner', reason: 'pinned' };
+    }
+    return { tier: 'unavailable', reason: 'tool_unavailable_on_pin', tool: 'osv-scanner' };
+  }
+
+  if (configTool === 'native') {
+    const toolKey = NATIVE_TOOL_FOR_ECOSYSTEM[entryEcosystem] ?? null;
+    return { tier: 'native', toolKey, reason: 'pinned' };
+  }
+
+  // Auto cascade
+  if (snykAuth && snykAuth.available && isOnPath('snyk')) {
+    return { tier: 'snyk', toolKey: 'snyk', reason: 'auto' };
+  }
+  if (isOnPath('osv-scanner')) {
+    return { tier: 'osv', toolKey: 'osv-scanner', reason: 'auto' };
+  }
+  const toolKey = NATIVE_TOOL_FOR_ECOSYSTEM[entryEcosystem] ?? null;
+  return { tier: 'native', toolKey, reason: 'auto' };
+}
+
+// ─── Public: collectScanTargets ───────────────────────────────────────────────
+
+/**
+ * Enumerate scan targets: every repo in REPOS.md (worktree-aware) plus the product root.
+ *
+ * Phase 153 PKG-28: when `onlyRepo` is provided, restrict targets to the matching repo
+ * and exclude the product root. Returns shape: `{ targets, error }`. Backward-compat:
+ * legacy callsites that expected `Array` should switch to `.targets`.
+ *
+ * @param {string} cwd
+ * @param {string|null} [onlyRepo]
+ * @returns {{ targets: Array<{ name: string, dir: string, has_snyk_policy?: boolean }>, error: object|null }}
+ */
+function collectScanTargets(cwd, onlyRepo) {
+  const planningRoot = getPlanningRoot(cwd);
+  const parsed = parseReposMd(cwd);
+  const repos = (parsed && Array.isArray(parsed.repos)) ? parsed.repos : [];
+
+  const allTargets = repos.map(r => {
+    let dir;
+    try {
+      const ctx = resolveCodeContext(cwd, r.name);
+      dir = ctx && ctx.directory ? ctx.directory : path.resolve(planningRoot, r.path || ('../' + r.name));
+    } catch {
+      dir = path.resolve(planningRoot, r.path || ('../' + r.name));
+    }
+    return { name: r.name, dir, has_snyk_policy: _detectSnykPolicy(dir) };
+  });
+
+  if (onlyRepo !== null && onlyRepo !== undefined && onlyRepo !== '') {
+    const found = allTargets.find(t => t.name === onlyRepo);
+    if (!found) {
+      const validRepos = allTargets.length > 0
+        ? allTargets.map(t => t.name).join(', ')
+        : '(none registered)';
+      return {
+        targets: [],
+        error: {
+          kind: 'unknown_repo',
+          message: "Unknown repo: '" + onlyRepo + "'. Valid repos: " + validRepos + ". Use /dgs:package-scan (no flag) to scan all.",
+        },
+      };
+    }
+    return { targets: [found], error: null };
+  }
+
+  // PKG-16: always append product root when scanning all; detector handles "no manifests" gracefully
+  allTargets.push({ name: '_product_root', dir: planningRoot, has_snyk_policy: _detectSnykPolicy(planningRoot) });
+  return { targets: allTargets, error: null };
+}
+
+// ─── argv builder ─────────────────────────────────────────────────────────────
+
+function _buildArgv(tier, toolKey, entry, pkgCfg, opts = {}) {
+  const includeDev = pkgCfg.include_dev_dependencies !== false;
+  const isMonorepoRoot = !!opts.monorepoRoot; // Snyk needs --all-projects at root
+  switch (toolKey) {
+    case 'snyk': {
+      const argv = ['snyk', 'test', '--json'];
+      if (!includeDev) argv.push('--production');
+      if (isMonorepoRoot) argv.push('--all-projects');
+      // UAT Bug 2: thread --org=<ID> for multi-org Snyk accounts.
+      if (pkgCfg.snyk_org) argv.push('--org=' + pkgCfg.snyk_org);
+      return argv;
+    }
+    case 'osv-scanner':
+      return ['osv-scanner', '--json', '-r', '.'];
+    case 'npm-audit': {
+      const argv = ['npm', 'audit', '--json'];
+      if (!includeDev) argv.push('--omit=dev');
+      return argv;
+    }
+    case 'pip-audit':
+      return ['pip-audit', '--format=json'];
+    case 'govulncheck':
+      return ['govulncheck', '-json', './...'];
+    case 'bundler-audit':
+      return ['bundle', 'audit', 'check', '--format', 'json'];
+    default:
+      return [];
+  }
+}
+
+// ─── adapter dispatch ─────────────────────────────────────────────────────────
+
+function _invokeAdapter(toolKey, runResult, ctx) {
+  const adapter = ADAPTER_FOR_TOOL[toolKey];
+  if (!adapter) return [];
+  // govulncheck consumes stdout (NDJSON) string; others consume parsed JSON.
+  if (toolKey === 'govulncheck') {
+    return adapter(runResult.stdout, ctx) || [];
+  }
+  const payload = runResult.parsed !== undefined ? runResult.parsed : runResult.stdout;
+  try {
+    return adapter(payload, ctx) || [];
+  } catch {
+    return [];
+  }
+}
+
+// ─── main runScan ─────────────────────────────────────────────────────────────
+
+/**
+ * Pure orchestrator. Composes detector + runner + adapters + config + repos + context.
+ * Never throws on per-repo failure; only catastrophic setup errors escape.
+ *
+ * @param {string} cwd
+ * @param {object} [opts] -- future flags (threshold, repo, etc.); {} acceptable in Phase 150
+ * @param {object} [deps] -- TEST SEAM; inject { detector, runner, adapters, snykAuth, checkToolOnPath }
+ * @returns {{ exit_code: 0|2, tool_per_target, repo_results, findings, skipped, diagnostics }}
+ */
+function runScan(cwd, opts = {}, deps) {
+  deps = deps || {};
+  const detector = deps.detector || detectEcosystems;
+  const runner = deps.runner || runTool;
+  const snykAuthFn = deps.snykAuth || resolveSnykAuth;
+  const checkToolOnPath = deps.checkToolOnPath || _checkToolOnPath;
+  // Phase 153 PKG-33: provenance lookup test seam.
+  const provLookupFn = deps.provenanceLookup || provenanceLookup;
+
+  let pkgCfgRaw;
+  try {
+    pkgCfgRaw = _readPackagesConfig(cwd);
+  } catch {
+    pkgCfgRaw = {};
+  }
+  const pkgCfg = { ...DEFAULTS, ...pkgCfgRaw };
+  delete pkgCfg.snyk_token; // never exposed in effective config
+
+  const snyk = snykAuthFn(cwd);
+  const toolsOnPath = (bin) => checkToolOnPath(bin);
+
+  // Pin-fail-fast pre-check
+  if (pkgCfg.tool === 'snyk' && (!snyk.available || !toolsOnPath('snyk').available)) {
+    return {
+      exit_code: 2,
+      diagnostics: [{
+        kind: 'tool_unavailable_on_pin',
+        tool: 'snyk',
+        hint: 'Install Snyk CLI (https://docs.snyk.io/snyk-cli/install-the-snyk-cli) and run `snyk auth` or set SNYK_TOKEN via `dgs-tools config-local-set testing.packages.snyk_token`',
+      }],
+      findings: [],
+      repo_results: [],
+      tool_per_target: {},
+      skipped: [],
+    };
+  }
+  if (pkgCfg.tool === 'osv' && !toolsOnPath('osv-scanner').available) {
+    return {
+      exit_code: 2,
+      diagnostics: [{
+        kind: 'tool_unavailable_on_pin',
+        tool: 'osv-scanner',
+        hint: 'Install OSV-Scanner (https://github.com/google/osv-scanner)',
+      }],
+      findings: [],
+      repo_results: [],
+      tool_per_target: {},
+      skipped: [],
+    };
+  }
+
+  // Phase 153 PKG-28: support opts.only_repo to restrict scan targets.
+  const collected = collectScanTargets(cwd, opts.only_repo || null);
+  if (collected.error) {
+    return {
+      exit_code: 2,
+      tool_per_target: {},
+      repo_results: [],
+      findings: [],
+      skipped: [],
+      diagnostics: [collected.error],
+    };
+  }
+  const targets = collected.targets;
+  // Phase 153 PKG-27: resolve effective threshold (CLI > config > DEFAULT).
+  const effectiveThreshold = opts.threshold || pkgCfg.severity_threshold;
+  // Phase 153 PKG-28: resolve include_dev_dependencies (CLI > config > DEFAULT).
+  if (opts.include_dev_dependencies !== null && opts.include_dev_dependencies !== undefined) {
+    pkgCfg.include_dev_dependencies = opts.include_dev_dependencies;
+  }
+  const repo_results = [];
+  const tool_per_target = {};
+  const diagnostics = [];
+  const skipped = [];
+  // Phase 153 PKG-30/34: licence roster accumulator (Snyk only).
+  const rosterAccumulator = [];
+
+  for (const target of targets) {
+    let entries = [];
+    try {
+      entries = detector(target.dir) || [];
+    } catch {
+      entries = [];
+    }
+
+    if (entries.length === 0) {
+      repo_results.push({
+        repo: target.name,
+        ecosystem: null,
+        manifest_path: null,
+        tool_used: null,
+        tool_used_source: null,
+        outcome: 'no_manifests',
+        findings: [],
+        durationMs: 0,
+      });
+      continue;
+    }
+
+    // Group entries by ecosystem
+    const byEco = new Map();
+    for (const e of entries) {
+      if (!byEco.has(e.ecosystem)) byEco.set(e.ecosystem, []);
+      byEco.get(e.ecosystem).push(e);
+    }
+
+    for (const [ecosystem, group] of byEco) {
+      const selection = selectTool({
+        configTool: pkgCfg.tool,
+        entryEcosystem: ecosystem,
+        snykAuth: snyk,
+        toolsOnPath,
+      });
+
+      // Record tool_per_target (first ecosystem encountered wins for summary view)
+      if (tool_per_target[target.name] === undefined && selection.toolKey) {
+        tool_per_target[target.name] = selection.toolKey;
+      }
+
+      if (selection.tier === 'unavailable') {
+        repo_results.push({
+          repo: target.name,
+          ecosystem,
+          manifest_path: null,
+          tool_used: null,
+          tool_used_source: null,
+          outcome: 'skipped',
+          findings: [],
+          durationMs: 0,
+          diagnostic: {
+            kind: selection.reason,
+            message: selection.reason === 'forced_tool_unavailable'
+              ? `ECOSYSTEM_OVERRIDES forced ${selection.details.tool_forced} for ${ecosystem} but the tool is not on PATH`
+              : `Pinned tool ${selection.tool} is not available`,
+          },
+        });
+        skipped.push({ repo: target.name, ecosystem, reason: selection.reason });
+        continue;
+      }
+
+      if (selection.toolKey === null) {
+        // java native path -> no_native_tool_for_ecosystem
+        repo_results.push({
+          repo: target.name,
+          ecosystem,
+          manifest_path: null,
+          tool_used: null,
+          tool_used_source: null,
+          outcome: 'no_native_tool_for_ecosystem',
+          findings: [],
+          durationMs: 0,
+        });
+        continue;
+      }
+
+      const timeoutMs = (pkgCfg.timeout_seconds || DEFAULTS.timeout_seconds) * 1000;
+      const env = (selection.tier === 'snyk' && snyk.token) ? { SNYK_TOKEN: snyk.token } : {};
+
+      if (selection.tier === 'snyk' || selection.tier === 'osv') {
+        // Single invocation at target root; adapter extracts per-finding manifest_path
+        const argv = _buildArgv(selection.tier, selection.toolKey, null, pkgCfg, {
+          monorepoRoot: group.length > 1 || (group[0] && group[0].manifest_path),
+        });
+        let runResult;
+        try {
+          runResult = runner(target.dir, selection.toolKey, argv, { timeoutMs, env, expectJson: true });
+        } catch (err) {
+          runResult = { outcome: 'tool_failure', exitCode: -1, stdout: '', stderr: err.message || '', duration: 0, timedOut: false };
+        }
+
+        // Phase 153 PKG-32: per-invocation suppression counter; updated by adapterSnyk via ctx.recordSuppressions.
+        let suppressionsCount = 0;
+        let findings = [];
+        if (runResult.outcome === 'ok') {
+          findings = _invokeAdapter(selection.toolKey, runResult, {
+            repo: target.name,
+            ecosystem,
+            cwd: target.dir,
+            // manifest_path intentionally undefined for single-invoke: adapter extracts from tool JSON
+            recordSuppressions: (n) => { suppressionsCount = n; },
+            // Phase 153 PKG-30/34: receive licence roster entries (Snyk only).
+            recordLicenceRoster: (entries) => {
+              if (!Array.isArray(entries)) return;
+              for (const e of entries) rosterAccumulator.push({ repo: target.name, ...e });
+            },
+          });
+        }
+
+        repo_results.push({
+          repo: target.name,
+          ecosystem,
+          manifest_path: null,
+          tool_used: selection.toolKey,
+          tool_used_source: selection.tier === 'snyk' ? snyk.source : null,
+          outcome: runResult.outcome,
+          findings,
+          durationMs: runResult.duration || 0,
+          has_snyk_policy: target.has_snyk_policy === true,
+          snyk_suppressions_count: suppressionsCount,
+        });
+        continue;
+      }
+
+      // selection.tier === 'native'
+      // Python monorepo: multiple python entries -> tool_failure per entry (shared venv)
+      if (ecosystem === 'python' && group.length > 1 && selection.toolKey === 'pip-audit') {
+        for (const entry of group) {
+          repo_results.push({
+            repo: target.name,
+            ecosystem,
+            manifest_path: entry.manifest_path,
+            tool_used: selection.toolKey,
+            tool_used_source: null,
+            outcome: 'tool_failure',
+            findings: [],
+            durationMs: 0,
+            diagnostic: {
+              kind: 'python_monorepo_shared_venv',
+              message: 'Python monorepo native-tool invocation requires per-workspace venv; configure Snyk or install osv-scanner',
+            },
+          });
+        }
+        continue;
+      }
+
+      // Native loop: one runner call per workspace entry
+      for (const entry of group) {
+        const entryDir = entry.manifest_path
+          ? path.join(target.dir, path.dirname(entry.manifest_path))
+          : target.dir;
+        const argv = _buildArgv(selection.tier, selection.toolKey, entry, pkgCfg);
+        let runResult;
+        try {
+          runResult = runner(entryDir, selection.toolKey, argv, { timeoutMs, env, expectJson: true });
+        } catch (err) {
+          runResult = { outcome: 'tool_failure', exitCode: -1, stdout: '', stderr: err.message || '', duration: 0, timedOut: false };
+        }
+
+        let findings = [];
+        if (runResult.outcome === 'ok') {
+          findings = _invokeAdapter(selection.toolKey, runResult, {
+            repo: target.name,
+            ecosystem,
+            cwd: entryDir,
+            manifest_path: entry.manifest_path,
+          });
+        }
+
+        repo_results.push({
+          repo: target.name,
+          ecosystem,
+          manifest_path: entry.manifest_path,
+          tool_used: selection.toolKey,
+          tool_used_source: null,
+          outcome: runResult.outcome,
+          findings,
+          durationMs: runResult.duration || 0,
+        });
+      }
+    }
+  }
+
+  // Phase 153 PKG-32: ensure every repo_results row carries has_snyk_policy + snyk_suppressions_count.
+  // Snyk path already sets both; other paths default has_snyk_policy from target.has_snyk_policy and count to 0.
+  const targetByName = new Map();
+  for (const t of targets) targetByName.set(t.name, t);
+  for (const row of repo_results) {
+    if (row.has_snyk_policy === undefined) {
+      const t = targetByName.get(row.repo);
+      row.has_snyk_policy = t ? (t.has_snyk_policy === true) : false;
+    }
+    if (row.snyk_suppressions_count === undefined) {
+      row.snyk_suppressions_count = 0;
+    }
+  }
+
+  // Id assignment invariant (PKG-22 / test-gate spec §5a):
+  //   - Orchestrator assigns pkg-NNN to every adapter finding in this loop.
+  //   - Report writer may emit N extra canonical findings per Snyk entry for
+  //     licence violations (PKG-23). Those carry id = '{pkg-NNN}-lic' —
+  //     derived at emit time by _canonicalFindingsForAdapter, never
+  //     re-assigned here. Adapters never assign ids of any kind.
+  //
+  // Assign pkg-NNN ids AFTER scanning all targets (preserves target/ecosystem/workspace order)
+  const findings = [];
+  let counter = 1;
+  for (const rr of repo_results) {
+    for (const f of rr.findings) {
+      const id = 'pkg-' + String(counter).padStart(3, '0');
+      f.id = id;
+      findings.push(f);
+      counter += 1;
+    }
+  }
+
+  // Phase 153 PKG-27: apply threshold filter to top-level findings AND per-repo
+  // sub-arrays so the Summary table's per-row severity counts match.
+  const filteredFindings = _filterByThreshold(findings, effectiveThreshold);
+  for (const row of repo_results) {
+    if (Array.isArray(row.findings)) {
+      row.findings = _filterByThreshold(row.findings, effectiveThreshold);
+    }
+  }
+
+  // Phase 153 PKG-33: attach plan provenance to each remaining finding.
+  // Lookup is memoised per (repoDir, manifestPath, packageName) within this scan.
+  const provCache = new Map();
+  for (const f of filteredFindings) {
+    const repoEntry = targets.find(t => t.name === f.repo);
+    const repoDir = repoEntry ? repoEntry.dir : null;
+    const manifestPath = f.manifest_path || null;
+    const packageName = f.package_name || null;
+    const cacheKey = `${repoDir}\u0000${manifestPath}\u0000${packageName}`;
+    let prov;
+    if (provCache.has(cacheKey)) {
+      prov = provCache.get(cacheKey);
+    } else {
+      prov = provLookupFn({ repoDir, manifestPath, packageName });
+      provCache.set(cacheKey, prov);
+    }
+    f.introduced_in_commit = prov ? prov.commit : null;
+    f.introduced_in_plan = prov ? prov.plan : null;
+  }
+
+  return {
+    exit_code: 0,
+    tool_per_target,
+    repo_results,
+    findings: filteredFindings,
+    skipped,
+    diagnostics,
+    threshold_applied: effectiveThreshold,
+    // Phase 153 PKG-30/34: licence roster (always an array; empty when no Snyk roster emitted).
+    licence_roster: rosterAccumulator,
+    // UAT Bug 2: surface resolved snyk_org (config.local.json > config.json > null).
+    snyk_org: pkgCfg.snyk_org || null,
+  };
+}
+
+// ─── Public: cmdPackageScan (CLI entry) ───────────────────────────────────────
+
+/**
+ * Invoke `dgs-tools commit <msg> --files <path>` in a subprocess, or call the
+ * test-seam override if provided. Returns {status, stdout, stderr}.
+ */
+function _invokeCommit(cwd, message, filePath, overrideFn) {
+  if (typeof overrideFn === 'function') {
+    return overrideFn(message, filePath);
+  }
+  const dgsToolsPath = path.join(__dirname, '..', 'dgs-tools.cjs');
+  const result = spawnSync('node', [dgsToolsPath, 'commit', message, '--files', filePath], {
+    cwd,
+    encoding: 'utf-8',
+  });
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+/**
+ * CLI entry. Composes runScan -> writePackageScanReport -> atomic commit.
+ *
+ * Flow:
+ *   1. runScan(cwd, {}) -- catastrophic errors short-circuit with exit 2.
+ *   2. If raw, emit JSON result via output().
+ *   3. If scan exit_code !== 0 (e.g., tool_unavailable_on_pin): NO report
+ *      written, NO commit attempted; exit with scan's exit_code.
+ *   4. If scan exit_code === 0: writePackageScanReport(cwd, result, opts).
+ *      If write throws, emit diagnostic to stderr and exit 2.
+ *   5. _invokeCommit() stages + commits the report file. Commit failure is
+ *      NON-FATAL (report remains on disk; stderr notes the failure).
+ *   6. Emit `Wrote {path} ({n} findings, tool: {tool}).` to stdout (non-raw).
+ *   7. exit(scan's exit_code) — always 0 at this point (we short-circuited above).
+ */
+function cmdPackageScan(cwd, args, raw, opts) {
+  opts = opts || {};
+  // Test seam: opts._runScan lets tests inject a stubbed runScan (with
+  // detector/runner/snykAuth/checkToolOnPath stubs already pre-bound) without
+  // having to monkey-patch the module export.
+  const runScanFn = opts._runScan || runScan;
+
+  // Phase 153 PKG-27/28: parse CLI argv for --threshold, --repo,
+  // --include-dev-deps/--no-include-dev-deps, --json.
+  let parsed;
+  try {
+    parsed = _parseArgs(Array.isArray(args) ? args : []);
+  } catch (err) {
+    process.stderr.write((err && err.message ? err.message : String(err)) + '\n');
+    process.exit(2);
+    return;
+  }
+  const effectiveRaw = raw || parsed.raw || parsed.json;
+  const scanOpts = {
+    threshold: parsed.threshold,
+    only_repo: parsed.only_repo,
+    include_dev_dependencies: parsed.include_dev_dependencies,
+  };
+
+  let result;
+  try {
+    result = runScanFn(cwd, scanOpts);
+  } catch (err) {
+    result = {
+      exit_code: 2,
+      diagnostics: [{ kind: 'setup_error', message: err && err.message ? err.message : String(err) }],
+      findings: [],
+      repo_results: [],
+      tool_per_target: {},
+      skipped: [],
+    };
+  }
+
+  if (effectiveRaw) {
+    // Emit compact JSON to stdout without calling output() (which calls
+    // process.exit), so downstream composition (write report + commit) can
+    // still execute. Single-line form so callers can split on newlines.
+    process.stdout.write(JSON.stringify(result));
+    process.stdout.write('\n');
+  }
+
+  // Scan-level failure short-circuits before writing or committing.
+  if (result.exit_code !== 0) {
+    if (!effectiveRaw) {
+      const diag = (result.diagnostics && result.diagnostics[0]) || {};
+      const kind = diag.kind || 'unknown';
+      const hint = diag.hint ? ' — ' + diag.hint : (diag.message ? ' — ' + diag.message : '');
+      process.stderr.write(`Scan failed: ${kind}${hint}\n`);
+    }
+    process.exit(result.exit_code);
+  }
+
+  // Happy path: write the report.
+  let reportInfo;
+  try {
+    reportInfo = writePackageScanReport(cwd, result, opts);
+  } catch (err) {
+    if (!effectiveRaw) {
+      process.stderr.write(`Report generation failed: ${err && err.message ? err.message : String(err)}\n`);
+    }
+    process.exit(2);
+  }
+
+  const nFindings = reportInfo.n_findings;
+  const toolString = reportInfo.tool_string;
+  const reportPath = reportInfo.path;
+  const commitMsg = `scan(packages): ${toolString} report — ${nFindings} finding${nFindings === 1 ? '' : 's'}`;
+
+  const commitResult = _invokeCommit(cwd, commitMsg, reportPath, opts.commit);
+  if (commitResult && commitResult.status !== 0) {
+    if (!effectiveRaw) {
+      const stderrMsg = (commitResult.stderr || '').trim() || 'unknown error';
+      process.stderr.write(`Commit failed (report still on disk at ${reportPath}): ${stderrMsg}\n`);
+    }
+  }
+
+  if (!raw) {
+    const countPhrase = nFindings === 0
+      ? 'clean scan'
+      : `${nFindings} finding${nFindings === 1 ? '' : 's'}`;
+    process.stdout.write(`Wrote ${reportPath} (${countPhrase}, tool: ${toolString}).\n`);
+  }
+
+  process.exit(result.exit_code);
+}
+
+module.exports = {
+  cmdPackageScan,
+  runScan,
+  collectScanTargets,
+  selectTool,
+  resolveSnykAuth,
+  // Internal exports for test seam only:
+  _checkToolOnPath,
+  _invokeCommit,
+  NATIVE_TOOL_FOR_ECOSYSTEM,
+  ADAPTER_FOR_TOOL,
+  DEFAULTS,
+  // Phase 153 PKG-27/28 — CLI flag plumbing exported for unit tests.
+  _parseArgs,
+  _severityRank,
+  _filterByThreshold,
+  SEVERITY_RANK,
+  // Phase 153 PKG-32 — .snyk policy detection exported for unit tests.
+  _detectSnykPolicy,
+  // Re-export for test convenience.
+  _collapseSeverity,
+};