@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/api/openapi/tooling/project.mjs

@@ -0,0 +1,549 @@
+import { createHash } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import YAML from 'yaml';
+
+import { isSemanticVersion } from './semantic_version.mjs';
+
+export const apiRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const httpMethods = Object.freeze(['delete', 'get', 'head', 'options', 'patch', 'post', 'put', 'trace']);
+export const audiences = Object.freeze(['internal', 'partner', 'public']);
+export const stabilities = Object.freeze(['experimental', 'beta', 'stable']);
+export const documentationLocales = Object.freeze(['zh-CN']);
+
+const approvedDocumentationLeadingTerms = new Set([
+  'AI', 'API', 'Airwallex', 'Android', 'Apple', 'CH', 'CMS', 'CPM', 'Google', 'Hreflang', 'IAM', 'IAP', 'KOL', 'LINE',
+  'MCP', 'MFA', 'Mapbox', 'OAuth', 'OIDC', 'Outbox', 'PayPal', 'PayerMax', 'Payssion', 'RFC', 'SAML', 'SCIM', 'SEO',
+  'SES', 'SLA', 'SSO', 'SendGrid', 'Stripe', 'Twilio', 'WeChat', 'Webhook', 'WhatsApp', 'iCloud',
+]);
+
+const componentKinds = Object.freeze([
+  'callbacks',
+  'examples',
+  'headers',
+  'links',
+  'parameters',
+  'pathItems',
+  'requestBodies',
+  'responses',
+  'schemas',
+  'securitySchemes',
+]);
+const internalMetadata = new Set(['x-onex-audience', 'x-onex-source']);
+const privateServerPattern = /(^|\/\/)(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|[^/]+\.(internal|local))(?=[:/]|$)/i;
+const providerWebhookPathPattern = /^\/api\/v1\/webhooks\/\{product_code\}\/(airwallex|apple|google|payermax|paypal|payssion|stripe|wechatpay)\/$/;
+
+export async function readStructured(path) {
+  const source = await readFile(path, 'utf8');
+  return path.endsWith('.json') ? JSON.parse(source) : YAML.parse(source);
+}
+
+export async function readRegistry(root = apiRoot) {
+  const registry = await readStructured(resolve(root, 'service-registry.json'));
+  validateRegistry(registry);
+  return registry;
+}
+
+export function validateRegistry(registry) {
+  if (registry?.schema_version !== 1 || !Array.isArray(registry.services) || registry.services.length === 0) {
+    throw new Error('service registry must declare schema_version 1 and at least one service');
+  }
+  const seen = new Set();
+  const ids = registry.services.map((service) => service.id);
+  if (ids.join('\n') !== [...ids].sort().join('\n')) {
+    throw new Error('service registry entries must be sorted by id');
+  }
+  for (const service of registry.services) {
+    if (!/^[a-z][a-z0-9-]*$/.test(service.id) || seen.has(service.id)) {
+      throw new Error(`invalid or duplicate service id: ${service.id}`);
+    }
+    seen.add(service.id);
+    if (!service.display_name || !isSafeRelativePath(service.source) || !isSafeRelativePath(service.runtime_conformance)) {
+      throw new Error(`service ${service.id} must declare display_name, source, and runtime_conformance`);
+    }
+    if (!documentationLocales.includes(service.documentation_locale)) {
+      throw new Error(`service ${service.id} has unsupported documentation_locale: ${service.documentation_locale}`);
+    }
+    if (!hasHanText(service.display_name)) {
+      throw new Error(`service ${service.id} display_name must use Chinese documentation copy`);
+    }
+    if (!Array.isArray(service.publications) || service.publications[0] !== 'internal') {
+      throw new Error(`service ${service.id} publications must start with internal`);
+    }
+    const uniquePublications = new Set(service.publications);
+    if (uniquePublications.size !== service.publications.length || service.publications.some((value) => !audiences.includes(value))) {
+      throw new Error(`service ${service.id} has invalid publications`);
+    }
+    for (const exclusion of service.route_exclusions ?? []) {
+      if (!exclusion.startsWith('/') || /^\/(api|admin|internal)(\/|$)/.test(exclusion)) {
+        throw new Error(`service ${service.id} has forbidden route exclusion: ${exclusion}`);
+      }
+    }
+    if ((service.route_exclusions ?? []).join('\n') !== [...(service.route_exclusions ?? [])].sort().join('\n')) {
+      throw new Error(`service ${service.id} route exclusions must be sorted`);
+    }
+    const delegatedIds = (service.delegated_contracts ?? []).map((delegated) => delegated.id);
+    if (new Set(delegatedIds).size !== delegatedIds.length || delegatedIds.join('\n') !== [...delegatedIds].sort().join('\n')) {
+      throw new Error(`service ${service.id} delegated contracts must have unique sorted ids`);
+    }
+    for (const delegated of service.delegated_contracts ?? []) {
+      validateDelegatedRegistryEntry(service.id, delegated);
+    }
+  }
+}
+
+export function operationEntries(document) {
+  const entries = [];
+  for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
+    for (const method of httpMethods) {
+      if (pathItem?.[method]) {
+        entries.push({ method, operation: pathItem[method], path, pathItem });
+      }
+    }
+  }
+  return entries.sort((left, right) => compareUTF8Bytes(`${left.path}\0${left.method}`, `${right.path}\0${right.method}`));
+}
+
+function compareUTF8Bytes(left, right) {
+  return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}
+
+export function validateDocument(document, {
+  audience = 'internal',
+  documentationLocale = document?.['x-onex-documentation-locale'],
+  requireMetadata = true,
+  service,
+}) {
+  const errors = [];
+  if (document?.openapi !== '3.1.1') errors.push('openapi must be 3.1.1');
+  if (document?.jsonSchemaDialect !== 'https://json-schema.org/draft/2020-12/schema') {
+    errors.push('jsonSchemaDialect must be JSON Schema 2020-12');
+  }
+  if (!document?.info?.title || !isSemanticVersion(document?.info?.version)) {
+    errors.push('info.title and a SemVer info.version are required');
+  }
+  const entries = operationEntries(document);
+  if (entries.length === 0) errors.push('at least one operation is required');
+  for (const path of Object.keys(document.paths ?? {})) {
+    if (path.endsWith('/') && !providerWebhookPathPattern.test(path)) {
+      errors.push(`${path} has a trailing slash outside the provider webhook contract`);
+    }
+  }
+  const operationIds = new Set();
+  for (const { method, operation, path } of entries) {
+    const label = `${method.toUpperCase()} ${path}`;
+    if (!/^[a-z][A-Za-z0-9]*$/.test(operation.operationId ?? '')) errors.push(`${label} has invalid operationId`);
+    if (operationIds.has(operation.operationId)) errors.push(`${label} duplicates operationId ${operation.operationId}`);
+    operationIds.add(operation.operationId);
+    if (!operation.summary?.trim()) errors.push(`${label} has no summary`);
+    if (!Array.isArray(operation.tags) || operation.tags.length === 0) errors.push(`${label} has no tags`);
+    if (!Object.hasOwn(operation, 'security') || !Array.isArray(operation.security)) errors.push(`${label} has no explicit security`);
+    if (!operation.responses || Object.keys(operation.responses).length === 0) errors.push(`${label} has no responses`);
+    if (requireMetadata && !audiences.includes(operation['x-onex-audience'])) errors.push(`${label} has invalid x-onex-audience`);
+    if (requireMetadata && !operation['x-onex-owner']?.trim()) errors.push(`${label} has no x-onex-owner`);
+    if (!stabilities.includes(operation['x-onex-stability'])) errors.push(`${label} has invalid x-onex-stability`);
+    if (requireMetadata && operation['x-onex-audience'] !== 'internal' && !validLifecycle(operation['x-onex-lifecycle'])) {
+      errors.push(`${label} has invalid x-onex-lifecycle`);
+    }
+    if (audience !== 'internal' && pathLeaksInternalSurface(path)) errors.push(`${label} leaks an internal path`);
+  }
+  visit(document, (value, key, path, parent) => {
+    if (key === 'nullable') errors.push(`${path} uses forbidden nullable keyword`);
+    if (
+      key === 'name' &&
+      typeof value === 'string' &&
+      value.toLowerCase() === 'idempotency-key' &&
+      parent?.in === 'header'
+    ) {
+      errors.push(`${path} uses the provider idempotency header instead of X-Idempotency-Key`);
+    }
+    if ((key === '$ref' || key === '$dynamicRef') && typeof value === 'string' && !value.startsWith('#/')) {
+      errors.push(`${path} contains a remote or unresolved reference: ${value}`);
+    }
+    if (key === 'additionalProperties' && value === true && audience !== 'internal') {
+      errors.push(`${path} exposes an unconstrained object`);
+    }
+  });
+  if (documentationLocale !== undefined) validateDocumentation(document, documentationLocale, entries, errors);
+  if (audience !== 'internal') {
+    for (const server of document.servers ?? []) {
+      if (privateServerPattern.test(server.url ?? '')) errors.push(`external artifact contains private server ${server.url}`);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(`${service ?? document?.info?.title ?? 'OpenAPI document'} validation failed:\n- ${errors.join('\n- ')}`);
+  }
+  return { operationCount: entries.length, pathCount: Object.keys(document.paths ?? {}).length };
+}
+
+export function projectDocument(source, audience) {
+  if (!audiences.includes(audience)) throw new Error(`unknown audience: ${audience}`);
+  const projected = structuredClone(source);
+  projected.paths = selectPaths(source, (operation) => includesAudience(operation['x-onex-audience'], audience));
+  projectSecurityRequirements(source, projected, audience);
+
+  projected.components = collectReachableComponents(source, projected, audience);
+  projectDocumentationNavigation(source, projected);
+  validateDocument(projected, { audience, service: source.info?.title });
+  if (audience !== 'internal') {
+    projected.servers = (source.servers ?? []).filter((server) => !privateServerPattern.test(server.url ?? ''));
+    stripInternalMetadata(projected);
+  }
+  validateLinkTargets(projected);
+  return projected;
+}
+
+export function projectOperationSet(source, operationIds) {
+  const selected = new Set(operationIds);
+  if (selected.size === 0) throw new Error('operation projection requires at least one operationId');
+  const projected = structuredClone(source);
+  projected.paths = selectPaths(source, (operation) => selected.has(operation.operationId));
+  const found = new Set(operationEntries(projected).map(({ operation }) => operation.operationId));
+  const missing = [...selected].filter((operationId) => !found.has(operationId));
+  if (missing.length > 0) throw new Error(`operation projection contains unknown operationIds: ${missing.sort().join(', ')}`);
+  projected.components = collectReachableComponents(source, projected, 'internal');
+  projectDocumentationNavigation(source, projected);
+  validateDocument(projected, { audience: 'internal', service: `${source.info?.title} operation projection` });
+  validateLinkTargets(projected);
+  return projected;
+}
+
+export function canonicalJSON(value) {
+  return `${JSON.stringify(sortObjectKeys(value), null, 2)}\n`;
+}
+
+export function sha256(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function countComponents(document) {
+  return Object.values(document.components ?? {}).reduce((total, group) => total + Object.keys(group ?? {}).length, 0);
+}
+
+export function isSafeRelativePath(path) {
+  return typeof path === 'string' && path.length > 0 && !path.startsWith('/') && !path.split('/').includes('..');
+}
+
+function validateDelegatedRegistryEntry(serviceId, delegated) {
+  if (!/^[a-z][a-z0-9-]*$/.test(delegated.id ?? '')) throw new Error(`service ${serviceId} has invalid delegated id`);
+  for (const field of ['artifact', 'overlay', 'provenance']) {
+    if (!isSafeRelativePath(delegated[field])) throw new Error(`service ${serviceId} delegated ${delegated.id} has invalid ${field}`);
+  }
+  if (
+    !delegated.mount_prefix?.startsWith('/') ||
+    delegated.mount_prefix.endsWith('/') ||
+    delegated.mount_prefix.includes('*') ||
+    !Number.isInteger(delegated.expected_operation_count) ||
+    delegated.expected_operation_count < 1
+  ) {
+    throw new Error(`service ${serviceId} delegated ${delegated.id} has invalid mount or operation count`);
+  }
+  if (
+    !Array.isArray(delegated.methods) ||
+    delegated.methods.length === 0 ||
+    new Set(delegated.methods).size !== delegated.methods.length ||
+    delegated.methods.join('\n') !== [...delegated.methods].sort().join('\n') ||
+    delegated.methods.some((method) => method !== method.toUpperCase() || !httpMethods.includes(method.toLowerCase()))
+  ) {
+    throw new Error(`service ${serviceId} delegated ${delegated.id} has invalid methods`);
+  }
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(delegated.security_scheme ?? '')) {
+    throw new Error(`service ${serviceId} delegated ${delegated.id} has invalid security_scheme`);
+  }
+  if (typeof delegated.navigation_group !== 'string' || !hasHanText(delegated.navigation_group)) {
+    throw new Error(`service ${serviceId} delegated ${delegated.id} has invalid navigation_group`);
+  }
+  const prefixes = delegated.source_path_prefixes_to_strip;
+  if (
+    !Array.isArray(prefixes) ||
+    prefixes.length === 0 ||
+    new Set(prefixes).size !== prefixes.length ||
+    prefixes.some((prefix) => !prefix.startsWith('/') || prefix.endsWith('/') || prefix.includes('*'))
+  ) {
+    throw new Error(`service ${serviceId} delegated ${delegated.id} has invalid source path prefixes`);
+  }
+  if (delegated.csrf_protection !== undefined) {
+    const csrf = delegated.csrf_protection;
+    if (
+      csrf?.header_name !== 'X-CSRF-Token' ||
+      !Array.isArray(csrf.methods) ||
+      csrf.methods.length === 0 ||
+      new Set(csrf.methods).size !== csrf.methods.length ||
+      csrf.methods.join('\n') !== [...csrf.methods].sort().join('\n') ||
+      csrf.methods.some((method) => !delegated.methods.includes(method) || ['GET', 'HEAD', 'OPTIONS'].includes(method))
+    ) {
+      throw new Error(`service ${serviceId} delegated ${delegated.id} has invalid CSRF protection`);
+    }
+  }
+}
+
+function includesAudience(sourceAudience, targetAudience) {
+  return audiences.indexOf(sourceAudience) >= audiences.indexOf(targetAudience);
+}
+
+function projectDocumentationNavigation(source, projected) {
+  const usedTags = new Set(operationEntries(projected).flatMap(({ operation }) => operation.tags ?? []));
+  projected.tags = (source.tags ?? [...usedTags].map((name) => ({ name }))).filter((tag) => usedTags.has(tag.name));
+  if (Array.isArray(source['x-tagGroups'])) {
+    projected['x-tagGroups'] = source['x-tagGroups']
+      .map((group) => ({ ...structuredClone(group), tags: group.tags.filter((tag) => usedTags.has(tag)) }))
+      .filter((group) => group.tags.length > 0);
+  }
+}
+
+function validateDocumentation(document, locale, entries, errors) {
+  if (!documentationLocales.includes(locale)) {
+    errors.push(`unsupported documentation locale: ${locale}`);
+    return;
+  }
+  if (document['x-onex-documentation-locale'] !== locale) {
+    errors.push(`x-onex-documentation-locale must equal ${locale}`);
+  }
+
+  const declaredTags = [];
+  const declaredTagSet = new Set();
+  if (!Array.isArray(document.tags) || document.tags.length === 0) {
+    errors.push('localized documentation must declare ordered top-level tags');
+  } else {
+    for (const [index, tag] of document.tags.entries()) {
+      const name = tag?.name?.trim();
+      if (!name || !hasHanText(name)) errors.push(`tags[${index}].name must use Chinese documentation copy`);
+      if (declaredTagSet.has(name)) errors.push(`tags[${index}].name duplicates ${name}`);
+      declaredTags.push(name);
+      declaredTagSet.add(name);
+    }
+  }
+
+  const groupedTags = [];
+  const groupNames = new Set();
+  const groups = document['x-tagGroups'];
+  if (!Array.isArray(groups) || groups.length === 0) {
+    errors.push('localized documentation must declare x-tagGroups');
+  } else {
+    for (const [index, group] of groups.entries()) {
+      const name = group?.name?.trim();
+      if (!name || !hasHanText(name)) errors.push(`x-tagGroups[${index}].name must use Chinese documentation copy`);
+      if (groupNames.has(name)) errors.push(`x-tagGroups[${index}].name duplicates ${name}`);
+      groupNames.add(name);
+      if (!Array.isArray(group?.tags) || group.tags.length === 0) {
+        errors.push(`x-tagGroups[${index}] must contain at least one tag`);
+        continue;
+      }
+      groupedTags.push(...group.tags);
+    }
+  }
+  if (groupedTags.join('\n') !== declaredTags.join('\n')) {
+    errors.push('x-tagGroups must contain every declared tag exactly once and preserve top-level tag order');
+  }
+
+  for (const { method, operation, path } of entries) {
+    const label = `${method.toUpperCase()} ${path}`;
+    if (operation.tags?.length !== 1) errors.push(`${label} must declare exactly one navigation tag`);
+    for (const tag of operation.tags ?? []) {
+      if (!declaredTagSet.has(tag)) errors.push(`${label} uses undeclared tag ${tag}`);
+    }
+  }
+
+  const invalidText = [];
+  const leakedImplementationNames = [];
+  visit(document, (value, key, path) => {
+    if (typeof value === 'string' && ['description', 'summary', 'title'].includes(key) && !isExamplePayloadPath(path) && !hasHanText(value)) {
+      invalidText.push(`${path}=${JSON.stringify(value)}`);
+    }
+    if (key === 'summary' && typeof value === 'string' && !isExamplePayloadPath(path) && hasLegacyImplementationPrefix(value)) {
+      leakedImplementationNames.push(`${path}=${JSON.stringify(value)}`);
+    }
+  });
+  for (const [path, value] of [
+    ['$.info.contact.name', document.info?.contact?.name],
+    ['$.info.license.name', document.info?.license?.name],
+  ]) {
+    if (typeof value === 'string' && !hasHanText(value)) invalidText.push(`${path}=${JSON.stringify(value)}`);
+  }
+  const limit = 100;
+  errors.push(...invalidText.slice(0, limit).map((entry) => `documentation text must use Chinese copy: ${entry}`));
+  if (invalidText.length > limit) errors.push(`documentation text has ${invalidText.length - limit} additional non-Chinese values`);
+  errors.push(...leakedImplementationNames.slice(0, limit).map((entry) => `operation summary must not expose a handler or English action prefix: ${entry}`));
+  if (leakedImplementationNames.length > limit) {
+    errors.push(`operation summaries have ${leakedImplementationNames.length - limit} additional implementation-name leaks`);
+  }
+}
+
+function isExamplePayloadPath(path) {
+  return /\.example(?:\.|\[)/.test(path) || /\.examples\.[^.]+\.value(?:\.|\[)/.test(path) || /\.components\.examples\.[^.]+\.value(?:\.|\[)/.test(path);
+}
+
+function hasHanText(value) {
+  return typeof value === 'string' && /\p{Script=Han}/u.test(value);
+}
+
+function hasLegacyImplementationPrefix(value) {
+  const match = /^([A-Z][A-Za-z0-9]+)\s+(.+)$/u.exec(value.trim());
+  return Boolean(match && hasHanText(match[2]) && !approvedDocumentationLeadingTerms.has(match[1]));
+}
+
+function selectPaths(source, predicate) {
+  const paths = {};
+  for (const [path, sourcePathItem] of Object.entries(source.paths ?? {})) {
+    const pathItem = {};
+    for (const key of ['$ref', 'description', 'parameters', 'servers', 'summary']) {
+      if (Object.hasOwn(sourcePathItem, key)) pathItem[key] = structuredClone(sourcePathItem[key]);
+    }
+    for (const method of httpMethods) {
+      const operation = sourcePathItem[method];
+      if (operation && predicate(operation)) pathItem[method] = structuredClone(operation);
+    }
+    if (httpMethods.some((method) => pathItem[method])) paths[path] = pathItem;
+  }
+  return paths;
+}
+
+function projectSecurityRequirements(source, projected, audience) {
+  for (const { method, operation, path } of operationEntries(projected)) {
+    if (!Array.isArray(operation.security) || operation.security.length === 0) continue;
+    const security = operation.security.filter((requirement) => {
+      const schemeNames = Object.keys(requirement);
+      if (schemeNames.length === 0) return true;
+      return schemeNames.every((schemeName) => {
+        const scheme = source.components?.securitySchemes?.[schemeName];
+        if (!scheme) return true;
+        return includesAudience(scheme['x-onex-audience'] ?? 'internal', audience);
+      });
+    });
+    if (security.length === 0) {
+      throw new Error(`${method.toUpperCase()} ${path} has no security alternative available in ${audience} projection`);
+    }
+    operation.security = security;
+  }
+}
+
+function collectReachableComponents(source, projected, audience) {
+  const result = Object.fromEntries(componentKinds.map((kind) => [kind, {}]));
+  const queue = [];
+  const requiredStability = new Map();
+  for (const { operation } of operationEntries(projected)) {
+    enqueueReferences(operation, operation['x-onex-stability']);
+    for (const requirement of operation.security) {
+      for (const name of Object.keys(requirement)) queue.push({ kind: 'securitySchemes', name, stability: operation['x-onex-stability'] });
+    }
+  }
+  for (const pathItem of Object.values(projected.paths)) enqueueReferences(pathItem, 'experimental');
+
+  while (queue.length > 0) {
+    const { kind, name, stability } = queue.shift();
+    const identity = `${kind}/${name}`;
+    const previous = requiredStability.get(identity);
+    if (previous && stabilities.indexOf(previous) >= stabilities.indexOf(stability)) continue;
+    const component = source.components?.[kind]?.[name];
+    if (!component) throw new Error(`unresolved component reference: #/components/${kind}/${name}`);
+    if (audience !== 'internal') {
+      const componentAudience = component['x-onex-audience'] ?? 'internal';
+      const componentStability = component['x-onex-stability'];
+      if (!includesAudience(componentAudience, audience)) {
+        throw new Error(`component ${identity} cannot enter ${audience} projection`);
+      }
+      if (!stabilities.includes(componentStability) || stabilities.indexOf(componentStability) < stabilities.indexOf(stability)) {
+        throw new Error(`component ${identity} stability is lower than its consumer`);
+      }
+    }
+    requiredStability.set(identity, stability);
+    result[kind][name] = structuredClone(component);
+    enqueueReferences(component, stability);
+  }
+
+  for (const kind of componentKinds) if (Object.keys(result[kind]).length === 0) delete result[kind];
+  return result;
+
+  function enqueueReferences(node, stability) {
+    visit(node, (value, key) => {
+      if ((key === '$ref' || key === '$dynamicRef') && typeof value === 'string') {
+        const parsed = parseComponentReference(value);
+        if (parsed) queue.push({ ...parsed, stability });
+      }
+      if (key === 'mapping' && isPlainObject(value)) {
+        for (const reference of Object.values(value)) {
+          const parsed = parseComponentReference(reference);
+          if (parsed) queue.push({ ...parsed, stability });
+        }
+      }
+    });
+  }
+}
+
+function parseComponentReference(reference) {
+  const match = /^#\/components\/([^/]+)\/(.+)$/.exec(reference ?? '');
+  if (!match) return null;
+  const kind = decodePointer(match[1]);
+  if (!componentKinds.includes(kind)) throw new Error(`unsupported component kind in reference: ${reference}`);
+  return { kind, name: decodePointer(match[2]) };
+}
+
+function validateLinkTargets(document) {
+  const operationIds = new Set(operationEntries(document).map(({ operation }) => operation.operationId));
+  visit(document, (value, key, path, parent) => {
+    if (key === 'operationId' && !parent.responses && !operationIds.has(value)) {
+      throw new Error(`${path} targets operationId outside the projection: ${value}`);
+    }
+    if (key === 'operationRef' && typeof value === 'string' && value.startsWith('#/paths/')) {
+      const parts = value.split('/');
+      const targetPath = decodePointer(parts[2] ?? '');
+      const targetMethod = parts[3];
+      if (!document.paths?.[targetPath]?.[targetMethod]) throw new Error(`${path} targets operation outside the projection: ${value}`);
+    }
+  });
+}
+
+function stripInternalMetadata(value) {
+  if (Array.isArray(value)) {
+    for (const item of value) stripInternalMetadata(item);
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const key of Object.keys(value)) {
+    if (internalMetadata.has(key)) delete value[key];
+    else stripInternalMetadata(value[key]);
+  }
+}
+
+function pathLeaksInternalSurface(path) {
+  return /^\/(admin|internal)(\/|$)/.test(path) || /^\/api\/v\d+\/(admin|internal)(\/|$)/.test(path);
+}
+
+function validLifecycle(lifecycle) {
+  return lifecycle !== null && typeof lifecycle === 'object' && /^\d{4}-\d{2}-\d{2}$/.test(lifecycle.introduced ?? '') &&
+    Object.hasOwn(lifecycle, 'deprecated') && Object.hasOwn(lifecycle, 'sunset') &&
+    Object.hasOwn(lifecycle, 'replacementOperationId') && Object.hasOwn(lifecycle, 'migrationUrl');
+}
+
+function sortObjectKeys(value) {
+  if (Array.isArray(value)) return value.map(sortObjectKeys);
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortObjectKeys(value[key])]));
+}
+
+function visit(value, callback, path = '$', parent = null) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => {
+      callback(item, String(index), `${path}[${index}]`, value);
+      visit(item, callback, `${path}[${index}]`, value);
+    });
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${path}.${key}`;
+    callback(child, key, childPath, value);
+    visit(child, callback, childPath, value);
+  }
+}
+
+function decodePointer(value) {
+  return value.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+export function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}