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.
Files changed (96) hide show
  1. package/README.md +120 -5
  2. package/cli-contract.yaml +29 -17
  3. package/dist/agents/context-builder.d.ts.map +1 -1
  4. package/dist/agents/context-builder.js +3 -3
  5. package/dist/agents/context-builder.js.map +1 -1
  6. package/dist/cli/templates.d.ts +2 -1
  7. package/dist/cli/templates.d.ts.map +1 -1
  8. package/dist/cli/templates.js +173 -80
  9. package/dist/cli/templates.js.map +1 -1
  10. package/dist/cli.js +85 -54
  11. package/dist/cli.js.map +1 -1
  12. package/dist/generated/contract.d.ts.map +1 -1
  13. package/dist/generated/contract.js +2 -2
  14. package/dist/generated/contract.js.map +1 -1
  15. package/dist/generated/dsl/dsl-data.js +1 -1
  16. package/dist/generated/dsl/dsl-data.js.map +1 -1
  17. package/dist/generated/policy-runtime.d.ts +19 -5
  18. package/dist/generated/policy-runtime.d.ts.map +1 -1
  19. package/dist/generated/policy-runtime.js +65 -40
  20. package/dist/generated/policy-runtime.js.map +1 -1
  21. package/dist/generated/policy.d.ts +0 -4
  22. package/dist/generated/policy.d.ts.map +1 -1
  23. package/dist/generated/policy.js +6 -28
  24. package/dist/generated/policy.js.map +1 -1
  25. package/dist/generated/program.d.ts.map +1 -1
  26. package/dist/generated/program.js +14 -8
  27. package/dist/generated/program.js.map +1 -1
  28. package/dist/generator/index.d.ts +15 -5
  29. package/dist/generator/index.d.ts.map +1 -1
  30. package/dist/generator/index.js +71 -33
  31. package/dist/generator/index.js.map +1 -1
  32. package/dist/generator/inputHash.d.ts.map +1 -1
  33. package/dist/generator/inputHash.js +3 -57
  34. package/dist/generator/inputHash.js.map +1 -1
  35. package/dist/generator/linter.d.ts.map +1 -1
  36. package/dist/generator/linter.js +23 -25
  37. package/dist/generator/linter.js.map +1 -1
  38. package/dist/generator/overlayProcessor.d.ts +15 -11
  39. package/dist/generator/overlayProcessor.d.ts.map +1 -1
  40. package/dist/generator/overlayProcessor.js +63 -124
  41. package/dist/generator/overlayProcessor.js.map +1 -1
  42. package/dist/generator/schemaGenerator.d.ts.map +1 -1
  43. package/dist/generator/schemaGenerator.js +124 -140
  44. package/dist/generator/schemaGenerator.js.map +1 -1
  45. package/dist/generator/schemaGenerator.test.js +109 -0
  46. package/dist/generator/schemaGenerator.test.js.map +1 -1
  47. package/dist/generator/serviceGenerator.d.ts.map +1 -1
  48. package/dist/generator/serviceGenerator.js +18 -70
  49. package/dist/generator/serviceGenerator.js.map +1 -1
  50. package/dist/generator/specLoader.d.ts +33 -0
  51. package/dist/generator/specLoader.d.ts.map +1 -0
  52. package/dist/generator/specLoader.js +175 -0
  53. package/dist/generator/specLoader.js.map +1 -0
  54. package/dist/generator/templateProcessor.d.ts +35 -3
  55. package/dist/generator/templateProcessor.d.ts.map +1 -1
  56. package/dist/generator/templateProcessor.js +84 -77
  57. package/dist/generator/templateProcessor.js.map +1 -1
  58. package/dist/generator/typeGenerator.d.ts +42 -4
  59. package/dist/generator/typeGenerator.d.ts.map +1 -1
  60. package/dist/generator/typeGenerator.js +83 -72
  61. package/dist/generator/typeGenerator.js.map +1 -1
  62. package/dist/generator/typeGenerator.test.js +16 -0
  63. package/dist/generator/typeGenerator.test.js.map +1 -1
  64. package/dist/guardrails/allowlist.d.ts.map +1 -1
  65. package/dist/guardrails/allowlist.js +2 -1
  66. package/dist/guardrails/allowlist.js.map +1 -1
  67. package/dist/guardrails/config.js +3 -3
  68. package/dist/guardrails/config.js.map +1 -1
  69. package/dist/guardrails/drift.d.ts +5 -2
  70. package/dist/guardrails/drift.d.ts.map +1 -1
  71. package/dist/guardrails/drift.js +20 -15
  72. package/dist/guardrails/drift.js.map +1 -1
  73. package/dist/guardrails/index.d.ts +2 -2
  74. package/dist/guardrails/index.d.ts.map +1 -1
  75. package/dist/guardrails/index.js +1 -1
  76. package/dist/guardrails/index.js.map +1 -1
  77. package/dist/guardrails/lint.d.ts.map +1 -1
  78. package/dist/guardrails/lint.js +5 -6
  79. package/dist/guardrails/lint.js.map +1 -1
  80. package/dist/guardrails/manifest.d.ts +52 -8
  81. package/dist/guardrails/manifest.d.ts.map +1 -1
  82. package/dist/guardrails/manifest.js +157 -34
  83. package/dist/guardrails/manifest.js.map +1 -1
  84. package/dist/guardrails/types.d.ts +3 -1
  85. package/dist/guardrails/types.d.ts.map +1 -1
  86. package/dist/micro-contracts.bundle.mjs +640 -526
  87. package/dist/micro-contracts.bundle.mjs.map +4 -4
  88. package/dist/types.d.ts +135 -12
  89. package/dist/types.d.ts.map +1 -1
  90. package/dist/types.js +175 -14
  91. package/dist/types.js.map +1 -1
  92. package/docs/cli-reference.md +14 -14
  93. package/docs/development-guardrails.md +45 -31
  94. package/docs/guardrails-concept.svg +2 -2
  95. package/docs/overlays-deep-dive.md +14 -9
  96. package/package.json +3 -3
