@milpa/comal 0.2.6 → 0.2.8

package/src/plugin-contract.mjs

@@ -0,0 +1,309 @@
+import Ajv from 'ajv';
+import Ajv2020 from 'ajv/dist/2020.js';
+import Ajv2019 from 'ajv/dist/2019.js';
+import { digest, immutable } from './operations.mjs';
+
+// A plugin's contract: what the house can state about it without reading its code (its surface)
+// and the promises it makes in use cases (its cases). Cases are data the house evaluates on an
+// operation's real result; they are never code, and a plugin never grades itself. Pure module.
+//
+// A repair keeps the contract when the surface is identical and every existing case is still
+// present, unchanged; adding cases is allowed (compareContracts → kept).
+
+const MAX_CASES = 200, CASE_BYTES = 64 * 1024, NAME_MAX = 120, CODE_MAX = 128, JSON_DEPTH = 64;
+const OPERATION_NAME = /^[A-Za-z][A-Za-z0-9_]{0,31}$/;
+const EXPECT_FORMS = ['returns', 'output_schema', 'throws'];
+const validatorOptions = { strict: false, allErrors: true, validateFormats: false };
+const compiled = new WeakMap();
+
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const shown = value => { let text; try { text = JSON.stringify(value); } catch { text = String(value); } text ??= String(value); return text.length > 120 ? `${text.slice(0, 120)}…` : text; };
+
+function invalidCase(label, reason) {
+  return Object.assign(new Error(`Invalid plugin case ${label}: ${reason}`), { code: 'PLUGIN_CASES_INVALID', case: label });
+}
+
+// Throws (a plain message) unless value is JSON: null, strings, booleans, finite numbers, arrays
+// and plain objects, at most JSON_DEPTH levels deep (a cycle runs into the depth limit).
+function requireJson(value, what, depth = 0) {
+  if (depth > JSON_DEPTH) throw new Error(`${what} nests deeper than ${JSON_DEPTH} levels or is cyclic.`);
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number') { if (!Number.isFinite(value)) throw new Error(`${what} holds a number that is not finite.`); return; }
+  if (Array.isArray(value)) { for (const item of value) requireJson(item, what, depth + 1); return; }
+  if (plain(value)) { for (const key of Object.keys(value)) requireJson(value[key], what, depth + 1); return; }
+  throw new Error(`${what} is not JSON.`);
+}
+
+// An expectation that every output meets promises nothing.
+const vacuous = expect => (Object.hasOwn(expect, 'returns') && plain(expect.returns) && !Object.keys(expect.returns).length) || (Object.hasOwn(expect, 'output_schema') && (expect.output_schema === true || (plain(expect.output_schema) && !Object.keys(expect.output_schema).length)));
+// An $async schema validates through a promise: never a synchronous verdict.
+function hasAsync(value, depth = 0) {
+  if (depth > JSON_DEPTH || value === null || typeof value !== 'object') return false;
+  if (!Array.isArray(value) && Object.hasOwn(value, '$async')) return true;
+  return Object.values(value).some(item => hasAsync(item, depth + 1));
+}
+
+function schemaValidator(schema) {
+  let validate = compiled.get(schema);
+  if (!validate) {
+    const Validator = typeof schema.$schema === 'string' && schema.$schema.includes('2020-12') ? Ajv2020 : typeof schema.$schema === 'string' && schema.$schema.includes('2019-09') ? Ajv2019 : Ajv;
+    validate = new Validator(validatorOptions).compile(structuredClone(schema));
+    compiled.set(schema, validate);
+  }
+  return validate;
+}
+
+/**
+ * Validate a plugin's `cases`. Each case is { name, operation, input, expect }: name 1–120 chars,
+ * unique; operation one of `operationNames` (the short names passed to ctx.operation; when
+ * operationNames is omitted only the shape is checked); input a JSON object; expect exactly one
+ * of { returns: <JSON> }, { output_schema: <JSON Schema object> }, { throws: { code } }. At most
+ * 200 cases, each at most 64 KB as JSON. Returns a frozen copy; throws PLUGIN_CASES_INVALID
+ * naming the case. `undefined` is no cases.
+ */
+export function validateCases(cases, operationNames) {
+  if (cases === undefined) return immutable([]);
+  if (!Array.isArray(cases)) throw invalidCase('list', 'cases must be an array.');
+  if (cases.length > MAX_CASES) throw invalidCase('list', `a plugin declares at most ${MAX_CASES} cases (${cases.length} given).`);
+  const known = operationNames === undefined || operationNames === null ? null : new Set(operationNames);
+  const names = new Set(), out = [];
+  cases.forEach((item, index) => {
+    const label = plain(item) && typeof item.name === 'string' && item.name ? JSON.stringify(item.name.slice(0, NAME_MAX)) : `#${index + 1}`;
+    const refuse = reason => { throw invalidCase(label, reason); };
+    if (!plain(item)) refuse('a case must be an object.');
+    const extra = Object.keys(item).filter(key => !['name', 'operation', 'input', 'expect'].includes(key));
+    if (extra.length) refuse(`unknown fields ${extra.join(', ')}; a case is exactly { name, operation, input, expect }.`);
+    const { name, operation, input, expect } = item;
+    if (typeof name !== 'string' || name.length < 1 || name.length > NAME_MAX) refuse(`name must be a string of 1–${NAME_MAX} characters.`);
+    if (names.has(name)) refuse('duplicate case name.');
+    if (typeof operation !== 'string' || !OPERATION_NAME.test(operation)) refuse('operation must be an operation name as passed to ctx.operation.');
+    if (known && !known.has(operation)) refuse(`the plugin has no operation ${operation}.`);
+    if (!plain(input)) refuse('input must be a JSON object.');
+    if (!plain(expect)) refuse('expect must be an object.');
+    const forms = Object.keys(expect);
+    if (forms.length !== 1 || !EXPECT_FORMS.includes(forms[0])) refuse('expect must hold exactly one of returns, output_schema or throws.');
+    try { requireJson(item, 'The case'); } catch (error) { refuse(error.message); }
+    if (Object.hasOwn(expect, 'returns') && expect.returns === undefined) refuse('expect.returns must be a JSON value.');
+    if (vacuous(expect)) refuse('this expectation cannot fail (an empty returns object or an empty output_schema).');
+    if (Object.hasOwn(expect, 'output_schema')) {
+      if (!plain(expect.output_schema)) refuse('expect.output_schema must be a JSON Schema object.');
+      if (hasAsync(expect.output_schema)) refuse('expect.output_schema must not use $async.');
+      try { schemaValidator(expect.output_schema); } catch (error) { refuse(`expect.output_schema is not a valid schema: ${String(error.message).slice(0, 300)}`); }
+    }
+    if (Object.hasOwn(expect, 'throws')) {
+      const thrown = expect.throws;
+      if (!plain(thrown) || Object.keys(thrown).length !== 1 || typeof thrown.code !== 'string' || !thrown.code || thrown.code.length > CODE_MAX) refuse(`expect.throws must be exactly { code } with a code of 1–${CODE_MAX} characters.`);
+    }
+    if (Buffer.byteLength(JSON.stringify(item)) > CASE_BYTES) refuse('a case is at most 64 KB as JSON.');
+    names.add(name);
+    out.push({ name, operation, input: structuredClone(input), expect: structuredClone(expect) });
+  });
+  return immutable(out);
+}
+
+/** SHA-256 (64 hex) of the canonical JSON of a case's four fields. */
+export function caseDigest(c) {
+  return digest({ name: c.name, operation: c.operation, input: c.input, expect: c.expect });
+}
+
+// A contract is plain JSON or it is no contract: a value JSON cannot hold (NaN, ±Infinity, a RegExp, a
+// Date, a function, a class instance, a hole or undefined in an array, a cycle) could make two
+// different surfaces digest alike. Returns a copy; undefined object properties are dropped (absent).
+function contractInvalid(reason) { return Object.assign(new Error(`Invalid plugin contract: ${reason}`), { code: 'PLUGIN_CONTRACT_INVALID' }); }
+function strictJson(value, at, ancestors = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') { if (!Number.isFinite(value)) throw contractInvalid(`${at} is a number that is not finite.`); return value; }
+  if (typeof value !== 'object') throw contractInvalid(`${at} is a ${typeof value}, not JSON.`);
+  if (ancestors.has(value)) throw contractInvalid(`${at} is cyclic.`);
+  if (!Array.isArray(value) && !plain(value)) throw contractInvalid(`${at} is a ${value.constructor?.name || 'non-plain object'}, not JSON.`);
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const out = [];
+      for (let index = 0; index < value.length; index++) {
+        if (!Object.hasOwn(value, index) || value[index] === undefined) throw contractInvalid(`${at}[${index}] is undefined or a hole.`);
+        out.push(strictJson(value[index], `${at}[${index}]`, ancestors));
+      }
+      return out;
+    }
+    const out = {};
+    for (const key of Object.keys(value)) if (value[key] !== undefined) Object.defineProperty(out, key, { value: strictJson(value[key], `${at}.${key}`, ancestors), enumerable: true, writable: true, configurable: true });
+    return out;
+  } finally { ancestors.delete(value); }
+}
+
+// What an Operation carries that is derived for each generation or build, and so is not promised:
+//   revision             — a fresh UUID for every generation;
+//   origin.generation    — the same per-generation UUID;
+//   origin.module_sha256 — the code's fingerprint, which every repair changes;
+//   origin.version       — the plugin's version, which a repair may bump (version is not surface).
+// Everything else on the Operation's contract is surface, including fields added to Operation
+// later: the default is covered, the exclusion is explicit.
+const DERIVED_FIELDS = Object.freeze(['revision']);
+const DERIVED_ORIGIN_FIELDS = Object.freeze(['generation', 'module_sha256', 'version']);
+
+/** The surface entry of a registered operation: its full contract minus the derived fields, under its short name. */
+export function operationSurface(operationContract, name = operationContract.name) {
+  const entry = {};
+  for (const key of Object.keys(operationContract)) if (!DERIVED_FIELDS.includes(key)) Object.defineProperty(entry, key, { value: operationContract[key], enumerable: true, writable: true, configurable: true });
+  if (plain(entry.origin)) {
+    const origin = {};
+    for (const key of Object.keys(entry.origin)) if (!DERIVED_ORIGIN_FIELDS.includes(key)) Object.defineProperty(origin, key, { value: entry.origin[key], enumerable: true, writable: true, configurable: true });
+    entry.origin = origin;
+  }
+  entry.name = name;
+  return entry;
+}
+
+const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+const sortedNames = (list, what) => { if (!Array.isArray(list) || list.some(item => typeof item !== 'string')) throw contractInvalid(`${what} must be a list of names.`); return [...list].sort(); };
+
+/**
+ * The contract of a plugin. `operations` are surface entries (operationSurface, or any objects with a
+ * string `name`: the short name). `guards` is { count, covers: [short names] }, `observers`
+ * { <event>: count }, `services` [{ name, type, keys?: [{ key, type }] }]. Returns, frozen,
+ * { surface_digest, cases: [{ name, digest, operation, input, expect }], surface } where surface is
+ * { id, requires, provides, config_schema, tool_loading, discovery, hook_timeout_ms, operations
+ * (sorted by name), guards, observers, services } and surface_digest its SHA-256. `version` and the
+ * cases are not part of the surface. Throws PLUGIN_CONTRACT_INVALID for anything that is not plain
+ * JSON, and for duplicate operation names.
+ */
+export function contractOf({ id, version, requires = [], provides = [], config_schema = null, tool_loading = 'eager', discovery = null, hook_timeout_ms = 1000, operations = [], cases = [], guards = { count: 0, covers: [] }, observers = {}, services = [] }) {
+  void version;
+  if (!Array.isArray(operations) || operations.some(op => !plain(op) || typeof op.name !== 'string')) throw contractInvalid('operations must be objects with a name.');
+  if (new Set(operations.map(op => op.name)).size !== operations.length) throw contractInvalid('two operations share a name.');
+  if (!Array.isArray(services) || services.some(service => !plain(service) || typeof service.name !== 'string')) throw contractInvalid('services must be objects with a name.');
+  if (!plain(guards)) throw contractInvalid('guards must be an object.');
+  if (!Array.isArray(cases) || cases.some(c => !plain(c))) throw contractInvalid('cases must be a list of objects.');
+  const surface = strictJson({
+    id,
+    requires: sortedNames(requires, 'requires'),
+    provides: sortedNames(provides, 'provides'),
+    config_schema: config_schema ?? null,
+    tool_loading: tool_loading ?? 'eager',
+    discovery: discovery ?? null,
+    hook_timeout_ms: hook_timeout_ms ?? 1000,
+    operations: [...operations].sort(byName),
+    guards: { ...guards, ...(Array.isArray(guards.covers) ? { covers: sortedNames(guards.covers, 'guards.covers') } : {}) },
+    observers,
+    services: [...services].sort(byName),
+  }, 'surface');
+  const entries = strictJson(cases.map(c => ({ name: c.name, operation: c.operation, input: c.input, expect: c.expect })), 'cases');
+  return immutable({ surface_digest: digest(surface), cases: entries.map(c => ({ name: c.name, digest: caseDigest(c), operation: c.operation, input: c.input, expect: c.expect })), surface });
+}
+
+const SURFACE_ORDER = ['id', 'requires', 'provides', 'config_schema', 'tool_loading', 'discovery', 'hook_timeout_ms', 'guards', 'observers', 'services'];
+const sameValue = (a, b) => digest(a ?? null) === digest(b ?? null);
+const union = (a, b) => [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+
+// A contract compareContracts can trust: plain JSON, unique operation names, cases with a name and a digest.
+function readable(contract) {
+  if (!plain(contract) || Object.hasOwn(contract, 'invalid') || !plain(contract.surface) || !Array.isArray(contract.cases)) return null;
+  try {
+    const surface = strictJson(contract.surface, 'surface'), cases = strictJson(contract.cases, 'cases');
+    const operations = surface.operations ?? [];
+    if (!Array.isArray(operations) || operations.some(op => !plain(op) || typeof op.name !== 'string') || new Set(operations.map(op => op.name)).size !== operations.length) return null;
+    if (cases.some(c => !plain(c) || typeof c.name !== 'string' || typeof c.digest !== 'string')) return null;
+    return { surface, operations, cases };
+  } catch { return null; }
+}
+
+/**
+ * What a candidate contract changes against the live one. surface_changed lists the plugin-level
+ * fields that differ (id, requires, provides, config_schema, tool_loading, discovery,
+ * hook_timeout_ms, guards, observers, services, then any other), then per operation by name
+ * 'operation:<name>:removed', 'operation:<name>:<field>' (origin by 'origin.<field>') and
+ * 'operation:<name>:added'. A case name that appears twice on either side is in cases_changed.
+ * kept is true only when nothing in the surface changed and no live case was removed or changed;
+ * added cases keep the contract. A contract that is invalid or unreadable on either side is
+ * never kept: surface_changed ['contract:invalid']. Never throws.
+ */
+export function compareContracts(live, candidate) {
+  const before = readable(live), after = readable(candidate);
+  if (!before || !after) return { kept: false, surface_changed: ['contract:invalid'], cases_added: [], cases_removed: [], cases_changed: [] };
+  const surface_changed = [];
+  const keys = union(before.surface, after.surface).filter(key => key !== 'operations');
+  for (const key of [...SURFACE_ORDER, ...keys.filter(key => !SURFACE_ORDER.includes(key))]) if (!sameValue(before.surface[key], after.surface[key])) surface_changed.push(key);
+  const index = list => new Map(list.map(op => [op.name, op]));
+  const was = index(before.operations), now = index(after.operations);
+  for (const name of [...was.keys()].sort()) {
+    if (!now.has(name)) { surface_changed.push(`operation:${name}:removed`); continue; }
+    const a = was.get(name), b = now.get(name);
+    for (const field of union(a, b).filter(field => field !== 'name')) {
+      if (field === 'origin' && plain(a.origin) && plain(b.origin)) { for (const sub of union(a.origin, b.origin)) if (!sameValue(a.origin[sub], b.origin[sub])) surface_changed.push(`operation:${name}:origin.${sub}`); }
+      else if (!sameValue(a[field], b[field])) surface_changed.push(`operation:${name}:${field}`);
+    }
+  }
+  for (const name of [...now.keys()].sort()) if (!was.has(name)) surface_changed.push(`operation:${name}:added`);
+  if (!surface_changed.length && digest(before.surface) !== digest(after.surface)) surface_changed.push('surface');
+  const tally = list => { const out = new Map(); for (const c of list) out.set(c.name, [...(out.get(c.name) ?? []), c.digest]); return out; };
+  const liveCases = tally(before.cases), nextCases = tally(after.cases);
+  const duplicated = new Set([...liveCases, ...nextCases].filter(([, digests]) => digests.length > 1).map(([name]) => name));
+  const cases_added = [...nextCases.keys()].filter(name => !liveCases.has(name) && !duplicated.has(name));
+  const cases_removed = [...liveCases.keys()].filter(name => !nextCases.has(name) && !duplicated.has(name));
+  const cases_changed = [...new Set([...liveCases.keys(), ...nextCases.keys()])].filter(name => duplicated.has(name) || (liveCases.has(name) && nextCases.has(name) && liveCases.get(name)[0] !== nextCases.get(name)[0]));
+  return { kept: !surface_changed.length && !cases_removed.length && !cases_changed.length, surface_changed, cases_added, cases_removed, cases_changed };
+}
+
+// null when `actual` contains `expected`: objects by recursive subset, arrays element by element
+// with equal length, scalars by strict equality. Otherwise the first difference, by path.
+function difference(expected, actual, at) {
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) return `${at}: expected an array, got ${shown(actual)}`;
+    if (actual.length !== expected.length) return `${at}: expected ${expected.length} items, got ${actual.length}`;
+    for (let index = 0; index < expected.length; index++) { const found = difference(expected[index], actual[index], `${at}[${index}]`); if (found) return found; }
+    return null;
+  }
+  if (expected !== null && typeof expected === 'object') {
+    if (actual === null || typeof actual !== 'object' || Array.isArray(actual)) return `${at}: expected an object, got ${shown(actual)}`;
+    for (const key of Object.keys(expected)) {
+      if (!Object.hasOwn(actual, key)) return `${at}.${key}: missing`;
+      const found = difference(expected[key], actual[key], `${at}.${key}`); if (found) return found;
+    }
+    return null;
+  }
+  return Object.is(expected, actual) || expected === actual ? null : `${at}: expected ${shown(expected)}, got ${shown(actual)}`;
+}
+
+// An operation's output usually reaches the house as text: a string that is JSON is read as JSON.
+function readOutput(output) {
+  if (typeof output !== 'string') return output;
+  try { return JSON.parse(output); } catch { return output; }
+}
+
+/**
+ * Evaluate a case on an operation's real result: { status: 'returned', output } |
+ * { status: 'threw', code, message } | { status: 'not_run', reason }. Returns { pass, reason? }.
+ * `not_run` never passes. Never throws.
+ */
+export function evaluateCase(c, result) {
+  try {
+    const fail = reason => ({ pass: false, reason: String(reason).slice(0, 500) });
+    const expect = c?.expect;
+    if (!plain(result) || !['returned', 'threw', 'not_run'].includes(result.status)) return fail('No result to evaluate.');
+    if (result.status === 'not_run') return fail(`Not run: ${typeof result.reason === 'string' && result.reason ? result.reason : 'no reason given'}`);
+    if (!plain(expect)) return fail('The case has no expectation.');
+    if (vacuous(expect)) return fail('The expectation cannot fail, so it proves nothing.');
+    if (Object.hasOwn(expect, 'throws')) {
+      if (result.status !== 'threw') return fail(`Expected a throw with code ${expect.throws.code}; it returned.`);
+      return result.code === expect.throws.code ? { pass: true } : fail(`Expected code ${expect.throws.code}; it threw ${shown(result.code ?? null)}: ${shown(result.message ?? '')}`);
+    }
+    if (result.status !== 'returned') return fail(`Expected a return; it threw ${shown(result.code ?? null)}: ${shown(result.message ?? '')}`);
+    const output = readOutput(result.output);
+    if (Object.hasOwn(expect, 'returns')) {
+      const found = difference(expect.returns, output, 'output');
+      // A string promise is also kept by the same text, read as it is.
+      if (found && typeof expect.returns === 'string' && result.output === expect.returns) return { pass: true };
+      return found ? fail(found) : { pass: true };
+    }
+    if (Object.hasOwn(expect, 'output_schema')) {
+      if (!plain(expect.output_schema) || hasAsync(expect.output_schema)) return fail('output_schema must be a synchronous JSON Schema object.');
+      const validate = schemaValidator(expect.output_schema), verdict = validate(output);
+      if (verdict && typeof verdict.then === 'function') { verdict.then(() => {}, () => {}); return fail('output_schema did not give a synchronous verdict.'); }
+      return verdict === true ? { pass: true } : fail(`The output does not match output_schema: ${validate.errors.slice(0, 6).map(error => `${error.instancePath || 'output'} ${error.message}`).join('; ')}`);
+    }
+    return fail('The case has no known expectation.');
+  } catch (error) {
+    return { pass: false, reason: `The case could not be evaluated: ${String(error?.message ?? error).slice(0, 300)}` };
+  }
+}