@aifabrix/builder 2.43.0 → 2.44.1

package/lib/utils/datasource-test-run-display.js

@@ -0,0 +1,459 @@
+/**
+ * @fileoverview Minimal human TTY + --summary for DatasourceTestRun (plan §3.2 / §16.9 subset).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const { sectionTitle, headerKeyValue, colorAggregateGlyph, successGlyph, failureGlyph } = require('./cli-test-layout-chalk');
+const { appendCertificateTTY } = require('./datasource-test-run-certificate-tty');
+
+const SEP = '────────────────────────────────';
+
+/** @type {number} */
+const DEFAULT_MAX_REF_CHARS = 200;
+
+/**
+ * @param {'ok'|'warn'|'fail'|'skipped'} status
+ * @returns {string}
+ */
+function statusGlyph(status) {
+  if (status === 'ok') return '✔';
+  if (status === 'warn') return '⚠';
+  if (status === 'fail') return '✖';
+  if (status === 'skipped') return '⏭';
+  return '?';
+}
+
+/**
+ * Map API status string to aggregate bucket for colors.
+ * @param {*} status
+ * @returns {'ok'|'warn'|'fail'|'skipped'|null} null = unknown / other
+ */
+function envelopeStatusAggregate(status) {
+  const s = String(status || '').toLowerCase();
+  if (s === 'warn') return 'warn';
+  if (s === 'fail') return 'fail';
+  if (s === 'skipped' || s === 'skip') return 'skipped';
+  if (s === 'ok') return 'ok';
+  return null;
+}
+
+/**
+ * @param {*} status
+ * @param {string} rawWord - as returned by API (e.g. ok, warn)
+ * @returns {string}
+ */
+function colorStatusWord(status, rawWord) {
+  const agg = envelopeStatusAggregate(status);
+  const w = String(rawWord);
+  if (!agg) return chalk.gray(w);
+  if (agg === 'ok') return chalk.green(w);
+  if (agg === 'warn') return chalk.yellow(w);
+  if (agg === 'fail') return chalk.red(w);
+  return chalk.gray(w);
+}
+
+/**
+ * Colored glyph for status (neutral when unknown).
+ * @param {*} status
+ * @returns {string}
+ */
+function colorStatusGlyph(status) {
+  const agg = envelopeStatusAggregate(status);
+  const glyph = statusGlyph(status);
+  return agg ? colorAggregateGlyph(agg, glyph) : chalk.gray(glyph);
+}
+
+/**
+ * `Status: ✔ ok` with layout-aligned colors (preserves raw status text).
+ * @param {Object} envelope
+ * @returns {string}
+ */
+function formatEnvelopeStatusLine(envelope) {
+  const raw = envelope.status !== undefined && envelope.status !== null ? String(envelope.status) : 'unknown';
+  const g = colorStatusGlyph(envelope.status);
+  return `${chalk.gray('Status:')} ${g} ${colorStatusWord(envelope.status, raw)}`;
+}
+
+/**
+ * @param {boolean} ok
+ * @param {string} body - step name + optional tail
+ * @returns {string}
+ */
+function colorStepLine(ok, body) {
+  const sym = ok ? successGlyph() : failureGlyph();
+  return `  ${sym} ${chalk.white(body)}`;
+}
+
+/**
+ * Normalize CLI --capability value for matching envelope.capabilities[].key
+ * @param {*} focusCapabilityKey
+ * @returns {string} trimmed or ''
+ */
+function normalizedFocusCapabilityKey(focusCapabilityKey) {
+  if (focusCapabilityKey === undefined || focusCapabilityKey === null) return '';
+  const s = String(focusCapabilityKey).trim();
+  return s;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object|null|undefined} e2e
+ */
+function pushCapabilityE2eLines(lines, e2e) {
+  if (!e2e || typeof e2e !== 'object') return;
+  if (e2e.status) {
+    const g = colorStatusGlyph(e2e.status);
+    lines.push(`${chalk.gray('E2E:')} ${g} ${colorStatusWord(e2e.status, e2e.status)}`);
+  }
+  const esteps = Array.isArray(e2e.steps) ? e2e.steps : [];
+  for (const st of esteps) {
+    const nm = st.name || st.step || 'step';
+    const ok = st.success !== false && !st.error;
+    const tail = st.error || st.message ? `: ${st.error || st.message}` : '';
+    lines.push(colorStepLine(ok, `${nm}${tail}`));
+  }
+}
+
+/**
+ * Multi-line TTY block for a single capability row (plan §2.3 drill-down).
+ * @param {Object|null|undefined} envelope
+ * @param {string} focusKey - non-empty
+ * @returns {string}
+ */
+function formatCapabilityFocusSection(envelope, focusKey) {
+  if (!focusKey) return '';
+  const lines = ['', chalk.gray(SEP), sectionTitle(`Capability scope: ${focusKey}`)];
+  const caps =
+    envelope && typeof envelope === 'object' && Array.isArray(envelope.capabilities)
+      ? envelope.capabilities
+      : [];
+  const cap = caps.find(c => c && String(c.key) === focusKey);
+  if (!cap) {
+    lines.push(chalk.yellow(`(No row with key "${focusKey}" in capabilities[])`));
+    return lines.join('\n');
+  }
+  lines.push(formatEnvelopeStatusLine(cap));
+  if (cap.permission) {
+    lines.push(headerKeyValue('Permission:', String(cap.permission)));
+  }
+  pushCapabilityE2eLines(lines, cap.e2e);
+  return lines.join('\n');
+}
+
+/**
+ * @param {Object} envelope
+ * @returns {string[]}
+ */
+function buildTtyMetaLines(envelope) {
+  const lines = [];
+  lines.push(
+    headerKeyValue('Datasource:', `${envelope.datasourceKey} (${envelope.systemKey})`)
+  );
+  lines.push(headerKeyValue('Run:', String(envelope.runType)));
+  lines.push(formatEnvelopeStatusLine(envelope));
+  const rid = envelope.runId || envelope.testRunId;
+  if (rid) lines.push(`${chalk.gray('Run ID:')} ${chalk.cyan(String(rid))}`);
+  if (envelope.reportCompleteness && envelope.reportCompleteness !== 'full') {
+    lines.push(
+      `${chalk.gray('Report:')} ${chalk.yellow(String(envelope.reportCompleteness))}`
+    );
+  }
+  return lines;
+}
+
+/**
+ * @param {*} val
+ * @returns {string[]}
+ */
+function normalizeRefArray(val) {
+  if (val === null || val === undefined) return [];
+  return Array.isArray(val) ? val : [val];
+}
+
+/**
+ * @param {string} str
+ * @param {number} maxChars
+ * @returns {string}
+ */
+function truncateRefLine(str, maxChars) {
+  const s = String(str);
+  if (s.length <= maxChars) return s;
+  return `${s.slice(0, Math.max(0, maxChars - 24))}… [+${s.length - maxChars + 24} chars]`;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {string} title
+ * @param {*} arr
+ * @param {number} maxRefChars
+ * @returns {boolean}
+ */
+function appendStringRefBlock(lines, title, arr, maxRefChars) {
+  const entries = normalizeRefArray(arr).map(String);
+  if (!entries.length) return false;
+  lines.push(chalk.blue.bold(String(title)));
+  entries.forEach((text, i) => {
+    lines.push(`  ${chalk.gray(`[${i + 1}]`)} ${chalk.white(truncateRefLine(text, maxRefChars))}`);
+  });
+  return true;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object|null|undefined} dbg
+ * @param {number} maxRefChars
+ * @returns {boolean}
+ */
+function appendDebugPayloadRefLines(lines, dbg, maxRefChars) {
+  const payloadRefs = dbg && typeof dbg === 'object' ? normalizeRefArray(dbg.payloadRefs) : [];
+  if (!payloadRefs.length) return false;
+  lines.push(chalk.blue.bold('debug.payloadRefs:'));
+  payloadRefs.forEach((pr, i) => {
+    const idx = chalk.gray(`[${i + 1}]`);
+    if (typeof pr === 'string') {
+      lines.push(`  ${idx} ${chalk.white(truncateRefLine(pr, maxRefChars))}`);
+      return;
+    }
+    if (pr && typeof pr === 'object') {
+      const k = pr.key !== undefined && pr.key !== null ? String(pr.key) : 'payload';
+      const r = pr.ref !== undefined && pr.ref !== null ? String(pr.ref) : '';
+      const row = r ? `${k}: ${r}` : k;
+      lines.push(`  ${idx} ${chalk.white(truncateRefLine(row, maxRefChars))}`);
+      return;
+    }
+    lines.push(`  ${idx} ${chalk.gray('(ref)')}`);
+  });
+  return true;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object} dbg
+ * @param {number} maxRefChars
+ * @returns {boolean}
+ */
+function appendDebugMetaLines(lines, dbg, maxRefChars) {
+  let added = false;
+  function formatSecondsText(s) {
+    const txt = String(s);
+    // UI-only: reduce noisy float seconds to 3 decimals, e.g. "1.1713749s" -> "1.171s".
+    // Applies only to number tokens immediately followed by "s".
+    return txt.replace(/(\d+\.\d+)(?=s\b)/g, m => {
+      const n = Number(m);
+      if (!Number.isFinite(n)) return m;
+      return n.toFixed(3);
+    });
+  }
+  if (dbg.mode) {
+    lines.push(
+      `${chalk.blue.bold('debug.mode:')} ${chalk.white(String(dbg.mode))}`
+    );
+    added = true;
+  }
+  if (dbg.executionSummary) {
+    lines.push(
+      `${chalk.blue.bold('debug.executionSummary:')} ${chalk.white(
+        truncateRefLine(formatSecondsText(dbg.executionSummary), maxRefChars)
+      )}`
+    );
+    added = true;
+  }
+  return added;
+}
+
+/**
+ * Append audit + debug reference layout (OpenAPI AuditRefs, DebugTrace.payloadRefs).
+ * @param {string[]} lines
+ * @param {Object} envelope
+ * @param {{ maxRefChars?: number }} [opts]
+ * @returns {boolean} True if any reference line was added
+ */
+function appendReferenceLayoutLines(lines, envelope, opts = {}) {
+  const maxRefChars = opts.maxRefChars ?? DEFAULT_MAX_REF_CHARS;
+  const audit = envelope && envelope.audit;
+  const dbg = envelope && envelope.debug;
+  const parts = [];
+
+  if (audit && typeof audit === 'object') {
+    parts.push(appendStringRefBlock(lines, 'audit.executionIds:', audit.executionIds, maxRefChars));
+    parts.push(appendStringRefBlock(lines, 'audit.traceRefs:', audit.traceRefs, maxRefChars));
+    parts.push(appendStringRefBlock(lines, 'audit.rbacTraceRefs:', audit.rbacTraceRefs, maxRefChars));
+    parts.push(appendStringRefBlock(lines, 'audit.abacTraceRefs:', audit.abacTraceRefs, maxRefChars));
+  }
+
+  parts.push(appendDebugPayloadRefLines(lines, dbg, maxRefChars));
+
+  if (dbg && typeof dbg === 'object') {
+    parts.push(appendStringRefBlock(lines, 'debug.executionIds:', dbg.executionIds, maxRefChars));
+    parts.push(appendDebugMetaLines(lines, dbg, maxRefChars));
+  }
+
+  return parts.some(Boolean);
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object} envelope
+ * @param {number} [maxIssues]
+ */
+function appendValidationIssueLines(lines, envelope, maxIssues = 5) {
+  const issues = envelope && envelope.validation && Array.isArray(envelope.validation.issues) ? envelope.validation.issues : [];
+  if (!issues.length) return;
+  lines.push(sectionTitle('Validation issues:'));
+  const cap = Math.min(maxIssues, issues.length);
+  for (let i = 0; i < cap; i += 1) {
+    const iss = issues[i];
+    const code = iss && iss.code ? chalk.red(`[${iss.code}] `) : '';
+    const msg = iss && iss.message ? String(iss.message) : JSON.stringify(iss);
+    lines.push(`  ${code}${chalk.yellow(msg)}`);
+  }
+  if (issues.length > cap) {
+    lines.push(chalk.gray(`  … and ${issues.length - cap} more (see --json or debug full/raw)`));
+  }
+}
+
+/**
+ * @param {string[]} lines
+ * @param {Object} envelope
+ */
+function formatIntegrationStepLine(st) {
+  const nm = (st && (st.name || st.step)) || 'step';
+  const ok = st && st.success !== false && !st.error;
+  const detail = st && (st.message || st.error) ? `: ${st.message || st.error}` : '';
+  return colorStepLine(ok, `${nm}${detail}`);
+}
+
+function appendIntegrationStepLines(lines, envelope) {
+  const integ = envelope && envelope.integration;
+  const steps = integ && Array.isArray(integ.stepResults) ? integ.stepResults : [];
+  if (!steps.length) return;
+  lines.push(sectionTitle('Integration steps:'));
+  for (const st of steps) {
+    lines.push(formatIntegrationStepLine(st));
+  }
+}
+
+function pickExecutiveVerdictLine(envelope) {
+  const dev = envelope.developer;
+  const cert = envelope.certificate;
+  if (envelope.runType === 'e2e' && cert && typeof cert === 'object') {
+    const cs = cert.summary;
+    if (cs && String(cs).trim()) return String(cs).trim();
+  }
+  return (
+    (dev && dev.executiveSummary) ||
+    (cert && cert.summary) ||
+    (envelope.validation && envelope.validation.summary) ||
+    (envelope.integration && envelope.integration.summary) ||
+    `Run finished with status ${envelope.status}.`
+  );
+}
+
+/**
+ * Plan §3.9: explicit line when E2E has no capability rows (skipped when --capability drill-down is active).
+ * @param {string[]} lines
+ * @param {Object} envelope
+ * @param {{ focusCapabilityKey?: string }} [options]
+ */
+function appendNoCapabilitiesReportedLine(lines, envelope, options = {}) {
+  if (envelope.runType !== 'e2e') return;
+  if (normalizedFocusCapabilityKey(options.focusCapabilityKey)) return;
+  const caps = envelope.capabilities;
+  if (Array.isArray(caps) && caps.length > 0) return;
+  lines.push(chalk.gray('No capabilities reported.'));
+}
+
+/**
+ * @param {string[]} parts
+ * @param {Object} envelope
+ * @param {string} focus - normalized or ''
+ */
+function appendCapabilitySummaryPart(parts, envelope, focus) {
+  if (focus) {
+    const caps = Array.isArray(envelope.capabilities) ? envelope.capabilities : [];
+    const row = caps.find(c => c && String(c.key) === focus);
+    parts.push(
+      row ? `Cap ${focus}: ${statusGlyph(row.status)} ${row.status}` : `Cap ${focus}: (missing)`
+    );
+    return;
+  }
+  const capSummary = envelope.capabilitySummary;
+  if (capSummary && typeof capSummary === 'object') {
+    const passed = capSummary.passedCount;
+    const total = capSummary.totalCount;
+    if (typeof passed === 'number' && typeof total === 'number') {
+      parts.push(`Capabilities: ${passed}/${total}`);
+    }
+  }
+}
+
+/**
+ * @param {string[]} parts
+ * @param {Object} envelope
+ */
+function appendCertificateSummaryPart(parts, envelope) {
+  const cert = envelope.certificate;
+  if (!cert || typeof cert !== 'object') return;
+  const level =
+    cert.level !== undefined && cert.level !== null ? String(cert.level) : '';
+  const cg = cert.status === 'passed' ? '✔' : cert.status === 'not_passed' ? '✖' : '⚠';
+  if (level) parts.push(`Certificate: ${level} ${cg}`);
+}
+
+/**
+ * One-line summary (plan §16.9 normative field order subset).
+ * @param {Object} envelope
+ * @param {{ focusCapabilityKey?: string }} [options]
+ * @returns {string}
+ */
+function formatDatasourceTestRunSummary(envelope, options = {}) {
+  if (!envelope || typeof envelope !== 'object') return '';
+  const parts = [];
+  parts.push(String(envelope.datasourceKey || 'unknown'));
+  parts.push(`${statusGlyph(envelope.status)} ${(envelope.status || '').toUpperCase()}`);
+  const focus = normalizedFocusCapabilityKey(options.focusCapabilityKey);
+  appendCapabilitySummaryPart(parts, envelope, focus);
+  appendCertificateSummaryPart(parts, envelope);
+  return parts.join(' | ');
+}
+
+/**
+ * Default TTY block (header + verdict line + short summary + optional completeness).
+ * @param {Object} envelope
+ * @param {{ focusCapabilityKey?: string }} [options] - When set (e.g. --capability), append single-cap block (plan §2.3).
+ * @returns {string}
+ */
+function formatDatasourceTestRunTTY(envelope, options = {}) {
+  if (!envelope || typeof envelope !== 'object') return '';
+  const lines = [...buildTtyMetaLines(envelope)];
+  appendNoCapabilitiesReportedLine(lines, envelope, options);
+  lines.push('');
+  lines.push(sectionTitle('Verdict:'));
+  lines.push(chalk.white(pickExecutiveVerdictLine(envelope)));
+  appendCertificateTTY(lines, envelope);
+  lines.push('');
+  lines.push(chalk.gray(SEP));
+  if (appendReferenceLayoutLines(lines, envelope, { maxRefChars: 160 })) {
+    lines.push('');
+  }
+  appendValidationIssueLines(lines, envelope);
+  appendIntegrationStepLines(lines, envelope);
+  const focus = normalizedFocusCapabilityKey(options.focusCapabilityKey);
+  if (focus) {
+    lines.push(formatCapabilityFocusSection(envelope, focus));
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  formatDatasourceTestRunSummary,
+  formatDatasourceTestRunTTY,
+  formatCapabilityFocusSection,
+  normalizedFocusCapabilityKey,
+  statusGlyph,
+  SEP,
+  appendReferenceLayoutLines,
+  normalizeRefArray
+};

package/lib/utils/datasource-test-run-exit.js

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Exit code matrix for DatasourceTestRun after successful HTTP (plan §3.1).
+ * HTTP/transport failures are exit 3 (handled by callers).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Compute CLI exit code from parsed DatasourceTestRun envelope.
+ * Ordering: status / warnings-as-errors → require-cert (§3.1).
+ * @param {import('../api/types/validation-run.types').DatasourceTestRunLike|null|undefined} body
+ * @param {Object} [opts]
+ * @param {boolean} [opts.warningsAsErrors]
+ * @param {boolean} [opts.requireCert]
+ * @returns {number} 0 | 1 | 2 | 3 (3 = treat as parse/body unusable)
+ */
+function computeExitCodeFromDatasourceTestRun(body, opts = {}) {
+  if (!body || typeof body !== 'object') {
+    return 3;
+  }
+  const status = body.status;
+  if (status === 'fail') {
+    return 1;
+  }
+  if (status === 'warn' && opts.warningsAsErrors === true) {
+    return 1;
+  }
+  if (status === 'ok' || status === 'skipped' || status === 'warn') {
+    if (opts.requireCert === true) {
+      const cert = body.certificate;
+      if (!cert) {
+        return 2;
+      }
+      if (cert.status === 'not_passed') {
+        return 2;
+      }
+    }
+    return 0;
+  }
+  return 3;
+}
+
+/**
+ * Exit code for poll timeout with last envelope (plan §3.4).
+ * @param {import('../api/types/validation-run.types').DatasourceTestRunLike|null} lastBody
+ * @returns {number} 1 if root fail, else 3
+ */
+function exitCodeForPollTimeout(lastBody) {
+  if (lastBody && typeof lastBody === 'object' && lastBody.status === 'fail') {
+    return 1;
+  }
+  return 3;
+}
+
+const {
+  deriveSystemStatus,
+  systemCertStatus
+} = require('./external-system-system-test-tty');
+
+/**
+ * System-level exit code from per-datasource result rows (same matrix as §3.1 on synthetic rollup).
+ * @param {Array<{ skipped?: boolean, success?: boolean, datasourceTestRun?: Object|null }>} rows
+ * @param {Object} [opts]
+ * @param {boolean} [opts.warningsAsErrors]
+ * @param {boolean} [opts.requireCert]
+ * @returns {number}
+ */
+function computeSystemExitCodeFromDatasourceRows(rows, opts = {}) {
+  const list = Array.isArray(rows) ? rows : [];
+  const status = deriveSystemStatus(list);
+  const certAgg = systemCertStatus(list);
+  const body = {
+    status,
+    certificate: certAgg ? { status: certAgg === 'passed' ? 'passed' : 'not_passed' } : undefined
+  };
+  return computeExitCodeFromDatasourceTestRun(body, opts);
+}
+
+module.exports = {
+  computeExitCodeFromDatasourceTestRun,
+  computeSystemExitCodeFromDatasourceRows,
+  exitCodeForPollTimeout
+};

package/lib/utils/datasource-test-run-legacy-adapter.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Map DatasourceTestRun envelope → legacy CLI display shapes (integration + E2E).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * @param {Object|null} envelope
+ * @returns {string|null}
+ */
+function firstIssueMessage(envelope) {
+  const v = envelope && envelope.validation;
+  const issues = v && Array.isArray(v.issues) ? v.issues : [];
+  const first = issues.find(i => i && (i.message || i.hint));
+  if (first) return String(first.message || first.hint);
+  const integ = envelope && envelope.integration;
+  const steps = integ && Array.isArray(integ.stepResults) ? integ.stepResults : [];
+  const bad = steps.find(s => s && s.success === false && (s.message || s.error));
+  if (bad) return String(bad.message || bad.error || 'Integration step failed');
+  return null;
+}
+
+/**
+ * Legacy integration result for displayIntegrationTestResults / verbose details.
+ * @param {Object|null} envelope
+ * @param {string} datasourceKey
+ * @returns {Object}
+ */
+function integrationResultFromEnvelope(envelope, datasourceKey) {
+  if (!envelope || typeof envelope !== 'object') {
+    return {
+      key: datasourceKey,
+      systemKey: 'unknown',
+      success: false,
+      skipped: false,
+      validationResults: {},
+      fieldMappingResults: {},
+      endpointTestResults: {},
+      error: 'No report envelope',
+      envelope: null
+    };
+  }
+  const success = envelope.status !== 'fail';
+  const err = success ? undefined : firstIssueMessage(envelope) || `status: ${envelope.status}`;
+  return {
+    key: datasourceKey,
+    systemKey: envelope.systemKey || 'unknown',
+    success,
+    skipped: false,
+    error: err,
+    envelope
+  };
+}
+
+/**
+ * Map integration.stepResults → E2E-style steps for displayE2EResults.
+ * @param {Object|null} envelope
+ * @returns {{ steps: Object[], success: boolean, status?: string, error?: string }}
+ */
+function e2eShapeFromEnvelope(envelope) {
+  if (!envelope || typeof envelope !== 'object') {
+    return { steps: [], success: false, error: 'No report envelope' };
+  }
+  const integ = envelope.integration;
+  const raw = integ && Array.isArray(integ.stepResults) ? integ.stepResults : [];
+  const steps = raw.map(s => ({
+    name: s.name || 'step',
+    step: s.name,
+    success: s.success !== false,
+    message: s.message,
+    error: s.success === false ? s.message || 'failed' : undefined
+  }));
+  const success = envelope.status !== 'fail';
+  let status;
+  if (envelope.status === 'fail') status = 'failed';
+  else if (envelope.reportCompleteness && envelope.reportCompleteness !== 'full') {
+    status = 'completed';
+  } else {
+    status = 'completed';
+  }
+  return {
+    steps,
+    success,
+    status,
+    error: success ? undefined : firstIssueMessage(envelope) || undefined
+  };
+}
+
+module.exports = {
+  integrationResultFromEnvelope,
+  e2eShapeFromEnvelope,
+  firstIssueMessage
+};

package/lib/utils/datasource-test-run-report-version.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview reportVersion compatibility warnings (plan §3.15).
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/** CLI-supported major reportVersion (bump when breaking). */
+const SUPPORTED_MAJOR = 1;
+
+/**
+ * Parse leading major from semver-like string (e.g. 1.1.0 → 1).
+ * @param {string} v
+ * @returns {number|null}
+ */
+function parseMajor(v) {
+  if (!v || typeof v !== 'string') return null;
+  const m = /^v?(\d+)/.exec(v.trim());
+  if (!m) return null;
+  return parseInt(m[1], 10);
+}
+
+/**
+ * stderr messages for reportVersion handling.
+ * @param {string|undefined} reportVersion - From envelope
+ * @returns {{ level: 'none'|'warn'|'info', message: string }|null}
+ */
+function getReportVersionStderrMessage(reportVersion) {
+  const major = parseMajor(reportVersion || '');
+  if (major === null) {
+    return null;
+  }
+  if (major < SUPPORTED_MAJOR - 1) {
+    return {
+      level: 'warn',
+      message: `reportVersion unsupported (got ${reportVersion}, support ${SUPPORTED_MAJOR - 1}–${SUPPORTED_MAJOR} major)`
+    };
+  }
+  if (major > SUPPORTED_MAJOR) {
+    return {
+      level: 'info',
+      message: 'Newer reportVersion; some fields may be ignored'
+    };
+  }
+  return null;
+}
+
+module.exports = {
+  SUPPORTED_MAJOR,
+  parseMajor,
+  getReportVersionStderrMessage
+};