delimit-cli 2.2.0 → 2.3.0

package/README.md

@@ -1,6 +1,8 @@
 # delimit-cli
 
-**ESLint for API contracts** — detect breaking changes, enforce semver, and generate migration guides for OpenAPI specs.
+**Prevent breaking API changes before they reach production.**
+
+Deterministic diff engine + policy enforcement + semver classification for OpenAPI specs. The independent successor to Optic.
 
 [![npm](https://img.shields.io/npm/v/delimit-cli)](https://www.npmjs.com/package/delimit-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -11,46 +13,76 @@
 npm install -g delimit-cli
 ```
 
-This installs the `delimit` command globally.
-
-## Quick Start
+## Quick Start (Under 5 Minutes)
 
 ```bash
-# Initialize a policy file in your repo
-delimit init
+# 1. Initialize with a policy preset
+delimit init --preset default
 
-# Detect breaking changes between two specs
+# 2. Detect breaking changes
 delimit lint api/openapi-old.yaml api/openapi-new.yaml
 
-# See raw diff output
-delimit diff api/openapi-old.yaml api/openapi-new.yaml
-
-# Generate a human-readable explanation
-delimit explain api/openapi-old.yaml api/openapi-new.yaml
+# 3. Add the GitHub Action for automated PR checks
+#    Copy .github/workflows/api-governance.yml (see CI section below)
 ```
 
+## What It Catches
+
+Delimit deterministically detects 23 types of API changes, including 10 breaking patterns:
+
+- Endpoint or method removal
+- Required parameter addition
+- Response field removal
+- Type changes
+- Enum value removal
+- And more
+
+Every change is classified as `MAJOR`, `MINOR`, `PATCH`, or `NONE` per semver.
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `delimit init` | Create `.delimit/policies.yml` with default rules |
-| `delimit lint <old> <new>` | Diff + policy check with semver badge and violations |
+| `delimit init` | Create `.delimit/policies.yml` with a policy preset |
+| `delimit lint <old> <new>` | Diff + policy check — returns exit code 1 on violations |
 | `delimit diff <old> <new>` | Raw diff with `[BREAKING]`/`[safe]` tags |
 | `delimit explain <old> <new>` | Human-readable change explanation |
 
-### Options
+## Policy Presets
+
+Choose a preset that fits your team:
+
+```bash
+delimit init --preset strict    # Public APIs, payments — zero tolerance
+delimit init --preset default   # Most teams — balanced rules
+delimit init --preset relaxed   # Internal APIs, startups — warnings only
+```
+
+| Preset | Breaking changes | Type changes | Field removal |
+|--------|-----------------|--------------|---------------|
+| `strict` | Error (blocks) | Error (blocks) | Error (blocks) |
+| `default` | Error (blocks) | Warning | Error (blocks) |
+| `relaxed` | Warning | Warning | Info |
+
+Pass a preset directly to lint:
+
+```bash
+delimit lint --policy strict old.yaml new.yaml
+```
+
+## Options
 
 ```bash
-# Specify explainer template (default: developer)
+# Semver classification with version bump
+delimit lint old.yaml new.yaml --current-version 1.0.0
+
+# Explainer templates
 delimit explain old.yaml new.yaml -t migration
 delimit explain old.yaml new.yaml -t pr_comment
 delimit explain old.yaml new.yaml -t changelog
 
-# Include semver classification
-delimit lint old.yaml new.yaml --current-version 1.0.0
-
-# Use custom policy file
-delimit lint old.yaml new.yaml -p .delimit/policies.yml
+# JSON output for scripting
+delimit lint old.yaml new.yaml --json
 ```
 
 ### Explainer Templates
@@ -67,34 +99,56 @@ delimit lint old.yaml new.yaml -p .delimit/policies.yml
 
 ## CI/CD Integration
 
-For automated PR checks, use the GitHub Action:
+Add this workflow to `.github/workflows/api-governance.yml`:
 
 ```yaml
-- uses: delimit-ai/delimit-action@v1
-  with:
-    old_spec: base/api/openapi.yaml
-    new_spec: api/openapi.yaml
+name: API Governance
+on:
+  pull_request:
+    paths:
+      - 'path/to/openapi.yaml'  # adjust to your spec path
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  api-governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: _base
+      - uses: delimit-ai/delimit@v1
+        with:
+          old_spec: _base/path/to/openapi.yaml
+          new_spec: path/to/openapi.yaml
+          mode: advisory  # or 'enforce' to block PRs
 ```
 
+The action posts a PR comment with:
+- Semver badge (`MAJOR` / `MINOR` / `PATCH`)
+- Violation table with severity
+- Expandable migration guide for breaking changes
+
 See [Delimit API Governance](https://github.com/marketplace/actions/delimit-api-governance) on the GitHub Marketplace.
 
 ## Custom Policies
 
-Create `.delimit/policies.yml`:
+Create `.delimit/policies.yml` or start from a preset:
 
 ```yaml
+override_defaults: false
+
 rules:
-  - id: no_endpoint_removal
-    change_types: [endpoint_removed]
+  - id: protect_v1
+    name: Protect V1 API
+    change_types: [endpoint_removed, method_removed, field_removed]
     severity: error
     action: forbid
-    message: "Endpoints cannot be removed without deprecation"
-
-  - id: warn_type_change
-    change_types: [type_changed]
-    severity: warning
-    action: warn
-    message: "Type change may break clients"
+    conditions:
+      path_pattern: "^/v1/.*"
+    message: "V1 API is frozen. Make changes in V2."
 ```
 
 ## Supported Specs
@@ -105,7 +159,7 @@ rules:
 
 ## Links
 
-- [GitHub Action](https://github.com/marketplace/actions/delimit-api-governance) — CI/CD integration
+- [GitHub Action](https://github.com/marketplace/actions/delimit-api-governance) — Automated PR checks
 - [GitHub](https://github.com/delimit-ai/delimit) — Source code
 - [Issues](https://github.com/delimit-ai/delimit/issues) — Bug reports and feature requests
 

package/bin/delimit-cli.js

@@ -741,29 +741,72 @@ program
 
 const apiEngine = require('../lib/api-engine');
 
-// Init command — scaffold .delimit/ config
-program
-    .command('init')
-    .description('Initialize Delimit API governance in this project')
-    .action(async () => {
-        const configDir = path.join(process.cwd(), '.delimit');
-        const policyFile = path.join(configDir, 'policies.yml');
+// Policy preset templates
+const POLICY_PRESETS = {
+    strict: `# Delimit Policy Preset: strict
+# For public APIs, payment systems, and regulated environments.
+# Zero tolerance for breaking changes.
 
-        if (fs.existsSync(policyFile)) {
-            console.log(chalk.yellow('Already initialized — .delimit/policies.yml exists'));
-            return;
-        }
+override_defaults: true
 
-        fs.mkdirSync(configDir, { recursive: true });
+rules:
+  - id: no_endpoint_removal
+    name: Forbid Endpoint Removal
+    change_types: [endpoint_removed]
+    severity: error
+    action: forbid
+    message: "Endpoint {path} cannot be removed. Deprecate with Sunset header first."
+
+  - id: no_method_removal
+    name: Forbid Method Removal
+    change_types: [method_removed]
+    severity: error
+    action: forbid
+    message: "HTTP method removed from {path}. This breaks all clients."
+
+  - id: no_required_param_addition
+    name: Forbid Required Parameter Addition
+    change_types: [required_param_added]
+    severity: error
+    action: forbid
+    message: "Cannot add required parameter to {path}. Make it optional."
+
+  - id: no_field_removal
+    name: Forbid Response Field Removal
+    change_types: [field_removed]
+    severity: error
+    action: forbid
+    message: "Cannot remove field from {path}. Deprecate it first."
+
+  - id: no_type_change
+    name: Forbid Type Changes
+    change_types: [type_changed]
+    severity: error
+    action: forbid
+    message: "Type change at {path} breaks client deserialization."
+
+  - id: no_enum_removal
+    name: Forbid Enum Value Removal
+    change_types: [enum_value_removed]
+    severity: error
+    action: forbid
+    message: "Enum value removed at {path}."
 
-        const template = `# Delimit API Governance Policy
-# https://github.com/delimit-ai/delimit
+  - id: no_param_removal
+    name: Forbid Parameter Removal
+    change_types: [param_removed]
+    severity: error
+    action: forbid
+    message: "Parameter removed from {path}."
+`,
+    default: `# Delimit Policy Preset: default
+# Balanced rules for most teams. Blocks destructive changes, warns on risky ones.
+# Uses built-in defaults — customize by adding rules below.
 
-# Override built-in rules (default: false)
 override_defaults: false
 
 rules: []
-# Example:
+# Add custom rules here. Example:
 #   - id: protect_v1
 #     name: Protect V1 API
 #     change_types: [endpoint_removed, method_removed, field_removed]
@@ -772,9 +815,80 @@ rules: []
 #     conditions:
 #       path_pattern: "^/v1/.*"
 #     message: "V1 API is frozen. Make changes in V2."
-`;
-        fs.writeFileSync(policyFile, template);
-        console.log(chalk.green('Created .delimit/policies.yml'));
+`,
+    relaxed: `# Delimit Policy Preset: relaxed
+# For internal APIs, early-stage startups, and rapid iteration.
+# Only warns — never blocks CI.
+
+override_defaults: true
+
+rules:
+  - id: warn_endpoint_removal
+    name: Warn on Endpoint Removal
+    change_types: [endpoint_removed]
+    severity: warning
+    action: warn
+    message: "Endpoint {path} was removed. Check downstream consumers."
+
+  - id: warn_method_removal
+    name: Warn on Method Removal
+    change_types: [method_removed]
+    severity: warning
+    action: warn
+    message: "HTTP method removed from {path}."
+
+  - id: warn_required_param
+    name: Warn on Required Parameter Addition
+    change_types: [required_param_added]
+    severity: warning
+    action: warn
+    message: "New required parameter at {path}."
+
+  - id: warn_type_change
+    name: Warn on Type Changes
+    change_types: [type_changed]
+    severity: warning
+    action: warn
+    message: "Type changed at {path}."
+
+  - id: allow_field_removal
+    name: Allow Field Removal
+    change_types: [field_removed]
+    severity: info
+    action: allow
+    message: "Field removed from {path}."
+`,
+};
+
+// Init command — scaffold .delimit/ config
+program
+    .command('init')
+    .description('Initialize Delimit API governance in this project')
+    .option('--preset <name>', 'Policy preset: strict, default, or relaxed', 'default')
+    .action(async (options) => {
+        const configDir = path.join(process.cwd(), '.delimit');
+        const policyFile = path.join(configDir, 'policies.yml');
+
+        if (fs.existsSync(policyFile)) {
+            console.log(chalk.yellow('Already initialized — .delimit/policies.yml exists'));
+            return;
+        }
+
+        const preset = options.preset.toLowerCase();
+        if (!POLICY_PRESETS[preset]) {
+            console.log(chalk.red(`Unknown preset "${preset}". Choose: strict, default, or relaxed`));
+            return;
+        }
+
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(policyFile, POLICY_PRESETS[preset]);
+        console.log(chalk.green(`Created .delimit/policies.yml (preset: ${preset})`));
+        console.log('');
+        console.log(`  ${chalk.bold('strict')}  — zero tolerance, all breaking changes are errors`);
+        console.log(`  ${chalk.bold('default')} — balanced, blocks destructive changes, warns on risky`);
+        console.log(`  ${chalk.bold('relaxed')} — warnings only, never blocks CI`);
+        console.log('');
+        console.log(`Switch preset: ${chalk.bold('delimit init --preset strict')}`);
         console.log('');
         console.log('Next steps:');
         console.log(`  ${chalk.bold('delimit lint')} old.yaml new.yaml   — check for breaking changes`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "delimit-cli",
-  "version": "2.2.0",
-  "description": "ESLint for API contracts — detect breaking changes, enforce semver, and generate migration guides for OpenAPI specs",
+  "version": "2.3.0",
+  "description": "Prevent breaking API changes before they reach production. Deterministic diff engine + policy enforcement + semver classification.",
   "main": "index.js",
   "bin": {
     "delimit": "./bin/delimit-cli.js"