@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/api/openapi/services/worker/openapi.yaml

@@ -0,0 +1,222 @@
+openapi: 3.1.1
+jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
+info:
+  title: 后台任务 API
+  version: 1.0.0
+  description: 服务运行状态接口契约。
+  license:
+    name: 专有许可
+    identifier: LicenseRef-Proprietary
+servers:
+  - url: http://localhost:3000
+    description: 本地服务
+x-onex-documentation-locale: zh-CN
+tags:
+  - name: 运行状态
+    description: 健康检查及监控指标
+x-tagGroups:
+  - name: 服务运行
+    tags:
+      - 运行状态
+paths:
+  /health:
+    get:
+      operationId: workerGetHealth
+      summary: 检查服务健康
+      description: 检查服务健康，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/health
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResult"
+        "503":
+          description: 服务暂不可用
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResult"
+    head:
+      operationId: workerHeadHealth
+      summary: 检查服务健康
+      description: 检查服务健康，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/health
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+        "503":
+          description: 服务暂不可用
+  /health/liveness:
+    get:
+      operationId: workerGetLiveness
+      summary: 检查进程存活
+      description: 检查进程存活，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/health
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResult"
+        "503":
+          description: 服务暂不可用
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResult"
+    head:
+      operationId: workerHeadLiveness
+      summary: 检查进程存活
+      description: 检查进程存活，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/health
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+        "503":
+          description: 服务暂不可用
+  /health/readiness:
+    get:
+      operationId: workerGetReadiness
+      summary: 检查服务就绪
+      description: 检查服务就绪，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/health
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResult"
+        "503":
+          description: 服务暂不可用
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResult"
+    head:
+      operationId: workerHeadReadiness
+      summary: 检查服务就绪
+      description: 检查服务就绪，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/health
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+        "503":
+          description: 服务暂不可用
+  /health/startup:
+    get:
+      operationId: workerGetStartup
+      summary: 检查启动状态
+      description: 检查启动状态，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/health
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResult"
+        "503":
+          description: 服务暂不可用
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HealthResult"
+    head:
+      operationId: workerHeadStartup
+      summary: 检查启动状态
+      description: 检查启动状态，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/health
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+        "503":
+          description: 服务暂不可用
+  /metrics:
+    get:
+      operationId: workerGetMetrics
+      summary: 读取监控指标
+      description: 读取监控指标，供运行环境探测与监控采集使用。
+      tags:
+        - 运行状态
+      security: []
+      x-onex-audience: internal
+      x-onex-owner: core/metrics
+      x-onex-stability: stable
+      responses:
+        "200":
+          description: 检查成功
+          content:
+            text/plain:
+              schema:
+                type: string
+components:
+  schemas:
+    HealthResult:
+      type: object
+      required:
+        - status
+      properties:
+        status:
+          type: string
+          enum:
+            - up
+            - down
+        components:
+          type: object
+          additionalProperties:
+            type: object
+            required:
+              - status
+            properties:
+              status:
+                type: string
+                enum:
+                  - up
+                  - down
+              details:
+                type: object
+                additionalProperties: true

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

