@youzan-cloud/zan-saas-cli 0.0.0-stage → 0.1.0-beta.3

package/src/execution/parser-error.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const Ajv = require('ajv');
+const { diagnosticDefinitions } = require('./error-model');
+
+const object = properties => ({
+  type: 'object', additionalProperties: false, required: Object.keys(properties), properties
+});
+const argv = {
+  type: 'array', minItems: 1,
+  items: { type: 'string', pattern: '^(?:[a-z][a-z0-9-]*|\\+[a-z][a-z0-9-]*|--help)$' },
+  description: '从当前安装版注册树生成的参数数组，不含可执行文件名或收到的参数值。'
+};
+const issue = structuredClone(diagnosticDefinitions.diagnosticIssue);
+issue.properties.source = { const: 'argv', description: '命令行解析阶段的问题。' };
+issue.properties.expected = structuredClone(diagnosticDefinitions.diagnosticExpected);
+const details = object({
+  category: { const: 'parameter', description: 'CLI 命令或参数不符合调用要求。' },
+  stage: { const: 'input', description: '业务动作执行前的命令行解析阶段。' },
+  command: { type: 'string', description: '最近已识别节点的点分路径；根路径为空字符串。' },
+  targetScope: object({}),
+  requestState: { const: 'not_sent', description: '本地解析拒绝，尚未发送请求。' },
+  errorVersion: { const: 2, description: '公共解析错误复用第二版诊断字段。' },
+  issues: { type: 'array', minItems: 1, maxItems: 16, items: issue,
+    description: '已定位的参数问题，不回显原始输入。' },
+  helpArgv: { ...argv, description: '最近已识别节点的帮助参数，不含可执行文件名。' },
+  recovery: structuredClone(diagnosticDefinitions.diagnosticRecovery),
+  execution: object({
+    requestState: { const: 'not_sent' },
+    coverage: { const: 'complete' },
+    observedAttempts: { const: 0 }
+  }),
+  nextStep: { type: 'string', description: '从本地命令契约生成的安全修正或帮助提示。' }
+});
+details.properties.suggestions = {
+  type: 'array', minItems: 1, maxItems: 3, items: argv,
+  description: '可靠候选的完整参数数组；没有可靠候选时省略。仅提示，不自动执行。'
+};
+const parserErrorModel = {
+  ...object({
+    success: { const: false }, code: { const: -10001 },
+    message: { type: 'string', description: '简短中文摘要；机器判断使用 issues.reason。' },
+    details
+  }),
+  description: '公共命令行解析错误，stdout 为空，stderr 单行 JSON，退出 1。已有叶子的专用诊断可继续使用其 error 模型。'
+};
+const validate = new Ajv({ strict: true, allErrors: true }).compile(parserErrorModel);
+
+class ParserError extends Error {
+  constructor(message, facts) {
+    super(message);
+    this.result = {
+      success: false, code: -10001, message,
+      details: {
+        category: 'parameter', stage: 'input', targetScope: {}, requestState: 'not_sent',
+        errorVersion: 2,
+        recovery: { action: 'correct_input', automaticBusinessRetry: false },
+        execution: { requestState: 'not_sent', coverage: 'complete', observedAttempts: 0 },
+        ...facts
+      }
+    };
+    if (!validate(this.result)) throw new Error('公共解析错误不符合诊断契约');
+  }
+}
+
+module.exports = { ParserError, parserErrorModel };

