contract-drift-detection 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project are documented in this file.
 
+## 0.1.6 - 2026-03-16
+
+### Improved
+
+- Drift detection alerts now render as clean, colorized multiline terminal output instead of JSON-escaped logger lines.
+- Preserved structured drift payload logging at debug level for observability without cluttering normal terminal UX.
+- Updated drift proxy test assertions to validate pretty stderr output behavior.
+
+## 0.1.5 - 2026-03-16
+
+### Added
+
+- New drift reporting outputs via `--reporter pretty|json|junit`.
+- Optional report destination via `--report-file <path>`.
+- Strict drift mode via `--strict` to enforce `additionalProperties: false` behavior during validation.
+- Path-based drift ignore controls via repeated `--drift-ignore <path>` and `.driftignore` support.
+- New diagnostics endpoint: `GET /__drift` for in-memory drift issue visibility.
+- New unit test coverage for drift analyzer strict/ignore behavior.
+- New CLI e2e coverage for discover failure UX.
+
+### Improved
+
+- CI defaults now support fail-fast drift behavior with `--fail-on-drift`.
+- Drift validation pipeline now supports machine-readable reporting for CI gates.
+- Server-level drift callback flow for automated fail/report handling.
+
 ## 0.1.4 - 2026-03-16
 
 ### Improved

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import process from "process";
+import process2 from "process";
 
 // src/config.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
 import path2 from "path";
 import { Command } from "commander";
 
