qa-engineer 0.9.2 → 0.11.0

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

@@ -0,0 +1,187 @@
+// Product attribution for human-readable reports.
+//
+// One renderer, one metadata file, three output formats. Every report the pack
+// produces for a human ends with the same footer, and changing it means editing
+// `branding.json` — nothing else.
+//
+// ## Why this is code and not a string in each skill
+//
+// A footer typed by a model is a footer that drifts: the tagline gains a word, the
+// URL loses a scheme, one report says "Developed by" and the next says "Built by".
+// Rendering it deterministically makes every report byte-identical, and makes a
+// change to the branding a one-file edit that CI can verify
+// (scripts/check-branding.mjs fails if any branding string is hardcoded elsewhere).
+//
+// ## What gets a footer, and what must not
+//
+// Attribution belongs on documents a person reads. It is noise — or worse, a
+// parsing hazard — anywhere else.
+//
+//   Branded                          | Not branded
+//   ---------------------------------|--------------------------------------------
+//   HTML and PDF reports             | JSON and YAML artifacts under qa-artifacts/
+//   Markdown meant for people        | Markdown written for a machine to read
+//   Generated documentation          | CLI stdout, progress output, --json output
+//   Audit and evaluation renderings  | The system under test, the user's own source
+//
+// The rule behind the table: **if a program will parse it, it gets no footer.** A
+// contract artifact is an interface, and appending prose to an interface breaks it.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+// One metadata file, beside this module — so it travels with the engine into a
+// bundled skill without a second copy to keep in step.
+const METADATA_CANDIDATES = [path.join(here, 'branding.json')];
+
+// The visual width of the plain-text rules. Wide enough to frame the four lines,
+// narrow enough to survive an 80-column terminal or a PDF margin.
+const RULE_WIDTH = 60;
+
+const ALLOWED_SCHEMES = ['https://', 'http://'];
+
+export class BrandingError extends Error {}
+
+/** The branding metadata. Read fresh, so a change needs no reinstall. */
+export function metadata() {
+  const source = METADATA_CANDIDATES.find((candidate) => fs.existsSync(candidate));
+  if (!source) {
+    throw new BrandingError(
+      `could not find branding metadata (looked in: ${METADATA_CANDIDATES.join(', ')})`,
+    );
+  }
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(source, 'utf8'));
+  } catch (error) {
+    throw new BrandingError(`could not read branding metadata at ${source}: ${error.message}`);
+  }
+
+  const required = ['projectName', 'tagline', 'author', 'website', 'attributionPrefix', 'authorPrefix'];
+  const missing = required.filter((key) => !data[key]);
+  if (missing.length > 0) {
+    throw new BrandingError(`branding metadata is missing: ${missing.join(', ')}`);
+  }
+  if (!ALLOWED_SCHEMES.some((scheme) => data.website.startsWith(scheme))) {
+    // A footer is rendered into HTML, so a non-http scheme here would be an
+    // injection vector rather than a typo.
+    throw new BrandingError(
+      `branding website must start with http:// or https://, got '${data.website}'`,
+    );
+  }
+  return data;
+}
+
+/** HTML-escape, matching Python's `html.escape(s, quote=True)` character for character. */
+function escape(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;');
+}
+
+/** The four footer lines, in order, as plain strings. */
+function lines(data) {
+  return [
+    `${data.attributionPrefix} ${data.projectName}`,
+    data.tagline,
+    `${data.authorPrefix} ${data.author}`,
+    data.website,
+  ];
+}
+
+/**
+ * Rule-separated plain text, for PDF and any non-markup rendering.
+ *
+ * Centering follows Python's `str.center`: the odd space goes on the right, which
+ * then falls off with the trailing trim. Getting that backwards shifts every line
+ * by a character and breaks the snapshot the branding tests pin.
+ */
+export function footerText({ width = RULE_WIDTH } = {}) {
+  const data = metadata();
+  const rule = '-'.repeat(width);
+  const body = lines(data)
+    .map((line) => {
+      if (line.length >= width) return line;
+      return ' '.repeat(Math.floor((width - line.length) / 2)) + line;
+    })
+    .join('\n');
+  return `${rule}\n${body}\n${rule}\n`;
+}
+
+/** A thematic break and the four lines, with the site as a link. */
+export function footerMarkdown() {
+  const data = metadata();
+  return (
+    '---\n\n' +
+    `<sub>${data.attributionPrefix} **${data.projectName}** — ` +
+    `${data.tagline}<br>\n` +
+    `${data.authorPrefix} ` +
+    `[${data.author}](${data.website})</sub>\n`
+  );
+}
+
+/**
+ * A self-contained `<footer>`: inline styles, muted, centered, small.
+ *
+ * The author's site opens in a new tab. `rel="noopener noreferrer"` is not
+ * optional — a report may be opened from anywhere, and a new tab that can reach
+ * back into `window.opener` is a real hazard.
+ */
+export function footerHtml({ className = 'qa-pack-attribution' } = {}) {
+  const data = metadata();
+  return (
+    `<footer class="${escape(className)}" style="margin-top:2.5rem;padding-top:1rem;` +
+    'border-top:1px solid rgba(128,128,128,0.25);font-size:0.75rem;line-height:1.6;' +
+    'color:#6b7280;text-align:center;font-family:system-ui,-apple-system,' +
+    'Segoe UI,Roboto,sans-serif;">\n' +
+    `  <div>${escape(data.attributionPrefix)} <strong>${escape(data.projectName)}</strong></div>\n` +
+    `  <div>${escape(data.tagline)}</div>\n` +
+    `  <div>${escape(data.authorPrefix)} ` +
+    `<a href="${escape(data.website)}" target="_blank" rel="noopener noreferrer" ` +
+    'style="color:inherit;text-decoration:underline;">' +
+    `${escape(data.author)}</a></div>\n` +
+    '</footer>\n'
+  );
+}
+
+const RENDERERS = {
+  html: footerHtml,
+  markdown: footerMarkdown,
+  md: footerMarkdown,
+  text: footerText,
+  txt: footerText,
+  pdf: footerText, // what a PDF writer embeds when it cannot render markup
+};
+
+export const FORMATS = ['html', 'markdown', 'text'];
+
+/** Render the footer in `format`. Throws BrandingError on an unknown format. */
+export function footer(format = 'text') {
+  const renderer = RENDERERS[String(format).toLowerCase()];
+  if (!renderer) {
+    throw new BrandingError(
+      `unknown branding format '${format}'; expected one of: ${FORMATS.join(', ')}`,
+    );
+  }
+  return renderer();
+}
+
+/**
+ * Return `document` with the footer appended, idempotently.
+ *
+ * Idempotence matters: a report assembled in stages, or regenerated over its own
+ * output, must not accumulate footers.
+ */
+export function appendTo(document, format = 'markdown') {
+  const rendered = footer(format);
+  if (rendered.trim() && document.includes(rendered.trim())) return document;
+  const separator = document.endsWith('\n') ? '' : '\n';
+  return `${document}${separator}\n${rendered}`;
+}

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