package/src/execution/privacy.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const { snapshotApiEnvironment } = require('../transport/api');
+const { createShopQuery, failure } = require('./shop-query');
+const { object } = require('./query-api');
+const { copyErrorDetails } = require('./error-details');
+const { incompleteCoverage } = require('./request-state');
+
+const RESPONSE_LIMIT = 10 * 1024 * 1024;
+const OUTPUT_LIMIT = 5 * 1024 * 1024;
+const paths = Object.freeze({
+  verifySingle: 'youzan.cloud.secret.verify.isencrypt/1.0.0',
+  verifyBatch: 'youzan.cloud.secret.verify.isencryptlist/1.0.0',
+  decryptSingle: 'youzan.cloud.secret.decrypt.single/1.0.0',
+  decryptBatch: 'youzan.cloud.secret.decrypt.batch/1.0.0'
+});
+
+function validReason(value) {
+  return typeof value === 'string' && value === value.trim() &&
+    [...value].length >= 1 && [...value].length <= 200 && !/[\p{Cc}\p{Zl}\p{Zp}]/u.test(value);
+}
+
+function privacyFailure(command, scope, category, stage, state = 'not_sent', facts = {}) {
+  const error = failure(command, category, stage, scope, state, facts);
+  error.cliDetails.nextStep = '停止明文披露。核对原员工会话、应用、店铺、对象字段权限和可靠访问记录；不自动重试、换身份或改用其他入口。';
+  return error;
+}
+
+function privacyError(command, category, stage, scope = {}, requestState = 'not_sent', facts = {}) {
+  return privacyFailure(command, scope, category, stage, requestState, facts);
+}
+
+function safeFailure(error, command, scope, stage, state, independent = false) {
+  const details = error?.cliDetails;
+  const facts = {};
+  if (Number.isInteger(details?.httpStatus)) facts.httpStatus = details.httpStatus;
+  for (const key of ['businessCode', 'gatewayCode']) {
+    if (Number.isSafeInteger(details?.[key])) facts[key] = details[key];
+  }
+  const api = details?.api;
+  if (Object.values(paths).includes(api) || api === 'youzan.shop.basic.get/3.0.0' ||
+      api === 'youzan.trade.get/4.0.2') facts.api = api;
+  if (!facts.api) {
+    const stageApi = {
+      'shop-binding': 'youzan.shop.basic.get/3.0.0',
+      source: 'youzan.trade.get/4.0.2',
+      'source-object': 'youzan.trade.get/4.0.2',
+      'ciphertext-verification': paths.verifySingle,
+      verify: paths.verifySingle,
+      decryption: paths.decryptSingle,
+      decrypt: paths.decryptSingle
+    };
+    if (stageApi[stage]) facts.api = stageApi[stage];
+  }
+  const categories = ['configuration', 'authentication', 'permission', 'scope_unresolved',
+    'http', 'business_rejected', 'transport', 'protocol', 'limit'];
+  const failure = privacyFailure(command, scope, categories.includes(details?.category) ? details.category : 'protocol',
+    independent && details?.stage ? details.stage : stage,
+    ['not_sent', 'sent', 'unknown'].includes(details?.requestState) ? details.requestState : state, facts);
+  if (details) {
+    const safe = copyErrorDetails(details);
+    for (const key of ['issues', 'issuesTruncated', 'errorVersion', 'recovery', 'execution']) {
+      if (Object.hasOwn(safe, key)) failure.cliDetails[key] = safe[key];
+    }
+  }
+  if (error.diagnosticReason) failure.diagnosticReason = error.diagnosticReason;
+  return failure;
+}
+
+async function discloseFields(input, dependencies) {
+  const { command, allowedFields, readSource, validateResult, provider } = dependencies;
+  const scope = Object.freeze({ kdtId: input?.scope?.kdtId });
+  const fail = (category, stage, state, facts) => privacyFailure(command, scope, category, stage, state, facts);
+  const fields = input?.fields;
+  const independent = input?.preserveStage === true;
+  if (!Array.isArray(allowedFields) || typeof readSource !== 'function' || typeof validateResult !== 'function') {
+    throw fail('configuration', 'configuration');
+  }
+  if (typeof scope.kdtId !== 'string' || !/^[1-9]\d*$/.test(scope.kdtId) || !Number.isSafeInteger(Number(scope.kdtId)) ||
+      !object(input.object) || !Array.isArray(fields) || fields.length < 1 || fields.length > 3 ||
+      new Set(fields).size !== fields.length || fields.some(field => !allowedFields.includes(field)) ||
+      !validReason(input.reason)) throw fail('validation', 'input');
+  const expected = input.expectedCiphertexts;
+  if (expected !== undefined && (!object(expected) || Object.keys(expected).length !== fields.length ||
+      fields.some(field => !Object.hasOwn(expected, field) || typeof expected[field] !== 'string'))) {
+    throw fail('validation', 'input');
+  }
+  const request = Object.freeze({ scope, object: Object.freeze({ ...input.object }),
+    fields: Object.freeze([...fields]), reason: input.reason,
+    ...(expected === undefined ? {} : { expectedCiphertexts: Object.freeze({ ...expected }) }) });
+  if (!provider || typeof provider.authorize !== 'function') {
+    throw fail('configuration', 'sensitive-authorization');
+  }
+  let environment;
+  try { environment = await snapshotApiEnvironment(undefined, Number(scope.kdtId)); }
+  catch (error) {
+    const failure = fail('configuration', 'configuration');
+    failure.diagnosticReason = error.diagnosticReason;
+    throw failure;
+  }
+  let access;
+  incompleteCoverage();
+  try { access = await provider.authorize(request, { environment }); }
+  catch { throw fail('permission', 'sensitive-authorization', 'unknown'); }
+  if (!access || typeof access.verifySource !== 'function' || typeof access.recordAccess !== 'function') {
+    if (independent) throw privacyFailure(command, scope, 'permission', 'privacy-authorization');
+    throw fail('permission', 'sensitive-authorization');
+  }
+  let stage = 'shop-binding';
+  let requestCount = 0;
+  let responseBytes = 0;
+  const requestState = () => requestCount ? 'sent' : 'not_sent';
+  let result;
+  let error;
+  try {
+    const read = await createShopQuery({ kdtId: Number(scope.kdtId) }, command, {
+      environment,
+      transportOptions: {
+        shopApp: false,
+        onRequest: () => {
+          if (requestCount >= 4) throw fail('limit', stage, requestState());
+          requestCount += 1;
+        },
+        maxResponseBytes: () => RESPONSE_LIMIT - responseBytes
+      },
+      onResponse: response => {
+        responseBytes += response.responseBytes;
+        if (responseBytes > RESPONSE_LIMIT) throw fail('limit', stage, requestState());
+      }
+    });
+    stage = 'source';
+    const source = await readSource(read, request);
+    if (!object(source) || !Array.isArray(source.values) || source.values.length !== request.fields.length) {
+      throw fail('protocol', stage, requestState());
+    }
+    const selected = request.fields.map((field, index) => {
+      const entry = source.values[index];
+      if (!object(entry) || entry.field !== field || typeof entry.value !== 'string' ||
+          !entry.value.trim() || Buffer.byteLength(entry.value, 'utf8') > 16384 ||
+          /[\p{Cc}\p{Zl}\p{Zp}]/u.test(entry.value)) throw fail('protocol', stage, requestState());
+      if (request.expectedCiphertexts && request.expectedCiphertexts[field] !== entry.value) {
+        throw fail('scope_unresolved', stage, requestState());
+      }
+      return Object.freeze({ field, value: entry.value });
+    });
+    if (await access.verifySource({ sourceData: source.sourceData, values: selected }) !== true) {
+      throw fail('scope_unresolved', stage, requestState());
+    }
+    const sources = [...new Set(selected.map(entry => entry.value))];
+    const single = sources.length === 1;
+    stage = 'ciphertext-verification';
+    const verification = await read(single ? paths.verifySingle : paths.verifyBatch,
+      single ? { secret_key_single_encrypt_query_request: JSON.stringify({ source: sources[0] }) } :
+        { request: JSON.stringify({ sources }) }, stage);
+    if (!object(verification.data) || verification.data.is_encrypt !== true) {
+      throw fail('protocol', stage, requestState());
+    }
+    stage = 'decryption';
+    const decrypted = await read(single ? paths.decryptSingle : paths.decryptBatch,
+      single ? { source: sources[0] } : { sources }, stage);
+    if (!single && (!object(decrypted.data) || Object.keys(decrypted.data).length !== sources.length ||
+        sources.some(sourceValue => !Object.hasOwn(decrypted.data, sourceValue)))) {
+      throw fail('protocol', stage, requestState());
+    }
+    const plaintexts = new Map(sources.map(sourceValue => {
+      const value = single ? decrypted.data : decrypted.data[sourceValue];
+      if (typeof value !== 'string' || (!input.allowEmptyPlaintext && !value.trim()) || value === sourceValue) {
+        throw fail('protocol', stage, requestState());
+      }
+      return [sourceValue, value];
+    }));
+    result = { sourceData: source.sourceData,
+      values: selected.map(entry => ({ field: entry.field, value: plaintexts.get(entry.value) })) };
+    stage = 'output-model';
+    await validateResult(result);
+  } catch (caught) {
+    error = safeFailure(caught, command, scope, stage, requestState(), independent);
+  }
+  try {
+    const outcome = !error ? 'release_authorized' :
+      error.cliDetails?.requestState === 'unknown' ? 'unknown' : 'denied';
+    const auditEvent = {
+      outcome, stage,
+      ...(error?.cliDetails?.api ? { api: error.cliDetails.api } : {})
+    };
+    if (await access.recordAccess(auditEvent) !== true) {
+      throw new Error('audit unavailable');
+    }
+  } catch {
+    if (independent) throw privacyFailure(command, scope, 'audit_failed', 'audit', 'unknown');
+    throw fail('transport', 'sensitive-audit', 'unknown');
+  }
+  if (error) throw error;
+  return result;
+}
+
+module.exports = { discloseFields, privacyError, validReason, paths, RESPONSE_LIMIT, OUTPUT_LIMIT };

