qa-engineer 0.9.2 → 0.11.0

package/packages/engine/lib/artifacts/zip-write.mjs

@@ -0,0 +1,143 @@
+// Writing a ZIP, with no dependencies.
+//
+// `lib/analysis/zip.mjs` reads them (Playwright traces); this writes them, so a report
+// folder can leave as one file a stakeholder can actually receive. Every mail system,
+// ticket tracker, and chat tool accepts a `.zip`; none of them accept a directory.
+//
+// ## Scope
+//
+// The minimum format that every extractor understands: local headers, deflate or
+// store, a central directory, and an end-of-central-directory record. No ZIP64, no
+// encryption, no multi-disk — a QA report is megabytes, not gigabytes, and the
+// simplest file that opens everywhere is the right one.
+//
+// ## Reproducibility
+//
+// Timestamps come from the caller, defaulting to the report's own `generatedAt`.
+// Re-zipping the same report therefore produces the same bytes, so a bundle can be
+// checksummed and a diff between two runs is a diff of the content.
+
+import zlib from 'node:zlib';
+
+const LOCAL_SIGNATURE = 0x04034b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const EOCD_SIGNATURE = 0x06054b50;
+
+// Deflate is only worth its CPU on compressible bytes. A PNG or an MP4 is already
+// compressed, and re-deflating it costs time to make the file marginally larger.
+const ALREADY_COMPRESSED = new Set([
+  '.png', '.jpg', '.jpeg', '.webp', '.gif', '.avif', '.mp4', '.webm', '.ogv', '.zip', '.gz',
+]);
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+export function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** MS-DOS date and time, the only clock a ZIP header understands. */
+function dosStamp(date) {
+  // The format cannot represent anything before 1980; clamp rather than wrap, so a
+  // missing or nonsense timestamp produces a valid archive.
+  const year = Math.max(1980, date.getFullYear());
+  const time =
+    (date.getHours() << 11) | (date.getMinutes() << 5) | Math.floor(date.getSeconds() / 2);
+  const day = ((year - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate();
+  return { time: time & 0xffff, date: day & 0xffff };
+}
+
+function shouldStore(name) {
+  const dot = name.lastIndexOf('.');
+  return dot > 0 && ALREADY_COMPRESSED.has(name.slice(dot).toLowerCase());
+}
+
+/**
+ * Build a ZIP from `[{ name, data }]`.
+ *
+ * `name` is the path inside the archive and always uses forward slashes — a backslash
+ * here produces an archive that extracts into one long filename on Unix.
+ */
+export function createZip(entries, { modifiedAt = new Date(0) } = {}) {
+  const stamp = dosStamp(modifiedAt.getFullYear() >= 1980 ? modifiedAt : new Date('1980-01-01T00:00:00Z'));
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+
+  for (const entry of entries) {
+    const name = Buffer.from(String(entry.name).split('\\').join('/'), 'utf8');
+    const data = Buffer.isBuffer(entry.data) ? entry.data : Buffer.from(entry.data, 'utf8');
+    const store = shouldStore(entry.name);
+    const compressed = store ? data : zlib.deflateRawSync(data, { level: 9 });
+    // Deflate can inflate small or incompressible input; storing it is then both
+    // smaller and faster to read back.
+    const useStore = store || compressed.length >= data.length;
+    const body = useStore ? data : compressed;
+    const method = useStore ? 0 : 8;
+    const checksum = crc32(data);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(LOCAL_SIGNATURE, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt16LE(stamp.time, 10);
+    local.writeUInt16LE(stamp.date, 12);
+    local.writeUInt32LE(checksum, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    locals.push(local, name, body);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(CENTRAL_SIGNATURE, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt16LE(stamp.time, 12);
+    central.writeUInt16LE(stamp.date, 14);
+    central.writeUInt32LE(checksum, 16);
+    central.writeUInt32LE(body.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    // 0o644 in the high 16 bits, so extraction on Unix produces readable files rather
+    // than mode 000.
+    central.writeUInt32LE((0o100644 << 16) >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, name);
+
+    offset += local.length + name.length + body.length;
+  }
+
+  const centralBuffer = Buffer.concat(centrals);
+  // End of central directory. The field offsets are 4/6/8/10/12/16/20 — writing the
+  // directory size and its offset two bytes late produces a file that every extractor
+  // reads as truncated by roughly a gigabyte, because it takes the tail of one field
+  // and the head of the next as a length.
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(EOCD_SIGNATURE, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(centralBuffer.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...locals, centralBuffer, eocd]);
+}

package/packages/engine/lib/diagnostics/engine.mjs

@@ -0,0 +1,165 @@
+// The diagnostic engine — the one place failure reasoning happens.
+//
+// Orchestrates the analysis platform and the diagnostics modules into a single
+// diagnosis: per-failure root cause, prioritization, a reconstructed timeline, and
+// ranked recommendations. qa-debug presents the diagnosis; qa-fix turns it into
+// repair plans; qa-report aggregates diagnoses. None of them re-implements this.
+
+import * as taxonomy from '../analysis/taxonomy.mjs';
+
+import { analyze } from './root-cause.mjs';
+import { prioritize } from './prioritization.mjs';
+import { planRepair } from './repair.mjs';
+import { buildTimeline } from './timeline.mjs';
+import { validateDiagnosis } from './internal-contracts.mjs';
+
+const PRIORITY_RANK = { P1: 3, P2: 2, P3: 1 };
+
+// Classifications that block a release when they are the cause of a failure.
+const RELEASE_BLOCKING = new Set([
+  taxonomy.APPLICATION_BUG, taxonomy.NETWORK, taxonomy.INFRASTRUCTURE,
+  taxonomy.AUTH, taxonomy.AUTHORIZATION,
+]);
+
+/**
+ * Produce a full diagnosis from the available results.
+ *
+ * `{entries, timeline, recommendations}`, where each entry combines a root cause
+ * with its prioritization and affected tests.
+ */
+export function diagnose(executionResult, { analysisResult = null } = {}) {
+  const signals = deriveSignals(executionResult, analysisResult);
+  const findings = (analysisResult ?? {}).findings ?? [];
+
+  const entries = signals.map((signal) => {
+    const rootCause = analyze(signal);
+    const blocking = RELEASE_BLOCKING.has(rootCause.classification);
+    return {
+      rootCause,
+      priority: prioritize(rootCause, { blocking }),
+      affectedTests: signal.affectedTests ?? [],
+    };
+  });
+
+  // Highest priority first, then highest confidence. Python's `sort(reverse=True)`
+  // on a tuple key is a stable descending sort, so equal keys keep insertion order
+  // — reproduced by comparing in reverse and falling back to the original index.
+  const decorated = entries.map((entry, index) => ({ entry, index }));
+  decorated.sort((a, b) => {
+    const rank = (PRIORITY_RANK[b.entry.priority.priority] ?? 0) - (PRIORITY_RANK[a.entry.priority.priority] ?? 0);
+    if (rank !== 0) return rank;
+    const confidence = b.entry.rootCause.confidence - a.entry.rootCause.confidence;
+    if (confidence !== 0) return confidence;
+    // Insertion order for ties. Python's `sort(reverse=True)` is stable, so equal
+    // keys keep the order they arrived in — reversing the tie-break too would put
+    // two equally-ranked locator failures back to front.
+    return a.index - b.index;
+  });
+
+  const diagnosis = {
+    entries: decorated.map(({ entry }) => entry),
+    timeline: buildTimeline(executionResult, findings),
+    recommendations: recommendations(decorated.map(({ entry }) => entry)),
+  };
+  // Mechanical seam enforcement: a diagnosis must match the internal contract.
+  return validateDiagnosis(diagnosis);
+}
+
+/**
+ * Turn a diagnosis into repair plans (for qa-fix).
+ *
+ * One plan per entry; non-repairable causes yield an escalation plan. Never
+ * produces code.
+ */
+export function planRepairs(diagnosis) {
+  return diagnosis.entries.map((entry) => ({
+    ...planRepair(entry.rootCause, entry.affectedTests),
+    priority: entry.priority.priority,
+  }));
+}
+
+/**
+ * Aggregate a diagnosis for qa-report: totals, breakdown by classification, the
+ * top-priority findings, and a deterministic release-readiness call.
+ */
+export function summarize(executionResult, diagnosis) {
+  const tests = (executionResult ?? {}).tests ?? {};
+  const byClassification = {};
+  for (const entry of diagnosis.entries) {
+    const cls = entry.rootCause.classification;
+    byClassification[cls] = (byClassification[cls] ?? 0) + 1;
+  }
+
+  return {
+    totals: tests,
+    byClassification,
+    topPriority: diagnosis.entries.filter((entry) => entry.priority.priority === 'P1'),
+    releaseReadiness: releaseReadiness(executionResult, diagnosis),
+  };
+}
+
+/** Derive failure signals, preferring the analysis platform's findings. */
+function deriveSignals(executionResult, analysisResult) {
+  const findings = (analysisResult ?? {}).findings ?? [];
+  if (findings.length > 0) {
+    return findings.map((finding) => ({
+      message: finding.reason ?? '',
+      classification: finding.classification,
+      confidence: finding.confidence,
+      reason: finding.reason,
+      httpStatus: finding.httpStatus,
+      retries: finding.retries ?? 0,
+      finalStatus: finding.finalStatus,
+      evidence: finding.evidence ?? [],
+      affectedTests: finding.affectedTests ?? [],
+    }));
+  }
+
+  const signals = [];
+  for (const test of (executionResult ?? {}).executed ?? []) {
+    if (test.status === 'failed' || test.status === 'flaky') {
+      signals.push({
+        message: test.message ?? '',
+        retries: test.retries ?? 0,
+        finalStatus: test.status,
+        affectedTests: [test.title ?? ''],
+        evidence: [{
+          type: 'junit',
+          description: `${test.status}: ${test.title ?? ''}`,
+          source: test.file ?? 'execution-result',
+        }],
+      });
+    }
+  }
+  return signals;
+}
+
+/** Ranked, de-duplicated recommendations — highest priority first. */
+function recommendations(entries) {
+  const seen = new Set();
+  const ranked = [];
+  for (const entry of entries) {
+    const action = entry.rootCause.recommendation;
+    if (seen.has(action)) continue;
+    seen.add(action);
+    ranked.push({
+      action,
+      priority: entry.priority.priority,
+      owner: entry.rootCause.ownership,
+      classification: entry.rootCause.classification,
+    });
+  }
+  return ranked;
+}
+
+function releaseReadiness(executionResult, diagnosis) {
+  const failed = ((executionResult ?? {}).tests ?? {}).failed ?? 0;
+  if (failed === 0 && diagnosis.entries.length === 0) return 'ready';
+  const classes = new Set(diagnosis.entries.map((entry) => entry.rootCause.classification));
+  for (const blocking of RELEASE_BLOCKING) {
+    if (classes.has(blocking)) return 'not-ready';
+  }
+  // `classes <= {UNKNOWN}` in Python: every class is unknown (or there are none).
+  if ([...classes].every((cls) => cls === taxonomy.UNKNOWN)) return 'insufficient-data';
+  return 'ready-with-risks';
+}

package/packages/engine/lib/diagnostics/internal-contracts.mjs

@@ -0,0 +1,50 @@
+// Validate internal Analysis → Diagnostics seam payloads.
+//
+// Uses the dependency-free contract validator against the schemas under
+// shared/diagnostics/schemas/internal/.
+//
+// The schemas must be reachable in both layouts this code runs in: beside the
+// engine when it ships inside the package, and at the canonical repository path
+// during development. Missing schemas raise InternalContractError naming the
+// locations tried, rather than a bare ENOENT from deep inside a diagnosis.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { validate } from '../analysis/contracts.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const SCHEMA_DIRS = [path.join(here, 'schemas', 'internal')];
+
+export class InternalContractError extends Error {}
+
+/** The directory holding the internal schemas, whichever layout applies. */
+export function schemaDir() {
+  for (const candidate of SCHEMA_DIRS) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return candidate;
+  }
+  throw new InternalContractError(
+    `internal schemas not found; tried: ${SCHEMA_DIRS.join(', ')}. ` +
+      'A package that ships the engine must carry diagnostics/schemas/internal/.',
+  );
+}
+
+function load(name) {
+  const file = path.join(schemaDir(), name);
+  if (!fs.existsSync(file)) throw new InternalContractError(`internal schema missing: ${file}`);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function require_(payload, schemaName) {
+  const errors = validate(payload, load(schemaName));
+  if (errors.length > 0) {
+    throw new InternalContractError(`${schemaName}: ${errors.join('; ')}`);
+  }
+  return payload;
+}
+
+export const validateAnalysisResult = (payload) => require_(payload, 'analysis-result.schema.json');
+export const validateExecutionResultMin = (payload) => require_(payload, 'execution-result-min.schema.json');
+export const validateDiagnosis = (payload) => require_(payload, 'diagnosis.schema.json');

package/packages/engine/lib/diagnostics/prioritization.mjs

@@ -0,0 +1,99 @@
+// Deterministic finding prioritization.
+//
+// Assigns every finding a severity, priority, the three impacts, an owner, and an
+// estimated effort — by a fixed algorithm, so the same finding always ranks the
+// same way. Priority is not a feeling; it is a function of severity, confidence,
+// and business impact.
+
+import * as taxonomy from '../analysis/taxonomy.mjs';
+
+// Base severity per classification (before confidence adjustment).
+const SEVERITY = {
+  [taxonomy.APPLICATION_BUG]: 'high',
+  [taxonomy.INFRASTRUCTURE]: 'high',
+  [taxonomy.NETWORK]: 'high',
+  [taxonomy.AUTH]: 'high',
+  [taxonomy.AUTHORIZATION]: 'high',
+  [taxonomy.ASSERTION]: 'medium',
+  [taxonomy.LOCATOR]: 'medium',
+  [taxonomy.TIMEOUT]: 'medium',
+  [taxonomy.TEST_DATA]: 'medium',
+  [taxonomy.CONFIGURATION]: 'medium',
+  [taxonomy.ENVIRONMENT]: 'medium',
+  [taxonomy.FRAMEWORK]: 'medium',
+  [taxonomy.FLAKY]: 'medium',
+  [taxonomy.UNKNOWN]: 'low',
+};
+
+// Where the impact predominantly lands, per classification.
+const IMPACT = {
+  [taxonomy.APPLICATION_BUG]: { business: 'high', technical: 'high', testing: 'low' },
+  [taxonomy.NETWORK]: { business: 'high', technical: 'high', testing: 'medium' },
+  [taxonomy.AUTH]: { business: 'high', technical: 'medium', testing: 'medium' },
+  [taxonomy.AUTHORIZATION]: { business: 'high', technical: 'medium', testing: 'medium' },
+  [taxonomy.INFRASTRUCTURE]: { business: 'medium', technical: 'high', testing: 'high' },
+  [taxonomy.LOCATOR]: { business: 'low', technical: 'low', testing: 'high' },
+  [taxonomy.ASSERTION]: { business: 'medium', technical: 'medium', testing: 'medium' },
+  [taxonomy.TIMEOUT]: { business: 'low', technical: 'medium', testing: 'high' },
+  [taxonomy.TEST_DATA]: { business: 'low', technical: 'low', testing: 'high' },
+  [taxonomy.CONFIGURATION]: { business: 'low', technical: 'medium', testing: 'high' },
+  [taxonomy.ENVIRONMENT]: { business: 'low', technical: 'medium', testing: 'high' },
+  [taxonomy.FRAMEWORK]: { business: 'low', technical: 'medium', testing: 'high' },
+  [taxonomy.FLAKY]: { business: 'low', technical: 'low', testing: 'high' },
+  [taxonomy.UNKNOWN]: { business: 'low', technical: 'low', testing: 'medium' },
+};
+
+// Rough effort to resolve, per classification.
+const EFFORT = {
+  [taxonomy.LOCATOR]: 'low',
+  [taxonomy.ASSERTION]: 'low',
+  [taxonomy.CONFIGURATION]: 'low',
+  [taxonomy.ENVIRONMENT]: 'low',
+  [taxonomy.TEST_DATA]: 'medium',
+  [taxonomy.TIMEOUT]: 'medium',
+  [taxonomy.FLAKY]: 'medium',
+  [taxonomy.AUTH]: 'medium',
+  [taxonomy.AUTHORIZATION]: 'medium',
+  [taxonomy.FRAMEWORK]: 'medium',
+  [taxonomy.NETWORK]: 'high',
+  [taxonomy.INFRASTRUCTURE]: 'high',
+  [taxonomy.APPLICATION_BUG]: 'external',
+  [taxonomy.UNKNOWN]: 'unknown',
+};
+
+const RANK = { low: 1, medium: 2, high: 3 };
+const PRIORITY = { 1: 'P3', 2: 'P2', 3: 'P1', 4: 'P1' };
+
+/**
+ * Prioritize a root cause.
+ *
+ * Priority derives from severity, business impact, and confidence, and is escalated
+ * one step when the failure blocks a release.
+ */
+export function prioritize(rootCause, { blocking = false } = {}) {
+  const classification = rootCause.classification;
+  const confidence = 'confidence' in rootCause && rootCause.confidence !== undefined
+    ? rootCause.confidence
+    : 0.5;
+  const severity = SEVERITY[classification] ?? 'low';
+  const impact = IMPACT[classification] ?? IMPACT[taxonomy.UNKNOWN];
+
+  // Priority score: severity and business impact drive it; low confidence holds it
+  // back (an uncertain finding should not top the queue).
+  let score = RANK[severity];
+  if (impact.business === 'high') score += 1;
+  if (confidence < 0.5) score -= 1;
+  if (blocking) score += 1;
+  score = Math.max(1, Math.min(4, score));
+
+  return {
+    severity,
+    priority: PRIORITY[score],
+    businessImpact: impact.business,
+    technicalImpact: impact.technical,
+    testingImpact: impact.testing,
+    confidence,
+    owner: rootCause.ownership ?? 'needs-triage',
+    estimatedEffort: EFFORT[classification] ?? 'unknown',
+  };
+}

package/packages/engine/lib/diagnostics/repair.mjs

@@ -0,0 +1,73 @@
+// Deterministic repair planning.
+//
+// Turns a root cause into a repair *plan* — never code. It decides whether the
+// failure is test-side repairable at all, and if so proposes an abstract change,
+// the candidate type, the risk, and a rollback. qa-fix consumes these plans; the
+// plan is always gated by the diff guard and always requires permission before any
+// edit is applied.
+
+import * as taxonomy from '../analysis/taxonomy.mjs';
+
+// classification -> [repairable, candidate type, abstract change, risk].
+// Only test-side causes are repairable; product, network, infra, authorization and
+// environment failures are escalations, not repairs.
+const PLANS = {
+  [taxonomy.LOCATOR]: [true, 'locator-update',
+    'Update the failing locator to target the same element in the current DOM.', 'low'],
+  [taxonomy.ASSERTION]: [true, 'assertion-improvement',
+    'Correct the assertion to match the intended behavior, or confirm a product bug first.', 'medium'],
+  [taxonomy.TIMEOUT]: [true, 'wait-strategy',
+    'Replace a fixed or missing wait with a web-first wait on the awaited condition.', 'medium'],
+  [taxonomy.FLAKY]: [true, 'synchronization',
+    'Remove the race by awaiting the real condition; add a tracked quarantine only if needed.', 'medium'],
+  [taxonomy.TEST_DATA]: [true, 'test-data',
+    'Repair or reseed the test data the scenario depends on.', 'medium'],
+  [taxonomy.CONFIGURATION]: [true, 'configuration',
+    'Correct the test configuration the run depends on.', 'low'],
+  [taxonomy.ENVIRONMENT]: [false, 'environment',
+    'Fix the environment (base URL, service availability); not a test-side repair.', 'n/a'],
+  [taxonomy.AUTH]: [true, 'authentication',
+    "Repair the test's credentials or auth setup; do not weaken the check.", 'medium'],
+  [taxonomy.AUTHORIZATION]: [false, 'authorization',
+    'Grant the test account permission or use an authorized role; not a code repair.', 'n/a'],
+  [taxonomy.NETWORK]: [false, 'network',
+    'Investigate the upstream service; not a test-side repair.', 'n/a'],
+  [taxonomy.INFRASTRUCTURE]: [false, 'infrastructure',
+    'Escalate to CI/infra; not a test-side repair.', 'n/a'],
+  [taxonomy.APPLICATION_BUG]: [false, 'application-bug',
+    'File a product bug; the test correctly caught a real defect.', 'n/a'],
+  [taxonomy.FRAMEWORK]: [false, 'framework',
+    'Update or pin the framework/driver; not a test-side repair.', 'n/a'],
+  [taxonomy.UNKNOWN]: [false, 'unknown',
+    'Investigate further before any repair.', 'n/a'],
+};
+
+/**
+ * Produce a repair plan for a root cause.
+ *
+ * `{repairable, candidateType, proposedChanges, affectedFiles, risk,
+ * permissionRequired, rollbackStrategy, safetyReview}`. Never contains code.
+ */
+export function planRepair(rootCause, affectedFiles = null) {
+  const [repairable, candidate, change, risk] =
+    PLANS[rootCause.classification] ?? PLANS[taxonomy.UNKNOWN];
+
+  const safety = repairable
+    ? 'Any edit will be checked by the diff guard before it is proposed as complete; ' +
+      'the guard rejects removed assertions, added skips, forced passes, and timeout inflation.'
+    : 'No test-side edit is appropriate; this is an escalation, not a repair.';
+  const rollback = repairable
+    ? 'No source is changed without approval; revert the proposed edits to roll back.'
+    : 'Not applicable — no change is proposed.';
+
+  return {
+    repairable,
+    candidateType: candidate,
+    proposedChanges: repairable ? [change] : [],
+    affectedFiles: [...(affectedFiles ?? [])],
+    risk,
+    permissionRequired: true,
+    rollbackStrategy: rollback,
+    safetyReview: safety,
+  };
+}

package/packages/engine/lib/diagnostics/root-cause.mjs

@@ -0,0 +1,92 @@
+// Deterministic root-cause analysis.
+//
+// Turns a failure signal into a classified root cause with the four things every
+// classification must carry: a taxonomy class (with confidence and evidence-backed
+// reason), a recommended action, and an owner. It reuses the analysis platform's
+// failure taxonomy; it adds the ownership and recommendation mappings and the
+// metadata-driven classes (flaky) the taxonomy cannot infer from a message alone.
+//
+// No unsupported conclusions: a signal that matches no rule is `unknown`.
+
+import * as taxonomy from '../analysis/taxonomy.mjs';
+
+/** classification -> the party that typically owns the fix. */
+export const OWNERSHIP = {
+  [taxonomy.ASSERTION]: 'test-author-or-product',
+  [taxonomy.LOCATOR]: 'test-author',
+  [taxonomy.TIMEOUT]: 'test-author-or-environment',
+  [taxonomy.NETWORK]: 'backend-or-infrastructure',
+  [taxonomy.AUTH]: 'auth-or-test-setup',
+  [taxonomy.AUTHORIZATION]: 'permissions-or-test-account',
+  [taxonomy.ENVIRONMENT]: 'environment-owner',
+  [taxonomy.CONFIGURATION]: 'config-owner',
+  [taxonomy.INFRASTRUCTURE]: 'ci-or-infrastructure',
+  [taxonomy.TEST_DATA]: 'test-data-owner',
+  [taxonomy.APPLICATION_BUG]: 'product',
+  [taxonomy.FRAMEWORK]: 'framework-or-driver',
+  [taxonomy.FLAKY]: 'test-author',
+  [taxonomy.UNKNOWN]: 'needs-triage',
+};
+
+// classification -> the safe recommended action (implements the analysis
+// platform's recommendation-guidelines; never recommends forcing a pass).
+export const RECOMMENDATION = {
+  [taxonomy.ASSERTION]: 'Confirm whether the app or the expectation is wrong; fix whichever is genuinely incorrect.',
+  [taxonomy.LOCATOR]: 'Inspect the current DOM and update the locator to target the same element.',
+  [taxonomy.TIMEOUT]: 'Investigate the slowness; raise a wait only if the operation is legitimately slower.',
+  [taxonomy.NETWORK]: 'Check the upstream service and the request; retry only if the failure is genuinely transient.',
+  [taxonomy.AUTH]: 'Fix the credentials or auth setup; do not weaken the authentication check.',
+  [taxonomy.AUTHORIZATION]: 'Grant the test account the needed permission or use an authorized role; do not bypass the check.',
+  [taxonomy.ENVIRONMENT]: 'Fix the environment (base URL, service availability); the test is likely fine.',
+  [taxonomy.CONFIGURATION]: 'Correct the configuration; do not work around it in the test.',
+  [taxonomy.INFRASTRUCTURE]: 'Escalate to CI or infrastructure owners; add resources, do not shrink the suite.',
+  [taxonomy.TEST_DATA]: 'Repair or reseed the data; do not delete the assertion that caught the gap.',
+  [taxonomy.APPLICATION_BUG]: 'File a bug against the product; do NOT modify the test to pass.',
+  [taxonomy.FRAMEWORK]: 'Update or pin the framework/driver; report upstream if it is a genuine defect.',
+  [taxonomy.FLAKY]: 'Stabilize the test (fix the race or synchronization); quarantine only with a tracking issue.',
+  [taxonomy.UNKNOWN]: 'Investigate further; the evidence was insufficient to classify.',
+};
+
+/**
+ * Classify a failure signal into a root cause.
+ *
+ * `signal` may carry: message, httpStatus, retries, finalStatus, classification,
+ * confidence, reason, evidence. Returns
+ * `{classification, confidence, reason, ownership, recommendation, evidence}`.
+ */
+export function analyze(signal) {
+  const message = signal.message ?? '';
+  const httpStatus = signal.httpStatus;
+  const retries = signal.retries || 0;
+  const finalStatus = signal.finalStatus;
+  const provided = signal.classification;
+
+  let classification;
+  let confidence;
+  let reason;
+
+  // Flakiness is a metadata signal, not a message pattern: a test that needed a
+  // retry to pass, or is explicitly flagged flaky, is nondeterministic.
+  if (finalStatus === 'flaky' || (retries > 0 && ['passed', 'flaky'].includes(finalStatus))) {
+    classification = taxonomy.FLAKY;
+    confidence = 0.8;
+    reason = 'The test passed only after a retry, indicating nondeterministic behavior.';
+  } else if (taxonomy.CLASSES.has(provided)) {
+    // The analysis platform already classified this deterministically; trust it
+    // rather than re-deriving from the message.
+    classification = provided;
+    confidence = 'confidence' in signal ? signal.confidence : 0.8;
+    reason = signal.reason || `Classified ${provided} by the analysis platform.`;
+  } else {
+    ({ classification, confidence, reason } = taxonomy.classify(message, httpStatus ?? null));
+  }
+
+  return {
+    classification,
+    confidence,
+    reason,
+    ownership: OWNERSHIP[classification] ?? 'needs-triage',
+    recommendation: RECOMMENDATION[classification] ?? RECOMMENDATION[taxonomy.UNKNOWN],
+    evidence: signal.evidence ?? [],
+  };
+}