@test-station/core 0.1.7 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@test-station/core",
-  "version": "0.1.7",
+  "version": "0.2.10",
   "publishConfig": {
     "access": "public"
   },
@@ -9,12 +9,12 @@
     ".": "./src/index.js"
   },
   "dependencies": {
-    "@test-station/adapter-jest": "0.1.7",
-    "@test-station/adapter-node-test": "0.1.7",
-    "@test-station/adapter-playwright": "0.1.7",
-    "@test-station/adapter-shell": "0.1.7",
-    "@test-station/adapter-vitest": "0.1.7",
-    "@test-station/plugin-source-analysis": "0.1.7"
+    "@test-station/adapter-jest": "0.2.10",
+    "@test-station/adapter-node-test": "0.2.10",
+    "@test-station/adapter-playwright": "0.2.10",
+    "@test-station/adapter-shell": "0.2.10",
+    "@test-station/adapter-vitest": "0.2.10",
+    "@test-station/plugin-source-analysis": "0.2.10"
   },
   "scripts": {
     "build": "node ../../scripts/check-package.mjs ./src/index.js",

package/src/artifacts.js

@@ -7,6 +7,10 @@ export function writeReportArtifacts(context, report, suiteResults) {
 
   const reportJsonPath = path.join(context.project.outputDir, 'report.json');
   fs.writeFileSync(reportJsonPath, `${JSON.stringify(report, null, 2)}\n`);
+  const modulesJsonPath = path.join(context.project.outputDir, 'modules.json');
+  fs.writeFileSync(modulesJsonPath, `${JSON.stringify(createModulesArtifact(report), null, 2)}\n`);
+  const ownershipJsonPath = path.join(context.project.outputDir, 'ownership.json');
+  fs.writeFileSync(ownershipJsonPath, `${JSON.stringify(createOwnershipArtifact(report), null, 2)}\n`);
 
   const rawSuitePaths = [];
   for (const suite of suiteResults) {
@@ -21,6 +25,7 @@ export function writeReportArtifacts(context, report, suiteResults) {
       summary: suite.summary,
       coverage: suite.coverage,
       warnings: suite.warnings,
+      diagnostics: suite.diagnostics || null,
       rawArtifacts: suite.rawArtifacts,
       output: suite.output,
       tests: suite.tests,
@@ -46,10 +51,39 @@ export function writeReportArtifacts(context, report, suiteResults) {
 
   return {
     reportJsonPath,
+    modulesJsonPath,
+    ownershipJsonPath,
     rawSuitePaths,
   };
 }
 
+function createModulesArtifact(report) {
+  return {
+    schemaVersion: '1',
+    generatedAt: report?.generatedAt || new Date().toISOString(),
+    projectName: report?.meta?.projectName || null,
+    modules: Array.isArray(report?.modules) ? report.modules : [],
+  };
+}
+
+function createOwnershipArtifact(report) {
+  const modules = Array.isArray(report?.modules) ? report.modules : [];
+  return {
+    schemaVersion: '1',
+    generatedAt: report?.generatedAt || new Date().toISOString(),
+    projectName: report?.meta?.projectName || null,
+    modules: modules.map((moduleEntry) => ({
+      module: moduleEntry.module,
+      owner: moduleEntry.owner || null,
+    })),
+    themes: modules.flatMap((moduleEntry) => (Array.isArray(moduleEntry.themes) ? moduleEntry.themes : []).map((themeEntry) => ({
+      module: moduleEntry.module,
+      theme: themeEntry.theme,
+      owner: themeEntry.owner || null,
+    }))),
+  };
+}
+
 function copyArtifactSource(sourcePath, destinationPath, kind) {
   const sourceStat = fs.statSync(sourcePath);
   if (kind === 'directory' || sourceStat.isDirectory()) {

package/src/console.js

@@ -47,6 +47,17 @@ export function createConsoleProgressReporter(options = {}) {
         return;
       }
 
+      if (event.type === 'suite-diagnostics-start') {
+        writeLine(stream, `    diagnostics: running ${event.diagnosticsLabel || 'diagnostics rerun'}`);
+        return;
+      }
+
+      if (event.type === 'suite-diagnostics-complete') {
+        const result = event.result || {};
+        writeLine(stream, `    diagnostics: ${formatStatus(result.status)} ${formatDuration(result.durationMs || 0)} ${result.command || ''}`.trimEnd());
+        return;
+      }
+
       if (event.type === 'package-complete') {
         writeLine(
           stream,
@@ -73,6 +84,11 @@ export function formatConsoleSummary(report, artifactPaths = {}, options = {}) {
     lines.push(coverageLine);
   }
 
+  const policyLine = formatPolicyLine(report?.summary?.policy);
+  if (policyLine) {
+    lines.push(policyLine);
+  }
+
   lines.push(`Duration: ${formatDuration(report?.durationMs || report?.summary?.durationMs || 0)}`);
   if (options.htmlPath) {
     lines.push(`HTML report: ${options.htmlPath}`);
@@ -100,6 +116,15 @@ export function formatConsoleSummary(report, artifactPaths = {}, options = {}) {
     lines.push(Number.isFinite(lineCoverage) ? `${prefix}  L ${lineCoverage.toFixed(2)}%` : prefix);
   }
 
+  const modules = Array.isArray(report?.modules) ? report.modules : [];
+  if (modules.length > 0) {
+    lines.push('-'.repeat(SECTION_WIDTH));
+    lines.push('Modules');
+    for (const moduleEntry of modules) {
+      lines.push(formatModuleLine(moduleEntry));
+    }
+  }
+
   lines.push('='.repeat(SECTION_WIDTH));
   return `${lines.join('\n')}\n`;
 }
@@ -123,16 +148,77 @@ function formatCoverageLine(coverage) {
   return `Coverage: ${metrics.map(([label, pct]) => `${label} ${pct.toFixed(2)}%`).join(' | ')}`;
 }
 
+function formatPolicyLine(policy) {
+  const metrics = [];
+  if (Number.isFinite(policy?.failedThresholds) && policy.failedThresholds > 0) {
+    metrics.push(`threshold failures ${policy.failedThresholds}`);
+  }
+  if (Number.isFinite(policy?.warningThresholds) && policy.warningThresholds > 0) {
+    metrics.push(`threshold warnings ${policy.warningThresholds}`);
+  }
+  if (Number.isFinite(policy?.diagnosticsSuites) && policy.diagnosticsSuites > 0) {
+    metrics.push(`diagnostic reruns ${policy.diagnosticsSuites}`);
+  }
+  if (Number.isFinite(policy?.failedDiagnostics) && policy.failedDiagnostics > 0) {
+    metrics.push(`failed diagnostics ${policy.failedDiagnostics}`);
+  }
+  if (metrics.length === 0) {
+    return null;
+  }
+  return `Policy: ${metrics.join(' | ')}`;
+}
+
 function formatSummaryInline(summary) {
   return `tests ${summary.total || 0} | pass ${summary.passed || 0} | fail ${summary.failed || 0} | skip ${summary.skipped || 0}`;
 }
 
 function formatStatus(status) {
   if (status === 'failed') return 'FAIL';
+  if (status === 'warn') return 'WARN';
   if (status === 'skipped') return 'SKIP';
   return 'PASS';
 }
 
+function formatModuleLine(moduleEntry) {
+  const status = resolveModuleStatus(moduleEntry);
+  const base = [
+    formatStatus(status).padEnd(5),
+    String(moduleEntry?.module || 'uncategorized').padEnd(20),
+    formatDuration(moduleEntry?.durationMs || 0),
+    formatSummaryInline(moduleEntry?.summary || zeroSummary()),
+  ].join('  ');
+  const details = [];
+
+  const lineCoverage = moduleEntry?.coverage?.lines?.pct;
+  if (Number.isFinite(lineCoverage)) {
+    details.push(`L ${lineCoverage.toFixed(2)}%`);
+  }
+  if (moduleEntry?.owner) {
+    details.push(`owner ${moduleEntry.owner}`);
+  }
+  if (moduleEntry?.threshold?.configured) {
+    details.push(`threshold ${moduleEntry.threshold.status}`);
+  }
+
+  return details.length > 0 ? `${base}  ${details.join(' | ')}` : base;
+}
+
+function resolveModuleStatus(moduleEntry) {
+  if (moduleEntry?.threshold?.status === 'failed') {
+    return 'failed';
+  }
+  if (moduleEntry?.threshold?.status === 'warn') {
+    return 'warn';
+  }
+  if ((moduleEntry?.summary?.failed || 0) > 0) {
+    return 'failed';
+  }
+  if ((moduleEntry?.summary?.total || 0) === 0 && !moduleEntry?.coverage) {
+    return 'skipped';
+  }
+  return 'passed';
+}
+
 function formatDuration(durationMs) {
   const totalSeconds = Math.max(0, Math.round((durationMs || 0) / 1000));
   const hours = Math.floor(totalSeconds / 3600);

package/src/index.js

@@ -2,7 +2,7 @@ export { CONFIG_SCHEMA_VERSION, REPORT_SCHEMA_VERSION, defineConfig, loadConfig,
 export { createPhase1ScaffoldReport, createSummary, normalizeTestResult, normalizeSuiteResult, buildReportFromSuiteResults } from './report.js';
 export { createCoverageMetric, normalizeCoverageSummary, mergeCoverageSummaries } from './coverage.js';
 export { resolveAdapterForSuite } from './adapters.js';
-export { preparePolicyContext, applyPolicyPipeline, collectCoverageAttribution, lookupOwner } from './policy.js';
+export { preparePolicyContext, applyPolicyPipeline, collectCoverageAttribution, lookupOwner, evaluateCoverageThresholds } from './policy.js';
 export { writeReportArtifacts } from './artifacts.js';
 export { formatConsoleSummary, createConsoleProgressReporter } from './console.js';
 export { runReport } from './run-report.js';

package/src/policy.js

@@ -21,6 +21,73 @@ export async function preparePolicyContext(loadedConfig, project) {
   };
 }
 
+export function evaluateCoverageThresholds(policy, modules, options = {}) {
+  const thresholdManifest = policy?.manifests?.thresholds?.thresholds || {};
+  const moduleRules = buildThresholdRuleMap(thresholdManifest.modules || [], 'module');
+  const themeRules = buildThresholdRuleMap(thresholdManifest.themes || [], 'theme');
+  const coverageEnabled = options.coverageEnabled !== false;
+  const violations = [];
+  let configuredRules = moduleRules.size + themeRules.size;
+  let evaluatedRules = 0;
+  let passedRules = 0;
+  let failedRules = 0;
+  let warningRules = 0;
+
+  const annotatedModules = (Array.isArray(modules) ? modules : []).map((moduleEntry) => {
+    const moduleRule = moduleRules.get(moduleEntry.module) || null;
+    const evaluatedModuleThreshold = evaluateThresholdRule(coverageEnabled ? moduleEntry.coverage : null, moduleRule, {
+      scopeType: 'module',
+      module: moduleEntry.module,
+      theme: null,
+      label: moduleEntry.module,
+    });
+    if (evaluatedModuleThreshold && evaluatedModuleThreshold.status !== 'skipped') {
+      evaluatedRules += 1;
+      if (evaluatedModuleThreshold.status === 'failed') failedRules += 1;
+      if (evaluatedModuleThreshold.status === 'warn') warningRules += 1;
+      if (evaluatedModuleThreshold.status === 'passed') passedRules += 1;
+      violations.push(...evaluatedModuleThreshold.violations);
+    }
+
+    return {
+      ...moduleEntry,
+      threshold: evaluatedModuleThreshold,
+      themes: (Array.isArray(moduleEntry.themes) ? moduleEntry.themes : []).map((themeEntry) => {
+        const themeRule = themeRules.get(`${moduleEntry.module}/${themeEntry.theme}`) || null;
+        const evaluatedThemeThreshold = evaluateThresholdRule(coverageEnabled ? themeEntry.coverage : null, themeRule, {
+          scopeType: 'theme',
+          module: moduleEntry.module,
+          theme: themeEntry.theme,
+          label: `${moduleEntry.module} / ${themeEntry.theme}`,
+        });
+        if (evaluatedThemeThreshold && evaluatedThemeThreshold.status !== 'skipped') {
+          evaluatedRules += 1;
+          if (evaluatedThemeThreshold.status === 'failed') failedRules += 1;
+          if (evaluatedThemeThreshold.status === 'warn') warningRules += 1;
+          if (evaluatedThemeThreshold.status === 'passed') passedRules += 1;
+          violations.push(...evaluatedThemeThreshold.violations);
+        }
+        return {
+          ...themeEntry,
+          threshold: evaluatedThemeThreshold,
+        };
+      }),
+    };
+  });
+
+  return {
+    modules: annotatedModules,
+    summary: {
+      totalRules: configuredRules,
+      evaluatedRules,
+      passedRules,
+      failedRules,
+      warningRules,
+      violations,
+    },
+  };
+}
+
 export async function applyPolicyPipeline(context, suiteResults) {
   if (!context?.policy) {
     return suiteResults;
@@ -370,6 +437,7 @@ function loadPolicyManifests(config, configDir) {
     classification: loadManifestEntry(resolveManifestPath(config, 'classification'), configDir, cache),
     coverageAttribution: loadManifestEntry(resolveManifestPath(config, 'coverageAttribution'), configDir, cache),
     ownership: loadManifestEntry(resolveManifestPath(config, 'ownership'), configDir, cache),
+    thresholds: loadManifestEntry(resolveManifestPath(config, 'thresholds'), configDir, cache),
   };
 }
 
@@ -405,6 +473,10 @@ function loadManifestEntry(manifestPath, configDir, cache) {
       modules: Array.isArray(payload.ownership?.modules) ? payload.ownership.modules : [],
       themes: Array.isArray(payload.ownership?.themes) ? payload.ownership.themes : [],
     },
+    thresholds: {
+      modules: Array.isArray(payload.thresholds?.modules) ? payload.thresholds.modules : [],
+      themes: Array.isArray(payload.thresholds?.themes) ? payload.thresholds.themes : [],
+    },
     raw: payload,
   };
   cache.set(resolved, manifest);
@@ -534,6 +606,164 @@ function getPackageRelativeCandidates(context, suite, filePath) {
   return dedupe(candidates);
 }
 
+function buildThresholdRuleMap(entries, scopeType) {
+  const ruleMap = new Map();
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    const normalized = normalizeThresholdRule(entry, scopeType);
+    if (!normalized) {
+      continue;
+    }
+    ruleMap.set(normalized.key, normalized);
+  }
+  return ruleMap;
+}
+
+function normalizeThresholdRule(entry, scopeType) {
+  if (!entry || typeof entry !== 'object') {
+    return null;
+  }
+  const moduleName = typeof entry.module === 'string' && entry.module.trim().length > 0
+    ? entry.module.trim()
+    : null;
+  const themeName = typeof entry.theme === 'string' && entry.theme.trim().length > 0
+    ? entry.theme.trim()
+    : null;
+
+  if (!moduleName) {
+    return null;
+  }
+  if (scopeType === 'theme' && !themeName) {
+    return null;
+  }
+
+  const metrics = normalizeThresholdMetrics(entry.coverage || entry.minimums || entry.thresholds || {});
+  if (metrics.length === 0) {
+    return null;
+  }
+
+  const enforcement = entry.enforcement === 'warn' || entry.severity === 'warn'
+    ? 'warn'
+    : 'error';
+
+  return {
+    key: scopeType === 'theme' ? `${moduleName}/${themeName}` : moduleName,
+    module: moduleName,
+    theme: themeName,
+    scopeType,
+    enforcement,
+    reason: typeof entry.reason === 'string' && entry.reason.trim().length > 0
+      ? entry.reason.trim()
+      : null,
+    metrics,
+  };
+}
+
+function normalizeThresholdMetrics(source) {
+  const metrics = [];
+  for (const metricKey of ['lines', 'branches', 'functions', 'statements']) {
+    const minPct = resolveThresholdMetric(source, metricKey);
+    if (!Number.isFinite(minPct)) {
+      continue;
+    }
+    metrics.push({
+      metric: metricKey,
+      minPct: Number(Number(minPct).toFixed(2)),
+    });
+  }
+  return metrics;
+}
+
+function resolveThresholdMetric(source, metricKey) {
+  if (!source || typeof source !== 'object') {
+    return null;
+  }
+
+  if (Number.isFinite(source[`${metricKey}Pct`])) {
+    return source[`${metricKey}Pct`];
+  }
+
+  if (Number.isFinite(source[metricKey])) {
+    return source[metricKey];
+  }
+
+  const nested = source[metricKey];
+  if (!nested || typeof nested !== 'object') {
+    return null;
+  }
+
+  for (const key of ['minPct', 'minimum', 'pct', 'threshold']) {
+    if (Number.isFinite(nested[key])) {
+      return nested[key];
+    }
+  }
+
+  return null;
+}
+
+function evaluateThresholdRule(coverage, rule, scope) {
+  if (!rule) {
+    return null;
+  }
+
+  const metrics = rule.metrics.map((metric) => {
+    const actualPct = coverage?.[metric.metric]?.pct;
+    return {
+      metric: metric.metric,
+      minPct: metric.minPct,
+      actualPct: Number.isFinite(actualPct) ? Number(Number(actualPct).toFixed(2)) : null,
+      passed: Number.isFinite(actualPct) && actualPct >= metric.minPct,
+    };
+  });
+
+  if (!metrics.some((metric) => Number.isFinite(metric.actualPct))) {
+    return {
+      configured: true,
+      scopeType: scope.scopeType,
+      module: scope.module,
+      theme: scope.theme,
+      label: scope.label,
+      enforcement: rule.enforcement,
+      reason: rule.reason,
+      status: 'skipped',
+      metrics,
+      violations: [],
+    };
+  }
+
+  const failures = metrics.filter((metric) => !metric.passed);
+  const status = failures.length === 0
+    ? 'passed'
+    : (rule.enforcement === 'warn' ? 'warn' : 'failed');
+
+  return {
+    configured: true,
+    scopeType: scope.scopeType,
+    module: scope.module,
+    theme: scope.theme,
+    label: scope.label,
+    enforcement: rule.enforcement,
+    reason: rule.reason,
+    status,
+    metrics,
+    violations: failures.map((metric) => ({
+      scopeType: scope.scopeType,
+      module: scope.module,
+      theme: scope.theme,
+      label: scope.label,
+      enforcement: rule.enforcement,
+      metric: metric.metric,
+      minPct: metric.minPct,
+      actualPct: metric.actualPct,
+      message: formatThresholdViolation(scope.label, metric),
+    })),
+  };
+}
+
+function formatThresholdViolation(label, metric) {
+  const actual = Number.isFinite(metric.actualPct) ? `${metric.actualPct.toFixed(2)}%` : 'n/a';
+  return `${label} ${metric.metric} coverage ${actual} is below ${metric.minPct.toFixed(2)}%`;
+}
+
 function normalizeProjectRelative(rootDir, filePath) {
   if (!rootDir || !filePath) {
     return null;

package/src/report.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { mergeCoverageSummaries, normalizeCoverageSummary } from './coverage.js';
-import { collectCoverageAttribution, lookupOwner } from './policy.js';
+import { collectCoverageAttribution, lookupOwner, evaluateCoverageThresholds } from './policy.js';
 
 export function createSummary(values = {}) {
   return {
@@ -145,8 +145,13 @@ export function buildReportFromSuiteResults(context, suiteResults, durationMs) {
 
   const allTests = packages.flatMap((pkg) => pkg.suites.flatMap((suite) => suite.tests));
   const coverageAttribution = collectCoverageAttribution(context.policy, packages, context.project);
-  const modules = buildModulesFromPackages(packages, coverageAttribution.files, context.policy);
+  const moduleResults = buildModulesFromPackages(packages, coverageAttribution.files, context.policy);
+  const thresholdEvaluation = evaluateCoverageThresholds(context.policy, moduleResults, {
+    coverageEnabled: !context.execution?.coverageExplicitlyDisabled,
+  });
+  const modules = thresholdEvaluation.modules;
   const overallCoverage = mergeCoverageSummaries(packages.map((pkg) => pkg.coverage).filter(Boolean));
+  const diagnosticsSummary = summarizeDiagnostics(packages);
 
   return {
     schemaVersion: '1',
@@ -169,6 +174,12 @@ export function buildReportFromSuiteResults(context, suiteResults, durationMs) {
       coverage: overallCoverage,
       classification: summarizeClassification(allTests),
       coverageAttribution: coverageAttribution.summary,
+      policy: {
+        failedThresholds: thresholdEvaluation.summary.failedRules,
+        warningThresholds: thresholdEvaluation.summary.warningRules,
+        diagnosticsSuites: diagnosticsSummary.totalSuites,
+        failedDiagnostics: diagnosticsSummary.failedSuites,
+      },
       filterOptions: {
         modules: dedupe(modules.map((moduleEntry) => moduleEntry.module)).sort(),
         packages: packages.map((pkg) => pkg.name).sort(),
@@ -177,8 +188,12 @@ export function buildReportFromSuiteResults(context, suiteResults, durationMs) {
     },
     packages,
     modules,
+    policy: {
+      thresholds: thresholdEvaluation.summary,
+      diagnostics: diagnosticsSummary,
+    },
     meta: {
-      phase: 5,
+      phase: 8,
       projectName: context.project.name,
       projectRootDir: context.project.rootDir,
       outputDir: context.project.outputDir,
@@ -219,6 +234,7 @@ function buildModulesFromPackages(packages, coverageFiles, policy) {
             command: suite.command,
             warnings: suite.warnings,
             coverage: null,
+            diagnostics: suite.diagnostics || null,
             rawArtifacts: suite.rawArtifacts,
             tests: [],
             summary: createSummary(),
@@ -366,6 +382,16 @@ function stripSuitePackageName(suite) {
   return rest;
 }
 
+function summarizeDiagnostics(packages) {
+  const diagnostics = (packages || []).flatMap((pkg) => pkg.suites.map((suite) => suite.diagnostics).filter(Boolean));
+  return {
+    totalSuites: diagnostics.length,
+    passedSuites: diagnostics.filter((entry) => entry.status === 'passed').length,
+    failedSuites: diagnostics.filter((entry) => entry.status === 'failed').length,
+    skippedSuites: diagnostics.filter((entry) => entry.status === 'skipped').length,
+  };
+}
+
 function normalizeRawArtifacts(rawArtifacts, suite) {
   return (Array.isArray(rawArtifacts) ? rawArtifacts : [])
     .map((artifact) => normalizeRawArtifact(artifact, suite))

package/src/run-report.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { spawn } from 'node:child_process';
 import { loadConfig, applyConfigOverrides, resolveProjectContext } from './config.js';
 import { preparePolicyContext, applyPolicyPipeline } from './policy.js';
 import { resolveAdapterForSuite } from './adapters.js';
@@ -25,6 +26,7 @@ export async function runReport(options = {}) {
     execution: {
       dryRun: options.dryRun ?? Boolean(effectiveConfig?.execution?.dryRun),
       coverage: options.coverage ?? Boolean(effectiveConfig?.execution?.defaultCoverage),
+      coverageExplicitlyDisabled: options.coverage === false,
     },
   };
   context.policy = await preparePolicyContext(effectiveLoaded, context.project);
@@ -126,6 +128,13 @@ export async function runReport(options = {}) {
         }
       }
 
+      if (!context.execution.dryRun && normalized.status === 'failed') {
+        const diagnostics = await runSuiteDiagnostics(suite, context, options);
+        if (diagnostics) {
+          normalized = attachDiagnostics(normalized, diagnostics);
+        }
+      }
+
       suiteResults.push(normalized);
       packageSuiteResults.push(normalized);
       emitEvent(options, {
@@ -282,3 +291,254 @@ function relativePathSafe(fromPath, toPath) {
     return null;
   }
 }
+
+async function runSuiteDiagnostics(suite, context, options) {
+  const config = normalizeDiagnosticsConfig(suite);
+  if (!config) {
+    return null;
+  }
+
+  const label = config.label || 'Diagnostics rerun';
+  emitEvent(options, {
+    type: 'suite-diagnostics-start',
+    packageName: suite.packageName,
+    packageLocation: derivePackageLocation(suite, context.project),
+    suiteId: suite.id,
+    suiteLabel: suite.label,
+    diagnosticsLabel: label,
+  });
+
+  const startedAt = Date.now();
+  const command = config.command || suite.command;
+  const commandText = formatCommand(command);
+  const result = await executeDiagnosticCommand(command, {
+    cwd: config.cwd || suite.cwd || context.project.rootDir,
+    env: {
+      ...(suite.env || {}),
+      ...(config.env || {}),
+    },
+    timeoutMs: config.timeoutMs,
+  });
+
+  const durationMs = Date.now() - startedAt;
+  const artifactBase = `diagnostics/${slugify(suite.packageName || 'default')}-${slugify(suite.id)}-rerun`;
+  const rawArtifacts = [
+    {
+      relativePath: `${artifactBase}.log`,
+      label: `${label} log`,
+      content: buildDiagnosticsLog(result),
+    },
+    {
+      relativePath: `${artifactBase}.json`,
+      label: `${label} metadata`,
+      content: `${JSON.stringify({
+        label,
+        command: commandText,
+        cwd: config.cwd || suite.cwd || context.project.rootDir,
+        status: result.status,
+        exitCode: result.exitCode,
+        signal: result.signal,
+        timedOut: result.timedOut,
+        durationMs,
+      }, null, 2)}\n`,
+    },
+  ];
+
+  const diagnostics = {
+    label,
+    status: result.status,
+    command: commandText,
+    cwd: config.cwd || suite.cwd || context.project.rootDir,
+    durationMs,
+    exitCode: result.exitCode,
+    signal: result.signal,
+    timedOut: result.timedOut,
+    output: {
+      stdout: result.stdout,
+      stderr: result.stderr,
+    },
+    rawArtifacts,
+  };
+
+  emitEvent(options, {
+    type: 'suite-diagnostics-complete',
+    packageName: suite.packageName,
+    packageLocation: derivePackageLocation(suite, context.project),
+    suiteId: suite.id,
+    suiteLabel: suite.label,
+    diagnosticsLabel: label,
+    result: diagnostics,
+  });
+
+  return diagnostics;
+}
+
+function normalizeDiagnosticsConfig(suite) {
+  if (!suite?.diagnostics || typeof suite.diagnostics !== 'object') {
+    return null;
+  }
+  return {
+    label: typeof suite.diagnostics.label === 'string' && suite.diagnostics.label.trim().length > 0
+      ? suite.diagnostics.label.trim()
+      : 'Diagnostics rerun',
+    command: suite.diagnostics.command || suite.command,
+    cwd: suite.diagnostics.cwd || null,
+    env: suite.diagnostics.env && typeof suite.diagnostics.env === 'object'
+      ? suite.diagnostics.env
+      : {},
+    timeoutMs: Number.isFinite(suite.diagnostics.timeoutMs) ? suite.diagnostics.timeoutMs : null,
+  };
+}
+
+async function executeDiagnosticCommand(command, options) {
+  const spec = normalizeCommand(command);
+  if (!spec) {
+    return {
+      status: 'skipped',
+      exitCode: null,
+      signal: null,
+      timedOut: false,
+      stdout: '',
+      stderr: 'No diagnostic command configured.',
+    };
+  }
+
+  return new Promise((resolve) => {
+    const child = spawn(spec.command, spec.args, {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...(options.env || {}),
+      },
+      shell: spec.shell,
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let settled = false;
+    let timeoutId = null;
+
+    if (child.stdout) {
+      child.stdout.on('data', (chunk) => {
+        stdout += String(chunk);
+      });
+    }
+
+    if (child.stderr) {
+      child.stderr.on('data', (chunk) => {
+        stderr += String(chunk);
+      });
+    }
+
+    if (Number.isFinite(options.timeoutMs) && options.timeoutMs > 0) {
+      timeoutId = setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGTERM');
+      }, options.timeoutMs);
+    }
+
+    const finish = (payload) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      resolve(payload);
+    };
+
+    child.on('error', (error) => {
+      finish({
+        status: 'failed',
+        exitCode: null,
+        signal: null,
+        timedOut,
+        stdout,
+        stderr: `${stderr}${error instanceof Error ? error.stack || error.message : String(error)}\n`,
+      });
+    });
+
+    child.on('close', (code, signal) => {
+      finish({
+        status: timedOut
+          ? 'failed'
+          : (code === 0 ? 'passed' : 'failed'),
+        exitCode: Number.isFinite(code) ? code : null,
+        signal: signal || null,
+        timedOut,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+function normalizeCommand(command) {
+  if (Array.isArray(command)) {
+    const parts = command.map((value) => String(value || '')).filter(Boolean);
+    if (parts.length === 0) {
+      return null;
+    }
+    return {
+      command: parts[0],
+      args: parts.slice(1),
+      shell: false,
+    };
+  }
+
+  if (typeof command === 'string' && command.trim().length > 0) {
+    return {
+      command,
+      args: [],
+      shell: true,
+    };
+  }
+
+  return null;
+}
+
+function attachDiagnostics(suiteResult, diagnostics) {
+  const warnings = [...(suiteResult.warnings || [])];
+  warnings.push(`Diagnostics rerun ${diagnostics.status} (${diagnostics.label}).`);
+  return {
+    ...suiteResult,
+    warnings,
+    diagnostics,
+    rawArtifacts: [
+      ...(suiteResult.rawArtifacts || []),
+      ...(diagnostics.rawArtifacts || []),
+    ],
+  };
+}
+
+function buildDiagnosticsLog(result) {
+  const sections = [
+    '# stdout',
+    result.stdout || '',
+    '',
+    '# stderr',
+    result.stderr || '',
+  ];
+  return `${sections.join('\n')}\n`;
+}
+
+function formatCommand(command) {
+  if (Array.isArray(command)) {
+    return command.map((entry) => shellEscape(entry)).join(' ');
+  }
+  return typeof command === 'string' ? command : '';
+}
+
+function shellEscape(value) {
+  const normalized = String(value || '');
+  if (/^[A-Za-z0-9_./:=+-]+$/.test(normalized)) {
+    return normalized;
+  }
+  return JSON.stringify(normalized);
+}
+
+function slugify(value) {
+  return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}