fg-devkit 1.20.2 → 1.21.0

package/README.md

@@ -63,13 +63,18 @@ pnpm exec fgd fallow dead-code --json
 
 When you run `fgd sync-tooling-configs` (or `fgd sync-project-configs`), fg-devkit also writes a shared `.fallowrc.json` to the consuming repo.
 
-Copy the shared OWASP Dependency-Check suppressions file into a consuming repo and commit it:
+Write the OWASP Dependency-Check suppressions that apply to a consuming repo and commit them:
 
 ```bash
-pnpm exec fgd sync-dependency-check-suppressions-commit
+pnpm exec fgd sync-dependency-check-suppressions-commit        # only entries matching pnpm audit findings
+pnpm exec fgd sync-dependency-check-suppressions-commit --all  # every entry in the shared file
 ```
 
-Jenkins `owaspDependencyCheck` reads `dependency-check-suppressions.xml` from the repo root when the file exists. Add another `<suppress>` element in the shared fg-devkit file for each additional accepted finding. The command overwrites the consumer copy.
+The command runs `pnpm audit` and keeps only the active (not expired) `<suppress>` entries from fg-devkit's shared
+`configs/dependency-check-suppressions.xml` whose GHSA id is reported in the repo, so each repo accepts exactly the
+risks it has. Jenkins `owaspDependencyCheck` reads `dependency-check-suppressions.xml` from the repo root when the
+file exists. Add another `<suppress>` element in the shared fg-devkit file for each additional accepted finding.
+The command overwrites the consumer copy; if nothing applies and the repo has no copy, no file is created.
 
 To sync standard consumer scripts to `fgd` commands:
 
@@ -153,13 +158,32 @@ Same upgrade, then prune unused workspace overrides in a second commit if any ca
 pnpm exec fgd policy-upgrade-commit --prune-overrides
 ```
 
-Fix one or more vulnerability overrides interactively, prune unused overrides, and auto-commit
-(`vuln(package): override version`, `vuln(package): prune override`, or `vuln(): override N packages` with a body listing each change):
+Fix `pnpm audit` findings with the smallest change, verify, and auto-commit:
 
 ```bash
-pnpm exec fgd audit-override-commit
+pnpm exec fgd audit-override-commit              # refresh, override, prune, verify, commit
+pnpm exec fgd audit-override-commit --no-verify  # skip lint/typecheck/test/build (git hooks still run)
+pnpm exec fgd audit-override-commit --no-commit  # leave the changes in the working tree
 ```
 
+1. Runs `pnpm audit` and refreshes the vulnerable packages in the lockfile (`pnpm update <names>`).
+   Each moves to the newest version its parents' ranges already allow, so no override is needed.
+2. Audits again. When a patched version exists but a parent's range blocks it, adds a tight override to
+   `pnpm-workspace.yaml`: `'name@>=installed <patched': 'patched'` (the lowest patched version).
+3. Reports instead of overriding when the only patch is in a new major (upgrade the parent), when it is
+   younger than `minimumReleaseAge` (re-run later), when the package is a direct dependency (bump it with
+   `policy-upgrade-commit`), or when no patch exists (candidate for `auditConfig.ignoreGhsas`).
+4. Prunes overrides that no longer change the audit.
+5. If findings that are still reported have active (not expired) `<suppress>` entries in fg-devkit's shared
+   `configs/dependency-check-suppressions.xml`, writes the repo's `dependency-check-suppressions.xml` with only
+   those entries, so the Jenkins OWASP scan accepts exactly the risks this repo has. Findings with no patch and
+   no suppression are listed so you can add one.
+6. Installs and runs the repo's `lint-check`, `lint:ts`, `test`, `test:unit` and `build` scripts when present.
+   Nothing is committed if a check fails.
+7. Commits the lockfile refresh (`vuln(package): refresh lockfile` / `vuln(): refresh N packages in lockfile`),
+   the override changes (`vuln(package): override version`, `vuln(): override N packages`) and the
+   suppressions file (`chore(repo): sync dependency-check suppressions`) separately.
+
 Report, remove, or remove and auto-commit workspace overrides that no longer change `pnpm audit`:
 
 ```bash

