@ulisesgascon/openjs-cna-tools 0.0.0-stage → 1.0.0-alpha.1

package/lib/convert/version-range.js

@@ -0,0 +1,251 @@
+// Parse GHSA-style `vulnerable_version_range` strings into MITRE v5.2
+// `affected[].versions[]` entries.
+//
+// GHSA is permissive: maintainers type freeform range expressions and we
+// see ~60 distinct shapes across the vulnerabilities tracked
+// (see test/fixtures/version-range-matrix.js for the canonical list).
+// MITRE is strict: every entry needs { version, status, versionType } plus
+// at most one of { lessThan, lessThanOrEqual, changes }.
+//
+// Strategy:
+//
+//   1. Split multi-line inputs on `; ` or `&&` first — each segment becomes
+//      its own entry in the output array.
+//   2. For each segment, strip incidental noise (package-name prefix,
+//      parenthetical annotations, leading/trailing whitespace, leading
+//      `v` on tokens like `v5.2.1`).
+//   3. Try a sequence of structural matchers most-specific first: hyphen
+//      range, caret range, bounded (lower + upper), single operator,
+//      implicit-lower-bound shape, bare semver, commit hash.
+//   4. Unparseable segments fall back to `versionType: 'custom'` carrying
+//      the original text, unless we extracted an embedded commit hash —
+//      in which case use that.
+//
+// Always emits at least one entry per non-empty input, or [] for empty
+// strings. The function never throws on input.
+
+const SEMVER_TOKEN = String.raw`v?\d+(?:\.\d+){0,2}(?:-[\w.]+)?`
+const HASH_TOKEN = '[0-9a-f]{7,40}'
+const COMMIT_HASH = new RegExp(`^${HASH_TOKEN}$`, 'i')
+
+const RX = {
+  bareSemver: new RegExp(`^${SEMVER_TOKEN}$`),
+  rangeHyphen: new RegExp(`^(${SEMVER_TOKEN})\\s*-\\s*(${SEMVER_TOKEN})$`),
+  caret: new RegExp(`^\\^(${SEMVER_TOKEN})$`),
+
+  // Single-operator forms. The optional whitespace lets `<4.0.0` and
+  // `< 4.0.0` both match.
+  opUpperEx: new RegExp(`^<\\s*(${SEMVER_TOKEN}|${HASH_TOKEN})$`, 'i'),
+  opUpperInc: new RegExp(`^(?:<=|=<)\\s*(${SEMVER_TOKEN})$`),
+  opLowerEx: new RegExp(`^>\\s*(${SEMVER_TOKEN})$`),
+  opLowerInc: new RegExp(`^>=\\s*(${SEMVER_TOKEN})$`),
+  opEquals: new RegExp(`^=\\s*(${SEMVER_TOKEN})$`),
+
+  // Bounded ranges: lower + upper, glued together with comma, whitespace,
+  // or nothing. `>=4.0.0, <4.18.0` / `>=4.0.0 <4.18.0` / `>=4.0.0,<4.18.0`
+  // / `>=4.0.0<4.18.0` all match.
+  bounded: new RegExp(
+    `^>=?\\s*(${SEMVER_TOKEN})\\s*(?:,\\s*|\\s+|)\\s*(<=?|=<)\\s*(${SEMVER_TOKEN})$`
+  ),
+
+  // Implicit lower bound: "7.0.0 < 7.24.0" — no leading operator, the
+  // bare version IS the lower bound.
+  implicitBounded: new RegExp(
+    `^(${SEMVER_TOKEN})\\s*(<=?|=<)\\s*(${SEMVER_TOKEN})$`
+  )
+}
+
+function stripV (s) {
+  return String(s).replace(/^v/, '')
+}
+
+// Remove incidental noise from a segment before structural matching:
+// parenthetical annotations, leading package-name prefixes, surrounding
+// whitespace.
+function clean (segment) {
+  let s = segment.trim()
+  // Strip parenthetical clarifications: "<=5.2.1 (includes all 4.x)".
+  s = s.replace(/\s*\([^)]*\)\s*/g, '').trim()
+  // Strip package-name prefix: "lodash <= 4.18.1" or "lodash<=4.18.1".
+  // We only fire this when the prefix is alphabetic AND followed by an
+  // OPERATOR (`<`, `>`, `=`). If we widened to digits we'd shred
+  // freeform inputs like "Leangheng2004" into the bare "4".
+  s = s.replace(/^[a-z@][\w@/.-]*\s*(?=[<>=])/i, '').trim()
+  return s
+}
+
+// Split multi-line inputs on `;` or `&&`. Each segment becomes its own
+// entry in the output.
+function splitMultiline (input) {
+  return input
+    .split(/\s*(?:;|&&)\s*/)
+    .map(s => s.trim())
+    .filter(Boolean)
+}
+
+// Try to parse a single segment. Returns the MITRE entry if a structural
+// matcher hits, or null if the segment cannot be understood.
+function parseSegment (raw) {
+  const segment = clean(raw)
+  if (!segment) return null
+
+  // Wildcards
+  if (segment === '*' || /^all$/i.test(segment)) {
+    return { version: '0', status: 'affected', versionType: 'semver' }
+  }
+
+  // Hyphen range: "4.0.0 - 4.17.23"
+  const hyphenMatch = segment.match(RX.rangeHyphen)
+  if (hyphenMatch) {
+    return {
+      version: stripV(hyphenMatch[1]),
+      lessThanOrEqual: stripV(hyphenMatch[2]),
+      status: 'affected',
+      versionType: 'semver'
+    }
+  }
+
+  // Caret range: "^4.19.2" → [4.19.2, 5.0.0)
+  const caretMatch = segment.match(RX.caret)
+  if (caretMatch) {
+    const base = stripV(caretMatch[1])
+    const major = base.split('.')[0]
+    return {
+      version: base,
+      lessThan: `${Number(major) + 1}.0.0`,
+      status: 'affected',
+      versionType: 'semver'
+    }
+  }
+
+  // Bounded: ">=4.0.0, <4.18.0" / ">= 4.0.0 <= 4.18.1" / ">=4.0.0<4.18.0"
+  const bounded = segment.match(RX.bounded)
+  if (bounded) {
+    const lower = stripV(bounded[1])
+    const upperOp = bounded[2]
+    const upper = stripV(bounded[3])
+    const entry = { version: lower, status: 'affected', versionType: 'semver' }
+    if (upperOp === '<') entry.lessThan = upper
+    else entry.lessThanOrEqual = upper
+    return entry
+  }
+
+  // Implicit lower: "7.0.0 < 7.24.0" — bare version followed by operator.
+  const implicit = segment.match(RX.implicitBounded)
+  if (implicit) {
+    const lower = stripV(implicit[1])
+    const upperOp = implicit[2]
+    const upper = stripV(implicit[3])
+    const entry = { version: lower, status: 'affected', versionType: 'semver' }
+    if (upperOp === '<') entry.lessThan = upper
+    else entry.lessThanOrEqual = upper
+    return entry
+  }
+
+  // Single-operator forms — try most specific (two-char ops) first.
+  const opUpperInc = segment.match(RX.opUpperInc)
+  if (opUpperInc) {
+    return {
+      version: '0',
+      lessThanOrEqual: stripV(opUpperInc[1]),
+      status: 'affected',
+      versionType: 'semver'
+    }
+  }
+  const opLowerInc = segment.match(RX.opLowerInc)
+  if (opLowerInc) {
+    return { version: stripV(opLowerInc[1]), status: 'affected', versionType: 'semver' }
+  }
+  const opUpperEx = segment.match(RX.opUpperEx)
+  if (opUpperEx) {
+    const value = opUpperEx[1]
+    if (COMMIT_HASH.test(value)) {
+      return { version: '0', lessThan: value, status: 'affected', versionType: 'git' }
+    }
+    return { version: '0', lessThan: stripV(value), status: 'affected', versionType: 'semver' }
+  }
+  const opLowerEx = segment.match(RX.opLowerEx)
+  if (opLowerEx) {
+    return { version: stripV(opLowerEx[1]), status: 'affected', versionType: 'semver' }
+  }
+  const opEquals = segment.match(RX.opEquals)
+  if (opEquals) {
+    return { version: stripV(opEquals[1]), status: 'affected', versionType: 'semver' }
+  }
+
+  // Bare semver: "4.6.2"
+  if (RX.bareSemver.test(segment)) {
+    return { version: stripV(segment), status: 'affected', versionType: 'semver' }
+  }
+
+  // Bare commit hash: "39fd9827942..."
+  if (COMMIT_HASH.test(segment)) {
+    return { version: segment, status: 'affected', versionType: 'git' }
+  }
+
+  return null
+}
+
+// Public entry. See module header.
+export function parseVersionRange (input) {
+  if (typeof input !== 'string') return []
+  const trimmed = input.trim()
+  if (!trimmed) return []
+
+  const segments = splitMultiline(trimmed)
+  const out = []
+  const fallbacks = [] // { kind: 'hash'|'custom', entry, hadDigits }
+
+  for (const seg of segments) {
+    const parsed = parseSegment(seg)
+    if (parsed) {
+      out.push(parsed)
+      continue
+    }
+    // Fall back: extract an embedded commit hash if present, otherwise
+    // pass the segment through verbatim under `versionType: 'custom'`.
+    // We stage fallbacks separately so that, in multi-segment inputs,
+    // pure-prose segments can be dropped when at least one other segment
+    // yielded something useful.
+    const hashMatch = seg.match(new RegExp(`\\b(${HASH_TOKEN})\\b`, 'i'))
+    if (hashMatch) {
+      fallbacks.push({
+        kind: 'hash',
+        entry: { version: hashMatch[1], status: 'affected', versionType: 'custom' },
+        hadDigits: true
+      })
+    } else {
+      const hadDigits = /\d/.test(seg)
+      fallbacks.push({
+        kind: 'custom',
+        entry: { version: seg, status: 'affected', versionType: 'custom' },
+        hadDigits
+      })
+    }
+  }
+
+  if (segments.length > 1 && out.length > 0) {
+    // Multi-segment: only keep fallbacks that surfaced a hash or had
+    // digits. Prose-only fallbacks are dropped because the structured
+    // segments already carry the load-bearing information.
+    for (const f of fallbacks) {
+      if (f.kind === 'hash' || f.hadDigits) out.push(f.entry)
+    }
+  } else if (segments.length > 1) {
+    // Multi-segment with zero structured hits: surface hashes if any,
+    // otherwise nothing — the input is pure prose.
+    for (const f of fallbacks) {
+      if (f.kind === 'hash') out.push(f.entry)
+    }
+    if (out.length === 0 && fallbacks.length > 0) {
+      // Truly nothing — surface the first segment so the operator sees
+      // what was there.
+      out.push(fallbacks[0].entry)
+    }
+  } else {
+    // Single segment: pass the fallback through verbatim.
+    for (const f of fallbacks) out.push(f.entry)
+  }
+
+  return out
+}

