specshield 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deepak Satyam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# SpecShield CLI
+
+> Compare OpenAPI specs and detect breaking changes — designed for CI/CD and local developer workflows.
+
+## Features
+
+- Detect breaking changes, additions, and modifications between two OpenAPI specs
+- Support YAML and JSON specs
+- CI/CD-ready with exit code control (`--fail-on-breaking`)
+- Config file support (`.specshield.yml`)
+- JSON output for machine parsing
+- Ignore list to suppress known changes
+- Placeholder remote mode for future SaaS backend integration
+
+## Installation
+
+```bash
+npm install -g specshield
+# or use locally:
+npm install && npm link
+```
+
+## Usage
+
+### Basic comparison
+```bash
+specshield compare base.yaml target.yaml
+```
+
+### Fail CI on breaking changes
+```bash
+specshield compare base.yaml target.yaml --fail-on-breaking
+```
+
+### JSON output (for scripts/automation)
+```bash
+specshield compare base.yaml target.yaml --json
+```
+
+### Save results to file
+```bash
+specshield compare base.yaml target.yaml --output result.json
+```
+
+### Ignore specific changes
+```bash
+specshield compare base.yaml target.yaml --ignore "DELETE /users removed" --fail-on-breaking
+```
+
+### Use custom config
+```bash
+specshield compare base.yaml target.yaml --config ./configs/.specshield.yml
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--json` | Output machine-readable JSON |
+| `--output <file>` | Save result to file |
+| `--fail-on-breaking` | Exit 1 if breaking changes found |
+| `--allow-breaking` | Override fail behavior |
+| `--config <path>` | Path to `.specshield.yml` |
+| `--ignore <change>` | Ignore a change string (repeatable) |
+| `--severity <level>` | `info` / `warning` / `error` |
+| `--remote-url <url>` | Remote API endpoint (future mode) |
+| `--timeout <ms>` | Timeout for remote requests |
+
+## Config File
+
+Create `.specshield.yml` in your project root:
+
+```yaml
+allowBreakingChanges: false
+failOnBreaking: true
+
+ignore:
+  - "User.email removed"
+  - "/admin DELETE removed"
+
+severity: error
+
+remote:
+  enabled: false
+  url: "https://api.specshield.io/compare"
+  timeout: 10000
+```
+
+> CLI arguments always override config file values.
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success — no blocking issues |
+| `1` | Breaking changes found and `--fail-on-breaking` active |
+| `2` | Invalid input, config error, or runtime error |
+
+## CI/CD — GitHub Actions
+
+```yaml
+name: API Contract Check
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  check-api-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - run: npm install -g specshield
+
+      # Option A: spec files are committed to the repo
+      - name: Get base spec from main branch
+        run: git show origin/main:api/openapi.yaml > /tmp/base-spec.yaml
+
+      - name: Compare specs
+        run: |
+          specshield compare /tmp/base-spec.yaml api/openapi.yaml \
+            --fail-on-breaking \
+            --output spec-diff.json
+
+      - name: Upload diff report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: spec-diff
+          path: spec-diff.json
+```
+
+> **Note:** Some projects generate their OpenAPI spec dynamically (e.g. from Spring Boot annotations, FastAPI, etc.) instead of storing a static file. In that case, add a build step before the compare step to generate the spec from your code.
+
+## Running Locally
+
+```bash
+npm install
+npm link
+specshield compare fixtures/spec-v1.yaml fixtures/spec-v2.yaml --fail-on-breaking
+```
+
+## Running Tests
+
+```bash
+npm test
+```
+
+## License
+
+MIT © Deepak Satyam