@@ -238,11 +238,26 @@ function resolvePathFromCwd(cwd, value) {
   return path2.isAbsolute(value) ? value : path2.join(cwd, value);
 }
 function applyServeOptions(command) {
-  return command.option("--spec <path>", "Path to an OpenAPI 3.x file").option("--spec-url <url>", "Remote URL to an OpenAPI 3.x file").option("--discover <backend-url>", "Discover OpenAPI from a backend URL and cache it locally").option("--port <port>", "Port to bind the server", "4010").option("--host <host>", "Host to bind the server", "0.0.0.0").option("--db <path>", "JSON database path", ".mock-db.json").option("--cors-origin <origin>", "CORS origin (default is *)", "*").option("--drift-check <url>", "Forward traffic to a real backend and validate responses").option("--fallback-to-mock", "Fallback to mock responses when proxying fails", false).option("--verbose", "Enable verbose logging", false);
+  return command.option("--spec <path>", "Path to an OpenAPI 3.x file").option("--spec-url <url>", "Remote URL to an OpenAPI 3.x file").option("--discover <backend-url>", "Discover OpenAPI from a backend URL and cache it locally").option("--port <port>", "Port to bind the server", "4010").option("--host <host>", "Host to bind the server", "0.0.0.0").option("--db <path>", "JSON database path", ".mock-db.json").option("--cors-origin <origin>", "CORS origin (default is *)", "*").option("--drift-check <url>", "Forward traffic to a real backend and validate responses").option("--strict", "Treat additional fields as drift", false).option("--drift-ignore <paths>", "Comma-separated JSON pointer paths to ignore during drift checks").option("--reporter <type>", "Drift reporter: pretty|json|junit", "pretty").option("--report-file <path>", "Output file path for json/junit reporters").option("--fail-on-drift", "Exit with code 1 when drift is detected (enabled by default in CI)", false).option("--fallback-to-mock", "Fallback to mock responses when proxying fails", false).option("--verbose", "Enable verbose logging", false);
+}
+function parseCsvOption(value) {
+  if (!value || typeof value !== "string") {
+    return [];
+  }
+  return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+}
+async function loadDriftIgnoreFromFile(cwd) {
+  const ignoreFilePath = path2.join(cwd, ".driftignore");
+  try {
+    const raw = await readFile(ignoreFilePath, "utf8");
+    return raw.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
+  } catch {
+    return [];
+  }
 }
 function createCli() {
   const program = new Command();
-  program.name("contract-drift-detection").description("Stateful OpenAPI mock server with contract drift detection").version("0.1.0");
+  program.name("contract-drift-detection").description("Stateful OpenAPI mock server with contract drift detection").version("0.1.6");
   applyServeOptions(program);
   applyServeOptions(program.command("serve").description("Start the mock engine"));
   program.command("init").description("Create a starter config for the current workspace").option("--spec <path>", "Default OpenAPI path", "openapi.yaml").option("--template <name>", "Template to generate (rest-crud | none)", "rest-crud").option("--db <path>", "Default JSON database path", ".mock-db.json").option("--port <port>", "Default port", "4010").option("--host <host>", "Default host", "0.0.0.0");
@@ -262,6 +277,13 @@ async function resolveServeConfig(cwd, options) {
   if (!resolvedSpecPath) {
     throw new Error("Provide one of --spec, --spec-url, or --discover");
   }
+  const ignoreFromCli = parseCsvOption(options.driftIgnore);
+  const ignoreFromFile = await loadDriftIgnoreFromFile(cwd);
+  const mergedIgnore = Array.from(/* @__PURE__ */ new Set([...ignoreFromFile, ...ignoreFromCli]));
+  const reporter = String(options.reporter ?? "pretty");
+  if (!["pretty", "json", "junit"].includes(reporter)) {
+    throw new Error(`Invalid reporter '${reporter}'. Use one of: pretty, json, junit`);
+  }
   return {
     specPath: resolvedSpecPath,
     port: Number(options.port ?? 4010),
@@ -269,6 +291,11 @@ async function resolveServeConfig(cwd, options) {
     dbPath: resolvePathFromCwd(cwd, String(options.db ?? ".mock-db.json")),
     corsOrigin: String(options.corsOrigin ?? "*"),
     driftCheckTarget: options.driftCheck ? String(options.driftCheck) : void 0,
+    strictDrift: Boolean(options.strict),
+    driftIgnorePaths: mergedIgnore,
+    reporter,
+    reportFile: options.reportFile ? resolvePathFromCwd(cwd, String(options.reportFile)) : void 0,
+    failOnDrift: Boolean(options.failOnDrift) || process.env.CI === "true",
     fallbackToMockOnProxyError: Boolean(options.fallbackToMock),
     verbose: Boolean(options.verbose)
   };
@@ -298,7 +325,7 @@ async function writeStarterConfig(cwd, initConfig) {
 }
 
 // src/server.ts
-import path5 from "path";
+import path6 from "path";
 import Fastify from "fastify";
 import cors from "@fastify/cors";
 
@@ -453,39 +480,112 @@ function applyDslMutation(extension, request, collection, defaultIdKey) {
 import Ajv from "ajv";
 import addFormats from "ajv-formats";
 import pc from "picocolors";
+function deepClone2(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function pathMatchesIgnoreRule(instancePath, rule) {
+  if (!rule) {
+    return false;
+  }
+  const pathSegments = instancePath.split("/").filter(Boolean);
+  const ruleSegments = rule.split("/").filter(Boolean);
+  if (ruleSegments.length > pathSegments.length) {
+    return false;
+  }
+  return ruleSegments.every((segment, index) => segment === "*" || segment === pathSegments[index]);
+}
+function applyStrictAdditionalProperties(schema) {
+  const output = deepClone2(schema);
+  const walk = (candidate) => {
+    if (candidate.type === "object" || candidate.properties) {
+      if (candidate.additionalProperties === void 0) {
+        candidate.additionalProperties = false;
+      }
+      for (const value of Object.values(candidate.properties ?? {})) {
+        if (value && !("$ref" in value)) {
+          walk(value);
+        }
+      }
+    }
+    if (candidate.type === "array" && candidate.items && !("$ref" in candidate.items)) {
+      walk(candidate.items);
+    }
+    for (const entry of candidate.allOf ?? []) {
+      if (!("$ref" in entry)) {
+        walk(entry);
+      }
+    }
+    for (const entry of candidate.oneOf ?? []) {
+      if (!("$ref" in entry)) {
+        walk(entry);
+      }
+    }
+    for (const entry of candidate.anyOf ?? []) {
+      if (!("$ref" in entry)) {
+        walk(entry);
+      }
+    }
+  };
+  walk(output);
+  return output;
+}
+function buildAjvSchema(schema, strictMode) {
+  return strictMode ? applyStrictAdditionalProperties(schema) : schema;
+}
 function formatErrors(errors) {
   return (errors ?? []).map((error) => {
     const location = error.instancePath || "/";
     return `${location} ${error.message ?? "failed validation"}`.trim();
   });
 }
+function analyzeDrift(ajv, schema, body, options) {
+  const normalizedSchema = buildAjvSchema(schema, options.strictMode);
+  const validate = ajv.compile(normalizedSchema);
+  const valid = validate(body);
+  if (valid) {
+    return [];
+  }
+  const filteredErrors = (validate.errors ?? []).filter(
+    (entry) => !options.ignorePaths.some((rule) => pathMatchesIgnoreRule(entry.instancePath || "/", rule))
+  );
+  return formatErrors(filteredErrors);
+}
 var DriftDetector = class {
-  constructor(logger) {
+  constructor(logger, options) {
     this.logger = logger;
     addFormats(this.ajv);
+    this.strictMode = options?.strictMode ?? false;
+    this.ignorePaths = options?.ignorePaths ?? [];
   }
   ajv = new Ajv({ allErrors: true, strict: false });
-  validate(method, path6, statusCode, schema, body) {
+  strictMode;
+  ignorePaths;
+  validate(method, path7, statusCode, schema, body) {
     if (!schema || body === void 0 || body === null) {
       return null;
     }
-    const validate = this.ajv.compile(schema);
-    const valid = validate(body);
-    if (valid) {
+    const errors = analyzeDrift(this.ajv, schema, body, {
+      strictMode: this.strictMode,
+      ignorePaths: this.ignorePaths
+    });
+    if (!errors.length) {
       return null;
     }
     const issue = {
       method: method.toUpperCase(),
-      path: path6,
+      path: path7,
       statusCode,
-      message: `Drift detected for ${method.toUpperCase()} ${path6} (${statusCode})`,
-      errors: formatErrors(validate.errors)
+      message: `Drift detected for ${method.toUpperCase()} ${path7} (${statusCode})`,
+      errors
     };
     const errorLines = issue.errors.map((entry) => `  \u2022 ${entry}`).join("\n");
-    this.logger.error([
+    const prettyBlock = [
       `${pc.bgRed(pc.black(" \u{1F6A8} DRIFT DETECTED "))} ${pc.bold(issue.method)} ${issue.path} (${statusCode})`,
       errorLines
-    ].join("\n"));
+    ].join("\n");
+    process.stderr.write(`${prettyBlock}
+`);
+    this.logger.debug({ drift: issue }, issue.message);
     return issue;
   }
 };
@@ -635,7 +735,7 @@ async function loadOpenApiDocument(specPath) {
 }
 
 // src/state-store.ts
-import { mkdir as mkdir3, readFile, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile3 } from "fs/promises";
 import path4 from "path";
 function normalizeDatabase(input) {
   return {
@@ -676,7 +776,7 @@ var JsonStateStore = class {
     }
   }
   async read() {
-    const raw = await readFile(this.filePath, "utf8");
+    const raw = await readFile2(this.filePath, "utf8");
     return normalizeDatabase(JSON.parse(raw));
   }
   async write(database) {
@@ -692,8 +792,8 @@ var JsonStateStore = class {
 };
 
 // src/proxy.ts
-async function proxyRequest(targetBaseUrl, path6, init) {
-  const response = await fetch(new URL(path6, targetBaseUrl), init);
+async function proxyRequest(targetBaseUrl, path7, init) {
+  const response = await fetch(new URL(path7, targetBaseUrl), init);
   const contentType = readContentType(response.headers);
   let body;
   let rawBody;
@@ -714,6 +814,56 @@ async function proxyRequest(targetBaseUrl, path6, init) {
   };
 }
 
+// src/drift-reporter.ts
+import { mkdir as mkdir4, writeFile as writeFile4 } from "fs/promises";
+import path5 from "path";
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function toJunit(issues) {
+  const testCases = issues.map((issue, index) => {
+    const name = `${issue.method} ${issue.path} (${issue.statusCode}) #${index + 1}`;
+    const failure = escapeXml(issue.errors.join("; "));
+    return `    <testcase classname="contract-drift-detection" name="${escapeXml(name)}">
+      <failure message="drift detected">${failure}</failure>
+    </testcase>`;
+  }).join("\n");
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<testsuite name="contract-drift-detection" tests="${issues.length}" failures="${issues.length}">`,
+    testCases,
+    "</testsuite>",
+    ""
+  ].join("\n");
+}
+function toJson(issues) {
+  const report = {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: {
+      total: issues.length
+    },
+    issues
+  };
+  return `${JSON.stringify(report, null, 2)}
+`;
+}
+function defaultReportPath(config) {
+  if (config.reportFile) {
+    return config.reportFile;
+  }
+  return config.reporter === "junit" ? "cdd-drift-report.xml" : "cdd-drift-report.json";
+}
+async function writeDriftReport(config, issues) {
+  if (config.reporter === "pretty") {
+    return null;
+  }
+  const filePath = defaultReportPath(config);
+  const content = config.reporter === "junit" ? toJunit(issues) : toJson(issues);
+  await mkdir4(path5.dirname(filePath), { recursive: true });
+  await writeFile4(filePath, content, "utf8");
+  return filePath;
+}
+
 // src/server.ts
 function toProxyHeaders(inputHeaders) {
   const passthrough = ["host", "content-length", "connection"];
@@ -886,7 +1036,7 @@ async function handleMockRoute(store, route, request) {
     }
   });
 }
-async function handleProxyRoute(config, route, detector, request) {
+async function handleProxyRoute(config, request) {
   const targetBaseUrl = config.driftCheckTarget;
   if (!targetBaseUrl) {
     throw new Error("Proxy target is not configured");
@@ -900,15 +1050,6 @@ async function handleProxyRoute(config, route, detector, request) {
     headers,
     body: toProxyBody(request)
   });
-  if (result.statusCode >= 200 && result.statusCode < 300) {
-    detector.validate(
-      route.method,
-      route.path,
-      result.statusCode,
-      route.successResponse?.schema,
-      result.body
-    );
-  }
   return {
     statusCode: result.statusCode,
     headers: Object.fromEntries(result.headers.entries()),
@@ -917,7 +1058,11 @@ async function handleProxyRoute(config, route, detector, request) {
 }
 async function registerRoutes(app, document, config, store) {
   const routes = buildRouteContexts(document);
-  const detector = new DriftDetector(app.log);
+  const detector = new DriftDetector(app.log, {
+    strictMode: config.strictDrift,
+    ignorePaths: config.driftIgnorePaths
+  });
+  const driftIssues = [];
   for (const route of routes) {
     app.route({
       method: route.method.toUpperCase(),
@@ -925,7 +1070,21 @@ async function registerRoutes(app, document, config, store) {
       handler: async (request, reply) => {
         if (config.driftCheckTarget) {
           try {
-            const proxied = await handleProxyRoute(config, route, detector, request);
+            const proxied = await handleProxyRoute(config, request);
+            if (proxied.statusCode >= 200 && proxied.statusCode < 300 && proxied.body !== void 0) {
+              const issue = detector.validate(
+                route.method,
+                route.path,
+                proxied.statusCode,
+                route.successResponse?.schema,
+                proxied.body
+              );
+              if (issue) {
+                driftIssues.push(issue);
+                await writeDriftReport(config, driftIssues);
+                await config.onDriftDetected?.(issue);
+              }
+            }
             for (const [headerName, headerValue] of Object.entries(proxied.headers)) {
               if (headerName.toLowerCase() === "content-length") {
                 continue;
@@ -955,6 +1114,10 @@ async function registerRoutes(app, document, config, store) {
       hasDsl: Boolean(route.operation["x-mock-state"])
     }))
   );
+  app.get("/__drift", async () => ({
+    total: driftIssues.length,
+    issues: driftIssues
+  }));
 }
 async function createServer(config) {
   const app = Fastify({
@@ -970,7 +1133,7 @@ async function createServer(config) {
   });
   const document = await loadOpenApiDocument(config.specPath);
   const seedCollections = inferSeedCollections(document);
-  const dbPath = resolveFile(path5.dirname(config.specPath), config.dbPath);
+  const dbPath = resolveFile(path6.dirname(config.specPath), config.dbPath);
   const store = new JsonStateStore(dbPath);
   await store.initialize(seedCollections);
   app.get("/__health", async () => ({ status: "ok" }));
@@ -986,8 +1149,12 @@ function renderStartupBanner(config) {
     `- Spec: ${config.specPath}`,
     `- DB: ${config.dbPath}`,
     `- Mode: ${config.driftCheckTarget ? `proxy + drift-check (${config.driftCheckTarget})` : "stateful mock"}`,
+    `- Drift policy: strict=${config.strictDrift ? "on" : "off"}, fail-on-drift=${config.failOnDrift ? "on" : "off"}`,
+    `- Reporter: ${config.reporter}${config.reportFile ? ` (${config.reportFile})` : ""}`,
+    `- Ignore rules: ${config.driftIgnorePaths.length ? config.driftIgnorePaths.join(", ") : "none"}`,
     "- Health: GET /__health",
-    "- Routes: GET /__routes"
+    "- Routes: GET /__routes",
+    "- Drift: GET /__drift"
   ];
   return `${lines.join("\n")}
 `;
@@ -998,10 +1165,21 @@ async function main() {
   const initCommand = cli.commands.find((command) => command.name() === "init");
   const quickstartCommand = cli.commands.find((command) => command.name() === "quickstart");
   const startServer = async (rawOptions) => {
-    const config = await resolveServeConfig(process.cwd(), rawOptions);
+    let hasFailedOnDrift = false;
+    const config = await resolveServeConfig(process2.cwd(), rawOptions);
+    config.onDriftDetected = async () => {
+      if (!config.failOnDrift || hasFailedOnDrift) {
+        return;
+      }
+      hasFailedOnDrift = true;
+      process2.stderr.write("Failing process because drift was detected (--fail-on-drift enabled).\n");
+      setTimeout(() => {
+        process2.exit(1);
+      }, 25);
+    };
     const server = await createServer(config);
     await server.listen({ port: config.port, host: config.host });
-    process.stdout.write(renderStartupBanner(config));
+    process2.stdout.write(renderStartupBanner(config));
   };
   serveCommand?.action(async function() {
     await startServer(this.opts());
@@ -1016,19 +1194,19 @@ async function main() {
   });
   initCommand?.action(async function() {
     const options = this.opts();
-    const targetPath = await writeStarterConfig(process.cwd(), {
+    const targetPath = await writeStarterConfig(process2.cwd(), {
       spec: String(options.spec),
       db: String(options.db),
       host: String(options.host),
       port: Number(options.port),
       template: options.template === "none" ? "none" : "rest-crud"
     });
-    process.stdout.write(`Created ${targetPath}
+    process2.stdout.write(`Created ${targetPath}
 `);
   });
   quickstartCommand?.action(async function() {
     const options = this.opts();
-    const cwd = process.cwd();
+    const cwd = process2.cwd();
     const specPath = String(options.spec ?? "openapi.yaml");
     await writeStarterConfig(cwd, {
       spec: specPath,
@@ -1047,22 +1225,22 @@ async function main() {
     });
     const server = await createServer(config);
     await server.listen({ port: config.port, host: config.host });
-    process.stdout.write(renderStartupBanner(config));
+    process2.stdout.write(renderStartupBanner(config));
   });
-  await cli.parseAsync(process.argv);
+  await cli.parseAsync(process2.argv);
 }
 await main().catch((error) => {
   if (error instanceof Error) {
-    process.stderr.write(`Error: ${error.message}
+    process2.stderr.write(`Error: ${error.message}
 `);
-    if (process.env.CDD_SHOW_STACK === "1") {
-      process.stderr.write(`${error.stack}
+    if (process2.env.CDD_SHOW_STACK === "1") {
+      process2.stderr.write(`${error.stack}
 `);
     }
   } else {
-    process.stderr.write(`${String(error)}
+    process2.stderr.write(`${String(error)}
 `);
   }
-  process.exitCode = 1;
+  process2.exitCode = 1;
 });
 //# sourceMappingURL=cli.js.map