micro-contracts 0.18.18 → 0.19.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 (94) hide show
  1. package/README.md +63 -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.map +1 -1
  7. package/dist/cli/templates.js +14 -3
  8. package/dist/cli/templates.js.map +1 -1
  9. package/dist/cli.js +85 -54
  10. package/dist/cli.js.map +1 -1
  11. package/dist/generated/contract.d.ts.map +1 -1
  12. package/dist/generated/contract.js +2 -2
  13. package/dist/generated/contract.js.map +1 -1
  14. package/dist/generated/dsl/dsl-data.js +1 -1
  15. package/dist/generated/dsl/dsl-data.js.map +1 -1
  16. package/dist/generated/policy-runtime.d.ts +19 -5
  17. package/dist/generated/policy-runtime.d.ts.map +1 -1
  18. package/dist/generated/policy-runtime.js +65 -40
  19. package/dist/generated/policy-runtime.js.map +1 -1
  20. package/dist/generated/policy.d.ts +0 -4
  21. package/dist/generated/policy.d.ts.map +1 -1
  22. package/dist/generated/policy.js +6 -28
  23. package/dist/generated/policy.js.map +1 -1
  24. package/dist/generated/program.d.ts.map +1 -1
  25. package/dist/generated/program.js +14 -8
  26. package/dist/generated/program.js.map +1 -1
  27. package/dist/generator/index.d.ts +15 -5
  28. package/dist/generator/index.d.ts.map +1 -1
  29. package/dist/generator/index.js +65 -33
  30. package/dist/generator/index.js.map +1 -1
  31. package/dist/generator/inputHash.d.ts.map +1 -1
  32. package/dist/generator/inputHash.js +3 -57
  33. package/dist/generator/inputHash.js.map +1 -1
  34. package/dist/generator/linter.d.ts.map +1 -1
  35. package/dist/generator/linter.js +24 -25
  36. package/dist/generator/linter.js.map +1 -1
  37. package/dist/generator/overlayProcessor.d.ts +4 -11
  38. package/dist/generator/overlayProcessor.d.ts.map +1 -1
  39. package/dist/generator/overlayProcessor.js +42 -108
  40. package/dist/generator/overlayProcessor.js.map +1 -1
  41. package/dist/generator/schemaGenerator.d.ts.map +1 -1
  42. package/dist/generator/schemaGenerator.js +112 -140
  43. package/dist/generator/schemaGenerator.js.map +1 -1
  44. package/dist/generator/schemaGenerator.test.js +109 -0
  45. package/dist/generator/schemaGenerator.test.js.map +1 -1
  46. package/dist/generator/serviceGenerator.d.ts.map +1 -1
  47. package/dist/generator/serviceGenerator.js +20 -56
  48. package/dist/generator/serviceGenerator.js.map +1 -1
  49. package/dist/generator/specLoader.d.ts +33 -0
  50. package/dist/generator/specLoader.d.ts.map +1 -0
  51. package/dist/generator/specLoader.js +175 -0
  52. package/dist/generator/specLoader.js.map +1 -0
  53. package/dist/generator/templateProcessor.d.ts.map +1 -1
  54. package/dist/generator/templateProcessor.js +38 -55
  55. package/dist/generator/templateProcessor.js.map +1 -1
  56. package/dist/generator/typeGenerator.d.ts +2 -2
  57. package/dist/generator/typeGenerator.d.ts.map +1 -1
  58. package/dist/generator/typeGenerator.js +31 -29
  59. package/dist/generator/typeGenerator.js.map +1 -1
  60. package/dist/generator/typeGenerator.test.js +16 -0
  61. package/dist/generator/typeGenerator.test.js.map +1 -1
  62. package/dist/guardrails/allowlist.d.ts.map +1 -1
  63. package/dist/guardrails/allowlist.js +2 -1
  64. package/dist/guardrails/allowlist.js.map +1 -1
  65. package/dist/guardrails/config.js +3 -3
  66. package/dist/guardrails/config.js.map +1 -1
  67. package/dist/guardrails/drift.d.ts +5 -2
  68. package/dist/guardrails/drift.d.ts.map +1 -1
  69. package/dist/guardrails/drift.js +20 -15
  70. package/dist/guardrails/drift.js.map +1 -1
  71. package/dist/guardrails/index.d.ts +2 -2
  72. package/dist/guardrails/index.d.ts.map +1 -1
  73. package/dist/guardrails/index.js +1 -1
  74. package/dist/guardrails/index.js.map +1 -1
  75. package/dist/guardrails/lint.d.ts.map +1 -1
  76. package/dist/guardrails/lint.js +5 -6
  77. package/dist/guardrails/lint.js.map +1 -1
  78. package/dist/guardrails/manifest.d.ts +52 -8
  79. package/dist/guardrails/manifest.d.ts.map +1 -1
  80. package/dist/guardrails/manifest.js +157 -34
  81. package/dist/guardrails/manifest.js.map +1 -1
  82. package/dist/guardrails/types.d.ts +3 -1
  83. package/dist/guardrails/types.d.ts.map +1 -1
  84. package/dist/micro-contracts.bundle.mjs +563 -529
  85. package/dist/micro-contracts.bundle.mjs.map +4 -4
  86. package/dist/types.d.ts +101 -9
  87. package/dist/types.d.ts.map +1 -1
  88. package/dist/types.js +103 -14
  89. package/dist/types.js.map +1 -1
  90. package/docs/cli-reference.md +14 -14
  91. package/docs/development-guardrails.md +40 -31
  92. package/docs/guardrails-concept.svg +2 -2
  93. package/docs/overlays-deep-dive.md +6 -8
  94. package/package.json +3 -3
