delimit-cli 2.1.1 → 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."
 
-        const template = `# Delimit API Governance Policy
-# https://github.com/delimit-ai/delimit
+  - 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}."
+
+  - 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`);
@@ -783,20 +897,66 @@ rules: []
     });
 
 // Lint command — diff + policy (primary command)
+// Supports zero-spec mode: `delimit lint` (no args) auto-extracts from FastAPI
 program
-    .command('lint <old_spec> <new_spec>')
+    .command('lint [old_spec] [new_spec]')
     .description('Lint API specs for breaking changes and policy violations')
     .option('-p, --policy <file>', 'Custom policy file')
     .option('--current-version <ver>', 'Current API version for semver bump')
     .option('-n, --name <name>', 'API name for context')
     .option('--json', 'Output raw JSON')
+    .option('-d, --dir <path>', 'Project directory for zero-spec mode', '.')
     .action(async (oldSpec, newSpec, options) => {
         try {
-            const result = apiEngine.lint(
-                path.resolve(oldSpec),
-                path.resolve(newSpec),
-                { policy: options.policy, version: options.currentVersion, name: options.name }
-            );
+            let result;
+
+            if (!oldSpec || !newSpec) {
+                // Zero-spec mode: extract from framework source
+                console.log(chalk.gray('No spec files provided — detecting framework...'));
+                const zeroResult = apiEngine.zeroSpec(path.resolve(options.dir));
+
+                if (!zeroResult.success) {
+                    console.error(chalk.red(`\n  ${zeroResult.error}\n`));
+                    if (zeroResult.error_type === 'no_framework') {
+                        console.log('  Usage: delimit lint <old_spec> <new_spec>');
+                        console.log('  Or run from a FastAPI project directory.\n');
+                    }
+                    process.exit(1);
+                    return;
+                }
+
+                console.log(chalk.green(`  ${zeroResult.message}`));
+                console.log(`  Extracted: ${zeroResult.paths_count} paths, ${zeroResult.schemas_count} schemas`);
+                console.log(`  Spec: ${zeroResult.spec_path}\n`);
+
+                // Check for baseline
+                const baselineDir = path.join(path.resolve(options.dir), '.delimit');
+                const baselinePath = path.join(baselineDir, 'baseline.yaml');
+
+                if (!fs.existsSync(baselinePath)) {
+                    // First run: save baseline
+                    fs.mkdirSync(baselineDir, { recursive: true });
+                    const yaml = require('js-yaml');
+                    fs.writeFileSync(baselinePath, yaml.dump(zeroResult.spec));
+                    console.log(chalk.green('  Saved baseline to .delimit/baseline.yaml'));
+                    console.log('  Run again after making changes to see the diff.\n');
+                    process.exit(0);
+                    return;
+                }
+
+                // Compare against baseline
+                result = apiEngine.lint(
+                    baselinePath,
+                    zeroResult.spec_path,
+                    { policy: options.policy, version: options.currentVersion, name: options.name }
+                );
+            } else {
+                result = apiEngine.lint(
+                    path.resolve(oldSpec),
+                    path.resolve(newSpec),
+                    { policy: options.policy, version: options.currentVersion, name: options.name }
+                );
+            }
 
             if (options.json) {
                 console.log(JSON.stringify(result, null, 2));

package/lib/api-engine.js

@@ -153,4 +153,42 @@ function semver(oldSpec, newSpec, currentVersion) {
     ].join('\n'));
 }
 
-module.exports = { lint, diff, explain, semver, GATEWAY_ROOT };
+/**
+ * delimit zero-spec — extract OpenAPI from framework source code
+ */
+function zeroSpec(projectDir, opts = {}) {
+    const args = [];
+    if (opts.pythonBin) args.push(`python_bin=${pyStr(opts.pythonBin)}`);
+
+    return runGateway([
+        'import json, sys',
+        'sys.path.insert(0, ".")',
+        'from core.zero_spec.detector import detect_framework, Framework',
+        'from core.zero_spec.fastapi_extractor import extract_fastapi_spec',
+        'from core.zero_spec.nestjs_extractor import extract_nestjs_spec',
+        'from core.zero_spec.express_extractor import extract_express_spec',
+        `info = detect_framework(${pyStr(projectDir)})`,
+        'r = {"framework": info.framework.value, "confidence": info.confidence, "message": info.message}',
+        'if info.framework == Framework.FASTAPI:',
+        `    ext = extract_fastapi_spec(info, ${pyStr(projectDir)}${opts.pythonBin ? `, python_bin=${pyStr(opts.pythonBin)}` : ''})`,
+        '    r.update(ext)',
+        '    if ext.get("success") and info.app_locations:',
+        '        r["app_file"] = info.app_locations[0].file',
+        'elif info.framework == Framework.NESTJS:',
+        `    ext = extract_nestjs_spec(info, ${pyStr(projectDir)})`,
+        '    r.update(ext)',
+        '    if ext.get("success") and info.app_locations:',
+        '        r["app_file"] = info.app_locations[0].file',
+        'elif info.framework == Framework.EXPRESS:',
+        `    ext = extract_express_spec(info, ${pyStr(projectDir)})`,
+        '    r.update(ext)',
+        '    if ext.get("success") and info.app_locations:',
+        '        r["app_file"] = info.app_locations[0].file',
+        'else:',
+        '    r["success"] = False',
+        '    r["error"] = "No supported API framework detected"',
+        'print(json.dumps(r, default=str))',
+    ].join('\n'));
+}
+
+module.exports = { lint, diff, explain, semver, zeroSpec, GATEWAY_ROOT };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "delimit-cli",
-  "version": "2.1.1",
-  "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"