@arpixel/api-contract 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 api-contract contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,699 @@
+# api-contract
+
+> **Generate API clients. Compare contracts. Analyze frontend impact.**
+
+`api-contract` is a deterministic CLI for frontend developers who consume evolving OpenAPI specifications.
+
+It provides three capabilities that work together across the API lifecycle:
+
+```text
+┌─────────────────────────────────────────────────────────┐
+│                     api-contract                        │
+├──────────────────┬──────────────────┬───────────────────┤
+│     GENERATE     │     COMPARE      │      ANALYZE      │
+│                  │                  │                   │
+│ OpenAPI →        │ OpenAPI →        │ Contract changes  │
+│ TypeScript       │ structured diff  │ → frontend impact │
+│ API client       │                  │                   │
+└──────────────────┴──────────────────┴───────────────────┘
+```
+
+* **Generate** — Generate frontend-ready TypeScript API clients from OpenAPI.
+* **Compare** — Compare OpenAPI versions and identify structural and breaking changes.
+* **Analyze** — Use AI coding agents to trace contract changes into the frontend repository and identify actual consumers.
+
+The deterministic CLI provides the contract data. AI coding agents provide repository-aware impact analysis.
+
+**No LLM or API key is required by the CLI.**
+
+---
+
+# Why
+
+API contracts evolve continuously.
+
+When a backend team publishes a new OpenAPI specification, frontend teams typically need to answer three different questions:
+
+### 1. What do I need to integrate?
+
+Generate a TypeScript representation of the API:
+
+```text
+OpenAPI
+   ↓
+TypeScript API client
+```
+
+### 2. What changed?
+
+Compare the previous and current contract:
+
+```text
+OpenAPI v1
+     +
+OpenAPI v2
+     ↓
+Contract diff
+     ↓
+Added / Removed / Modified
+     ↓
+Breaking / Non-breaking
+```
+
+### 3. What does it mean for my frontend?
+
+Take those deterministic changes and trace them through the repository:
+
+```text
+Contract change
+      ↓
+API client / type
+      ↓
+Service
+      ↓
+Hook / Query / Mutation
+      ↓
+Component / Page
+      ↓
+Actual frontend impact
+```
+
+`api-contract` brings these three workflows together without making the CLI dependent on AI.
+
+---
+
+# Three Core Capabilities
+
+## 1. Generate
+
+Generate frontend-ready TypeScript from an OpenAPI specification:
+
+```bash
+npx api-contract generate openapi.yaml
+```
+
+The default output is:
+
+```text
+api-contract/generated/
+├── types.ts
+└── api.ts
+```
+
+The output directory is resolved relative to the current working directory.
+
+### Custom output
+
+```bash
+npx api-contract generate openapi.yaml --output src/api/generated
+```
+
+Produces:
+
+```text
+src/api/generated/
+├── types.ts
+└── api.ts
+```
+
+An explicitly provided `--output` directory takes precedence over the default.
+
+### Generated files
+
+#### `types.ts`
+
+Generated using `openapi-typescript`.
+
+It contains TypeScript representations of the OpenAPI contract, including schemas, parameters, responses, and enums.
+
+#### `api.ts`
+
+Contains a lightweight generated API-method contract based on OpenAPI `operationId`, parameters, and response schemas.
+
+For example:
+
+```ts
+export interface ApiMethods {
+  getDevice(id: string): Promise<Device>;
+}
+```
+
+---
+
+## 2. Compare
+
+Compare two OpenAPI specifications:
+
+```bash
+npx api-contract diff old.yaml new.yaml
+```
+
+The comparison identifies structural contract changes including:
+
+* endpoint additions and removals
+* parameter additions and removals
+* required/optional parameter changes
+* parameter type changes
+* request body changes
+* request body property changes
+* response changes
+* response property changes
+* schema additions and removals
+* property additions and removals
+* required/optional property changes
+* enum changes
+* type changes
+
+Changes are classified as **breaking** or **non-breaking** according to the supported compatibility rules.
+
+### Human-readable output
+
+```bash
+npx api-contract diff examples/old.yaml examples/new.yaml
+```
+
+Example:
+
+```text
+API Contract Changes
+
+Added:     4
+Removed:   1
+Modified:  1
+Breaking:  2
+
+BREAKING
+  DELETE /devices/{id} was removed.
+  Device.status changed from optional to required.
+
+NON-BREAKING
+  POST /devices was added.
+  Device.serialNumber was added.
+  DeviceStatus enum value "suspended" was added.
+```
+
+### Machine-readable output
+
+```bash
+npx api-contract diff examples/old.yaml examples/new.yaml --format json
+```
+
+The JSON output provides a stable V1 structure:
+
+```text
+version
+summary
+changes
+```
+
+Each change contains deterministic information such as:
+
+* change type
+* contract location
+* endpoint
+* HTTP method
+* schema
+* property
+* previous value
+* new value
+* breaking status
+* human-readable detail
+
+The JSON format is intentionally suitable for automation and AI-agent consumption.
+
+---
+
+## 3. Analyze
+
+Contract comparison tells you **what changed**.
+
+It does not tell you whether the frontend actually uses the changed contract.
+
+The AI-assisted impact workflow takes the deterministic diff and analyzes the frontend repository.
+
+```text
+api-contract diff
+        ↓
+Contract changes
+        ↓
+AI coding agent
+        ↓
+Frontend repository
+        ↓
+Search + dependency tracing
+        ↓
+Actual consumers
+        ↓
+Impact report
+```
+
+For example:
+
+```text
+DELETE /devices/{id}
+        ↓
+deleteDevice()
+        ↓
+useDeleteDevice()
+        ↓
+DeviceActions.tsx
+```
+
+The workflow can trace relationships such as:
+
+```text
+Endpoint
+   ↓
+API client
+   ↓
+Service
+   ↓
+Hook / Query / Mutation
+   ↓
+Component / Page
+```
+
+and:
+
+```text
+Schema
+   ↓
+Generated TypeScript
+   ↓
+Request / Response model
+   ↓
+Service / Hook
+   ↓
+Component / Page
+```
+
+The analysis distinguishes between:
+
+| Classification  | Meaning                                                    |
+| --------------- | ---------------------------------------------------------- |
+| `DIRECT`        | Application code directly consumes the changed contract    |
+| `INDIRECT`      | The change reaches application code through an abstraction |
+| `CONTRACT_ONLY` | Only generated/contract artifacts are related              |
+| `NONE_FOUND`    | No relevant frontend usage was found                       |
+
+These classifications describe the relationship between the contract and the frontend, not severity ratings.
+
+Generated API clients and TypeScript types are not treated as application consumers.
+
+---
+
+# The Complete Workflow
+
+The three capabilities can be used independently or together.
+
+```text
+                         OpenAPI
+                            │
+          ┌─────────────────┼─────────────────┐
+          │                 │                 │
+          ▼                 ▼                 ▼
+       GENERATE           COMPARE          ANALYZE
+          │                 │                 │
+          ▼                 ▼                 │
+   TypeScript client    What changed?        │
+   types.ts + api.ts    Breaking?            │
+                            │                 │
+                            ▼                 │
+                     Structured diff ─────────┘
+                                      │
+                                      ▼
+                                AI agent
+                                      │
+                                      ▼
+                            Frontend repository
+                                      │
+                                      ▼
+                               Impact report
+```
+
+A typical API evolution workflow becomes:
+
+```text
+1. Backend publishes OpenAPI
+             ↓
+2. Generate/update frontend API client
+             ↓
+3. Compare previous vs current contract
+             ↓
+4. Identify breaking changes
+             ↓
+5. Analyze frontend consumers
+             ↓
+6. Understand what actually needs attention
+```
+
+---
+
+# AI-Assisted Workflows
+
+AI is deliberately kept outside the deterministic CLI.
+
+The architecture is:
+
+```text
+api-contract
+    │
+    ├── generate
+    ├── diff
+    │
+    └── deterministic contract data
+                  │
+                  ▼
+             AI agent
+                  │
+                  ▼
+        repository-aware analysis
+```
+
+This means:
+
+* the CLI does not require an LLM
+* contract comparison remains deterministic
+* generated output remains reproducible
+* AI is used where repository context and reasoning are valuable
+
+The AI workflows can be used with supported coding-agent hosts such as VS Code/Copilot and other agent environments.
+
+---
+
+# VS Code / Copilot Integration
+
+The repository includes integration artifacts:
+
+```text
+integrations/vscode/
+├── api-contract-generate.prompt.md
+├── api-contract-generate.agent.md
+├── api-contract-impact.prompt.md
+└── api-contract-impact.agent.md
+```
+
+Install these integrations for your user account with:
+
+```bash
+npx api-contract init --host vscode
+```
+
+This installs the prompts under `~/.api-contract/prompts/` and the agents under
+`~/.copilot/agents/`. The command does not modify VS Code settings.
+
+### Prompt usage
+
+Choose one of these options for the prompts:
+
+1. **Repository-local** — Copy `~/.api-contract/prompts/` into
+   `<repository>/.github/prompts/` to make the prompts available to that repository.
+2. **Global** — Add `~/.api-contract/prompts` as a directory in VS Code's
+   `chat.promptFilesLocations` setting. Add the directory, not individual file paths.
+
+The agents installed under `~/.copilot/agents/` can be selected from the VS Code Chat agent experience.
+
+## API Contract Generate
+
+Allows an AI coding agent to invoke the deterministic generation workflow based on user input.
+
+For example:
+
+```text
+Generate TypeScript from openapi.yaml
+```
+
+The agent runs:
+
+```bash
+api-contract generate openapi.yaml
+```
+
+If the user specifies:
+
+```text
+Generate TypeScript from openapi.yaml and put it in src/api/generated.
+```
+
+the agent runs:
+
+```bash
+api-contract generate openapi.yaml --output src/api/generated
+```
+
+The agent does not manually reproduce the OpenAPI-to-TypeScript generation logic.
+
+## API Contract Impact
+
+Uses the deterministic `api-contract diff` output as the source of truth and then analyzes the frontend repository.
+
+```text
+api-contract diff
+       ↓
+contract changes
+       ↓
+repository analysis
+       ↓
+frontend consumers
+       ↓
+impact report
+```
+
+The analysis is read-only by default and does not modify source code unless explicitly requested.
+
+---
+
+# Architecture
+
+```text
+                         OpenAPI
+                            │
+                     OpenAPI parser
+                            │
+          ┌─────────────────┼─────────────────┐
+          │                 │                 │
+          ▼                 ▼                 ▼
+       GENERATE           COMPARE          ANALYZE*
+          │                 │                 │
+          ▼                 ▼                 │
+    TypeScript         Structured diff        │
+      client                 │               │
+          │                  │               │
+          │                  ▼               │
+          │             AI coding agent ◄────┘
+          │                  │
+          │                  ▼
+          │          Frontend repository
+          │                  │
+          │                  ▼
+          │            Impact analysis
+          │
+          ▼
+   types.ts + api.ts
+
+* Analyze is an AI-assisted workflow built on top of
+  the deterministic CLI output.
+```
+
+### Design principles
+
+**Deterministic core**
+
+OpenAPI parsing, validation, generation, and comparison are performed without an LLM.
+
+**AI at the reasoning layer**
+
+AI agents are used for repository-aware analysis where code relationships and application context matter.
+
+**Separation of concerns**
+
+```text
+api-contract
+    = generate + compare
+
+AI agent workflow
+    = analyze frontend impact
+```
+
+**Evidence over assumptions**
+
+Impact analysis should prefer concrete repository evidence over assumptions based solely on names or generated artifacts.
+
+---
+
+# Installation
+
+## Use with npx
+
+No global installation is required:
+
+```bash
+npx api-contract --help
+```
+
+Generate:
+
+```bash
+npx api-contract generate openapi.yaml
+```
+
+Compare:
+
+```bash
+npx api-contract diff old.yaml new.yaml
+```
+
+Install the optional VS Code/Copilot integration:
+
+```bash
+npx api-contract init --host vscode
+```
+
+## Requirements
+
+* Node.js 22.12+
+* npm
+
+The CLI bundles its OpenAPI parser and generator as npm dependencies.
+
+---
+
+# Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Run the CLI locally without linking:
+
+```bash
+npm run dev -- generate examples/old.yaml
+```
+
+```bash
+npm run dev -- diff examples/old.yaml examples/new.yaml
+```
+
+---
+
+# Project Structure
+
+```text
+api-contract/
+├── src/
+│   ├── cli.ts
+│   ├── commands/
+│   │   ├── generate.ts
+│   │   └── diff.ts
+│   ├── openapi/
+│   │   └── loader.ts
+│   ├── generator/
+│   │   ├── typescript.ts
+│   │   └── api.ts
+│   ├── diff/
+│   │   ├── comparator.ts
+│   │   └── reporter.ts
+│   └── types/
+│       └── diff.ts
+│
+├── tests/
+│   ├── diff/
+│   └── generate/
+│
+├── examples/
+│   ├── old.yaml
+│   └── new.yaml
+│
+└── integrations/
+    └── vscode/
+        ├── api-contract-generate.prompt.md
+        ├── api-contract-generate.agent.md
+        ├── api-contract-impact.prompt.md
+        └── api-contract-impact.agent.md
+```
+
+---
+
+# V1 Scope
+
+### Generate
+
+* OpenAPI parsing and validation
+* TypeScript type generation
+* Lightweight API-method generation
+
+### Compare
+
+* OpenAPI contract comparison
+* Structural change detection
+* Breaking/non-breaking classification
+* Human-readable diff
+* Machine-readable JSON diff
+
+### Analyze
+
+* AI-assisted frontend repository analysis
+* API consumer discovery
+* Dependency tracing
+* `DIRECT` / `INDIRECT` / `CONTRACT_ONLY` / `NONE_FOUND` classification
+* Evidence-based impact reporting
+
+---
+
+# V1 Non-Goals
+
+* Full HTTP client runtime generation
+* React hooks
+* TanStack Query hooks
+* runtime validation
+* mock generation
+* LLM/API-key management inside the CLI
+* direct repository modification by the CLI
+* host-specific agent installation
+
+The goal of V1 is to provide a small, deterministic, composable foundation for working with evolving API contracts and connecting contract changes to frontend code.
+
+---
+
+# Security
+
+OpenAPI `$ref` resolution can reference external files or URLs.
+
+Treat untrusted OpenAPI specifications carefully.
+
+Future versions may expose an explicit safe-resolution policy rather than blindly dereferencing arbitrary references.
+
+---
+
+# Roadmap
+
+Potential future capabilities include:
+
+* richer OpenAPI compatibility analysis
+* additional breaking-change rules
+* improved API client generation
+* additional AI-agent host integrations
+* repository initialization/install commands
+* broader frontend framework support
+
+The roadmap is intentionally exploratory. The current focus is keeping the three core workflows — **Generate, Compare, Analyze** — deterministic, composable, and useful.
+
+---
+
+# License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};