@@ -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
 
@@ -336,9 +338,11 @@ allowed:
336
338
 
337
339
  # Files that require special approval
338
340
  protected:
339
- # Spectral lint rules
340
- - spec/spectral.yaml
341
- - spec/_shared/spectral.yaml
341
+ # Lint rules: spec/redocly.yaml, the redocly.yaml of every spec/<dir>/ that
342
+ # extends it, and the plugin they load
343
+ - spec/*.yaml
344
+ - spec/*/*.yaml
345
+ - spec/redocly-plugin.js
342
346
 
343
347
  # Shared overlay definitions
344
348
  - spec/_shared/overlays/**
@@ -368,15 +372,20 @@ generated:
368
372
  # Based on guardrails-concept.svg:
369
373
  #
370
374
  # Gate 1: Change Allowlist
371
- # - allowlist (built-in): packages/** edit blocked, *.generated.* edit blocked
375
+ # - allowlist (built-in): a change outside `allowed` is blocked, a `protected` one
376
+ # needs approval; generated files (`generated:` and the manifest) may change,
377
+ # and drift and manifest verify them
372
378
  #
373
- # Gate 2: OpenAPI Contract Validation (Spectral)
374
- # - spec-lint: Schema Validity, x-security Required, x-auth Declaration
379
+ # Gate 2: OpenAPI Contract Validation (Redocly)
380
+ # - spec-lint: Schema Validity, x-micro-contracts-service/-method Required, Canonical Extension Prefix
375
381
  # - spec-breaking: Breaking Changes detection (oasdiff)
376
382
  #
377
383
  # Gate 3: Generated Artifact Integrity
378
- # - drift (built-in): git diff packages/**
379
- # - manifest (built-in): SHA-256 verification
384
+ # - drift (built-in): uncommitted changes to generated files in the manifest's
385
+ # directory: by default the deepest one holding every output the config
386
+ # generates to (here, this directory)
387
+ # - manifest (built-in): SHA-256 verification of the generated files recorded in
388
+ # .generated-manifest.json in that directory
380
389
  # - package-typecheck: Generated package type check
381
390
  #
382
391
  # Gate 4: Code Quality
@@ -399,9 +408,9 @@ checks:
399
408
  # ==========================================
400
409
  # Gate 2: OpenAPI Contract Validation
401
410
  # ==========================================
402
- # Schema Validity, x-security Required, x-auth Declaration, Description Check
411
+ # Schema Validity, x-micro-contracts-service/-method Required, Canonical Extension Prefix
403
412
  spec-lint:
404
- command: "npx @stoplight/spectral-cli lint {files} --ruleset spec/spectral.yaml"
413
+ command: "npx redocly lint {files} --config spec/redocly.yaml"
405
414
  gate: 2
406
415
 
407
416
  # Breaking Changes detection (oasdiff)
@@ -466,7 +475,7 @@ checks:
466
475
 
467
476
  ### Manifest Format
468
477
 
469
- When guardrails are configured with a `generated:` section, `micro-contracts generate` automatically creates `packages/.generated-manifest.json`:
478
+ When guardrails are configured with a `generated:` section, `micro-contracts generate` automatically creates `.generated-manifest.json`, with paths relative to its directory:
470
479
 
471
480
  ```json
472
481
  {
@@ -474,7 +483,7 @@ When guardrails are configured with a `generated:` section, `micro-contracts gen
474
483
  "generatorVersion": "0.9.3",
475
484
  "updatedAt": "2024-01-15T10:30:00Z",
476
485
  "files": {
477
- "contract/core/schemas/types.ts": {
486
+ "packages/contract/core/schemas/types.ts": {
478
487
  "sha256": "a1b2c3d4e5f6...",
479
488
  "source": "spec/core/openapi/core.yaml"
480
489
  }
@@ -523,7 +532,7 @@ what makes it usable as an approval at all.
523
532
 
524
533
  | Path | Owner | Reason |
525
534
  |------|-------|--------|
526
- | `spec/spectral.yaml` | security/platform | Lint rules |
535
+ | `spec/redocly.yaml` | security/platform | Lint rules |
527
536
  | `server/src/_shared/overlays/**` | security/platform | Security logic |
528
537
  | `micro-contracts.guardrails.yaml` | security/platform | Guardrail config |
529
538
  | `.github/**` | infra/maintainer | CI definitions |
@@ -658,8 +667,8 @@ jobs:
658
667
  "check:docs-sync": "node ../dist/cli.js check --only docs-sync",
659
668
  "check:docs-links": "node ../dist/cli.js check --only docs-links",
660
669
 
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",
670
+ "lint:openapi": "redocly lint spec/core/openapi/core.yaml spec/billing/openapi/billing.yaml --config spec/redocly.yaml",
671
+ "lint:openapi:generated": "redocly lint packages/contract/core/docs/openapi.generated.yaml packages/contract/billing/docs/openapi.generated.yaml --config spec/redocly.yaml",
663
672
  "lint:ts": "eslint server/src frontend/src --ext .ts,.tsx",
664
673
  "lint": "npm run lint:openapi && npm run lint:ts",
665
674
 
@@ -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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "micro-contracts",
3
- "version": "0.18.18",
3
+ "version": "0.19.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",