package/bin/specshield.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/cli');

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "specshield",
+  "version": "1.0.0",
+  "description": "CLI tool to compare OpenAPI specs and detect breaking changes",
+  "main": "src/cli.js",
+  "bin": {
+    "specshield": "./bin/specshield.js"
+  },
+  "scripts": {
+    "start": "node bin/specshield.js",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "lint": "eslint src tests --ext .js"
+  },
+  "keywords": ["openapi", "api", "breaking-changes", "cli", "specshield"],
+  "license": "MIT",
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "dependencies": {
+    "axios": "^1.6.7",
+    "chalk": "^4.1.2",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "js-yaml": "^4.1.0",
+    "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": ["**/tests/**/*.test.js"],
+    "collectCoverageFrom": ["src/**/*.js"]
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { Command } = require('commander');
+const { version } = require('../package.json');
+const compareCommand = require('./commands/compare');
+
+const program = new Command();
+
+program
+  .name('specshield')
+  .description('Compare OpenAPI specs and detect breaking changes')
+  .version(version);
+
+program.addCommand(compareCommand);
+
+program.parseAsync(process.argv).catch((err) => {
+  const logger = require('./utils/logger');
+  logger.error(err.message);
+  process.exit(2);
+});

package/src/commands/compare.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const path = require('path');
+const { loadSpec } = require('../core/loadSpec');
+const { parseSpec } = require('../core/parseSpec');
+const { normalizeSpec } = require('../core/normalizeSpec');
+const { diffSpecs } = require('../core/diffEngine');
+const { classifyChanges, filterBySeverity } = require('../core/classifyChanges');
+const { formatHuman, formatJson } = require('../core/outputFormatter');
+const { loadConfig } = require('../core/configLoader');
+const { resolveExitCode } = require('../core/exitCode');
+const logger = require('../utils/logger');
+const fsExtra = require('fs-extra');
+
+const compare = new Command('compare');
+
+compare
+  .description('Compare two OpenAPI spec files and detect breaking changes')
+  .argument('<base>', 'Path to the base (old) OpenAPI spec')
+  .argument('<target>', 'Path to the target (new) OpenAPI spec')
+  .option('--json', 'Output machine-readable JSON')
+  .option('--output <file>', 'Save result to a file')
+  .option('--fail-on-breaking', 'Exit with code 1 if breaking changes are found')
+  .option('--allow-breaking', 'Override fail-on-breaking behavior')
+  .option('--config <path>', 'Path to .specshield.yml config file')
+  .option('--ignore <change>', 'Ignore a specific change string (repeatable)', collect, [])
+  .option('--severity <level>', 'Minimum severity level: info | warning | error', 'error')
+  .option('--remote-url <url>', 'Remote API endpoint for comparison')
+  .option('--timeout <ms>', 'Request timeout for remote mode (ms)', '10000')
+  .action(async (base, target, opts) => {
+    try {
+      // Load config
+      const config = await loadConfig(opts.config);
+
+      // Merge config with CLI options (CLI wins)
+      const options = mergeOptions(config, opts);
+
+      const spinner = options.json ? null : ora('Loading specs...').start();
+
+      let result;
+
+      if (options.remoteUrl || (config.remote && config.remote.enabled)) {
+        result = await runRemoteComparison(base, target, options, spinner);
+      } else {
+        result = await runLocalComparison(base, target, options, spinner);
+      }
+
+      if (spinner) spinner.stop();
+
+      // Apply ignore list
+      result = applyIgnoreList(result, options.ignore || []);
+
+      // Apply severity filter
+      result = filterBySeverity(result, options.severity);
+
+      // Output
+      if (options.json) {
+        const jsonOutput = formatJson(result);
+        process.stdout.write(JSON.stringify(jsonOutput, null, 2) + '\n');
+        if (options.output) {
+          await fsExtra.outputFile(options.output, JSON.stringify(jsonOutput, null, 2));
+        }
+      } else {
+        const humanOutput = formatHuman(result);
+        process.stdout.write(humanOutput + '\n');
+        if (options.output) {
+          const jsonOutput = formatJson(result);
+          await fsExtra.outputFile(options.output, JSON.stringify(jsonOutput, null, 2));
+          logger.info(`Results saved to ${options.output}`);
+        }
+      }
+
+      // Exit code
+      const code = resolveExitCode(result, options);
+      process.exit(code);
+
+    } catch (err) {
+      logger.error(`Error: ${err.message}`);
+      process.exit(2);
+    }
+  });
+
+async function runLocalComparison(base, target, options, spinner) {
+  if (spinner) spinner.text = 'Loading base spec...';
+  const baseRaw = await loadSpec(base);
+
+  if (spinner) spinner.text = 'Loading target spec...';
+  const targetRaw = await loadSpec(target);
+
+  if (spinner) spinner.text = 'Parsing specs...';
+  const baseParsed = parseSpec(baseRaw, base);
+  const targetParsed = parseSpec(targetRaw, target);
+
+  if (spinner) spinner.text = 'Normalizing specs...';
+  const baseNorm = normalizeSpec(baseParsed);
+  const targetNorm = normalizeSpec(targetParsed);
+
+  if (spinner) spinner.text = 'Comparing specs...';
+  const rawDiffs = diffSpecs(baseNorm, targetNorm);
+
+  if (spinner) spinner.text = 'Classifying changes...';
+  return classifyChanges(rawDiffs);
+}
+
+async function runRemoteComparison(base, target, options, spinner) {
+  const axios = require('axios');
+  const { loadSpec } = require('../core/loadSpec');
+
+  if (spinner) spinner.text = 'Loading specs for remote comparison...';
+  const baseRaw = await loadSpec(base);
+  const targetRaw = await loadSpec(target);
+
+  const url = options.remoteUrl || (options.remote && options.remote.url);
+  const timeout = parseInt(options.timeout, 10) || 10000;
+
+  if (spinner) spinner.text = `Sending to remote: ${url}`;
+
+  try {
+    const response = await axios.post(
+      url,
+      { baseSpec: baseRaw, targetSpec: targetRaw },
+      { timeout, headers: { 'Content-Type': 'application/json' } }
+    );
+    return response.data;
+  } catch (err) {
+    const msg = err.response
+      ? `Remote API error ${err.response.status}: ${JSON.stringify(err.response.data)}`
+      : `Remote connection failed: ${err.message}`;
+    throw new Error(msg);
+  }
+}
+
+function applyIgnoreList(result, ignoreList) {
+  if (!ignoreList || ignoreList.length === 0) return result;
+
+  const shouldIgnore = (change) => {
+    const desc = change.description || change.message || '';
+    return ignoreList.some((pattern) => desc.includes(pattern));
+  };
+
+  return {
+    ...result,
+    breakingChanges: result.breakingChanges.filter((c) => !shouldIgnore(c)),
+    additions: result.additions.filter((c) => !shouldIgnore(c)),
+    modifications: result.modifications.filter((c) => !shouldIgnore(c)),
+    warnings: result.warnings.filter((c) => !shouldIgnore(c)),
+  };
+}
+
+function mergeOptions(config, cliOpts) {
+  return {
+    json: cliOpts.json || false,
+    output: cliOpts.output || null,
+    failOnBreaking: cliOpts.allowBreaking
+      ? false
+      : cliOpts.failOnBreaking !== undefined
+      ? cliOpts.failOnBreaking
+      : config.failOnBreaking !== undefined
+      ? config.failOnBreaking
+      : false,
+    allowBreaking: cliOpts.allowBreaking || config.allowBreakingChanges || false,
+    ignore: [
+      ...(cliOpts.ignore || []),
+      ...(config.ignore || []),
+    ],
+    severity: cliOpts.severity || config.severity || 'error',
+    remoteUrl: cliOpts.remoteUrl || (config.remote && config.remote.enabled ? config.remote.url : null),
+    timeout: cliOpts.timeout || (config.remote && config.remote.timeout) || 10000,
+  };
+}
+
+function collect(value, previous) {
+  return previous.concat([value]);
+}
+
+module.exports = compare;

package/src/core/classifyChanges.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * Classify raw diffs into breaking changes, additions, modifications, warnings.
+ */
+
+const BREAKING_TYPES = new Set([
+  'ENDPOINT_REMOVED',
+  'METHOD_REMOVED',
+  'PARAMETER_REMOVED',
+  'PARAMETER_TYPE_CHANGED',
+  'PARAMETER_BECAME_REQUIRED',
+  'REQUEST_FIELD_REMOVED',
+  'REQUEST_FIELD_TYPE_CHANGED',
+  'REQUEST_REQUIRED_FIELD_ADDED',
+  'RESPONSE_FIELD_REMOVED',
+  'RESPONSE_FIELD_TYPE_CHANGED',
+  'RESPONSE_REMOVED',
+  'FIELD_BECAME_REQUIRED',
+  'ENUM_VALUE_REMOVED',
+  'REQUEST_TYPE_CHANGED',
+  'RESPONSE_TYPE_CHANGED',
+  'SCHEMA_REMOVED',
+]);
+
+const ADDITION_TYPES = new Set([
+  'ENDPOINT_ADDED',
+  'METHOD_ADDED',
+  'PARAMETER_ADDED',
+  'REQUEST_FIELD_ADDED',
+  'RESPONSE_FIELD_ADDED',
+  'RESPONSE_ADDED',
+  'SCHEMA_ADDED',
+]);
+
+const MODIFICATION_TYPES = new Set([
+  'FIELD_BECAME_OPTIONAL',
+  'PARAMETER_BECAME_OPTIONAL',
+]);
+
+const WARNING_TYPES = new Set([
+  // future use
+]);
+
+// Numeric order: higher = more severe
+const SEVERITY_ORDER = { error: 2, warning: 1, info: 0 };
+
+function classifyChanges(diffs) {
+  const result = {
+    breakingChanges: [],
+    additions: [],
+    modifications: [],
+    warnings: [],
+  };
+
+  for (const diff of diffs) {
+    const change = {
+      type: diff.type,
+      path: diff.path || null,
+      method: diff.method || null,
+      field: diff.field || null,
+      oldValue: diff.oldValue || null,
+      newValue: diff.newValue || null,
+      description: diff.description,
+    };
+
+    if (BREAKING_TYPES.has(diff.type)) {
+      change.severity = 'error';
+      result.breakingChanges.push(change);
+    } else if (ADDITION_TYPES.has(diff.type)) {
+      change.severity = 'info';
+      result.additions.push(change);
+    } else if (MODIFICATION_TYPES.has(diff.type)) {
+      change.severity = 'warning';
+      result.modifications.push(change);
+    } else if (WARNING_TYPES.has(diff.type)) {
+      change.severity = 'warning';
+      result.warnings.push(change);
+    } else {
+      // Unknown type — treat as modification
+      change.severity = 'warning';
+      result.modifications.push(change);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Filter a classified result to only include changes at or above minSeverity.
+ * info < warning < error
+ */
+function filterBySeverity(result, minSeverity) {
+  const minLevel = SEVERITY_ORDER[minSeverity] ?? 0;
+  const passes = (c) => (SEVERITY_ORDER[c.severity] ?? 0) >= minLevel;
+  return {
+    breakingChanges: result.breakingChanges.filter(passes),
+    additions: result.additions.filter(passes),
+    modifications: result.modifications.filter(passes),
+    warnings: result.warnings.filter(passes),
+  };
+}
+
+module.exports = { classifyChanges, filterBySeverity };

package/src/core/configLoader.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const fsExtra = require('fs-extra');
+const yaml = require('js-yaml');
+const path = require('path');
+const logger = require('../utils/logger');
+
+const DEFAULT_CONFIG_NAMES = ['.specshield.yml', '.specshield.yaml', '.specshield.json'];
+
+const DEFAULT_CONFIG = {
+  allowBreakingChanges: false,
+  failOnBreaking: false,
+  ignore: [],
+  severity: 'info',
+  remote: {
+    enabled: false,
+    url: null,
+    timeout: 10000,
+  },
+};
+
+async function loadConfig(configPath) {
+  // Explicit path provided
+  if (configPath) {
+    const resolved = path.resolve(configPath);
+    if (!(await fsExtra.pathExists(resolved))) {
+      throw new Error(`Config file not found: ${resolved}`);
+    }
+    return parseConfigFile(resolved);
+  }
+
+  // Auto-discover in cwd
+  for (const name of DEFAULT_CONFIG_NAMES) {
+    const resolved = path.resolve(process.cwd(), name);
+    if (await fsExtra.pathExists(resolved)) {
+      logger.debug(`Using config: ${resolved}`);
+      return parseConfigFile(resolved);
+    }
+  }
+
+  return { ...DEFAULT_CONFIG };
+}
+
+async function parseConfigFile(filePath) {
+  const content = await fsExtra.readFile(filePath, 'utf8');
+  let parsed;
+
+  try {
+    if (filePath.endsWith('.json')) {
+      parsed = JSON.parse(content);
+    } else {
+      parsed = yaml.load(content);
+    }
+  } catch (err) {
+    throw new Error(`Invalid config file "${filePath}": ${err.message}`);
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`Config file "${filePath}" must be a YAML/JSON object`);
+  }
+
+  return validateConfig(parsed, filePath);
+}
+
+function validateConfig(config, filePath) {
+  const valid = { ...DEFAULT_CONFIG };
+
+  if (config.allowBreakingChanges !== undefined) {
+    if (typeof config.allowBreakingChanges !== 'boolean') {
+      throw new Error(`Config error in "${filePath}": allowBreakingChanges must be a boolean`);
+    }
+    valid.allowBreakingChanges = config.allowBreakingChanges;
+  }
+
+  if (config.failOnBreaking !== undefined) {
+    if (typeof config.failOnBreaking !== 'boolean') {
+      throw new Error(`Config error in "${filePath}": failOnBreaking must be a boolean`);
+    }
+    valid.failOnBreaking = config.failOnBreaking;
+  }
+
+  if (config.ignore !== undefined && config.ignore !== null) {
+    if (!Array.isArray(config.ignore)) {
+      throw new Error(`Config error in "${filePath}": ignore must be an array`);
+    }
+    valid.ignore = config.ignore.filter(Boolean);
+  }
+
+  if (config.severity !== undefined) {
+    const allowed = ['info', 'warning', 'error'];
+    if (!allowed.includes(config.severity)) {
+      throw new Error(`Config error in "${filePath}": severity must be one of: ${allowed.join(', ')}`);
+    }
+    valid.severity = config.severity;
+  }
+
+  if (config.remote !== undefined) {
+    if (typeof config.remote !== 'object') {
+      throw new Error(`Config error in "${filePath}": remote must be an object`);
+    }
+    valid.remote = {
+      enabled: Boolean(config.remote.enabled),
+      url: config.remote.url || null,
+      timeout: parseInt(config.remote.timeout, 10) || 10000,
+    };
+  }
+
+  return valid;
+}
+
+module.exports = { loadConfig };

package/src/core/diffEngine.js

@@ -0,0 +1,370 @@
+'use strict';
+
+/**
+ * Compare two normalized specs and return a flat list of raw diffs.
+ * Each diff: { type, path, method, field, oldValue, newValue, description }
+ */
+function diffSpecs(base, target) {
+  const diffs = [];
+
+  diffEndpoints(base.endpoints || {}, target.endpoints || {}, diffs);
+  diffSchemas(base.schemas || {}, target.schemas || {}, diffs);
+
+  return diffs;
+}
+
+// ─── Endpoints ──────────────────────────────────────────────────────────────
+
+function diffEndpoints(baseEndpoints, targetEndpoints, diffs) {
+  // Removed paths
+  for (const path of Object.keys(baseEndpoints)) {
+    if (!targetEndpoints[path]) {
+      for (const method of Object.keys(baseEndpoints[path])) {
+        diffs.push({
+          type: 'ENDPOINT_REMOVED',
+          path,
+          method,
+          description: `${method.toUpperCase()} ${path} was removed`,
+        });
+      }
+    } else {
+      diffMethods(path, baseEndpoints[path], targetEndpoints[path], diffs);
+    }
+  }
+
+  // Added paths
+  for (const path of Object.keys(targetEndpoints)) {
+    if (!baseEndpoints[path]) {
+      for (const method of Object.keys(targetEndpoints[path])) {
+        diffs.push({
+          type: 'ENDPOINT_ADDED',
+          path,
+          method,
+          description: `${method.toUpperCase()} ${path} was added`,
+        });
+      }
+    }
+  }
+}
+
+function diffMethods(path, baseMethods, targetMethods, diffs) {
+  for (const method of Object.keys(baseMethods)) {
+    if (!targetMethods[method]) {
+      diffs.push({
+        type: 'METHOD_REMOVED',
+        path,
+        method,
+        description: `${method.toUpperCase()} ${path} method was removed`,
+      });
+    } else {
+      diffOperation(path, method, baseMethods[method], targetMethods[method], diffs);
+    }
+  }
+
+  for (const method of Object.keys(targetMethods)) {
+    if (!baseMethods[method]) {
+      diffs.push({
+        type: 'METHOD_ADDED',
+        path,
+        method,
+        description: `${method.toUpperCase()} ${path} method was added`,
+      });
+    }
+  }
+}
+
+function diffOperation(path, method, baseOp, targetOp, diffs) {
+  diffParameters(path, method, baseOp.parameters || [], targetOp.parameters || [], diffs);
+  diffSchemaNode(path, method, 'requestBody', baseOp.requestBody, targetOp.requestBody, diffs, true);
+  diffResponses(path, method, baseOp.responses || {}, targetOp.responses || {}, diffs);
+}
+
+// ─── Parameters ─────────────────────────────────────────────────────────────
+
+function diffParameters(path, method, baseParams, targetParams, diffs) {
+  const baseMap = toParamMap(baseParams);
+  const targetMap = toParamMap(targetParams);
+
+  for (const key of Object.keys(baseMap)) {
+    if (!targetMap[key]) {
+      const p = baseMap[key];
+      diffs.push({
+        type: 'PARAMETER_REMOVED',
+        path,
+        method,
+        field: `parameters.${p.name}`,
+        description: `Parameter "${p.name}" (${p.in}) was removed from ${method.toUpperCase()} ${path}`,
+      });
+    } else {
+      const bp = baseMap[key];
+      const tp = targetMap[key];
+      const baseType = schemaTypeStr(bp.schema);
+      const targetType = schemaTypeStr(tp.schema);
+
+      if (baseType !== targetType) {
+        diffs.push({
+          type: 'PARAMETER_TYPE_CHANGED',
+          path,
+          method,
+          field: `parameters.${bp.name}`,
+          oldValue: baseType,
+          newValue: targetType,
+          description: `Parameter "${bp.name}" type changed from "${baseType}" to "${targetType}" in ${method.toUpperCase()} ${path}`,
+        });
+      }
+
+      if (bp.required !== tp.required) {
+        diffs.push({
+          type: tp.required ? 'PARAMETER_BECAME_REQUIRED' : 'PARAMETER_BECAME_OPTIONAL',
+          path,
+          method,
+          field: `parameters.${bp.name}`,
+          oldValue: String(bp.required),
+          newValue: String(tp.required),
+          description: `Parameter "${bp.name}" became ${tp.required ? 'required' : 'optional'} in ${method.toUpperCase()} ${path}`,
+        });
+      }
+    }
+  }
+
+  for (const key of Object.keys(targetMap)) {
+    if (!baseMap[key]) {
+      const p = targetMap[key];
+      diffs.push({
+        type: 'PARAMETER_ADDED',
+        path,
+        method,
+        field: `parameters.${p.name}`,
+        description: `Parameter "${p.name}" (${p.in}) was added to ${method.toUpperCase()} ${path}`,
+      });
+    }
+  }
+}
+
+function toParamMap(params) {
+  const map = {};
+  for (const p of params) {
+    map[`${p.in}:${p.name}`] = p;
+  }
+  return map;
+}
+
+// ─── Responses ──────────────────────────────────────────────────────────────
+
+function diffResponses(path, method, baseResponses, targetResponses, diffs) {
+  for (const statusCode of Object.keys(baseResponses)) {
+    if (!targetResponses[statusCode]) {
+      diffs.push({
+        type: 'RESPONSE_REMOVED',
+        path,
+        method,
+        field: `responses.${statusCode}`,
+        description: `Response status ${statusCode} was removed from ${method.toUpperCase()} ${path}`,
+      });
+    } else {
+      diffSchemaNode(path, method, `responses.${statusCode}`, baseResponses[statusCode], targetResponses[statusCode], diffs, false);
+    }
+  }
+
+  for (const statusCode of Object.keys(targetResponses)) {
+    if (!baseResponses[statusCode]) {
+      diffs.push({
+        type: 'RESPONSE_ADDED',
+        path,
+        method,
+        field: `responses.${statusCode}`,
+        description: `Response status ${statusCode} was added to ${method.toUpperCase()} ${path}`,
+      });
+    }
+  }
+}
+
+// ─── Schema diffing ─────────────────────────────────────────────────────────
+
+function diffSchemaNode(path, method, fieldPrefix, base, target, diffs, isRequest) {
+  if (!base && !target) return;
+  if (!base || !target) return;
+
+  const baseProps = base.properties || {};
+  const targetProps = target.properties || {};
+  const baseRequired = base.required || [];
+  const targetRequired = target.required || [];
+
+  // Check type change at node level
+  if (base.type && target.type && base.type !== target.type) {
+    diffs.push({
+      type: isRequest ? 'REQUEST_TYPE_CHANGED' : 'RESPONSE_TYPE_CHANGED',
+      path,
+      method,
+      field: fieldPrefix,
+      oldValue: base.type,
+      newValue: target.type,
+      description: `Type of "${fieldPrefix}" changed from "${base.type}" to "${target.type}" in ${method.toUpperCase()} ${path}`,
+    });
+  }
+
+  // Check enum changes
+  diffEnums(path, method, fieldPrefix, base.enum, target.enum, diffs);
+
+  // Removed properties
+  for (const field of Object.keys(baseProps)) {
+    const fullField = `${fieldPrefix}.${field}`;
+    if (!targetProps[field]) {
+      diffs.push({
+        type: isRequest ? 'REQUEST_FIELD_REMOVED' : 'RESPONSE_FIELD_REMOVED',
+        path,
+        method,
+        field: fullField,
+        description: `Field "${fullField}" was removed from ${method.toUpperCase()} ${path}`,
+      });
+    } else {
+      const bField = baseProps[field];
+      const tField = targetProps[field];
+
+      // Type change
+      const bType = schemaTypeStr(bField);
+      const tType = schemaTypeStr(tField);
+      if (bType !== tType) {
+        diffs.push({
+          type: isRequest ? 'REQUEST_FIELD_TYPE_CHANGED' : 'RESPONSE_FIELD_TYPE_CHANGED',
+          path,
+          method,
+          field: fullField,
+          oldValue: bType,
+          newValue: tType,
+          description: `Field "${fullField}" type changed from "${bType}" to "${tType}" in ${method.toUpperCase()} ${path}`,
+        });
+      }
+
+      // Required changed
+      const wasRequired = baseRequired.includes(field);
+      const isRequired = targetRequired.includes(field);
+      if (!wasRequired && isRequired) {
+        diffs.push({
+          type: 'FIELD_BECAME_REQUIRED',
+          path,
+          method,
+          field: fullField,
+          description: `Field "${fullField}" became required in ${method.toUpperCase()} ${path}`,
+        });
+      } else if (wasRequired && !isRequired) {
+        diffs.push({
+          type: 'FIELD_BECAME_OPTIONAL',
+          path,
+          method,
+          field: fullField,
+          description: `Field "${fullField}" became optional in ${method.toUpperCase()} ${path}`,
+        });
+      }
+
+      // Enum changes on field
+      diffEnums(path, method, fullField, bField.enum, tField.enum, diffs);
+
+      // Recurse into nested objects
+      if (bField.properties || tField.properties) {
+        diffSchemaNode(path, method, fullField, bField, tField, diffs, isRequest);
+      }
+    }
+  }
+
+  // Added properties
+  for (const field of Object.keys(targetProps)) {
+    if (!baseProps[field]) {
+      const fullField = `${fieldPrefix}.${field}`;
+      const isRequired = targetRequired.includes(field);
+      diffs.push({
+        type: isRequest
+          ? isRequired ? 'REQUEST_REQUIRED_FIELD_ADDED' : 'REQUEST_FIELD_ADDED'
+          : 'RESPONSE_FIELD_ADDED',
+        path,
+        method,
+        field: fullField,
+        description: `Field "${fullField}" was added to ${method.toUpperCase()} ${path}${isRequest && isRequired ? ' (required)' : ''}`,
+      });
+    }
+  }
+
+  // Diff array items
+  if (base.items || target.items) {
+    const itemsField = `${fieldPrefix}[items]`;
+    if (base.items && target.items) {
+      const baseItemType = schemaTypeStr(base.items);
+      const targetItemType = schemaTypeStr(target.items);
+      if (baseItemType !== targetItemType) {
+        diffs.push({
+          type: isRequest ? 'REQUEST_FIELD_TYPE_CHANGED' : 'RESPONSE_FIELD_TYPE_CHANGED',
+          path,
+          method,
+          field: itemsField,
+          oldValue: baseItemType,
+          newValue: targetItemType,
+          description: `Array item type of "${fieldPrefix}" changed from "${baseItemType}" to "${targetItemType}" in ${method.toUpperCase()} ${path}`,
+        });
+      }
+      // Recurse into items if they contain object properties
+      if (base.items.properties || target.items.properties) {
+        diffSchemaNode(path, method, itemsField, base.items, target.items, diffs, isRequest);
+      }
+    } else if (base.items && !target.items) {
+      diffs.push({
+        type: isRequest ? 'REQUEST_FIELD_REMOVED' : 'RESPONSE_FIELD_REMOVED',
+        path,
+        method,
+        field: itemsField,
+        description: `Array items schema was removed from "${fieldPrefix}" in ${method.toUpperCase()} ${path}`,
+      });
+    }
+  }
+}
+
+function diffEnums(path, method, fieldPrefix, baseEnum, targetEnum, diffs) {
+  if (!baseEnum || !targetEnum) return;
+  for (const val of baseEnum) {
+    if (!targetEnum.includes(val)) {
+      diffs.push({
+        type: 'ENUM_VALUE_REMOVED',
+        path,
+        method,
+        field: fieldPrefix,
+        oldValue: String(val),
+        description: `Enum value "${val}" was removed from "${fieldPrefix}" in ${method.toUpperCase()} ${path}`,
+      });
+    }
+  }
+}
+
+// ─── Component schemas ───────────────────────────────────────────────────────
+
+function diffSchemas(baseSchemas, targetSchemas, diffs) {
+  for (const name of Object.keys(baseSchemas)) {
+    if (!targetSchemas[name]) {
+      diffs.push({
+        type: 'SCHEMA_REMOVED',
+        field: `components.schemas.${name}`,
+        description: `Schema "${name}" was removed from components.schemas`,
+      });
+    }
+  }
+
+  for (const name of Object.keys(targetSchemas)) {
+    if (!baseSchemas[name]) {
+      diffs.push({
+        type: 'SCHEMA_ADDED',
+        field: `components.schemas.${name}`,
+        description: `Schema "${name}" was added to components.schemas`,
+      });
+    }
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function schemaTypeStr(schema) {
+  if (!schema) return 'unknown';
+  if (schema.ref) return schema.ref;
+  let t = schema.type || 'object';
+  if (schema.format) t += `:${schema.format}`;
+  return t;
+}
+
+module.exports = { diffSpecs };

package/src/core/exitCode.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * Resolve exit code based on comparison result and options.
+ * 0 = success
+ * 1 = breaking changes found and fail-on-breaking active
+ * 2 = runtime/input error (handled elsewhere)
+ */
+function resolveExitCode(result, options) {
+  const hasBreaking = result.breakingChanges && result.breakingChanges.length > 0;
+
+  if (hasBreaking && options.failOnBreaking && !options.allowBreaking) {
+    return 1;
+  }
+
+  return 0;
+}
+
+module.exports = { resolveExitCode };

package/src/core/loadSpec.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const fsExtra = require('fs-extra');
+const path = require('path');
+
+/**
+ * Load a spec file from the local filesystem.
+ * Returns raw string content.
+ */
+async function loadSpec(filePath) {
+  const resolved = path.resolve(filePath);
+
+  const exists = await fsExtra.pathExists(resolved);
+  if (!exists) {
+    throw new Error(`Spec file not found: ${resolved}`);
+  }
+
+  const stat = await fsExtra.stat(resolved);
+  if (!stat.isFile()) {
+    throw new Error(`Path is not a file: ${resolved}`);
+  }
+
+  const content = await fsExtra.readFile(resolved, 'utf8');
+  if (!content || content.trim().length === 0) {
+    throw new Error(`Spec file is empty: ${resolved}`);
+  }
+
+  return content;
+}
+
+module.exports = { loadSpec };

package/src/core/normalizeSpec.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * Normalize an OpenAPI spec into a flat, consistent internal model.
+ * Resolves simple $ref references from components.schemas.
+ */
+function normalizeSpec(spec) {
+  if (!spec || typeof spec !== 'object') {
+    throw new Error('Invalid spec: must be an object');
+  }
+
+  const components = spec.components || {};
+  const schemas = components.schemas || {};
+
+  const endpoints = {};
+
+  const paths = spec.paths || {};
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== 'object') continue;
+
+    const methods = {};
+    const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
+
+    for (const method of HTTP_METHODS) {
+      if (!pathItem[method]) continue;
+      const operation = pathItem[method];
+      methods[method] = normalizeOperation(operation, schemas);
+    }
+
+    if (Object.keys(methods).length > 0) {
+      endpoints[pathKey] = methods;
+    }
+  }
+
+  return {
+    info: spec.info || {},
+    endpoints,
+    schemas: normalizeSchemaMap(schemas, schemas),
+  };
+}
+
+function normalizeOperation(operation, schemas) {
+  return {
+    operationId: operation.operationId || null,
+    summary: operation.summary || null,
+    parameters: normalizeParameters(operation.parameters || [], schemas),
+    requestBody: normalizeRequestBody(operation.requestBody, schemas),
+    responses: normalizeResponses(operation.responses || {}, schemas),
+  };
+}
+
+function normalizeParameters(params, schemas) {
+  return params.map((p) => ({
+    name: p.name,
+    in: p.in,
+    required: Boolean(p.required),
+    schema: p.schema ? resolveSchema(p.schema, schemas) : null,
+  }));
+}
+
+function normalizeRequestBody(requestBody, schemas) {
+  if (!requestBody) return null;
+  const content = requestBody.content || {};
+  const mediaType = content['application/json'] || Object.values(content)[0];
+  if (!mediaType || !mediaType.schema) return null;
+  return resolveSchema(mediaType.schema, schemas);
+}
+
+function normalizeResponses(responses, schemas) {
+  const result = {};
+  for (const [statusCode, response] of Object.entries(responses)) {
+    if (!response) continue;
+    const content = response.content || {};
+    const mediaType = content['application/json'] || Object.values(content)[0];
+    result[statusCode] = mediaType && mediaType.schema
+      ? resolveSchema(mediaType.schema, schemas)
+      : null;
+  }
+  return result;
+}
+
+function normalizeSchemaMap(schemaMap, allSchemas) {
+  const result = {};
+  for (const [name, schema] of Object.entries(schemaMap)) {
+    result[name] = resolveSchema(schema, allSchemas);
+  }
+  return result;
+}
+
+/**
+ * Resolve a schema node, following simple $ref to components.schemas.
+ * Returns a normalized schema node with { type, properties, required, items, enum }.
+ */
+function resolveSchema(schema, schemas, depth = 0) {
+  if (!schema || typeof schema !== 'object') return { type: 'unknown' };
+  if (depth > 10) return { type: 'circular' };
+
+  if (schema.$ref) {
+    const refName = schema.$ref.replace('#/components/schemas/', '');
+    const resolved = schemas[refName];
+    if (!resolved) return { type: 'unknown', ref: schema.$ref };
+    return resolveSchema(resolved, schemas, depth + 1);
+  }
+
+  // Handle allOf / oneOf / anyOf by merging
+  if (schema.allOf) {
+    return mergeSchemas(schema.allOf, schemas, depth);
+  }
+  if (schema.oneOf || schema.anyOf) {
+    const list = schema.oneOf || schema.anyOf;
+    return mergeSchemas(list, schemas, depth);
+  }
+
+  const node = {
+    type: schema.type || 'object',
+    format: schema.format || null,
+    enum: schema.enum || null,
+    nullable: Boolean(schema.nullable),
+    required: Array.isArray(schema.required) ? schema.required : [],
+    properties: {},
+    items: null,
+  };
+
+  if (schema.properties) {
+    for (const [key, val] of Object.entries(schema.properties)) {
+      node.properties[key] = resolveSchema(val, schemas, depth + 1);
+    }
+  }
+
+  if (schema.items) {
+    node.items = resolveSchema(schema.items, schemas, depth + 1);
+  }
+
+  return node;
+}
+
+function mergeSchemas(schemaList, schemas, depth) {
+  const merged = { type: 'object', required: [], properties: {}, items: null, enum: null, nullable: false };
+  for (const s of schemaList) {
+    const resolved = resolveSchema(s, schemas, depth + 1);
+    if (resolved.properties) Object.assign(merged.properties, resolved.properties);
+    if (resolved.required) merged.required.push(...resolved.required);
+    if (resolved.type && resolved.type !== 'object') merged.type = resolved.type;
+    if (resolved.enum) merged.enum = resolved.enum;
+  }
+  return merged;
+}
+
+module.exports = { normalizeSpec, resolveSchema };

package/src/core/outputFormatter.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const chalk = require('chalk');
+
+function formatHuman(result) {
+  const lines = [];
+  const { breakingChanges, additions, modifications, warnings } = result;
+
+  const total = breakingChanges.length + additions.length + modifications.length + warnings.length;
+
+  if (total === 0) {
+    lines.push(chalk.green('✔  No changes detected between the two specs.'));
+    return lines.join('\n');
+  }
+
+  // Summary header
+  lines.push('');
+  lines.push(chalk.bold('  SpecShield Comparison Report'));
+  lines.push(chalk.gray('  ─────────────────────────────────────────'));
+  lines.push(
+    `  ${chalk.red.bold(`${breakingChanges.length} breaking`)}  ` +
+    `${chalk.green(`${additions.length} additions`)}  ` +
+    `${chalk.yellow(`${modifications.length} modifications`)}  ` +
+    `${chalk.gray(`${warnings.length} warnings`)}`
+  );
+  lines.push('');
+
+  if (breakingChanges.length > 0) {
+    lines.push(chalk.red.bold('  ✖  BREAKING CHANGES'));
+    lines.push(chalk.gray('  ─────────────────────────────────────────'));
+    for (const c of breakingChanges) {
+      lines.push(`  ${chalk.red('●')} ${c.description}`);
+      if (c.oldValue && c.newValue) {
+        lines.push(`    ${chalk.gray('from:')} ${chalk.red(c.oldValue)}  ${chalk.gray('→')}  ${chalk.green(c.newValue)}`);
+      }
+    }
+    lines.push('');
+  }
+
+  if (additions.length > 0) {
+    lines.push(chalk.green.bold('  ✚  ADDITIONS'));
+    lines.push(chalk.gray('  ─────────────────────────────────────────'));
+    for (const c of additions) {
+      lines.push(`  ${chalk.green('+')} ${c.description}`);
+    }
+    lines.push('');
+  }
+
+  if (modifications.length > 0) {
+    lines.push(chalk.yellow.bold('  ✎  MODIFICATIONS'));
+    lines.push(chalk.gray('  ─────────────────────────────────────────'));
+    for (const c of modifications) {
+      lines.push(`  ${chalk.yellow('~')} ${c.description}`);
+      if (c.oldValue && c.newValue) {
+        lines.push(`    ${chalk.gray('from:')} ${chalk.yellow(c.oldValue)}  ${chalk.gray('→')}  ${chalk.yellow(c.newValue)}`);
+      }
+    }
+    lines.push('');
+  }
+
+  if (warnings.length > 0) {
+    lines.push(chalk.gray.bold('  ⚠  WARNINGS'));
+    lines.push(chalk.gray('  ─────────────────────────────────────────'));
+    for (const c of warnings) {
+      lines.push(`  ${chalk.gray('!')} ${c.description}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatJson(result) {
+  return {
+    summary: {
+      breaking: result.breakingChanges.length,
+      additions: result.additions.length,
+      modifications: result.modifications.length,
+      warnings: result.warnings.length,
+    },
+    breakingChanges: result.breakingChanges,
+    additions: result.additions,
+    modifications: result.modifications,
+    warnings: result.warnings,
+  };
+}
+
+module.exports = { formatHuman, formatJson };

package/src/core/parseSpec.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const yaml = require('js-yaml');
+const path = require('path');
+
+/**
+ * Parse raw spec content (YAML or JSON) into a JavaScript object.
+ * Detects format from file extension or content.
+ */
+function parseSpec(content, filePath) {
+  const ext = filePath ? path.extname(filePath).toLowerCase() : '';
+
+  try {
+    if (ext === '.json') {
+      return parseJson(content);
+    } else if (ext === '.yaml' || ext === '.yml') {
+      return parseYaml(content);
+    } else {
+      // Auto-detect: try JSON first, then YAML
+      return autoDetect(content);
+    }
+  } catch (err) {
+    throw new Error(`Failed to parse spec "${filePath}": ${err.message}`);
+  }
+}
+
+function parseJson(content) {
+  try {
+    return JSON.parse(content);
+  } catch (err) {
+    throw new Error(`Invalid JSON: ${err.message}`);
+  }
+}
+
+function parseYaml(content) {
+  const result = yaml.load(content);
+  if (result === null || typeof result !== 'object') {
+    throw new Error('YAML did not produce a valid object');
+  }
+  return result;
+}
+
+function autoDetect(content) {
+  const trimmed = content.trim();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    return parseJson(content);
+  }
+  return parseYaml(content);
+}
+
+module.exports = { parseSpec, parseJson, parseYaml };

package/src/utils/logger.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const chalk = require('chalk');
+
+const logger = {
+  info(msg) {
+    process.stderr.write(chalk.blue('ℹ ') + msg + '\n');
+  },
+  warn(msg) {
+    process.stderr.write(chalk.yellow('⚠ ') + msg + '\n');
+  },
+  error(msg) {
+    process.stderr.write(chalk.red('✖ ') + msg + '\n');
+  },
+  debug(msg) {
+    if (process.env.SPECSHIELD_DEBUG) {
+      process.stderr.write(chalk.gray('[debug] ') + msg + '\n');
+    }
+  },
+};
+
+module.exports = logger;