package/src/execution/public-schema.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const modelMaps = new Set([
+  'properties', 'patternProperties', 'definitions', '$defs', 'dependentSchemas'
+]);
+const modelValues = new Set([
+  'items', 'additionalItems', 'additionalProperties', 'contains', 'not',
+  'if', 'then', 'else', 'propertyNames', 'contentSchema'
+]);
+const modelArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+
+function publicModel(model) {
+  if (typeof model === 'boolean') return model;
+  const result = {};
+  for (const [key, value] of Object.entries(model)) {
+    if (key === '$comment') continue;
+    if (modelMaps.has(key) || key === 'dependencies') {
+      result[key] = Object.fromEntries(Object.entries(value).map(([name, child]) => [
+        name, Array.isArray(child) ? structuredClone(child) : publicModel(child)
+      ]));
+    } else if (modelArrays.has(key) || (key === 'items' && Array.isArray(value))) {
+      result[key] = value.map(publicModel);
+    } else if (modelValues.has(key)) {
+      result[key] = publicModel(value);
+    } else {
+      result[key] = structuredClone(value);
+    }
+  }
+  return result;
+}
+
+function publicCommandSchema(schema) {
+  if (!schema) return {};
+  const result = { schemaVersion: schema.schemaVersion };
+  for (const section of ['input', 'output', 'preview', 'error']) {
+    if (schema[section]) result[section] = publicModel(schema[section]);
+  }
+  if (schema.definitions) {
+    result.definitions = Object.fromEntries(Object.entries(schema.definitions)
+      .map(([name, model]) => [name, publicModel(model)]));
+  }
+  if (schema.modules) {
+    result.modules = Object.fromEntries(Object.entries(schema.modules)
+      .map(([name, { base, description }]) => [name, { base, description }]));
+  }
+  for (const key of ['success', 'errors', 'notes']) {
+    if (schema[key]) result[key] = structuredClone(schema[key]);
+  }
+  return result;
+}
+
+module.exports = { publicModel, publicCommandSchema };