@@ -0,0 +1,416 @@
+import { spawnSync } from 'node:child_process';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+
+import {
+  artifactContentIdentity,
+  artifactSlotKey,
+  artifactVersionKey,
+  contractArtifacts,
+  currentRevision,
+  readCurrentArtifact,
+  readCurrentManifest,
+  readHistoricalArtifact,
+  readHistoricalManifests,
+  readManifestAtRevision,
+  resolveProtectedBaseRevision,
+} from './git_artifact_history.mjs';
+import { apiRoot, canonicalJSON, operationEntries, sha256 } from './project.mjs';
+import { compareSemanticVersions, parseSemanticVersion } from './semantic_version.mjs';
+import { assertToolVersions, backendRoot } from './build.mjs';
+
+const outputRoot = resolve(backendRoot, 'tmp/openapi-breaking');
+const audienceRank = Object.freeze({ internal: 0, partner: 1, public: 2 });
+const stabilityRank = Object.freeze({ experimental: 0, beta: 1, stable: 2 });
+
+export function buildComparisonPlan({ baseManifest, headManifest }) {
+  const errors = [];
+  const comparisons = new Map();
+  const head = new Map(contractArtifacts(headManifest).map((record) => [artifactSlotKey(record), record]));
+
+  for (const baseRecord of contractArtifacts(baseManifest)) {
+    const key = artifactSlotKey(baseRecord);
+    const headRecord = head.get(key);
+    if (!headRecord) {
+      errors.push(finding('artifact_identity_removed', key, artifactContentIdentity(baseRecord), null));
+      continue;
+    }
+    if (compareSemanticVersions(headRecord.api_version, baseRecord.api_version) < 0) {
+      errors.push(finding('artifact_version_downgraded', key, baseRecord.api_version, headRecord.api_version));
+      continue;
+    }
+    addComparison(comparisons, baseRecord, headRecord, 'protected_base');
+  }
+
+  return {
+    comparisons: [...comparisons.values()].sort((left, right) => left.id.localeCompare(right.id)),
+    errors: errors.sort(compareFindings),
+  };
+}
+
+export function semanticBreakingChanges(baseDocument, headDocument) {
+  const findings = [];
+  const headOperations = new Map(operationEntries(headDocument).map((entry) => [operationKey(entry), entry.operation]));
+  for (const entry of operationEntries(baseDocument)) {
+    const key = operationKey(entry);
+    const base = entry.operation;
+    const head = headOperations.get(key);
+    if (!head) {
+      findings.push(finding('operation_removed', key, base.operationId ?? null, null));
+      continue;
+    }
+    if (base.operationId !== head.operationId) findings.push(finding('operation_id_changed', key, base.operationId, head.operationId));
+    compareRankedExtension(findings, key, 'audience_visibility_reduced', base['x-onex-audience'], head['x-onex-audience'], audienceRank);
+    compareRankedExtension(findings, key, 'stability_reduced', base['x-onex-stability'], head['x-onex-stability'], stabilityRank);
+    compareLifecycle(findings, key, base['x-onex-lifecycle'], head['x-onex-lifecycle']);
+  }
+  return findings.sort(compareFindings);
+}
+
+async function main() {
+  const versions = await assertToolVersions({ requireOASDiff: true });
+  const [headManifest, baseRevision] = await Promise.all([readCurrentManifest(), resolveProtectedBaseRevision()]);
+  const headRevision = currentRevision();
+  const baseManifest = readManifestAtRevision(baseRevision) ?? { artifacts: [], schema_version: 1 };
+  const history = readHistoricalManifests();
+  const plan = buildComparisonPlan({ baseManifest, headManifest });
+  const errors = [...plan.errors];
+  const results = [];
+  const temporaryRoot = await mkdtemp(resolve(tmpdir(), 'onex-openapi-breaking-'));
+
+  try {
+    for (const comparison of plan.comparisons) {
+      const baseLocator = locateArtifact(comparison.base, headManifest, baseManifest, baseRevision, history);
+      if (!baseLocator) {
+        errors.push(finding('baseline_artifact_unavailable', comparison.id, comparison.base.sha256, null));
+        continue;
+      }
+      const baseContent = await readLocatedArtifact(baseLocator);
+      const headContent = await readCurrentArtifact(comparison.head);
+      const baseDocument = JSON.parse(baseContent);
+      const headDocument = JSON.parse(headContent);
+      const semantic = semanticBreakingChanges(baseDocument, headDocument);
+      const oasdiff = await runOASDiff(
+        temporaryRoot,
+        comparison.id,
+        canonicalJSON(projectDocumentForOASDiff(baseDocument)),
+        canonicalJSON(projectDocumentForOASDiff(headDocument)),
+      );
+      const policy = evaluateComparisonPolicy(comparison, {
+        oasdiffBreaking: oasdiff.breaking,
+        semanticFindings: semantic,
+      });
+      errors.push(...policy.errors);
+      results.push({
+        base_api_version: comparison.base.api_version,
+        base_sha256: comparison.base.sha256,
+        head_api_version: comparison.head.api_version,
+        head_sha256: comparison.head.sha256,
+        id: comparison.id,
+        oasdiff: oasdiff.findings,
+        oasdiff_breaking: oasdiff.breaking,
+        origins: comparison.origins,
+        semantic_findings: semantic,
+        status: policy.status,
+        version_findings: policy.versionFindings,
+      });
+    }
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+
+  const payload = {
+    base_revision: baseRevision,
+    candidate_revision: headRevision,
+    comparisons: results.sort((left, right) => left.id.localeCompare(right.id)),
+    errors: errors.sort(compareFindings),
+    schema_version: 1,
+    tool_versions: { oasdiff: versions.oasdiff },
+  };
+  const report = { ...payload, fingerprint: sha256(canonicalJSON(payload)) };
+  await writeEvidence(report);
+  if (report.errors.length > 0) throw new Error(`OpenAPI compatibility gate failed with ${report.errors.length} finding(s)`);
+}
+
+function addComparison(comparisons, base, head, origin) {
+  const id = `${artifactVersionKey(base)}@${base.sha256}->${artifactVersionKey(head)}@${head.sha256}`;
+  const existing = comparisons.get(id);
+  if (existing) {
+    existing.origins = [...new Set([...existing.origins, origin])].sort();
+    return;
+  }
+  const baseVersion = parseSemanticVersion(base.api_version);
+  const headVersion = parseSemanticVersion(head.api_version);
+  comparisons.set(id, {
+    base,
+    head,
+    id,
+    intentionalMajorVersionChange: baseVersion.major !== headVersion.major,
+    origins: [origin],
+  });
+}
+
+export function evaluateComparisonPolicy(comparison, { oasdiffBreaking, semanticFindings }) {
+  const hasBreakingChanges = oasdiffBreaking || semanticFindings.length > 0;
+  const versionFindings = comparison.intentionalMajorVersionChange
+    ? [finding(
+      'intentional_major_version_change',
+      artifactSlotKey(comparison.base),
+      comparison.base.api_version,
+      comparison.head.api_version,
+    )]
+    : [];
+  const errors = [];
+  if (!comparison.intentionalMajorVersionChange) {
+    if (oasdiffBreaking) {
+      errors.push(finding(
+        'oasdiff_breaking_change',
+        comparison.id,
+        comparison.base.sha256,
+        comparison.head.sha256,
+      ));
+    }
+    errors.push(...semanticFindings.map((entry) => ({ ...entry, artifact: comparison.id })));
+  }
+  return {
+    errors: errors.sort(compareFindings),
+    status: comparison.intentionalMajorVersionChange
+      ? 'intentional_major_version_change'
+      : hasBreakingChanges ? 'failed' : 'compatible',
+    versionFindings,
+  };
+}
+
+function locateArtifact(record, headManifest, baseManifest, baseRevision, history) {
+  const identity = artifactContentIdentity(record);
+  const current = contractArtifacts(headManifest).find((candidate) => artifactContentIdentity(candidate) === identity);
+  if (current) return { kind: 'current', record: current };
+  const base = contractArtifacts(baseManifest).find((candidate) => artifactContentIdentity(candidate) === identity);
+  if (base) return { kind: 'historical', record: base, revision: baseRevision };
+  for (const entry of history) {
+    const historical = contractArtifacts(entry.manifest).find((candidate) => artifactContentIdentity(candidate) === identity);
+    if (historical) {
+      return { kind: 'historical', record: historical, revision: entry.revision };
+    }
+  }
+  return null;
+}
+
+async function readLocatedArtifact(locator) {
+  return locator.kind === 'current' ? readCurrentArtifact(locator.record) : readHistoricalArtifact(locator.record, locator.revision);
+}
+
+const schemaMapKeywords = new Set([
+  '$defs',
+  'definitions',
+  'dependentSchemas',
+  'patternProperties',
+  'properties',
+]);
+const schemaValueKeywords = new Set([
+  'additionalItems',
+  'additionalProperties',
+  'contains',
+  'contentSchema',
+  'else',
+  'if',
+  'not',
+  'propertyNames',
+  'then',
+  'unevaluatedItems',
+  'unevaluatedProperties',
+]);
+const schemaArrayKeywords = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const opaqueOpenAPIKeywords = new Set(['const', 'default', 'enum', 'example', 'examples']);
+
+// projectDocumentForOASDiff 保留 OpenAPI 3.1 语义，并把布尔 Schema
+// 投影为 oasdiff 1.23.0 可解析的等价 Schema Object。
+export function projectDocumentForOASDiff(document) {
+  const projected = structuredClone(document);
+  projectOpenAPIValue(projected, []);
+  return projected;
+}
+
+function projectOpenAPIValue(value, path) {
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      projectOpenAPIValue(value[index], [...path, index]);
+    }
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+
+  for (const [key, child] of Object.entries(value)) {
+    if (key.startsWith('x-') || opaqueOpenAPIKeywords.has(key)) continue;
+    if (key === 'schema') {
+      value[key] = projectJSONSchema(child);
+      continue;
+    }
+    if (key === 'schemas' && path.at(-1) === 'components' && child && typeof child === 'object' && !Array.isArray(child)) {
+      value[key] = Object.fromEntries(Object.entries(child).map(([name, schema]) => [name, projectJSONSchema(schema)]));
+      continue;
+    }
+    projectOpenAPIValue(child, [...path, key]);
+  }
+}
+
+function projectJSONSchema(schema) {
+  if (schema === true) return {};
+  if (schema === false) return { not: {} };
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return schema;
+
+  const projected = structuredClone(schema);
+  for (const [key, child] of Object.entries(projected)) {
+    if (schemaMapKeywords.has(key) && child && typeof child === 'object' && !Array.isArray(child)) {
+      projected[key] = Object.fromEntries(Object.entries(child).map(([name, nested]) => [name, projectJSONSchema(nested)]));
+      continue;
+    }
+    if (schemaArrayKeywords.has(key) && Array.isArray(child)) {
+      projected[key] = child.map(projectJSONSchema);
+      continue;
+    }
+    if (key === 'items' && Array.isArray(child)) {
+      projected[key] = child.map(projectJSONSchema);
+      continue;
+    }
+    if (key === 'items' || schemaValueKeywords.has(key)) {
+      projected[key] = projectJSONSchema(child);
+    }
+  }
+  return projected;
+}
+
+async function runOASDiff(root, id, baseContent, headContent) {
+  const directory = resolve(root, sha256(id).slice(0, 16));
+  await mkdir(directory, { recursive: true });
+  const basePath = resolve(directory, 'base.openapi.json');
+  const headPath = resolve(directory, 'head.openapi.json');
+  await Promise.all([writeFile(basePath, baseContent), writeFile(headPath, headContent)]);
+  const result = spawnSync('oasdiff', buildOASDiffArguments(basePath, headPath), {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.error) throw result.error;
+  let findings;
+  try {
+    findings = JSON.parse(result.stdout || '[]');
+  } catch (error) {
+    throw new Error(`oasdiff returned invalid JSON for ${id}: ${error.message}`);
+  }
+  if (![0, 1].includes(result.status) || (result.status === 1 && !Array.isArray(findings))) {
+    throw new Error(`oasdiff failed for ${id}: ${result.stderr.trim() || `exit ${result.status}`}`);
+  }
+  return { breaking: result.status === 1, findings };
+}
+
+export function buildOASDiffArguments(basePath, headPath) {
+  return [
+    'breaking',
+    basePath,
+    headPath,
+    '--allow-external-refs=false',
+    '--attributes',
+    'x-onex-audience,x-onex-stability,x-onex-lifecycle',
+    '--deprecation-days-beta',
+    '4294967295',
+    '--deprecation-days-stable',
+    '4294967295',
+    '--fail-on',
+    'ERR',
+    '--format',
+    'json',
+    '--include-path-params',
+  ];
+}
+
+function compareRankedExtension(findings, key, code, base, head, ranking) {
+  if (base === undefined && head === undefined) return;
+  if (!Object.hasOwn(ranking, base) || !Object.hasOwn(ranking, head) || ranking[head] < ranking[base]) {
+    findings.push(finding(code, key, base ?? null, head ?? null));
+  }
+}
+
+function compareLifecycle(findings, key, base, head) {
+  if (base === undefined && head === undefined) return;
+  if (!base || !head) {
+    findings.push(finding('lifecycle_contract_removed', key, base ?? null, head ?? null));
+    return;
+  }
+  if (base.introduced !== head.introduced) findings.push(finding('lifecycle_introduced_changed', key, base.introduced, head.introduced));
+  for (const field of ['deprecated', 'sunset', 'replacementOperationId', 'migrationUrl']) {
+    if (base[field] !== null && base[field] !== head[field]) {
+      findings.push(finding(`lifecycle_${field}_changed`, key, base[field], head[field] ?? null));
+    }
+  }
+}
+
+function operationKey({ method, path }) {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+function finding(code, identity, before, after) {
+  return { after, before, code, identity };
+}
+
+function compareFindings(left, right) {
+  return `${left.code}\0${left.identity}\0${left.artifact ?? ''}`.localeCompare(`${right.code}\0${right.identity}\0${right.artifact ?? ''}`);
+}
+
+async function writeEvidence(report) {
+  await rm(outputRoot, { recursive: true, force: true });
+  await mkdir(outputRoot, { recursive: true });
+  await writeFile(resolve(outputRoot, 'compatibility-report.json'), canonicalJSON(report));
+  await writeFile(resolve(outputRoot, 'compatibility-report.md'), renderCompatibilityReportMarkdown(report));
+}
+
+export function renderCompatibilityReportMarkdown(report) {
+  const rows = report.comparisons.map((entry) => `| ${entry.id} | ${entry.base_api_version} | ${entry.head_api_version} | ${entry.origins.join(', ')} | ${entry.status} |`);
+  const errors = report.errors.length === 0
+    ? 'No gate-blocking compatibility findings.'
+    : report.errors.map((entry) => `- \`${entry.code}\` ${entry.artifact ? `${entry.artifact}: ` : ''}${entry.identity}`).join('\n');
+  const comparisonFindings = report.comparisons.flatMap((entry) => {
+    const findings = [];
+    if (entry.oasdiff_breaking || entry.oasdiff.length > 0) {
+      findings.push(`oasdiff breaking=${entry.oasdiff_breaking ? 'yes' : 'no'}, findings=${entry.oasdiff.length}`);
+    }
+    if (entry.semantic_findings.length > 0) {
+      findings.push(`OneX semantic=${entry.semantic_findings.map((finding) => finding.code).join(',')}`);
+    }
+    if (entry.version_findings.length > 0) {
+      findings.push(`version=${entry.version_findings.map((finding) => finding.code).join(',')}`);
+    }
+    return findings.length > 0 ? [`- \`${entry.id}\`: ${findings.join('; ')}`] : [];
+  });
+  const markdown = [
+    '# OpenAPI Compatibility Report',
+    '',
+    `- Base revision: \`${report.base_revision}\``,
+    `- Candidate revision: \`${report.candidate_revision}\``,
+    `- Fingerprint: \`${report.fingerprint}\``,
+    `- oasdiff: \`${report.tool_versions.oasdiff}\``,
+    '',
+    '| Artifact comparison | Base version | Head version | Baseline | Status |',
+    '| --- | --- | --- | --- | --- |',
+    ...(rows.length > 0 ? rows : ['| None | - | - | Initial catalog baseline | compatible |']),
+    '',
+    '## Comparison Findings',
+    '',
+    ...(comparisonFindings.length > 0 ? comparisonFindings : ['No comparison findings.']),
+    '',
+    '## Gate Findings',
+    '',
+    errors,
+    '',
+  ].join('\n');
+  return markdown;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error(`Evidence: ${resolve(outputRoot, 'compatibility-report.json')}`);
+    process.exitCode = 1;
+  });
+}