package/configs/dependency-policy.vue-workspace.json

@@ -95,7 +95,7 @@
     "dotenv": "18.0.5",
     "qrcode.vue": "3.11.0",
     "tailwindcss": "4.3.3",
-    "vite": "8.3.2",
+    "vite": "8.3.3",
     "vue": "3.5.43"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fg-devkit",
-  "version": "1.20.2",
+  "version": "1.21.0",
   "description": "Shared configs, scripts, and DX tooling for Vue / TypeScript frontend repos",
   "type": "module",
   "license": "UNLICENSED",
@@ -116,8 +116,8 @@
     "@inquirer/input": "5.1.7",
     "@inquirer/select": "5.2.6",
     "@intlify/eslint-plugin-vue-i18n": "4.5.1",
-    "@typescript-eslint/eslint-plugin": "8.71.0",
-    "@typescript-eslint/parser": "8.71.0",
+    "@typescript-eslint/eslint-plugin": "8.71.1",
+    "@typescript-eslint/parser": "8.71.1",
     "@vitest/eslint-plugin": "1.6.27",
     "@vue/eslint-config-prettier": "10.2.0",
     "@vue/eslint-config-typescript": "14.9.0",

package/scaffold/vue/package.json

@@ -32,11 +32,11 @@
     "@intlify/unplugin-vue-i18n": "11.2.5",
     "@tanstack/vue-query-devtools": "6.3.1",
     "@types/node": "22.16.5",
-    "fg-devkit": "1.20.2",
+    "fg-devkit": "1.21.0",
     "@vitejs/plugin-vue": "6.0.9",
     "tailwindcss": "4.3.3",
     "tsx": "4.23.15",
-    "vite": "8.3.2",
+    "vite": "8.3.3",
     "vite-plugin-vue-inspector": "7.0.0"
   },
   "packageManager": "pnpm@12.9.1",

package/scripts/audit-fix-plan.mjs

