@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,498 @@
+import { canonicalJSON, isPlainObject, operationEntries, sha256 } from './project.mjs';
+import {
+  isEmailExampleKey,
+  isSensitiveExampleKey,
+  safeSHA256ExampleValue,
+  safeSensitiveExampleValue,
+} from './documentation_example_privacy.mjs';
+
+export const documentationProjectionVersion = '1.0.0';
+
+const locationNames = Object.freeze({
+  cookie: 'Cookie',
+  header: '请求头',
+  path: '路径',
+  query: '查询',
+});
+
+export function applyDocumentationProjection(document, { audience, service, sourceSha256 }) {
+  const projected = structuredClone(document);
+  const operationPointers = new Map(
+    operationEntries(projected).map(({ method, operation, path }) => [operation.operationId, `#/paths/${escapePointer(path)}/${method}`]),
+  );
+
+  for (const { method, operation, path, pathItem } of operationEntries(projected)) {
+    const operationPointer = `#/paths/${escapePointer(path)}/${method}`;
+    const operationProvenance = provenance(operationPointer, sourceSha256, hasText(operation.description) ? 'authored' : 'generated');
+    operation['x-onex-documentation-provenance'] ??= operationProvenance;
+    if (!hasText(operation.description)) {
+      operation.description = operation.summary.trim();
+      operation['x-onex-documentation-provenance'] = operationProvenance;
+    }
+
+    const parameters = [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])];
+    for (const [index, parameterReference] of parameters.entries()) {
+      const parameter = resolveReference(projected, parameterReference);
+      if (!parameter) continue;
+      const parameterPointer = `${operationPointer}/parameters/${index}`;
+      if (!hasText(parameter.description)) {
+        const location = locationNames[parameter.in] ?? '请求';
+        parameter.description = `${operation.summary.trim()}使用的${location}参数 ${parameter.name}。`;
+        parameter['x-onex-documentation-provenance'] = provenance(parameterPointer, sourceSha256, 'generated');
+      }
+    }
+
+    const requestBody = resolveReference(projected, operation.requestBody);
+    if (requestBody) {
+      const requestPointer = `${operationPointer}/requestBody`;
+      if (!hasText(requestBody.description)) {
+        requestBody.description = `${operation.summary.trim()}的请求数据。`;
+        requestBody['x-onex-documentation-provenance'] = provenance(requestPointer, sourceSha256, 'generated');
+      }
+      projectMediaExamples(projected, requestBody.content, requestPointer, sourceSha256, 'request');
+    }
+
+    for (const [status, responseReference] of Object.entries(operation.responses ?? {})) {
+      const response = resolveReference(projected, responseReference);
+      if (!response) continue;
+      const responsePointer = `${operationPointer}/responses/${escapePointer(status)}`;
+      if (!hasText(response.description)) {
+        response.description = responseDescription(status);
+        response['x-onex-documentation-provenance'] = provenance(responsePointer, sourceSha256, 'generated');
+      }
+      projectMediaExamples(projected, response.content, responsePointer, sourceSha256, 'response');
+    }
+  }
+
+  for (const [schemaName, schema] of Object.entries(projected.components?.schemas ?? {})) {
+    projectSchemaDescriptions(schema, `#/components/schemas/${escapePointer(schemaName)}`, sourceSha256, new Set());
+  }
+
+  projected['x-onex-publication'] = {
+    audience,
+    documentation_projection_version: documentationProjectionVersion,
+    service,
+    source_sha256: sourceSha256,
+  };
+  validateLinkProvenance(projected, operationPointers);
+  return projected;
+}
+
+export function resolveReference(document, value) {
+  if (!value || typeof value !== 'object') return null;
+  if (!value.$ref) return value;
+  if (!value.$ref.startsWith('#/')) throw new Error(`external reference is not supported: ${value.$ref}`);
+  let current = document;
+  for (const token of value.$ref.slice(2).split('/').map(unescapePointer)) {
+    current = current?.[token];
+  }
+  if (!current || typeof current !== 'object') throw new Error(`unresolved reference: ${value.$ref}`);
+  return current;
+}
+
+function projectMediaExamples(document, content, sourcePointer, sourceSha256, mode) {
+  for (const [mediaType, media] of Object.entries(content ?? {})) {
+    if (!media?.schema) continue;
+    const schemaPointer = `${sourcePointer}/content/${escapePointer(mediaType)}/schema`;
+    const generated = generateSchemaExample(document, media.schema, { mode, name: 'value' });
+    const exampleProvenance = {
+      generator: `onex-schema-example/${documentationProjectionVersion}`,
+      schema_pointer: schemaPointer,
+      schema_sha256: sha256(canonicalJSON(media.schema)),
+      source_sha256: sourceSha256,
+    };
+    if (media.examples && Object.keys(media.examples).length > 0) {
+      for (const [name, exampleReference] of Object.entries(media.examples)) {
+        const example = resolveReference(document, exampleReference);
+        if (!example) continue;
+        if (Object.hasOwn(example, 'value')) example.value = sanitizeValue(example.value, 'value');
+        example['x-onex-example-provenance'] ??= { ...exampleProvenance, source: `named-example:${name}` };
+      }
+      continue;
+    }
+    const value = Object.hasOwn(media, 'example') ? sanitizeValue(media.example, 'value') : generated;
+    delete media.example;
+    media.examples = {
+      deterministic: {
+        summary: '根据契约生成的脱敏示例',
+        value,
+        'x-onex-example-provenance': { ...exampleProvenance, source: 'schema' },
+      },
+    };
+  }
+}
+
+function projectSchemaDescriptions(schema, pointer, sourceSha256, visited) {
+  if (!isPlainObject(schema) || visited.has(schema)) return;
+  visited.add(schema);
+  for (const [propertyName, property] of Object.entries(schema.properties ?? {})) {
+    if (!isPlainObject(property)) continue;
+    const propertyPointer = `${pointer}/properties/${escapePointer(propertyName)}`;
+    if (!hasText(property.description)) {
+      property.description = `字段 ${propertyName} 的结构化值。`;
+      property['x-onex-documentation-provenance'] = provenance(propertyPointer, sourceSha256, 'generated');
+    }
+    projectSchemaDescriptions(property, propertyPointer, sourceSha256, visited);
+  }
+  if (schema.items) projectSchemaDescriptions(schema.items, `${pointer}/items`, sourceSha256, visited);
+  for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+    for (const [index, child] of (schema[keyword] ?? []).entries()) {
+      projectSchemaDescriptions(child, `${pointer}/${keyword}/${index}`, sourceSha256, visited);
+    }
+  }
+  visited.delete(schema);
+}
+
+function generateSchemaExample(document, schemaReference, context, seen = new Set(), depth = 0) {
+  const schema = resolveReference(document, schemaReference);
+  if (!schema) return null;
+  if (depth > 12) return nullable(schema) ? null : fallbackForType(schema);
+  const identity = schemaReference.$ref ?? schema;
+  if (seen.has(identity)) return nullable(schema) ? null : fallbackForType(schema);
+  const nextSeen = new Set(seen).add(identity);
+
+  if (Object.hasOwn(schema, 'const')) return sanitizeValue(schema.const, context.name, schema, { preserve: true });
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) return sanitizeValue(schema.enum[0], context.name, schema, { preserve: true });
+  if (Object.hasOwn(schema, 'default')) return sanitizeValue(schema.default, context.name, schema);
+  if (Object.hasOwn(schema, 'example')) return sanitizeValue(schema.example, context.name, schema);
+
+  if (Array.isArray(schema.allOf)) {
+    const mergedObject = mergeAllOfObjectSchema(document, schema);
+    if (mergedObject) return generateSchemaExample(document, mergedObject, context, nextSeen, depth + 1);
+    const values = schema.allOf.map((entry) => generateSchemaExample(document, entry, context, nextSeen, depth + 1));
+    if (values.every(isPlainObject)) return Object.assign({}, ...values);
+    return values.find((value) => value !== null) ?? null;
+  }
+  for (const keyword of ['oneOf', 'anyOf']) {
+    if (Array.isArray(schema[keyword]) && schema[keyword].length > 0) {
+      const selected = schema[keyword].find((entry) => !nullable(entry)) ?? schema[keyword][0];
+      const composedObject = mergeVariantObjectSchema(document, schema, keyword, selected);
+      if (composedObject) return generateSchemaExample(document, composedObject, context, nextSeen, depth + 1);
+      return generateSchemaExample(document, selected, context, nextSeen, depth + 1);
+    }
+  }
+
+  const type = schemaType(schema);
+  if (type === 'object') {
+    const properties = Object.entries(schema.properties ?? {}).sort(([left], [right]) => left.localeCompare(right));
+    const required = new Set(schema.required ?? []);
+    const eligible = properties.filter(([, property]) => context.mode === 'request' ? property.readOnly !== true : property.writeOnly !== true);
+    const selected = eligible.filter(([name]) => required.has(name));
+    for (const entry of eligible) {
+      if (selected.length >= Math.max(required.size, 6)) break;
+      if (!selected.includes(entry)) selected.push(entry);
+    }
+    const selectedNames = new Set(selected.map(([name]) => name));
+    for (let index = 0; index < selected.length; index += 1) {
+      const [name] = selected[index];
+      for (const dependencyName of schema.dependentRequired?.[name] ?? []) {
+        if (selectedNames.has(dependencyName)) continue;
+        const dependency = eligible.find(([candidate]) => candidate === dependencyName);
+        if (!dependency) {
+          throw new Error(`schema example cannot satisfy dependentRequired ${name} -> ${dependencyName}`);
+        }
+        selected.push(dependency);
+        selectedNames.add(dependencyName);
+      }
+    }
+    const value = Object.fromEntries(selected.map(([name, property]) => [
+      name,
+      generateSchemaExample(document, property, { ...context, name }, nextSeen, depth + 1),
+    ]));
+    const missingPropertyCount = Math.max((schema.minProperties ?? 0) - Object.keys(value).length, 0);
+    if (missingPropertyCount > 0 && schema.additionalProperties !== false) {
+      Object.assign(value, ...generateAdditionalPropertyEntries(
+        document,
+        schema.additionalProperties,
+        context,
+        nextSeen,
+        depth,
+        new Set(Object.keys(value)),
+        missingPropertyCount,
+      ));
+    }
+    return value;
+  }
+  if (type === 'array') {
+    const minimum = Math.max(schema.minItems ?? (depth === 0 ? 1 : 0), 0);
+    const count = Math.min(minimum, schema.maxItems ?? minimum, 3);
+    return Array.from({ length: count }, () => generateSchemaExample(document, schema.items ?? {}, context, nextSeen, depth + 1));
+  }
+  if (type === 'integer' || type === 'number') return numericExample(schema, type === 'integer');
+  if (type === 'boolean') return true;
+  if (type === 'null') return null;
+  return stringExample(context.name, schema);
+}
+
+function mergeAllOfObjectSchema(document, schema) {
+  const branches = flattenAllOfSchemas(document, schema);
+  if (branches.length === 0 || !branches.some(hasObjectConstraint)) return null;
+  if (branches.some((branch) => branch.type && schemaType(branch) !== 'object')) return null;
+
+  const properties = {};
+  const required = new Set();
+  let additionalProperties;
+  let minProperties = 0;
+  let maxProperties;
+  for (const branch of branches) {
+    Object.assign(properties, branch.properties ?? {});
+    for (const propertyName of branch.required ?? []) required.add(propertyName);
+    if (branch.additionalProperties === false) additionalProperties = false;
+    else if (additionalProperties === undefined && Object.hasOwn(branch, 'additionalProperties')) {
+      additionalProperties = branch.additionalProperties;
+    }
+    minProperties = Math.max(minProperties, branch.minProperties ?? 0);
+    if (Number.isInteger(branch.maxProperties)) {
+      maxProperties = maxProperties === undefined ? branch.maxProperties : Math.min(maxProperties, branch.maxProperties);
+    }
+  }
+
+  const merged = { properties, required: [...required].sort(), type: 'object' };
+  if (additionalProperties !== undefined) merged.additionalProperties = additionalProperties;
+  if (minProperties > 0) merged.minProperties = minProperties;
+  if (maxProperties !== undefined) merged.maxProperties = maxProperties;
+  return merged;
+}
+
+function mergeVariantObjectSchema(document, schema, keyword, selected) {
+  const parent = { ...schema };
+  delete parent[keyword];
+  return mergeAllOfObjectSchema(document, { allOf: [parent, selected] });
+}
+
+function flattenAllOfSchemas(document, schema, visited = new Set()) {
+  const resolved = resolveReference(document, schema);
+  if (!resolved || visited.has(resolved)) return [];
+  const nextVisited = new Set(visited).add(resolved);
+  const own = { ...resolved };
+  delete own.$ref;
+  delete own.allOf;
+  const branches = hasObjectConstraint(own) ? [own] : [];
+  for (const child of resolved.allOf ?? []) {
+    branches.push(...flattenAllOfSchemas(document, child, nextVisited));
+  }
+  return branches;
+}
+
+function hasObjectConstraint(schema) {
+  return schema.type === 'object' || Object.hasOwn(schema, 'properties') ||
+    Object.hasOwn(schema, 'required') || Object.hasOwn(schema, 'additionalProperties') ||
+    Object.hasOwn(schema, 'minProperties') || Object.hasOwn(schema, 'maxProperties');
+}
+
+function generateAdditionalPropertyEntries(document, additionalProperties, context, seen, depth, occupiedNames, count) {
+  const propertySchema = isPlainObject(additionalProperties) ? additionalProperties : {};
+  const entries = [];
+  let sequence = 1;
+  while (entries.length < count) {
+    const name = sequence === 1 ? 'example_key' : `example_key_${sequence}`;
+    sequence += 1;
+    if (occupiedNames.has(name)) continue;
+    occupiedNames.add(name);
+    entries.push({
+      [name]: generateSchemaExample(document, propertySchema, { ...context, name }, seen, depth + 1),
+    });
+  }
+  return entries;
+}
+
+function stringExample(name, schema) {
+  const normalized = name.toLowerCase();
+  let value;
+  const sensitiveValue = isSensitiveExampleKey(name) ? safeSensitiveExampleValue(schema) : null;
+  const patternValue = stringPatternExample(schema.pattern, schema);
+  if (sensitiveValue !== null) value = sensitiveValue;
+  else if (isSensitiveExampleKey(name)) throw new Error(`sensitive schema cannot produce a safe example: ${name}`);
+  else if (patternValue !== null) value = patternValue;
+  else if (schema.format === 'date-time') value = '2026-01-01T00:00:00Z';
+  else if (schema.format === 'date') value = '2026-01-01';
+  else if (schema.format === 'uuid') value = '00000000-0000-4000-8000-000000000000';
+  else if (schema.format === 'email' || isEmailExampleKey(name)) value = 'user@example.com';
+  else if (schema.format === 'uri' || /(url|uri|link)$/.test(normalized)) value = 'https://api.example.com/resource';
+  else if (isIPKey(normalized)) value = '192.0.2.1';
+  else if (/(host|domain)/.test(normalized)) value = 'api.example.com';
+  else if (/(phone|mobile)/.test(normalized)) value = '+12025550123';
+  else if (normalized.includes('locale') || normalized.includes('language')) value = 'zh-CN';
+  else if (normalized.includes('currency')) value = 'USD';
+  else if (normalized.includes('country')) value = 'US';
+  else if (normalized === 'product_code') value = 'example_product';
+  else if (/(^|_)(id|no|key)$/.test(normalized)) value = 'example-id';
+  else value = 'example';
+  const minimum = schema.minLength ?? 0;
+  while (value.length < minimum) value += 'x';
+  if (Number.isInteger(schema.maxLength) && value.length > schema.maxLength) value = value.slice(0, schema.maxLength);
+  return value;
+}
+
+function stringPatternExample(pattern, schema) {
+  if (typeof pattern !== 'string') return null;
+  const sha256Value = safeSHA256ExampleValue(schema);
+  if (sha256Value !== null) return sha256Value;
+  if (pattern === '^[1-9][0-9]*[smhd]$') return '1s';
+  if (pattern === '^gcap_v1\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$') return 'gcap_v1.example.example';
+  if (
+    pattern === '^(?:[01]\\d|2[0-3]):[0-5]\\d$' ||
+    pattern === '^([01][0-9]|2[0-3]):[0-5][0-9]$'
+  ) return '00:00';
+  const selectedPrefix = selectedPrefixBoundedCharacterClassPatternExample(pattern, schema);
+  if (selectedPrefix !== null) return selectedPrefix;
+  const boundedCharacterClass = boundedCharacterClassPatternExample(pattern);
+  if (boundedCharacterClass !== null) return boundedCharacterClass;
+  const unboundedCharacterClass = unboundedCharacterClassPatternExample(pattern, schema);
+  if (unboundedCharacterClass !== null) return unboundedCharacterClass;
+  const literalPrefix = /^\^([A-Za-z0-9_.:-]+)$/.exec(pattern);
+  if (literalPrefix) {
+    const candidate = `${literalPrefix[1]}example`;
+    if (matchesPattern(pattern, candidate)) return candidate;
+  }
+  const fixedDigits = /^\^\[0-9\]\{([1-9][0-9]*)\}\$$/.exec(pattern ?? '');
+  return fixedDigits ? '0'.repeat(Number(fixedDigits[1])) : null;
+}
+
+function selectedPrefixBoundedCharacterClassPatternExample(pattern, schema) {
+  const match = /^\^([A-Za-z0-9_.:-]*)\[([A-Za-z0-9_-]+)\]([A-Za-z0-9_.:-]*)\[([A-Za-z0-9_-]+)\]\{([1-9][0-9]*)(?:,([1-9][0-9]*))?\}\$$/.exec(pattern);
+  if (!match) return null;
+  const minimum = Number(match[5]);
+  const maximum = Number(match[6] ?? match[5]);
+  if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum) || minimum > maximum || minimum > 256) {
+    return null;
+  }
+  for (const selected of 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-') {
+    for (const repeated of 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-') {
+      const candidate = `${match[1]}${selected}${match[3]}${repeated.repeat(minimum)}`;
+      if (Number.isInteger(schema.maxLength) && candidate.length > schema.maxLength) continue;
+      if (matchesPattern(pattern, candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+function unboundedCharacterClassPatternExample(pattern, schema) {
+  const match = /^\^([A-Za-z0-9_.:-]*)\[([A-Za-z0-9_.:-]+)\]\+\$$/.exec(pattern);
+  if (!match) return null;
+  const minimum = Math.max(1, (schema.minLength ?? 0) - match[1].length);
+  if (!Number.isSafeInteger(minimum) || minimum > 256) return null;
+  if (Number.isInteger(schema.maxLength) && match[1].length + minimum > schema.maxLength) return null;
+  for (const character of ['a', 'A', '0', '_', '-', '.', ':']) {
+    const candidate = `${match[1]}${character.repeat(minimum)}`;
+    if (matchesPattern(pattern, candidate)) return candidate;
+  }
+  return null;
+}
+
+function boundedCharacterClassPatternExample(pattern) {
+  const match = /^\^([A-Za-z0-9_.:-]*)\[([A-Za-z0-9_-]+)\]\{([1-9][0-9]*)(?:,([1-9][0-9]*))?\}\$$/.exec(pattern);
+  if (!match) return null;
+  const minimum = Number(match[3]);
+  const maximum = Number(match[4] ?? match[3]);
+  if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum) || minimum > maximum || minimum > 256) {
+    return null;
+  }
+  for (const character of ['a', 'A', '0', '_', '-']) {
+    const candidate = `${match[1]}${character.repeat(minimum)}`;
+    if (matchesPattern(pattern, candidate)) return candidate;
+  }
+  return null;
+}
+
+function matchesPattern(pattern, value) {
+  try {
+    return new RegExp(pattern, 'u').test(value);
+  } catch {
+    return false;
+  }
+}
+
+function numericExample(schema, integer) {
+  const multiple = schema.multipleOf ?? 1;
+  let value = schema.minimum ?? (schema.exclusiveMinimum !== undefined ? schema.exclusiveMinimum + multiple : multiple);
+  if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) value = schema.exclusiveMinimum + multiple;
+  if (schema.maximum !== undefined && value > schema.maximum) value = schema.maximum;
+  if (schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum) value = schema.exclusiveMaximum - multiple;
+  return integer ? Math.trunc(value) : value;
+}
+
+function sanitizeValue(value, name, schema = {}, { preserve = false } = {}) {
+  if (Array.isArray(value)) return value.map((entry) => sanitizeValue(entry, name));
+  if (isPlainObject(value)) return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, sanitizeValue(entry, key)]));
+  if (typeof value !== 'string' || preserve) return value;
+  const normalized = name.toLowerCase();
+  if (isSensitiveExampleKey(name)) {
+    const redacted = safeSensitiveExampleValue(schema);
+    if (redacted === null) throw new Error(`sensitive schema cannot produce a safe example: ${name}`);
+    return redacted;
+  }
+  if (schema.format === 'email' || isEmailExampleKey(name) || /^[^\s@]+@[^\s@]+$/.test(value)) return 'user@example.com';
+  if (schema.format === 'uri' || /(url|uri|link)$/.test(normalized) || /^https?:\/\//.test(value)) return 'https://api.example.com/resource';
+  if (isIPKey(normalized)) return '192.0.2.1';
+  if (/(phone|mobile)/.test(normalized)) return '+12025550123';
+  return value;
+}
+
+function isIPKey(value) {
+  return /(^|_)(ip|ip_address)($|_)/.test(value) || /^(client|remote|source|destination)ip(address)?$/.test(value);
+}
+
+function provenance(sourcePointer, sourceSha256, descriptionSource) {
+  return {
+    description_source: descriptionSource,
+    generator: `onex-documentation-projection/${documentationProjectionVersion}`,
+    source_pointer: sourcePointer,
+    source_sha256: sourceSha256,
+  };
+}
+
+function responseDescription(status) {
+  if (/^2/.test(status)) return '请求成功';
+  if (/^3/.test(status)) return '请求需要重定向';
+  if (/^4/.test(status)) return '请求未能完成';
+  if (/^5/.test(status)) return '服务处理失败';
+  return '请求处理结果';
+}
+
+function validateLinkProvenance(document, operationPointers) {
+  for (const { operation } of operationEntries(document)) {
+    for (const responseReference of Object.values(operation.responses ?? {})) {
+      const response = resolveReference(document, responseReference);
+      for (const linkReference of Object.values(response?.links ?? {})) {
+        const link = resolveReference(document, linkReference);
+        if (link?.operationId && !operationPointers.has(link.operationId)) {
+          throw new Error(`link targets unknown operationId: ${link.operationId}`);
+        }
+      }
+    }
+  }
+}
+
+function schemaType(schema) {
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const nonNullType = types.find((type) => type && type !== 'null');
+  if (nonNullType) return nonNullType;
+  if (types.includes('null')) return 'null';
+  return schema.properties || schema.additionalProperties ? 'object' : 'string';
+}
+
+function nullable(schema) {
+  return schema?.type === 'null' || (Array.isArray(schema?.type) && schema.type.includes('null')) || schema?.const === null;
+}
+
+function fallbackForType(schema) {
+  const type = schemaType(schema);
+  if (type === 'object') return {};
+  if (type === 'array') return [];
+  if (type === 'integer' || type === 'number') return 0;
+  if (type === 'boolean') return false;
+  return 'example';
+}
+
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function escapePointer(value) {
+  return value.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+function unescapePointer(value) {
+  return value.replaceAll('~1', '/').replaceAll('~0', '~');
+}