@gpzhang2001/sharpkit-reporting 0.2.1

package/src/state.ts

@@ -0,0 +1,250 @@
+/**
+ * Report state — port of strix report/state.py: the per-scan report store
+ * with sequential `vuln-NNNN` ids, strix's exact field insertion order,
+ * title cleaning, update whitelist with dependent-field dropping, update
+ * history, and hydration from a previous run dir. Key order matters: the
+ * stored dicts are JSON-serialized byte-for-byte into vulnerabilities.json,
+ * so fields are inserted in state.py `add_vulnerability_report` order.
+ * @module @gpzhang2001/sharpkit-reporting/state
+ */
+
+/** A stored vulnerability/dependency report dict (strix shape). */
+export interface VulnerabilityReport {
+  readonly id: string
+  title: string
+  severity: string
+  readonly timestamp: string
+  [key: string]: unknown
+}
+
+/** Injectable clock (tests pass fixed times; default wall clock). */
+export type Clock = () => Date
+
+/** strix display timestamp format (state.py :349). */
+export function formatTimestamp(date: Date): string {
+  const pad = (value: number): string => String(value).padStart(2, '0')
+  return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} UTC`
+}
+
+/** strix ISO instant format (start/end times). */
+export function formatIso(date: Date): string {
+  return date.toISOString().replace('Z', '+00:00')
+}
+
+/** Control-char → space + whitespace collapse (state.py `_clean_title`). */
+export function cleanTitle(title: string): string {
+  // eslint-disable-next-line no-control-regex -- strix strips exactly these control chars (state.py :36)
+  return title.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim()
+}
+
+/** strix severity order (tool.py `_SEVERITY_ORDER`). */
+export const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low', 'info', 'none'] as const
+
+/** Severity rank with unknown → last (writer parity). */
+export function severityRank(severity: string): number {
+  const index = (SEVERITY_ORDER as readonly string[]).indexOf(severity)
+  return index === -1 ? SEVERITY_ORDER.length : index
+}
+
+/** Field insertion order for optional string fields (state.py :352-396). */
+const OPTIONAL_STRING_FIELDS = [
+  'description', 'impact', 'target', 'technical_analysis', 'poc_description', 'poc_script_code',
+  'remediation_steps', 'evidence', 'assumptions', 'counterevidence', 'confidence_rationale',
+  'severity_change_conditions', 'fix_verification', 'fix_pr_body', 'endpoint', 'method', 'cve',
+] as const
+
+/** Lowercased optional fields (state.py `_LOWERCASE_REPORT_FIELDS` subset). */
+const LOWERCASE_FIELDS = new Set(['confidence', 'fix_effort'])
+
+/** Updatable field whitelist (state.py `UPDATABLE_REPORT_FIELDS`). */
+export const UPDATABLE_REPORT_FIELDS = new Set([
+  'title', 'dependency_metadata', 'severity', 'description', 'impact', 'target', 'technical_analysis',
+  'poc_description', 'poc_script_code', 'remediation_steps', 'evidence', 'assumptions', 'counterevidence',
+  'confidence', 'confidence_rationale', 'severity_change_conditions', 'fix_effort', 'cvss', 'cvss_breakdown',
+  'endpoint', 'method', 'cve', 'cwe', 'code_locations', 'fix_verification', 'fix_pr_body',
+])
+
+/** Dependent fields dropped when their primary changes without replacement. */
+export const DEPENDENT_REPORT_FIELDS: Readonly<Record<string, string>> = {
+  confidence: 'confidence_rationale',
+  severity: 'severity_change_conditions',
+  cvss: 'cvss_breakdown',
+  code_locations: 'fix_verification',
+}
+
+/** One update-history entry (state.py :467-487). */
+export interface UpdateHistoryEntry {
+  readonly timestamp: string
+  fields: string[]
+  dropped_fields?: string[]
+  reason?: string
+  agent_id?: string
+  agent_name?: string
+  previous_severity?: string
+  previous_cvss?: number
+  previous_confidence?: string
+}
+
+export interface AddReportInput {
+  readonly title: string
+  readonly severity: string
+  readonly findingClass?: string | undefined
+  readonly dependencyMetadata?: Record<string, unknown> | undefined
+  readonly agentId?: string | undefined
+  readonly agentName?: string | undefined
+  /** All remaining report fields (already validated/normalized by the tool layer). */
+  readonly fields: Record<string, unknown>
+}
+
+/** The revision outcome: null = no-op (strix parity). */
+export type UpdateOutcome =
+  | { readonly report: VulnerabilityReport }
+  | { readonly noop: true }
+
+/**
+ * One scan's report store. Not a process singleton — the suite runs one per
+ * scan id inside the tool package's closure (strix's module-global maps to a
+ * per-scan instance in dsh).
+ */
+export class ReportState {
+  readonly runId: string
+  runName: string | null
+  readonly startTime: string
+  endTime: string | null = null
+  status = 'running'
+  finalScanResult: string | null = null
+  readonly vulnerabilityReports: VulnerabilityReport[] = []
+  /** Ids already rendered to markdown (incremental writer input). */
+  readonly savedVulnIds = new Set<string>()
+  updateHistoryAgent: { readonly agentId?: string; readonly agentName?: string } | undefined
+  private readonly clock: Clock
+
+  constructor(options: { readonly runId?: string; readonly runName?: string | null; readonly clock?: Clock } = {}) {
+    this.clock = options.clock ?? (() => new Date())
+    this.runId = options.runId ?? `run-${Math.random().toString(16).slice(2, 10)}`
+    this.runName = options.runName ?? null
+    this.startTime = formatIso(this.clock())
+  }
+
+  /** Allocate the next sequential id (state.py :343 — length-derived). */
+  private nextId(): string {
+    return `vuln-${String(this.vulnerabilityReports.length + 1).padStart(4, '0')}`
+  }
+
+  /**
+   * Add one report with strix's exact field construction order.
+   * @param input - the validated/normalized create payload.
+   */
+  addVulnerabilityReport(input: AddReportInput): VulnerabilityReport {
+    const report: Record<string, unknown> = {
+      id: this.nextId(),
+      title: cleanTitle(input.title),
+      severity: input.severity.toLowerCase().trim(),
+      timestamp: formatTimestamp(this.clock()),
+    }
+    for (const field of OPTIONAL_STRING_FIELDS) {
+      const value = input.fields[field]
+      if (typeof value === 'string' && value.trim() !== '') report[field] = value.trim()
+    }
+    const confidence = input.fields['confidence']
+    if (typeof confidence === 'string' && confidence.trim() !== '') report['confidence'] = confidence.trim().toLowerCase()
+    const fixEffort = input.fields['fix_effort']
+    if (typeof fixEffort === 'string' && fixEffort.trim() !== '') report['fix_effort'] = fixEffort.trim().toLowerCase()
+    const cvss = input.fields['cvss']
+    if (cvss !== null && cvss !== undefined) report['cvss'] = cvss
+    const breakdown = input.fields['cvss_breakdown']
+    if (breakdown !== null && breakdown !== undefined && Object.keys(breakdown as object).length > 0) report['cvss_breakdown'] = breakdown
+    const cwe = input.fields['cwe']
+    if (typeof cwe === 'string' && cwe.trim() !== '') report['cwe'] = cwe.trim()
+    const codeLocations = input.fields['code_locations']
+    if (codeLocations !== null && codeLocations !== undefined && (codeLocations as unknown[]).length > 0) report['code_locations'] = codeLocations
+    report['finding_class'] = (input.findingClass ?? 'dynamic').toLowerCase().trim()
+    if (input.dependencyMetadata !== undefined && Object.keys(input.dependencyMetadata).length > 0) report['dependency_metadata'] = input.dependencyMetadata
+    if (input.agentId !== undefined && input.agentId !== '') report['agent_id'] = input.agentId
+    if (input.agentName !== undefined && input.agentName !== '') report['agent_name'] = input.agentName
+    const frozen = report as VulnerabilityReport
+    this.vulnerabilityReports.push(frozen)
+    return frozen
+  }
+
+  /**
+   * Revise one report in place (state.py `update_vulnerability_report`):
+   * whitelist + strip/lowercase, unchanged-skip, dependent-field dropping,
+   * history append, and the MD invalidation marker.
+   * @param reportId - the `vuln-NNNN` id.
+   * @param changes - only the fields the model passed.
+   * @param reason - the update_reason (truncated to 500).
+   */
+  updateVulnerabilityReport(reportId: string, changes: Record<string, unknown>, reason: string): UpdateOutcome {
+    const report = this.vulnerabilityReports.find(entry => entry.id === reportId)
+    if (report === undefined) return { noop: true }
+    const mutable = report as Record<string, unknown>
+    const changed: string[] = []
+    const dropped: string[] = []
+    const history: UpdateHistoryEntry = {
+      timestamp: formatTimestamp(this.clock()),
+      fields: [],
+      reason: reason.slice(0, 500),
+      ...(this.updateHistoryAgent?.agentId !== undefined ? { agent_id: this.updateHistoryAgent.agentId } : {}),
+      ...(this.updateHistoryAgent?.agentName !== undefined ? { agent_name: this.updateHistoryAgent.agentName } : {}),
+    }
+    const previous: { severity?: string; cvss?: number; confidence?: string } = {}
+    for (const [field, rawValue] of Object.entries(changes)) {
+      if (!UPDATABLE_REPORT_FIELDS.has(field)) continue
+      let value: unknown = rawValue
+      if (field === 'title' && typeof value === 'string') value = cleanTitle(value)
+      else if (typeof value === 'string') value = value.trim()
+      if (LOWERCASE_FIELDS.has(field) && typeof value === 'string') value = value.toLowerCase()
+      if (Object.is(mutable[field], value)) continue
+      if (JSON.stringify(mutable[field]) === JSON.stringify(value)) continue
+      if (mutable[field] !== undefined) {
+        if (field === 'severity') previous.severity = mutable['severity'] as string
+        if (field === 'cvss') previous.cvss = mutable['cvss'] as number
+        if (field === 'confidence') previous.confidence = mutable['confidence'] as string
+      }
+      const dependent = DEPENDENT_REPORT_FIELDS[field]
+      if (dependent !== undefined && mutable[dependent] !== undefined && changes[dependent] === undefined) {
+        delete mutable[dependent]
+        dropped.push(dependent)
+      }
+      mutable[field] = value
+      changed.push(field)
+    }
+    if (changed.length === 0 && dropped.length === 0) return { noop: true }
+    history.fields = [...changed].sort()
+    if (dropped.length > 0) history.dropped_fields = [...dropped].sort()
+    if (previous.severity !== undefined) history.previous_severity = previous.severity
+    if (previous.cvss !== undefined) history.previous_cvss = previous.cvss
+    if (previous.confidence !== undefined) history.previous_confidence = previous.confidence
+    const historyList = (mutable['update_history'] as UpdateHistoryEntry[] | undefined) ?? []
+    historyList.push(history)
+    mutable['update_history'] = historyList
+    mutable['updated_at'] = history.timestamp
+    this.savedVulnIds.delete(reportId)
+    return { report }
+  }
+
+  /**
+   * Reload from a previous run's vulnerabilities.json so id allocation does
+   * not collide (state.py `hydrate_from_run_dir`; raises on corrupt JSON).
+   * @param reports - the parsed JSON array.
+   */
+  hydrate(reports: unknown): void {
+    if (!Array.isArray(reports)) throw new Error('corrupt vulnerabilities.json: expected a list of reports')
+    for (const entry of reports) {
+      const report = entry as Record<string, unknown>
+      if (report['finding_class'] === undefined) {
+        report['finding_class'] = report['dependency_metadata'] !== undefined ? 'dependency_cve' : 'dynamic'
+      }
+      if (typeof report['title'] === 'string') report['title'] = cleanTitle(report['title'])
+      this.vulnerabilityReports.push(report as VulnerabilityReport)
+      if (typeof report['id'] === 'string') this.savedVulnIds.add(report['id'])
+    }
+  }
+
+  /** Mark the run complete (status transition + end time). */
+  complete(exitStatus = 'completed'): void {
+    this.endTime = formatIso(this.clock())
+    this.status = exitStatus
+  }
+}

package/src/writers.ts

@@ -0,0 +1,316 @@
+/**
+ * Artifact writers — port of strix report/writer.py: atomic writes
+ * (temp-in-same-dir + rename, no fsync), run.json, vulnerabilities.csv
+ * (formula-injection guard, \r\n terminators, uppercase severity,
+ * severity-then-timestamp ordering), vulnerabilities.json (byte-identical
+ * serialization), the vuln-NNNN.md renderer (exact section order), and the
+ * executive report template.
+ * @module @gpzhang2001/sharpkit-reporting/writers
+ */
+
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { SEVERITY_ORDER, severityRank, type VulnerabilityReport } from './state.ts'
+
+/** JSON.stringify with Python `json.dumps(ensure_ascii=False, indent=2)` parity. */
+export function dumpsIndent(value: unknown): string {
+  return JSON.stringify(value, null, 2)
+}
+
+/**
+ * Atomic text write (writer.py `atomic_write_text` :201-220): temp file in
+ * the target's directory + rename; no fsync (strix parity).
+ * @param path - target file path.
+ * @param payload - exact bytes to write.
+ */
+export async function atomicWriteText(path: string, payload: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  const temp = `${dirname(path)}/.${join('', basenameOf(path))}.${process.pid}.tmp`
+  await writeFile(temp, payload, 'utf8')
+  await rename(temp, path)
+}
+
+function basenameOf(path: string): string {
+  const index = path.lastIndexOf('/')
+  return index === -1 ? path : path.slice(index + 1)
+}
+
+/**
+ * Formula-injection guard (writer.py `csv_safe` :35-53): prefix `'` when the
+ * rendered cell starts with `= + - @ \t \r`.
+ * @param value - the cell value.
+ */
+export function csvSafe(value: string): string {
+  return /^[=+\-@\t\r]/.test(value) ? `'${value}` : value
+}
+
+/** CSV columns (writer.py :165-184). */
+const CSV_COLUMNS = ['id', 'title', 'severity', 'timestamp', 'file'] as const
+
+/** CSV-escape one cell per RFC 4180 as Python's csv module does. */
+function csvCell(value: string): string {
+  const safe = csvSafe(value)
+  if (safe.includes('"') || safe.includes(',') || safe.includes('\r') || safe.includes('\n')) {
+    return `"${safe.replace(/"/g, '""')}"`
+  }
+  return safe
+}
+
+/**
+ * Render vulnerabilities.csv: header + rows sorted by (severity rank,
+ * timestamp), uppercase severity, \r\n terminators.
+ * @param reports - the stored reports.
+ */
+export function renderVulnerabilitiesCsv(reports: readonly VulnerabilityReport[]): string {
+  const sorted = [...reports].sort((a, b) =>
+    severityRank(String(a.severity)) - severityRank(String(b.severity))
+    || String(a.timestamp).localeCompare(String(b.timestamp)),
+  )
+  const lines = [CSV_COLUMNS.join(',')]
+  for (const report of sorted) {
+    const cells = [
+      csvCell(String(report.id)),
+      csvCell(String(report.title)),
+      csvCell(String(report.severity).toUpperCase()),
+      csvCell(String(report.timestamp)),
+      csvCell(`vulnerabilities/${String(report.id)}.md`),
+    ]
+    lines.push(cells.join(','))
+  }
+  return `${lines.join('\r\n')}\r\n`
+}
+
+/** title-case one word (strix Confidence/Fix Effort display). */
+function titleCase(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1)
+}
+
+/** Safe fence length: one longer than the longest backtick run (writer.py :56-66). */
+function safeFence(code: string): string {
+  let longest = 0
+  let current = 0
+  for (const char of code) {
+    if (char === '`') {
+      current++
+      longest = Math.max(longest, current)
+    } else {
+      current = 0
+    }
+  }
+  return '`'.repeat(Math.max(3, longest + 1))
+}
+
+/** Unwrap an existing fence and return its language (writer.py :69-82). */
+function parseFencedCode(code: string): { readonly language: string; readonly body: string } {
+  const match = /^```([A-Za-z0-9_+-]*)\n([\s\S]*?)\n?```$/.exec(code.trim())
+  if (match === null) return { language: '', body: code }
+  return { language: match[1] ?? '', body: match[2] ?? '' }
+}
+
+/** Guess a fenced language for a PoC script (writer.py :107-116). */
+function guessLanguageName(code: string): string {
+  if (/^\s*(import |from |def |class |print\()/.test(code)) return 'python'
+  if (/^\s*(const |let |var |function |require\()/.test(code)) return 'javascript'
+  if (/^\s*(curl |GET |POST |PUT |DELETE )/.test(code)) return 'bash'
+  return 'python'
+}
+
+/** Metadata lines of the vuln markdown header block (writer.py :222-259 order). */
+function renderMetadataLines(report: Record<string, unknown>): string[] {
+  const lines: string[] = [`**ID:** ${String(report['id'])}`, `**Severity:** ${String(report['severity']).toUpperCase()}`, `**Found:** ${String(report['timestamp'])}`]
+  const depMeta = (report['dependency_metadata'] as Record<string, unknown> | null | undefined) ?? {}
+  const cvss = report['cvss']
+  const metadata: Array<[string, unknown]> = [
+    ['Target', report['target']],
+    ['Package', depMeta['package_name']],
+    ['Ecosystem', depMeta['package_ecosystem']],
+    ['Installed Version', depMeta['installed_version']],
+    ['Fixed Version', depMeta['fixed_version']],
+    ['Introduced By', depMeta['introduced_by']],
+    ['Dependency Chain', depMeta['dependency_path']],
+    ['Endpoint', report['endpoint']],
+    ['Method', report['method']],
+    ['CVE', report['cve']],
+    ['CWE', report['cwe']],
+  ]
+  if (cvss !== null && cvss !== undefined) metadata.push(['CVSS', cvss])
+  const advisory = depMeta['advisory_cvss']
+  if (advisory !== null && advisory !== undefined && advisory !== cvss) metadata.push(['Advisory CVSS', advisory])
+  if (depMeta['contextual_cvss_vector'] !== undefined && depMeta['contextual_cvss_vector'] !== null && depMeta['contextual_cvss_vector'] !== '') {
+    metadata.push(['Contextual CVSS Vector', depMeta['contextual_cvss_vector']])
+  }
+  if (report['confidence'] !== undefined && report['confidence'] !== null && report['confidence'] !== '') {
+    metadata.push(['Confidence', titleCase(String(report['confidence']))])
+  }
+  if (report['fix_effort'] !== undefined && report['fix_effort'] !== null && report['fix_effort'] !== '') {
+    metadata.push(['Fix Effort', titleCase(String(report['fix_effort']))])
+  }
+  for (const [label, value] of metadata) {
+    if (value !== null && value !== undefined && value !== '') lines.push(`**${label}:** ${String(value)}`)
+  }
+  return lines
+}
+
+/** One code-location section (writer.py :315-342, 2-space indents verbatim). */
+function renderCodeLocation(location: Record<string, unknown>, index: number): string[] {
+  const lines: string[] = ['## Code Analysis', '']
+  const file = String(location['file'] ?? 'unknown')
+  const start = location['start_line']
+  const end = location['end_line']
+  let lineLabel = ''
+  if (start !== null && start !== undefined) {
+    lineLabel = end !== undefined && end !== null && end !== start ? ` (lines ${String(start)}-${String(end)})` : ` (line ${String(start)})`
+  }
+  lines.push(`**Location ${String(index + 1)}:** \`${file}\`${lineLabel}`)
+  const label = location['label']
+  if (typeof label === 'string' && label !== '') lines.push(`  ${label}`)
+  const snippet = location['snippet']
+  if (typeof snippet === 'string' && snippet !== '') {
+    const fence = safeFence(snippet)
+    lines.push(`  ${fence}`)
+    for (const line of snippet.split('\n')) lines.push(`  ${line}`)
+    lines.push(`  ${fence}`)
+  }
+  const fixBefore = location['fix_before']
+  const fixAfter = location['fix_after']
+  if ((typeof fixBefore === 'string' && fixBefore !== '') || (typeof fixAfter === 'string' && fixAfter !== '')) {
+    lines.push('')
+    lines.push('  **Suggested Fix:**')
+    lines.push('```diff')
+    if (typeof fixBefore === 'string' && fixBefore !== '') for (const line of fixBefore.split('\n')) lines.push(`- ${line}`)
+    if (typeof fixAfter === 'string' && fixAfter !== '') for (const line of fixAfter.split('\n')) lines.push(`+ ${line}`)
+    lines.push('```')
+  }
+  lines.push('')
+  return lines
+}
+
+/** Update history section (writer.py `render_update_history` :364-396). */
+export function renderUpdateHistory(report: Record<string, unknown>): string[] {
+  const history = report['update_history'] as ReadonlyArray<Record<string, unknown>> | undefined
+  if (history === undefined || history.length === 0) return []
+  const lines: string[] = ['## Update History', '']
+  for (const entry of history) {
+    const who = (entry['agent_name'] as string | undefined) ?? (entry['agent_id'] as string | undefined) ?? 'an agent'
+    const fields = (entry['fields'] as readonly string[] | undefined)?.join(', ') ?? ''
+    lines.push(`**${String(entry['timestamp'])}** — ${who} updated: ${fields}`)
+    const dropped = entry['dropped_fields'] as readonly string[] | undefined
+    if (dropped !== undefined && dropped.length > 0) lines.push(`  Dropped as superseded: ${dropped.join(', ')}`)
+    const previousSeverity = entry['previous_severity']
+    if (typeof previousSeverity === 'string') lines.push(`  Previous severity: ${previousSeverity}`)
+    const previousCvss = entry['previous_cvss']
+    if (previousCvss !== undefined && previousCvss !== null) lines.push(`  Previous CVSS: ${String(previousCvss)}`)
+    const previousConfidence = entry['previous_confidence']
+    if (typeof previousConfidence === 'string') lines.push(`  Previous confidence: ${previousConfidence}`)
+    const reason = entry['reason']
+    if (typeof reason === 'string' && reason !== '') lines.push(`  Reason: ${reason}`)
+    lines.push('')
+  }
+  return lines
+}
+
+/**
+ * Render one vulnerability markdown document (writer.py
+ * `render_vulnerability_md` :223-361 section order).
+ * @param report - the stored report dict.
+ */
+export function renderVulnerabilityMd(report: VulnerabilityReport): string {
+  const record = report as unknown as Record<string, unknown>
+  const lines: string[] = [`# ${String(record['title'])}`, '']
+  lines.push(...renderMetadataLines(record), '')
+
+  const section = (heading: string, field: string): void => {
+    const value = record[field]
+    if (typeof value === 'string' && value !== '') lines.push(`## ${heading}`, '', value, '')
+  }
+  section('Description', 'description')
+  section('Evidence', 'evidence')
+  section('Impact', 'impact')
+  section('Counterevidence', 'counterevidence')
+  section('Confidence Rationale', 'confidence_rationale')
+  section('What Would Change This Severity', 'severity_change_conditions')
+  section('Technical Analysis', 'technical_analysis')
+
+  const metadata = record['dependency_metadata'] as Record<string, unknown> | undefined
+  const contextualReasoning = metadata?.['contextual_cvss_reasoning']
+  if (typeof contextualReasoning === 'string' && contextualReasoning !== '') {
+    lines.push('## Contextual CVSS', '', contextualReasoning, '')
+  }
+
+  const pocDescription = record['poc_description']
+  const pocScript = record['poc_script_code']
+  if ((typeof pocDescription === 'string' && pocDescription !== '') || (typeof pocScript === 'string' && pocScript !== '')) {
+    lines.push('## Proof of Concept', '')
+    if (typeof pocDescription === 'string' && pocDescription !== '') lines.push(pocDescription, '')
+    if (typeof pocScript === 'string' && pocScript !== '') {
+      const fenced = parseFencedCode(pocScript)
+      const language = fenced.language !== '' ? fenced.language : guessLanguageName(fenced.body)
+      const fence = safeFence(fenced.body)
+      lines.push(`${fence}${language}`, fenced.body, fence, '')
+    }
+  }
+
+  const locations = record['code_locations'] as ReadonlyArray<Record<string, unknown>> | undefined
+  if (locations !== undefined && locations.length > 0) {
+    for (const [index, location] of locations.entries()) lines.push(...renderCodeLocation(location, index))
+  }
+
+  section('Remediation', 'remediation_steps')
+  section('Fix Verification', 'fix_verification')
+  section('Assumptions', 'assumptions')
+  lines.push(...renderUpdateHistory(record))
+  return lines.join('\n')
+}
+
+/**
+ * Write the per-run artifacts handled outside SARIF (writer.py parity):
+ * vulnerabilities/*.md (incremental), vulnerabilities.csv,
+ * vulnerabilities.json.
+ * @param runDir - the run directory.
+ * @param reports - all stored reports.
+ * @param savedIds - ids whose MD is already on disk (updated ids must be re-rendered by the caller removing them).
+ */
+export async function writeVulnerabilities(
+  runDir: string,
+  reports: readonly VulnerabilityReport[],
+  savedIds: ReadonlySet<string>,
+): Promise<void> {
+  for (const report of reports) {
+    if (savedIds.has(report.id)) continue
+    await atomicWriteText(join(runDir, 'vulnerabilities', `${report.id}.md`), renderVulnerabilityMd(report))
+  }
+  await atomicWriteText(join(runDir, 'vulnerabilities.csv'), renderVulnerabilitiesCsv(reports))
+  await atomicWriteText(join(runDir, 'vulnerabilities.json'), dumpsIndent(reports))
+}
+
+/**
+ * Write the assembled coverage document (coverage.py `write_coverage`).
+ * @param runDir - the run directory.
+ * @param document - the assembled coverage document.
+ */
+export async function writeCoverage(runDir: string, document: Record<string, unknown>): Promise<void> {
+  await atomicWriteText(join(runDir, 'coverage.json'), dumpsIndent(document))
+}
+
+/**
+ * Write run.json last (state.py ordering).
+ * @param runDir - the run directory.
+ * @param runRecord - the run record dict.
+ */
+export async function writeRunRecord(runDir: string, runRecord: Record<string, unknown>): Promise<void> {
+  await atomicWriteText(join(runDir, 'run.json'), dumpsIndent(runRecord))
+}
+
+/**
+ * Write the executive report (plain truncate-write, writer.py :139-145).
+ * @param runDir - the run directory.
+ * @param finalScanResult - the composed final report body.
+ * @param generatedAt - display timestamp.
+ */
+export async function writeExecutiveReport(runDir: string, finalScanResult: string, generatedAt: string): Promise<void> {
+  await mkdir(runDir, { recursive: true })
+  await writeFile(join(runDir, 'penetration_test_report.md'), `# Security Penetration Test Report\n\n**Generated:** ${generatedAt}\n\n${finalScanResult}`, 'utf8')
+}
+
+/** Severity list used by callers that need the canonical order. */
+export const severityOrder = SEVERITY_ORDER