@@ -0,0 +1,436 @@
+/**
+ * Pure helpers for audit-override-commit: normalize `pnpm audit --json` output, plan
+ * minimal overrides for what a lockfile refresh could not fix, edit the `overrides:`
+ * section of pnpm-workspace.yaml, and diff resolved versions between two lockfiles.
+ *
+ * No I/O here so the logic can be unit tested (audit-fix-plan.test.mjs).
+ */
+
+// ---------------------------------------------------------------------------
+// Versions
+// ---------------------------------------------------------------------------
+
+/** Parse `1.2.3` / `1.2.3-beta.1` (build metadata ignored). Returns null when not semver. */
+export function parseVersion(value) {
+  const match = String(value ?? '')
+    .trim()
+    .match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/)
+  if (!match) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ? match[4].split('.') : [],
+  }
+}
+
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) return 0
+  if (a.length === 0) return 1
+  if (b.length === 0) return -1
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    if (a[i] === undefined) return -1
+    if (b[i] === undefined) return 1
+    const aNum = /^\d+$/.test(a[i])
+    const bNum = /^\d+$/.test(b[i])
+    if (aNum && bNum) {
+      const diff = Number(a[i]) - Number(b[i])
+      if (diff !== 0) return Math.sign(diff)
+    } else if (aNum !== bNum) {
+      return aNum ? -1 : 1
+    } else if (a[i] !== b[i]) {
+      return a[i] < b[i] ? -1 : 1
+    }
+  }
+  return 0
+}
+
+/** Semver precedence compare. Throws on non-semver input. */
+export function compareVersions(a, b) {
+  const left = typeof a === 'string' ? parseVersion(a) : a
+  const right = typeof b === 'string' ? parseVersion(b) : b
+  if (!left || !right) throw new Error(`cannot compare versions ${a} and ${b}`)
+  for (const part of ['major', 'minor', 'patch']) {
+    if (left[part] !== right[part]) return Math.sign(left[part] - right[part])
+  }
+  return comparePrerelease(left.prerelease, right.prerelease)
+}
+
+/**
+ * True when `to` is a semver-compatible upgrade of `from` (what a `^from` range accepts):
+ * same major for >=1.0.0, same minor for 0.x, same patch for 0.0.x.
+ */
+export function isSameReleaseLine(from, to) {
+  const a = parseVersion(from)
+  const b = parseVersion(to)
+  if (!a || !b) return false
+  if (a.major !== b.major) return false
+  if (a.major > 0) return true
+  if (a.minor !== b.minor) return false
+  if (a.minor > 0) return true
+  return a.patch === b.patch
+}
+
+/**
+ * Lowest patched version strictly above `installed`, read from an advisory's
+ * `patched_versions` (e.g. `>=1.2.2`, `>=1.1.21 <2.0.0 || >=2.1.7`).
+ * Returns `{ status: 'none' }` when no patch exists, `{ status: 'unparseable' }` when the
+ * range is not made of `>=x.y.z` lower bounds, else `{ status: 'ok', version }`.
+ */
+export function lowestPatchedVersion(patchedVersions, installed) {
+  const text = String(patchedVersions ?? '').trim()
+  if (!text || text === 'None' || text === '<0.0.0') return { status: 'none' }
+  const bounds = []
+  for (const alternative of text.split('||')) {
+    const lower = alternative.trim().match(/^>=\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\s|$)/)
+    if (!lower) return { status: 'unparseable' }
+    bounds.push(lower[1])
+  }
+  const candidates = bounds.filter((version) => compareVersions(version, installed) > 0).sort(compareVersions)
+  if (candidates.length === 0) return { status: 'unparseable' }
+  return { status: 'ok', version: candidates[0] }
+}
+
+// ---------------------------------------------------------------------------
+// pnpm audit --json
+// ---------------------------------------------------------------------------
+
+/** Parse `pnpm audit --json` stdout (tolerates log noise around the JSON). */
+export function parseAuditJson(stdout) {
+  const text = String(stdout ?? '').trim()
+  try {
+    return JSON.parse(text)
+  } catch {
+    const start = text.indexOf('{')
+    const end = text.lastIndexOf('}')
+    if (start >= 0 && end > start) return JSON.parse(text.slice(start, end + 1))
+    throw new Error(`pnpm audit --json did not return JSON\n${text.slice(0, 500)}`)
+  }
+}
+
+/**
+ * Flatten an audit report into advisories:
+ * `{ id, ghsa, name, severity, title, vulnerable, patched, versions: string[] }`.
+ * `id` is unique per advisory *and* vulnerable range (one GHSA can cover several majors).
+ */
+export function normalizeAdvisories(report) {
+  const advisories = []
+  for (const [key, advisory] of Object.entries(report?.advisories ?? {})) {
+    const ghsa = advisory.github_advisory_id || String(advisory.id ?? key)
+    const versions = [...new Set((advisory.findings ?? []).map((finding) => finding.version).filter(Boolean))]
+    advisories.push({
+      id: `${ghsa}|${advisory.module_name}|${advisory.vulnerable_versions}`,
+      ghsa,
+      name: advisory.module_name,
+      severity: advisory.severity,
+      title: advisory.title,
+      vulnerable: advisory.vulnerable_versions,
+      patched: advisory.patched_versions,
+      versions,
+    })
+  }
+  return advisories
+}
+
+// ---------------------------------------------------------------------------
+// Override planning
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide what to do with advisories that survived the lockfile refresh.
+ *
+ * For every installed vulnerable version the target is the lowest version that fixes all
+ * advisories affecting it. Targets in the same release line become one override per range,
+ * keyed tightly (`name@>=installed <target`) so nothing outside the vulnerable span moves.
+ *
+ * @param {ReturnType<typeof normalizeAdvisories>} advisories
+ * @param {{ directDependencies?: Set<string> }} [options]
+ */
+export function planOverrides(advisories, { directDependencies = new Set() } = {}) {
+  const plan = { overrides: [], noPatch: [], crossMajor: [], direct: [], unparseable: [] }
+  const byPackage = new Map()
+  for (const advisory of advisories) {
+    if (!byPackage.has(advisory.name)) byPackage.set(advisory.name, [])
+    byPackage.get(advisory.name).push(advisory)
+  }
+
+  for (const [name, packageAdvisories] of byPackage) {
+    const ghsas = [...new Set(packageAdvisories.map((advisory) => advisory.ghsa))]
+    if (directDependencies.has(name)) {
+      plan.direct.push({ name, ghsas, versions: collectVersions(packageAdvisories) })
+      continue
+    }
+
+    // installed version -> highest "lowest patched version" across its advisories
+    const targets = new Map()
+    const blocked = { none: new Set(), unparseable: new Set() }
+    for (const advisory of packageAdvisories) {
+      for (const installed of advisory.versions) {
+        if (!parseVersion(installed)) {
+          blocked.unparseable.add(advisory.ghsa)
+          continue
+        }
+        const patched = lowestPatchedVersion(advisory.patched, installed)
+        if (patched.status !== 'ok') {
+          blocked[patched.status].add(advisory.ghsa)
+          continue
+        }
+        const current = targets.get(installed)
+        if (!current) {
+          targets.set(installed, { target: patched.version, ghsas: new Set([advisory.ghsa]) })
+          continue
+        }
+        if (compareVersions(patched.version, current.target) > 0) current.target = patched.version
+        current.ghsas.add(advisory.ghsa)
+      }
+    }
+
+    if (blocked.none.size > 0) {
+      plan.noPatch.push({ name, ghsas: [...blocked.none], versions: collectVersions(packageAdvisories) })
+    }
+    if (blocked.unparseable.size > 0) {
+      plan.unparseable.push({ name, ghsas: [...blocked.unparseable], patched: packageAdvisories[0].patched })
+    }
+    // A package with an unfixable advisory gets no override: it would not clear the finding.
+    if (blocked.none.size > 0 || blocked.unparseable.size > 0) continue
+
+    const spans = [...targets.entries()]
+      .map(([installed, { target, ghsas: spanGhsas }]) => ({ low: installed, high: target, ghsas: spanGhsas }))
+      .sort((a, b) => compareVersions(a.low, b.low))
+
+    const merged = []
+    for (const span of spans) {
+      const last = merged.at(-1)
+      if (last && compareVersions(span.low, last.high) < 0) {
+        if (compareVersions(span.high, last.high) > 0) last.high = span.high
+        for (const ghsa of span.ghsas) last.ghsas.add(ghsa)
+      } else {
+        merged.push({ ...span, ghsas: new Set(span.ghsas) })
+      }
+    }
+
+    for (const span of merged) {
+      const entry = { name, from: span.low, to: span.high, ghsas: [...span.ghsas] }
+      if (!isSameReleaseLine(span.low, span.high)) {
+        plan.crossMajor.push(entry)
+        continue
+      }
+      plan.overrides.push({ ...entry, key: `${name}@>=${span.low} <${span.high}`, value: span.high })
+    }
+  }
+
+  return plan
+}
+
+function collectVersions(advisories) {
+  return [...new Set(advisories.flatMap((advisory) => advisory.versions))].sort((a, b) => {
+    try {
+      return compareVersions(a, b)
+    } catch {
+      return a < b ? -1 : 1
+    }
+  })
+}
+
+// ---------------------------------------------------------------------------
+// minimumReleaseAge
+// ---------------------------------------------------------------------------
+
+/** pnpm 11+ defaults minimumReleaseAge to 1440 minutes when it is not configured. */
+export const DEFAULT_MINIMUM_RELEASE_AGE_MINUTES = 1440
+
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')
+  return new RegExp(`^${escaped}$`)
+}
+
+/**
+ * Whether `name@version` is listed in minimumReleaseAgeExclude. Entries can be a name,
+ * a name pattern (`@scope/*`), or `name@1.2.3 || 1.2.4`.
+ */
+export function isReleaseAgeExcluded(excludeList, name, version) {
+  for (const raw of excludeList ?? []) {
+    const entry = String(raw).trim()
+    const at = entry.lastIndexOf('@')
+    if (at <= 0) {
+      if (globToRegExp(entry).test(name)) return true
+      continue
+    }
+    if (entry.slice(0, at) !== name) continue
+    const versions = entry
+      .slice(at + 1)
+      .split('||')
+      .map((item) => item.trim())
+    if (versions.includes(version)) return true
+  }
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// pnpm-workspace.yaml overrides
+// ---------------------------------------------------------------------------
+
+function quoteYamlKey(key) {
+  return `'${key.replace(/'/g, "''")}'`
+}
+
+function unquoteYaml(value) {
+  const text = value.trim()
+  if (text.startsWith("'") && text.endsWith("'")) return text.slice(1, -1).replace(/''/g, "'")
+  if (text.startsWith('"') && text.endsWith('"')) return text.slice(1, -1)
+  return text
+}
+
+/**
+ * Add or replace entries in the top-level `overrides:` map of pnpm-workspace.yaml,
+ * keeping every other line untouched. Creates the section when missing.
+ *
+ * @param {string} text
+ * @param {{ key: string, value: string }[]} entries
+ */
+export function upsertWorkspaceOverrides(text, entries) {
+  if (entries.length === 0) return text
+  const lines = text.replace(/\r\n/g, '\n').split('\n')
+  const start = lines.findIndex((line) => /^overrides:\s*(?:#.*)?$/.test(line))
+  const rendered = (entry) => `  ${quoteYamlKey(entry.key)}: '${entry.value}'`
+
+  if (start === -1) {
+    while (lines.length > 0 && lines.at(-1) === '') lines.pop()
+    lines.push('overrides:', ...entries.map(rendered), '')
+    return lines.join('\n')
+  }
+
+  let end = start + 1
+  while (end < lines.length && (lines[end] === '' || /^\s/.test(lines[end]))) end += 1
+  // Keep trailing blank lines outside the section.
+  let lastContent = end - 1
+  while (lastContent > start && lines[lastContent] === '') lastContent -= 1
+
+  const pending = new Map(entries.map((entry) => [entry.key, entry]))
+  for (let i = start + 1; i <= lastContent; i += 1) {
+    const match = lines[i].match(/^(\s+)((?:'(?:[^']|'')*'|"[^"]*"|[^:#]+)):/)
+    if (!match) continue
+    const key = unquoteYaml(match[2])
+    if (pending.has(key)) {
+      lines[i] = rendered(pending.get(key))
+      pending.delete(key)
+    }
+  }
+  lines.splice(lastContent + 1, 0, ...[...pending.values()].map(rendered))
+  return lines.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Lockfile diff
+// ---------------------------------------------------------------------------
+
+/** Map of package name -> Set of resolved versions in a pnpm-lock.yaml (all YAML documents). */
+export function lockfileVersions(text) {
+  const versions = new Map()
+  const pattern = /^ {2}'?((?:@[^/\s']+\/)?[^@\s'()]+)@(\d+\.\d+\.\d+[^:'\s(]*)/gm
+  for (const match of String(text ?? '').matchAll(pattern)) {
+    if (!versions.has(match[1])) versions.set(match[1], new Set())
+    versions.get(match[1]).add(match[2])
+  }
+  return versions
+}
+
+/** `[{ name, from: string[], to: string[] }]` for packages whose resolved versions changed. */
+export function diffLockfileVersions(beforeText, afterText) {
+  const before = lockfileVersions(beforeText)
+  const after = lockfileVersions(afterText)
+  const changes = []
+  for (const name of [...new Set([...before.keys(), ...after.keys()])].sort()) {
+    const from = [...(before.get(name) ?? [])].filter((version) => !after.get(name)?.has(version))
+    const to = [...(after.get(name) ?? [])].filter((version) => !before.get(name)?.has(version))
+    if (from.length === 0 && to.length === 0) continue
+    changes.push({ name, from: from.sort(compareVersionsLoose), to: to.sort(compareVersionsLoose) })
+  }
+  return changes
+}
+
+function compareVersionsLoose(a, b) {
+  try {
+    return compareVersions(a, b)
+  } catch {
+    return a < b ? -1 : 1
+  }
+}
+
+/** Commit message for the lockfile-refresh commit, in the repo's `vuln()` convention. */
+export function buildRefreshCommitMessage(changes) {
+  const describe = (change) =>
+    `- ${change.name}: ${change.from.join(', ') || '(new)'} -> ${change.to.join(', ') || '(removed)'}`
+  if (changes.length === 0) {
+    return { subject: 'vuln(): refresh lockfile', body: '' }
+  }
+  if (changes.length === 1) {
+    return { subject: `vuln(${changes[0].name}): refresh lockfile`, body: describe(changes[0]) }
+  }
+  return { subject: `vuln(): refresh ${changes.length} packages in lockfile`, body: changes.map(describe).join('\n') }
+}
+
+// ---------------------------------------------------------------------------
+// OWASP Dependency-Check suppressions
+// ---------------------------------------------------------------------------
+
+function parseSuppressUntil(value) {
+  if (!value) return undefined
+  // Dependency-Check uses xs:date, e.g. `2026-12-01Z` or `2026-12-01+01:00`.
+  const match = value.trim().match(/^(\d{4}-\d{2}-\d{2})(Z|[+-]\d{2}:\d{2})?$/)
+  const time = match ? Date.parse(`${match[1]}T00:00:00${match[2] ?? 'Z'}`) : Date.parse(value)
+  return Number.isFinite(time) ? time : undefined
+}
+
+/**
+ * Parse the `<suppress>` entries of a dependency-check-suppressions.xml.
+ * GHSA ids are read from the matching elements only (not `<notes>`). An entry is
+ * inactive once its `until` date has passed, because Dependency-Check ignores it then.
+ *
+ * @returns {{ text: string, ghsas: string[], until?: string, active: boolean }[]}
+ *   `text` is the entry exactly as written, including indentation and line break.
+ */
+export function parseSuppressions(xmlText, now = Date.now()) {
+  const entries = []
+  const pattern = /^[ \t]*<suppress\b([^>]*)>([\s\S]*?)<\/suppress>[ \t]*(?:\r?\n)?/gm
+  for (const [text, attributes, body] of String(xmlText ?? '').matchAll(pattern)) {
+    const until = attributes.match(/\buntil="([^"]*)"/)?.[1]
+    const untilTime = parseSuppressUntil(until)
+    const active = !until || (untilTime !== undefined && untilTime > now)
+    const matchers = body.replace(/<notes>[\s\S]*?<\/notes>/g, '')
+    const ghsas = [
+      ...new Set(
+        [...matchers.matchAll(/GHSA-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}/gi)].map(
+          ([ghsa]) => `GHSA${ghsa.slice(4).toLowerCase()}`,
+        ),
+      ),
+    ]
+    entries.push({ text, ghsas, until, active })
+  }
+  return entries
+}
+
+/** GHSA id -> `until` for every active `<suppress>` entry. */
+export function activeSuppressedGhsas(xmlText, now = Date.now()) {
+  const covered = new Map()
+  for (const entry of parseSuppressions(xmlText, now)) {
+    if (!entry.active) continue
+    for (const ghsa of entry.ghsas) covered.set(ghsa, entry.until)
+  }
+  return covered
+}
+
+/**
+ * The shared suppressions file reduced to the active entries that match one of `ghsas`,
+ * so a repo only accepts the risks it actually has. Header, namespace and the kept
+ * entries are copied verbatim.
+ */
+export function filterSuppressions(xmlText, ghsas, now = Date.now()) {
+  const wanted = new Set(ghsas)
+  let result = String(xmlText ?? '')
+  for (const entry of parseSuppressions(result, now)) {
+    if (entry.active && entry.ghsas.some((ghsa) => wanted.has(ghsa))) continue
+    result = result.replace(entry.text, '')
+  }
+  return result
+}