@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,103 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { compileCanonicalContract, lintContractDocument, publicationLintConfig } from './contract_compiler.mjs';
+import { apiRoot, canonicalJSON, projectDocument, readRegistry, readStructured, sha256 } from './project.mjs';
+import { conformanceMatrix } from './conformance_coverage.mjs';
+import { applyDocumentationProjection } from './documentation_projection.mjs';
+import { routeContract } from './route_contract.mjs';
+import { generateSDKPackages } from './sdk_generator.mjs';
+export const backendRoot = resolve(apiRoot, '../..');
+export async function assertToolVersions({ requireOASDiff = false } = {}) {
+  const pkg = JSON.parse(await readFile(resolve(apiRoot, 'package.json'), 'utf8'));
+  const versions = {};
+  for (const [name, expected] of Object.entries(pkg.devDependencies)) {
+    const actual = JSON.parse(await readFile(resolve(apiRoot, 'node_modules', name, 'package.json'), 'utf8')).version;
+    if (actual !== expected) throw new Error(`${name} version ${actual} does not match ${expected}`);
+    versions[name] = expected;
+  }
+  if (requireOASDiff) {
+    const version = execFileSync('oasdiff', ['--version'], { encoding: 'utf8' }).trim().replace(/^oasdiff version v?/, '');
+    if (version !== '1.23.0') throw new Error('oasdiff 1.23.0 is required');
+    versions.oasdiff = version;
+  }
+  return versions;
+}
+
+export function runtimeMetadata(service, document, delegated) {
+  const routes = routeContract(document).map(({ method, path }) => ({ method, path }));
+  return {
+    schema_version: 2,
+    media_type: 'application/vnd.onex.runtime-contract+json;version=2',
+    service: service.id,
+    display_name: service.display_name,
+    api_version: document.info.version,
+    sha256: sha256(canonicalJSON(document)),
+    operation_count: routes.length,
+    native_operation_count: routes.length - delegated.evidence.reduce((total, entry) => total + entry.operation_count, 0),
+    delegated_contracts: delegated.evidence.map(({ id, operation_count }) => ({ id, operation_count })),
+    route_exclusions: service.route_exclusions,
+    routes,
+  };
+}
+
+export function publicationDocument(document, audience) {
+  return audience === 'internal' ? document : applyDocumentationProjection(projectDocument(document, audience), {
+    audience, service: document.info.title, sourceSha256: sha256(canonicalJSON(document)),
+  });
+}
+
+async function main() {
+  const versions = await assertToolVersions();
+  const check = process.argv.includes('--check');
+  const sdk = process.argv.includes('--sdk');
+  const registry = await readRegistry();
+  const files = new Map();
+  const artifacts = [];
+  const serviceDocuments = new Map();
+  const workflowDocuments = new Map();
+  for (const service of registry.services) {
+    const { document, delegated } = await compileCanonicalContract(service);
+    serviceDocuments.set(service.id, document);
+    workflowDocuments.set(service.id, [await readStructured(resolve(apiRoot, service.runtime_conformance))]);
+    const root = `services/${service.id}/dist`;
+    files.set(`${root}/runtime-contract.json`, canonicalJSON(runtimeMetadata(service, document, delegated)));
+    for (const audience of service.publications) {
+      const projected = publicationDocument(document, audience);
+      if (audience !== 'internal') {
+        await lintContractDocument(projected, `${service.id}-${audience}`, publicationLintConfig);
+      }
+      const spec = canonicalJSON(projected);
+      const contractPath = `${root}/${audience}.openapi.json`;
+      files.set(contractPath, spec);
+      artifacts.push({ service: service.id, audience, api_version: projected.info.version,
+        path: contractPath, sha256: sha256(spec) });
+      if (sdk && audience !== 'internal') {
+        const gitRevision = process.env.SOURCE_REVISION ?? execFileSync('git', ['rev-parse', 'HEAD'], {
+          cwd: apiRoot, encoding: 'utf8',
+        }).trim();
+        if (!/^[a-f0-9]{40}$/.test(gitRevision)) throw new Error('SDK SOURCE_REVISION must be a full Git revision');
+        const packages = await generateSDKPackages({ audience, contractSha256: sha256(spec), document: projected,
+          gitRevision, service: service.id, toolVersions: versions });
+        for (const item of packages) for (const [path, content] of item.files) {
+          files.set(`services/${service.id}/sdk/${audience}/${item.generator}/${path}`, content);
+        }
+      }
+    }
+  }
+  artifacts.sort((left, right) => `${left.service}\0${left.audience}`.localeCompare(`${right.service}\0${right.audience}`));
+  files.set('dist/conformance-matrix.json', canonicalJSON(conformanceMatrix(serviceDocuments, workflowDocuments)));
+  files.set('dist/artifact-manifest.json', canonicalJSON({ schema_version: 1, artifacts }));
+  for (const [path, content] of files) {
+    const target = resolve(apiRoot, path);
+    if (check) {
+      const current = await readFile(target);
+      if (!current.equals(Buffer.from(content))) throw new Error(`generated OpenAPI artifact differs: ${path}`);
+    } else {
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, content);
+    }
+  }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();

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