package/lib/errors.js

@@ -0,0 +1,44 @@
+// Error classes for openjs-cna-tools.
+//
+// Each error carries enough structured context that a recovery flow (or the
+// CLI exit-code mapping) can act on it without parsing the message. Messages
+// themselves are written to teach the next operator how to fix the problem
+// (see "Errors that teach" — the NCU pattern this borrows from).
+
+export class CnaAuthError extends Error {
+  constructor (message, { status } = {}) {
+    super(message)
+    this.name = 'CnaAuthError'
+    this.status = status
+  }
+}
+
+export class CnaTimeoutError extends Error {
+  constructor (message, { correlationId, runId, timeoutMs } = {}) {
+    super(message)
+    this.name = 'CnaTimeoutError'
+    this.correlationId = correlationId
+    this.runId = runId
+    this.timeoutMs = timeoutMs
+  }
+}
+
+export class CnaOperationError extends Error {
+  constructor (message, { correlationId, runId, conclusion, result } = {}) {
+    super(message)
+    this.name = 'CnaOperationError'
+    this.correlationId = correlationId
+    this.runId = runId
+    this.conclusion = conclusion
+    this.result = result
+  }
+}
+
+export class CnaReviewBlockedError extends Error {
+  constructor (message, { report } = {}) {
+    super(message)
+    this.name = 'CnaReviewBlockedError'
+    this.report = report
+    this.blockers = report?.issues?.filter(i => i.severity === 'blocker') ?? []
+  }
+}

