@arpixel/api-contract 0.1.0

package/dist/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { generateCommand } from "./commands/generate.js";
+import { diffCommand } from "./commands/diff.js";
+import { initCommand } from "./commands/init.js";
+const program = new Command();
+program
+    .name("api-contract")
+    .description("Understand OpenAPI contract changes and generate frontend-ready TypeScript.")
+    .version("0.1.0");
+program
+    .command("generate")
+    .description("Generate TypeScript types and API method signatures from an OpenAPI file.")
+    .argument("<openapi-file>", "Path to OpenAPI YAML or JSON file")
+    .option("-o, --output <directory>", "Output directory")
+    .action(async (file, options) => {
+    try {
+        await generateCommand(file, options.output);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("diff")
+    .description("Compare two OpenAPI contracts.")
+    .argument("<old-file>", "Previous OpenAPI YAML or JSON file")
+    .argument("<new-file>", "New OpenAPI YAML or JSON file")
+    .option("-f, --format <format>", "Output format: text or json", "text")
+    .action(async (oldFile, newFile, options) => {
+    try {
+        if (options.format !== "text" && options.format !== "json") {
+            throw new Error(`Unsupported format "${options.format}". Use "text" or "json".`);
+        }
+        await diffCommand(oldFile, newFile, options.format);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+});
+program
+    .command("init")
+    .description("Install optional API Contract integrations.")
+    .option("--host <host>", "Integration host")
+    .action(async (options) => {
+    try {
+        await initCommand(options.host);
+    }
+    catch (error) {
+        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+});
+await program.parseAsync();

package/dist/commands/diff.d.ts

@@ -0,0 +1 @@
+export declare function diffCommand(oldPath: string, newPath: string, format: "text" | "json"): Promise<void>;

package/dist/commands/diff.js

@@ -0,0 +1,15 @@
+import { loadOpenApi } from "../openapi/loader.js";
+import { compareContracts } from "../diff/comparator.js";
+import { formatDiff } from "../diff/reporter.js";
+export async function diffCommand(oldPath, newPath, format) {
+    const [oldDocument, newDocument] = await Promise.all([
+        loadOpenApi(oldPath),
+        loadOpenApi(newPath)
+    ]);
+    const result = compareContracts(oldDocument, newDocument);
+    if (format === "json") {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(formatDiff(result));
+}

package/dist/commands/generate.d.ts

@@ -0,0 +1 @@
+export declare function generateCommand(inputPath: string, outputDir?: string): Promise<void>;

package/dist/commands/generate.js

@@ -0,0 +1,19 @@
+import { mkdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { generateApi } from "../generator/api.js";
+import { generateTypes } from "../generator/typescript.js";
+export async function generateCommand(inputPath, outputDir) {
+    const input = resolve(inputPath);
+    const output = outputDir
+        ? resolve(outputDir)
+        : resolve(process.cwd(), "api-contract/generated");
+    await mkdir(output, { recursive: true });
+    const typesPath = `${output}/types.ts`;
+    const apiPath = `${output}/api.ts`;
+    await generateTypes(input, typesPath);
+    await generateApi(input, apiPath);
+    console.log("Generated TypeScript API contract.");
+    console.log("\nOutput:");
+    console.log(`  ${typesPath}`);
+    console.log(`  ${apiPath}`);
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(host: string | undefined, homeDirectory?: string): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,33 @@
+import { copyFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const integrationDirectory = join(dirname(fileURLToPath(import.meta.url)), "../../integrations/vscode");
+const promptFiles = [
+    "api-contract-generate.prompt.md",
+    "api-contract-impact.prompt.md"
+];
+const agentFiles = [
+    "api-contract-generate.agent.md",
+    "api-contract-impact.agent.md"
+];
+export async function initCommand(host, homeDirectory = homedir()) {
+    if (!host) {
+        throw new Error('A host is required. Supported hosts: "vscode".');
+    }
+    if (host !== "vscode") {
+        throw new Error(`Unsupported host "${host}". Supported hosts: "vscode".`);
+    }
+    const promptDirectory = join(homeDirectory, ".api-contract", "prompts");
+    const agentDirectory = join(homeDirectory, ".copilot", "agents");
+    await mkdir(promptDirectory, { recursive: true });
+    await mkdir(agentDirectory, { recursive: true });
+    await Promise.all([
+        ...promptFiles.map(file => copyFile(join(integrationDirectory, file), join(promptDirectory, file))),
+        ...agentFiles.map(file => copyFile(join(integrationDirectory, file), join(agentDirectory, file)))
+    ]);
+    console.log("API Contract VS Code integration installed.");
+    console.log(`\nPrompts:\n  ~/.api-contract/prompts/${promptFiles.join("\n  ~/.api-contract/prompts/")}`);
+    console.log(`\nAgents:\n  ~/.copilot/agents/${agentFiles.join("\n  ~/.copilot/agents/")}`);
+    console.log(`\nPrompt usage options:\n\n1. Repository-local\n   Copy prompts from:\n     ~/.api-contract/prompts/\n   to:\n     .github/prompts/\n\n2. Global\n   Add this directory to VS Code's chat.promptFilesLocations:\n     ~/.api-contract/prompts\n\nThe API Contract agents are installed globally and can be selected from VS Code Chat.`);
+}

package/dist/diff/comparator.d.ts

@@ -0,0 +1,3 @@
+import type { OpenApiDocument } from "../openapi/loader.js";
+import type { DiffResult } from "../types/diff.js";
+export declare function compareContracts(oldDocument: OpenApiDocument, newDocument: OpenApiDocument): DiffResult;

package/dist/diff/comparator.js

@@ -0,0 +1,416 @@
+const METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function schemaType(schema) {
+    const value = asRecord(schema);
+    if (!value)
+        return "unknown";
+    if (typeof value.$ref === "string")
+        return value.$ref;
+    if (value.type === "array")
+        return `array<${schemaType(value.items)}>`;
+    if (typeof value.type === "string")
+        return String(value.type);
+    if (Array.isArray(value.oneOf))
+        return `oneOf(${value.oneOf.map(item => schemaType(item)).join("|")})`;
+    if (Array.isArray(value.allOf))
+        return `allOf(${value.allOf.map(item => schemaType(item)).join("&")})`;
+    return "object";
+}
+function schemaLocation(name) {
+    return `components.schemas.${name}`;
+}
+function propertyLocation(name, property) {
+    return `${schemaLocation(name)}.properties.${property}`;
+}
+function operationLocation(path, method) {
+    return `paths.${path}.${method}`;
+}
+function changeLocation(path, method, suffix) {
+    return `${operationLocation(path, method)}.${suffix}`;
+}
+function compareOperationDetails(path, method, oldOperation, newOperation, changes) {
+    const oldParameters = Array.isArray(oldOperation.parameters)
+        ? oldOperation.parameters
+            .map(item => asRecord(item))
+            .filter((item) => Boolean(item))
+        : [];
+    const newParameters = Array.isArray(newOperation.parameters)
+        ? newOperation.parameters
+            .map(item => asRecord(item))
+            .filter((item) => Boolean(item))
+        : [];
+    const parameterKey = (parameter) => `${String(parameter.in ?? "unknown")}.${String(parameter.name ?? "unknown")}`;
+    const oldParameterMap = new Map();
+    for (const parameter of oldParameters) {
+        oldParameterMap.set(parameterKey(parameter), parameter);
+    }
+    const newParameterMap = new Map();
+    for (const parameter of newParameters) {
+        newParameterMap.set(parameterKey(parameter), parameter);
+    }
+    for (const key of new Set([...oldParameterMap.keys(), ...newParameterMap.keys()])) {
+        const oldParameter = oldParameterMap.get(key);
+        const newParameter = newParameterMap.get(key);
+        const location = changeLocation(path, method, `parameters.${key}`);
+        const parameterName = typeof newParameter?.name === "string"
+            ? newParameter.name
+            : typeof oldParameter?.name === "string"
+                ? oldParameter.name
+                : key;
+        if (!oldParameter) {
+            const required = Boolean(newParameter?.required);
+            changes.push({
+                type: "PARAMETER_ADDED",
+                path,
+                method: method.toUpperCase(),
+                parameter: parameterName,
+                location,
+                to: { required },
+                detail: `${method.toUpperCase()} ${path} parameter ${parameterName} was added${required ? " as required" : ""}.`,
+                breaking: required
+            });
+            continue;
+        }
+        if (!newParameter) {
+            changes.push({
+                type: "PARAMETER_REMOVED",
+                path,
+                method: method.toUpperCase(),
+                parameter: parameterName,
+                location,
+                from: { required: Boolean(oldParameter.required) },
+                detail: `${method.toUpperCase()} ${path} parameter ${parameterName} was removed.`,
+                breaking: true
+            });
+            continue;
+        }
+        const oldType = schemaType(oldParameter.schema);
+        const newType = schemaType(newParameter.schema);
+        if (oldType !== newType) {
+            changes.push({
+                type: "PARAMETER_TYPE_CHANGED",
+                path,
+                method: method.toUpperCase(),
+                parameter: parameterName,
+                location,
+                from: oldType,
+                to: newType,
+                detail: `${method.toUpperCase()} ${path} parameter ${parameterName} type changed from ${oldType} to ${newType}.`,
+                breaking: true
+            });
+        }
+        if (Boolean(oldParameter.required) !== Boolean(newParameter.required)) {
+            const from = Boolean(oldParameter.required) ? "required" : "optional";
+            const to = Boolean(newParameter.required) ? "required" : "optional";
+            changes.push({
+                type: "PARAMETER_REQUIRED_CHANGED",
+                path,
+                method: method.toUpperCase(),
+                parameter: parameterName,
+                location,
+                from,
+                to,
+                detail: `${method.toUpperCase()} ${path} parameter ${parameterName} changed from ${from} to ${to}.`,
+                breaking: !Boolean(oldParameter.required) && Boolean(newParameter.required)
+            });
+        }
+    }
+    const oldResponses = asRecord(oldOperation.responses) ?? {};
+    const newResponses = asRecord(newOperation.responses) ?? {};
+    for (const status of new Set([...Object.keys(oldResponses), ...Object.keys(newResponses)])) {
+        const oldResponse = asRecord(oldResponses[status]);
+        const newResponse = asRecord(newResponses[status]);
+        const location = changeLocation(path, method, `responses.${status}`);
+        const oldResponseContent = asRecord(oldResponse?.content);
+        const newResponseContent = asRecord(newResponse?.content);
+        const oldResponseJson = asRecord(oldResponseContent?.["application/json"]);
+        const newResponseJson = asRecord(newResponseContent?.["application/json"]);
+        const oldResponseType = schemaType(oldResponseJson?.schema);
+        const newResponseType = schemaType(newResponseJson?.schema);
+        if (!oldResponse) {
+            changes.push({
+                type: "RESPONSE_ADDED",
+                path,
+                method: method.toUpperCase(),
+                status,
+                location,
+                to: newResponseType,
+                detail: `${method.toUpperCase()} ${path} response ${status} was added.`,
+                breaking: false
+            });
+        }
+        else if (!newResponse) {
+            changes.push({
+                type: "RESPONSE_REMOVED",
+                path,
+                method: method.toUpperCase(),
+                status,
+                location,
+                from: oldResponseType,
+                detail: `${method.toUpperCase()} ${path} response ${status} was removed.`,
+                breaking: true
+            });
+        }
+        else if (oldResponseType !== newResponseType) {
+            changes.push({
+                type: "RESPONSE_CHANGED",
+                path,
+                method: method.toUpperCase(),
+                status,
+                location,
+                from: oldResponseType,
+                to: newResponseType,
+                detail: `${method.toUpperCase()} ${path} response ${status} changed from ${oldResponseType} to ${newResponseType}.`,
+                breaking: true
+            });
+        }
+    }
+    const oldRequestBody = asRecord(oldOperation.requestBody);
+    const newRequestBody = asRecord(newOperation.requestBody);
+    const requestBodyLocation = changeLocation(path, method, "requestBody");
+    const oldRequestBodyContent = asRecord(oldRequestBody?.content);
+    const newRequestBodyContent = asRecord(newRequestBody?.content);
+    const oldRequestBodyJson = asRecord(oldRequestBodyContent?.["application/json"]);
+    const newRequestBodyJson = asRecord(newRequestBodyContent?.["application/json"]);
+    const oldRequestBodyType = schemaType(oldRequestBodyJson?.schema);
+    const newRequestBodyType = schemaType(newRequestBodyJson?.schema);
+    if (!oldRequestBody && newRequestBody) {
+        changes.push({
+            type: "REQUEST_BODY_ADDED",
+            path,
+            method: method.toUpperCase(),
+            location: requestBodyLocation,
+            to: newRequestBodyType,
+            detail: `${method.toUpperCase()} ${path} request body was added.`,
+            breaking: Boolean(newRequestBody.required)
+        });
+    }
+    else if (oldRequestBody && !newRequestBody) {
+        changes.push({
+            type: "REQUEST_BODY_REMOVED",
+            path,
+            method: method.toUpperCase(),
+            location: requestBodyLocation,
+            from: oldRequestBodyType,
+            detail: `${method.toUpperCase()} ${path} request body was removed.`,
+            breaking: true
+        });
+    }
+    else if (oldRequestBody && newRequestBody && oldRequestBodyType !== newRequestBodyType) {
+        changes.push({
+            type: "REQUEST_BODY_CHANGED",
+            path,
+            method: method.toUpperCase(),
+            location: requestBodyLocation,
+            from: oldRequestBodyType,
+            to: newRequestBodyType,
+            detail: `${method.toUpperCase()} ${path} request body changed from ${oldRequestBodyType} to ${newRequestBodyType}.`,
+            breaking: true
+        });
+    }
+}
+function compareSchemas(oldSchemas, newSchemas, changes) {
+    const names = new Set([...Object.keys(oldSchemas), ...Object.keys(newSchemas)]);
+    for (const name of names) {
+        const oldSchema = oldSchemas[name];
+        const newSchema = newSchemas[name];
+        if (!oldSchema) {
+            changes.push({
+                type: "SCHEMA_ADDED",
+                schema: name,
+                location: schemaLocation(name),
+                detail: `Schema ${name} was added.`,
+                breaking: false
+            });
+            continue;
+        }
+        if (!newSchema) {
+            changes.push({
+                type: "SCHEMA_REMOVED",
+                schema: name,
+                location: schemaLocation(name),
+                detail: `Schema ${name} was removed.`,
+                breaking: true
+            });
+            continue;
+        }
+        const oldProps = asRecord(oldSchema.properties) ?? {};
+        const newProps = asRecord(newSchema.properties) ?? {};
+        const oldRequired = new Set(asStringArray(oldSchema.required));
+        const newRequired = new Set(asStringArray(newSchema.required));
+        const props = new Set([...Object.keys(oldProps), ...Object.keys(newProps)]);
+        for (const property of props) {
+            const oldProp = oldProps[property];
+            const newProp = newProps[property];
+            if (!oldProp) {
+                const required = newRequired.has(property);
+                changes.push({
+                    type: "PROPERTY_ADDED",
+                    schema: name,
+                    property,
+                    location: propertyLocation(name, property),
+                    required,
+                    detail: `${name}.${property} was added${required ? " as required" : ""}.`,
+                    breaking: required
+                });
+                continue;
+            }
+            if (!newProp) {
+                changes.push({
+                    type: "PROPERTY_REMOVED",
+                    schema: name,
+                    property,
+                    location: propertyLocation(name, property),
+                    from: oldRequired.has(property) ? "required" : "optional",
+                    detail: `${name}.${property} was removed.`,
+                    breaking: true
+                });
+                continue;
+            }
+            const oldType = schemaType(oldProp);
+            const newType = schemaType(newProp);
+            if (oldType !== newType) {
+                changes.push({
+                    type: "PROPERTY_TYPE_CHANGED",
+                    schema: name,
+                    property,
+                    location: propertyLocation(name, property),
+                    from: oldType,
+                    to: newType,
+                    detail: `${name}.${property}: ${oldType} → ${newType}.`,
+                    breaking: true
+                });
+            }
+            if (!oldRequired.has(property) && newRequired.has(property)) {
+                changes.push({
+                    type: "PROPERTY_REQUIRED_CHANGED",
+                    schema: name,
+                    property,
+                    location: propertyLocation(name, property),
+                    from: "optional",
+                    to: "required",
+                    detail: `${name}.${property} changed from optional to required.`,
+                    breaking: true
+                });
+            }
+        }
+        const oldEnum = asStringArray(oldSchema.enum);
+        const newEnum = asStringArray(newSchema.enum);
+        for (const value of oldEnum) {
+            if (!newEnum.includes(value)) {
+                changes.push({
+                    type: "ENUM_VALUE_REMOVED",
+                    schema: name,
+                    location: `${schemaLocation(name)}.enum`,
+                    from: value,
+                    detail: `${name} enum value ${JSON.stringify(value)} was removed.`,
+                    breaking: true
+                });
+            }
+        }
+        for (const value of newEnum) {
+            if (!oldEnum.includes(value)) {
+                changes.push({
+                    type: "ENUM_VALUE_ADDED",
+                    schema: name,
+                    location: `${schemaLocation(name)}.enum`,
+                    value,
+                    detail: `${name} enum value ${JSON.stringify(value)} was added.`,
+                    breaking: false
+                });
+            }
+        }
+    }
+}
+export function compareContracts(oldDocument, newDocument) {
+    const changes = [];
+    const oldPaths = oldDocument.paths ?? {};
+    const newPaths = newDocument.paths ?? {};
+    const paths = new Set([...Object.keys(oldPaths), ...Object.keys(newPaths)]);
+    for (const path of paths) {
+        const oldPath = oldPaths[path];
+        const newPath = newPaths[path];
+        if (!oldPath) {
+            for (const method of METHODS) {
+                if (newPath?.[method]) {
+                    changes.push({
+                        type: "ENDPOINT_ADDED",
+                        path,
+                        method: method.toUpperCase(),
+                        location: operationLocation(path, method),
+                        detail: `${method.toUpperCase()} ${path} was added.`,
+                        breaking: false
+                    });
+                }
+            }
+            continue;
+        }
+        if (!newPath) {
+            for (const method of METHODS) {
+                if (oldPath?.[method]) {
+                    changes.push({
+                        type: "ENDPOINT_REMOVED",
+                        path,
+                        method: method.toUpperCase(),
+                        location: operationLocation(path, method),
+                        detail: `${method.toUpperCase()} ${path} was removed.`,
+                        breaking: true
+                    });
+                }
+            }
+            continue;
+        }
+        for (const method of METHODS) {
+            const oldOperation = asRecord(oldPath?.[method]);
+            const newOperation = asRecord(newPath?.[method]);
+            if (!oldOperation && newOperation) {
+                changes.push({
+                    type: "ENDPOINT_ADDED",
+                    path,
+                    method: method.toUpperCase(),
+                    location: operationLocation(path, method),
+                    detail: `${method.toUpperCase()} ${path} was added.`,
+                    breaking: false
+                });
+            }
+            else if (oldOperation && !newOperation) {
+                changes.push({
+                    type: "ENDPOINT_REMOVED",
+                    path,
+                    method: method.toUpperCase(),
+                    location: operationLocation(path, method),
+                    detail: `${method.toUpperCase()} ${path} was removed.`,
+                    breaking: true
+                });
+            }
+            else if (oldOperation && newOperation) {
+                compareOperationDetails(path, method, oldOperation, newOperation, changes);
+            }
+        }
+    }
+    const oldComponents = asRecord(oldDocument.components) ?? {};
+    const newComponents = asRecord(newDocument.components) ?? {};
+    const oldSchemas = (asRecord(oldComponents.schemas) ?? {});
+    const newSchemas = (asRecord(newComponents.schemas) ?? {});
+    compareSchemas(oldSchemas, newSchemas, changes);
+    const added = changes.filter(c => c.type.endsWith("_ADDED")).length;
+    const removed = changes.filter(c => c.type.endsWith("_REMOVED")).length;
+    const modified = changes.filter(c => c.type.endsWith("_CHANGED") || c.type === "REQUEST_BODY_CHANGED" || c.type === "RESPONSE_CHANGED").length;
+    const breaking = changes.filter(c => c.breaking).length;
+    return {
+        version: "1",
+        summary: { added, removed, modified, breaking },
+        changes
+    };
+}

package/dist/diff/reporter.d.ts

@@ -0,0 +1,2 @@
+import type { DiffResult } from "../types/diff.js";
+export declare function formatDiff(result: DiffResult): string;

package/dist/diff/reporter.js

@@ -0,0 +1,32 @@
+export function formatDiff(result) {
+    const lines = [
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "API CONTRACT DIFF",
+        "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+        "",
+        "Summary",
+        `  Added:       ${result.summary.added}`,
+        `  Removed:     ${result.summary.removed}`,
+        `  Modified:    ${result.summary.modified}`,
+        `  Breaking:    ${result.summary.breaking}`,
+        ""
+    ];
+    const breaking = result.changes.filter(c => c.breaking);
+    const nonBreaking = result.changes.filter(c => !c.breaking);
+    if (breaking.length) {
+        lines.push("BREAKING CHANGES", "──────────────────────────────────────", "");
+        for (const change of breaking) {
+            lines.push(`⚠ ${change.detail}`, "");
+        }
+    }
+    if (nonBreaking.length) {
+        lines.push("NON-BREAKING CHANGES", "──────────────────────────────────────", "");
+        for (const change of nonBreaking) {
+            lines.push(`+ ${change.detail}`, "");
+        }
+    }
+    if (!result.changes.length) {
+        lines.push("No contract changes detected.", "");
+    }
+    return lines.join("\n");
+}

package/dist/generator/api.d.ts

@@ -0,0 +1 @@
+export declare function generateApi(inputPath: string, outputPath: string, typesImport?: string): Promise<void>;