@@ -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.18.18
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, applies overlays, runs Spectral linting (unless skipped), and generates contract packages, server routes, frontend clients, and documentation from OpenAPI specs. Supports input-hash caching to skip unnecessary regeneration.
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 Spectral linting before generation. |
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 | `"packages/"` | Directory for manifest output. |
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 for x-micro-contracts extension violations and structural issues using Spectral rules.
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, Spectral rules, and optional config file for a new module. Can also process an existing OpenAPI spec to auto-add x-micro-contracts extensions.
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 | `"packages/"` | Path to generated files directory. |
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 | `"packages/"` | Path to generated files directory. |
323
- | `--manifest` | | No | `true` | Generate manifest after generation. Enabled by default. Use --no-manifest to disable. |
324
- | `--skip-lint` | | No | `false` | Skip Spectral linting before generation. |
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 | `"packages/"` | Directory to scan. |
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> Path to generated files directory (default: "packages/")
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> Path to generated files directory (default: "packages/")
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/spectral.yaml`, `server/src/_shared/overlays/**` | Anyone, once a maintainer approves the pull request (see below) |
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
- - Spectral lint rules (`spec/spectral.yaml`) — security rule tampering
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 (Spectral) | `micro-contracts check --only spec-lint` | `spec-lint` |
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 Spectral ruleset:
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 `packages/.generated-manifest.json`. Use `--no-manifest` to skip this behavior.
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 | `packages/**` must match the commit (staged, unstaged and untracked all count) | `micro-contracts check --only drift` | `drift` |
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 Spectral rules on **generated** spec | `micro-contracts check --only spec-project` | `spec-project` |
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`, `packages/**` must match committed state:
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 --exit-code HEAD -- packages/ && git ls-files --others --exclude-standard packages/
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** — `packages/.generated-manifest.json` stores:
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
- # Spectral lint rules
340
- - spec/spectral.yaml
341
- - spec/_shared/spectral.yaml
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): packages/** edit blocked, *.generated.* edit blocked
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 (Spectral)
374
- # - spec-lint: Schema Validity, x-security Required, x-auth Declaration
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): git diff packages/**
379
- # - manifest (built-in): SHA-256 verification
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-security Required, x-auth Declaration, Description Check
416
+ # Schema Validity, x-micro-contracts-service/-method Required, Canonical Extension Prefix
403
417
  spec-lint:
404
- command: "npx @stoplight/spectral-cli lint {files} --ruleset spec/spectral.yaml"
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 `packages/.generated-manifest.json`:
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/spectral.yaml` | security/platform | Lint rules |
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": "spectral lint spec/core/openapi/core.yaml spec/billing/openapi/billing.yaml --ruleset spec/spectral.yaml",
662
- "lint:openapi:generated": "spectral lint packages/contract/core/docs/openapi.generated.yaml packages/contract/billing/docs/openapi.generated.yaml --ruleset spec/spectral.yaml",
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 (Spectral)</text>
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 (Spectral)</text>
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 automatically rebases these paths so that the generated `openapi.generated.yaml` can resolve them correctly.
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
- **Rebase example:**
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
- | File | $ref path |
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[*][*]`. An unnamed action injects its parameters, responses and extension
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.18.18",
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.6",
83
+ "agent-contracts-runtime": "^0.36.15",
84
84
  "chalk": "^5.3.0",
85
- "cli-contracts": "^0.34.6",
85
+ "cli-contracts": "^0.34.12",
86
86
  "commander": "^12.1.0",
87
87
  "embedoc": "^0.9.0",
88
88
  "esbuild": "^0.28.0",