package/lib/index.js

@@ -0,0 +1,9 @@
+// Public package surface.
+
+export { CnaClient } from './client.js'
+export {
+  CnaAuthError,
+  CnaTimeoutError,
+  CnaOperationError,
+  CnaReviewBlockedError
+} from './errors.js'

package/lib/preview.js

@@ -0,0 +1,144 @@
+// Compact preview of a v5.2 CNA Container, designed for terminal output
+// before / instead of editing the JSON by hand.
+//
+// Shape goal: key/value rows, pipe-friendly (no boxes, no ANSI). Preview
+// is the operator's last chance to review before publish, so values are
+// rendered in full lenght
+
+const KEY_WIDTH = 14
+const SEPARATOR_WIDTH = 56
+const SEPARATOR = '·'.repeat(SEPARATOR_WIDTH)
+
+function pad (key) {
+  if (!key) return ' '.repeat(KEY_WIDTH)
+  return (key + ':').padEnd(KEY_WIDTH)
+}
+
+function getDescription (c) {
+  return c?.descriptions?.find(d => d?.lang === 'en')?.value ??
+      c?.descriptions?.[0]?.value ??
+      ''
+}
+
+function getCvss (c) {
+  for (const m of c?.metrics ?? []) {
+    if (m?.cvssV3_1?.vectorString) {
+      return {
+        version: '3.1',
+        score: m.cvssV3_1.baseScore,
+        severity: m.cvssV3_1.baseSeverity,
+        vector: m.cvssV3_1.vectorString
+      }
+    }
+    if (m?.cvssV4_0?.vectorString) {
+      return {
+        version: '4.0',
+        score: m.cvssV4_0.baseScore,
+        severity: m.cvssV4_0.baseSeverity,
+        vector: m.cvssV4_0.vectorString
+      }
+    }
+  }
+  return null
+}
+
+function getCwes (c) {
+  const out = new Set()
+  for (const pt of c?.problemTypes ?? []) {
+    for (const d of pt?.descriptions ?? []) {
+      if (d?.cweId) out.add(d.cweId)
+    }
+  }
+  return [...out]
+}
+
+function summarizeAffected (entry) {
+  const product = `${entry.vendor ?? '?'}:${entry.product ?? '?'}`
+  const ranges = (entry.versions ?? []).map(v => {
+    if (v.lessThan) return `${v.version} → < ${v.lessThan}`
+    if (v.lessThanOrEqual) return `${v.version} → ≤ ${v.lessThanOrEqual}`
+    return v.version
+  })
+  return ranges.length === 0 ? product : `${product} (${ranges.join(', ')})`
+}
+
+function summarizeCredit (cr) {
+  const identity = cr.value ?? cr.user ?? '?'
+  return `${cr.type}: ${identity}`
+}
+
+// Render the preview into the given CLI. Stays sync and side-effect-free
+// apart from the cli writes. Callers can null-out cli to get a string
+// instead (useful for tests).
+export function renderPreview (record, cli) {
+  const lines = []
+  const out = (line = '') => {
+    if (cli) cli.log(line)
+    lines.push(line)
+  }
+
+  if (!record || typeof record !== 'object') {
+    out('Record preview: (no record provided)')
+    return lines.join('\n')
+  }
+
+  const container = record?.containers?.cna ?? {}
+  const cveId = record?.cveMetadata?.cveId
+
+  out('')
+  out('Record preview: (edit visually at https://vulnogram.org/#source)')
+
+  // Each field becomes a "row" via `row(key, value, ...extras)`. The
+  // helper emits a dotted separator before every row except the first
+  // so the operator can scan the preview as a stack of distinct fields.
+  let rowsEmitted = 0
+  const row = (key, value, ...extras) => {
+    if (rowsEmitted > 0) out(`  ${SEPARATOR}`)
+    out(`  ${pad(key)} ${value}`)
+    const continuation = ' '.repeat(2 + KEY_WIDTH + 1)
+    for (const line of extras) out(`${continuation}${line}`)
+    rowsEmitted += 1
+  }
+
+  if (cveId) row('CVE', cveId)
+  if (container.title) row('Title', container.title)
+
+  const description = getDescription(container)
+  if (description) {
+    const [firstLine, ...rest] = String(description).split('\n')
+    row('Description', firstLine, ...rest)
+  }
+
+  const affected = container.affected ?? []
+  if (affected.length > 0) {
+    const [first, ...rest] = affected
+    row('Affected', summarizeAffected(first), ...rest.map(summarizeAffected))
+  }
+
+  const cvss = getCvss(container)
+  if (cvss) {
+    const score = typeof cvss.score === 'number' ? cvss.score.toFixed(1) : '?'
+    row(`CVSS ${cvss.version}`, `${score} ${cvss.severity ?? ''} (${cvss.vector})`.trimEnd().replace(/^\s+/, ''))
+  }
+
+  const cwes = getCwes(container)
+  if (cwes.length > 0) row('CWE', cwes.join(', '))
+
+  const credits = container.credits ?? []
+  if (credits.length > 0) {
+    row('Credits', credits.map(summarizeCredit).join(', '))
+  }
+
+  const refs = container.references ?? []
+  if (refs.length > 0) {
+    const [first, ...rest] = refs.map(r => r?.url ?? '?')
+    row('References', first, ...rest)
+  }
+
+  if (container.x_generator?.engine) {
+    row('Generator', container.x_generator.engine)
+  }
+
+  out('')
+  return lines.join('\n')
+}

