micro-contracts 0.18.18 → 0.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +120 -5
- package/cli-contract.yaml +29 -17
- package/dist/agents/context-builder.d.ts.map +1 -1
- package/dist/agents/context-builder.js +3 -3
- package/dist/agents/context-builder.js.map +1 -1
- package/dist/cli/templates.d.ts +2 -1
- package/dist/cli/templates.d.ts.map +1 -1
- package/dist/cli/templates.js +173 -80
- package/dist/cli/templates.js.map +1 -1
- package/dist/cli.js +85 -54
- package/dist/cli.js.map +1 -1
- package/dist/generated/contract.d.ts.map +1 -1
- package/dist/generated/contract.js +2 -2
- package/dist/generated/contract.js.map +1 -1
- package/dist/generated/dsl/dsl-data.js +1 -1
- package/dist/generated/dsl/dsl-data.js.map +1 -1
- package/dist/generated/policy-runtime.d.ts +19 -5
- package/dist/generated/policy-runtime.d.ts.map +1 -1
- package/dist/generated/policy-runtime.js +65 -40
- package/dist/generated/policy-runtime.js.map +1 -1
- package/dist/generated/policy.d.ts +0 -4
- package/dist/generated/policy.d.ts.map +1 -1
- package/dist/generated/policy.js +6 -28
- package/dist/generated/policy.js.map +1 -1
- package/dist/generated/program.d.ts.map +1 -1
- package/dist/generated/program.js +14 -8
- package/dist/generated/program.js.map +1 -1
- package/dist/generator/index.d.ts +15 -5
- package/dist/generator/index.d.ts.map +1 -1
- package/dist/generator/index.js +71 -33
- package/dist/generator/index.js.map +1 -1
- package/dist/generator/inputHash.d.ts.map +1 -1
- package/dist/generator/inputHash.js +3 -57
- package/dist/generator/inputHash.js.map +1 -1
- package/dist/generator/linter.d.ts.map +1 -1
- package/dist/generator/linter.js +23 -25
- package/dist/generator/linter.js.map +1 -1
- package/dist/generator/overlayProcessor.d.ts +15 -11
- package/dist/generator/overlayProcessor.d.ts.map +1 -1
- package/dist/generator/overlayProcessor.js +63 -124
- package/dist/generator/overlayProcessor.js.map +1 -1
- package/dist/generator/schemaGenerator.d.ts.map +1 -1
- package/dist/generator/schemaGenerator.js +124 -140
- package/dist/generator/schemaGenerator.js.map +1 -1
- package/dist/generator/schemaGenerator.test.js +109 -0
- package/dist/generator/schemaGenerator.test.js.map +1 -1
- package/dist/generator/serviceGenerator.d.ts.map +1 -1
- package/dist/generator/serviceGenerator.js +18 -70
- package/dist/generator/serviceGenerator.js.map +1 -1
- package/dist/generator/specLoader.d.ts +33 -0
- package/dist/generator/specLoader.d.ts.map +1 -0
- package/dist/generator/specLoader.js +175 -0
- package/dist/generator/specLoader.js.map +1 -0
- package/dist/generator/templateProcessor.d.ts +35 -3
- package/dist/generator/templateProcessor.d.ts.map +1 -1
- package/dist/generator/templateProcessor.js +84 -77
- package/dist/generator/templateProcessor.js.map +1 -1
- package/dist/generator/typeGenerator.d.ts +42 -4
- package/dist/generator/typeGenerator.d.ts.map +1 -1
- package/dist/generator/typeGenerator.js +83 -72
- package/dist/generator/typeGenerator.js.map +1 -1
- package/dist/generator/typeGenerator.test.js +16 -0
- package/dist/generator/typeGenerator.test.js.map +1 -1
- package/dist/guardrails/allowlist.d.ts.map +1 -1
- package/dist/guardrails/allowlist.js +2 -1
- package/dist/guardrails/allowlist.js.map +1 -1
- package/dist/guardrails/config.js +3 -3
- package/dist/guardrails/config.js.map +1 -1
- package/dist/guardrails/drift.d.ts +5 -2
- package/dist/guardrails/drift.d.ts.map +1 -1
- package/dist/guardrails/drift.js +20 -15
- package/dist/guardrails/drift.js.map +1 -1
- package/dist/guardrails/index.d.ts +2 -2
- package/dist/guardrails/index.d.ts.map +1 -1
- package/dist/guardrails/index.js +1 -1
- package/dist/guardrails/index.js.map +1 -1
- package/dist/guardrails/lint.d.ts.map +1 -1
- package/dist/guardrails/lint.js +5 -6
- package/dist/guardrails/lint.js.map +1 -1
- package/dist/guardrails/manifest.d.ts +52 -8
- package/dist/guardrails/manifest.d.ts.map +1 -1
- package/dist/guardrails/manifest.js +157 -34
- package/dist/guardrails/manifest.js.map +1 -1
- package/dist/guardrails/types.d.ts +3 -1
- package/dist/guardrails/types.d.ts.map +1 -1
- package/dist/micro-contracts.bundle.mjs +640 -526
- package/dist/micro-contracts.bundle.mjs.map +4 -4
- package/dist/types.d.ts +135 -12
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +175 -14
- package/dist/types.js.map +1 -1
- package/docs/cli-reference.md +14 -14
- package/docs/development-guardrails.md +45 -31
- package/docs/guardrails-concept.svg +2 -2
- package/docs/overlays-deep-dive.md +14 -9
- package/package.json +3 -3
package/docs/cli-reference.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Contract-first OpenAPI toolchain for TypeScript Web/API systems. Generates contract packages, server routes, and frontend clients from OpenAPI specifications with enforceable guardrails.
|
|
4
4
|
|
|
5
|
-
**Version:** 0.
|
|
5
|
+
**Version:** 0.20.0
|
|
6
6
|
|
|
7
7
|
## Table of Contents
|
|
8
8
|
|
|
@@ -38,7 +38,7 @@ Contract-first OpenAPI toolchain for TypeScript.
|
|
|
38
38
|
|
|
39
39
|
Generate code from OpenAPI specifications.
|
|
40
40
|
|
|
41
|
-
Loads the multi-module config,
|
|
41
|
+
Loads the multi-module config, lints each spec with the rules of the lint command (unless skipped), applies overlays, and generates contract packages, server routes, frontend clients, and documentation from OpenAPI specs. Supports input-hash caching to skip unnecessary regeneration.
|
|
42
42
|
|
|
43
43
|
**Usage:**
|
|
44
44
|
|
|
@@ -68,11 +68,11 @@ micro-contracts generate --force
|
|
|
68
68
|
| `--contracts-only` | | No | `false` | Generate contract packages only. |
|
|
69
69
|
| `--server-only` | | No | `false` | Generate the built-in server section only. Not valid with an outputs configuration — select outputs with --output instead. |
|
|
70
70
|
| `--frontend-only` | | No | `false` | Generate the built-in frontend section only. Not valid with an outputs configuration — select outputs with --output instead. |
|
|
71
|
-
| `--skip-lint` | | No | `false` | Skip
|
|
72
|
-
| `--manifest` | | No | `true` | Generate manifest after generation. Enabled by default when micro-contracts.guardrails.yaml has a generated section. Use --no-manifest to disable. |
|
|
73
|
-
| `--manifest-dir` | | No |
|
|
71
|
+
| `--skip-lint` | | No | `false` | Skip linting (the rules of the lint command) before generation. |
|
|
72
|
+
| `--manifest`, `--no-manifest` | | No | `true` | Generate manifest after generation. Enabled by default when micro-contracts.guardrails.yaml has a generated section. Use --no-manifest to disable. |
|
|
73
|
+
| `--manifest-dir` | | No | | Directory for manifest output. Defaults to the deepest directory holding every location the config generates to (contract, published contract and outputs), so that the manifest can record each output. |
|
|
74
74
|
| `--force` | | No | `false` | Bypass input hash cache and always regenerate. |
|
|
75
|
-
| `--cache` | | No | `true` | Enable input hash caching. Enabled by default. Use --no-cache to disable both reading and writing cache. |
|
|
75
|
+
| `--cache`, `--no-cache` | | No | `true` | Enable input hash caching. Enabled by default. Use --no-cache to disable both reading and writing cache. |
|
|
76
76
|
|
|
77
77
|
#### Exit Codes
|
|
78
78
|
|
|
@@ -108,7 +108,7 @@ x-agent:
|
|
|
108
108
|
|
|
109
109
|
Lint OpenAPI specification.
|
|
110
110
|
|
|
111
|
-
Validates an OpenAPI specification
|
|
111
|
+
Validates an OpenAPI specification against micro-contracts' own rules: the x-micro-contracts-* extensions every operation needs, screen spec consistency, and what a published endpoint may reach (x-private, x-micro-contracts-non-exportable).
|
|
112
112
|
|
|
113
113
|
**Usage:**
|
|
114
114
|
|
|
@@ -158,7 +158,7 @@ x-agent:
|
|
|
158
158
|
|
|
159
159
|
Initialize a new module structure with starter templates.
|
|
160
160
|
|
|
161
|
-
Creates the directory structure, starter Handlebars templates, shared schemas,
|
|
161
|
+
Creates the directory structure, starter Handlebars templates, shared schemas, Redocly lint rules, and optional config file for a new module. Can also process an existing OpenAPI spec to auto-add x-micro-contracts extensions.
|
|
162
162
|
|
|
163
163
|
**Usage:**
|
|
164
164
|
|
|
@@ -257,7 +257,7 @@ micro-contracts check --list-gates
|
|
|
257
257
|
| `--verbose` | -v | No | `false` | Enable verbose output. |
|
|
258
258
|
| `--fix` | | No | `false` | Auto-fix issues where possible. |
|
|
259
259
|
| `--guardrails` | -g | No | | Path to micro-contracts.guardrails.yaml. |
|
|
260
|
-
| `--generated-dir` | -d | No |
|
|
260
|
+
| `--generated-dir` | -d | No | | Directory holding the manifest of generated files. Defaults to the directory generate writes the manifest to: the deepest directory holding every location the config generates to. |
|
|
261
261
|
| `--changed-files` | | No | | Path to file containing list of changed files (for CI). |
|
|
262
262
|
| `--list` | | No | `false` | List available checks and exit. |
|
|
263
263
|
| `--list-gates` | | No | `false` | List available gates and exit. |
|
|
@@ -319,14 +319,14 @@ micro-contracts pipeline --contracts-only --skip-lint
|
|
|
319
319
|
| `--skip` | | No | | Skip specific checks (comma-separated). |
|
|
320
320
|
| `--continue-on-error` | | No | `false` | Continue running even if a step fails. |
|
|
321
321
|
| `--guardrails` | -g | No | | Path to micro-contracts.guardrails.yaml. |
|
|
322
|
-
| `--generated-dir` | -d | No |
|
|
323
|
-
| `--manifest` | | No | `true` | Generate manifest after generation. Enabled by default. Use --no-manifest to disable. |
|
|
324
|
-
| `--skip-lint` | | No | `false` | Skip
|
|
322
|
+
| `--generated-dir` | -d | No | | Directory holding the manifest of generated files. Defaults to the directory generate writes the manifest to: the deepest directory holding every location the config generates to. |
|
|
323
|
+
| `--manifest`, `--no-manifest` | | No | `true` | Generate manifest after generation. Enabled by default. Use --no-manifest to disable. |
|
|
324
|
+
| `--skip-lint` | | No | `false` | Skip linting (the rules of the lint command) before generation. |
|
|
325
325
|
| `--contracts-only` | | No | `false` | Generate contract packages only. |
|
|
326
326
|
| `--server-only` | | No | `false` | Generate the built-in server section only. Not valid with an outputs configuration — select outputs with --output instead. |
|
|
327
327
|
| `--frontend-only` | | No | `false` | Generate the built-in frontend section only. Not valid with an outputs configuration — select outputs with --output instead. |
|
|
328
328
|
| `--force` | | No | `false` | Bypass input hash cache and always regenerate. |
|
|
329
|
-
| `--cache` | | No | `true` | Enable input hash caching. Enabled by default. Use --no-cache to disable both reading and writing cache. |
|
|
329
|
+
| `--cache`, `--no-cache` | | No | `true` | Enable input hash caching. Enabled by default. Use --no-cache to disable both reading and writing cache. |
|
|
330
330
|
|
|
331
331
|
#### Exit Codes
|
|
332
332
|
|
|
@@ -535,7 +535,7 @@ micro-contracts manifest -o custom-manifest.json
|
|
|
535
535
|
|
|
536
536
|
| Option | Aliases | Required | Default | Description |
|
|
537
537
|
|---|---|---|---|---|
|
|
538
|
-
| `--dir` | -d | No |
|
|
538
|
+
| `--dir` | -d | No | | Directory to scan. Defaults to the directory generate writes the manifest to: the deepest directory holding every location the config generates to. |
|
|
539
539
|
| `--verify` | | No | `false` | Verify existing manifest instead of generating. |
|
|
540
540
|
| `--output` | -o | No | | Output manifest path. Defaults to {dir}/.generated-manifest.json. |
|
|
541
541
|
|
|
@@ -34,7 +34,7 @@ The following diagram illustrates the overall architecture of the guardrails sys
|
|
|
34
34
|
|------|------|-------|------------------|
|
|
35
35
|
| **1** | Change Allowlist | repo-wide | Editing protected/generated areas directly |
|
|
36
36
|
| **2** | OpenAPI Spec Validation | `spec/**` | Invalid specs, bad extensions, breaking changes |
|
|
37
|
-
| **3** | Generated Artifact Integrity | `packages/**`, `*.generated.*` | Hand-editing generated code, drift, tampering |
|
|
37
|
+
| **3** | Generated Artifact Integrity | files matching `generated:` (`packages/**`, `*.generated.*`) | Hand-editing generated code, drift, tampering |
|
|
38
38
|
| **4** | Code Quality | `server/**`, `frontend/**` | Type errors, lint issues, failing tests |
|
|
39
39
|
| **5** | Doc & Architectural Consistency | `docs/**`, all code | Doc/code mismatch, broken references, architecture drift |
|
|
40
40
|
|
|
@@ -61,7 +61,7 @@ Options:
|
|
|
61
61
|
-v, --verbose Enable verbose output (groups by gate)
|
|
62
62
|
--fix Auto-fix issues where possible
|
|
63
63
|
-g, --guardrails <path> Path to micro-contracts.guardrails.yaml
|
|
64
|
-
-d, --generated-dir <path>
|
|
64
|
+
-d, --generated-dir <path> Directory holding the manifest (default: the one generate writes it to)
|
|
65
65
|
--changed-files <path> Path to file containing list of changed files (for CI)
|
|
66
66
|
--list List available checks with gate assignments
|
|
67
67
|
--list-gates List available gates
|
|
@@ -102,7 +102,7 @@ Options:
|
|
|
102
102
|
--continue-on-error Continue running even if a step fails
|
|
103
103
|
-g, --guardrails <path> Path to micro-contracts.guardrails.yaml
|
|
104
104
|
-c, --config <path> Path to config file (micro-contracts.config.yaml)
|
|
105
|
-
-d, --generated-dir <path>
|
|
105
|
+
-d, --generated-dir <path> Directory holding the manifest (default: the one generate writes it to)
|
|
106
106
|
--no-manifest Skip manifest generation
|
|
107
107
|
--skip-lint Skip linting before generation
|
|
108
108
|
--contracts-only Generate contract packages only
|
|
@@ -159,7 +159,7 @@ Files are categorized into three groups:
|
|
|
159
159
|
| Category | Examples | Who can edit |
|
|
160
160
|
|----------|----------|--------------|
|
|
161
161
|
| `allowed` | `spec/**/*.yaml`, `server/src/**/services/**` | Anyone (AI or human) |
|
|
162
|
-
| `protected` | `.github/**`, `spec/
|
|
162
|
+
| `protected` | `.github/**`, `spec/redocly.yaml`, `server/src/_shared/overlays/**` | Anyone, once a maintainer approves the pull request (see below) |
|
|
163
163
|
| `generated` | `packages/**`, `*.generated.*` | Only via `generate` command |
|
|
164
164
|
|
|
165
165
|
Patterns are evaluated in order and the last match wins, so a negation (`!pattern`)
|
|
@@ -167,7 +167,7 @@ must come after the pattern it narrows.
|
|
|
167
167
|
|
|
168
168
|
Protected files include:
|
|
169
169
|
- CI/workflow definitions (`.github/**`) — guardrail bypass prevention
|
|
170
|
-
-
|
|
170
|
+
- Lint rules (`spec/redocly.yaml`, and any rules file or plugin it loads) — security rule tampering
|
|
171
171
|
- Shared overlay implementations (`server/src/_shared/overlays/**`) — security logic
|
|
172
172
|
- The guardrails config itself, under every name it is loaded as
|
|
173
173
|
(`micro-contracts.guardrails.yaml`/`.yml`, and the legacy `guardrails.yaml`/`.yml`)
|
|
@@ -205,13 +205,12 @@ Validates OpenAPI specs before generation.
|
|
|
205
205
|
|
|
206
206
|
| Check | Type | Description | Local Command | CI Job |
|
|
207
207
|
|-------|------|-------------|---------------|--------|
|
|
208
|
-
| Spec lint | custom | OpenAPI schema + micro-contracts extensions (
|
|
208
|
+
| Spec lint | custom | OpenAPI schema + micro-contracts extensions (Redocly) | `micro-contracts check --only spec-lint` | `spec-lint` |
|
|
209
209
|
| Breaking changes | custom | API compatibility check (oasdiff) | `micro-contracts check --only spec-breaking` | `spec-breaking` |
|
|
210
210
|
|
|
211
|
-
**Spec lint** — Validates via
|
|
211
|
+
**Spec lint** — Validates via the Redocly lint config (`spec/redocly.yaml`):
|
|
212
212
|
- OpenAPI 3.x structure (required fields, JSON Schema, `$ref` resolution)
|
|
213
|
-
- micro-contracts extensions (`x-micro-contracts-service`, `x-micro-contracts-method`)
|
|
214
|
-
- Security extensions (`x-auth`, `x-authz`) if required
|
|
213
|
+
- micro-contracts extensions (`x-micro-contracts-service`, `x-micro-contracts-method`, no `x-service`/`x-method`/`x-public`/`x-private`)
|
|
215
214
|
|
|
216
215
|
**Breaking changes** — Detects backward-incompatible changes:
|
|
217
216
|
- Removed endpoints or parameters
|
|
@@ -226,7 +225,7 @@ Transforms `spec/**` → `packages/**`.
|
|
|
226
225
|
|---------|-------------|
|
|
227
226
|
| `micro-contracts generate` | Generate contracts from OpenAPI specs |
|
|
228
227
|
|
|
229
|
-
> **Note**: When `micro-contracts.guardrails.yaml` has a `generated:` section defined, `generate` automatically creates/updates
|
|
228
|
+
> **Note**: When `micro-contracts.guardrails.yaml` has a `generated:` section defined, `generate` automatically creates/updates `.generated-manifest.json` in the deepest directory holding every location the config generates to (the project root when outputs sit both in `packages/` and next to the server code). `pipeline` and `check` read it there. Use `--no-manifest` to skip this behavior.
|
|
230
229
|
|
|
231
230
|
### Gate 3: Generated Artifact Integrity
|
|
232
231
|
|
|
@@ -236,17 +235,18 @@ Ensures generated code matches spec and hasn't been tampered.
|
|
|
236
235
|
|
|
237
236
|
| Check | Type | Description | Local Command | CI Job |
|
|
238
237
|
|-------|------|-------------|---------------|--------|
|
|
239
|
-
| Drift | built-in |
|
|
238
|
+
| Drift | built-in | Generated files must match the commit (staged, unstaged and untracked all count) | `micro-contracts check --only drift` | `drift` |
|
|
240
239
|
| Manifest | built-in | SHA-256 hash verification | `micro-contracts check --only manifest` | `manifest` |
|
|
241
240
|
| Package typecheck | custom | Generated packages compile (`tsc`) | `micro-contracts check --only package-typecheck` | `package-typecheck` |
|
|
242
|
-
| Project rules | custom | Project-specific
|
|
241
|
+
| Project rules | custom | Project-specific lint rules (Redocly) on **generated** spec | `micro-contracts check --only spec-project` | `spec-project` |
|
|
243
242
|
| Published breaking | custom | Breaking changes vs **published** contract (oasdiff) | `micro-contracts check --only spec-breaking-published` | `spec-breaking-published` |
|
|
244
243
|
|
|
245
244
|
> **Why spec checks in Gate 3?** `spec-project` and `spec-breaking-published` validate the **generated/bundled** spec output, not the source. They run after generation to verify the published contract.
|
|
246
245
|
|
|
247
|
-
**Drift check** — After running `generate`,
|
|
246
|
+
**Drift check** — After running `generate`, the generated files (those the `generated:`
|
|
247
|
+
patterns match, and the manifest) in the manifest's directory must match committed state:
|
|
248
248
|
```bash
|
|
249
|
-
git diff --
|
|
249
|
+
git diff --name-only HEAD -- <dir> && git ls-files --others --exclude-standard <dir>
|
|
250
250
|
```
|
|
251
251
|
Comparing against `HEAD` rather than the index matters: a pre-commit run stages
|
|
252
252
|
its changes first, and comparing the worktree to the index would report a
|
|
@@ -256,8 +256,10 @@ A configured generated directory that does not exist fails both checks: nothing
|
|
|
256
256
|
inspect is not the same as nothing wrong. A run in which every check skipped
|
|
257
257
|
reports `No checks ran` rather than success.
|
|
258
258
|
|
|
259
|
-
**Manifest verification** —
|
|
260
|
-
- SHA-256 hashes of all generated files
|
|
259
|
+
**Manifest verification** — `.generated-manifest.json` stores:
|
|
260
|
+
- SHA-256 hashes of all generated files: the files in the directory that the
|
|
261
|
+
`generated:` patterns match, read relative to the guardrails config. A
|
|
262
|
+
hand-written package beside them is neither recorded nor reported.
|
|
261
263
|
- Generator version used
|
|
262
264
|
- Source spec file references
|
|
263
265
|
|
|
@@ -321,6 +323,11 @@ allowed:
|
|
|
321
323
|
- server/src/*/overlays/**/*.ts
|
|
322
324
|
- "!server/src/_shared/overlays/**"
|
|
323
325
|
|
|
326
|
+
# Frontend code (human-written; the generated clients are under generated:)
|
|
327
|
+
- frontend/src/**/*.ts
|
|
328
|
+
- frontend/src/**/*.tsx
|
|
329
|
+
- "!frontend/src/**/*.generated.ts"
|
|
330
|
+
|
|
324
331
|
# Configuration
|
|
325
332
|
# The example is three npm projects (this one, server/, frontend/) and CI installs all
|
|
326
333
|
# three. A dependency change moves a manifest and its lock together, so allowing one
|
|
@@ -336,9 +343,11 @@ allowed:
|
|
|
336
343
|
|
|
337
344
|
# Files that require special approval
|
|
338
345
|
protected:
|
|
339
|
-
#
|
|
340
|
-
|
|
341
|
-
- spec
|
|
346
|
+
# Lint rules: spec/redocly.yaml, the redocly.yaml of every spec/<dir>/ that
|
|
347
|
+
# extends it, and the plugin they load
|
|
348
|
+
- spec/*.yaml
|
|
349
|
+
- spec/*/*.yaml
|
|
350
|
+
- spec/redocly-plugin.js
|
|
342
351
|
|
|
343
352
|
# Shared overlay definitions
|
|
344
353
|
- spec/_shared/overlays/**
|
|
@@ -368,15 +377,20 @@ generated:
|
|
|
368
377
|
# Based on guardrails-concept.svg:
|
|
369
378
|
#
|
|
370
379
|
# Gate 1: Change Allowlist
|
|
371
|
-
# - allowlist (built-in):
|
|
380
|
+
# - allowlist (built-in): a change outside `allowed` is blocked, a `protected` one
|
|
381
|
+
# needs approval; generated files (`generated:` and the manifest) may change,
|
|
382
|
+
# and drift and manifest verify them
|
|
372
383
|
#
|
|
373
|
-
# Gate 2: OpenAPI Contract Validation (
|
|
374
|
-
# - spec-lint: Schema Validity, x-
|
|
384
|
+
# Gate 2: OpenAPI Contract Validation (Redocly)
|
|
385
|
+
# - spec-lint: Schema Validity, x-micro-contracts-service/-method Required, Canonical Extension Prefix
|
|
375
386
|
# - spec-breaking: Breaking Changes detection (oasdiff)
|
|
376
387
|
#
|
|
377
388
|
# Gate 3: Generated Artifact Integrity
|
|
378
|
-
# - drift (built-in):
|
|
379
|
-
#
|
|
389
|
+
# - drift (built-in): uncommitted changes to generated files in the manifest's
|
|
390
|
+
# directory: by default the deepest one holding every output the config
|
|
391
|
+
# generates to (here, this directory)
|
|
392
|
+
# - manifest (built-in): SHA-256 verification of the generated files recorded in
|
|
393
|
+
# .generated-manifest.json in that directory
|
|
380
394
|
# - package-typecheck: Generated package type check
|
|
381
395
|
#
|
|
382
396
|
# Gate 4: Code Quality
|
|
@@ -399,9 +413,9 @@ checks:
|
|
|
399
413
|
# ==========================================
|
|
400
414
|
# Gate 2: OpenAPI Contract Validation
|
|
401
415
|
# ==========================================
|
|
402
|
-
# Schema Validity, x-
|
|
416
|
+
# Schema Validity, x-micro-contracts-service/-method Required, Canonical Extension Prefix
|
|
403
417
|
spec-lint:
|
|
404
|
-
command: "npx
|
|
418
|
+
command: "npx redocly lint {files} --config spec/redocly.yaml"
|
|
405
419
|
gate: 2
|
|
406
420
|
|
|
407
421
|
# Breaking Changes detection (oasdiff)
|
|
@@ -466,7 +480,7 @@ checks:
|
|
|
466
480
|
|
|
467
481
|
### Manifest Format
|
|
468
482
|
|
|
469
|
-
When guardrails are configured with a `generated:` section, `micro-contracts generate` automatically creates
|
|
483
|
+
When guardrails are configured with a `generated:` section, `micro-contracts generate` automatically creates `.generated-manifest.json`, with paths relative to its directory:
|
|
470
484
|
|
|
471
485
|
```json
|
|
472
486
|
{
|
|
@@ -474,7 +488,7 @@ When guardrails are configured with a `generated:` section, `micro-contracts gen
|
|
|
474
488
|
"generatorVersion": "0.9.3",
|
|
475
489
|
"updatedAt": "2024-01-15T10:30:00Z",
|
|
476
490
|
"files": {
|
|
477
|
-
"contract/core/schemas/types.ts": {
|
|
491
|
+
"packages/contract/core/schemas/types.ts": {
|
|
478
492
|
"sha256": "a1b2c3d4e5f6...",
|
|
479
493
|
"source": "spec/core/openapi/core.yaml"
|
|
480
494
|
}
|
|
@@ -523,7 +537,7 @@ what makes it usable as an approval at all.
|
|
|
523
537
|
|
|
524
538
|
| Path | Owner | Reason |
|
|
525
539
|
|------|-------|--------|
|
|
526
|
-
| `spec/
|
|
540
|
+
| `spec/redocly.yaml` | security/platform | Lint rules |
|
|
527
541
|
| `server/src/_shared/overlays/**` | security/platform | Security logic |
|
|
528
542
|
| `micro-contracts.guardrails.yaml` | security/platform | Guardrail config |
|
|
529
543
|
| `.github/**` | infra/maintainer | CI definitions |
|
|
@@ -658,8 +672,8 @@ jobs:
|
|
|
658
672
|
"check:docs-sync": "node ../dist/cli.js check --only docs-sync",
|
|
659
673
|
"check:docs-links": "node ../dist/cli.js check --only docs-links",
|
|
660
674
|
|
|
661
|
-
"lint:openapi": "
|
|
662
|
-
"lint:openapi:generated": "
|
|
675
|
+
"lint:openapi": "redocly lint spec/core/openapi/core.yaml spec/billing/openapi/billing.yaml --config spec/redocly.yaml",
|
|
676
|
+
"lint:openapi:generated": "redocly lint packages/contract/core/docs/openapi.generated.yaml packages/contract/billing/docs/openapi.generated.yaml --config spec/redocly.yaml",
|
|
663
677
|
"lint:ts": "eslint server/src frontend/src --ext .ts,.tsx",
|
|
664
678
|
"lint": "npm run lint:openapi && npm run lint:ts",
|
|
665
679
|
|
|
@@ -96,7 +96,7 @@
|
|
|
96
96
|
<text x="285" y="352" text-anchor="middle" fill="#1e40af" font-size="13" font-weight="600">OpenAPI Spec Validation</text>
|
|
97
97
|
|
|
98
98
|
<rect x="100" y="362" width="200" height="24" rx="4" fill="#dc2626"/>
|
|
99
|
-
<text x="200" y="378" text-anchor="middle" fill="white" font-size="9" font-weight="600">Spec Lint (
|
|
99
|
+
<text x="200" y="378" text-anchor="middle" fill="white" font-size="9" font-weight="600">Spec Lint (Redocly)</text>
|
|
100
100
|
|
|
101
101
|
<rect x="320" y="362" width="180" height="24" rx="4" fill="#f59e0b"/>
|
|
102
102
|
<text x="410" y="378" text-anchor="middle" fill="white" font-size="9" font-weight="600">Breaking Changes (oasdiff)</text>
|
|
@@ -133,7 +133,7 @@
|
|
|
133
133
|
<text x="430" y="558" text-anchor="middle" fill="white" font-size="9" font-weight="600">Package Typecheck (tsc)</text>
|
|
134
134
|
|
|
135
135
|
<rect x="60" y="577" width="180" height="24" rx="4" fill="#dc2626"/>
|
|
136
|
-
<text x="150" y="593" text-anchor="middle" fill="white" font-size="9" font-weight="600">Project Rules (
|
|
136
|
+
<text x="150" y="593" text-anchor="middle" fill="white" font-size="9" font-weight="600">Project Rules (Redocly)</text>
|
|
137
137
|
|
|
138
138
|
<rect x="250" y="577" width="250" height="24" rx="4" fill="#dc2626"/>
|
|
139
139
|
<text x="375" y="593" text-anchor="middle" fill="white" font-size="9" font-weight="600">Published Breaking Changes (oasdiff)</text>
|
|
@@ -135,7 +135,7 @@ actions:
|
|
|
135
135
|
|
|
136
136
|
### $ref Paths in Overlays
|
|
137
137
|
|
|
138
|
-
Specify `$ref` paths **relative to the overlay file's location**. micro-contracts
|
|
138
|
+
Specify `$ref` paths **relative to the overlay file's location**. A `$ref` into another file must point at a component (`#/components/<section>/<name>`): micro-contracts brings that component, and everything it references, into the module's spec, and the reference becomes a local one.
|
|
139
139
|
|
|
140
140
|
```yaml
|
|
141
141
|
# spec/_shared/overlays/middleware.overlay.yaml
|
|
@@ -143,14 +143,12 @@ $ref: '../openapi/problem-details.yaml#/components/responses/Unauthorized'
|
|
|
143
143
|
# ↑ Resolves to spec/_shared/openapi/problem-details.yaml
|
|
144
144
|
```
|
|
145
145
|
|
|
146
|
-
|
|
146
|
+
| File | $ref |
|
|
147
|
+
|------|------|
|
|
148
|
+
| Overlay (source) | `../openapi/problem-details.yaml#/components/responses/Unauthorized` |
|
|
149
|
+
| Generated spec (`packages/contract/core/docs/openapi.generated.yaml`) | `#/components/responses/Unauthorized`, with `Unauthorized` and the `ProblemDetails` schema it references under `components` |
|
|
147
150
|
|
|
148
|
-
|
|
149
|
-
|------|-----------|
|
|
150
|
-
| Overlay (source) | `../openapi/problem-details.yaml#/...` |
|
|
151
|
-
| Generated spec (`packages/contract/core/docs/openapi.generated.yaml`) | `../../../../spec/_shared/openapi/problem-details.yaml#/...` |
|
|
152
|
-
|
|
153
|
-
The generated path is relative to `openapi.generated.yaml`'s location, ensuring the reference resolves correctly.
|
|
151
|
+
The generated spec references nothing outside itself. A component brought in under a name the spec already uses for a different definition is an error.
|
|
154
152
|
|
|
155
153
|
---
|
|
156
154
|
|
|
@@ -185,6 +183,11 @@ export async function requireAuth(input: RequireAuthOverlayInput): Promise<Overl
|
|
|
185
183
|
|
|
186
184
|
> **📦 Full examples**: See [`examples/server/src/core/overlays/`](../examples/server/src/core/overlays/)
|
|
187
185
|
|
|
186
|
+
A parameter the overlay declares `required: true` is always in the input: the generated
|
|
187
|
+
adapter refuses a request without it — header, query or cookie — with 400 (a ProblemDetails
|
|
188
|
+
naming the missing parameter) before the handler runs. The generated route also validates an
|
|
189
|
+
injected header, query or cookie parameter against its schema, before any overlay runs.
|
|
190
|
+
|
|
188
191
|
### Layer Responsibilities
|
|
189
192
|
|
|
190
193
|
| Layer | Responsibility | Touches HTTP objects | Knows HTTP concepts |
|
|
@@ -287,7 +290,9 @@ operations get a handler:
|
|
|
287
290
|
|
|
288
291
|
A named action gets an `OverlayRegistry` entry, a handler type, an extractor in the overlay
|
|
289
292
|
adapter, and a `runOverlays` call on every operation its target selected — through a marker or
|
|
290
|
-
through `$.paths[*][*]`.
|
|
293
|
+
through `$.paths[*][*]`. The registry entry is keyed by the name as written; the types are named
|
|
294
|
+
by its words, capitalized: `requireAuth` gets `RequireAuthOverlayInput`, and `tenant-isolation`
|
|
295
|
+
gets `TenantIsolationOverlayInput` under the registry key `'tenant-isolation'`. An unnamed action injects its parameters, responses and extension
|
|
291
296
|
properties into the spec and stops there, which is what a documentation-only header such as
|
|
292
297
|
`X-Correlation-Id` needs.
|
|
293
298
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "micro-contracts",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"description": "Contract-first OpenAPI toolchain that keeps TypeScript UI and microservices aligned via code generation",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -80,9 +80,9 @@
|
|
|
80
80
|
"@types/node": "^20.11.0",
|
|
81
81
|
"agent-contracts": "^0.34.12",
|
|
82
82
|
"agent-contracts-analyzer": "file:vendor/agent-contracts-analyzer-0.1.1.tgz",
|
|
83
|
-
"agent-contracts-runtime": "^0.36.
|
|
83
|
+
"agent-contracts-runtime": "^0.36.15",
|
|
84
84
|
"chalk": "^5.3.0",
|
|
85
|
-
"cli-contracts": "^0.34.
|
|
85
|
+
"cli-contracts": "^0.34.12",
|
|
86
86
|
"commander": "^12.1.0",
|
|
87
87
|
"embedoc": "^0.9.0",
|
|
88
88
|
"esbuild": "^0.28.0",
|