contract-drift-detection 0.1.0

package/dist/cli.js

@@ -0,0 +1,721 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import process from "process";
+
+// src/config.ts
+import { mkdir, writeFile } from "fs/promises";
+import path from "path";
+import { Command } from "commander";
+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.command("serve").description("Start the mock engine").requiredOption("--spec <path>", "Path to an OpenAPI 3.x file").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);
+  program.command("init").description("Create a starter config for the current workspace").option("--spec <path>", "Default OpenAPI path", "openapi.yaml").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");
+  return program;
+}
+function toServeConfig(options) {
+  return {
+    specPath: String(options.spec),
+    port: Number(options.port ?? 4010),
+    host: String(options.host ?? "0.0.0.0"),
+    dbPath: String(options.db ?? ".mock-db.json"),
+    corsOrigin: String(options.corsOrigin ?? "*"),
+    driftCheckTarget: options.driftCheck ? String(options.driftCheck) : void 0,
+    fallbackToMockOnProxyError: Boolean(options.fallbackToMock),
+    verbose: Boolean(options.verbose)
+  };
+}
+async function writeStarterConfig(cwd, initConfig) {
+  const targetPath = path.join(cwd, "contract-drift.config.json");
+  await mkdir(cwd, { recursive: true });
+  await writeFile(
+    targetPath,
+    `${JSON.stringify(
+      {
+        spec: initConfig.spec,
+        db: initConfig.db,
+        host: initConfig.host,
+        port: initConfig.port
+      },
+      null,
+      2
+    )}
+`,
+    "utf8"
+  );
+  return targetPath;
+}
+
+// src/server.ts
+import path4 from "path";
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+
+// src/utils.ts
+import path2 from "path";
+function isSchemaObject(schema) {
+  return Boolean(schema) && !("$ref" in schema);
+}
+function normalizeCollectionName(raw) {
+  return raw.replace(/[{}]/g, "").split("/").filter(Boolean).at(-1)?.replace(/[^a-zA-Z0-9]+/g, "_").toLowerCase() ?? "items";
+}
+function toFastifyPath(openApiPath) {
+  return openApiPath.replace(/\{([^}]+)\}/g, ":$1");
+}
+function singularize(value) {
+  if (value.endsWith("ies")) {
+    return `${value.slice(0, -3)}y`;
+  }
+  if (value.endsWith("s")) {
+    return value.slice(0, -1);
+  }
+  return value;
+}
+function resolveFile(baseDir, filePath) {
+  return path2.isAbsolute(filePath) ? filePath : path2.join(baseDir, filePath);
+}
+function getOperationId(method, openApiPath, operation) {
+  if (operation.operationId) {
+    return operation.operationId;
+  }
+  const sanitizedPath = openApiPath.replace(/[{}]/g, "").split("/").filter(Boolean).join("_");
+  return `${method}_${sanitizedPath || "root"}`;
+}
+function inferPathParamName(openApiPath) {
+  const match = openApiPath.match(/\{([^}]+)\}/);
+  return match?.[1];
+}
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function deepMerge(base, patch) {
+  const output = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && output[key] && typeof output[key] === "object" && !Array.isArray(output[key])) {
+      output[key] = deepMerge(
+        output[key],
+        value
+      );
+    } else {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+function readContentType(headers) {
+  return headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() ?? "";
+}
+function isJsonLikeContentType(contentType) {
+  return contentType === "application/json" || contentType.endsWith("+json");
+}
+
+// src/dsl.ts
+function resolvePathExpression(source, expression) {
+  return expression.split(".").reduce((value, segment) => value && typeof value === "object" ? value[segment] : void 0, source);
+}
+function evaluateTemplate(value, request) {
+  if (typeof value === "string") {
+    const match = value.match(/^\{\{\s*(.+?)\s*\}\}$/);
+    if (!match) {
+      return value;
+    }
+    return resolvePathExpression(
+      {
+        params: request.params,
+        query: request.query,
+        body: request.body,
+        headers: request.headers
+      },
+      match[1]
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => evaluateTemplate(entry, request));
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, evaluateTemplate(entry, request)])
+    );
+  }
+  return value;
+}
+function applyDslMutation(extension, request, collection, defaultIdKey) {
+  const idKey = extension.find_by ?? defaultIdKey;
+  const targetId = request.params[idKey] ?? request.params.id;
+  const evaluatedAssign = evaluateTemplate(extension.assign ?? {}, request) ?? {};
+  const evaluatedSet = evaluateTemplate(extension.set ?? {}, request) ?? {};
+  switch (extension.action) {
+    case "create": {
+      const candidate = {
+        ...request.body ?? {},
+        ...evaluatedAssign,
+        ...evaluatedSet
+      };
+      collection.push(candidate);
+      return candidate;
+    }
+    case "append": {
+      const item = {
+        ...evaluatedAssign,
+        ...evaluatedSet
+      };
+      collection.push(item);
+      return collection;
+    }
+    case "replace": {
+      const nextValue = {
+        ...request.body ?? {},
+        ...evaluatedAssign,
+        ...evaluatedSet
+      };
+      const index = collection.findIndex((entry) => String(entry[idKey]) === String(targetId));
+      if (index >= 0) {
+        collection[index] = nextValue;
+      }
+      return nextValue;
+    }
+    case "delete": {
+      const index = collection.findIndex((entry) => String(entry[idKey]) === String(targetId));
+      if (index >= 0) {
+        const [removed] = collection.splice(index, 1);
+        return removed;
+      }
+      return null;
+    }
+    case "update":
+    default: {
+      const entity = collection.find((entry) => String(entry[idKey]) === String(targetId));
+      if (!entity) {
+        return null;
+      }
+      const merged = deepMerge(entity, {
+        ...evaluatedAssign,
+        ...evaluatedSet
+      });
+      Object.assign(entity, merged);
+      return entity;
+    }
+  }
+}
+
+// src/drift-detector.ts
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+import pc from "picocolors";
+function formatErrors(errors) {
+  return (errors ?? []).map((error) => {
+    const location = error.instancePath || "/";
+    return `${location} ${error.message ?? "failed validation"}`.trim();
+  });
+}
+var DriftDetector = class {
+  constructor(logger) {
+    this.logger = logger;
+    addFormats(this.ajv);
+  }
+  ajv = new Ajv({ allErrors: true, strict: false });
+  validate(method, path5, statusCode, schema, body) {
+    if (!schema || body === void 0 || body === null) {
+      return null;
+    }
+    const validate = this.ajv.compile(schema);
+    const valid = validate(body);
+    if (valid) {
+      return null;
+    }
+    const issue = {
+      method: method.toUpperCase(),
+      path: path5,
+      statusCode,
+      message: `Drift detected for ${method.toUpperCase()} ${path5} (${statusCode})`,
+      errors: formatErrors(validate.errors)
+    };
+    this.logger.error(
+      `${pc.red("DRIFT DETECTED")} ${issue.method} ${issue.path} -> ${issue.errors.join("; ")}`
+    );
+    return issue;
+  }
+};
+
+// src/route-context.ts
+var SUPPORTED_METHODS = ["get", "post", "put", "patch", "delete"];
+function getRequestBodySchema(operation) {
+  const content = operation.requestBody && !("$ref" in operation.requestBody) ? operation.requestBody.content?.["application/json"] : void 0;
+  return isSchemaObject(content?.schema) ? content.schema : void 0;
+}
+function getSuccessResponse(operation) {
+  const preferredCodes = ["200", "201", "202", "204"];
+  for (const code of preferredCodes) {
+    const response = operation.responses?.[code];
+    if (!response || "$ref" in response) {
+      continue;
+    }
+    const schema = response.content?.["application/json"]?.schema;
+    return {
+      statusCode: Number(code),
+      schema: isSchemaObject(schema) ? schema : void 0
+    };
+  }
+  return void 0;
+}
+function buildRouteContexts(document) {
+  const routes = [];
+  for (const [openApiPath, pathItem] of Object.entries(document.paths ?? {})) {
+    if (!pathItem || "$ref" in pathItem) {
+      continue;
+    }
+    for (const method of SUPPORTED_METHODS) {
+      const operation = pathItem[method];
+      if (!operation || "$ref" in operation) {
+        continue;
+      }
+      const pathParamName = inferPathParamName(openApiPath);
+      const resourceName = normalizeCollectionName(
+        pathParamName ? openApiPath.replace(/\/\{[^}]+\}$/, "") : openApiPath
+      );
+      const route = {
+        method,
+        path: openApiPath,
+        fastifyPath: toFastifyPath(openApiPath),
+        operation,
+        operationId: getOperationId(method, openApiPath, operation),
+        resourceName,
+        isCollection: !pathParamName,
+        pathParamName,
+        requestBodySchema: getRequestBodySchema(operation),
+        successResponse: getSuccessResponse(operation)
+      };
+      routes.push(route);
+    }
+  }
+  return routes;
+}
+
+// src/schema-seeder.ts
+import { faker } from "@faker-js/faker";
+function seedPrimitive(schema) {
+  if (schema.enum?.length) {
+    return schema.enum[0];
+  }
+  switch (schema.type) {
+    case "string": {
+      if (schema.format === "email") {
+        return faker.internet.email();
+      }
+      if (schema.format === "date-time") {
+        return faker.date.recent().toISOString();
+      }
+      if (schema.format === "uuid") {
+        return faker.string.uuid();
+      }
+      return faker.lorem.words(2);
+    }
+    case "integer":
+      return faker.number.int({ min: 1, max: 1e3 });
+    case "number":
+      return faker.number.float({ min: 1, max: 1e3, fractionDigits: 2 });
+    case "boolean":
+      return faker.datatype.boolean();
+    default:
+      return null;
+  }
+}
+function seedFromSchema(schema, depth = 0) {
+  if (!schema || depth > 4) {
+    return null;
+  }
+  if (schema.oneOf?.length && isSchemaObject(schema.oneOf[0])) {
+    return seedFromSchema(schema.oneOf[0], depth + 1);
+  }
+  if (schema.anyOf?.length && isSchemaObject(schema.anyOf[0])) {
+    return seedFromSchema(schema.anyOf[0], depth + 1);
+  }
+  if (schema.allOf?.length) {
+    return schema.allOf.reduce((accumulator, item) => {
+      if (!isSchemaObject(item)) {
+        return accumulator;
+      }
+      const seeded = seedFromSchema(item, depth + 1);
+      if (seeded && typeof seeded === "object" && !Array.isArray(seeded)) {
+        Object.assign(accumulator, seeded);
+      }
+      return accumulator;
+    }, {});
+  }
+  if (schema.type === "array") {
+    const item = isSchemaObject(schema.items) ? schema.items : void 0;
+    return [seedFromSchema(item, depth + 1), seedFromSchema(item, depth + 1)].filter(
+      (value) => value !== null
+    );
+  }
+  if (schema.type === "object" || schema.properties) {
+    const entries = Object.entries(schema.properties ?? {}).map(([key, value]) => {
+      if (!isSchemaObject(value)) {
+        return [key, null];
+      }
+      return [key, seedFromSchema(value, depth + 1)];
+    });
+    return Object.fromEntries(entries);
+  }
+  return seedPrimitive(schema);
+}
+function inferSeedCollections(document) {
+  const collections = {};
+  for (const [schemaName, schemaValue] of Object.entries(document.components?.schemas ?? {})) {
+    if (!isSchemaObject(schemaValue) || schemaValue.type !== "object") {
+      continue;
+    }
+    const collectionName = `${singularize(schemaName).toLowerCase()}s`;
+    collections[collectionName] = Array.from({ length: 3 }, () => seedFromSchema(schemaValue));
+  }
+  return collections;
+}
+
+// src/spec-loader.ts
+import SwaggerParser from "@apidevtools/swagger-parser";
+async function loadOpenApiDocument(specPath) {
+  const document = await SwaggerParser.dereference(specPath);
+  if (!document.openapi?.startsWith("3.")) {
+    throw new Error(`Only OpenAPI 3.x specs are supported. Received: ${document.openapi}`);
+  }
+  return document;
+}
+
+// src/state-store.ts
+import { mkdir as mkdir2, readFile, writeFile as writeFile2 } from "fs/promises";
+import path3 from "path";
+function normalizeDatabase(input) {
+  return {
+    collections: input?.collections ?? {},
+    counters: input?.counters ?? {}
+  };
+}
+var JsonStateStore = class {
+  filePath;
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  async initialize(seedCollections) {
+    await mkdir2(path3.dirname(this.filePath), { recursive: true });
+    try {
+      const existing = await this.read();
+      let changed = false;
+      for (const [collectionName, items] of Object.entries(seedCollections)) {
+        if (!existing.collections[collectionName]) {
+          existing.collections[collectionName] = deepClone(items);
+          existing.counters[collectionName] = items.length;
+          changed = true;
+        }
+      }
+      if (changed) {
+        await this.write(existing);
+      }
+      return existing;
+    } catch {
+      const initial = {
+        collections: deepClone(seedCollections),
+        counters: Object.fromEntries(
+          Object.entries(seedCollections).map(([name, items]) => [name, items.length])
+        )
+      };
+      await this.write(initial);
+      return initial;
+    }
+  }
+  async read() {
+    const raw = await readFile(this.filePath, "utf8");
+    return normalizeDatabase(JSON.parse(raw));
+  }
+  async write(database) {
+    await writeFile2(this.filePath, `${JSON.stringify(database, null, 2)}
+`, "utf8");
+  }
+  async withDatabase(updater) {
+    const database = await this.read();
+    const result = await updater(database);
+    await this.write(database);
+    return result;
+  }
+};
+
+// src/proxy.ts
+async function proxyRequest(targetBaseUrl, path5, init) {
+  const response = await fetch(new URL(path5, targetBaseUrl), init);
+  const contentType = readContentType(response.headers);
+  let body;
+  let rawBody;
+  if (response.status !== 204) {
+    rawBody = await response.text();
+    if (rawBody && isJsonLikeContentType(contentType)) {
+      body = JSON.parse(rawBody);
+    } else if (rawBody) {
+      body = rawBody;
+    }
+  }
+  return {
+    ok: response.ok,
+    statusCode: response.status,
+    headers: response.headers,
+    body,
+    rawBody
+  };
+}
+
+// src/server.ts
+function sendResponse(reply, statusCode, body) {
+  if (statusCode === 204) {
+    return reply.code(204).send();
+  }
+  return reply.code(statusCode).send(body);
+}
+function defaultStatusCode(route) {
+  if (route.method === "post") {
+    return 201;
+  }
+  if (route.method === "delete") {
+    return 204;
+  }
+  return 200;
+}
+function getRequestBody(request) {
+  if (!request.body || typeof request.body !== "object" || Array.isArray(request.body)) {
+    return {};
+  }
+  return request.body;
+}
+function getCollection(database, route) {
+  if (!database.collections[route.resourceName]) {
+    database.collections[route.resourceName] = [];
+    database.counters[route.resourceName] = 0;
+  }
+  return database.collections[route.resourceName];
+}
+function getCollectionByName(database, collectionName) {
+  if (!database.collections[collectionName]) {
+    database.collections[collectionName] = [];
+    database.counters[collectionName] = 0;
+  }
+  return database.collections[collectionName];
+}
+function computeIdKey(route) {
+  return route.pathParamName ?? "id";
+}
+function normalizeComparable(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return void 0;
+}
+function nextId(database, route) {
+  const current = database.counters[route.resourceName] ?? 0;
+  const next = current + 1;
+  database.counters[route.resourceName] = next;
+  return next;
+}
+function allocateUniqueId(database, route, collection, idKey) {
+  let candidate = nextId(database, route);
+  const hasCollision = (value) => collection.some((item) => normalizeComparable(item[idKey]) === String(value));
+  while (hasCollision(candidate)) {
+    candidate = nextId(database, route);
+  }
+  return candidate;
+}
+function resolveEntity(route, collection, request) {
+  const idKey = computeIdKey(route);
+  const rawId = normalizeComparable(
+    request.params[idKey] ?? request.params.id
+  );
+  return collection.find((item) => normalizeComparable(item[idKey]) === rawId);
+}
+function materializeMockBody(route, request) {
+  const requestBody = getRequestBody(request);
+  const seeded = route.requestBodySchema ? seedFromSchema(route.requestBodySchema) : {};
+  return deepMerge(
+    seeded && typeof seeded === "object" && !Array.isArray(seeded) ? seeded : {},
+    requestBody
+  );
+}
+function getNotFoundResponse(route) {
+  return {
+    statusCode: 404,
+    body: { message: `${route.resourceName} not found` }
+  };
+}
+function handleReadRoute(route, collection, request) {
+  if (route.isCollection) {
+    return { statusCode: 200, body: collection };
+  }
+  const entity = resolveEntity(route, collection, request);
+  return entity ? { statusCode: 200, body: entity } : getNotFoundResponse(route);
+}
+function handleCreateRoute(database, route, collection, request) {
+  const entity = materializeMockBody(route, request);
+  const idKey = computeIdKey(route);
+  if (entity[idKey] === void 0) {
+    entity[idKey] = allocateUniqueId(database, route, collection, idKey);
+  }
+  collection.push(entity);
+  return { statusCode: route.successResponse?.statusCode ?? 201, body: entity };
+}
+function handleUpdateRoute(route, collection, request) {
+  const current = resolveEntity(route, collection, request);
+  if (!current) {
+    return getNotFoundResponse(route);
+  }
+  const merged = route.method === "put" ? materializeMockBody(route, request) : deepMerge(current, getRequestBody(request));
+  Object.assign(current, merged);
+  return { statusCode: 200, body: current };
+}
+function handleDeleteRoute(route, collection, request) {
+  const entity = resolveEntity(route, collection, request);
+  if (!entity) {
+    return getNotFoundResponse(route);
+  }
+  const index = collection.indexOf(entity);
+  collection.splice(index, 1);
+  return { statusCode: 204 };
+}
+async function handleMockRoute(store, route, request) {
+  return store.withDatabase(async (database) => {
+    const collection = getCollection(database, route);
+    const extension = route.operation["x-mock-state"];
+    if (extension) {
+      const targetCollection = extension.target ? getCollectionByName(database, extension.target) : collection;
+      const response = applyDslMutation(extension, request, targetCollection, computeIdKey(route));
+      if (extension.response === "none") {
+        return { statusCode: 204 };
+      }
+      if (extension.response === "collection") {
+        return { statusCode: route.successResponse?.statusCode ?? 200, body: targetCollection };
+      }
+      return { statusCode: route.successResponse?.statusCode ?? defaultStatusCode(route), body: response };
+    }
+    switch (route.method) {
+      case "get": {
+        return handleReadRoute(route, collection, request);
+      }
+      case "post": {
+        return handleCreateRoute(database, route, collection, request);
+      }
+      case "put":
+      case "patch": {
+        return handleUpdateRoute(route, collection, request);
+      }
+      case "delete": {
+        return handleDeleteRoute(route, collection, request);
+      }
+    }
+  });
+}
+async function handleProxyRoute(config, route, detector, request) {
+  const rawBody = request.body ? JSON.stringify(request.body) : void 0;
+  const targetBaseUrl = config.driftCheckTarget;
+  if (!targetBaseUrl) {
+    throw new Error("Proxy target is not configured");
+  }
+  const result = await proxyRequest(targetBaseUrl, request.url, {
+    method: request.method,
+    headers: {
+      "content-type": request.headers["content-type"] ?? "application/json"
+    },
+    body: rawBody
+  });
+  detector.validate(
+    route.method,
+    route.path,
+    result.statusCode,
+    route.successResponse?.schema,
+    result.body
+  );
+  return {
+    statusCode: result.statusCode,
+    headers: Object.fromEntries(result.headers.entries()),
+    body: result.body
+  };
+}
+async function registerRoutes(app, document, config, store) {
+  const routes = buildRouteContexts(document);
+  const detector = new DriftDetector(app.log);
+  for (const route of routes) {
+    app.route({
+      method: route.method.toUpperCase(),
+      url: route.fastifyPath,
+      handler: async (request, reply) => {
+        if (config.driftCheckTarget) {
+          try {
+            const proxied = await handleProxyRoute(config, route, detector, request);
+            for (const [headerName, headerValue] of Object.entries(proxied.headers)) {
+              if (headerName.toLowerCase() === "content-length") {
+                continue;
+              }
+              reply.header(headerName, headerValue);
+            }
+            return reply.code(proxied.statusCode).send(proxied.body);
+          } catch (error) {
+            app.log.error({ error }, `Proxy execution failed for ${route.method.toUpperCase()} ${route.path}`);
+            if (!config.fallbackToMockOnProxyError) {
+              throw error;
+            }
+          }
+        }
+        const mockResponse = await handleMockRoute(store, route, request);
+        return sendResponse(reply, mockResponse.statusCode, mockResponse.body);
+      }
+    });
+  }
+}
+async function createServer(config) {
+  const app = Fastify({
+    logger: {
+      level: config.verbose ? "debug" : "error"
+    }
+  });
+  await app.register(cors, {
+    origin: config.corsOrigin === "*" ? true : config.corsOrigin,
+    methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    allowedHeaders: ["content-type", "authorization"],
+    credentials: false
+  });
+  const document = await loadOpenApiDocument(config.specPath);
+  const seedCollections = inferSeedCollections(document);
+  const dbPath = resolveFile(path4.dirname(config.specPath), config.dbPath);
+  const store = new JsonStateStore(dbPath);
+  await store.initialize(seedCollections);
+  app.get("/__health", async () => ({ status: "ok" }));
+  app.get("/__spec", async () => document);
+  await registerRoutes(app, document, config, store);
+  return app;
+}
+
+// src/cli.ts
+async function main() {
+  const cli = createCli();
+  const serveCommand = cli.commands.find((command) => command.name() === "serve");
+  const initCommand = cli.commands.find((command) => command.name() === "init");
+  serveCommand?.action(async function() {
+    const config = toServeConfig(this.opts());
+    const server = await createServer(config);
+    await server.listen({ port: config.port, host: config.host });
+    process.stdout.write(`Mock engine listening on http://${config.host}:${config.port}
+`);
+  });
+  initCommand?.action(async function() {
+    const options = this.opts();
+    const targetPath = await writeStarterConfig(process.cwd(), {
+      spec: String(options.spec),
+      db: String(options.db),
+      host: String(options.host),
+      port: Number(options.port)
+    });
+    process.stdout.write(`Created ${targetPath}
+`);
+  });
+  await cli.parseAsync(process.argv);
+}
+await main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.stack : String(error)}
+`);
+  process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map