@subhamxcod/apiguard 1.0.4 → 1.1.0

package/dist/{chunk-RQVNHPHC.js → chunk-EJQ5XOY6.js}

@@ -16,7 +16,7 @@ var ignoreSchema = z.strictObject({
   "show-ignored": z.boolean().optional().default(false)
 });
 var outputSchema = z.strictObject({
-  format: z.enum(["terminal", "json", "markdown"]).optional().default("terminal"),
+  format: z.enum(["terminal", "json", "markdown", "html", "sarif"]).optional().default("terminal"),
   "include-non-breaking": z.boolean().optional().default(false),
   color: z.enum(["auto", "always", "never"]).optional().default("auto")
 });
@@ -24,13 +24,17 @@ var versioningSchema = z.strictObject({
   suggest: z.boolean().optional().default(true)
 });
 var loaderSchema = z.strictObject({
-  "allow-remote-refs": z.boolean().optional().default(false)
+  "allow-remote-refs": z.boolean().optional().default(false),
+  "allow-external-files": z.boolean().optional().default(false),
+  "allow-private-ips": z.boolean().optional().default(false),
+  headers: z.record(z.string(), z.string()).optional().default({})
 });
 var githubSchema = z.strictObject({
   comment: z.boolean().optional().default(true),
   "check-run": z.boolean().optional().default(true),
   "update-existing-comment": z.boolean().optional().default(true)
 });
