contract-driven-delivery 2.1.3 → 2.2.1

package/docs/api-conformance.md

@@ -0,0 +1,145 @@
+# API Conformance: catching frontend/backend drift mechanically
+
+## Why this exists
+
+cdd-kit calls `contracts/api/api-contract.md` the single source of truth for the
+API. But the other validators only check that the contract *document* is well
+formed (`validate_api_semantic.py` validates the endpoint table's columns). They
+never look at code. So the frontend and backend can both drift away from the
+contract — the frontend can call `/api/v2/orders` while the backend serves
+`/api/orders` and the contract documents neither — and every gate stays green.
+
+In a workflow where **no human reviews the contract by hand**, prose review is
+worthless and the markdown is only worth what a machine can enforce against real
+code. `validate_api_conformance.py` is that machine check: it parses the actual
+backend routes and frontend call sites and diffs them against the contract.
+
+## What it checks
+
+| Check | Meaning | Default severity |
+|---|---|---|
+| `backendRouteNotInContract` | a route is declared in backend code but not in the contract | warning |
+| `contractEndpointNotImplemented` | a contract endpoint has no backend route in scanned source | warning |
+| `frontendCallNotInContract` | the frontend calls a path/method that is not in the contract | error |
+
+Paths are normalized so `/users/:id`, `/users/{id}`, and `/users/${id}` all
+compare equal. Methods are compared too; `fetch()` and Django/Spring-style
+declarations that don't expose a verb to the regex are treated as method-agnostic.
+
+It is **heuristic** (regex, stack-agnostic) by design — a generic kit cannot ship
+a parser for every framework. It recognizes:
+
+- **Backend**: Express/Koa/Fastify (`app/router.get('/x')`), NestJS
+  (`@Controller` prefix + `@Get(':id')`), Flask/FastAPI/Django, Spring
+  (`@GetMapping`, and `@RequestMapping(..., method=...)` with the method parsed),
+  Go (chi/gin/echo/mux + `HandleFunc`), and Laravel (`Route::get` and
+  `Route::match([...])`).
+- **Flask Blueprint / FastAPI APIRouter prefixes** are resolved across files: a
+  pre-pass maps each router variable to its prefix — from the constructor kwarg
+  (`Blueprint(..., url_prefix="/admin")`, `APIRouter(prefix="/admin")`) and/or the
+  registration call (`register_blueprint(bp, url_prefix=...)`,
+  `include_router(router, prefix=...)`) — and folds it into every route on that
+  router. The registration-site prefix wins over the constructor's.
+- **Frontend**: `fetch` (method read from the options object; defaults to GET),
+  `axios`/`ky`/`$http`/`client`/`http`/`api.*` verb calls, the
+  `axios({ url, method })` config-object form, and `useFetch`/`useSWR`/`useQuery`.
+
+Backend patterns are **gated by file extension** so a Python/Go/PHP pattern can
+never match a JS/TS file (and vice versa). Treat it as a high-signal net, not a
+proof.
+
+### Known heuristic limits
+
+- **Ruby/Rails is not supported.** Rails routing is a stateful `routes.rb draw`
+  DSL that a regex cannot parse honestly, so `.rb` is not in the default
+  `backendGlobsExt` and Rails routes are not claimed.
+- **Mounted Express routers** (`app.use('/api', router)` + `router.get('/users')`)
+  record only `/users`; the validator does not resolve the mount prefix across
+  files. (Flask Blueprint and FastAPI APIRouter prefixes *are* resolved — see
+  above — but the Express `app.use` mount form is not.) If you use mounted
+  routers, either declare the unprefixed paths in the contract, add the mount
+  prefix in the route literal, or set `contractEndpointNotImplemented` to `off`.
+- **Prefix resolution keys on the local variable name.** Constructor prefixes
+  (`Blueprint(url_prefix=...)`, `APIRouter(prefix=...)`) are scoped per file, so a
+  `router` reused across modules does not collide; registration prefixes
+  (`register_blueprint`/`include_router`) are matched across files, with Flask's
+  override and FastAPI's additive (`include_router` prefix + `APIRouter` prefix)
+  semantics each respected. What is **not** resolved: a router imported under an
+  alias (`from x import router as r`), or a name registered under conflicting
+  prefixes across files — the latter is detected and dropped (so the per-file
+  constructor prefix decides) rather than guessed.
+- **Registrations resolved by a shared bare receiver name can cross modules.**
+  Because a registration is keyed by the variable name (`router`, `bp`), not the
+  module it was imported from, the following are not resolved — they all need
+  import tracking the regex heuristic deliberately does not attempt:
+  - **Module-qualified registration**: `include_router(users.router,
+    prefix="/api")` (router referenced through an imported module) is not matched.
+  - **Same name, conflicting prefixes**: two modules each `include_router(router,
+    prefix=...)` under different prefixes — the ambiguous registration is dropped,
+    so those routes are left unresolved (a warning) rather than mis-attributed.
+  - **One registration leaking onto a same-named local router**: if `users.py`
+    exports `router` mounted under `/api`, while `admin.py` has its own file-local
+    `router = APIRouter(prefix="/admin")` mounted without a prefix, the `/api`
+    registration is applied to `admin.py`'s routes too (scanned as `/api/admin/…`
+    though FastAPI serves `/admin/…`). To avoid this, give routers distinct names
+    or set `backendRouteNotInContract`/`contractEndpointNotImplemented` to
+    `warning` (the default) so it does not fail CI.
+- **Dynamic routes** built from variables or registered via framework modules
+  (NestJS `RouterModule`, dynamic prefixes) are not detected.
+
+Because of these residual blind spots, `backendRouteNotInContract` **defaults to
+`warning`**: a route the scanner mislocates must not break CI on a contract that
+is actually correct. Raise it to `error` (or set `"strict": true`) once your
+project's routing shape is known to resolve cleanly.
+
+## Enabling it
+
+It is **off unless `.cdd/conformance.json` exists with `"enabled": true`**, so it
+never breaks repos that ship the kit. `cdd-kit init` scaffolds a disabled config;
+flip it on:
+
+```json
+{
+  "enabled": true,
+  "apiPrefixes": ["/api"],
+  "sourceRoots": ["src", "app"],
+  "ignorePaths": ["/health", "/metrics"],
+  "checks": {
+    "backendRouteNotInContract": "warning",
+    "contractEndpointNotImplemented": "warning",
+    "frontendCallNotInContract": "error"
+  },
+  "strict": false
+}
+```
+
+- `apiPrefixes` — only frontend calls under these prefixes are checked, so
+  static-asset and third-party URLs don't produce noise. Leave empty to check all.
+- `sourceRoots` — directories to scan. Empty means auto-detect common roots
+  (`src`, `app`, `server`, `frontend`, …) that exist.
+- `ignorePaths` — contract/code paths to skip; a trailing `*` matches a prefix.
+- `strict` — escalate every warning to an error.
+- Per-check severity can be set to `"error"`, `"warning"`, or `"off"`.
+
+## How it runs
+
+It is chained under contract validation, so both of these pick it up:
+
+```bash
+cdd-kit validate --contracts      # runs it alongside the markdown validators
+cdd-kit gate <change-id>          # gate runs the contract validators, so drift blocks the gate
+```
+
+`cdd-kit doctor` reports whether the net is armed (`enabled` / `present but
+disabled` / `not configured`) without failing — turning it on is a project policy
+decision, not a doctor error.
+
+## Tuning false positives
+
+Because it is regex-based, an internal helper that isn't really an HTTP route can
+occasionally match. Options, in order of preference:
+
+1. Add the genuine endpoint to the contract (usually the right fix).
+2. Add the path to `ignorePaths`.
+3. Narrow `sourceRoots` to where real routes/calls live.
+4. Lower a specific check to `"warning"` or `"off"`.

