qa-engineer 0.9.2 → 0.11.0

package/packages/engine/lib/analysis/redaction.mjs

@@ -0,0 +1,127 @@
+// Credential, secret, token, and PII redaction.
+//
+// Every analyzer runs artifact text through redaction before it appears in a
+// finding, a report, or stdout. Redaction happens as evidence is captured, not
+// after — a secret must never reach a model's context or a log.
+//
+// Ported from qa_analysis/redaction.py, rule for rule and in the same order, and
+// held to identical output by scripts/check-engine-parity.mjs. Python's inline
+// `(?i)` / `(?im)` flags become JavaScript flag letters; every rule carries `g`
+// because Python's `re.sub` replaces all occurrences.
+
+export class RedactionError extends Error {}
+
+// Ordered. Order matters: match structured, high-signal secrets (JWTs, provider
+// keys) before generic fallbacks.
+const RULES = [
+  { name: 'jwt', pattern: /eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}/g },
+  { name: 'aws-access-key', pattern: /AKIA[0-9A-Z]{16}/g },
+  { name: 'github-token', pattern: /gh[pousr]_[A-Za-z0-9]{20,}/g },
+  { name: 'slack-token', pattern: /xox[baprs]-[A-Za-z0-9-]{10,}/g },
+  { name: 'openai-key', pattern: /sk-[A-Za-z0-9]{20,}/g },
+  { name: 'bearer', pattern: /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi },
+  // Sensitive header lines: keep the header name, mask the value.
+  //
+  // The value is `[^\r\n]+` rather than `.+$`, and the indent is `[ \t]*` rather
+  // than `\s*`, because `$` and `\s` do not mean the same thing in Python and
+  // JavaScript on CRLF text: Python's `.+$` swallowed the carriage return and
+  // rewrote the line ending to LF. Anchoring on a negated class removes the
+  // difference and stops the redactor corrupting a document it only meant to mask.
+  {
+    name: 'auth-header',
+    pattern: /^([ \t]*(?:authorization|proxy-authorization)[ \t]*[:=][ \t]*)[^\r\n]+/gim,
+    replacement: '$1[REDACTED:auth-header]',
+  },
+  {
+    name: 'cookie-header',
+    pattern: /^([ \t]*(?:set-cookie|cookie)[ \t]*[:=][ \t]*)[^\r\n]+/gim,
+    replacement: '$1[REDACTED:cookie-header]',
+  },
+  // Secret-like assignments: key=value / "key": "value".
+  {
+    name: 'assigned-secret',
+    pattern: /(\b(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)\b\s*[:=]\s*["']?)([^\s"'&]{4,})/gi,
+    replacement: '$1[REDACTED:secret]',
+  },
+  // Credentials in URLs and query strings.
+  {
+    name: 'url-credential',
+    pattern: /(:\/\/[^:/@\s]+:)([^@/\s]+)(@)/gi,
+    replacement: '$1[REDACTED:credential]$3',
+  },
+  {
+    name: 'query-secret',
+    pattern: /([?&](?:password|passwd|pwd|token|secret|api[_-]?key|access[_-]?key)=)([^&\s#]+)/gi,
+    replacement: '$1[REDACTED:secret]',
+  },
+  // PII: email addresses.
+  { name: 'email', pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+];
+
+const SENSITIVE_HEADERS = new Set([
+  'authorization', 'proxy-authorization', 'cookie', 'set-cookie',
+  'x-api-key', 'x-auth-token', 'api-key', 'x-csrf-token',
+]);
+
+/** Return text with every recognized secret or PII value masked. */
+export function redactText(text) {
+  if (!text) return text;
+  let result = String(text);
+  for (const rule of RULES) {
+    // A fresh regex per call: `g` regexes carry lastIndex, and a module-level
+    // pattern reused across calls would skip matches unpredictably.
+    const pattern = new RegExp(rule.pattern.source, rule.pattern.flags);
+    result = result.replace(pattern, rule.replacement ?? `[REDACTED:${rule.name}]`);
+  }
+  return result;
+}
+
+/**
+ * Return `[{type, start, end}]` for secrets found — never the values.
+ *
+ * Used to decide whether an artifact is safe to expose without surfacing the
+ * secret itself.
+ */
+export function detectSecrets(text) {
+  const findings = [];
+  if (!text) return findings;
+  const source = String(text);
+  for (const rule of RULES) {
+    const pattern = new RegExp(rule.pattern.source, rule.pattern.flags);
+    for (const match of source.matchAll(pattern)) {
+      findings.push({ type: rule.name, start: match.index, end: match.index + match[0].length });
+    }
+  }
+  // Stable sort by position, so two secrets at the same offset keep rule order.
+  findings.sort((a, b) => a.start - b.start);
+  return findings;
+}
+
+/**
+ * Mask the values of sensitive HTTP headers.
+ *
+ * Accepts an object, or an array of `{name, value}` entries (the HAR shape), and
+ * returns the same shape with sensitive values replaced.
+ */
+export function redactHeaders(headers) {
+  const mask = (name, value) =>
+    SENSITIVE_HEADERS.has(String(name).trim().toLowerCase())
+      ? '[REDACTED:header]'
+      : redactText(value);
+
+  if (Array.isArray(headers)) {
+    return headers.map((entry) =>
+      entry && typeof entry === 'object' && 'name' in entry
+        ? { ...entry, value: mask(String(entry.name), String(entry.value ?? '')) }
+        : entry,
+    );
+  }
+  if (headers && typeof headers === 'object') {
+    return Object.fromEntries(
+      Object.entries(headers).map(([key, value]) => [key, mask(key, String(value))]),
+    );
+  }
+  return headers;
+}
+
+export const RULE_NAMES = RULES.map((rule) => rule.name);

package/packages/engine/lib/analysis/report-html.mjs

@@ -0,0 +1,76 @@
+// Render a contract artifact as a presentation-grade HTML report.
+//
+// ## What this module is now
+//
+// A stable entry point. The rendering itself moved to `lib/report/`, which is split
+// into theme, components, core, and export — because a single 700-line file could not
+// hold an enterprise report and stay reviewable, and because the Markdown, SARIF,
+// JUnit, and CSV renderings all need the same view model the HTML uses.
+//
+// This file stays because it is the *published* seam: `qa-tool.mjs analysis
+// report-html` is documented in nine installed skills and in every report-pipeline
+// reference. Moving code is cheap; moving a documented command out from under
+// installed copies is not.
+//
+// ## Why the report is rendered rather than typed
+//
+// The first real `/qa-explore` run on a live application produced a valid artifact and
+// a *lossy* report. Every finding in the contract carries `repro`, `actual`,
+// `expected`, and `fixDirection` — all four required — and the hand-written HTML
+// collapsed them into a single sentence:
+//
+//     EXP-1 · high — Double-click Login fires two GraphQL auth requests
+//     Two identical POSTs to /graphql. Disable Login while in flight.
+//
+// The reader is left to infer what was expected, how to reproduce it, and what
+// "correct" would look like. The data existed; the rendering discarded it.
+//
+// The second live run produced a beautiful report in which **every screenshot was
+// broken**, because the declared paths were relative to the project root and the
+// report was written inside the run folder. Both failures have the same cause: a human
+// or a model retyping what a renderer should own. So the renderer owns it, and
+// `lib/artifacts/manager.mjs` owns the difference between where a file is and how this
+// document links to it.
+//
+// No dependencies, one self-contained file out, no external assets — a report must
+// open from an email attachment on a plane.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  render as renderDocument, ReportError, supportedContracts, supportedModes,
+  versionStamp, versionLine,
+} from '../report/export/html.mjs';
+
+export { ReportError, supportedContracts, supportedModes, versionStamp, versionLine };
+
+/**
+ * Render a full standalone HTML document for a supported artifact.
+ *
+ * `resultPath` and `outPath` are how evidence links come out correct: the first says
+ * what declared paths are relative to, the second says what hrefs must be relative to.
+ * Both are optional and both should be supplied — without them every artifact resolves
+ * against the process working directory, which is right only by luck.
+ */
+export function render(result, options = {}) {
+  return renderDocument(result, options);
+}
+
+/** Read an artifact from disk and render it. */
+export function renderFile(file, options = {}) {
+  let result;
+  try {
+    result = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new ReportError(`could not read artifact at ${file}: ${error.message}`);
+  }
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) {
+    throw new ReportError(`artifact at ${file} is not a JSON object`);
+  }
+  return renderDocument(result, {
+    ...options,
+    resultPath: path.resolve(file),
+    outPath: options.outPath ?? null,
+  });
+}

package/packages/engine/lib/analysis/taxonomy.mjs

@@ -0,0 +1,109 @@
+// The canonical QA failure taxonomy and its deterministic classifier.
+//
+// Classification maps observed signals to one of a closed set of failure classes.
+// It is rule-based and conservative: when no rule matches with sufficient signal,
+// the result is UNKNOWN. Unknown is preferable to incorrect.
+//
+// Ported from qa_analysis/taxonomy.py with the rule order preserved exactly —
+// order *is* the logic here (see the note on the first two rules) — and held to
+// identical output by scripts/check-engine-parity.mjs.
+
+export const ASSERTION = 'assertion-failure';
+export const LOCATOR = 'locator-failure';
+export const TIMEOUT = 'timeout';
+export const NETWORK = 'network';
+export const AUTH = 'authentication';
+export const AUTHORIZATION = 'authorization';
+export const ENVIRONMENT = 'environment';
+export const CONFIGURATION = 'configuration';
+export const INFRASTRUCTURE = 'infrastructure';
+export const TEST_DATA = 'test-data';
+export const APPLICATION_BUG = 'application-bug';
+export const FRAMEWORK = 'framework-failure';
+export const FLAKY = 'flaky';
+export const UNKNOWN = 'unknown';
+
+export const CLASSES = new Set([
+  ASSERTION, LOCATOR, TIMEOUT, NETWORK, AUTH, AUTHORIZATION, ENVIRONMENT,
+  CONFIGURATION, INFRASTRUCTURE, TEST_DATA, APPLICATION_BUG, FRAMEWORK,
+  FLAKY, UNKNOWN,
+]);
+
+// Ordered rules: [classification, pattern, confidence, reason].
+//
+// Order encodes priority, and the first two rules exist because modern runners
+// print a timeout budget in *every* assertion failure. Playwright's message for a
+// plain text mismatch ends with "Timeout: 5000ms" even though nothing timed out,
+// so a naive timeout rule captures assertion and locator failures alike and sends
+// the reader to raise a timeout — the one action guaranteed not to help. The
+// patterns below are derived from real captured runner output.
+//
+// The discriminators, from that output:
+//   element missing  -> "Error: element(s) not found"   (no Received: value)
+//   value mismatch   -> "Expected: X" + "Received: Y"   (element was resolved)
+//   real timeout     -> a timeout with neither of the above
+const RULES = [
+  [LOCATOR, /(no such element|element(?:\(s\))?\s+not\s+(?:found|visible|attached)|locator.*(?:resolved to 0|not found)|waiting for (?:locator|selector)|unable to locate element)/i, 0.8,
+    'Error indicates the target element could not be found or resolved.'],
+  // A concrete expected-vs-received comparison is an assertion result, not a
+  // time budget: the runner resolved the target and compared values.
+  [ASSERTION, /expected:.*received:/is, 0.8,
+    'Error shows a concrete expected-versus-received comparison, so the assertion did not hold.'],
+  [TIMEOUT, /(timeout|timed out|exceeded .*ms|deadline exceeded)/i, 0.75,
+    'Error indicates an operation exceeded its time budget.'],
+  [AUTH, /(401 unauthorized|authentication failed|invalid (?:credentials|token)|login failed|not authenticated)/i, 0.85,
+    'Error indicates an authentication failure — the identity could not be established.'],
+  [AUTHORIZATION, /(403 forbidden|permission denied|access denied|not authorized|forbidden\b|insufficient (?:permission|privilege))/i, 0.85,
+    'Error indicates an authorization failure — the identity lacked permission.'],
+  [NETWORK, /(ECONNREFUSED| ENOTFOUND|net::ERR|connection (?:refused|reset)|5\d\d (?:internal server error|bad gateway|service unavailable)|fetch failed)/i, 0.8,
+    'Error indicates a network or upstream service failure.'],
+  [ASSERTION, /(assertion|expect(?:ed)?\b|toBe|toEqual|toHaveText|toBeVisible|AssertionError|expected .* (?:to|but))/i, 0.7,
+    'Error indicates an assertion did not hold.'],
+  [TEST_DATA, /(duplicate key|constraint violation|no rows|seed data|fixture .*(?:missing|not found)|invalid test data)/i, 0.7,
+    'Error indicates a test-data problem.'],
+  [CONFIGURATION, /(cannot find module|config(?:uration)? (?:error|not found)|missing (?:config|environment variable)|unknown option)/i, 0.7,
+    'Error indicates a configuration problem.'],
+  [ENVIRONMENT, /(base ?url|env(?:ironment)? .*(?:not set|missing)|ECONNREFUSED .*localhost|dev server)/i, 0.6,
+    'Error indicates an environment problem such as a missing base URL or unreachable local service.'],
+  [INFRASTRUCTURE, /(out of memory|OOM|disk (?:full|space)|browser .*(?:crash|closed unexpectedly)|worker .*(?:died|crashed))/i, 0.7,
+    'Error indicates an infrastructure problem such as a crash or resource exhaustion.'],
+  [FRAMEWORK, /(internal error|unexpected error in (?:playwright|selenium|cypress|webdriver)|driver .*mismatch)/i, 0.6,
+    'Error indicates a fault in the test framework or driver itself.'],
+];
+
+/**
+ * Classify a failure from its error message and optional HTTP status.
+ *
+ * Returns `{classification, confidence, reason}`. Never guesses: an unrecognized
+ * signal yields UNKNOWN at low confidence with an honest reason.
+ */
+export function classify(message, httpStatus = null) {
+  const text = message || '';
+
+  // A concrete HTTP status is stronger evidence than message text.
+  if (httpStatus !== null && httpStatus !== undefined) {
+    if (httpStatus === 401) {
+      return { classification: AUTH, confidence: 0.9, reason: 'HTTP 401 indicates an authentication failure.' };
+    }
+    if (httpStatus === 403) {
+      return { classification: AUTHORIZATION, confidence: 0.9, reason: 'HTTP 403 indicates an authorization failure.' };
+    }
+    if (httpStatus >= 500 && httpStatus <= 599) {
+      return {
+        classification: NETWORK,
+        confidence: 0.85,
+        reason: `HTTP ${httpStatus} indicates an upstream server failure.`,
+      };
+    }
+  }
+
+  for (const [classification, pattern, confidence, reason] of RULES) {
+    if (pattern.test(text)) return { classification, confidence, reason };
+  }
+
+  return {
+    classification: UNKNOWN,
+    confidence: 0.2,
+    reason: 'No classification rule matched the available signals; manual review needed.',
+  };
+}

package/packages/engine/lib/analysis/xml.mjs

@@ -0,0 +1,153 @@
+// A dependency-free XML reader for the subset the pack's artifacts use.
+//
+// Node has no built-in XML parser, and taking one as a dependency is ruled out:
+// this code is bundled into skills that run in other people's repositories, where
+// every dependency is attack surface and an install burden (ADR-0009). So the
+// subset we actually need is parsed here — element tags, attributes, text,
+// nesting, comments, CDATA, and the five predefined entities.
+//
+// Deliberately NOT supported, because no artifact the pack reads uses them:
+// namespaces (a prefixed tag is treated as an opaque name), DTD entity
+// definitions, and processing instructions beyond being skipped. Anything
+// unsupported raises — the parser never guesses its way past a document it does
+// not understand, because a fabricated parse becomes a fabricated test result.
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+export class XmlError extends Error {}
+
+function decode(text) {
+  if (!text.includes('&')) return text;
+  return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body) => {
+    if (body[0] === '#') {
+      const code = body[1] === 'x' || body[1] === 'X'
+        ? parseInt(body.slice(2), 16)
+        : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) && code >= 0 && code <= 0x10ffff
+        ? String.fromCodePoint(code)
+        : whole;
+    }
+    return Object.prototype.hasOwnProperty.call(ENTITIES, body) ? ENTITIES[body] : whole;
+  });
+}
+
+/**
+ * Parse an XML document into a node tree.
+ *
+ * A node is `{ tag, attrs, children, text }`. Text is the concatenation of the
+ * element's own character data, matching what `xml.etree` exposes closely enough
+ * for the artifacts the pack reads (which never mix text and children
+ * meaningfully).
+ *
+ * @param {string} source
+ * @returns {{tag: string, attrs: Record<string,string>, children: object[], text: string}}
+ */
+export function parseXml(source) {
+  if (typeof source !== 'string') throw new XmlError('XML source must be a string');
+
+  let cursor = 0;
+  const root = { tag: null, attrs: {}, children: [], text: '' };
+  const stack = [root];
+  const top = () => stack[stack.length - 1];
+
+  // Reported against the position of the offending markup, not the cursor: when a
+  // mismatched close tag is found, the cursor still sits at the end of the last
+  // *good* tag, so using it points a reader at the wrong line of a large report.
+  const fail = (why, at = cursor) => {
+    const line = source.slice(0, at).split('\n').length;
+    throw new XmlError(`${why} (line ${line})`);
+  };
+
+  while (cursor < source.length) {
+    const open = source.indexOf('<', cursor);
+    if (open === -1) {
+      top().text += decode(source.slice(cursor));
+      break;
+    }
+    if (open > cursor) top().text += decode(source.slice(cursor, open));
+
+    if (source.startsWith('<?', open)) {
+      const end = source.indexOf('?>', open);
+      if (end === -1) fail('unterminated processing instruction', open);
+      cursor = end + 2;
+      continue;
+    }
+    if (source.startsWith('<!--', open)) {
+      const end = source.indexOf('-->', open);
+      if (end === -1) fail('unterminated comment', open);
+      cursor = end + 3;
+      continue;
+    }
+    if (source.startsWith('<![CDATA[', open)) {
+      const end = source.indexOf(']]>', open);
+      if (end === -1) fail('unterminated CDATA section', open);
+      // CDATA is literal: no entity decoding.
+      top().text += source.slice(open + 9, end);
+      cursor = end + 3;
+      continue;
+    }
+    if (source.startsWith('<!', open)) {
+      const end = source.indexOf('>', open);
+      if (end === -1) fail('unterminated declaration', open);
+      cursor = end + 1;
+      continue;
+    }
+
+    const close = source.indexOf('>', open);
+    if (close === -1) fail('unterminated tag', open);
+    const raw = source.slice(open + 1, close);
+    if (raw.length === 0) fail('empty tag', open);
+
+    if (raw[0] === '/') {
+      const name = raw.slice(1).trim();
+      if (stack.length === 1) fail(`closing tag </${name}> with no open element`, open);
+      const node = stack.pop();
+      if (node.tag !== name) fail(`expected </${node.tag}> but found </${name}>`, open);
+      cursor = close + 1;
+      continue;
+    }
+
+    const selfClosing = raw.endsWith('/');
+    const body = selfClosing ? raw.slice(0, -1) : raw;
+    const firstSpace = body.search(/\s/);
+    const tag = (firstSpace === -1 ? body : body.slice(0, firstSpace)).trim();
+    if (!tag) fail('empty tag name', open);
+
+    const attrs = {};
+    if (firstSpace !== -1) {
+      const attrSource = body.slice(firstSpace);
+      // Quoted values only. An unquoted attribute value is not valid XML, and
+      // accepting one would mean guessing where it ends.
+      const pattern = /([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+      let match;
+      let consumed = 0;
+      while ((match = pattern.exec(attrSource)) !== null) {
+        attrs[match[1]] = decode(match[3] ?? match[4] ?? '');
+        consumed = match.index + match[0].length;
+      }
+      if (attrSource.slice(consumed).trim().length > 0) {
+        fail(`unparsable attributes in <${tag}>: ${attrSource.slice(consumed).trim()}`, open);
+      }
+    }
+
+    const node = { tag, attrs, children: [], text: '' };
+    top().children.push(node);
+    if (!selfClosing) stack.push(node);
+    cursor = close + 1;
+  }
+
+  if (stack.length !== 1) fail(`unclosed element <${top().tag}>`);
+  if (root.children.length === 0) throw new XmlError('document has no root element');
+  if (root.children.length > 1) throw new XmlError('document must have exactly one root element');
+  return root.children[0];
+}
+
+/** First child element with this tag, or null — `Element.find` in xml.etree. */
+export function find(node, tag) {
+  return node.children.find((child) => child.tag === tag) ?? null;
+}
+
+/** Every child element with this tag — `Element.findall` in xml.etree. */
+export function findAll(node, tag) {
+  return node.children.filter((child) => child.tag === tag);
+}

package/packages/engine/lib/analysis/zip.mjs

@@ -0,0 +1,107 @@
+// A dependency-free ZIP reader for the entries the pack needs to read.
+//
+// Node has no archive API, and a dependency is ruled out for code that runs in
+// other people's repositories (ADR-0009). Playwright writes its trace as a zip of
+// newline-delimited JSON, so the central directory is walked here and each entry
+// inflated with the built-in `zlib`.
+//
+// Supported: stored (method 0) and deflated (method 8) entries — the only two a
+// zip writer produces in practice, and the only two Playwright emits. Anything
+// else raises by name rather than returning empty bytes, because a silently empty
+// trace reads as "nothing happened" instead of "could not be read".
+
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const MAX_COMMENT = 0xffff;
+
+export class ZipError extends Error {}
+
+/**
+ * Every entry in the archive: `[{name, method, compressedSize, size, offset}]`.
+ *
+ * Read from the central directory, which is authoritative — the per-entry local
+ * headers may carry zeroed sizes when the writer streamed the file.
+ */
+export function listEntries(buffer) {
+  const eocd = findEndOfCentralDirectory(buffer);
+  const count = buffer.readUInt16LE(eocd + 10);
+  let cursor = buffer.readUInt32LE(eocd + 16);
+  const entries = [];
+
+  for (let index = 0; index < count; index += 1) {
+    if (cursor + 46 > buffer.length || buffer.readUInt32LE(cursor) !== CENTRAL_SIGNATURE) {
+      throw new ZipError(`central directory entry ${index} is malformed`);
+    }
+    const method = buffer.readUInt16LE(cursor + 10);
+    const compressedSize = buffer.readUInt32LE(cursor + 20);
+    const size = buffer.readUInt32LE(cursor + 24);
+    const nameLength = buffer.readUInt16LE(cursor + 28);
+    const extraLength = buffer.readUInt16LE(cursor + 30);
+    const commentLength = buffer.readUInt16LE(cursor + 32);
+    const offset = buffer.readUInt32LE(cursor + 42);
+    const name = buffer.subarray(cursor + 46, cursor + 46 + nameLength).toString('utf8');
+    entries.push({ name, method, compressedSize, size, offset });
+    cursor += 46 + nameLength + extraLength + commentLength;
+  }
+  return entries;
+}
+
+/** The bytes of one entry, inflated if it was deflated. */
+export function readEntry(buffer, entry) {
+  if (entry.offset + 30 > buffer.length) {
+    throw new ZipError(`entry ${entry.name} points past the end of the archive`);
+  }
+  const nameLength = buffer.readUInt16LE(entry.offset + 26);
+  const extraLength = buffer.readUInt16LE(entry.offset + 28);
+  const start = entry.offset + 30 + nameLength + extraLength;
+  const raw = buffer.subarray(start, start + entry.compressedSize);
+
+  if (entry.method === 0) return raw;
+  if (entry.method === 8) {
+    try {
+      return zlib.inflateRawSync(raw);
+    } catch (error) {
+      throw new ZipError(`entry ${entry.name} could not be inflated: ${error.message}`);
+    }
+  }
+  throw new ZipError(`entry ${entry.name} uses unsupported compression method ${entry.method}`);
+}
+
+/** Is this a readable ZIP archive? Locates the end-of-central-directory record. */
+export function isZip(buffer) {
+  try {
+    findEndOfCentralDirectory(buffer);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Open a zip file and hand back `{entries, read}`. */
+export function openZip(path) {
+  let buffer;
+  try {
+    buffer = fs.readFileSync(path);
+  } catch (error) {
+    throw new ZipError(`could not read ${path}: ${error.message}`);
+  }
+  const entries = listEntries(buffer);
+  return { entries, read: (entry) => readEntry(buffer, entry) };
+}
+
+/**
+ * The record is last in the file, possibly followed by a comment, so the tail is
+ * scanned backwards. Trusting the first four bytes instead would accept a
+ * truncated archive whose header still reads `PK\x03\x04`.
+ */
+function findEndOfCentralDirectory(buffer) {
+  if (buffer.length < 22) throw new ZipError('too short to be a zip archive');
+  const earliest = Math.max(0, buffer.length - 22 - MAX_COMMENT);
+  for (let cursor = buffer.length - 22; cursor >= earliest; cursor -= 1) {
+    if (buffer.readUInt32LE(cursor) === EOCD_SIGNATURE) return cursor;
+  }
+  throw new ZipError('no end-of-central-directory record: not a zip archive');
+}