package/lib/prompt.js

@@ -0,0 +1,165 @@
+// Build an LLM audit prompt for a v5.2 CVE Record's natural-language
+// fields. The CLI side just prints the result; the user pastes it into
+// the LLM of their choice (no network call from this tool).
+//
+// What we ask the LLM to do:
+//   * audit the title against the OpenJS naming convention
+//   * audit the description for clarity, tone, and editorial rules
+//     (no PoCs, no em/en-dashes, no cross-references to other private
+//     advisories, references belong in cna.references[] not in prose)
+//   * return Markdown with a rating + a per-issue list including a
+//     suggested rewrite where applicable.
+//
+// The prompt embeds:
+//   * the title
+//   * the plain-text description (descriptions[0].value)
+//   * the raw Markdown if supportingMedia[0].type === text/markdown
+//   * a short facts block (affected, CVSS, CWE) so the LLM grounds its
+//     suggestions in what the vulnerability actually is.
+
+function getCna (record) {
+  return record?.containers?.cna ?? {}
+}
+
+function getDescription (cna) {
+  return cna?.descriptions?.find(d => d?.lang === 'en') ?? cna?.descriptions?.[0] ?? null
+}
+
+function getMarkdown (description) {
+  if (!description?.supportingMedia) return null
+  const media = description.supportingMedia.find(m => m?.type === 'text/markdown')
+  return media?.value ?? null
+}
+
+function summarizeAffected (cna) {
+  return (cna?.affected ?? []).map((a) => {
+    const product = `${a.vendor ?? '?'}:${a.product ?? '?'}`
+    const ranges = (a.versions ?? []).map((v) => {
+      if (v.lessThan) return `${v.version} → < ${v.lessThan}`
+      if (v.lessThanOrEqual) return `${v.version} → ≤ ${v.lessThanOrEqual}`
+      return v.version
+    })
+    return ranges.length === 0 ? product : `${product} (${ranges.join(', ')})`
+  })
+}
+
+function summarizeCvss (cna) {
+  for (const m of cna?.metrics ?? []) {
+    if (m?.cvssV3_1?.vectorString) {
+      const { vectorString, baseScore, baseSeverity } = m.cvssV3_1
+      return { label: 'CVSS 3.1', body: `${baseScore ?? '?'} ${baseSeverity ?? ''} (${vectorString})`.replace(/\s+/g, ' ').trim() }
+    }
+    if (m?.cvssV4_0?.vectorString) {
+      const { vectorString, baseScore, baseSeverity } = m.cvssV4_0
+      return { label: 'CVSS 4.0', body: `${baseScore ?? '?'} ${baseSeverity ?? ''} (${vectorString})`.replace(/\s+/g, ' ').trim() }
+    }
+  }
+  return null
+}
+
+function summarizeCwes (cna) {
+  const out = new Set()
+  for (const pt of cna?.problemTypes ?? []) {
+    for (const d of pt?.descriptions ?? []) {
+      if (d?.cweId) out.add(d.cweId)
+    }
+  }
+  return [...out]
+}
+
+// Generate the full LLM prompt as a string. Caller is responsible for
+// printing it; this stays pure so it's trivial to test.
+export function buildAuditPrompt (record) {
+  const cna = getCna(record)
+  const description = getDescription(cna)
+  const title = cna?.title ?? '(no title)'
+  const value = description?.value ?? '(no description)'
+  const markdown = getMarkdown(description)
+  const affected = summarizeAffected(cna)
+  const cvss = summarizeCvss(cna)
+  const cwes = summarizeCwes(cna)
+  const cveId = record?.cveMetadata?.cveId
+
+  const lines = []
+  lines.push(
+    'You are reviewing the natural-language fields of a CVE record before it ships to MITRE.',
+    'The fields are read by application developers and security tooling worldwide.',
+    'Be concise, factual, and editorial. Flag what should change and why.',
+    '',
+    '## Editorial guidelines',
+    '',
+    '**Title** (`cna.title`):',
+    '- Format: `<package> vulnerable to <Vulnerability Type>` or `<package> vulnerable to <Type> via <Vector>`.',
+    '- 6 to 15 words. Package name lowercase as it appears on npm.',
+    '- Spell out vulnerability classes (e.g. "Denial of Service", not "DoS"; "Cross-Site Scripting", not "XSS").',
+    '',
+    '**Description** (`cna.descriptions[0].value`):',
+    '- Plain English. No raw PoCs, exploit code, or step-by-step attack walkthroughs. Those belong in the advisory body, not the CVE record.',
+    '- No em-dashes (—) or en-dashes (–). Use periods or commas instead.',
+    '- No references to other private advisories (consumers cannot see them).',
+    '- URLs do **not** belong in the description prose. They live in `cna.references[]`. Flag any that leaked in.',
+    '- Match the tone of prior published advisories: short, neutral, factual. No alarmist language ("catastrophic", "blocks the entire event loop"). State facts.',
+    '- Sections (Impact / Patches / Workarounds) should be labelled clearly and read as standalone paragraphs.',
+    '',
+    '**General**:',
+    '- Confusing or ambiguous wording is a defect. Flag it.',
+    '- Inconsistencies between the title, description, and the facts block (affected, CWE, CVSS) are also defects.',
+    '- Do not invent facts. If a guideline cannot be evaluated from the text alone, say so.',
+    '',
+    '## Record context',
+    ''
+  )
+  if (cveId) lines.push(`- **CVE**: ${cveId}`)
+  if (affected.length > 0) lines.push(`- **Affected**: ${affected.join('; ')}`)
+  if (cvss) lines.push(`- **${cvss.label}**: ${cvss.body}`)
+  if (cwes.length > 0) lines.push(`- **CWE**: ${cwes.join(', ')}`)
+  lines.push(
+    '',
+    '## Title to audit',
+    '',
+    '```',
+    title,
+    '```',
+    '',
+    '## Description (plain-text value)',
+    '',
+    '```',
+    value,
+    '```'
+  )
+  if (markdown) {
+    lines.push(
+      '',
+      '## Description (original Markdown, from supportingMedia)',
+      '',
+      '```markdown',
+      markdown,
+      '```'
+    )
+  }
+  lines.push(
+    '',
+    '## Respond in this exact Markdown shape',
+    '',
+    '```markdown',
+    '**Rating**: ready | needs-work | blocked',
+    '',
+    '### Issues',
+    '',
+    '- **[field]** *(severity: blocker | warning | suggestion)*: what is wrong, in one sentence.',
+    '  - **Suggested rewrite**: a concrete replacement, OR "n/a" if the issue is about deletion / structure rather than wording.',
+    '',
+    '(Omit the Issues section entirely if Rating is "ready".)',
+    '',
+    '### Rewritten title (only if the title needs work)',
+    '',
+    'Single-line suggested replacement.',
+    '',
+    '### Rewritten description (only if the description needs material edits)',
+    '',
+    'A full replacement, in the same plain-text style as the original.',
+    '```',
+    ''
+  )
+  return lines.join('\n')
+}

