@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,346 @@
+import { isPlainObject, operationEntries } from './project.mjs';
+import { documentationProjectionVersion, resolveReference } from './documentation_projection.mjs';
+import {
+  isEmailExampleKey,
+  isSafeSensitiveExampleValue,
+  isSensitiveExampleKey,
+} from './documentation_example_privacy.mjs';
+
+export const documentationQualityRulesetVersion = 2;
+
+const requiredMetrics = Object.freeze([
+  'operation_descriptions',
+  'parameter_descriptions',
+  'request_body_descriptions',
+  'response_descriptions',
+  'schema_property_descriptions',
+  'named_media_examples',
+  'owner_evidence',
+  'lifecycle_evidence',
+  'last_reviewed_at_evidence',
+  'review_digest_evidence',
+  'freshness_evidence',
+  'openapi_link_evidence',
+  'documentation_link_validity',
+  'error_evidence',
+  'sdk_typecheck_evidence',
+  'code_example_evidence',
+  'source_contract_evidence',
+]);
+
+export async function analyzeDocumentationQuality({
+  audience,
+  canonicalDocument,
+  document,
+  linkChecker = checkDocumentationURL,
+  service,
+  sdkEvidence = [],
+  sourceContractSha256,
+  sourceSha256,
+}) {
+  const metrics = Object.fromEntries(requiredMetrics.map((name) => [name, createMetric()]));
+  const canonicalOperations = new Map(operationEntries(canonicalDocument).map(({ operation }) => [operation.operationId, operation]));
+
+  for (const { method, operation, path, pathItem } of operationEntries(document)) {
+    const label = `${method.toUpperCase()} ${path}`;
+    cover(metrics.operation_descriptions, hasText(operation.description), label, isGenerated(operation));
+
+    const parameters = [...(pathItem.parameters ?? []), ...(operation.parameters ?? [])];
+    for (const [index, reference] of parameters.entries()) {
+      const parameter = resolveReference(document, reference);
+      cover(metrics.parameter_descriptions, hasText(parameter?.description), `${label} parameter[${index}]`, isGenerated(parameter));
+    }
+
+    const requestBody = resolveReference(document, operation.requestBody);
+    if (requestBody) {
+      cover(metrics.request_body_descriptions, hasText(requestBody.description), `${label} requestBody`, isGenerated(requestBody));
+      inspectMediaExamples(metrics.named_media_examples, document, requestBody.content, `${label} requestBody`);
+    }
+
+    for (const [status, reference] of Object.entries(operation.responses ?? {})) {
+      const response = resolveReference(document, reference);
+      cover(metrics.response_descriptions, hasText(response?.description), `${label} response ${status}`, isGenerated(response));
+      inspectMediaExamples(metrics.named_media_examples, document, response?.content, `${label} response ${status}`);
+      if (/^[45]/.test(status)) {
+        const hasSchemaEvidence = Object.values(response?.content ?? {}).some((media) => media?.schema);
+        const hasEmptyMethodEvidence = status === '405' && response?.headers?.Allow;
+        cover(metrics.error_evidence, hasText(response?.description) && Boolean(hasSchemaEvidence || hasEmptyMethodEvidence), `${label} error ${status}`, false);
+      }
+      for (const [name, linkReference] of Object.entries(response?.links ?? {})) {
+        const link = resolveReference(document, linkReference);
+        cover(
+          metrics.openapi_link_evidence,
+          validOpenAPILink(link, document),
+          `${label} response ${status} link ${name}`,
+          false,
+        );
+      }
+    }
+
+    const canonical = canonicalOperations.get(operation.operationId);
+    cover(metrics.owner_evidence, hasText(operation['x-onex-owner']) && operation['x-onex-owner'] === canonical?.['x-onex-owner'], label, false);
+    const lifecycle = canonical?.['x-onex-lifecycle'];
+    if (canonical?.['x-onex-audience'] !== 'internal') {
+      cover(metrics.lifecycle_evidence, validLifecycle(lifecycle), label, false);
+    }
+    const review = operation['x-onex-review-provenance'];
+    cover(metrics.last_reviewed_at_evidence, validDate(operation['x-onex-last-reviewed-at']) && operation['x-onex-last-reviewed-at'] === review?.last_reviewed_at, label, false);
+    cover(metrics.review_digest_evidence, review?.validation === 'passed' && validDigest(review?.operation_sha256), label, false);
+    cover(metrics.freshness_evidence, review?.freshness === 'current' && validDate(review?.expires_at), label, false);
+    if (lifecycle?.deprecated) {
+      cover(
+        metrics.openapi_link_evidence,
+        hasText(lifecycle.replacementOperationId) || validURL(lifecycle.migrationUrl),
+        `${label} deprecated lifecycle`,
+        false,
+      );
+    }
+  }
+
+  for (const [schemaName, schema] of Object.entries(document.components?.schemas ?? {})) {
+    inspectSchemaProperties(metrics.schema_property_descriptions, schema, `schema ${schemaName}`, new Set());
+  }
+
+  const linkChecks = [];
+  for (const link of collectDocumentationLinks(document)) {
+    const result = await linkChecker(link.url);
+    linkChecks.push({ ...link, ...result });
+    cover(metrics.documentation_link_validity, result.passed === true, `${link.location} ${link.url}`, false);
+  }
+
+  if (audience !== 'internal') {
+    cover(
+      metrics.sdk_typecheck_evidence,
+      sdkEvidence.length > 0 && sdkEvidence.every((entry) => entry.typecheck?.status === 'passed'),
+      `${service}/${audience} SDK typecheck`,
+      false,
+    );
+    cover(
+      metrics.code_example_evidence,
+      sdkEvidence.length > 0 && sdkEvidence.every((entry) => entry.code_example?.status === 'passed' && validDigest(entry.code_example?.sha256)),
+      `${service}/${audience} SDK code example`,
+      false,
+    );
+  }
+  cover(metrics.source_contract_evidence, validDigest(sourceContractSha256), `${service}/${audience} source contract`, false);
+
+  const violations = Object.entries(metrics).flatMap(([metric, value]) => value.missing.map((location) => ({
+    code: `missing_${metric}`,
+    location,
+    metric,
+  })));
+  for (const metric of Object.values(metrics)) finalizeMetric(metric);
+  const passed = requiredMetrics.every((name) => metrics[name].percentage === 100) && violations.length === 0;
+  if (!passed) {
+    const details = violations.slice(0, 100).map((violation) => `${violation.code}: ${violation.location}`).join('\n- ');
+    const suffix = violations.length > 100 ? `\n- ${violations.length - 100} additional violation(s)` : '';
+    throw new Error(`${service}/${audience} documentation quality gate failed with ${violations.length} violation(s):\n- ${details}${suffix}`);
+  }
+
+  return {
+    audience,
+    gate: { passed, policy: 'all_applicable_metrics_100_percent' },
+    link_checks: linkChecks,
+    metrics,
+    projection_version: documentationProjectionVersion,
+    ruleset_version: documentationQualityRulesetVersion,
+    service,
+    source_contract_sha256: sourceContractSha256,
+    canonical_source_sha256: sourceSha256,
+    violations,
+  };
+}
+
+async function checkDocumentationURL(value) {
+  return validURL(value)
+    ? { passed: true, validation: 'absolute_http_uri' }
+    : { passed: false, validation: 'invalid_uri' };
+}
+
+function collectDocumentationLinks(document) {
+  const links = new Map();
+  const add = (url, location) => {
+    if (!hasText(url)) return;
+    const key = `${location}\0${url}`;
+    links.set(key, { location, url });
+  };
+  add(document.externalDocs?.url, 'externalDocs');
+  for (const [index, tag] of (document.tags ?? []).entries()) add(tag.externalDocs?.url, `tags[${index}].externalDocs`);
+  walk(document, (value, key, location, parent) => {
+    if (key === 'description' && typeof value === 'string') {
+      for (const url of extractDescriptionURLs(value)) add(url, location);
+    }
+    if (key === 'externalValue') add(value, location);
+    if (key === 'migrationUrl' && parent?.deprecated) add(value, location);
+    if (key === 'url' && parent === document.externalDocs) add(value, location);
+  });
+  for (const { method, operation, path } of operationEntries(document)) {
+    add(operation.externalDocs?.url, `${method.toUpperCase()} ${path} externalDocs`);
+  }
+  return [...links.values()].sort((left, right) => `${left.location}\0${left.url}`.localeCompare(`${right.location}\0${right.url}`));
+}
+
+function extractDescriptionURLs(value) {
+  const result = [];
+  for (const match of value.matchAll(/https?:\/\/[^\s<>"'`\])}]+/gu)) result.push(match[0].replace(/[.,;:!?]+$/u, ''));
+  for (const match of value.matchAll(/\[[^\]]+\]\(([^)]+)\)/gu)) {
+    if (!/^https?:\/\//u.test(match[1])) result.push(match[1]);
+  }
+  return result;
+}
+
+function inspectMediaExamples(metric, document, content, label) {
+  for (const [mediaType, media] of Object.entries(content ?? {})) {
+    if (!media?.schema) continue;
+    const examples = Object.entries(media.examples ?? {});
+    const valid = examples.length > 0 && examples.every(([, reference]) => {
+      const example = resolveReference(document, reference);
+      if (!example || (!Object.hasOwn(example, 'value') && !hasText(example.externalValue))) return false;
+      const provenance = example['x-onex-example-provenance'];
+      return hasText(provenance?.generator) && hasText(provenance?.schema_pointer) &&
+        validDigest(provenance?.schema_sha256) && validDigest(provenance?.source_sha256) &&
+        !containsSensitiveData(example.value, '', media.schema, document);
+    });
+    cover(metric, valid, `${label} ${mediaType}`, examples.some(([, reference]) => isGenerated(resolveReference(document, reference))));
+  }
+}
+
+function inspectSchemaProperties(metric, schema, label, visited) {
+  if (!isPlainObject(schema) || visited.has(schema)) return;
+  visited.add(schema);
+  for (const [name, property] of Object.entries(schema.properties ?? {})) {
+    if (!isPlainObject(property)) continue;
+    const propertyLabel = `${label}.${name}`;
+    cover(metric, hasText(property.description), propertyLabel, isGenerated(property));
+    inspectSchemaProperties(metric, property, propertyLabel, visited);
+  }
+  if (schema.items) inspectSchemaProperties(metric, schema.items, `${label}[]`, visited);
+  for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+    for (const [index, child] of (schema[keyword] ?? []).entries()) {
+      inspectSchemaProperties(metric, child, `${label}.${keyword}[${index}]`, visited);
+    }
+  }
+  visited.delete(schema);
+}
+
+function validOpenAPILink(link, document) {
+  if (!link || typeof link !== 'object') return false;
+  if (hasText(link.operationId)) return operationEntries(document).some(({ operation }) => operation.operationId === link.operationId);
+  if (!hasText(link.operationRef)) return false;
+  if (!link.operationRef.startsWith('#/paths/')) return validURL(link.operationRef);
+  const parts = link.operationRef.split('/');
+  const path = decodePointer(parts[2] ?? '');
+  return Boolean(document.paths?.[path]?.[parts[3]]);
+}
+
+function createMetric() {
+  return { covered: 0, generated: 0, missing: [], percentage: 100, total: 0 };
+}
+
+function cover(metric, condition, location, generated) {
+  metric.total += 1;
+  if (condition) {
+    metric.covered += 1;
+    if (generated) metric.generated += 1;
+  } else {
+    metric.missing.push(location);
+  }
+}
+
+function finalizeMetric(metric) {
+  metric.percentage = metric.total === 0 ? 100 : Number(((metric.covered / metric.total) * 100).toFixed(4));
+  delete metric.missing;
+}
+
+function validLifecycle(value) {
+  return value && validDate(value.introduced) && Object.hasOwn(value, 'deprecated') && Object.hasOwn(value, 'sunset') &&
+    Object.hasOwn(value, 'replacementOperationId') && Object.hasOwn(value, 'migrationUrl');
+}
+
+function validDate(value) {
+  return /^\d{4}-\d{2}-\d{2}$/.test(value ?? '') && !Number.isNaN(Date.parse(`${value}T00:00:00Z`));
+}
+
+function validDigest(value) {
+  return /^[a-f0-9]{64}$/.test(value ?? '');
+}
+
+function validURL(value) {
+  if (!hasText(value)) return false;
+  try {
+    return ['https:', 'http:'].includes(new URL(value).protocol);
+  } catch {
+    return false;
+  }
+}
+
+function containsSensitiveData(value, key = '', schema = {}, document = null) {
+  const resolvedSchema = document ? resolveReference(document, schema) ?? {} : schema;
+  if (Array.isArray(value)) {
+    return value.some((entry) => containsSensitiveData(entry, key, resolvedSchema.items ?? {}, document));
+  }
+  if (value && typeof value === 'object') {
+    return Object.entries(value).some(([name, entry]) => containsSensitiveData(
+      entry,
+      name,
+      examplePropertySchema(document, resolvedSchema, name),
+      document,
+    ));
+  }
+  if (typeof value !== 'string') return false;
+  const normalized = key.toLowerCase();
+  if (isSensitiveExampleKey(key)) return !isSafeSensitiveExampleValue(value, resolvedSchema);
+  if (isEmailExampleKey(key) || /^[^\s@]+@[^\s@]+$/.test(value)) return !value.endsWith('@example.com');
+  if (/(url|uri|link)$/.test(normalized) || /^https?:\/\//.test(value)) {
+    try {
+      return !new URL(value).hostname.endsWith('example.com');
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
+
+function examplePropertySchema(document, schema, propertyName) {
+  if (schema.properties?.[propertyName]) return schema.properties[propertyName];
+  for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+    for (const child of schema[keyword] ?? []) {
+      const resolvedChild = document ? resolveReference(document, child) ?? {} : child;
+      const property = examplePropertySchema(document, resolvedChild, propertyName);
+      if (Object.keys(property).length > 0) return property;
+    }
+  }
+  return schema.additionalProperties && typeof schema.additionalProperties === 'object'
+    ? schema.additionalProperties
+    : {};
+}
+
+function isGenerated(value) {
+  const documentation = value?.['x-onex-documentation-provenance'];
+  const example = value?.['x-onex-example-provenance'];
+  return documentation?.description_source === 'generated' || example?.source === 'schema';
+}
+
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function walk(value, callback, location = '$', parent = null) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => {
+      callback(entry, String(index), `${location}[${index}]`, value);
+      walk(entry, callback, `${location}[${index}]`, value);
+    });
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  for (const [key, entry] of Object.entries(value)) {
+    const childLocation = `${location}.${key}`;
+    callback(entry, key, childLocation, value);
+    walk(entry, callback, childLocation, value);
+  }
+}
+
+function decodePointer(value) {
+  return value.replaceAll('~1', '/').replaceAll('~0', '~');
+}

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

@@ -0,0 +1,188 @@
+import { execFileSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+
+import { apiRoot, isSafeRelativePath, readStructured, sha256 } from './project.mjs';
+import { isSemanticVersion } from './semantic_version.mjs';
+
+export const repositoryRoot = locateRepositoryRoot(apiRoot);
+const apiRepositoryPath = relative(repositoryRoot, apiRoot).replaceAll('\\', '/');
+export const manifestRepositoryPath = `${apiRepositoryPath}/dist/artifact-manifest.json`;
+
+function locateRepositoryRoot(start) {
+  let current = start;
+  while (dirname(current) !== current) {
+    if (existsSync(resolve(current, '.git'))) return current;
+    current = dirname(current);
+  }
+  return resolve(apiRoot, '../..');
+}
+
+export async function readCurrentManifest() {
+  const manifest = await readStructured(resolve(apiRoot, 'dist/artifact-manifest.json'));
+  validateArtifactManifest(manifest, 'working tree artifact manifest');
+  return manifest;
+}
+
+export function readManifestAtRevision(revision) {
+  const source = readFileAtRevision(revision, manifestRepositoryPath, { allowMissing: true });
+  if (source === null) return null;
+  const manifest = parseJSON(source, `${revision}:${manifestRepositoryPath}`);
+  validateArtifactManifest(manifest, `${revision} artifact manifest`);
+  return manifest;
+}
+
+export function readHistoricalManifests() {
+  const output = git(['log', '--full-history', '--format=%H', 'HEAD', '--', manifestRepositoryPath], { allowFailure: true });
+  if (!output) return [];
+  const result = [];
+  for (const revision of [...new Set(output.split('\n').filter(Boolean))]) {
+    const manifest = readManifestAtRevision(revision);
+    if (manifest) result.push({ manifest, revision });
+  }
+  return result;
+}
+
+export async function resolveProtectedBaseRevision() {
+  const eventRevision = await revisionFromGitHubEvent();
+  if (eventRevision) return mergeBase(eventRevision);
+
+  const target = git(['rev-parse', '--verify', 'refs/remotes/origin/main'], { allowFailure: true });
+  if (target) {
+    const base = mergeBase(target);
+    const head = git(['rev-parse', 'HEAD']);
+    if (base !== head) return base;
+  }
+
+  const parent = git(['rev-parse', '--verify', 'HEAD^'], { allowFailure: true });
+  if (parent) return parent;
+  throw new Error('unable to derive the protected comparison base');
+}
+
+export function currentRevision() {
+  return git(['rev-parse', 'HEAD']);
+}
+
+export function readFileAtRevision(revision, repositoryPath, { allowMissing = false } = {}) {
+  assertRevision(revision);
+  if (!isSafeRepositoryPath(repositoryPath)) throw new Error(`unsafe repository path: ${repositoryPath}`);
+  return git(['show', `${revision}:${repositoryPath}`], { allowFailure: allowMissing, trim: false });
+}
+
+export async function readCurrentArtifact(record) {
+  validateArtifactRecord(record, 'working tree artifact');
+  const content = await readFile(resolve(apiRoot, record.path));
+  verifyArtifactDigest(content, record, 'working tree artifact');
+  return content;
+}
+
+export function readHistoricalArtifact(record, revision) {
+  validateArtifactRecord(record, `${revision} artifact`);
+  const content = Buffer.from(readFileAtRevision(revision, `${apiRepositoryPath}/${record.path}`));
+  verifyArtifactDigest(content, record, `${revision} artifact`);
+  return content;
+}
+
+export function validateArtifactManifest(manifest, label = 'artifact manifest') {
+  if (manifest?.schema_version !== 1 || !Array.isArray(manifest.artifacts)) {
+    throw new Error(`${label} must declare schema_version 1 and artifacts`);
+  }
+  const seen = new Set();
+  const ordered = [];
+  for (const record of manifest.artifacts) {
+    validateArtifactRecord(record, label);
+    const key = artifactSlotKey(record);
+    if (seen.has(key)) throw new Error(`${label} contains duplicate artifact ${key}`);
+    seen.add(key);
+    ordered.push(`${record.service}\0${record.audience}`);
+  }
+  if (ordered.join('\n') !== [...ordered].sort().join('\n')) {
+    throw new Error(`${label} artifacts must be sorted by service and audience`);
+  }
+}
+
+export function validateArtifactRecord(record, label = 'artifact') {
+  if (!/^[a-z][a-z0-9-]*$/.test(record?.service ?? '') || !['internal', 'partner', 'public'].includes(record?.audience)) {
+    throw new Error(`${label} has an invalid service or audience`);
+  }
+  if (!isSemanticVersion(record.api_version) || !/^[a-f0-9]{64}$/.test(record.sha256 ?? '')) {
+    throw new Error(`${label} has an invalid API version or SHA-256`);
+  }
+  const expectedPath = `services/${record.service}/dist/${record.audience}.openapi.json`;
+  if (!isSafeRelativePath(record.path) || record.path !== expectedPath) {
+    throw new Error(`${label} has an invalid artifact path`);
+  }
+}
+
+export function artifactVersionKey(record) {
+  return `${artifactSlotKey(record)}/${record.api_version}`;
+}
+
+export function artifactSlotKey(record) {
+  if (!isContractArtifact(record)) throw new Error(`artifact ${record?.kind ?? 'unknown'} is not an OpenAPI contract`);
+  return `${record.service}/${record.audience}`;
+}
+
+export function artifactContentIdentity(record) {
+  return `${artifactVersionKey(record)}/${record.sha256}`;
+}
+
+export function contractArtifacts(manifest) {
+  return (manifest?.artifacts ?? []).filter(isContractArtifact);
+}
+
+export function isContractArtifact(record) {
+  return record?.kind === 'openapi-contract' || record?.kind === undefined;
+}
+
+function verifyArtifactDigest(content, record, label) {
+  if (sha256(content) !== record.sha256) throw new Error(`${label} SHA-256 does not match its manifest`);
+}
+
+async function revisionFromGitHubEvent() {
+  const path = process.env.GITHUB_EVENT_PATH;
+  if (!path) return null;
+  const event = parseJSON(await readFile(path, 'utf8'), 'GitHub event');
+  const candidate = event.pull_request?.base?.sha ?? event.merge_group?.base_sha ?? event.before ?? null;
+  if (!candidate || /^0+$/.test(candidate)) return null;
+  assertRevision(candidate);
+  return candidate;
+}
+
+function mergeBase(revision) {
+  assertRevision(revision);
+  return git(['merge-base', 'HEAD', revision]);
+}
+
+function assertRevision(revision) {
+  if (!/^[a-f0-9]{40}$/.test(revision ?? '')) throw new Error(`invalid Git revision: ${revision}`);
+}
+
+function isSafeRepositoryPath(path) {
+  return typeof path === 'string' && path.length > 0 && !path.startsWith('/') && !path.split('/').includes('..');
+}
+
+function parseJSON(source, label) {
+  try {
+    return JSON.parse(source);
+  } catch (error) {
+    throw new Error(`invalid ${label}: ${error.message}`);
+  }
+}
+
+function git(args, { allowFailure = false, trim = true } = {}) {
+  try {
+    const output = execFileSync('git', args, {
+      cwd: repositoryRoot,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', allowFailure ? 'ignore' : 'pipe'],
+    });
+    return trim ? output.trimEnd() : output;
+  } catch (error) {
+    if (allowFailure) return null;
+    const detail = error.stderr?.toString().trim();
+    throw new Error(`git ${args.join(' ')} failed${detail ? `: ${detail}` : ''}`);
+  }
+}