Refactor code structure for improved readability and maintainability; removed redundant code blocks and optimized function calls.

scripts/api-compat-diff.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * API compatibility diff tool
+ * Compares two OpenAPI 3.x specs (YAML or JSON) and reports additive vs breaking changes.
+ *
+ * Usage:
+ *   node scripts/api-compat-diff.mjs <oldSpec> <newSpec> [--output json|text] [--fail-on-breaking]
+ *
+ * Output (text):
+ *   - Added operations (additive)
+ *   - Removed operations (breaking)
+ *   - Added responses (additive)
+ *   - Removed responses (breaking)
+ *
+ * Output (json):
+ *   {
+ *     additive: { operations: [...], responses: [...] },
+ *     breaking: { operations: [...], responses: [...] }
+ *   }
+ *
+ * Exit codes:
+ *   0  => success
+ *   1  => invalid/missing args or IO/parsing error
+ *   2  => breaking changes detected with --fail-on-breaking
+ */
+
+import fs from 'fs';
+import path from 'path';
+import process from 'process';
+import yaml from 'yaml';
+
+function panic(message) {
+  console.error(`[api-compat-diff] ${message}`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = { output: 'text', failOnBreaking: false };
+
+  if (args.length < 2) {
+    panic('Usage: node scripts/api-compat-diff.mjs <oldSpec> <newSpec> [--output json|text] [--fail-on-breaking]');
+  }
+
+  [opts.oldSpec, opts.newSpec] = args.slice(0, 2);
+
+  for (let i = 2; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--output' && args[i + 1]) {
+      opts.output = args[i + 1].toLowerCase();
+      i += 1;
+    } else if (arg === '--fail-on-breaking') {
+      opts.failOnBreaking = true;
+    }
+  }
+
+  if (!['text', 'json'].includes(opts.output)) {
+    panic(`Unsupported output mode: ${opts.output}`);
+  }
+
+  return opts;
+}
+
+function loadSpec(specPath) {
+  if (!fs.existsSync(specPath)) {
+    panic(`Spec not found: ${specPath}`);
+  }
+
+  const raw = fs.readFileSync(specPath, 'utf8');
+  const ext = path.extname(specPath).toLowerCase();
+
+  try {
+    if (ext === '.json') {
+      return JSON.parse(raw);
+    }
+    return yaml.parse(raw);
+  } catch (err) {
+    panic(`Failed to parse ${specPath}: ${err.message}`);
+  }
+}
+
+function enumerateOperations(spec) {
+  const ops = new Map();
+  if (!spec?.paths || typeof spec.paths !== 'object') {
+    return ops;
+  }
+
+  for (const [pathKey, pathItem] of Object.entries(spec.paths)) {
+    if (!pathItem || typeof pathItem !== 'object') {
+      continue;
+    }
+    for (const method of Object.keys(pathItem)) {
+      const lowerMethod = method.toLowerCase();
+      if (!['get', 'put', 'post', 'delete', 'patch', 'head', 'options', 'trace'].includes(lowerMethod)) {
+        continue;
+      }
+      const opId = `${lowerMethod} ${pathKey}`;
+      const responses = pathItem[method]?.responses ?? {};
+      ops.set(opId, {
+        method: lowerMethod,
+        path: pathKey,
+        responses: new Set(Object.keys(responses)),
+      });
+    }
+  }
+
+  return ops;
+}
+
+function diffOperations(oldOps, newOps) {
+  const additiveOps = [];
+  const breakingOps = [];
+  const additiveResponses = [];
+  const breakingResponses = [];
+
+  // Operations added or removed
+  for (const [id, op] of newOps.entries()) {
+    if (!oldOps.has(id)) {
+      additiveOps.push(id);
+    }
+  }
+
+  for (const [id] of oldOps.entries()) {
+    if (!newOps.has(id)) {
+      breakingOps.push(id);
+    }
+  }
+
+  // Response-level diffs for shared operations
+  for (const [id, newOp] of newOps.entries()) {
+    if (!oldOps.has(id)) continue;
+    const oldOp = oldOps.get(id);
+
+    for (const code of newOp.responses) {
+      if (!oldOp.responses.has(code)) {
+        additiveResponses.push(`${id} -> ${code}`);
+      }
+    }
+
+    for (const code of oldOp.responses) {
+      if (!newOp.responses.has(code)) {
+        breakingResponses.push(`${id} -> ${code}`);
+      }
+    }
+  }
+
+  return {
+    additive: {
+      operations: additiveOps.sort(),
+      responses: additiveResponses.sort(),
+    },
+    breaking: {
+      operations: breakingOps.sort(),
+      responses: breakingResponses.sort(),
+    },
+  };
+}
+
+function renderText(diff) {
+  const lines = [];
+  lines.push('Additive:');
+  lines.push(`  Operations: ${diff.additive.operations.length}`);
+  diff.additive.operations.forEach((op) => lines.push(`    + ${op}`));
+  lines.push(`  Responses: ${diff.additive.responses.length}`);
+  diff.additive.responses.forEach((resp) => lines.push(`    + ${resp}`));
+  lines.push('Breaking:');
+  lines.push(`  Operations: ${diff.breaking.operations.length}`);
+  diff.breaking.operations.forEach((op) => lines.push(`    - ${op}`));
+  lines.push(`  Responses: ${diff.breaking.responses.length}`);
+  diff.breaking.responses.forEach((resp) => lines.push(`    - ${resp}`));
+  return lines.join('\n');
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  const oldSpec = loadSpec(opts.oldSpec);
+  const newSpec = loadSpec(opts.newSpec);
+
+  const diff = diffOperations(enumerateOperations(oldSpec), enumerateOperations(newSpec));
+
+  if (opts.output === 'json') {
+    console.log(JSON.stringify(diff, null, 2));
+  } else {
+    console.log(renderText(diff));
+  }
+
+  if (opts.failOnBreaking && (diff.breaking.operations.length > 0 || diff.breaking.responses.length > 0)) {
+    process.exit(2);
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}