package/src/execution/query-api.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const { requestApi, ApiConfigurationError, ApiResponseLimitError } = require('../transport/api');
+const { parseExactJson } = require('./exact-json');
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+class QueryError extends Error {
+  constructor(category, stage, scope, facts, requestState, command, nextStep) {
+    super(`查询失败：${category}（${stage}）`);
+    this.cliDetails = {
+      ...facts, category, stage, command, targetScope: scope, requestState, nextStep
+    };
+  }
+}
+
+function assertSafeNumbers(value) {
+  if (typeof value === 'number' && (!Number.isFinite(value) ||
+      (Number.isInteger(value) && !Number.isSafeInteger(value)))) {
+    throw new Error('unsafe numeric value');
+  }
+  if (Array.isArray(value)) value.forEach(assertSafeNumbers);
+  else if (object(value)) Object.values(value).forEach(assertSafeNumbers);
+}
+
+function diagnosticCode(value) {
+  return Number.isSafeInteger(value) ||
+    (typeof value === 'string' && value.trim() === value && /^-?\d{1,12}$/.test(value));
+}
+
+function diagnostics(result, path, httpStatus) {
+  const facts = { api: path, httpStatus };
+  if (diagnosticCode(result?.code)) facts.businessCode = result.code;
+  const gateway = object(result?.gw_err_resp) ? result.gw_err_resp : null;
+  if (diagnosticCode(gateway?.err_code)) facts.gatewayCode = gateway.err_code;
+  for (const field of ['trace_id', 'request_id']) {
+    const value = result?.[field] ?? gateway?.[field];
+    if (typeof value === 'string' && value.trim() === value &&
+        /^[a-zA-Z0-9_-]{1,128}$/.test(value)) {
+      facts[field] = value;
+    }
+  }
+  return facts;
+}
+
+async function readApiEnvelope(path, body, failure, env, onResponse, transportOptions) {
+  let response;
+  try {
+    response = await requestApi({ path, body }, env, transportOptions);
+  } catch (error) {
+    if (error instanceof ApiConfigurationError) {
+      const rejected = failure('configuration', {}, 'not_sent', 'configuration');
+      rejected.diagnosticReason = error.diagnosticReason;
+      throw rejected;
+    }
+    if (error instanceof ApiResponseLimitError) {
+      const limitStage = typeof transportOptions?.limitStage === 'function'
+        ? transportOptions.limitStage(path) : transportOptions?.limitStage;
+      throw failure(transportOptions?.limitCategory || 'limit',
+        { api: path, httpStatus: error.httpStatus }, 'sent',
+        limitStage || 'response');
+    }
+    throw failure('transport', {}, 'unknown', 'transport');
+  }
+  if (onResponse) onResponse(response, path);
+  let result;
+  try {
+    result = parseExactJson(response.body);
+    if (!object(result)) result = null;
+  } catch {
+    result = null;
+  }
+  const facts = diagnostics(result, path, response.httpStatus);
+  if (!response.ok) {
+    const category = response.httpStatus === 401 ? 'authentication' :
+      response.httpStatus === 403 ? 'permission' : 'http';
+    throw failure(category, facts, 'sent', 'http');
+  }
+  if (!result) throw failure('protocol', facts, 'sent', 'response');
+  return { result, facts, rawBody: response.body, responseBytes: response.responseBytes };
+}
+
+function assertApiSuccess(result, reject, successCodes = [200]) {
+  if (Object.hasOwn(result, 'gw_err_resp')) {
+    if (result.success === true || successCodes.includes(result.code)) reject('protocol');
+    if (object(result.gw_err_resp) && diagnosticCode(result.gw_err_resp.err_code)) {
+      reject('business_rejected');
+    }
+    reject('protocol');
+  }
+  if (result.success === false) {
+    reject(successCodes.includes(result.code) ? 'protocol' : 'business_rejected');
+  }
+  if (result.success === undefined && Number.isSafeInteger(result.code) &&
+      ![0, 200].includes(result.code)) reject('business_rejected');
+  if (result.success !== true || !successCodes.includes(result.code)) reject('protocol');
+}
+
+module.exports = {
+  QueryError, readApiEnvelope, assertApiSuccess, assertSafeNumbers, object, diagnosticCode
+};