@@ -0,0 +1,294 @@
+// Deterministic parsing of `.qa/context.md`.
+//
+// `qa-init` writes the project profile as a Markdown file whose frontmatter holds
+// the machine-readable facts, and every other skill reads it. The contract for
+// those facts is a JSON Schema (shared/analysis/schemas/context.schema.json) — but
+// nothing could check a *real* `.qa/context.md` against it, because the engine
+// takes no dependencies and the frontmatter is YAML. Validation ran against a
+// hand-written JSON fixture instead, so the contract was unenforced exactly where
+// it mattered.
+//
+// This closes that gap without adding a dependency or changing the file format: it
+// parses the **explicit subset** of YAML the context contract uses, then hands the
+// result to the contract validator.
+//
+// ## The supported subset
+//
+// Deliberately small, and everything outside it is an error rather than a guess:
+//
+//   - `key: value` mappings, nested by two-space indentation
+//   - block sequences (`- item`), including nested under a key
+//   - flow collections only when empty: `[]` and `{}`
+//   - scalars: double- or single-quoted strings, bare strings, integers, floats,
+//     `true`/`false`, `null`/`~`/empty
+//   - `#` comments on their own line or after a value
+//   - the leading/trailing `---` fences
+//
+// Not supported, and rejected loudly: anchors/aliases, multi-line block scalars
+// (`|`, `>`), non-empty flow collections, multi-document streams, and tabs for
+// indentation. A generator that needs one of those has outgrown the contract, and
+// the right response is to change the contract deliberately — not to have a parser
+// quietly misread it.
+
+import fs from 'node:fs';
+
+import { validate } from './contracts.mjs';
+
+const FENCE = '---';
+const TRUE = new Set(['true', 'True', 'TRUE']);
+const FALSE = new Set(['false', 'False', 'FALSE']);
+const NULL = new Set(['null', 'Null', 'NULL', '~', '']);
+const UNSUPPORTED_SCALARS = new Set(['|', '>']);
+const INT = /^-?\d+$/;
+const FLOAT = /^-?\d+\.\d+$/;
+
+export class MalformedContext extends Error {}
+
+/** Return `{frontmatter, body}`. Throws if the fences are missing. */
+export function splitFrontmatter(text) {
+  const lines = String(text).split('\n');
+  let start = null;
+  for (const [index, line] of lines.entries()) {
+    if (line.trim() === '') continue;
+    if (trimEnd(line) === FENCE) start = index;
+    break;
+  }
+  if (start === null) {
+    throw new MalformedContext(
+      "no frontmatter: the file must open with a '---' fence " +
+        '(see the qa-init context template)',
+    );
+  }
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (trimEnd(lines[index]) === FENCE) {
+      return {
+        frontmatter: lines.slice(start + 1, index).join('\n'),
+        body: lines.slice(index + 1).join('\n'),
+      };
+    }
+  }
+  throw new MalformedContext("unterminated frontmatter: no closing '---' fence");
+}
+
+/** Remove a trailing `#` comment that is not inside quotes. */
+function stripComment(value) {
+  let quote = null;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === '#' && (index === 0 || value[index - 1] === ' ' || value[index - 1] === '\t')) {
+      return value.slice(0, index);
+    }
+  }
+  return value;
+}
+
+function scalar(raw, lineNumber) {
+  const text = stripComment(raw).trim();
+  const first = text.slice(0, 1);
+  if (UNSUPPORTED_SCALARS.has(first)) {
+    throw new MalformedContext(
+      `line ${lineNumber}: block scalars ('|', '>') are outside the supported subset`,
+    );
+  }
+  if (first === '&' || first === '*') {
+    throw new MalformedContext(
+      `line ${lineNumber}: anchors and aliases are outside the supported subset`,
+    );
+  }
+  if (text.length >= 2 && text[0] === text[text.length - 1] && (text[0] === "'" || text[0] === '"')) {
+    return text.slice(1, -1);
+  }
+  if (text === '[]') return [];
+  if (text === '{}') return {};
+  if (text.startsWith('[') || text.startsWith('{')) {
+    throw new MalformedContext(
+      `line ${lineNumber}: only empty flow collections ('[]', '{}') are supported; ` +
+        'use a block sequence or mapping',
+    );
+  }
+  if (TRUE.has(text)) return true;
+  if (FALSE.has(text)) return false;
+  if (NULL.has(text)) return null;
+  if (INT.test(text)) return Number.parseInt(text, 10);
+  if (FLOAT.test(text)) return Number.parseFloat(text);
+  return text;
+}
+
+/**
+ * A line must sit at exactly the indent of the container it lands in.
+ *
+ * Without this, a document YAML itself rejects was silently misread. Given
+ *
+ *     list:
+ *       - one
+ *       key: inside a sequence
+ *
+ * PyYAML reports "expected <block end>, but found '?'" — a mapping key cannot
+ * share indentation with a sequence entry in the same block. The parser closed the
+ * sequence and put `key` in the *root* mapping, two levels out from where it was
+ * written, turning an invalid file into a plausible one.
+ */
+function requireIndentMatches(stack, indent, lineNumber) {
+  if (stack[stack.length - 1][0] !== indent) {
+    throw new MalformedContext(
+      `line ${lineNumber}: indentation ${indent} matches no open block ` +
+        `(the enclosing block starts at column ${stack[stack.length - 1][0]})`,
+    );
+  }
+}
+
+/**
+ * Parse the supported YAML subset into an object.
+ *
+ * The parser keeps a stack of `[keyIndent, container]` frames. `keyIndent` is the
+ * column at which that container's own entries start, so a line's indent alone
+ * decides which container it belongs to: pop every frame deeper than the line, and
+ * the top of the stack is the target.
+ */
+export function parseFrontmatter(text) {
+  const root = {};
+  const stack = [[0, root]];
+  let pending = null; // [key, indent] — a key whose value is a block that follows
+
+  const resolvePendingAsNull = () => {
+    // A key with no value and no nested block is a null field.
+    if (pending !== null) {
+      stack[stack.length - 1][1][pending[0]] = null;
+      pending = null;
+    }
+  };
+
+  const lines = String(text).split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    const rawLine = lines[index];
+    const number = index + 1;
+    const leading = rawLine.slice(0, rawLine.length - trimStart(rawLine).length);
+    if (leading.includes('\t')) {
+      throw new MalformedContext(`line ${number}: tab indentation is not supported`);
+    }
+    const stripped = rawLine.trim();
+    if (!stripped || stripped.startsWith('#')) continue;
+    if (stripped === FENCE) {
+      throw new MalformedContext(`line ${number}: unexpected '---' inside frontmatter`);
+    }
+
+    const indent = rawLine.length - trimStartSpaces(rawLine).length;
+
+    // --- sequence item ---
+    if (stripped.startsWith('- ') || stripped === '-') {
+      const item = scalar(stripped.length > 1 ? stripped.slice(2) : '', number);
+      if (pending !== null) {
+        // A sequence may sit at the key's indent or deeper.
+        const parent = stack[stack.length - 1][1];
+        parent[pending[0]] = [];
+        stack.push([indent, parent[pending[0]]]);
+        pending = null;
+      }
+      while (stack.length > 1 && stack[stack.length - 1][0] > indent) stack.pop();
+      const container = stack[stack.length - 1][1];
+      if (!Array.isArray(container)) {
+        throw new MalformedContext(`line ${number}: sequence item outside a sequence`);
+      }
+      requireIndentMatches(stack, indent, number);
+      container.push(item);
+      continue;
+    }
+
+    // --- mapping entry ---
+    if (!stripped.includes(':')) {
+      throw new MalformedContext(
+        `line ${number}: expected 'key: value' or '- item', got '${stripped}'`,
+      );
+    }
+
+    if (pending !== null) {
+      if (indent > pending[1]) {
+        // The pending key opens a nested mapping at this indent.
+        const parent = stack[stack.length - 1][1];
+        parent[pending[0]] = {};
+        stack.push([indent, parent[pending[0]]]);
+        pending = null;
+      } else {
+        resolvePendingAsNull();
+      }
+    }
+
+    // Leave the frames this line does not belong to. A sequence frame at the same
+    // indent as a key also ends here (`packages:` / `- a` / `ci:`).
+    while (
+      stack.length > 1 &&
+      (stack[stack.length - 1][0] > indent ||
+        (Array.isArray(stack[stack.length - 1][1]) && stack[stack.length - 1][0] >= indent))
+    ) {
+      stack.pop();
+    }
+
+    const separator = stripped.indexOf(':');
+    const key = stripped.slice(0, separator).trim();
+    const value = stripped.slice(separator + 1);
+    if (!key) throw new MalformedContext(`line ${number}: empty key`);
+    const container = stack[stack.length - 1][1];
+    if (Array.isArray(container)) {
+      throw new MalformedContext(`line ${number}: mapping key inside a sequence`);
+    }
+    requireIndentMatches(stack, indent, number);
+
+    if (stripComment(value).trim() === '') {
+      pending = [key, indent]; // a block or a null follows
+    } else {
+      container[key] = scalar(value, number);
+    }
+  }
+
+  resolvePendingAsNull();
+  return root;
+}
+
+/**
+ * Parse `.qa/context.md` text and, when a schema is given, validate it.
+ *
+ * A parse failure throws: it is not a validation result. "This file is not
+ * parseable" and "this file is parseable but wrong" are different answers, and
+ * collapsing them would report a broken file as a merely invalid one.
+ */
+export function parse(text, { schema = null } = {}) {
+  const { frontmatter, body } = splitFrontmatter(text);
+  const context = parseFrontmatter(frontmatter);
+  const result = { context, body, valid: true, errors: [] };
+  if (schema !== null) {
+    const errors = validate(context, schema);
+    result.valid = errors.length === 0;
+    result.errors = errors;
+  }
+  return result;
+}
+
+/** Read and parse a `.qa/context.md` file. */
+export function parseFile(path, { schema = null } = {}) {
+  let text;
+  try {
+    text = fs.readFileSync(path, 'utf8');
+  } catch (error) {
+    throw new MalformedContext(`could not read ${path}: ${error.message}`);
+  }
+  return parse(text, { schema });
+}
+
+// Python's str.rstrip()/lstrip() strip all whitespace; JavaScript's trimEnd and
+// trimStart do the same, but the indent calculation needs spaces only — a line
+// indented with a form feed is not indented two columns.
+function trimEnd(value) {
+  return value.replace(/\s+$/, '');
+}
+
+function trimStart(value) {
+  return value.replace(/^\s+/, '');
+}
+
+function trimStartSpaces(value) {
+  return value.replace(/^ +/, '');
+}

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