+var profileSchema = z.enum(["default", "strict-sdk", "loose-web"]).default("default");
 var configSchema = z.strictObject({
   schemaVersion: z.literal(1, {
     error: "schemaVersion must be 1 (other versions are rejected; see docs/configuration.md)"
@@ -40,6 +44,7 @@ var configSchema = z.strictObject({
   output: outputSchema.optional(),
   "fail-on": z.enum(["error", "warning", "never"]).optional(),
   versioning: versioningSchema.optional(),
+  profile: profileSchema.optional(),
   loader: loaderSchema.optional(),
   github: githubSchema.optional()
 });
@@ -63,7 +68,13 @@ var DEFAULT_CONFIG = {
   failOn: "error",
   // §13 golden output shows the bump line "only with --suggest-version"; config may opt in.
   versioning: { suggest: false },
-  loader: { allowRemoteRefs: false },
+  profile: "default",
+  loader: {
+    allowRemoteRefs: false,
+    allowExternalFiles: false,
+    allowPrivateIps: false,
+    headers: {}
+  },
   github: { comment: true, checkRun: true, updateExistingComment: true }
 };
 
@@ -156,7 +167,13 @@ function toResolved(parsed) {
     },
     failOn: parsed["fail-on"] ?? "error",
     versioning: { suggest: parsed.versioning?.suggest ?? true },
-    loader: { allowRemoteRefs: parsed.loader?.["allow-remote-refs"] ?? false },
+    profile: parsed.profile ?? "default",
+    loader: {
+      allowRemoteRefs: parsed.loader?.["allow-remote-refs"] ?? false,
+      allowExternalFiles: parsed.loader?.["allow-external-files"] ?? false,
+      allowPrivateIps: parsed.loader?.["allow-private-ips"] ?? false,
+      headers: parsed.loader?.headers ?? {}
+    },
     github: {
       comment: parsed.github?.comment ?? true,
       checkRun: parsed.github?.["check-run"] ?? true,
@@ -236,13 +253,16 @@ function mergeWithFlags(base, flags) {
     failOn: flags.failOn ?? base.failOn,
     versioning: {
       suggest: flags.suggestVersion ?? base.versioning.suggest
-    }
+    },
+    profile: flags.profile ?? base.profile
   };
 }
 
 // src/loaders/spec-loader.ts
 import fs2 from "fs";
 import path2 from "path";
+import os from "os";
+import { execFileSync } from "child_process";
 import SwaggerParser from "@apidevtools/swagger-parser";
 import { parse as parseYaml2 } from "yaml";
 
@@ -341,6 +361,87 @@ function toNormalizedSpec(loaded, normalized) {
 }
 
 // src/loaders/spec-loader.ts
+function isPrivateHost(hostname) {
+  const h = hostname.toLowerCase().trim();
+  if (h === "localhost" || h === "127.0.0.1" || h === "::1" || h === "0.0.0.0" || h === "::") {
+    return true;
+  }
+  const ipv4Match = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (ipv4Match) {
+    const [b0, b1] = [Number(ipv4Match[1]), Number(ipv4Match[2])];
+    if (b0 === 127) return true;
+    if (b0 === 10) return true;
+    if (b0 === 172 && b1 >= 16 && b1 <= 31) return true;
+    if (b0 === 192 && b1 === 168) return true;
+    if (b0 === 169 && b1 === 254) return true;
+    if (b0 === 0) return true;
+  }
+  if (h.startsWith("fc") || h.startsWith("fd") || h.startsWith("fe80:")) {
+    return true;
+  }
+  return false;
+}
+async function fetchRemoteSpec(urlStr, options = {}) {
+  let url;
+  try {
+    url = new URL(urlStr);
+  } catch (e) {
+    throw new SpecLoadError(`${urlStr}: invalid URL: ${errorMessage(e)}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new SpecLoadError(
+      `${urlStr}: unsupported protocol "${url.protocol}" (expected http: or https:)`
+    );
+  }
+  if (!options.allowPrivateIps && isPrivateHost(url.hostname)) {
+    throw new SpecLoadError(
+      `${urlStr}: remote spec blocked: private or loopback host "${url.hostname}" denied by SSRF protection. Set loader.allow-private-ips: true in apiguard.yaml or CLI to opt in.`
+    );
+  }
+  let text;
+  try {
+    const res = await fetch(urlStr, {
+      headers: options.headers ?? {},
+      signal: AbortSignal.timeout(15e3)
+    });
+    if (!res.ok) {
+      throw new SpecLoadError(
+        `${urlStr}: failed to fetch spec (HTTP ${res.status} ${res.statusText})`
+      );
+    }
+    text = await res.text();
+  } catch (e) {
+    if (e instanceof SpecLoadError) throw e;
+    throw new SpecLoadError(`${urlStr}: network error fetching spec: ${errorMessage(e)}`);
+  }
+  const tmpDir = fs2.mkdtempSync(path2.join(os.tmpdir(), "apiguard-remote-"));
+  const ext = url.pathname.toLowerCase().endsWith(".json") ? ".json" : ".yaml";
+  const localPath = path2.join(tmpDir, "spec" + ext);
+  fs2.writeFileSync(localPath, text, "utf8");
+  return { localPath, text };
+}
+function fetchGitSpec(gitUri, cwd = process.cwd()) {
+  const stripped = gitUri.replace(/^git:\/\//i, "").replace(/^git:/i, "");
+  const colonIdx = stripped.indexOf(":");
+  if (colonIdx === -1) {
+    throw new SpecLoadError(`${gitUri}: invalid git spec URI (expected git://<rev>:<path>)`);
+  }
+  const rev = stripped.slice(0, colonIdx);
+  const relPath = stripped.slice(colonIdx + 1);
+  let text;
+  try {
+    text = execFileSync("git", ["show", `${rev}:${relPath}`], { cwd, encoding: "utf8" });
+  } catch (e) {
+    throw new SpecLoadError(
+      `${gitUri}: failed to retrieve spec from git (${rev}:${relPath}): ${errorMessage(e)}`
+    );
+  }
+  const tmpDir = fs2.mkdtempSync(path2.join(os.tmpdir(), "apiguard-git-"));
+  const ext = relPath.toLowerCase().endsWith(".json") ? ".json" : ".yaml";
+  const localPath = path2.join(tmpDir, path2.basename(relPath) || "spec" + ext);
+  fs2.writeFileSync(localPath, text, "utf8");
+  return { localPath, text };
+}
 function parseSpecText(text, source) {
   let parsed;
   const isJsonByExt = source.trimEnd().toLowerCase().endsWith(".json");
@@ -418,12 +519,23 @@ function findExternalFileRefs(document, specDir) {
   return found;
 }
 async function loadSpec(filePath, options = {}) {
-  const abs = path2.resolve(filePath);
+  let abs;
   let text;
-  try {
-    text = fs2.readFileSync(abs, "utf8");
-  } catch (e) {
-    throw new SpecLoadError(`${filePath}: cannot read file: ${errorMessage(e)}`);
+  if (filePath.startsWith("http://") || filePath.startsWith("https://")) {
+    const fetched = await fetchRemoteSpec(filePath, options.loader);
+    abs = fetched.localPath;
+    text = fetched.text;
+  } else if (filePath.startsWith("git://") || filePath.startsWith("git:")) {
+    const fetched = fetchGitSpec(filePath, options.cwd);
+    abs = fetched.localPath;
+    text = fetched.text;
+  } else {
+    abs = path2.resolve(filePath);
+    try {
+      text = fs2.readFileSync(abs, "utf8");
+    } catch (e) {
+      throw new SpecLoadError(`${filePath}: cannot read file: ${errorMessage(e)}`);
+    }
   }
   if (text.trim() === "") {
     throw new SpecLoadError(`${filePath}: file is empty \u2014 a spec must contain an OpenAPI document`);
@@ -468,7 +580,8 @@ async function loadSpec(filePath, options = {}) {
     source: filePath,
     openapiVersion: openapi,
     title,
-    sha256: ""
+    sha256: "",
+    rawText: text
   };
   return toNormalizedSpec(loaded, normalizeDocument(document));
 }
@@ -1509,6 +1622,9 @@ function getRule(id) {
   if (!rule) throw new Error(`internal error: unknown rule id "${id}"`);
   return rule;
 }
+function getAllRules() {
+  return [...RULES];
+}
 function constraintText(c) {
   const name = nameOf(c);
   const oldV = c.oldValue === void 0 ? void 0 : JSON.stringify(c.oldValue);
@@ -1577,7 +1693,21 @@ function classify(ruleId, context, options, doctrine) {
     "request-body-removed",
     "removed-parameter"
   ]);
-  const severity = override ?? (DOCTRINE_RULES.has(ruleId) ? resolveContextSeverity(ruleId, context, doctrine ?? {}) : rule.defaultSeverity);
+  let baseSeverity = DOCTRINE_RULES.has(ruleId) ? resolveContextSeverity(ruleId, context, doctrine ?? {}) : rule.defaultSeverity;
+  if (override === void 0 && options.profile) {
+    if (options.profile === "strict-sdk") {
+      if (ruleId === "enum-value-added") {
+        baseSeverity = "error";
+      } else if (ruleId === "anyOf-oneOf-member-added") {
+        baseSeverity = "warning";
+      }
+    } else if (options.profile === "loose-web") {
+      if (ruleId === "enum-value-added") {
+        baseSeverity = "info";
+      }
+    }
+  }
+  const severity = override ?? baseSeverity;
   return { severity, kind: rule.defaultKind };
 }
 
@@ -2303,7 +2433,7 @@ function emit(ctx, opts) {
   const resolved = classify(
     opts.ruleId,
     opts.location.context,
-    { rules: ctx.config.rules },
+    { rules: ctx.config.rules, profile: ctx.config.profile },
     opts.doctrine
   );
   const rule = getRule(opts.ruleId);
@@ -3721,6 +3851,71 @@ function satisfiesAny(oldReq, newReqs) {
   });
 }
 
+// src/utils/source-map.ts
+import { parseDocument, LineCounter } from "yaml";
+var SpecSourceMap = class {
+  doc;
+  lineCounter;
+  constructor(rawText) {
+    this.lineCounter = new LineCounter();
+    this.doc = parseDocument(rawText, { lineCounter: this.lineCounter });
+  }
+  /** Resolve 1-based line & column for a JSON pointer. */
+  findPosition(pointer) {
+    if (!pointer || pointer === "/") {
+      return { line: 1, column: 1 };
+    }
+    const tokens = pointer.split("/").filter(Boolean).map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~"));
+    for (let i = tokens.length; i >= 1; i--) {
+      const subTokens = tokens.slice(0, i);
+      try {
+        const node = this.doc.getIn(subTokens, true);
+        if (node && Array.isArray(node.range) && typeof node.range[0] === "number") {
+          const pos = this.lineCounter.linePos(node.range[0]);
+          return { line: pos.line, column: pos.col };
+        }
+      } catch {
+      }
+    }
+    return void 0;
+  }
+};
+function attachSourceLocations(changes, baselineSpec, currentSpec) {
+  let currentMap;
+  let baselineMap;
+  if (currentSpec.rawText) {
+    try {
+      currentMap = new SpecSourceMap(currentSpec.rawText);
+    } catch {
+    }
+  }
+  if (baselineSpec.rawText) {
+    try {
+      baselineMap = new SpecSourceMap(baselineSpec.rawText);
+    } catch {
+    }
+  }
+  for (const c of changes) {
+    if (currentMap && c.location.pointerNew) {
+      const pos = currentMap.findPosition(c.location.pointerNew);
+      if (pos) {
+        c.location.file = currentSpec.source;
+        c.location.line = pos.line;
+        c.location.column = pos.column;
+        continue;
+      }
+    }
+    if (baselineMap && c.location.pointerOld) {
+      const pos = baselineMap.findPosition(c.location.pointerOld);
+      if (pos) {
+        c.location.file = baselineSpec.source;
+        c.location.line = pos.line;
+        c.location.column = pos.column;
+      }
+    }
+  }
+}
+
 // src/core/ignore/ignore.ts
 import micromatch from "micromatch";
 function changePath(change) {
@@ -3797,8 +3992,8 @@ async function analyze(baselinePath, currentPath, options = {}) {
   const loaded = options.config ? { config: options.config, sourcePath: "", warnings: [] } : discoverAndLoadConfig({ explicit: options.configPath });
   const config = loaded.config;
   const [baseline, current] = await Promise.all([
-    loadSpec(baselinePath, { loader: { allowRemoteRefs: config.loader.allowRemoteRefs } }),
-    loadSpec(currentPath, { loader: { allowRemoteRefs: config.loader.allowRemoteRefs } })
+    loadSpec(baselinePath, { loader: config.loader }),
+    loadSpec(currentPath, { loader: config.loader })
   ]);
   structuralDeref(baseline.normalized);
   structuralDeref(current.normalized);
@@ -3812,6 +4007,7 @@ async function analyze(baselinePath, currentPath, options = {}) {
   };
   runStructuralDiff(ctx);
   const deduped = dedupeChanges(sortChanges([...ctx.candidates]));
+  attachSourceLocations(deduped, baseline, current);
   const { kept, ignored } = applyIgnores(deduped, config);
   const summary = summarize(kept, ignored.length);
   const semver = suggestVersion(kept);
@@ -3830,6 +4026,802 @@ async function analyze(baselinePath, currentPath, options = {}) {
   return { report, ignored };
 }
 
+// src/reporters/html.ts
+function esc(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function endpointOf(change) {
+  const loc = change.location;
+  if (loc.method && loc.path) return `${loc.method} ${loc.path}`;
+  if (loc.path && loc.path !== "/") return loc.path;
+  if (loc.context === "webhook") return `webhook ${loc.componentName ?? ""}`.trim();
+  if (loc.componentName) return `component ${loc.componentName}`;
+  return "API Root";
+}
+function valueRepr(v) {
+  if (v === void 0) return "absent";
+  if (v === null) return "null";
+  if (typeof v === "string") return v;
+  return JSON.stringify(v);
+}
+function renderHtml(report) {
+  const breaking = report.summary.bySeverity.error;
+  const warnings = report.summary.bySeverity.warning;
+  const infos = report.summary.bySeverity.info;
+  const total = report.summary.total;
+  const isPass = breaking === 0;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>API Guard Report - ${isPass ? "Passed" : "Breaking Changes Found"}</title>
+  <style>
+    /* Hallmark stamp: modern-minimal developer tool contract dashboard */
+    :root {
+      --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+      --bg-page: #f8fafc;
+      --bg-card: #ffffff;
+      --bg-input: #ffffff;
+      --border-subtle: #e2e8f0;
+      --border-strong: #cbd5e1;
+      --text-main: #0f172a;
+      --text-muted: #64748b;
+      --color-pass: #059669;
+      --color-pass-bg: #ecfdf5;
+      --color-pass-border: #a7f3d0;
+      --color-fail: #dc2626;
+      --color-fail-bg: #fef2f2;
+      --color-fail-border: #fecaca;
+      --color-warn: #d97706;
+      --color-warn-bg: #fffbeb;
+      --color-warn-border: #fde68a;
+      --color-info: #0284c7;
+      --color-info-bg: #f0f9ff;
+      --color-info-border: #bae6fd;
+      --color-accent: #2563eb;
+      --color-accent-bg: #eff6ff;
+      --focus-ring: #3b82f6;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg-page: #090d16;
+        --bg-card: #131b2e;
+        --bg-input: #1a243b;
+        --border-subtle: #1e293b;
+        --border-strong: #334155;
+        --text-main: #f1f5f9;
+        --text-muted: #94a3b8;
+        --color-pass: #10b981;
+        --color-pass-bg: #064e3b33;
+        --color-pass-border: #065f46;
+        --color-fail: #f87171;
+        --color-fail-bg: #7f1d1d33;
+        --color-fail-border: #991b1b;
+        --color-warn: #fbbf24;
+        --color-warn-bg: #78350f33;
+        --color-warn-border: #92400e;
+        --color-info: #38bdf8;
+        --color-info-bg: #0c4a6e33;
+        --color-info-border: #075985;
+        --color-accent: #60a5fa;
+        --color-accent-bg: #1e3a8a33;
+        --focus-ring: #60a5fa;
+      }
+    }
+
+    html, body {
+      margin: 0;
+      padding: 0;
+      overflow-x: clip;
+      background: var(--bg-page);
+      color: var(--text-main);
+      font-family: var(--font-body);
+      line-height: 1.5;
+      font-size: 15px;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    *:focus-visible {
+      outline: 2px solid var(--focus-ring);
+      outline-offset: 2px;
+    }
+
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 2.5rem 1.5rem 5rem 1.5rem;
+    }
+
+    .header {
+      background: var(--bg-card);
+      border: 1px solid var(--border-subtle);
+      border-radius: 8px;
+      padding: 1.75rem 2rem;
+      margin-bottom: 2rem;
+    }
+
+    .header-top {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      flex-wrap: wrap;
+      gap: 1rem;
+      margin-bottom: 1.25rem;
+    }
+
+    .title-row {
+      display: flex;
+      align-items: center;
+      gap: 1rem;
+    }
+
+    .brand-title {
+      font-size: 1.35rem;
+      font-weight: 700;
+      letter-spacing: -0.02em;
+      margin: 0;
+    }
+
+    .status-badge {
+      display: inline-flex;
+      align-items: center;
+      font-size: 0.825rem;
+      font-weight: 600;
+      padding: 0.25rem 0.75rem;
+      border-radius: 9999px;
+      border: 1px solid;
+    }
+
+    .status-badge.pass {
+      background: var(--color-pass-bg);
+      color: var(--color-pass);
+      border-color: var(--color-pass-border);
+    }
+
+    .status-badge.fail {
+      background: var(--color-fail-bg);
+      color: var(--color-fail);
+      border-color: var(--color-fail-border);
+    }
+
+    .spec-metadata {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+      gap: 1.25rem;
+      padding-top: 1.25rem;
+      border-top: 1px solid var(--border-subtle);
+      font-size: 0.875rem;
+      color: var(--text-muted);
+    }
+
+    .meta-box strong {
+      color: var(--text-main);
+      display: block;
+      margin-bottom: 0.2rem;
+    }
+
+    .meta-code {
+      font-family: var(--font-mono);
+      font-size: 0.8rem;
+    }
+
+    .stats-row {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+      gap: 1rem;
+      margin-bottom: 2rem;
+    }
+
+    .stat-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border-subtle);
+      border-radius: 8px;
+      padding: 1.25rem 1.5rem;
+    }
+
+    .stat-label {
+      font-size: 0.8rem;
+      color: var(--text-muted);
+      margin-bottom: 0.35rem;
+    }
+
+    .stat-value {
+      font-size: 1.75rem;
+      font-weight: 700;
+      line-height: 1;
+    }
+
+    .stat-card.error .stat-value { color: var(--color-fail); }
+    .stat-card.warning .stat-value { color: var(--color-warn); }
+    .stat-card.info .stat-value { color: var(--color-info); }
+    .stat-card.total .stat-value { color: var(--text-main); }
+
+    .semver-banner {
+      background: var(--color-accent-bg);
+      border: 1px solid var(--border-subtle);
+      border-left: 4px solid var(--color-accent);
+      border-radius: 6px;
+      padding: 1rem 1.25rem;
+      margin-bottom: 2rem;
+      font-size: 0.9rem;
+    }
+
+    .semver-banner strong {
+      color: var(--text-main);
+    }
+
+    .controls-bar {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 1rem;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: 1.5rem;
+    }
+
+    .search-input {
+      flex: 1 1 260px;
+      padding: 0.6rem 0.9rem;
+      font-size: 0.9rem;
+      border: 1px solid var(--border-strong);
+      border-radius: 6px;
+      background: var(--bg-input);
+      color: var(--text-main);
+    }
+
+    .filter-group {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 0.5rem;
+    }
+
+    .filter-btn {
+      padding: 0.45rem 0.85rem;
+      font-size: 0.825rem;
+      font-weight: 500;
+      border: 1px solid var(--border-strong);
+      border-radius: 6px;
+      background: var(--bg-card);
+      color: var(--text-muted);
+      cursor: pointer;
+    }
+
+    .filter-btn.active {
+      background: var(--color-accent);
+      color: #ffffff;
+      border-color: var(--color-accent);
+    }
+
+    .changes-list {
+      display: flex;
+      flex-direction: column;
+      gap: 1rem;
+    }
+
+    .change-card {
+      background: var(--bg-card);
+      border: 1px solid var(--border-subtle);
+      border-radius: 8px;
+      padding: 1.25rem 1.5rem;
+    }
+
+    .change-card.error { border-left: 4px solid var(--color-fail); }
+    .change-card.warning { border-left: 4px solid var(--color-warn); }
+    .change-card.info { border-left: 4px solid var(--color-info); }
+
+    .change-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: baseline;
+      flex-wrap: wrap;
+      gap: 0.5rem;
+      margin-bottom: 0.75rem;
+    }
+
+    .change-title-group {
+      display: flex;
+      align-items: center;
+      flex-wrap: wrap;
+      gap: 0.6rem;
+    }
+
+    .severity-tag {
+      font-size: 0.725rem;
+      font-weight: 700;
+      padding: 0.15rem 0.5rem;
+      border-radius: 4px;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+    }
+
+    .severity-tag.error { background: var(--color-fail-bg); color: var(--color-fail); border: 1px solid var(--color-fail-border); }
+    .severity-tag.warning { background: var(--color-warn-bg); color: var(--color-warn); border: 1px solid var(--color-warn-border); }
+    .severity-tag.info { background: var(--color-info-bg); color: var(--color-info); border: 1px solid var(--color-info-border); }
+
+    .rule-name {
+      font-family: var(--font-mono);
+      font-size: 0.85rem;
+      font-weight: 600;
+      color: var(--text-main);
+    }
+
+    .endpoint-pill {
+      font-family: var(--font-mono);
+      font-size: 0.825rem;
+      color: var(--text-muted);
+      background: var(--bg-page);
+      border: 1px solid var(--border-subtle);
+      padding: 0.15rem 0.5rem;
+      border-radius: 4px;
+    }
+
+    .location-info {
+      font-family: var(--font-mono);
+      font-size: 0.775rem;
+      color: var(--text-muted);
+    }
+
+    .change-message {
+      font-size: 0.95rem;
+      margin: 0 0 0.75rem 0;
+      color: var(--text-main);
+      word-break: break-word;
+    }
+
+    .suggestion-box {
+      font-size: 0.85rem;
+      color: var(--text-muted);
+      background: var(--bg-page);
+      border-radius: 6px;
+      padding: 0.6rem 0.9rem;
+      border: 1px solid var(--border-subtle);
+    }
+
+    .suggestion-box strong {
+      color: var(--text-main);
+    }
+
+    .diff-values {
+      margin-top: 0.75rem;
+      display: flex;
+      flex-wrap: wrap;
+      gap: 1rem;
+      font-family: var(--font-mono);
+      font-size: 0.8rem;
+    }
+
+    .val-block {
+      padding: 0.35rem 0.65rem;
+      border-radius: 4px;
+      background: var(--bg-page);
+      border: 1px solid var(--border-subtle);
+    }
+
+    .empty-state {
+      text-align: center;
+      padding: 4rem 2rem;
+      background: var(--bg-card);
+      border: 1px solid var(--border-subtle);
+      border-radius: 8px;
+      color: var(--text-muted);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      * {
+        animation-duration: 0.01ms !important;
+        transition-duration: 0.01ms !important;
+      }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header class="header">
+      <div class="header-top">
+        <div class="title-row">
+          <h1 class="brand-title">API Guard Diff Report</h1>
+          <span class="status-badge ${isPass ? "pass" : "fail"}">
+            ${isPass ? "PASS: No Breaking Changes" : "FAIL: Breaking Changes Detected"}
+          </span>
+        </div>
+        <div style="font-size: 0.85rem; color: var(--text-muted);">
+          Generated by apiguard ${esc(report.tool.version)}
+        </div>
+      </div>
+      <div class="spec-metadata">
+        <div class="meta-box">
+          <strong>Baseline Specification</strong>
+          <div>${esc(report.baseline.title || report.baseline.source)}</div>
+          <div class="meta-code">SHA: ${esc(report.baseline.sha256.slice(0, 16))} (${esc(report.baseline.openapiVersion)})</div>
+        </div>
+        <div class="meta-box">
+          <strong>Current Specification</strong>
+          <div>${esc(report.current.title || report.current.source)}</div>
+          <div class="meta-code">SHA: ${esc(report.current.sha256.slice(0, 16))} (${esc(report.current.openapiVersion)})</div>
+        </div>
+      </div>
+    </header>
+
+    <section class="stats-row">
+      <div class="stat-card error">
+        <div class="stat-label">Breaking Errors</div>
+        <div class="stat-value">${breaking}</div>
+      </div>
+      <div class="stat-card warning">
+        <div class="stat-label">Warnings</div>
+        <div class="stat-value">${warnings}</div>
+      </div>
+      <div class="stat-card info">
+        <div class="stat-label">Informational</div>
+        <div class="stat-value">${infos}</div>
+      </div>
+      <div class="stat-card total">
+        <div class="stat-label">Total Changes</div>
+        <div class="stat-value">${total}</div>
+      </div>
+    </section>
+
+    <div class="semver-banner">
+      <strong>Suggested Version Bump:</strong> ${esc(report.semver.bump.toUpperCase())} &mdash; ${esc(report.semver.reason)}
+    </div>
+
+    <section class="controls-bar">
+      <input type="search" id="searchInput" class="search-input" placeholder="Search by rule, path, or message..." aria-label="Search changes">
+      <div class="filter-group">
+        <button class="filter-btn active" data-severity="all">All (${total})</button>
+        <button class="filter-btn" data-severity="error">Errors (${breaking})</button>
+        <button class="filter-btn" data-severity="warning">Warnings (${warnings})</button>
+        <button class="filter-btn" data-severity="info">Info (${infos})</button>
+      </div>
+    </section>
+
+    <main class="changes-list" id="changesContainer">
+      ${report.changes.length === 0 ? `<div class="empty-state"><h3>No contract changes detected</h3><p>The current specification is fully compatible with the baseline.</p></div>` : report.changes.map((c) => {
+    const ep = endpointOf(c);
+    const locStr = c.location.file && c.location.line ? `${c.location.file}:${c.location.line}:${c.location.column ?? 1}` : c.location.pointerNew || c.location.pointerOld;
+    const hasDiff = c.oldValue !== void 0 || c.newValue !== void 0;
+    return `
+        <article class="change-card ${c.severity}" data-severity="${c.severity}" data-search="${esc(`${c.ruleId} ${ep} ${c.message} ${locStr}`).toLowerCase()}">
+          <div class="change-header">
+            <div class="change-title-group">
+              <span class="severity-tag ${c.severity}">${c.severity}</span>
+              <span class="rule-name">${esc(c.ruleId)}</span>
+              <span class="endpoint-pill">${esc(ep)}</span>
+            </div>
+            <div class="location-info">${esc(locStr)}</div>
+          </div>
+          <p class="change-message">${esc(c.message)}</p>
+          <div class="suggestion-box">
+            <strong>Suggestion:</strong> ${esc(c.suggestion)}
+          </div>
+          ${hasDiff ? `<div class="diff-values">
+            ${c.oldValue !== void 0 ? `<div class="val-block">Old: <code>${esc(valueRepr(c.oldValue))}</code></div>` : ""}
+            ${c.newValue !== void 0 ? `<div class="val-block">New: <code>${esc(valueRepr(c.newValue))}</code></div>` : ""}
+          </div>` : ""}
+        </article>`;
+  }).join("\n")}
+    </main>
+  </div>
+
+  <script>
+    (function() {
+      const searchInput = document.getElementById('searchInput');
+      const filterBtns = document.querySelectorAll('.filter-btn');
+      const cards = document.querySelectorAll('.change-card');
+      let currentSeverity = 'all';
+      let currentQuery = '';
+
+      function applyFilters() {
+        cards.forEach(card => {
+          const sev = card.getAttribute('data-severity');
+          const searchData = card.getAttribute('data-search') || '';
+          const matchesSev = (currentSeverity === 'all' || sev === currentSeverity);
+          const matchesQuery = (!currentQuery || searchData.includes(currentQuery));
+          card.style.display = (matchesSev && matchesQuery) ? '' : 'none';
+        });
+      }
+
+      if (searchInput) {
+        searchInput.addEventListener('input', e => {
+          currentQuery = e.target.value.trim().toLowerCase();
+          applyFilters();
+        });
+      }
+
+      filterBtns.forEach(btn => {
+        btn.addEventListener('click', () => {
+          filterBtns.forEach(b => b.classList.remove('active'));
+          btn.classList.add('active');
+          currentSeverity = btn.getAttribute('data-severity') || 'all';
+          applyFilters();
+        });
+      });
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+// src/reporters/sarif.ts
+function sarifLevel(severity) {
+  switch (severity) {
+    case "error":
+      return "error";
+    case "warning":
+      return "warning";
+    case "info":
+      return "note";
+  }
+}
+function renderSarif(report) {
+  const rules = getAllRules().map((r) => ({
+    id: r.id,
+    shortDescription: { text: r.id },
+    fullDescription: { text: r.trigger },
+    defaultConfiguration: {
+      level: sarifLevel(r.defaultSeverity)
+    },
+    help: {
+      text: `${r.trigger}
+Suggestion: ${r.suggestion({ location: { path: "/", pointerOld: "", pointerNew: "", context: "api" } })}`,
+      markdown: `**Trigger:** ${r.trigger}
+
+[API Guard Rule Reference](https://github.com/subhamxaura/apiguard/blob/main/docs/rules.md#${r.id})`
+    },
+    properties: {
+      tags: ["api-contract", "openapi", "breaking-change", ...r.contexts]
+    }
+  }));
+  const results = report.changes.map((c) => {
+    const fileUri = (c.location.file || report.current.source).replace(/\\/g, "/");
+    const line = c.location.line && c.location.line > 0 ? c.location.line : 1;
+    const col = c.location.column && c.location.column > 0 ? c.location.column : 1;
+    return {
+      ruleId: c.ruleId,
+      level: sarifLevel(c.severity),
+      message: {
+        text: `${c.message}. Suggestion: ${c.suggestion}`
+      },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: fileUri,
+              uriBaseId: "%SRCROOT%"
+            },
+            region: {
+              startLine: line,
+              startColumn: col
+            }
+          }
+        }
+      ],
+      properties: {
+        kind: c.kind,
+        breaking: c.breaking,
+        context: c.location.context,
+        path: c.location.path,
+        method: c.location.method
+      }
+    };
+  });
+  const sarifLog = {
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "apiguard",
+            version: report.tool.version,
+            informationUri: "https://github.com/subhamxaura/apiguard",
+            rules
+          }
+        },
+        results
+      }
+    ]
+  };
+  return JSON.stringify(sarifLog, null, 2);
+}
+
+// src/reporters/changelog.ts
+function endpointOf2(change) {
+  const loc = change.location;
+  if (loc.method && loc.path) return `\`${loc.method} ${loc.path}\``;
+  if (loc.path && loc.path !== "/") return `\`${loc.path}\``;
+  if (loc.componentName) return `component \`${loc.componentName}\``;
+  return "API";
+}
+function renderChangelog(report) {
+  const lines = [];
+  const version = report.semver.bump === "none" ? "Current Release (No version bump)" : `Next Release (Recommended bump: ${report.semver.bump.toUpperCase()})`;
+  lines.push(`## ${version}`);
+  lines.push("");
+  const breaking = report.changes.filter((c) => c.severity === "error");
+  const additions = report.changes.filter((c) => c.severity !== "error" && c.kind === "addition");
+  const modifications = report.changes.filter(
+    (c) => c.severity !== "error" && c.kind === "modification"
+  );
+  const relaxations = report.changes.filter(
+    (c) => c.severity !== "error" && (c.kind === "relaxation" || c.kind === "documentation")
+  );
+  if (breaking.length > 0) {
+    lines.push("### \u{1F6D1} Breaking Changes");
+    lines.push("");
+    for (const c of breaking) {
+      lines.push(`- **${endpointOf2(c)}**: ${c.message} (\`${c.ruleId}\`)`);
+      lines.push(`  *Suggestion: ${c.suggestion}*`);
+    }
+    lines.push("");
+  }
+  if (additions.length > 0) {
+    lines.push("### \u{1F680} Added");
+    lines.push("");
+    for (const c of additions) {
+      lines.push(`- **${endpointOf2(c)}**: ${c.message}`);
+    }
+    lines.push("");
+  }
+  if (modifications.length > 0) {
+    lines.push("### \u{1F504} Changed");
+    lines.push("");
+    for (const c of modifications) {
+      lines.push(`- **${endpointOf2(c)}**: ${c.message}`);
+    }
+    lines.push("");
+  }
+  if (relaxations.length > 0) {
+    lines.push("### \u2139\uFE0F Other Improvements");
+    lines.push("");
+    for (const c of relaxations) {
+      lines.push(`- **${endpointOf2(c)}**: ${c.message}`);
+    }
+    lines.push("");
+  }
+  if (report.changes.length === 0) {
+    lines.push("No functional contract changes detected between specifications.");
+  }
+  return lines.join("\n").trim();
+}
+
+// src/codegen/shim.ts
+function generateExpressShim(report) {
+  const breaking = report.changes.filter((c) => c.severity === "error");
+  const pathRewrites = [];
+  const paramDefaults = [];
+  for (const c of breaking) {
+    if (c.ruleId === "operation-removed" && c.location.path) {
+      pathRewrites.push({ oldPath: c.location.path });
+    } else if (c.ruleId === "parameter-added-required" || c.ruleId === "parameter-made-required") {
+      const paramName = c.location.pointerNew.split("/").pop() || "param";
+      paramDefaults.push({
+        method: c.location.method,
+        path: c.location.path,
+        param: paramName,
+        defaultVal: c.newValue ?? ""
+      });
+    }
+  }
+  return `// Generated by API Guard (apiguard codegen-shim --target express)
+// Backward compatibility shim for baseline @ ${report.baseline.sha256.slice(0, 12)}
+import type { Request, Response, NextFunction } from 'express';
+
+export function apiGuardCompatibilityShim(req: Request, res: Response, next: NextFunction) {
+  const method = req.method.toUpperCase();
+  const path = req.path;
+
+  // 1. Parameter defaults for newly required parameters
+${paramDefaults.map(
+    (p) => `  if (${p.method ? `method === '${p.method}' && ` : ""}path.startsWith('${p.path.replace(/\{.*\}/, "")}')) {
+    if (req.query['${p.param}'] === undefined && req.body?.['${p.param}'] === undefined) {
+      req.query['${p.param}'] = '${String(p.defaultVal)}';
+    }
+  }`
+  ).join("\n")}
+
+  // 2. Response adapter interception
+  const originalJson = res.json;
+  res.json = function(body: any) {
+    // Intercept and maintain legacy schema structure
+    if (body && typeof body === 'object') {
+      // Compatibility mutations can be inserted here
+    }
+    return originalJson.call(this, body);
+  };
+
+  next();
+}
+`;
+}
+function generateCloudflareWorkerShim(report) {
+  const breaking = report.changes.filter((c) => c.severity === "error");
+  return `// Generated by API Guard (apiguard codegen-shim --target cloudflare-worker)
+// Edge backward-compatibility worker
+export default {
+  async fetch(request: Request, env: any, ctx: any): Promise<Response> {
+    const url = new URL(request.url);
+    const method = request.method.toUpperCase();
+
+    // Clone request headers for mutation
+    const modifiedHeaders = new Headers(request.headers);
+
+    // Track downstream upstream response
+    const response = await fetch(new Request(url.toString(), {
+      method: request.method,
+      headers: modifiedHeaders,
+      body: request.body,
+      redirect: 'manual'
+    }));
+
+    // Intercept JSON responses for schema backward compatibility
+    const contentType = response.headers.get('content-type') || '';
+    if (contentType.includes('application/json')) {
+      try {
+        const data = await response.json();
+        // ${breaking.length} breaking changes monitored
+        return new Response(JSON.stringify(data), {
+          status: response.status,
+          headers: response.headers
+        });
+      } catch {
+        // Pass through unmodified if not json
+      }
+    }
+
+    return response;
+  }
+};
+`;
+}
+function generateEnvoyLuaShim(report) {
+  return `-- Generated by API Guard (apiguard codegen-shim --target envoy-lua)
+-- Envoy Proxy Lua filter for API backward compatibility (baseline: ${report.baseline.sha256.slice(0, 12)})
+
+function envoy_on_request(request_handle)
+  local headers = request_handle:headers()
+  local path = headers:get(":path")
+  local method = headers:get(":method")
+
+  -- Check for API compatibility headers
+  if not headers:get("x-apiguard-shimmed") then
+    headers:add("x-apiguard-shimmed", "true")
+  end
+end
+
+function envoy_on_response(response_handle)
+  local headers = response_handle:headers()
+  headers:add("x-apiguard-adapter", "v1-compat")
+end
+`;
+}
+function generateGatewayShim(report, target = "express") {
+  const breaking = report.changes.filter((c) => c.severity === "error");
+  let code;
+  switch (target) {
+    case "express":
+      code = generateExpressShim(report);
+      break;
+    case "cloudflare-worker":
+      code = generateCloudflareWorkerShim(report);
+      break;
+    case "envoy-lua":
+      code = generateEnvoyLuaShim(report);
+      break;
+  }
+  return {
+    target,
+    code,
+    handledChanges: breaking.length
+  };
+}
+
 export {
   ExitCode,
   ApiguardError,
@@ -3844,5 +4836,9 @@ export {
   validateSemantics,
   formatIssues,
   suggestVersion,
-  analyze
+  analyze,
+  renderHtml,
+  renderSarif,
+  renderChangelog,
+  generateGatewayShim
 };