package/src/execution/range.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const { parseDateTime, formatDateTime, apiSeconds } = require('./datetime');
+const { formatYuan, compareYuan } = require('./money');
+
+function bounds(raw, allowBare) {
+  if (typeof raw !== 'string' || !raw || raw.trim() !== raw) {
+    throw new Error('区间须为非空文本，不能包含首尾空白');
+  }
+  const parts = raw.split('..');
+  if (parts.length === 1 && allowBare) return [raw, raw];
+  if (parts.length !== 2 || (!parts[0] && !parts[1])) {
+    throw new Error('区间须使用 LOW..HIGH、LOW.. 或 ..HIGH，时间必须包含 ..');
+  }
+  return parts;
+}
+
+function parseRange(raw, { keys, allowBare = false, requireBoth = false, strictOrder = false,
+  parse, compare }) {
+  const parts = bounds(raw, allowBare);
+  if (requireBoth && parts.some(value => value === '')) throw new Error('此区间必须显式提供两个边界');
+  const result = {};
+  parts.forEach((value, index) => {
+    if (value === '') return;
+    if (value.trim() !== value) throw new Error('区间边界不能包含首尾空白');
+    result[keys[index]] = parse(value);
+  });
+  if (parts.every(value => value !== '')) {
+    const order = compare(result[keys[0]], result[keys[1]]);
+    if (order > 0 || (strictOrder && order === 0)) {
+      throw new Error(strictOrder ? '区间起点必须早于终点' : '区间起点不得晚于终点');
+    }
+  }
+  return result;
+}
+
+function parseIntegerRange(raw, { minimum = 0, maximum = Number.MAX_SAFE_INTEGER } = {}) {
+  if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum) || minimum > maximum) {
+    throw new Error('整数区间配置无效');
+  }
+  return parseRange(raw, { keys: ['min', 'max'], allowBare: true,
+    parse(value) {
+      if (!/^-?\d+$/.test(value)) throw new Error('区间边界须为十进制整数');
+      const number = Number(value);
+      if (!Number.isSafeInteger(number) || number < minimum || number > maximum) {
+        throw new Error('整数区间边界超出命令允许范围');
+      }
+      return number;
+    },
+    compare: (a, b) => a < b ? -1 : a > b ? 1 : 0
+  });
+}
+
+function parseMoneyRange(raw, { minimum = '0.00', maximum } = {}) {
+  const lower = formatYuan(minimum);
+  const upper = maximum === undefined ? undefined : formatYuan(maximum);
+  if (!lower || upper === '' || (upper !== undefined && compareYuan(lower, upper) > 0)) {
+    throw new Error('金额区间配置无效');
+  }
+  return parseRange(raw, { keys: ['min', 'max'], allowBare: true,
+    parse(value) {
+      const normalized = formatYuan(value);
+      if (!normalized || compareYuan(normalized, lower) < 0 ||
+          (upper !== undefined && compareYuan(normalized, upper) > 0)) {
+        throw new Error('金额区间边界超出命令允许范围');
+      }
+      return normalized;
+    },
+    compare: compareYuan
+  });
+}
+
+function parseDateTimeRange(raw, { precision, requireBoth = false, strictOrder = false } = {}) {
+  if (!['seconds', 'milliseconds'].includes(precision)) throw new Error('须声明接口时间精度');
+  return parseRange(raw, { keys: ['start', 'end'], requireBoth, strictOrder,
+    parse(value) {
+      const milliseconds = precision === 'seconds' ? apiSeconds(value) * 1000 : parseDateTime(value);
+      return formatDateTime(milliseconds);
+    },
+    compare: (a, b) => a < b ? -1 : a > b ? 1 : 0
+  });
+}
+
+module.exports = { parseIntegerRange, parseMoneyRange, parseDateTimeRange };