package/docs/openapi-export.md

@@ -0,0 +1,157 @@
+# OpenAPI export
+
+`cdd-kit openapi export` projects `contracts/api/api-contract.md` (the source of
+truth) into a minimal **OpenAPI 3.1** skeleton for tooling. The markdown contract
+stays authoritative; the OpenAPI document is a one-way, regenerable projection.
+
+See `docs/adr/0001-contract-to-openapi-export.md` and
+`docs/adr/0002-schema-carrying-contract-format.md` for the design rationale.
+
+## Usage
+
+```bash
+cdd-kit openapi export                          # JSON to stdout
+cdd-kit openapi export --yaml                    # YAML to stdout
+cdd-kit openapi export --out build/openapi.json  # write to a file
+cdd-kit openapi export --yaml --out openapi.yaml
+cdd-kit openapi export --contract path/to/api-contract.md
+cdd-kit openapi export --check --out build/openapi.json  # sync gate
+```
+
+## The sync gate: `--check`
+
+A regenerable artifact is only safe if it is actually regenerated. `--check`
+makes that mechanical instead of a habit:
+
+```bash
+cdd-kit openapi export --check --out build/openapi.json
+```
+
+It does **not** write. It compares the committed artifact at `--out` against what
+the contract produces right now and exits:
+
+- `0` - in sync.
+- `1` - the artifact is missing, or the contract changed but the export was not
+  regenerated. The command prints the exact `openapi export --out ...` command
+  to fix it.
+
+Wire it into CI or a pre-commit hook so a contract edit that forgets to
+regenerate the export, and therefore the typed client downstream, fails the
+build. `--check` honors `--yaml`, so check the same format you committed.
+
+## What it derives
+
+From the endpoint table (`| method | path | auth | request schema | response schema | errors | tests |`):
+
+| Contract column | OpenAPI output |
+|---|---|
+| `method` + `path` | operation under `paths`, with `:id`/`{id}` normalized to `{id}` |
+| path templates | `parameters` (`in: path`, `required: true`, `type: string`) |
+| `auth` | `security` (`bearerAuth`) for `required`/`admin`, optional+anonymous for `optional`, none for `none`/`public` |
+| `method` | success status: `201` for `POST`, else `200` |
+| `errors` | extra response entries for any explicit `4xx`/`5xx` codes listed |
+| `response schema` | if it names a schema in `## Schemas`, emitted as response JSON Schema; otherwise recorded as `x-cdd-response-contract` prose |
+| `request schema` | if it names a schema in `## Schemas`, emitted as request JSON Schema; otherwise `requestBody` is marked `x-cdd-unresolved: true` |
+
+The exporter does not fabricate field-level schemas. Request/response cells that
+do not resolve to a named schema remain prose. The unresolved markers are
+deliberate: emitting a fake schema would be a new drift source. Add a
+`## Schemas` section when a body shape should become machine-typed.
+
+## Schema-carrying contracts
+
+Add optional `### Name` subsections under `## Schemas`. Existing endpoint table
+cells like `CreateUser`, `User`, or `User[]` become references when a matching
+schema exists.
+
+```markdown
+## Endpoint Requirements
+| method | path | auth | request schema | response schema | errors | tests |
+|---|---|---|---|---|---|---|
+| POST | /api/users | admin | CreateUser | User | 400 | yes |
+
+## Schemas
+
+### CreateUser
+| field | type | required | format | notes |
+|---|---|---|---|---|
+| email | string | yes | email | login identity |
+| name | string | yes | | display name |
+| role | enum(admin, member) | no | | |
+
+### User
+| field | type | required | notes |
+|---|---|---|---|
+| id | string | yes | |
+| email | string | yes | |
+```
+
+Field-table types are intentionally small and closed:
+
+| Type cell | Output |
+|---|---|
+| `string`, `integer`, `number`, `boolean` | primitive JSON Schema |
+| `OtherSchema` | `$ref` to another named schema |
+| `OtherSchema[]` or `string[]` | array wrapper |
+| `enum(active, disabled)` | string enum |
+
+`required: yes` adds the field to JSON Schema `required`. `notes` becomes
+`description`. An optional `format` column is emitted as JSON Schema `format`
+and may be enforced by downstream tooling.
+
+For complex bodies, use a raw Tier B escape hatch:
+
+````markdown
+### Event
+```json-schema
+{
+  "type": "object",
+  "oneOf": [
+    { "required": ["createdAt"] },
+    { "required": ["deletedAt"] }
+  ]
+}
+```
+````
+
+The exporter fails instead of weakening types when a schema is ambiguous:
+duplicate schema names, a section that mixes a field table and `json-schema`
+block, invalid JSON, or an unknown field type all exit non-zero.
+
+## Wiring a typed client in a consumer repo
+
+The kit produces the OpenAPI seam; you generate the client with an existing,
+well-maintained generator in your own CI. When a `package.json` is present,
+`cdd-kit init` scaffolds this for you as two editable npm scripts:
+
+```jsonc
+"scripts": {
+  // regenerate the OpenAPI artifact + the typed client
+  "contract:client": "cdd-kit openapi export --out contracts/api/openapi.json && npx --yes openapi-typescript contracts/api/openapi.json -o src/api/types.ts",
+  // the sync gate - fails if the artifact drifted from the contract
+  "contract:client:check": "cdd-kit openapi export --check --out contracts/api/openapi.json"
+}
+```
+
+These are a starting point, not a hard dependency: the generator
+(`openapi-typescript`) and the output path are yours to change. The kit owns the
+generic contract-to-OpenAPI half (`openapi export` / `--check`); the
+stack-specific codegen stays in your repo, which is why init writes an editable
+script rather than hard-coding a tool. Run `npm run contract:client:check` in CI
+as the gate.
+
+Doing it by hand instead, for a TypeScript frontend:
+
+```bash
+# 1. Export the contract to OpenAPI (committed or generated in CI)
+cdd-kit openapi export --yaml --out openapi.yaml
+
+# 2. Generate types with openapi-typescript (or orval / openapi-generator)
+npx openapi-typescript openapi.yaml -o src/api/schema.d.ts
+```
+
+Now frontend calls typed against `schema.d.ts` make a divergent path, method, or
+schema-resolved body shape a compile error. Run both generated clients and
+`validate_api_conformance.py`: conformance stays the universal floor for code
+that cannot be regenerated, generated types are the stronger path where the
+stack allows it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.1.3",
+  "version": "2.2.1",
   "description": "Contract-driven delivery kit for AI coding agents with deterministic context indexes, manifest-backed read-scope governance, and orchestrated contracts-first delivery.",
   "keywords": [
     "contract-driven",