npm - @nebulacomponents/citable - Versions diffs - 1.16.0 → 1.18.0 - Mend

@nebulacomponents/citable 1.16.0 → 1.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (142) hide show

package/src/commands/sweep.js ADDED Viewed

@@ -0,0 +1,357 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { parse as parseHtml } from 'node-html-parser';
+import { buildContext } from './context.js';
+import { selectDetectors } from '../detectors/index.js';
+import { runDetectors, indexTargets, pageSubject, safePath } from '../detectors/framework.js';
+/**
+ * CWV standard thresholds per Google / web.dev guidance
+ */
+export const CWV_THRESHOLDS = {
+  lcp: { unit: 's', good: 2.5, needs_improvement: 4.0, description: 'Largest Contentful Paint' },
+  inp: { unit: 'ms', good: 200, needs_improvement: 500, description: 'Interaction to Next Paint' },
+  cls: { unit: 'score', good: 0.1, needs_improvement: 0.25, description: 'Cumulative Layout Shift' },
+  fcp: { unit: 's', good: 1.8, needs_improvement: 3.0, description: 'First Contentful Paint' },
+  ttfb: { unit: 'ms', good: 800, needs_improvement: 1800, description: 'Time to First Byte' },
+};
+/**
+ * Evaluate static DOM heuristics for Core Web Vitals readiness
+ */
+export function evaluateStaticCwv(page) {
+  const issues = [];
+  const heuristics = {
+    lcp_blockers: 0,
+    inp_risks: 0,
+    cls_risks: 0,
+    unsized_images: 0,
+    total_images: 0,
+    render_blocking_scripts: 0,
+    head_stylesheets: 0,
+    lazy_above_fold: 0,
+    missing_preconnect: false,
+    dom_nodes: page.domNodeCount || 0,
+    max_dom_depth: page.maxDomDepth || 0,
+  };
+  const html = page.html || '';
+  const root = parseHtml(html);
+  const head = root.querySelector('head');
+  // 1. LCP checks
+  if (head) {
+    const scripts = head.querySelectorAll('script:not([async]):not([defer])');
+    for (const s of scripts) {
+      const src = s.getAttribute('src');
+      if (src && !src.includes('analytics') && !src.includes('tracking')) {
+        heuristics.render_blocking_scripts++;
+      }
+    }
+    const stylesheets = head.querySelectorAll('link[rel="stylesheet"]');
+    heuristics.head_stylesheets = stylesheets.length;
+    const preconnects = head.querySelectorAll('link[rel="preconnect"]');
+    const fontLinks = head.querySelectorAll('link[href*="fonts.googleapis.com"], link[href*="fonts.gstatic.com"], link[href*="typekit.net"]');
+    if (fontLinks.length > 0 && preconnects.length === 0) {
+      heuristics.missing_preconnect = true;
+      issues.push({
+        vitals: 'FCP/LCP',
+        severity: 'low',
+        issue: 'External font origin without preconnect link hint',
+        remediation: 'Add <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>',
+      });
+    }
+  }
+  if (heuristics.render_blocking_scripts > 0) {
+    heuristics.lcp_blockers += heuristics.render_blocking_scripts;
+    issues.push({
+      vitals: 'LCP',
+      severity: 'high',
+      issue: `${heuristics.render_blocking_scripts} render-blocking script(s) in <head>`,
+      remediation: 'Add async or defer attributes, or move scripts to end of <body>',
+    });
+  }
+  if (heuristics.head_stylesheets > 5) {
+    heuristics.lcp_blockers++;
+    issues.push({
+      vitals: 'LCP',
+      severity: 'medium',
+      issue: `${heuristics.head_stylesheets} stylesheets in <head> may delay first paint`,
+      remediation: 'Inline critical CSS and defer non-critical stylesheets',
+    });
+  }
+  // Hero image / lazy loading
+  const imgs = root.querySelectorAll('img');
+  heuristics.total_images = imgs.length;
+  for (const img of imgs) {
+    const src = img.getAttribute('src') || '';
+    const width = img.getAttribute('width');
+    const height = img.getAttribute('height');
+    const loading = (img.getAttribute('loading') || '').toLowerCase();
+    if (!width || !height) {
+      heuristics.unsized_images++;
+    }
+    const numWidth = parseInt(width || '0', 10);
+    if (numWidth > 400 && loading === 'lazy') {
+      heuristics.lazy_above_fold++;
+      heuristics.lcp_blockers++;
+      issues.push({
+        vitals: 'LCP',
+        severity: 'high',
+        issue: `Large hero image (${src || '<img>'}) uses loading="lazy", delaying LCP`,
+        remediation: 'Remove loading="lazy" and add fetchpriority="high" to above-fold hero images',
+      });
+    }
+  }
+  // 2. CLS checks
+  if (heuristics.unsized_images > 0) {
+    heuristics.cls_risks += heuristics.unsized_images;
+    issues.push({
+      vitals: 'CLS',
+      severity: 'medium',
+      issue: `${heuristics.unsized_images} of ${heuristics.total_images} image(s) lack explicit width/height dimensions`,
+      remediation: 'Set explicit width and height attributes or CSS aspect-ratio on all image elements',
+    });
+  }
+  // 3. INP checks
+  if (heuristics.dom_nodes > 1500) {
+    heuristics.inp_risks++;
+    issues.push({
+      vitals: 'INP',
+      severity: heuristics.dom_nodes > 3000 ? 'high' : 'medium',
+      issue: `Excessive DOM size: ${heuristics.dom_nodes} nodes (Google recommends <= 1,500)`,
+      remediation: 'Simplify DOM hierarchy, virtualize large lists, and defer non-critical components',
+    });
+  }
+  if (heuristics.max_dom_depth > 32) {
+    heuristics.inp_risks++;
+    issues.push({
+      vitals: 'INP',
+      severity: 'medium',
+      issue: `Deep DOM nesting: maximum depth ${heuristics.max_dom_depth} (Google recommends <= 32)`,
+      remediation: 'Flatten nested layout wrapper containers',
+    });
+  }
+  // Determine readiness status per vital
+  const lcpStatus = heuristics.lcp_blockers === 0 ? 'good' : heuristics.lcp_blockers <= 2 ? 'needs_improvement' : 'poor';
+  const inpStatus = heuristics.inp_risks === 0 ? 'good' : heuristics.inp_risks <= 1 ? 'needs_improvement' : 'poor';
+  const clsStatus = heuristics.cls_risks === 0 ? 'good' : heuristics.cls_risks <= 2 ? 'needs_improvement' : 'poor';
+  return {
+    fact_status: 'deterministic_readiness_audit',
+    status: {
+      lcp: lcpStatus,
+      inp: inpStatus,
+      cls: clsStatus,
+      fcp: heuristics.missing_preconnect || heuristics.render_blocking_scripts > 0 ? 'needs_improvement' : 'good',
+      ttfb: 'unassessed_without_server_telemetry',
+    },
+    heuristics,
+    issues,
+  };
+}
+/**
+ * Search recent audit runs for observed performance telemetry
+ */
+function findObservedPerformance(root, targetUrl) {
+  const runsDir = path.join(root, '.citable', 'runs');
+  if (!fs.existsSync(runsDir)) return null;
+  try {
+    const runs = fs.readdirSync(runsDir).sort().reverse();
+    for (const run of runs) {
+      const obsDir = path.join(runsDir, run, 'observations');
+      if (!fs.existsSync(obsDir)) continue;
+      const obsFiles = fs.readdirSync(obsDir).filter((f) => f.includes('performance') && f.endsWith('.json'));
+      for (const file of obsFiles) {
+        const obs = JSON.parse(fs.readFileSync(path.join(obsDir, file), 'utf8'));
+        if (obs.kind === 'performance' && obs.state === 'observed') {
+          return {
+            source_run: run,
+            provider: obs.data?.provider || 'Lighthouse',
+            evidence_type: obs.data?.evidence_type || 'lab',
+            metrics: {
+              lcp_ms: obs.data?.largest_contentful_paint_ms ?? null,
+              fcp_ms: obs.data?.first_contentful_paint_ms ?? null,
+              cls: obs.data?.cumulative_layout_shift ?? null,
+              tbt_ms: obs.data?.total_blocking_time_ms ?? null,
+              score: obs.data?.performance_score ?? null,
+            },
+            collected_at: obs.collected_at,
+          };
+        }
+      }
+    }
+  } catch {
+    // Ignore non-blocking read errors
+  }
+  return null;
+}
+/**
+ * `citable sweep technical` — execute a technical SEO sweep with Core Web Vitals metrics.
+ */
+export async function sweepTechnical(root, { target, baseUrl, refDate, page: pageFilter } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) {
+    throw new Error('technical sweep requires a site target (built output directory or URL)');
+  }
+  // 1. Run technical detectors: TECH, CRAWL, CWV, ARCH, STATUS, LINK
+  const technicalDetectors = selectDetectors({
+    namespaces: ['TECH', 'CRAWL', 'CWV', 'ARCH', 'STATUS', 'LINK'],
+  });
+  const { findings } = runDetectors(technicalDetectors, ctx);
+  // 2. Select target pages
+  let pages = indexTargets(ctx);
+  if (pageFilter) {
+    const wanted = safePath(pageFilter, ctx.site.baseUrl);
+    pages = pages.filter((p) => safePath(p.url) === wanted || p.sourceFile === pageFilter);
+    if (!pages.length) throw new Error(`page not found in audited output: ${pageFilter}`);
+  }
+  // 3. Aggregate Core Web Vitals across audited pages
+  const pageVitals = [];
+  let totalLcpBlockers = 0;
+  let totalInpRisks = 0;
+  let totalClsRisks = 0;
+  let totalUnsizedImages = 0;
+  let totalImagesCount = 0;
+  for (const page of pages) {
+    const staticCwv = evaluateStaticCwv(page);
+    totalLcpBlockers += staticCwv.heuristics.lcp_blockers;
+    totalInpRisks += staticCwv.heuristics.inp_risks;
+    totalClsRisks += staticCwv.heuristics.cls_risks;
+    totalUnsizedImages += staticCwv.heuristics.unsized_images;
+    totalImagesCount += staticCwv.heuristics.total_images;
+    const observed = findObservedPerformance(root, page.url);
+    pageVitals.push({
+      url: page.url,
+      status: page.status,
+      cwv_readiness: staticCwv.status,
+      heuristics: staticCwv.heuristics,
+      issues: staticCwv.issues,
+      observed_telemetry: observed,
+    });
+  }
+  // 4. Crawl and indexability health summary
+  const non200Pages = pages.filter((p) => p.status !== 200);
+  const noindexPages = pages.filter((p) => p.noindex);
+  const canonicalMismatches = pages.filter((p) => p.canonicals.length === 0 || p.canonicals.length > 1);
+  // 5. Findings categorization
+  const criticalFindings = findings.filter((f) => f.classification.severity === 'critical');
+  const highFindings = findings.filter((f) => f.classification.severity === 'high');
+  const mediumFindings = findings.filter((f) => f.classification.severity === 'medium');
+  const lowFindings = findings.filter((f) => f.classification.severity === 'low' || f.classification.severity === 'informational');
+  // Overall posture
+  let overallHealth = 'optimal';
+  if (criticalFindings.length > 0 || non200Pages.length > 0) {
+    overallHealth = 'critical_blockers';
+  } else if (highFindings.length > 0 || totalLcpBlockers > 3 || totalClsRisks > 5) {
+    overallHealth = 'needs_attention';
+  }
+  const result = {
+    target: ctx.site.baseUrl || target,
+    total_pages_audited: pages.length,
+    overall_health: overallHealth,
+    crawl_and_indexability: {
+      status_200_count: pages.length - non200Pages.length,
+      non_200_count: non200Pages.length,
+      noindex_count: noindexPages.length,
+      canonical_issues_count: canonicalMismatches.length,
+      details: non200Pages.map((p) => ({ url: p.url, status: p.status })),
+    },
+    core_web_vitals: {
+      thresholds: CWV_THRESHOLDS,
+      summary: {
+        lcp_readiness: totalLcpBlockers === 0 ? 'good' : totalLcpBlockers <= 2 ? 'needs_improvement' : 'poor',
+        inp_readiness: totalInpRisks === 0 ? 'good' : 'needs_improvement',
+        cls_readiness: totalClsRisks === 0 ? 'good' : 'needs_improvement',
+        total_lcp_blockers: totalLcpBlockers,
+        total_inp_risks: totalInpRisks,
+        unsized_images: totalUnsizedImages,
+        total_images: totalImagesCount,
+        image_dimension_coverage_pct: totalImagesCount > 0 ? Math.round(((totalImagesCount - totalUnsizedImages) / totalImagesCount) * 100) : 100,
+      },
+      pages: pageVitals,
+    },
+    findings_summary: {
+      total: findings.length,
+      critical: criticalFindings.length,
+      high: highFindings.length,
+      medium: mediumFindings.length,
+      low: lowFindings.length,
+    },
+    findings: findings.map((f) => ({
+      detector_id: f.detector_id,
+      name: f.name,
+      severity: f.classification.severity,
+      subject: f.subject.identifier || f.subject.url,
+      summary: f.observation.summary,
+      remediation: f.remediation?.preferred,
+    })),
+  };
+  return result;
+}
+/**
+ * Format terminal output for `citable sweep technical`
+ */
+export function formatSweepOutput(r) {
+  const lines = [
+    `Technical SEO Sweep & Core Web Vitals Report`,
+    `===========================================`,
+    `Target: ${r.target}`,
+    `Pages Audited: ${r.total_pages_audited}`,
+    `Overall Health: ${r.overall_health.toUpperCase()}`,
+    ``,
+    `CRAWL & INDEXABILITY:`,
+    `  HTTP 200 OK: ${r.crawl_and_indexability.status_200_count}/${r.total_pages_audited}`,
+    `  Non-200 Statuses: ${r.crawl_and_indexability.non_200_count}`,
+    `  Noindex Pages: ${r.crawl_and_indexability.noindex_count}`,
+    `  Canonical Issues: ${r.crawl_and_indexability.canonical_issues_count}`,
+    ``,
+    `CORE WEB VITALS READINESS (Deterministic Static Audit):`,
+    `  LCP Readiness: ${r.core_web_vitals.summary.lcp_readiness.toUpperCase()} (${r.core_web_vitals.summary.total_lcp_blockers} potential render blocker(s))`,
+    `  INP Readiness: ${r.core_web_vitals.summary.inp_readiness.toUpperCase()} (${r.core_web_vitals.summary.total_inp_risks} DOM complexity risk(s))`,
+    `  CLS Readiness: ${r.core_web_vitals.summary.cls_readiness.toUpperCase()} (${r.core_web_vitals.summary.unsized_images}/${r.core_web_vitals.summary.total_images} images lack dimensions; ${r.core_web_vitals.summary.image_dimension_coverage_pct}% coverage)`,
+    ``,
+    `CWV Threshold Standards:`,
+    `  - LCP: <= ${CWV_THRESHOLDS.lcp.good}s (Good), <= ${CWV_THRESHOLDS.lcp.needs_improvement}s (Needs Improvement)`,
+    `  - INP: <= ${CWV_THRESHOLDS.inp.good}ms (Good), <= ${CWV_THRESHOLDS.inp.needs_improvement}ms (Needs Improvement)`,
+    `  - CLS: <= ${CWV_THRESHOLDS.cls.good} (Good), <= ${CWV_THRESHOLDS.cls.needs_improvement} (Needs Improvement)`,
+    ``,
+    `FINDINGS: ${r.findings_summary.total} total (critical:${r.findings_summary.critical} high:${r.findings_summary.high} medium:${r.findings_summary.medium} low:${r.findings_summary.low})`,
+  ];
+  if (r.findings.length) {
+    lines.push(``, `Key Remediation Priorities:`);
+    for (const f of r.findings.slice(0, 10)) {
+      lines.push(`  [${f.detector_id}] (${f.severity}) ${f.summary}`);
+      if (f.remediation) lines.push(`    Fix: ${f.remediation}`);
+    }
+  }
+  return lines.join('\n');
+}