package/src/execution/request-state.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+const sessions = new AsyncLocalStorage();
+const failures = new WeakMap();
+
+function requestState() {
+  const state = sessions.getStore();
+  const complete = state && !state.partial;
+  return {
+    requestState: !complete || state.unknown || state.pending ? 'unknown' :
+      state.attempts ? 'sent' : 'not_sent',
+    coverage: complete ? 'complete' : 'partial',
+    observedAttempts: state?.attempts || 0
+  };
+}
+
+async function runWithRequestState(action) {
+  incompleteCoverage();
+  return sessions.run({ attempts: 0, pending: 0, unknown: false, partial: false }, async () => {
+    try { return await action(); }
+    catch (error) {
+      if (error instanceof Error) failures.set(error, requestState());
+      throw error;
+    }
+  });
+}
+
+function beginRequest() {
+  const state = sessions.getStore();
+  if (!state) return undefined;
+  state.attempts++;
+  state.pending++;
+  let finished = false;
+  return outcome => {
+    if (finished) return;
+    finished = true;
+    state.pending--;
+    if (outcome === 'unknown') state.unknown = true;
+  };
+}
+
+function incompleteCoverage() {
+  const state = sessions.getStore();
+  if (state) state.partial = true;
+}
+
+function executionFor(error) {
+  return failures.get(error) || requestState();
+}
+
+module.exports = {
+  runWithRequestState, requestState, beginRequest, incompleteCoverage, executionFor
+};