@@ -0,0 +1,111 @@
+import { operationEntries } from './project.mjs';
+
+export function requiredContractAssertions(operation) {
+  const assertions = new Set();
+  for (const parameter of operation.parameters ?? []) {
+    assertions.add(`parameter:${parameter.in}:${parameter.name}`);
+  }
+  if (operation.requestBody) assertions.add('request_body');
+  for (const [status, response] of Object.entries(operation.responses ?? {})) {
+    assertions.add(`response:${status}`);
+    for (const name of Object.keys(response.headers ?? {})) {
+      assertions.add(`response_header:${status}:${name}`);
+    }
+  }
+  if (operation.security.length === 0) {
+    assertions.add('security:anonymous');
+  } else {
+    operation.security.forEach((requirement, index) => {
+      assertions.add(`security:${index}:${Object.keys(requirement).sort().join('+') || 'anonymous'}`);
+    });
+  }
+  if (operation['x-onex-idempotency']) assertions.add('idempotency');
+  return [...assertions].sort();
+}
+
+export function conformanceMatrix(serviceDocuments, workflowDocuments) {
+  const operations = [];
+  const services = [];
+  let workflowCount = 0;
+  let runtimeStepCount = 0;
+
+  for (const [service, document] of [...serviceDocuments].sort(([left], [right]) => left.localeCompare(right))) {
+    const entries = operationEntries(document);
+    const operationIds = new Set(entries.map(({ operation }) => operation.operationId));
+    const runtime = runtimeWorkflowCoverage(workflowDocuments.get(service) ?? [], operationIds, service);
+    workflowCount += runtime.workflowCount;
+    runtimeStepCount += runtime.stepCount;
+    services.push({
+      operation_count: entries.length,
+      runtime_operation_count: runtime.coverage.size,
+      runtime_step_count: runtime.stepCount,
+      runtime_workflow_count: runtime.workflowCount,
+      service,
+    });
+
+    for (const { method, operation, path } of entries) {
+      operations.push({
+        contract_assertions: requiredContractAssertions(operation),
+        method: method.toUpperCase(),
+        operation_id: operation.operationId,
+        path,
+        runtime_scenarios: [...(runtime.coverage.get(operation.operationId) ?? [])].sort(),
+        service,
+      });
+    }
+  }
+
+  return {
+    contract_assertion_count: operations.reduce((total, operation) => total + operation.contract_assertions.length, 0),
+    operation_count: operations.length,
+    operations,
+    runtime_operation_count: operations.filter((operation) => operation.runtime_scenarios.length > 0).length,
+    runtime_step_count: runtimeStepCount,
+    runtime_workflow_count: workflowCount,
+    schema_version: 2,
+    services,
+  };
+}
+
+export function runtimeWorkflowCoverage(arazzoDocuments, operationIds, service = 'service') {
+  const coverage = new Map();
+  let workflowCount = 0;
+  let stepCount = 0;
+  for (const document of arazzoDocuments) {
+    if (document?.arazzo !== '1.0.1') {
+      throw new Error(`${service} Arazzo documents must use version 1.0.1`);
+    }
+    for (const workflow of document.workflows ?? []) {
+      if (!workflow.workflowId || !Array.isArray(workflow.steps) || workflow.steps.length === 0) {
+        throw new Error(`${service} Arazzo workflows must declare workflowId and steps`);
+      }
+      workflowCount += 1;
+      for (const step of workflow.steps) {
+        validateRuntimeStep(step, operationIds, service);
+        stepCount += 1;
+        const current = coverage.get(step.operationId) ?? new Set();
+        for (const scenario of step['x-onex-covers']) current.add(scenario);
+        coverage.set(step.operationId, current);
+      }
+    }
+  }
+  if (workflowCount === 0) {
+    throw new Error(`${service} must declare at least one executable Arazzo workflow`);
+  }
+  return { coverage, stepCount, workflowCount };
+}
+
+function validateRuntimeStep(step, operationIds, service) {
+  if (!step.stepId || !step.operationId || !operationIds.has(step.operationId)) {
+    throw new Error(`${service} Arazzo step ${step.stepId ?? '<unknown>'} must reference a known operationId`);
+  }
+  if (!Array.isArray(step['x-onex-covers']) || step['x-onex-covers'].length === 0) {
+    throw new Error(`${service} Arazzo step ${step.stepId} must declare x-onex-covers`);
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(step['x-onex-fixture-profile'] ?? '')) {
+    throw new Error(`${service} Arazzo step ${step.stepId} must declare x-onex-fixture-profile`);
+  }
+  if (!Array.isArray(step.successCriteria) || step.successCriteria.length === 0) {
+    throw new Error(`${service} Arazzo step ${step.stepId} must declare successCriteria`);
+  }
+}

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