@@ -0,0 +1,149 @@
+// A dependency-free validator for the JSON Schema subset this project uses.
+//
+// This began as the JavaScript *twin* of a Python validator, kept in step by a
+// shared corpus. The move to a Node-only engine (ADR-0012) made it the single
+// implementation: the installer's config and lockfile checks and the analysis
+// engine's contract checks now go through this one function, rather than two
+// copies that agreed by test.
+//
+// The corpus outlived the twin. packages/engine/test/corpus/validator-cases.json
+// still runs every case here, because it encodes which subset of JSON Schema the
+// pack's contracts may use — and that is worth pinning whether or not a second
+// validator exists to compare against.
+//
+// Anything outside the subset is a programming error in the schema, reported
+// rather than silently ignored. `allOf`/`if`/`then`/`else` are in the subset
+// because the pack's safety invariants are cross-field implications.
+
+// Keep in sync with SUPPORTED_KEYWORDS in
+// shared/analysis/lib/qa_analysis/contracts.py and the table in
+// docs/skills/output-contracts.md (checked by scripts/check-spec-code-sync.mjs).
+const SUPPORTED = new Set([
+  '$schema', '$id', 'title', 'description', 'type', 'properties', 'required',
+  'additionalProperties', 'items', 'enum', 'const', 'pattern', 'minimum',
+  'maximum', 'minItems', 'maxItems', 'minLength', 'maxLength', 'default',
+  'examples', 'format', 'allOf', 'if', 'then', 'else',
+]);
+
+// RFC 3339 date-time — the same rule as the Python twin.
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+
+function typeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value; // string | number | boolean | object
+}
+
+function matchesType(value, type) {
+  if (type === 'integer') return Number.isInteger(value) && typeof value !== 'boolean';
+  if (type === 'number') return typeof value === 'number';
+  if (type === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (type === 'array') return Array.isArray(value);
+  return typeOf(value) === type;
+}
+
+/** True when value satisfies schema; used for if/then branch selection. */
+function satisfies(value, schema) {
+  const probe = [];
+  validateNode(value, schema, '', probe);
+  return probe.length === 0;
+}
+
+function validateNode(value, schema, pointer, errors) {
+  for (const key of Object.keys(schema)) {
+    if (!SUPPORTED.has(key)) {
+      errors.push(`${pointer || '/'}: schema uses unsupported keyword "${key}"`);
+    }
+  }
+
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((t) => matchesType(value, t))) {
+      errors.push(`${pointer || '/'}: expected ${types.join(' | ')}, got ${typeOf(value)}`);
+      return; // further checks assume the type held
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(schema, 'const') && JSON.stringify(value) !== JSON.stringify(schema.const)) {
+    errors.push(`${pointer || '/'}: must equal ${JSON.stringify(schema.const)}`);
+  }
+
+  if (schema.enum && !schema.enum.some((option) => JSON.stringify(option) === JSON.stringify(value))) {
+    errors.push(`${pointer || '/'}: ${JSON.stringify(value)} is not one of ${JSON.stringify(schema.enum)}`);
+  }
+
+  if (typeof value === 'string') {
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      errors.push(`${pointer || '/'}: "${value}" does not match /${schema.pattern}/`);
+    }
+    if (schema.format === 'date-time' && !DATE_TIME.test(value)) {
+      errors.push(`${pointer || '/'}: "${value}" is not a valid date-time`);
+    }
+    if (schema.minLength != null && value.length < schema.minLength) {
+      errors.push(`${pointer || '/'}: shorter than minLength ${schema.minLength}`);
+    }
+    if (schema.maxLength != null && value.length > schema.maxLength) {
+      errors.push(`${pointer || '/'}: longer than maxLength ${schema.maxLength}`);
+    }
+  }
+
+  if (typeof value === 'number') {
+    if (schema.minimum != null && value < schema.minimum) {
+      errors.push(`${pointer || '/'}: ${value} is below minimum ${schema.minimum}`);
+    }
+    if (schema.maximum != null && value > schema.maximum) {
+      errors.push(`${pointer || '/'}: ${value} is above maximum ${schema.maximum}`);
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems != null && value.length < schema.minItems) {
+      errors.push(`${pointer || '/'}: has ${value.length} items, needs at least ${schema.minItems}`);
+    }
+    if (schema.maxItems != null && value.length > schema.maxItems) {
+      errors.push(`${pointer || '/'}: has ${value.length} items, allows at most ${schema.maxItems}`);
+    }
+    if (schema.items) {
+      value.forEach((item, index) => validateNode(item, schema.items, `${pointer}/${index}`, errors));
+    }
+  }
+
+  if (matchesType(value, 'object') && (schema.properties || schema.required || schema.additionalProperties === false)) {
+    const properties = schema.properties ?? {};
+    for (const name of schema.required ?? []) {
+      if (!Object.prototype.hasOwnProperty.call(value, name)) {
+        errors.push(`${pointer || '/'}: missing required property "${name}"`);
+      }
+    }
+    for (const [name, child] of Object.entries(value)) {
+      if (properties[name]) {
+        validateNode(child, properties[name], `${pointer}/${name}`, errors);
+      } else if (schema.additionalProperties === false) {
+        errors.push(`${pointer || '/'}: unexpected property "${name}"`);
+      }
+    }
+  }
+
+  // Applicators last: the invariant layer. `additionalProperties` deliberately
+  // does not see properties introduced by these subschemas (JSON Schema
+  // 2020-12 rule, matching the Python twin).
+  for (const sub of schema.allOf ?? []) {
+    validateNode(value, sub, pointer, errors);
+  }
+
+  if (Object.prototype.hasOwnProperty.call(schema, 'if')) {
+    const branch = satisfies(value, schema.if) ? schema.then : schema.else;
+    if (branch != null) validateNode(value, branch, pointer, errors);
+  }
+}
+
+/** Validate `value` against `schema`; returns an array of error strings (empty = valid). */
+export function validate(value, schema) {
+  const errors = [];
+  validateNode(value, schema, '', errors);
+  return errors;
+}
+
+/** The supported keyword subset, exported so tooling can assert parity. */
+export const SUPPORTED_KEYWORDS = Object.freeze([...SUPPORTED].sort());