package/src/execution/schema-completeness.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const assertionKeywords = new Set([
+  '$ref', 'type', 'const', 'enum', 'allOf', 'anyOf', 'oneOf', 'not', 'if',
+  'contains', 'pattern', 'format', 'minLength', 'maxLength', 'minimum',
+  'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf', 'minItems',
+  'maxItems', 'uniqueItems', 'minProperties', 'maxProperties', 'properties',
+  'patternProperties', 'additionalProperties', 'propertyNames', 'dependencies',
+  'dependentRequired', 'dependentSchemas'
+]);
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function includesType(schema, type) {
+  return schema.type === type || (Array.isArray(schema.type) && schema.type.includes(type));
+}
+
+function hasObjectShape(schema) {
+  return ['properties', 'patternProperties', 'additionalProperties', 'maxProperties']
+    .some(key => Object.hasOwn(schema, key));
+}
+
+function addIssue(issues, path, message) {
+  issues.push({ path, message });
+}
+
+function visitSchema(schema, path, issues, seen) {
+  if (typeof schema === 'boolean') return;
+  if (!object(schema)) {
+    addIssue(issues, path, 'must be a schema object');
+    return;
+  }
+  if (seen.has(schema)) return;
+  seen.add(schema);
+
+  if (Object.keys(schema).every(key => !assertionKeywords.has(key))) {
+    addIssue(issues, path, 'must define a validation rule, not only metadata such as description');
+  }
+  if (includesType(schema, 'object') && !hasObjectShape(schema)) {
+    addIssue(issues, path,
+      'object schemas must define properties, patternProperties, additionalProperties, or maxProperties');
+  }
+  if (includesType(schema, 'array') && !Object.hasOwn(schema, 'items') &&
+      !Object.hasOwn(schema, 'contains') && schema.maxItems !== 0) {
+    addIssue(issues, path, 'array schemas must define items or contains');
+  }
+  if (Array.isArray(schema.required) && object(schema.properties)) {
+    for (const name of schema.required) {
+      if (!Object.hasOwn(schema.properties, name)) {
+        addIssue(issues, `${path}.required`, `references missing property ${JSON.stringify(name)}`);
+      }
+    }
+  }
+
+  if (object(schema.properties)) {
+    for (const [name, child] of Object.entries(schema.properties)) {
+      visitSchema(child, `${path}.properties.${name}`, issues, seen);
+    }
+  }
+  if (object(schema.patternProperties)) {
+    for (const [name, child] of Object.entries(schema.patternProperties)) {
+      visitSchema(child, `${path}.patternProperties.${name}`, issues, seen);
+    }
+  }
+  if (object(schema.additionalProperties)) {
+    visitSchema(schema.additionalProperties, `${path}.additionalProperties`, issues, seen);
+  }
+  if (object(schema.propertyNames)) {
+    visitSchema(schema.propertyNames, `${path}.propertyNames`, issues, seen);
+  }
+  if (object(schema.dependencies)) {
+    for (const [name, child] of Object.entries(schema.dependencies)) {
+      if (object(child)) visitSchema(child, `${path}.dependencies.${name}`, issues, seen);
+    }
+  }
+  if (object(schema.dependentSchemas)) {
+    for (const [name, child] of Object.entries(schema.dependentSchemas)) {
+      visitSchema(child, `${path}.dependentSchemas.${name}`, issues, seen);
+    }
+  }
+  for (const key of ['items', 'contains', 'not', 'if', 'then', 'else']) {
+    if (object(schema[key])) visitSchema(schema[key], `${path}.${key}`, issues, seen);
+  }
+  for (const key of ['allOf', 'anyOf', 'oneOf']) {
+    if (!Array.isArray(schema[key])) continue;
+    if (schema[key].length === 0) addIssue(issues, `${path}.${key}`, 'must contain at least one schema');
+    schema[key].forEach((child, index) => {
+      visitSchema(child, `${path}.${key}[${index}]`, issues, seen);
+    });
+  }
+}
+
+function findSchemaCompletenessIssues(schema) {
+  const issues = [];
+  const seen = new WeakSet();
+  for (const section of ['input', 'output', 'preview', 'error', 'parserError']) {
+    if (Object.hasOwn(schema, section)) visitSchema(schema[section], section, issues, seen);
+  }
+  if (object(schema.definitions)) {
+    for (const [name, definition] of Object.entries(schema.definitions)) {
+      visitSchema(definition, `definitions.${name}`, issues, seen);
+    }
+  }
+  return issues;
+}
+
+function assertSchemaCompleteness(schema) {
+  const issues = findSchemaCompletenessIssues(schema);
+  if (issues.length === 0) return;
+  const details = issues.map(({ path, message }) => `${path} ${message}`).join('; ');
+  throw new Error(`Incomplete command schema: ${details}`);
+}
+
+module.exports = { assertSchemaCompleteness, findSchemaCompletenessIssues };