@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,229 @@
+import { execFileSync } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { createClient } from '@hey-api/openapi-ts';
+
+import { apiRoot, canonicalJSON, operationEntries, readStructured, sha256 } from './project.mjs';
+
+export const sdkGeneratorRegistrySchemaVersion = 1;
+
+const adapters = Object.freeze({
+  'hey-api': Object.freeze({ generate: generateHeyAPISDK }),
+});
+
+export async function readSDKGeneratorRegistry(path = resolve(apiRoot, 'sdk-generators.json')) {
+  const registry = await readStructured(path);
+  if (registry?.schema_version !== sdkGeneratorRegistrySchemaVersion || !Array.isArray(registry.generators) || registry.generators.length === 0) {
+    throw new Error('SDK generator registry must declare schema_version 1 and generators');
+  }
+  const ids = new Set();
+  for (const generator of registry.generators) {
+    if (!/^[a-z][a-z0-9-]*$/.test(generator.id ?? '') || ids.has(generator.id)) throw new Error(`invalid SDK generator id: ${generator.id}`);
+    ids.add(generator.id);
+    if (!adapters[generator.provider]) throw new Error(`unknown SDK generator provider: ${generator.provider}`);
+    if (generator.language !== 'typescript' || generator.runtime !== 'fetch') throw new Error(`unsupported SDK target: ${generator.language}/${generator.runtime}`);
+    if (!/^@[a-z][a-z0-9-]*$/.test(generator.package_scope ?? '')) throw new Error(`invalid SDK package scope: ${generator.package_scope}`);
+    if (!Array.isArray(generator.audiences) || generator.audiences.length === 0 || generator.audiences.some((audience) => !['partner', 'public'].includes(audience))) {
+      throw new Error(`invalid SDK audiences for ${generator.id}`);
+    }
+  }
+  return registry;
+}
+
+export async function generateSDKPackages({ audience, contractSha256, document, gitRevision, service, toolVersions }) {
+  const registry = await readSDKGeneratorRegistry();
+  const packages = [];
+  for (const generator of registry.generators.filter((entry) => entry.audiences.includes(audience))) {
+    const adapter = adapters[generator.provider];
+    const packageName = `${generator.package_scope}/${service}-${audience}-sdk`;
+    packages.push(await adapter.generate({
+      apiVersion: document.info.version,
+      audience,
+      contractSha256,
+      document,
+      generator,
+      gitRevision,
+      packageName,
+      service,
+      toolVersions,
+    }));
+  }
+  return packages;
+}
+
+async function generateHeyAPISDK(context) {
+  const root = await mkdtemp(resolve(tmpdir(), 'onex-sdk-'));
+  const sourceRoot = resolve(root, 'src');
+  const packageRoot = resolve(root, 'package');
+  const outputRoot = resolve(packageRoot, 'src');
+  try {
+    await mkdir(sourceRoot, { recursive: true });
+    const inputPath = resolve(sourceRoot, 'openapi.json');
+    await writeFile(inputPath, canonicalJSON(context.document));
+    await createClient({
+      input: inputPath,
+      interactive: false,
+      logs: { file: false, level: 'silent' },
+      output: {
+        clean: true,
+        header: [],
+        module: { extension: '.js' },
+        path: outputRoot,
+        tsConfigPath: null,
+      },
+      plugins: [
+        { comments: false, enums: 'javascript', name: '@hey-api/typescript' },
+        { client: '@hey-api/client-fetch', comments: false, name: '@hey-api/sdk', paramsStructure: 'grouped' },
+        { name: '@hey-api/client-fetch', throwOnError: false },
+      ],
+    });
+    const entryPath = resolve(outputRoot, 'index.ts');
+    const entry = await readFile(entryPath, 'utf8');
+    await writeFile(entryPath, `${entry.trimEnd()}\nexport { client } from './client.gen.js';\n`);
+
+    const packageJSON = {
+      description: `${context.service} ${context.audience} TypeScript SDK`,
+      exports: {
+        '.': {
+          import: './dist/index.js',
+          types: './dist/index.d.ts',
+        },
+      },
+      files: ['dist', 'README.md', 'sdk-provenance.json'],
+      name: context.packageName,
+      private: true,
+      sideEffects: false,
+      type: 'module',
+      version: context.apiVersion,
+    };
+    const tsconfig = {
+      compilerOptions: {
+        declaration: true,
+        declarationMap: false,
+        lib: ['DOM', 'DOM.Iterable', 'ES2022'],
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        noEmitOnError: true,
+        noUncheckedIndexedAccess: true,
+        outDir: 'dist',
+        rootDir: 'src',
+        skipLibCheck: false,
+        strict: true,
+        target: 'ES2022',
+      },
+      include: ['src/**/*.ts'],
+    };
+    const examplePath = 'src/usage.example.ts';
+    const verificationCommand = 'tsc --project tsconfig.json --pretty false';
+    const provenance = {
+      api_version: context.apiVersion,
+      audience: context.audience,
+      contract_sha256: context.contractSha256,
+      evidence: {
+        code_example: {
+          command: verificationCommand,
+          path: examplePath,
+          status: 'passed',
+        },
+        typecheck: {
+          command: verificationCommand,
+          status: 'passed',
+        },
+      },
+      generator: context.generator.id,
+      git_revision: context.gitRevision,
+      package: context.packageName,
+      schema_version: 1,
+      service: context.service,
+      tool_versions: context.toolVersions,
+    };
+    const readme = sdkReadme(context);
+    const example = sdkUsageExample(context, './index.js');
+    await Promise.all([
+      writeFile(resolve(packageRoot, 'README.md'), readme),
+      writeFile(resolve(packageRoot, 'package.json'), canonicalJSON(packageJSON)),
+      writeFile(resolve(packageRoot, examplePath), example),
+      writeFile(resolve(packageRoot, 'tsconfig.json'), canonicalJSON(tsconfig)),
+    ]);
+    execFileSync(resolve(apiRoot, 'node_modules/.bin/tsc'), ['--project', resolve(packageRoot, 'tsconfig.json'), '--pretty', 'false'], {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    provenance.evidence.code_example.sha256 = sha256(example);
+    await writeFile(resolve(packageRoot, 'sdk-provenance.json'), canonicalJSON(provenance));
+
+    const files = new Map();
+    for (const path of await listFiles(packageRoot)) {
+      files.set(relative(packageRoot, path).replaceAll('\\', '/'), normalizeTextArtifact(await readFile(path)));
+    }
+    return {
+      files,
+      generator: context.generator.id,
+      evidence: provenance.evidence,
+      packageName: context.packageName,
+      packageVersion: context.apiVersion,
+      sourceContractSha256: context.contractSha256,
+    };
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+function normalizeTextArtifact(content) {
+  return Buffer.from(content.toString('utf8').replace(/[ \t]+$/gmu, ''));
+}
+
+function sdkReadme(context) {
+  return `# ${context.packageName}\n\n` +
+    `${context.service} 的 ${context.audience} 受众 TypeScript Fetch SDK，契约版本为 ${context.apiVersion}。\n\n` +
+    `该制品为私有的内部或合作方下载包，不声明公共 npm 发布许可。使用前必须按 release manifest 校验 SHA-256 与 sdk-provenance.json。\n\n` +
+    `## 安装\n\n` +
+    `下载并校验制品后，从本地目录安装：\n\n` +
+    '```bash\n' +
+    `pnpm add ./package.tgz\n` +
+    '```\n\n' +
+    `## 创建客户端\n\n` +
+    '```ts\n' +
+    sdkUsageExample(context, context.packageName) +
+    '```\n\n' +
+    `## 认证\n\n` +
+    `示例中的 \`configureClient\` 通过参数注入短期访问令牌；不得把凭证写入源码、日志或制品。\n\n` +
+    `## 错误处理\n\n` +
+    `示例检查 \`result.error\` 并携带 HTTP 状态抛出错误。发布流水线会对同一份示例执行 TypeScript 严格类型检查，证据记录在 \`sdk-provenance.json\`。\n\n` +
+    `生成的 operation 函数与类型均来自同一份 ${context.audience} OpenAPI 制品；调用参数以生成的类型声明为准。\n`;
+}
+
+function sdkUsageExample(context, importSpecifier) {
+  const operation = operationEntries(context.document)[0];
+  if (!operation) throw new Error(`${context.service}/${context.audience} SDK requires at least one operation`);
+  const requestPath = operation.path.replaceAll(/\{[^}]+\}/g, 'example-id');
+  return `import { client } from '${importSpecifier}';\n\n` +
+    `export function configureClient(accessToken: string): void {\n` +
+    `  client.setConfig({\n` +
+    `    auth: async () => accessToken,\n` +
+    `    baseUrl: 'https://api.example.com',\n` +
+    `  });\n` +
+    `}\n\n` +
+    `export async function requestExample(): Promise<unknown> {\n` +
+    `  const result = await client.${operation.method}({ url: '${requestPath}' });\n` +
+    `  if (result.error !== undefined) {\n` +
+    `    throw new Error(\`API request failed with status \${result.response?.status ?? 'unknown'}\`);\n` +
+    `  }\n` +
+    `  return result.data;\n` +
+    `}\n`;
+}
+
+async function listFiles(root) {
+  const result = [];
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const path = resolve(root, entry.name);
+    if (entry.isDirectory()) result.push(...await listFiles(path));
+    else if (entry.isFile()) result.push(path);
+  }
+  return result.sort();
+}

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

@@ -0,0 +1,64 @@
+const semanticVersionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+export function isSemanticVersion(value) {
+  if (typeof value !== 'string') return false;
+  const match = semanticVersionPattern.exec(value);
+  return match?.[0] === value;
+}
+
+export function parseSemanticVersion(value) {
+  if (typeof value !== 'string') throw new Error(`invalid semantic version: ${String(value)}`);
+  const match = semanticVersionPattern.exec(value);
+  if (!match || match[0] !== value) throw new Error(`invalid semantic version: ${value}`);
+  return Object.freeze({
+    build: Object.freeze(match[5]?.split('.') ?? []),
+    major: match[1],
+    minor: match[2],
+    patch: match[3],
+    prerelease: Object.freeze(match[4]?.split('.') ?? []),
+    raw: value,
+  });
+}
+
+export function compareSemanticVersions(left, right) {
+  const leftVersion = parseSemanticVersion(left);
+  const rightVersion = parseSemanticVersion(right);
+  for (const field of ['major', 'minor', 'patch']) {
+    const compared = compareNumericIdentifiers(leftVersion[field], rightVersion[field]);
+    if (compared !== 0) return compared;
+  }
+  return comparePrerelease(leftVersion.prerelease, rightVersion.prerelease);
+}
+
+function comparePrerelease(left, right) {
+  if (left.length === 0 || right.length === 0) {
+    if (left.length === right.length) return 0;
+    return left.length === 0 ? 1 : -1;
+  }
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    if (left[index] === undefined) return -1;
+    if (right[index] === undefined) return 1;
+    const leftNumeric = /^\d+$/.test(left[index]);
+    const rightNumeric = /^\d+$/.test(right[index]);
+    if (leftNumeric && rightNumeric) {
+      const compared = compareNumericIdentifiers(left[index], right[index]);
+      if (compared !== 0) return compared;
+      continue;
+    }
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    const compared = compareASCII(left[index], right[index]);
+    if (compared !== 0) return compared;
+  }
+  return 0;
+}
+
+function compareNumericIdentifiers(left, right) {
+  if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+  return compareASCII(left, right);
+}
+
+function compareASCII(left, right) {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}

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

@@ -0,0 +1,16 @@
+import { extname } from 'node:path';
+
+const serviceContractSourceExtensions = Object.freeze(['.json', '.yaml', '.yml']);
+
+export function isServiceContractBuildInput(path) {
+  const segments = path.replaceAll('\\', '/').split('/');
+  return !segments.includes('dist') && serviceContractSourceExtensions.includes(extname(path));
+}
+
+export function serviceContractReviewPathspecs(sourceRoot) {
+  return Object.freeze([
+    ...serviceContractSourceExtensions.map((extension) => `:(glob)${sourceRoot}/**/*${extension}`),
+    `:(glob,exclude)${sourceRoot}/conformance/**`,
+    `:(glob,exclude)${sourceRoot}/dist/**`,
+  ]);
+}

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

@@ -0,0 +1,365 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  buildComparisonPlan,
+  buildOASDiffArguments,
+  evaluateComparisonPolicy,
+  projectDocumentForOASDiff,
+  renderCompatibilityReportMarkdown,
+  semanticBreakingChanges,
+} from '../breaking.mjs';
+
+test('comparison plan rejects a service and audience slot removed from the protected base', () => {
+  const base = artifact();
+  const plan = buildComparisonPlan({
+    baseManifest: manifest([base]),
+    headManifest: manifest([]),
+  });
+
+  assert.deepEqual(plan.errors, [{
+    after: null,
+    before: `platform-api/public/1.0.0/${'a'.repeat(64)}`,
+    code: 'artifact_identity_removed',
+    identity: 'platform-api/public',
+  }]);
+});
+
+test('comparison plan compares a same-version content change and preserves both full identities', () => {
+  const base = artifact();
+  const head = artifact({ digest: 'b' });
+  const plan = buildComparisonPlan({
+    baseManifest: manifest([base]),
+    headManifest: manifest([head]),
+  });
+
+  assert.equal(plan.comparisons.length, 1);
+  assert.equal(
+    plan.comparisons[0].id,
+    `platform-api/public/1.0.0@${'a'.repeat(64)}->platform-api/public/1.0.0@${'b'.repeat(64)}`,
+  );
+  assert.equal(plan.comparisons[0].intentionalMajorVersionChange, false);
+  assert.deepEqual(plan.comparisons[0].origins, ['protected_base']);
+});
+
+test('comparison plan pairs version changes by service and audience slot', () => {
+  const plan = buildComparisonPlan({
+    baseManifest: manifest([artifact({ apiVersion: '1.2.3' })]),
+    headManifest: manifest([artifact({ apiVersion: '1.3.0', digest: 'b' })]),
+  });
+
+  assert.deepEqual(plan.errors, []);
+  assert.equal(plan.comparisons.length, 1);
+  assert.match(plan.comparisons[0].id, /^platform-api\/public\/1\.2\.3@.+->platform-api\/public\/1\.3\.0@/);
+});
+
+test('comparison plan rejects semantic version downgrades', () => {
+  for (const [baseVersion, headVersion] of [
+    ['1.1.0', '1.0.9'],
+    ['1.0.0', '1.0.0-rc.1'],
+  ]) {
+    const plan = buildComparisonPlan({
+      baseManifest: manifest([artifact({ apiVersion: baseVersion })]),
+      headManifest: manifest([artifact({ apiVersion: headVersion, digest: 'b' })]),
+    });
+    assert.deepEqual(plan.comparisons, []);
+    assert.deepEqual(plan.errors, [{
+      after: headVersion,
+      before: baseVersion,
+      code: 'artifact_version_downgraded',
+      identity: 'platform-api/public',
+    }]);
+  }
+});
+
+test('comparison plan ordering is deterministic across manifest input order', () => {
+  const base = [
+    artifact({ audience: 'partner', service: 'zeta-api' }),
+    artifact({ audience: 'public', service: 'alpha-api', digest: 'b' }),
+  ];
+  const head = [
+    artifact({ audience: 'partner', service: 'zeta-api', digest: 'c' }),
+    artifact({ audience: 'public', service: 'alpha-api', digest: 'd' }),
+  ];
+  const forward = buildComparisonPlan({ baseManifest: manifest(base), headManifest: manifest(head) });
+  const reverse = buildComparisonPlan({
+    baseManifest: manifest([...base].reverse()),
+    headManifest: manifest([...head].reverse()),
+  });
+
+  assert.deepEqual(reverse, forward);
+  assert.deepEqual(forward.comparisons.map((entry) => entry.base.service), ['alpha-api', 'zeta-api']);
+});
+
+test('semantic gate reports an operation removed from the contract', () => {
+  const findings = semanticBreakingChanges(document({ operationId: 'getWidget' }), { paths: {} });
+
+  assert.deepEqual(findings, [{
+    after: null,
+    before: 'getWidget',
+    code: 'operation_removed',
+    identity: 'GET /widgets/{id}',
+  }]);
+});
+
+test('semantic gate rejects operation identity and contract metadata regressions', () => {
+  const base = document({
+    operationId: 'getWidget',
+    'x-onex-audience': 'public',
+    'x-onex-lifecycle': lifecycle(),
+    'x-onex-stability': 'stable',
+  });
+  const head = document({
+    operationId: 'findWidget',
+    'x-onex-audience': 'partner',
+    'x-onex-lifecycle': lifecycle({ deprecated: '2026-08-01' }),
+    'x-onex-stability': 'beta',
+  });
+
+  assert.deepEqual(semanticBreakingChanges(base, head).map((entry) => entry.code), [
+    'audience_visibility_reduced',
+    'operation_id_changed',
+    'stability_reduced',
+  ]);
+});
+
+test('semantic gate allows additive lifecycle metadata and rejects mutation after publication', () => {
+  const baseLifecycle = lifecycle({ deprecated: '2026-08-01' });
+  const additive = lifecycle({
+    deprecated: '2026-08-01',
+    migrationUrl: 'https://docs.example.com/migrate',
+    replacementOperationId: 'getWidgetV2',
+    sunset: '2028-08-01',
+  });
+  assert.deepEqual(semanticBreakingChanges(document({
+    operationId: 'getWidget',
+    'x-onex-lifecycle': baseLifecycle,
+    'x-onex-stability': 'stable',
+  }), document({
+    operationId: 'getWidget',
+    'x-onex-lifecycle': additive,
+    'x-onex-stability': 'stable',
+  })), []);
+
+  const changed = semanticBreakingChanges(document({
+    operationId: 'getWidget',
+    'x-onex-lifecycle': additive,
+    'x-onex-stability': 'stable',
+  }), document({
+    operationId: 'getWidget',
+    'x-onex-lifecycle': lifecycle({ deprecated: '2026-09-01' }),
+    'x-onex-stability': 'stable',
+  }));
+  assert.ok(changed.some((entry) => entry.code === 'lifecycle_deprecated_changed'));
+});
+
+test('same-major removals fail for stable and zero-major version lines', () => {
+  const removal = semanticBreakingChanges(document({ operationId: 'getWidget' }), { paths: {} });
+  for (const [baseVersion, headVersion] of [
+    ['1.0.0', '1.1.0'],
+    ['0.1.0', '0.2.0'],
+  ]) {
+    const outcome = evaluateComparisonPolicy(comparison(baseVersion, headVersion), {
+      oasdiffBreaking: false,
+      semanticFindings: removal,
+    });
+    assert.equal(outcome.status, 'failed');
+    assert.deepEqual(outcome.errors.map((entry) => entry.code), ['operation_removed']);
+    assert.deepEqual(outcome.versionFindings, []);
+  }
+});
+
+test('same-version content changes still enforce operation removal policy', () => {
+  const removal = semanticBreakingChanges(document({ operationId: 'getWidget' }), { paths: {} });
+  const outcome = evaluateComparisonPolicy(comparison('1.0.0', '1.0.0'), {
+    oasdiffBreaking: true,
+    semanticFindings: removal,
+  });
+
+  assert.equal(outcome.status, 'failed');
+  assert.deepEqual(outcome.errors.map((entry) => entry.code), [
+    'oasdiff_breaking_change',
+    'operation_removed',
+  ]);
+  assert.deepEqual(outcome.versionFindings, []);
+});
+
+test('major version changes retain breaking findings without failing the gate', () => {
+  const removal = semanticBreakingChanges(document({ operationId: 'getWidget' }), { paths: {} });
+  const candidate = comparison('1.9.0', '2.0.0');
+  const outcome = evaluateComparisonPolicy(candidate, {
+    oasdiffBreaking: true,
+    semanticFindings: removal,
+  });
+
+  assert.deepEqual(outcome.errors, []);
+  assert.equal(outcome.status, 'intentional_major_version_change');
+  assert.deepEqual(outcome.versionFindings, [{
+    after: '2.0.0',
+    before: '1.9.0',
+    code: 'intentional_major_version_change',
+    identity: 'platform-api/public',
+  }]);
+});
+
+test('nonbreaking patch, minor, and major version changes pass', () => {
+  for (const headVersion of ['1.2.4', '1.3.0', '2.0.0']) {
+    const outcome = evaluateComparisonPolicy(comparison('1.2.3', headVersion), {
+      oasdiffBreaking: false,
+      semanticFindings: [],
+    });
+    assert.deepEqual(outcome.errors, []);
+    assert.equal(outcome.status, headVersion === '2.0.0' ? 'intentional_major_version_change' : 'compatible');
+  }
+});
+
+test('oasdiff arguments disable clock-dependent beta and stable deprecation windows', () => {
+  assert.deepEqual(buildOASDiffArguments('/tmp/base.json', '/tmp/head.json'), [
+    'breaking',
+    '/tmp/base.json',
+    '/tmp/head.json',
+    '--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',
+  ]);
+});
+
+test('oasdiff projection preserves OpenAPI data while adapting every boolean Schema slot', () => {
+  const source = {
+    components: {
+      schemas: {
+        ClosedChoice: {
+          additionalProperties: false,
+          oneOf: [
+            {
+              properties: {
+                forbidden: false,
+                unconstrained: true,
+                visible: { readOnly: true, type: 'boolean' },
+              },
+            },
+          ],
+        },
+      },
+    },
+    paths: {
+      '/closed': {
+        get: {
+          responses: {
+            200: {
+              content: {
+                'application/json': { schema: false },
+              },
+            },
+          },
+          'x-onex-evidence': { schema: false },
+        },
+      },
+    },
+  };
+
+  const projected = projectDocumentForOASDiff(source);
+
+  assert.deepEqual(projected.components.schemas.ClosedChoice.additionalProperties, { not: {} });
+  assert.deepEqual(projected.components.schemas.ClosedChoice.oneOf[0].properties.forbidden, { not: {} });
+  assert.deepEqual(projected.components.schemas.ClosedChoice.oneOf[0].properties.unconstrained, {});
+  assert.equal(projected.components.schemas.ClosedChoice.oneOf[0].properties.visible.readOnly, true);
+  assert.deepEqual(projected.paths['/closed'].get.responses[200].content['application/json'].schema, { not: {} });
+  assert.deepEqual(projected.paths['/closed'].get['x-onex-evidence'], { schema: false });
+  assert.equal(source.components.schemas.ClosedChoice.additionalProperties, false);
+});
+
+test('Markdown evidence separates allowed major-version findings from gate errors', () => {
+  const candidate = comparison('1.0.0', '2.0.0');
+  const removal = semanticBreakingChanges(document({ operationId: 'getWidget' }), { paths: {} });
+  const outcome = evaluateComparisonPolicy(candidate, {
+    oasdiffBreaking: true,
+    semanticFindings: removal,
+  });
+  const markdown = renderCompatibilityReportMarkdown({
+    base_revision: 'a'.repeat(40),
+    candidate_revision: 'b'.repeat(40),
+    comparisons: [{
+      base_api_version: candidate.base.api_version,
+      base_sha256: candidate.base.sha256,
+      head_api_version: candidate.head.api_version,
+      head_sha256: candidate.head.sha256,
+      id: candidate.id,
+      oasdiff: [{ id: 'paths' }],
+      oasdiff_breaking: true,
+      origins: candidate.origins,
+      semantic_findings: removal,
+      status: outcome.status,
+      version_findings: outcome.versionFindings,
+    }],
+    errors: outcome.errors,
+    fingerprint: 'c'.repeat(64),
+    schema_version: 1,
+    tool_versions: { oasdiff: '1.23.0' },
+  });
+
+  assert.match(markdown, /oasdiff breaking=yes, findings=1/);
+  assert.match(markdown, /OneX semantic=operation_removed/);
+  assert.match(markdown, /version=intentional_major_version_change/);
+  assert.match(markdown, /No gate-blocking compatibility findings\./);
+  assert.doesNotMatch(markdown, /No compatibility findings\./);
+});
+
+function comparison(baseVersion, headVersion) {
+  const plan = buildComparisonPlan({
+    baseManifest: manifest([artifact({ apiVersion: baseVersion })]),
+    headManifest: manifest([artifact({ apiVersion: headVersion, digest: 'b' })]),
+  });
+  assert.deepEqual(plan.errors, []);
+  assert.equal(plan.comparisons.length, 1);
+  return plan.comparisons[0];
+}
+
+function artifact({
+  apiVersion = '1.0.0',
+  audience = 'public',
+  digest = 'a',
+  service = 'platform-api',
+} = {}) {
+  return {
+    api_version: apiVersion,
+    audience,
+    path: `services/${service}/dist/${audience}.openapi.json`,
+    service,
+    sha256: digest.repeat(64),
+  };
+}
+
+function manifest(artifacts) {
+  return { artifacts, schema_version: 1 };
+}
+
+function document(operation) {
+  return {
+    paths: {
+      '/widgets/{id}': {
+        get: operation,
+      },
+    },
+  };
+}
+
+function lifecycle(overrides = {}) {
+  return {
+    deprecated: null,
+    introduced: '2026-07-16',
+    migrationUrl: null,
+    replacementOperationId: null,
+    sunset: null,
+    ...overrides,
+  };
+}