@@ -0,0 +1,62 @@
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { applyContractPolicies } from './contract_policy.mjs';
+import { composeDelegatedContracts } from './delegated_contract.mjs';
+import { apiRoot, canonicalJSON, validateDocument } from './project.mjs';
+import { routeContract } from './route_contract.mjs';
+
+const backendRoot = resolve(apiRoot, '../..');
+export const contractSourceLintConfig = resolve(apiRoot, 'redocly-source.yaml');
+export const publicationLintConfig = resolve(apiRoot, 'redocly.yaml');
+export const redoclyExecutable = resolve(apiRoot, 'node_modules/.bin/redocly');
+
+export async function compileCanonicalContract(service) {
+  const sourcePath = resolve(apiRoot, service.source);
+  lintContractSource(sourcePath, contractSourceLintConfig);
+  const source = await bundleSource(sourcePath);
+  const delegated = await composeDelegatedContracts(service, source);
+  const document = applyContractPolicies(delegated.document);
+  await lintContractDocument(document, service.id, contractSourceLintConfig);
+  validateDocument(document, {
+    audience: 'internal',
+    documentationLocale: service.documentation_locale,
+    service: service.id,
+  });
+  routeContract(document);
+  return { delegated, document, sourcePath };
+}
+
+export function lintContractSource(sourcePath, configPath) {
+  execFileSync(redoclyExecutable, ['lint', sourcePath, '--config', configPath, '--format', 'stylish', '--max-problems', '1000'], commandOptions());
+}
+
+export async function lintContractDocument(document, label, configPath) {
+  const tempRoot = resolve(backendRoot, 'tmp', `openapi-lint-${randomUUID()}`);
+  const input = resolve(tempRoot, `${label}.json`);
+  await mkdir(tempRoot, { recursive: true });
+  try {
+    await writeFile(input, canonicalJSON(document));
+    lintContractSource(input, configPath);
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+async function bundleSource(sourcePath) {
+  const tempRoot = resolve(backendRoot, 'tmp', `openapi-bundle-${randomUUID()}`);
+  const output = resolve(tempRoot, 'bundle.json');
+  await mkdir(tempRoot, { recursive: true });
+  try {
+    execFileSync(redoclyExecutable, ['bundle', sourcePath, '--config', contractSourceLintConfig, '--ext', 'json', '--output', output, '--remove-unused-components', '--component-renaming-conflicts-severity', 'error'], commandOptions());
+    return JSON.parse(await readFile(output, 'utf8'));
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function commandOptions() {
+  return { cwd: apiRoot, encoding: 'utf8', env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' }, stdio: ['ignore', 'pipe', 'pipe'] };
+}

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

@@ -0,0 +1,208 @@
+import { operationEntries } from './project.mjs';
+
+const defaultErrorResponseSchema = 'ErrorResponse';
+const serviceErrorResponseSchemaExtension = 'x-onex-error-response-schema';
+
+const standardAuthenticationResponses = Object.freeze({
+  401: {
+    description: '需要身份认证',
+  },
+  403: {
+    description: '无权执行此操作',
+  },
+});
+
+export function applyContractPolicies(document) {
+  const result = structuredClone(document);
+  if (Object.hasOwn(result, serviceErrorResponseSchemaExtension)) {
+    throw new Error(`${serviceErrorResponseSchemaExtension} is forbidden; use components.schemas.ErrorResponse`);
+  }
+  if (result.components?.schemas?.[defaultErrorResponseSchema]) {
+    assertCanonicalErrorSchemas(result.components.schemas);
+  }
+  const errorResponseSchema = defaultErrorResponseSchema;
+  const errorResponseReference = `#/components/schemas/${errorResponseSchema}`;
+  const operations = operationEntries(result);
+  const securedOperations = operations.filter(({ operation }) => requiresAuthentication(operation));
+
+  for (const { operation } of securedOperations) {
+    for (const [status, response] of Object.entries(standardAuthenticationResponses)) {
+      if (!Object.hasOwn(operation.responses, status)) {
+        operation.responses[status] = responseWithSchema(response, errorResponseReference);
+      }
+    }
+  }
+
+  for (const response of Object.values(result.components?.responses ?? {})) {
+    resolveResponseObject(result, response);
+  }
+  const errorsWithoutSchema = operations.filter(({ method }) => method !== 'head').flatMap(({ operation }) => Object.entries(operation.responses ?? {})
+    .map(([status, response]) => ({ operation, resolved: resolveResponseObject(result, response), status })))
+    .filter(({ resolved, status }) => /^[45]/u.test(status) && !hasResponseSchema(resolved) && !isEmptyMethodResponse(status, resolved));
+  if ((securedOperations.length > 0 || errorsWithoutSchema.length > 0) && !result.components?.schemas?.[errorResponseSchema]) {
+    throw new Error(`contract policies require components.schemas.${errorResponseSchema}`);
+  }
+  for (const { operation, resolved, status } of errorsWithoutSchema) {
+    operation.responses[status] = responseWithSchema(resolved, errorResponseReference);
+  }
+  return result;
+}
+
+function assertCanonicalErrorSchemas(schemas) {
+  assertObjectSchema(schemas.ErrorResponse, 'ErrorResponse', ['error'], ['error']);
+  assertReference(schemas.ErrorResponse.properties.error, '#/components/schemas/ErrorDetail', 'ErrorResponse.error');
+
+  assertObjectSchema(schemas.ErrorDetail, 'ErrorDetail', ['code', 'errors', 'message', 'param', 'type'], ['code', 'message', 'type']);
+  assertNonEmptyString(schemas.ErrorDetail.properties.code, 'ErrorDetail.code');
+  assertNonEmptyString(schemas.ErrorDetail.properties.message, 'ErrorDetail.message');
+  assertNonEmptyString(schemas.ErrorDetail.properties.param, 'ErrorDetail.param');
+  assertNonEmptyString(schemas.ErrorDetail.properties.type, 'ErrorDetail.type');
+  assertAllowedKeys(schemas.ErrorDetail.properties.errors, 'ErrorDetail.errors', ['description', 'items', 'type']);
+  if (schemas.ErrorDetail.properties.errors?.type !== 'array') {
+    throw new Error('components.schemas.ErrorDetail.errors must be an array');
+  }
+  assertReference(schemas.ErrorDetail.properties.errors.items, '#/components/schemas/FieldError', 'ErrorDetail.errors items');
+
+  assertObjectSchema(schemas.FieldError, 'FieldError', ['field', 'message'], ['field', 'message']);
+  assertNonEmptyString(schemas.FieldError.properties.field, 'FieldError.field');
+  assertNonEmptyString(schemas.FieldError.properties.message, 'FieldError.message');
+}
+
+function assertObjectSchema(schema, name, expectedProperties, expectedRequired) {
+  assertAllowedKeys(schema, name, [
+    'additionalProperties',
+    'description',
+    'properties',
+    'required',
+    'type',
+    'x-onex-audience',
+    'x-onex-stability',
+  ]);
+  if (schema?.type !== 'object' || schema.additionalProperties !== false) {
+    throw new Error(`components.schemas.${name} must be a closed object`);
+  }
+  if (!sameMembers(Object.keys(schema.properties ?? {}), expectedProperties)) {
+    throw new Error(`components.schemas.${name} properties must be ${expectedProperties.join(', ')}`);
+  }
+  if (!sameMembers(schema.required ?? [], expectedRequired)) {
+    throw new Error(`components.schemas.${name} required fields must be ${expectedRequired.join(', ')}`);
+  }
+}
+
+function assertNonEmptyString(schema, label) {
+  assertAllowedKeys(schema, label, ['description', 'example', 'minLength', 'type']);
+  if (schema?.type !== 'string' || schema.minLength !== 1) {
+    throw new Error(`components.schemas.${label} must be a non-empty string`);
+  }
+}
+
+function assertReference(schema, reference, label) {
+  assertAllowedKeys(schema, label, ['$ref', 'description']);
+  if (schema?.$ref !== reference) {
+    throw new Error(`components.schemas.${label} must reference ${reference}`);
+  }
+}
+
+function assertAllowedKeys(value, label, allowedKeys) {
+  if (!isObject(value)) {
+    throw new Error(`components.schemas.${label} must be an object`);
+  }
+  const unexpectedKeys = Object.keys(value).filter((key) => !allowedKeys.includes(key));
+  if (unexpectedKeys.length > 0) {
+    throw new Error(`components.schemas.${label} contains unsupported keys: ${unexpectedKeys.join(', ')}`);
+  }
+}
+
+function sameMembers(actual, expected) {
+  return actual.length === expected.length && expected.every((value) => actual.includes(value));
+}
+
+export function requiresAuthentication(operation) {
+  return Array.isArray(operation.security) &&
+    operation.security.length > 0 &&
+    operation.security.every((requirement) => Object.keys(requirement).length > 0);
+}
+
+function hasResponseSchema(response) {
+  return Object.values(response?.content ?? {}).some((media) => media?.schema);
+}
+
+function isEmptyMethodResponse(status, response) {
+  return status === '405' && response?.headers?.Allow;
+}
+
+function responseWithSchema(response, schemaReference) {
+  const existing = structuredClone(response);
+  return {
+    ...existing,
+    content: {
+      ...(existing.content ?? {}),
+      'application/json': {
+        ...(existing.content?.['application/json'] ?? {}),
+        schema: { $ref: schemaReference },
+      },
+    },
+  };
+}
+
+function resolveResponseObject(document, value, visited = new Set()) {
+  if (!isObject(value) || !Object.hasOwn(value, '$ref')) return value;
+  assertResponseReference(value);
+  const reference = value.$ref;
+  if (visited.has(reference)) {
+    throw new Error(`circular response reference: ${reference}`);
+  }
+  visited.add(reference);
+  const name = parseResponseComponentReference(reference);
+  const target = document.components?.responses?.[name];
+  if (!isObject(target)) {
+    throw new Error(`unresolved response reference: ${reference}`);
+  }
+  const resolved = structuredClone(resolveResponseObject(document, target, visited));
+  if (Object.hasOwn(value, 'description')) resolved.description = value.description;
+  return resolved;
+}
+
+function assertResponseReference(reference) {
+  const allowedKeys = ['$ref', 'description', 'summary'];
+  const unexpectedKeys = Object.keys(reference).filter((key) => !allowedKeys.includes(key));
+  if (unexpectedKeys.length > 0) {
+    throw new Error(`response Reference Object contains unsupported siblings: ${unexpectedKeys.join(', ')}`);
+  }
+  if (typeof reference.$ref !== 'string' || reference.$ref.length === 0) {
+    throw new Error('response Reference Object must contain a non-empty $ref');
+  }
+  for (const key of ['description', 'summary']) {
+    if (Object.hasOwn(reference, key) && typeof reference[key] !== 'string') {
+      throw new Error(`response Reference Object ${key} must be a string`);
+    }
+  }
+}
+
+function parseResponseComponentReference(reference) {
+  let pointer;
+  try {
+    pointer = decodeURIComponent(reference.slice(1));
+  } catch (error) {
+    throw new Error(`invalid response reference: ${reference}`, { cause: error });
+  }
+  if (!pointer.startsWith('/')) {
+    throw new Error(`response reference must target internal components.responses: ${reference}`);
+  }
+  const tokens = pointer.slice(1).split('/').map(decodePointerToken);
+  if (tokens.length !== 3 || tokens[0] !== 'components' || tokens[1] !== 'responses') {
+    throw new Error(`response reference must target internal components.responses: ${reference}`);
+  }
+  return tokens[2];
+}
+
+function decodePointerToken(token) {
+  if (/~(?:[^01]|$)/u.test(token)) {
+    throw new Error(`response reference contains an invalid JSON Pointer token: ${token}`);
+  }
+  return token.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}