@ktpartners/dgs-platform 3.0.4 → 3.3.0

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

@@ -0,0 +1,1140 @@
+/**
+ * package-scan-report.cjs -- Phase 151 report writer for /dgs:package-scan
+ *
+ * Consumes Phase 150's frozen `runScan` result shape and emits a markdown
+ * report with YAML frontmatter (programmatic consumption) + a human-readable
+ * body. Chooses the report's on-disk location via a three-tier cascade:
+ * active phase -> active milestone -> project root with timestamp.
+ *
+ * Exports:
+ *   writePackageScanReport(cwd, runResult, opts) -- composes emit + render + resolve + write
+ *   _emitYamlFrontmatter(payload)                -- hand-rolled YAML emitter (round-trip-validated)
+ *   _parseEmittedYaml(text)                      -- minimal parser (subset the emitter produces)
+ *   _renderBody(runResult)                       -- pure markdown emitter
+ *   _resolveReportPath(cwd, opts)                -- cascade resolver
+ *
+ * Covers roadmap requirements: PKG-06, PKG-07, PKG-20, PKG-21.
+ *
+ * Pure module: no module-level state, no side effects except (a) the file
+ * write inside writePackageScanReport and (b) mkdirSync for the milestones/
+ * or project-root parent dir during path resolution (acceptable per research
+ * hard rule 7).
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { getPlanningRoot } = require('./paths.cjs');
+const { getLocalConfigPath } = require('./config.cjs');
+
+// ─── Canonical frontmatter constants ─────────────────────────────────────────
+// Every findings[] entry emitted by this module carries these two constant
+// fields so downstream consumers (Phase 152 skill plugin, Phase 153 gap
+// planner) can detect + route on them without re-parsing severity strings.
+//
+//   test_source: "package-scan"
+//   gap_type: "dependency-security"
+const CANONICAL_TEST_SOURCE = 'package-scan';
+const CANONICAL_GAP_TYPE = 'dependency-security';
+
+// ─── Severity / licence normalisation (PKG-22 / PKG-23) ──────────────────────
+// SEVERITY_MAP covers every raw severity string the six adapters emit. Keys
+// are lowercased at lookup time; the map's own keys are pre-lowercased. The
+// map resolves adapter dialects to exactly one canonical tier:
+// critical|high|medium|low. Unknown or null inputs collapse to medium (see
+// _collapseSeverity below) — a conservative default that prefers false
+// positives over silently dropping a finding.
+//
+// Tool dialects covered (via lowercased lookup):
+//   - Snyk:           critical | high | medium | low        (canonical tiers, pass-through)
+//   - Bundler-Audit:  High | Medium | Low                    (lowercases to canonical)
+//   - OSV:            CRITICAL | HIGH | MODERATE | MEDIUM | LOW   (database_specific.severity)
+//   - npm audit:      critical | high | moderate | low | info
+//   - pip-audit:      null (never emits severity)
+//   - govulncheck:    null (never emits severity)
+const SEVERITY_MAP = Object.freeze({
+  critical: 'critical',
+  high: 'high',
+  medium: 'medium',
+  low: 'low',
+  moderate: 'medium', // npm-audit + OSV MODERATE (lowered)
+  info: 'low',        // npm-audit info-level
+});
+
+// LICENCE_SEVERITY_MAP maps SPDX identifiers (lowercased) to the canonical
+// severity tier. Used by _mapLicenceToSeverity for licence-finding synthesis
+// when the Snyk adapter surfaces a `licence` field. Permissive licences (MIT,
+// Apache-2.0, BSD-*, ISC, etc.) are intentionally absent from the map — the
+// helper returns null for them and no licence finding is synthesised.
+const LICENCE_SEVERITY_MAP = Object.freeze({
+  'gpl-3.0': 'high',
+  'gpl-3.0-only': 'high',
+  'gpl-3.0-or-later': 'high',
+  'agpl-3.0': 'high',
+  'agpl-3.0-only': 'high',
+  'agpl-3.0-or-later': 'high',
+  'lgpl-2.1': 'medium',
+  'lgpl-2.1-only': 'medium',
+  'lgpl-2.1-or-later': 'medium',
+  'lgpl-3.0': 'medium',
+  'lgpl-3.0-only': 'medium',
+  'lgpl-3.0-or-later': 'medium',
+  'mpl-1.1': 'medium',
+  'mpl-2.0': 'medium',
+  // Phase 153 PKG-34: SSPL classified as restrictive (high).
+  'sspl-1.0': 'high',
+  'sspl-1.0-only': 'high',
+});
+
+// ─── YAML emitter ────────────────────────────────────────────────────────────
+
+const TOP_LEVEL_ORDER = Object.freeze([
+  // UAT Bug 2: snyk_org emitted between 'tool' and 'repos_scanned' so the
+  // resolved Snyk org UUID is auditable in every report frontmatter.
+  'type', 'date', 'tool', 'snyk_org', 'repos_scanned',
+  'critical', 'high', 'medium', 'low',
+  'duration', 'findings',
+]);
+
+const FINDING_FIELD_ORDER = Object.freeze([
+  'id', 'test_source', 'gap_type', 'severity', 'resource_id',
+  'repo', 'manifest_path', 'title', 'description', 'remediation',
+  'reference', 'cve', 'cvss', 'dependency_chain', 'chain_available',
+  'direct_or_transitive', 'tool',
+  // Phase 153 PKG-33: optional plan provenance fields.
+  'introduced_in_commit', 'introduced_in_plan',
+]);
+
+const STRING_FINDING_FIELDS = new Set([
+  'id', 'test_source', 'gap_type', 'severity', 'resource_id',
+  'repo', 'manifest_path', 'title', 'description', 'remediation',
+  'reference', 'cve', 'direct_or_transitive', 'tool',
+  // Phase 153 PKG-33: provenance fields are nullable strings.
+  'introduced_in_commit', 'introduced_in_plan',
+]);
+
+/**
+ * Emit a YAML string for a finding-array member. All non-null keys emit in
+ * FINDING_FIELD_ORDER. String scalars are double-quoted and escaped; newlines
+ * switch to block-scalar `|-` form. Null emits literal `null`; numbers/booleans
+ * unquoted. `dependency_chain` emits as either `null` or a nested block
+ * sequence. Throws on any disallowed value (function, circular, non-finding
+ * nested object).
+ */
+function _emitFindingEntry(entry, visited) {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error('Finding must be a non-null object');
+  }
+  if (visited.has(entry)) throw new Error('Circular reference in finding');
+  visited.add(entry);
+
+  // First field uses the `  - ` prefix; remaining indent is 4 spaces.
+  const lines = [];
+  let first = true;
+  for (const key of FINDING_FIELD_ORDER) {
+    if (!(key in entry)) continue;
+    const value = entry[key];
+    const indent = first ? '  - ' : '    ';
+    if (key === 'dependency_chain') {
+      if (value === null || value === undefined) {
+        lines.push(indent + 'dependency_chain: null');
+      } else if (Array.isArray(value)) {
+        if (value.length === 0) {
+          lines.push(indent + 'dependency_chain: []');
+        } else {
+          lines.push(indent + 'dependency_chain:');
+          for (const link of value) {
+            if (typeof link !== 'string') {
+              throw new Error('dependency_chain elements must be strings');
+            }
+            lines.push('      - ' + _emitStringScalarInline(link));
+          }
+        }
+      } else {
+        throw new Error('dependency_chain must be null or an array');
+      }
+      first = false;
+      continue;
+    }
+    if (STRING_FINDING_FIELDS.has(key)) {
+      if (value === null || value === undefined) {
+        lines.push(indent + key + ': null');
+      } else if (typeof value === 'string') {
+        const rendered = _emitStringScalar(value, first ? 4 : 4);
+        if (rendered.block) {
+          lines.push(indent + key + ': |-');
+          for (const bl of rendered.lines) {
+            lines.push('      ' + bl);
+          }
+        } else {
+          lines.push(indent + key + ': ' + rendered.inline);
+        }
+      } else {
+        throw new Error('Field ' + key + ' must be a string or null, got ' + typeof value);
+      }
+      first = false;
+      continue;
+    }
+    // Number / boolean fields (cvss, chain_available).
+    if (key === 'cvss') {
+      if (value === null || value === undefined) {
+        lines.push(indent + 'cvss: null');
+      } else if (typeof value === 'number' && Number.isFinite(value)) {
+        lines.push(indent + 'cvss: ' + String(value));
+      } else {
+        throw new Error('cvss must be number or null, got ' + typeof value);
+      }
+    } else if (key === 'chain_available') {
+      if (typeof value !== 'boolean') {
+        throw new Error('chain_available must be boolean, got ' + typeof value);
+      }
+      lines.push(indent + 'chain_available: ' + String(value));
+    }
+    first = false;
+  }
+  visited.delete(entry);
+  return lines.join('\n');
+}
+
+/**
+ * Emit a string scalar inline (double-quoted). For use inside block-sequence
+ * entries where the value is known to be a single-line string.
+ */
+function _emitStringScalarInline(value) {
+  const rendered = _emitStringScalar(value, 4);
+  if (rendered.block) {
+    // Extremely unusual for a chain element; block form not supported here.
+    throw new Error('Block-scalar form unsupported in inline string context');
+  }
+  return rendered.inline;
+}
+
+/**
+ * Emit a string scalar. Returns either `{block: false, inline: '"..."'}` for
+ * single-line strings (double-quoted, with `"` and `\` escaped) or
+ * `{block: true, lines: ['line1', 'line2', ...]}` for multi-line strings
+ * (caller writes `|-` header + 2-space further indent).
+ */
+function _emitStringScalar(value) {
+  const s = String(value);
+  if (s.indexOf('\n') === -1) {
+    let escaped = '';
+    for (const ch of s) {
+      if (ch === '\\') escaped += '\\\\';
+      else if (ch === '"') escaped += '\\"';
+      else escaped += ch;
+    }
+    return { block: false, inline: '"' + escaped + '"' };
+  }
+  const rawLines = s.split('\n');
+  return { block: true, lines: rawLines };
+}
+
+/**
+ * Emit YAML frontmatter for the full payload (top-level fields + findings[]).
+ * Performs round-trip validation after emitting and throws if the parsed
+ * output does not deep-equal the input payload.
+ */
+function _emitYamlFrontmatter(payload) {
+  if (!payload || typeof payload !== 'object') {
+    throw new Error('Frontmatter payload must be a non-null object');
+  }
+  const lines = ['---'];
+  for (const key of TOP_LEVEL_ORDER) {
+    if (!(key in payload)) continue;
+    const value = payload[key];
+    if (key === 'findings') {
+      if (!Array.isArray(value)) {
+        throw new Error('findings must be an array');
+      }
+      if (value.length === 0) {
+        lines.push('findings: []');
+      } else {
+        lines.push('findings:');
+        const visited = new WeakSet();
+        for (const entry of value) {
+          lines.push(_emitFindingEntry(entry, visited));
+        }
+      }
+      continue;
+    }
+    if (value === null || value === undefined) {
+      lines.push(key + ': null');
+      continue;
+    }
+    if (typeof value === 'string') {
+      const rendered = _emitStringScalar(value);
+      if (rendered.block) {
+        lines.push(key + ': |-');
+        for (const bl of rendered.lines) {
+          lines.push('  ' + bl);
+        }
+      } else {
+        lines.push(key + ': ' + rendered.inline);
+      }
+      continue;
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      lines.push(key + ': ' + String(value));
+      continue;
+    }
+    if (typeof value === 'boolean') {
+      lines.push(key + ': ' + String(value));
+      continue;
+    }
+    if (typeof value === 'function') {
+      throw new Error('Function values are not allowed in frontmatter payload (field: ' + key + ')');
+    }
+    if (typeof value === 'object') {
+      throw new Error('Unsupported nested object for field: ' + key);
+    }
+    throw new Error('Unsupported value type ' + typeof value + ' for field: ' + key);
+  }
+  lines.push('---');
+  const emitted = lines.join('\n') + '\n';
+
+  // Round-trip validation
+  let parsed;
+  try {
+    parsed = _parseEmittedYaml(emitted);
+  } catch (err) {
+    throw new Error('YAML emitter round-trip failed: parse error — ' + (err && err.message ? err.message : String(err)));
+  }
+  if (!_deepEqual(parsed, payload)) {
+    throw new Error('YAML emitter round-trip failed: parsed output does not match input payload');
+  }
+  return emitted;
+}
+
+// ─── YAML parser (minimal, matches emitter subset) ───────────────────────────
+
+/**
+ * Parse the YAML subset produced by _emitYamlFrontmatter. Handles:
+ *   - top-level `key: <scalar>` with scalars being double-quoted strings,
+ *     `null`, integers, floats, booleans, or `[]` (empty sequence).
+ *   - block-scalar `|-` with 2-space-indented content lines.
+ *   - `findings:` header followed by block-sequence entries (`  - key: value`
+ *     then `    key2: value2` or `    key2: |-\n      line1\n      line2`).
+ */
+function _parseEmittedYaml(text) {
+  if (typeof text !== 'string') throw new Error('text must be a string');
+  // Strip leading / trailing --- fences.
+  let body = text;
+  if (body.startsWith('---\n')) body = body.slice(4);
+  const closeIdx = body.indexOf('\n---');
+  if (closeIdx !== -1) body = body.slice(0, closeIdx);
+  const rawLines = body.split('\n');
+  // Remove trailing empty line if present.
+  if (rawLines.length > 0 && rawLines[rawLines.length - 1] === '') rawLines.pop();
+
+  const out = {};
+  let i = 0;
+  while (i < rawLines.length) {
+    const line = rawLines[i];
+    // Top-level lines: no leading whitespace.
+    if (/^[A-Za-z_]/.test(line)) {
+      const colonIdx = line.indexOf(':');
+      if (colonIdx === -1) throw new Error('Malformed line: ' + line);
+      const key = line.slice(0, colonIdx);
+      const rest = line.slice(colonIdx + 1);
+      if (key === 'findings') {
+        // Sequence
+        if (rest.trim() === '[]') {
+          out.findings = [];
+          i += 1;
+          continue;
+        }
+        if (rest.trim() !== '') {
+          throw new Error('findings: expected [] or block sequence, got ' + rest);
+        }
+        // Parse block sequence entries
+        const entries = [];
+        i += 1;
+        while (i < rawLines.length && rawLines[i].startsWith('  -')) {
+          const entry = {};
+          // First line of entry
+          const firstLine = rawLines[i];
+          const firstRest = firstLine.slice(4); // strip "  - "
+          const fcolon = firstRest.indexOf(':');
+          if (fcolon === -1) throw new Error('Malformed entry first line: ' + firstLine);
+          const fkey = firstRest.slice(0, fcolon);
+          const fvalRaw = firstRest.slice(fcolon + 1);
+          const firstResult = _parseScalarOrBlock(fvalRaw, rawLines, i + 1, '      ');
+          entry[fkey] = firstResult.value;
+          i = firstResult.nextIndex;
+          // Remaining lines for this entry start with "    " (4 spaces) and are
+          // not the next sequence entry.
+          while (i < rawLines.length && rawLines[i].startsWith('    ') && !rawLines[i].startsWith('  - ')) {
+            const l = rawLines[i];
+            const inner = l.slice(4);
+            if (inner.startsWith('- ')) {
+              // Part of a nested sequence handled by _parseScalarOrBlock earlier.
+              i += 1;
+              continue;
+            }
+            const ccolon = inner.indexOf(':');
+            if (ccolon === -1) {
+              i += 1;
+              continue;
+            }
+            const ckey = inner.slice(0, ccolon);
+            const cvalRaw = inner.slice(ccolon + 1);
+            const parsed = _parseScalarOrBlock(cvalRaw, rawLines, i + 1, '      ');
+            entry[ckey] = parsed.value;
+            i = parsed.nextIndex;
+          }
+          entries.push(entry);
+        }
+        out.findings = entries;
+        continue;
+      }
+      // Regular top-level key
+      const parsed = _parseScalarOrBlock(rest, rawLines, i + 1, '  ');
+      out[key] = parsed.value;
+      i = parsed.nextIndex;
+      continue;
+    }
+    // Unexpected line structure; skip.
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * Parse a scalar from `rest` (the slice after `key:`). If rest starts with
+ * ` |-`, collect indented continuation lines at `blockIndent` as a multi-line
+ * string. Returns `{value, nextIndex}` where nextIndex is the index of the
+ * first line AFTER this value's lines.
+ */
+function _parseScalarOrBlock(rest, rawLines, continueIdx, blockIndent) {
+  const trimmed = rest.trim();
+  if (trimmed === '|-') {
+    const bodyLines = [];
+    let i = continueIdx;
+    while (i < rawLines.length && rawLines[i].startsWith(blockIndent)) {
+      bodyLines.push(rawLines[i].slice(blockIndent.length));
+      i += 1;
+    }
+    return { value: bodyLines.join('\n'), nextIndex: i };
+  }
+  if (trimmed === '') {
+    // Possibly a nested sequence (e.g., dependency_chain:)
+    const seqIndent = blockIndent;
+    const seq = [];
+    let i = continueIdx;
+    while (i < rawLines.length && rawLines[i].startsWith(seqIndent + '- ')) {
+      const itemRaw = rawLines[i].slice(seqIndent.length + 2);
+      seq.push(_parseInlineScalar(itemRaw));
+      i += 1;
+    }
+    return { value: seq, nextIndex: i };
+  }
+  if (trimmed === '[]') {
+    return { value: [], nextIndex: continueIdx };
+  }
+  return { value: _parseInlineScalar(trimmed), nextIndex: continueIdx };
+}
+
+function _parseInlineScalar(s) {
+  if (s === 'null') return null;
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    // unescape
+    const inner = s.slice(1, -1);
+    let out = '';
+    for (let i = 0; i < inner.length; i += 1) {
+      const ch = inner[i];
+      if (ch === '\\' && i + 1 < inner.length) {
+        const next = inner[i + 1];
+        if (next === '"') { out += '"'; i += 1; continue; }
+        if (next === '\\') { out += '\\'; i += 1; continue; }
+        out += ch;
+      } else {
+        out += ch;
+      }
+    }
+    return out;
+  }
+  // Number?
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  if (/^-?\d+\.\d+$/.test(s)) return parseFloat(s);
+  // Fallthrough: treat as bare string (should not happen for emitter output).
+  return s;
+}
+
+// ─── Deep equality (used for round-trip validation) ──────────────────────────
+
+function _deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== 'object') return a === b;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) {
+      if (!_deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(b)) return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, k)) return false;
+    if (!_deepEqual(a[k], b[k])) return false;
+  }
+  return true;
+}
+
+// ─── Body renderer ───────────────────────────────────────────────────────────
+
+function _statusLabel(outcome) {
+  switch (outcome) {
+    case 'ok': return 'ok';
+    case 'no_manifests': return 'skipped (no manifests)';
+    case 'tool_failure': return 'tool failure';
+    case 'timeout': return 'timeout';
+    case 'no_native_tool_for_ecosystem': return 'no native tool';
+    case 'skipped': return 'skipped';
+    default: return outcome || 'unknown';
+  }
+}
+
+function _collapseSeverity(raw) {
+  if (raw === null || raw === undefined) return 'medium';
+  const key = String(raw).toLowerCase();
+  return Object.prototype.hasOwnProperty.call(SEVERITY_MAP, key) ? SEVERITY_MAP[key] : 'medium';
+}
+
+/**
+ * Map a raw SPDX licence identifier to a canonical severity tier. Returns null
+ * for permissive licences (MIT, Apache-2.0, BSD-*, ISC, etc.) or when the
+ * licence field is null/undefined. Used by _canonicalFindingsForAdapter to
+ * decide whether a Snyk finding should emit an extra licence-violation
+ * finding (PKG-23).
+ */
+function _mapLicenceToSeverity(licence) {
+  if (licence === null || licence === undefined) return null;
+  const key = String(licence).toLowerCase();
+  return Object.prototype.hasOwnProperty.call(LICENCE_SEVERITY_MAP, key)
+    ? LICENCE_SEVERITY_MAP[key]
+    : null;
+}
+
+function _renderBody(runResult) {
+  const lines = ['# Package Scan Report', ''];
+  const rr = Array.isArray(runResult.repo_results) ? runResult.repo_results : [];
+  const findings = Array.isArray(runResult.findings) ? runResult.findings : [];
+  const diagnostics = Array.isArray(runResult.diagnostics) ? runResult.diagnostics : [];
+
+  // Empty repo_results case.
+  if (rr.length === 0) {
+    lines.push('## No targets scanned', '');
+    if (diagnostics.length > 0) {
+      for (const d of diagnostics) {
+        const msg = d.message || d.hint || d.kind || 'unknown diagnostic';
+        lines.push(`- **${d.kind || 'diagnostic'}:** ${msg}`);
+      }
+    } else {
+      lines.push('- No repos registered and product root has no manifests.');
+    }
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  // Summary table — Phase 153 PKG-32 adds the ".snyk policy" column.
+  lines.push('## Summary', '');
+  lines.push('| Repo | Ecosystem | Tool | .snyk policy | Critical | High | Medium | Low | Status |');
+  lines.push('|------|-----------|------|--------------|----------|------|--------|-----|--------|');
+  // Group findings by (repo, ecosystem) so we know per-row severity counts.
+  for (const row of rr) {
+    const repo = row.repo;
+    const eco = row.ecosystem || '—';
+    const tool = row.tool_used || '—';
+    const snykPolicy = row.has_snyk_policy === true ? 'yes'
+      : row.has_snyk_policy === false ? 'no' : '—';
+    const isOk = row.outcome === 'ok';
+    let critical = '—', high = '—', medium = '—', low = '—';
+    if (isOk) {
+      let c = 0, h = 0, m = 0, l = 0;
+      const rowFindings = Array.isArray(row.findings) ? row.findings : [];
+      for (const f of rowFindings) {
+        const s = _collapseSeverity(f.severity);
+        if (s === 'critical') c += 1;
+        else if (s === 'high') h += 1;
+        else if (s === 'medium') m += 1;
+        else if (s === 'low') l += 1;
+      }
+      critical = String(c); high = String(h); medium = String(m); low = String(l);
+    }
+    lines.push(`| ${repo} | ${eco} | ${tool} | ${snykPolicy} | ${critical} | ${high} | ${medium} | ${low} | ${_statusLabel(row.outcome)} |`);
+  }
+  lines.push('');
+
+  // Phase 153 PKG-32: per-repo suppression notes (when .snyk policy applied AND count > 0).
+  for (const row of rr) {
+    if (row.has_snyk_policy === true
+        && typeof row.snyk_suppressions_count === 'number'
+        && row.snyk_suppressions_count > 0) {
+      const n = row.snyk_suppressions_count;
+      const word = n === 1 ? 'vulnerability' : 'vulnerabilities';
+      lines.push(`> ${row.repo}: .snyk policy applied: ${n} ${word} suppressed.`);
+      lines.push('');
+    }
+  }
+
+  // Phase 153 PKG-30/34: Licence Compliance section (always rendered).
+  const aggToolForLicence = _aggregateToolString(runResult);
+  const licenceRoster = Array.isArray(runResult.licence_roster) ? runResult.licence_roster : [];
+  if (findings.length > 0 || licenceRoster.length > 0 || aggToolForLicence !== 'none') {
+    lines.push(_renderLicenceComplianceSection({ tool_agg: aggToolForLicence, licence_roster: licenceRoster }));
+  }
+
+  // Phase 153 PKG-35: cross-repo dedup (body-only; YAML findings stay one-per-repo).
+  const groups = _groupFindingsByPackageVersion(findings);
+  const crossRepoSection = _renderCrossRepoSummary(groups);
+  if (crossRepoSection) lines.push(crossRepoSection);
+  // Phase 153 PKG-36: dependency version overlap.
+  const overlaps = _detectVersionOverlaps(findings, runResult.licence_roster);
+  const overlapSection = _renderVersionOverlap(overlaps);
+  if (overlapSection) lines.push(overlapSection);
+
+  // Severity sections (only when findings exist)
+  if (findings.length === 0) {
+    lines.push('## Findings', '');
+    lines.push(`No vulnerabilities found across ${rr.length} scanned repos.`);
+    lines.push('');
+  } else {
+    const severityOrder = ['critical', 'high', 'medium', 'low'];
+    const byTier = { critical: [], high: [], medium: [], low: [] };
+    for (const f of findings) {
+      const s = _collapseSeverity(f.severity);
+      byTier[s].push(f);
+    }
+    const titleCase = { critical: 'Critical', high: 'High', medium: 'Medium', low: 'Low' };
+    for (const tier of severityOrder) {
+      const tierFindings = byTier[tier];
+      if (tierFindings.length === 0) continue;
+      lines.push(`## ${titleCase[tier]}`, '');
+      for (const f of tierFindings) {
+        const title = (f.vulnerability && f.vulnerability.title) || 'Untitled';
+        const pkg = f.package_name || 'unknown';
+        const ver = f.installed_version || '';
+        const headerSuffix = ver ? `${pkg}@${ver}` : pkg;
+        lines.push(`### ${f.repo}: ${headerSuffix} — ${title}`);
+        const cve = (f.vulnerability && f.vulnerability.cve) || null;
+        const cvss = (typeof f.cvss_score === 'number') ? f.cvss_score : null;
+        const tool = f.tool || 'unknown';
+        const manifest = f.manifest_path ? '`' + f.manifest_path + '`' : 'repo root';
+        const direct = f.direct_or_transitive || 'unknown';
+        let chainLine;
+        if (f.chain_available && Array.isArray(f.dependency_chain) && f.dependency_chain.length > 0) {
+          chainLine = f.dependency_chain.map(_chainEntryToString).join(' → ');
+        } else {
+          chainLine = 'unavailable (chain_available: false — recommend Snyk for full chain analysis)';
+        }
+        const fix = f.remediation || 'no upgrade path available — manual review required';
+        const ref = (f.vulnerability && f.vulnerability.reference_url) || 'unavailable';
+        lines.push(`- **CVE:** ${cve || 'unavailable'}`);
+        lines.push(`- **CVSS:** ${cvss !== null ? String(cvss) : 'unavailable'}`);
+        lines.push(`- **Tool:** ${tool}`);
+        lines.push(`- **Manifest:** ${manifest}`);
+        lines.push(`- **Direct/Transitive:** ${direct}`);
+        lines.push(`- **Dependency chain:** ${chainLine}`);
+        lines.push(`- **Fix:** ${fix}`);
+        lines.push(`- **Reference:** ${ref}`);
+        // Phase 153 PKG-33: provenance line.
+        let introLine;
+        if (f.introduced_in_commit && f.introduced_in_plan) {
+          introLine = `- **Introduced in:** commit ${f.introduced_in_commit} (plan ${f.introduced_in_plan})`;
+        } else if (f.introduced_in_commit) {
+          introLine = `- **Introduced in:** commit ${f.introduced_in_commit}`;
+        } else {
+          introLine = `- **Introduced in:** unknown`;
+        }
+        lines.push(introLine);
+        const descr = f.vulnerability && f.vulnerability.description;
+        if (descr !== null && descr !== undefined && String(descr).length > 0) {
+          lines.push('');
+          for (const dl of String(descr).split('\n')) {
+            lines.push('> ' + dl);
+          }
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  // Diagnostics appendix (only when findings exist + diagnostics populated)
+  if (findings.length > 0 && diagnostics.length > 0) {
+    lines.push('## Diagnostics', '');
+    for (const d of diagnostics) {
+      const msg = d.message || d.hint || d.kind || 'unknown';
+      lines.push(`- **${d.kind || 'diagnostic'}:** ${msg}`);
+    }
+    lines.push('');
+  }
+
+  // Pitfall 17 one-line warning (when aggregated tool is snyk).
+  const aggTool = _aggregateToolString(runResult);
+  if (aggTool === 'snyk') {
+    lines.push('> Note: scan output may include package names and tool URLs. Review before pushing.');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Phase 153 Plan 04: Cross-repo dedup + version overlap (PKG-35, PKG-36) ─
+
+function _severityRankLocal(tier) {
+  const RANK = { critical: 4, high: 3, medium: 2, low: 1 };
+  if (tier === null || tier === undefined) return 0;
+  return RANK[String(tier).toLowerCase()] || 0;
+}
+
+function _groupFindingsByPackageVersion(findings) {
+  if (!Array.isArray(findings)) return [];
+  const map = new Map();
+  for (const f of findings) {
+    const pkg = f.package_name || 'unknown';
+    const ver = f.installed_version || '';
+    const vuln = f.vulnerability || {};
+    const cveKey = vuln.cve || null;
+    const titleKey = vuln.title || '';
+    const key = `${pkg}\u0000${ver}\u0000${cveKey || titleKey}`;
+    if (!map.has(key)) {
+      map.set(key, {
+        package_name: pkg,
+        installed_version: ver,
+        cve: cveKey,
+        title: vuln.title || '',
+        severity: _collapseSeverity(f.severity),
+        repos: [],
+      });
+    }
+    const group = map.get(key);
+    if (!group.repos.includes(f.repo)) group.repos.push(f.repo);
+    const prevRank = _severityRankLocal(group.severity);
+    const curRank = _severityRankLocal(_collapseSeverity(f.severity));
+    if (curRank > prevRank) group.severity = _collapseSeverity(f.severity);
+  }
+  const out = Array.from(map.values());
+  out.sort((a, b) => {
+    const sa = _severityRankLocal(a.severity);
+    const sb = _severityRankLocal(b.severity);
+    if (sa !== sb) return sb - sa;
+    if (a.repos.length !== b.repos.length) return b.repos.length - a.repos.length;
+    return String(a.package_name).localeCompare(String(b.package_name));
+  });
+  return out;
+}
+
+function _detectVersionOverlaps(findings, licenceRoster) {
+  const fArr = Array.isArray(findings) ? findings : [];
+  const rArr = Array.isArray(licenceRoster) ? licenceRoster : [];
+  const byPkg = new Map(); // package_name -> Map(version -> Set(repo))
+  const addEntry = (pkg, ver, repo) => {
+    if (!pkg || ver === undefined || ver === null || ver === '') return;
+    if (!byPkg.has(pkg)) byPkg.set(pkg, new Map());
+    const versionMap = byPkg.get(pkg);
+    if (!versionMap.has(ver)) versionMap.set(ver, new Set());
+    if (repo) versionMap.get(ver).add(repo);
+  };
+  for (const f of fArr) addEntry(f.package_name, f.installed_version, f.repo);
+  for (const e of rArr) addEntry(e.package_name, e.installed_version, e.repo);
+  const out = [];
+  for (const [pkg, versionMap] of byPkg.entries()) {
+    if (versionMap.size < 2) continue;
+    const versions = Array.from(versionMap.keys()).sort();
+    const repos = {};
+    for (const v of versions) repos[v] = Array.from(versionMap.get(v)).sort();
+    out.push({ package_name: pkg, versions, repos });
+  }
+  out.sort((a, b) => String(a.package_name).localeCompare(String(b.package_name)));
+  return out;
+}
+
+function _renderCrossRepoSummary(groups) {
+  const multi = Array.isArray(groups) ? groups.filter(g => g.repos && g.repos.length >= 2) : [];
+  if (multi.length === 0) return '';
+  const lines = ['## Cross-Repo Summary', ''];
+  lines.push('| Package | Version | CVE | Severity | Repos |');
+  lines.push('|---------|---------|-----|----------|-------|');
+  for (const g of multi) {
+    const cve = g.cve || '—';
+    const repos = g.repos.slice().sort().join(', ');
+    lines.push(`| ${g.package_name} | ${g.installed_version || '—'} | ${cve} | ${g.severity} | ${repos} |`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function _renderVersionOverlap(overlaps) {
+  const arr = Array.isArray(overlaps) ? overlaps : [];
+  if (arr.length === 0) return '';
+  const lines = ['## Dependency Overlap', ''];
+  lines.push('| Package | Versions | Repos |');
+  lines.push('|---------|----------|-------|');
+  for (const o of arr) {
+    const versions = o.versions.join(', ');
+    const reposParts = [];
+    for (const v of o.versions) {
+      const repos = (o.repos && o.repos[v]) ? o.repos[v].join(', ') : '';
+      reposParts.push(`${v}: ${repos}`);
+    }
+    lines.push(`| ${o.package_name} | ${versions} | ${reposParts.join(' / ')} |`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ─── Phase 153 Plan 03: Licence Compliance section (PKG-30, PKG-34) ─────────
+
+/**
+ * PKG-30, PKG-34: render the dedicated Licence Compliance section.
+ * @param {{ tool_agg: string|null, licence_roster: Array|null }} args
+ * @returns {string} Markdown fragment ending with a blank line.
+ */
+function _renderLicenceComplianceSection(args) {
+  const lines = ['## Licence Compliance', ''];
+  const tool = args && args.tool_agg;
+  const roster = (args && Array.isArray(args.licence_roster)) ? args.licence_roster : [];
+  if (tool !== 'snyk') {
+    // Non-snyk (or no tool aggregated) — suggest Snyk for licence coverage.
+    lines.push('> Licence scan incomplete -- use Snyk for full coverage.');
+    lines.push('');
+    return lines.join('\n');
+  }
+  if (roster.length === 0) {
+    // UAT Bug 3: Snyk IS the tool but roster is empty. This is NOT
+    // "incomplete coverage" — the scan ran and surfaced no restrictive
+    // licences. Point the user at Snyk org-level licence policy configuration
+    // for expanded scope rather than repeating the non-snyk "install Snyk"
+    // prompt, which was misleading during live UAT.
+    lines.push('> Snyk licence scan completed; no restrictive licences flagged.');
+    lines.push('> To expand licence coverage, configure org-level licence policies at https://app.snyk.io/org/licenses.');
+    lines.push('');
+    return lines.join('\n');
+  }
+  lines.push('| Package | Version | Repo | Licence | Flag |');
+  lines.push('|---------|---------|------|---------|------|');
+  // Deterministic ordering: restrictive first, copyleft next, permissive last; secondary by package name.
+  const sorted = roster.slice().sort((a, b) => {
+    const fa = _licenceRosterFlag(a.licence);
+    const fb = _licenceRosterFlag(b.licence);
+    const rank = (flag) => flag === 'RESTRICTIVE' ? 2 : (flag === 'copyleft' ? 1 : 0);
+    if (rank(fb) !== rank(fa)) return rank(fb) - rank(fa);
+    return String(a.package_name).localeCompare(String(b.package_name));
+  });
+  for (const e of sorted) {
+    const flag = _licenceRosterFlag(e.licence);
+    const licence = e.licence === null || e.licence === undefined ? 'unknown' : String(e.licence);
+    lines.push(`| ${e.package_name} | ${e.installed_version} | ${e.repo || '—'} | ${licence} | ${flag} |`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+function _licenceRosterFlag(licence) {
+  if (licence === null || licence === undefined) return '';
+  const key = String(licence).toLowerCase();
+  if (/^gpl[-]?/.test(key) || /^agpl[-]?/.test(key) || /^sspl[-]?/.test(key)) return 'RESTRICTIVE';
+  if (/^lgpl[-]?/.test(key) || /^mpl[-]?/.test(key)) return 'copyleft';
+  return '';
+}
+
+// ─── Path resolution ─────────────────────────────────────────────────────────
+
+function _pad2(n) { return String(n).padStart(2, '0'); }
+
+function _formatTimestamp(dateObj) {
+  const y = dateObj.getUTCFullYear();
+  const mo = _pad2(dateObj.getUTCMonth() + 1);
+  const d = _pad2(dateObj.getUTCDate());
+  const hh = _pad2(dateObj.getUTCHours());
+  const mm = _pad2(dateObj.getUTCMinutes());
+  return `${y}-${mo}-${d}-${hh}${mm}`;
+}
+
+function _resolveReportPath(cwd, opts) {
+  opts = opts || {};
+  const planningRoot = getPlanningRoot(cwd);
+  let activeContext = null;
+  try {
+    const localPath = getLocalConfigPath(cwd);
+    if (fs.existsSync(localPath)) {
+      const local = JSON.parse(fs.readFileSync(localPath, 'utf-8'));
+      activeContext = (local.execution && local.execution.active_context) || null;
+    }
+  } catch {
+    activeContext = null;
+  }
+
+  if (typeof activeContext === 'string' && activeContext.length > 0) {
+    // Tier 1: active phase. Look for a projects/*/phases/ directory whose
+    // basename matches activeContext (or whose number prefix matches).
+    const projectsDir = path.join(planningRoot, 'projects');
+    if (fs.existsSync(projectsDir) && fs.statSync(projectsDir).isDirectory()) {
+      const projects = fs.readdirSync(projectsDir, { withFileTypes: true });
+      for (const pEnt of projects) {
+        if (!pEnt.isDirectory()) continue;
+        const phasesDir = path.join(projectsDir, pEnt.name, 'phases');
+        if (!fs.existsSync(phasesDir)) continue;
+        const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+        for (const phEnt of phaseEntries) {
+          if (!phEnt.isDirectory()) continue;
+          if (phEnt.name === activeContext) {
+            const m = phEnt.name.match(/^(\d+)/);
+            const prefix = m ? m[1] : phEnt.name;
+            return path.join(phasesDir, phEnt.name, prefix + '-PACKAGE-SCAN.md');
+          }
+        }
+      }
+    }
+    // Tier 2: milestone slug (e.g., `v23.1`, `v2.0`, etc.).
+    if (/^v\d+(\.\d+)?$/.test(activeContext)) {
+      const milestonesDir = path.join(planningRoot, 'milestones');
+      fs.mkdirSync(milestonesDir, { recursive: true });
+      return path.join(milestonesDir, activeContext + '-PACKAGE-SCAN.md');
+    }
+    // Tier 2b: activeContext is a worktree slug whose entry carries a milestone_version.
+    // Enables `package-scan` to land reports under `milestones/<version>-PACKAGE-SCAN.md`
+    // when the active context is a milestone worktree (e.g. `package-dependency-scanning`).
+    try {
+      const localPath2 = getLocalConfigPath(cwd);
+      if (fs.existsSync(localPath2)) {
+        const local2 = JSON.parse(fs.readFileSync(localPath2, 'utf-8'));
+        const currentProject = local2.current_project;
+        const wt = currentProject
+          && local2.projects
+          && local2.projects[currentProject]
+          && local2.projects[currentProject].worktrees
+          && local2.projects[currentProject].worktrees[activeContext];
+        if (wt
+          && wt.type === 'milestone'
+          && typeof wt.milestone_version === 'string'
+          && /^v\d+(\.\d+)?$/.test(wt.milestone_version)) {
+          const milestonesDir = path.join(planningRoot, 'milestones');
+          fs.mkdirSync(milestonesDir, { recursive: true });
+          return path.join(milestonesDir, wt.milestone_version + '-PACKAGE-SCAN.md');
+        }
+      }
+    } catch { /* fall through to tier 3 */ }
+    // Tier 2 fallback: active_context did not match a phase dir, but is not a
+    // milestone-slug pattern either. Fall through to tier 3.
+  }
+  // Tier 3: project-root timestamped.
+  const now = (opts.now ? opts.now() : new Date());
+  const stamp = _formatTimestamp(now instanceof Date ? now : new Date(now));
+  return path.join(planningRoot, `PACKAGE-SCAN-${stamp}.md`);
+}
+
+// ─── Composition helpers ─────────────────────────────────────────────────────
+
+function _aggregateToolString(runResult) {
+  const tools = new Set();
+  let hasNull = false;
+  const rr = Array.isArray(runResult.repo_results) ? runResult.repo_results : [];
+  for (const row of rr) {
+    if (row.tool_used === null || row.tool_used === undefined) {
+      hasNull = true;
+    } else {
+      tools.add(row.tool_used);
+    }
+  }
+  if (tools.size === 0) return 'none';
+  if (tools.size === 1) return Array.from(tools)[0];
+  return 'mixed';
+}
+
+function _countSeverity(findings, tier) {
+  let n = 0;
+  for (const f of findings) {
+    if (_collapseSeverity(f.severity) === tier) n += 1;
+  }
+  return n;
+}
+
+/**
+ * Normalise a dependency_chain entry to a string. Adapter output may use either
+ * plain strings (e.g., from govulncheck) or `{name, version}` objects (Snyk
+ * _parseSnykFromEntry). Non-string entries render as `name@version` or just
+ * `name` if version is empty.
+ */
+function _chainEntryToString(entry) {
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object') {
+    const name = entry.name || entry.package || '';
+    const ver = entry.version || '';
+    return ver ? `${name}@${ver}` : name;
+  }
+  return String(entry);
+}
+
+function _normaliseChain(chain) {
+  if (chain === null || chain === undefined) return null;
+  if (!Array.isArray(chain)) return null;
+  return chain.map(_chainEntryToString);
+}
+
+function _mapAdapterFindingToCanonical(f) {
+  const pkg = f.package_name || '';
+  const ver = f.installed_version || '';
+  const resource_id = ver ? `${pkg}@${ver}` : pkg;
+  const vuln = f.vulnerability || {};
+  const severity = _collapseSeverity(f.severity);
+  return {
+    id: f.id,
+    test_source: CANONICAL_TEST_SOURCE,
+    gap_type: CANONICAL_GAP_TYPE,
+    severity,
+    resource_id,
+    repo: f.repo,
+    manifest_path: f.manifest_path === undefined ? null : f.manifest_path,
+    title: vuln.title || '',
+    description: vuln.description === undefined ? null : vuln.description,
+    remediation: f.remediation === undefined ? null : f.remediation,
+    reference: vuln.reference_url === undefined ? null : vuln.reference_url,
+    cve: vuln.cve === undefined ? null : vuln.cve,
+    cvss: typeof f.cvss_score === 'number' ? f.cvss_score : null,
+    dependency_chain: _normaliseChain(f.dependency_chain === undefined ? null : f.dependency_chain),
+    chain_available: !!f.chain_available,
+    direct_or_transitive: f.direct_or_transitive === undefined ? null : f.direct_or_transitive,
+    tool: f.tool,
+    // Phase 153 PKG-33: plan provenance (optional; null when unknown).
+    introduced_in_commit: f.introduced_in_commit === undefined ? null : f.introduced_in_commit,
+    introduced_in_plan: f.introduced_in_plan === undefined ? null : f.introduced_in_plan,
+  };
+}
+
+/**
+ * Map one adapter finding to 1 or 2 canonical findings.
+ *
+ *   - Always emits the security finding (unchanged shape from _mapAdapterFindingToCanonical).
+ *   - When f.tool === 'snyk' AND f.licence maps to a non-null canonical tier,
+ *     appends a licence finding with gap_type: 'dependency-licence'. The
+ *     licence finding's id is `${security.id}-lic` (derived, collision-free)
+ *     when the security finding has a non-null id, else null.
+ *
+ * Licence synthesis is Snyk-only on purpose: PKG-30 pins licence detection to
+ * Snyk's pass-through licence field — other tools don't reliably emit licence
+ * data. The future test-gate gap planner correlates licence + security
+ * findings on `resource_id` (same package@version for both halves).
+ */
+function _canonicalFindingsForAdapter(f) {
+  const security = _mapAdapterFindingToCanonical(f);
+  if (f.tool !== 'snyk') return [security];
+  const licence = f.licence === undefined ? null : f.licence;
+  const licenceSeverity = _mapLicenceToSeverity(licence);
+  if (licenceSeverity === null) return [security];
+  const pkg = f.package_name || 'unknown';
+  const ver = f.installed_version || 'unknown';
+  const licenceId = security.id === null || security.id === undefined
+    ? null
+    : `${security.id}-lic`;
+  const licenceFinding = {
+    id: licenceId,
+    test_source: CANONICAL_TEST_SOURCE,
+    gap_type: 'dependency-licence',
+    severity: licenceSeverity,
+    resource_id: security.resource_id,
+    repo: f.repo,
+    manifest_path: f.manifest_path === undefined ? null : f.manifest_path,
+    title: `Restrictive licence: ${licence}`,
+    description: `Package ${pkg}@${ver} is licensed under ${licence}. Using this dependency may impose copyleft obligations on your project.`,
+    remediation: 'Review licence compatibility or replace with a permissive-licensed alternative.',
+    reference: null,
+    cve: null,
+    cvss: null,
+    dependency_chain: null,
+    chain_available: false,
+    direct_or_transitive: f.direct_or_transitive === undefined ? null : f.direct_or_transitive,
+    tool: 'snyk',
+    // Phase 153 PKG-33: licence finding inherits provenance from the security finding (same package, same manifest).
+    introduced_in_commit: security.introduced_in_commit,
+    introduced_in_plan: security.introduced_in_plan,
+  };
+  return [security, licenceFinding];
+}
+
+// ─── Public: writePackageScanReport ──────────────────────────────────────────
+
+function writePackageScanReport(cwd, runResult, opts) {
+  opts = opts || {};
+  if (!runResult || typeof runResult !== 'object') {
+    throw new Error('runResult must be a non-null object');
+  }
+
+  const now = opts.now ? opts.now() : new Date();
+  const nowDate = now instanceof Date ? now : new Date(now);
+
+  const rr = Array.isArray(runResult.repo_results) ? runResult.repo_results : [];
+  const findings = Array.isArray(runResult.findings) ? runResult.findings : [];
+
+  const toolString = _aggregateToolString(runResult);
+  const repos_scanned = rr.filter(r => r.outcome !== 'no_manifests').length;
+  const duration = Math.round(rr.reduce((s, r) => s + (r.durationMs || 0), 0) / 1000);
+
+  const payload = {
+    type: 'package-scan',
+    date: nowDate.toISOString().slice(0, 10),
+    tool: toolString,
+    // UAT Bug 2: forward snyk_org from runScan result. Null when unset.
+    snyk_org: (runResult.snyk_org === undefined ? null : runResult.snyk_org),
+    repos_scanned,
+    critical: _countSeverity(findings, 'critical'),
+    high: _countSeverity(findings, 'high'),
+    medium: _countSeverity(findings, 'medium'),
+    low: _countSeverity(findings, 'low'),
+    duration,
+    findings: findings.flatMap(_canonicalFindingsForAdapter),
+  };
+
+  let frontmatter;
+  try {
+    frontmatter = _emitYamlFrontmatter(payload);
+  } catch (err) {
+    throw new Error('YAML emitter: ' + (err && err.message ? err.message : String(err)));
+  }
+
+  const body = _renderBody(runResult);
+  const reportPath = opts.overridePath || _resolveReportPath(cwd, { now: opts.now });
+  fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+  const content = frontmatter + '\n' + body + '\n';
+  fs.writeFileSync(reportPath, content);
+
+  return {
+    path: reportPath,
+    tool_string: toolString,
+    n_findings: findings.length,
+  };
+}
+
+module.exports = {
+  writePackageScanReport,
+  _emitYamlFrontmatter,
+  _parseEmittedYaml,
+  _renderBody,
+  _resolveReportPath,
+  // Internal helpers exported for symmetry with tests.
+  _aggregateToolString,
+  _countSeverity,
+  _collapseSeverity,
+  _mapAdapterFindingToCanonical,
+  _canonicalFindingsForAdapter,
+  _mapLicenceToSeverity,
+  // Phase 152: canonical normaliser tables exported for test-gate consumers.
+  SEVERITY_MAP,
+  LICENCE_SEVERITY_MAP,
+  // Phase 153 PKG-30/34: Licence Compliance section renderer.
+  _renderLicenceComplianceSection,
+  _licenceRosterFlag,
+  // Phase 153 PKG-35/36: cross-repo dedup + version overlap.
+  _groupFindingsByPackageVersion,
+  _detectVersionOverlaps,
+  _renderCrossRepoSummary,
+  _renderVersionOverlap,
+};