package/src/commands/verifyRemediation.js ADDED Viewed

@@ -0,0 +1,204 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { readJson, writeJson, nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import { buildContext } from './context.js';
+import { runDetectors } from '../detectors/framework.js';
+import { selectDetectors } from '../detectors/index.js';
+import { remediateCommand } from './remediate.js';
+const PKG_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version;
+const RESOLUTION_DEFINITION =
+  'Resolved means the named detector no longer reports a finding for the same subject in the re-run. '
+  + 'Detector absence is not a guarantee of conversion, ranking, or outcome; it is a mechanical re-check only.';
+function sha256(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+function subjectKey(subject) {
+  return subject?.identifier || subject?.url || JSON.stringify(subject) || 'unknown';
+}
+function newVerificationId() {
+  return `VR-${nowIso().replace(/\D/g, '')}-${Math.random().toString(36).slice(2, 6)}`;
+}
+/**
+ * `citable verify remediation` — closed loop: source-run finding -> patch ->
+ * detector re-run -> before/after evidence bundle.
+ *
+ * Fail-closed: a missing source run, an unloadable re-check target, a refused
+ * patch, or a failed detector re-run yields status `blocked`/`patch_refused`,
+ * never a silent `verified`.
+ */
+export async function verifyRemediation(root, options = {}) {
+  const { run: runId, finding, target, apply = false, subject = null } = options;
+  const runDir = path.join(root, '.citable', 'runs', runId || '');
+  const limitations = [
+    RESOLUTION_DEFINITION,
+    'The re-check observes the target as it exists now; unrelated concurrent changes are not attributable to the patch.',
+    'Rendering-dependent conditions on URL targets are re-observed only if the original collection method is available.',
+  ];
+  const result = {
+    verification_id: newVerificationId(),
+    timestamp: nowIso(),
+    status: 'blocked',
+    tool_version: PKG_VERSION,
+    repository_commit: null,
+    source_run_id: runId || null,
+    recheck_run_id: null,
+    detector_id: finding ? String(finding).toUpperCase() : null,
+    subject: null,
+    verdict: { resolved: false, before_finding_ids: [], after_finding_ids: [], new_regressions: [], resolution_definition: RESOLUTION_DEFINITION },
+    patch: null,
+    provenance: { command: 'verify remediation', recheck_target: target || null, detectors_run: [], detectors_skipped: [], recheck_errors: [], recheck_warnings: [] },
+    limitations,
+    bundle_dir: null,
+    bundle_checksums: {},
+  };
+  if (!runId || !fs.existsSync(path.join(runDir, 'findings.json'))) {
+    result.provenance.recheck_errors.push(`source run not found: .citable/runs/${runId || '(none)'}`);
+    result.limitations.push('required_input: run-id of the immutable source audit containing the finding.');
+    return finalizeResult(result);
+  }
+  if (!finding) {
+    result.provenance.recheck_errors.push('missing required input: --finding <detector-id>');
+    return finalizeResult(result);
+  }
+  const beforeFindings = readJson(path.join(runDir, 'findings.json'));
+  const manifest = fs.existsSync(path.join(runDir, 'manifest.json'))
+    ? readJson(path.join(runDir, 'manifest.json'))
+    : null;
+  result.tool_version = manifest?.tool_version || PKG_VERSION;
+  result.repository_commit = manifest?.repository_commit ?? null;
+  const matches = beforeFindings.filter((f) =>
+    (f.detector_id || '').toUpperCase() === result.detector_id
+    && (!subject || subjectKey(f.subject) === subject));
+  if (matches.length === 0) {
+    result.provenance.recheck_errors.push(`finding ${result.detector_id} not present in source run ${runId}`);
+    result.status = 'blocked';
+    return finalizeResult(result);
+  }
+  result.verdict.before_finding_ids = matches.map((f) => f.finding_id);
+  result.subject = { type: matches[0].subject?.type || 'unknown', identifier: subject || subjectKey(matches[0].subject) };
+  // Optional gated patch application (production-safe pipeline from remediate.js)
+  if (target && apply) {
+    const targetPath = path.resolve(root, target);
+    const beforeSha = fs.existsSync(targetPath) ? sha256(fs.readFileSync(targetPath, 'utf8')) : null;
+    const patchRes = await remediateCommand(root, { finding: result.detector_id, target, write: true });
+    result.patch = {
+      target_file: target,
+      framework: patchRes.framework?.framework ?? null,
+      patcher_class: patchRes.patcher_class ?? null,
+      confidence: patchRes.confidence?.score ?? null,
+      validation_passed: Boolean(patchRes.validation?.ok),
+      applied: Boolean(patchRes.written),
+      refusal_reason: patchRes.refusal_reason ?? null,
+      rollback_snapshot: patchRes.rollback?.snapshot_file ?? null,
+      before_sha256: beforeSha,
+      after_sha256: patchRes.written ? sha256(fs.readFileSync(targetPath, 'utf8')) : null,
+    };
+    if (!patchRes.written) {
+      result.status = 'patch_refused';
+      result.limitations.push('Patch was refused by the safety gate; no re-check verdict is possible until the patch is applied or refused intentionally.');
+      return finalizeResult(result);
+    }
+  } else if (target) {
+    const p = path.resolve(root, target);
+    if (fs.existsSync(p)) {
+      result.patch = { target_file: target, applied: true, before_sha256: null, after_sha256: sha256(fs.readFileSync(p, 'utf8')) };
+    }
+  }
+  // Re-run the detector namespace against the original audit target (site dir
+  // or URL) — deliberately independent from the patch file target.
+  const recheckTarget = options.recheckTarget || manifest?.target?.location || target || null;
+  if (!recheckTarget) {
+    result.provenance.recheck_errors.push('no re-check target available (original run had no location and no --target supplied)');
+    result.limitations.push('required_input: --target <dir|url> matching the source run target.');
+    return finalizeResult(result);
+  }
+  result.provenance.recheck_target = recheckTarget;
+  const namespace = result.detector_id.split('-')[0];
+  let ctx;
+  try {
+    ctx = await buildContext(root, { target: recheckTarget, baseUrl: options.baseUrl, refDate: options.refDate });
+  } catch (err) {
+    result.provenance.recheck_errors.push(`re-check context failed: ${err.message}`);
+    result.limitations.push('required_input: a readable target directory or URL for the detector re-run.');
+    return finalizeResult(result);
+  }
+  if (!ctx.site) {
+    result.provenance.recheck_errors.push('re-check target produced no site context; detector re-run impossible (fail closed)');
+    return finalizeResult(result);
+  }
+  result.provenance.recheck_warnings.push(...(ctx.warnings || []));
+  const { findings: afterFindings, detectorsRun, detectorsSkipped, errors } = runDetectors(
+    selectDetectors({ namespaces: [namespace] }),
+    ctx
+  );
+  result.provenance.detectors_run = detectorsRun;
+  result.provenance.detectors_skipped = detectorsSkipped;
+  result.provenance.recheck_errors.push(...errors);
+  const afterMatches = afterFindings.filter((f) =>
+    (f.detector_id || '').toUpperCase() === result.detector_id
+    && subjectKey(f.subject) === subjectKey(matches[0].subject));
+  result.verdict.after_finding_ids = afterMatches.map((f) => f.finding_id);
+  const beforeKeys = new Set(beforeFindings.map((f) => `${f.detector_id}|${subjectKey(f.subject)}|${f.observation?.summary}`));
+  const afterKeys = new Set(afterFindings.map((f) => `${f.detector_id}|${subjectKey(f.subject)}|${f.observation?.summary}`));
+  result.verdict.new_regressions = afterFindings
+    .filter((f) => ['critical', 'high'].includes(f.classification?.severity))
+    .filter((f) => !beforeKeys.has(`${f.detector_id}|${subjectKey(f.subject)}|${f.observation?.summary}`))
+    .map((f) => ({ finding_id: f.finding_id, detector_id: f.detector_id, severity: f.classification.severity, summary: f.observation?.summary }));
+  const errorsDuringRecheck = result.provenance.recheck_errors.length > 0;
+  if (errorsDuringRecheck) {
+    result.status = 'blocked';
+    result.verdict.resolved = false;
+    result.limitations.push('Detector errors occurred during the re-check; resolution cannot be established from a failed observation.');
+  } else if (afterMatches.length === 0) {
+    result.status = 'verified';
+    result.verdict.resolved = true;
+  } else {
+    result.status = 'not_resolved';
+    result.verdict.resolved = false;
+  }
+  return finalizeResult(result, root);
+}
+function finalizeResult(result, root = null) {
+  const { valid, errors } = validateAgainst('remediation-verification.schema.json', result);
+  if (!valid) throw new Error(`verification record invalid: ${errors.join('; ')}`);
+  if (root) {
+    const bundleDir = path.join(root, '.citable', 'verification', result.verification_id);
+    fs.mkdirSync(bundleDir, { recursive: true });
+    writeJson(path.join(bundleDir, 'verification.json'), result);
+    writeJson(path.join(bundleDir, 'before-findings.json'), { source_run_id: result.source_run_id, findings: result.verdict.before_finding_ids });
+    const checksums = {};
+    for (const name of fs.readdirSync(bundleDir)) {
+      const p = path.join(bundleDir, name);
+      if (fs.statSync(p).isFile()) checksums[name] = sha256(fs.readFileSync(p, 'utf8'));
+    }
+    result.bundle_dir = path.relative(root, bundleDir);
+    result.bundle_checksums = checksums;
+    writeJson(path.join(bundleDir, 'verification.json'), result);
+    writeJson(path.join(bundleDir, 'checksums.json'), checksums);
+  }
+  return result;
+}