package/lib/review/index.js

@@ -0,0 +1,78 @@
+// reviewRecord(record, { strict }) -> review report
+//
+// Sync, offline. Validates a full v5.2 CVE Record:
+//   { dataType, dataVersion, cveMetadata, containers: { cna: {...} } }
+//
+// MITRE's official schema check (via ajv) runs against the whole Record;
+// the editorial rules in ./rules.js then walk the inner cna container.
+
+import { RULES } from './rules.js'
+import { validateAgainstMitreSchema } from './schema.js'
+
+// `strict` defaults to true because publishing to MITRE is irreversible:
+// every warning the reviewer surfaces blocks until the operator opts out
+// explicitly via `--no-strict` (CLI) or `{ strict: false }` (library).
+export function reviewRecord (record, { strict = true } = {}) {
+  const issues = []
+
+  // MITRE schema first. Every schema violation is a blocker because
+  // publish will fail downstream — there is no soft version of "doesn't
+  // match the schema MITRE uses". One issue per ajv error so operators
+  // see exactly what's wrong.
+  for (const err of validateAgainstMitreSchema(record)) {
+    issues.push({
+      rule: 'mitre-schema',
+      // Schema violations always fail at MITRE's end too.
+      tier: 'mitre-common',
+      severity: 'blocker',
+      path: err.path,
+      message: err.message
+    })
+  }
+
+  // Editorial rules look at just the cna container — drill in once here.
+  const cna = record?.containers?.cna ?? {}
+
+  for (const rule of RULES) {
+    let result
+    try {
+      result = rule.check(cna)
+    } catch (e) {
+      // A buggy rule shouldn't fail the review. Surface as a warning so the
+      // operator knows to file an issue.
+      issues.push({
+        rule: `${rule.id}:internal-error`,
+        // Carry the source rule's tier through so the --tier filter still
+        // works in the unlikely event the rule itself blew up.
+        tier: rule.tier,
+        severity: 'warning',
+        path: 'reviewer',
+        message: `Rule '${rule.id}' threw: ${e.message}`
+      })
+      continue
+    }
+    if (result) {
+      issues.push({
+        rule: rule.id,
+        tier: rule.tier,
+        severity: strict && rule.severity === 'warning' ? 'blocker' : rule.severity,
+        path: result.path,
+        message: result.message
+      })
+    }
+  }
+
+  const blockers = issues.filter(i => i.severity === 'blocker').length
+  const warnings = issues.filter(i => i.severity === 'warning').length
+  const suggestions = issues.filter(i => i.severity === 'suggestion').length
+
+  let rating
+  if (blockers > 0) rating = 'blocked'
+  else if (warnings > 0) rating = 'needs-work'
+  else rating = 'ready'
+
+  return {
+    summary: { rating, blockers, warnings, suggestions, total: issues.length },
+    issues
+  }
+}