@drift-agent/api-drift-engine 2.5.4

package/README.md

@@ -0,0 +1,133 @@
+# @drift-agent/api-drift-engine
+
+API schema diff engine — detect breaking changes in **OpenAPI**, **GraphQL**, and **gRPC** schemas.
+
+Thin npm wrapper around the [`drift-guard`](https://github.com/DriftAgent/api-drift-engine) Go binary. On install, the correct pre-built binary for your platform is downloaded automatically.
+
+## Installation
+
+```sh
+npm install @drift-agent/api-drift-engine
+```
+
+Requires Node.js ≥ 16. The binary is downloaded for your platform (macOS arm64/amd64, Linux arm64/amd64, Windows amd64) during `npm install`.
+
+## CLI
+
+After installing, the `drift-guard` binary is available as an npm bin:
+
+```sh
+npx drift-guard --help
+```
+
+### OpenAPI
+
+```sh
+drift-guard openapi --base old.yaml --head new.yaml
+drift-guard openapi --base old.yaml --head new.yaml --format json
+drift-guard openapi --base old.yaml --head new.yaml --fail-on-breaking
+```
+
+### GraphQL
+
+```sh
+drift-guard graphql --base old.graphql --head new.graphql
+drift-guard graphql --base old.graphql --head new.graphql --format markdown
+```
+
+### gRPC / Protobuf
+
+```sh
+drift-guard grpc --base old.proto --head new.proto
+drift-guard grpc --base old.proto --head new.proto --format json
+```
+
+### Impact analysis
+
+Scan source code for references to each breaking change:
+
+```sh
+# From a saved diff JSON
+drift-guard openapi --base old.yaml --head new.yaml --format json > diff.json
+drift-guard impact --diff diff.json --scan ./src
+
+# Pipe mode
+drift-guard openapi --base old.yaml --head new.yaml --format json \
+  | drift-guard impact --scan ./src
+
+# Output as markdown
+drift-guard impact --diff diff.json --scan ./src --format markdown
+```
+
+## Node.js / TypeScript API
+
+```ts
+import { compareOpenAPI, compareGraphQL, compareGRPC, impact } from "@drift-agent/api-drift-engine";
+
+// Diff two OpenAPI schemas
+const result = compareOpenAPI("old.yaml", "new.yaml");
+console.log(result.summary);
+// { total: 3, breaking: 1, non_breaking: 2, info: 0 }
+
+// Diff two GraphQL schemas
+const gqlResult = compareGraphQL("old.graphql", "new.graphql");
+
+// Diff two Protobuf schemas
+const grpcResult = compareGRPC("old.proto", "new.proto");
+
+// Scan source for references to breaking changes
+const hits = impact(result, "./src");
+// Returns Hit[] — file paths and line numbers that reference each breaking change
+
+// Text or markdown report
+const report = impact(result, "./src", { format: "markdown" });
+```
+
+### CommonJS
+
+```js
+const { compareOpenAPI, impact } = require("@drift-agent/api-drift-engine");
+```
+
+## TypeScript types
+
+```ts
+type Severity = "breaking" | "non-breaking" | "info";
+
+interface Change {
+  type: string;       // e.g. "endpoint_removed", "field_type_changed"
+  severity: Severity;
+  path: string;       // e.g. "/users/{id}"
+  method: string;     // e.g. "DELETE"
+  location: string;
+  description: string;
+  before?: string;
+  after?: string;
+}
+
+interface Summary {
+  total: number;
+  breaking: number;
+  non_breaking: number;
+  info: number;
+}
+
+interface DiffResult {
+  base_file: string;
+  head_file: string;
+  changes: Change[];
+  summary: Summary;
+}
+
+interface Hit {
+  file: string;
+  line_num: number;
+  line: string;
+  change_type: string;  // e.g. "endpoint_removed"
+  change_path: string;  // e.g. "DELETE /users/{id}"
+}
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,55 @@
+export type Severity = "breaking" | "non-breaking" | "info";
+
+export interface Change {
+  type: string;
+  severity: Severity;
+  path: string;
+  method: string;
+  location: string;
+  description: string;
+  before?: string;
+  after?: string;
+}
+
+export interface Summary {
+  total: number;
+  breaking: number;
+  non_breaking: number;
+  info: number;
+}
+
+export interface DiffResult {
+  base_file: string;
+  head_file: string;
+  changes: Change[];
+  summary: Summary;
+}
+
+export interface Hit {
+  file: string;
+  line_num: number;
+  line: string;
+  change_type: string;
+  change_path: string;
+}
+
+export interface ImpactOptions {
+  format?: "text" | "json" | "markdown";
+}
+
+/** Diff two OpenAPI 3.x schemas (YAML or JSON). */
+export function compareOpenAPI(base: string, head: string): DiffResult;
+
+/** Diff two GraphQL SDL schemas (.graphql or .gql). */
+export function compareGraphQL(base: string, head: string): DiffResult;
+
+/** Diff two Protobuf schemas (.proto). */
+export function compareGRPC(base: string, head: string): DiffResult;
+
+/**
+ * Scan a source directory for references to breaking changes.
+ * Returns Hit[] when format is "json" (default), otherwise a formatted string.
+ */
+export function impact(diffResult: DiffResult, scanDir?: string, options?: ImpactOptions & { format: "json" }): Hit[];
+export function impact(diffResult: DiffResult, scanDir?: string, options?: ImpactOptions & { format: "text" | "markdown" }): string;
+export function impact(diffResult: DiffResult, scanDir?: string, options?: ImpactOptions): Hit[] | string;

package/index.js

@@ -0,0 +1,86 @@
+"use strict";
+// Programmatic API — wraps the drift-guard binary and returns parsed results.
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const BIN = path.join(
+  __dirname,
+  "bin",
+  process.platform === "win32" ? "drift-guard.exe" : "drift-guard"
+);
+
+/**
+ * Run the drift-guard binary and return its stdout.
+ * @param {string[]} args
+ * @returns {string}
+ */
+function run(args) {
+  const result = spawnSync(BIN, args, { encoding: "utf8" });
+  if (result.error) {
+    throw new Error(`drift-guard binary error: ${result.error.message}`);
+  }
+  if (result.status !== 0 && result.status !== 1) {
+    // exit 1 means breaking changes found (--fail-on-breaking), not a crash
+    throw new Error(`drift-guard exited with code ${result.status}: ${result.stderr}`);
+  }
+  return result.stdout;
+}
+
+/**
+ * Diff two OpenAPI 3.x schemas.
+ * @param {string} base  Path to the base (old) schema file
+ * @param {string} head  Path to the head (new) schema file
+ * @returns {DiffResult}
+ */
+function compareOpenAPI(base, head) {
+  return JSON.parse(run(["openapi", "--base", base, "--head", head, "--format", "json"]));
+}
+
+/**
+ * Diff two GraphQL SDL schemas.
+ * @param {string} base
+ * @param {string} head
+ * @returns {DiffResult}
+ */
+function compareGraphQL(base, head) {
+  return JSON.parse(run(["graphql", "--base", base, "--head", head, "--format", "json"]));
+}
+
+/**
+ * Diff two Protobuf schemas.
+ * @param {string} base
+ * @param {string} head
+ * @returns {DiffResult}
+ */
+function compareGRPC(base, head) {
+  return JSON.parse(run(["grpc", "--base", base, "--head", head, "--format", "json"]));
+}
+
+/**
+ * Scan a directory for source references to breaking changes in a diff result.
+ * @param {DiffResult} diffResult
+ * @param {string} scanDir  Directory to scan (default ".")
+ * @param {{ format?: "text"|"json"|"markdown" }} [options]
+ * @returns {Hit[]|string}  Array of hits when format="json", otherwise formatted string
+ */
+function impact(diffResult, scanDir = ".", options = {}) {
+  const { format = "json" } = options;
+  const fs = require("fs");
+  const os = require("os");
+
+  // Write the diff result to a temp file so we can pass --diff
+  const tmp = require("path").join(os.tmpdir(), `drift-guard-diff-${Date.now()}.json`);
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(diffResult));
+    const out = run(["impact", "--diff", tmp, "--scan", scanDir, "--format", format]);
+    if (format === "json") {
+      return JSON.parse(out);
+    }
+    return out;
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+module.exports = { compareOpenAPI, compareGraphQL, compareGRPC, impact };

package/install.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// postinstall: downloads the drift-guard binary from GitHub Releases.
+"use strict";
+
+const https = require("https");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const VERSION = require("./package.json").version;
+const REPO = "DriftAgent/api-drift-engine";
+const BIN_DIR = path.join(__dirname, "bin");
+const BIN_PATH = path.join(BIN_DIR, process.platform === "win32" ? "drift-guard.exe" : "drift-guard");
+
+// Map Node.js platform/arch → goreleaser archive naming
+function getPlatformInfo() {
+  const p = process.platform;
+  const a = process.arch;
+
+  const osMap = { linux: "linux", darwin: "darwin", win32: "windows" };
+  const archMap = { x64: "amd64", arm64: "arm64" };
+
+  const goos = osMap[p];
+  const goarch = archMap[a];
+
+  if (!goos || !goarch) {
+    throw new Error(`Unsupported platform: ${p}/${a}`);
+  }
+  if (goos === "windows" && goarch === "arm64") {
+    throw new Error("Windows arm64 is not supported");
+  }
+
+  const ext = goos === "windows" ? "zip" : "tar.gz";
+  const archive = `drift-guard_${VERSION}_${goos}_${goarch}.${ext}`;
+  const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${archive}`;
+
+  return { url, archive, ext };
+}
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    function get(u) {
+      https.get(u, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          return get(res.headers.location);
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`Download failed: HTTP ${res.statusCode} for ${u}`));
+          return;
+        }
+        res.pipe(file);
+        file.on("finish", () => file.close(resolve));
+      }).on("error", reject);
+    }
+    get(url);
+  });
+}
+
+async function install() {
+  if (fs.existsSync(BIN_PATH)) {
+    return; // already installed (e.g. cached node_modules)
+  }
+
+  const { url, archive, ext } = getPlatformInfo();
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "drift-guard-"));
+  const archivePath = path.join(tmpDir, archive);
+
+  process.stdout.write(`Downloading drift-guard v${VERSION}...\n`);
+
+  try {
+    await download(url, archivePath);
+
+    fs.mkdirSync(BIN_DIR, { recursive: true });
+
+    if (ext === "tar.gz") {
+      execSync(`tar -xzf "${archivePath}" -C "${tmpDir}"`);
+    } else {
+      execSync(`unzip -o "${archivePath}" -d "${tmpDir}"`);
+    }
+
+    const extracted = path.join(tmpDir, process.platform === "win32" ? "drift-guard.exe" : "drift-guard");
+    fs.copyFileSync(extracted, BIN_PATH);
+    fs.chmodSync(BIN_PATH, 0o755);
+
+    process.stdout.write(`drift-guard installed to ${BIN_PATH}\n`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+install().catch((err) => {
+  process.stderr.write(`drift-guard install failed: ${err.message}\n`);
+  process.stderr.write("You can install it manually: https://github.com/DriftAgent/api-drift-engine/releases\n");
+  // Do not exit(1) — allow npm install to succeed even if binary download fails.
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@drift-agent/api-drift-engine",
+  "version": "2.5.4",
+  "description": "API schema diff engine — detect breaking changes in OpenAPI, GraphQL, and gRPC schemas",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "drift-guard": "run.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "run.js",
+    "install.js",
+    "bin/",
+    "README.md"
+  ],
+  "keywords": [
+    "api",
+    "openapi",
+    "graphql",
+    "grpc",
+    "schema",
+    "diff",
+    "breaking-changes",
+    "drift"
+  ],
+  "author": "DriftAgent",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DriftAgent/api-drift-engine"
+  },
+  "homepage": "https://github.com/DriftAgent/api-drift-engine",
+  "engines": {
+    "node": ">=16"
+  }
+}

package/run.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Thin shim: passes all arguments to the drift-guard binary.
+"use strict";
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const bin = path.join(
+  __dirname,
+  "bin",
+  process.platform === "win32" ? "drift-guard.exe" : "drift-guard"
+);
+
+const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  process.stderr.write(
+    `drift-guard: could not run binary: ${result.error.message}\n` +
+    `Make sure the package installed correctly or download manually:\n` +
+    `https://github.com/DriftAgent/api-drift-engine/releases\n`
+  );
+  process.exit(1);
+}
+
+process.exit(result.status ?? 0);