micro-contracts 0.17.19 → 0.18.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 CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  micro-contracts is a contract-first toolchain for TypeScript Web/API development. It tackles common failure modes—**frontend/backend contract drift**, **duplicated "common" rules**, and **accidental breaking changes in public APIs**—by treating **OpenAPI as the Single Source of Truth (SSoT)**.
8
8
 
9
- Contracts alone aren't enough—they must be **enforceable**. micro-contracts includes **[Enforceable Guardrails](docs/development-guardrails.md)** that prevent both humans and AI from bypassing the contract-first workflow: blocking direct edits to generated files, detecting drift, and verifying security declarations match implementations.
9
+ Contracts alone aren't enough—they must be **enforceable**. micro-contracts includes **[Enforceable Guardrails](docs/development-guardrails.md)** that prevent both humans and AI from bypassing the contract-first workflow: generated files may only change by regenerating them (drift and manifest integrity), changes stay inside allowed paths, and the contract itself is linted before anything is generated.
10
10
 
11
11
  ## Design Philosophy
12
12
 
@@ -25,9 +25,9 @@ The core architecture is organized along two axes:
25
25
  |---|----------------|---------------|
26
26
  | 1 | **Vertical Modules + Horizontal Overlays** | Feature-aligned modules as contract boundaries; cross-cutting concerns (auth, rate-limit) injected via [OpenAPI Overlays](https://www.openapis.org/blog/2024/10/22/announcing-overlay-specification). |
27
27
  | 2 | **OpenAPI as SSoT → Multi-artifact generation** | Single spec generates contract packages, server routes, and frontend clients. No manual sync required. |
28
- | 3 | **Enforceable Guardrails** | Built-in checks prevent bypassing contract-first workflow—blocks direct edits to generated files, detects drift, verifies security declarations. See **[Guardrails](docs/development-guardrails.md)**. |
28
+ | 3 | **Enforceable Guardrails** | Built-in checks prevent bypassing contract-first workflow—allowlist for changed paths, drift detection and manifest integrity for generated artifacts, plus your own commands as gated checks. See **[Guardrails](docs/development-guardrails.md)**. |
29
29
  | 4 | **Public Surface Governance** | `contract-published` is extracted (not duplicated) from the master contract. `x-micro-contracts-non-exportable` fails generation if internal data leaks. |
30
- | 5 | **Explicit Module Dependencies** | `x-micro-contracts-depend-on` declares cross-module dependencies. `deps/` re-exports only declared types; enables impact analysis. |
30
+ | 5 | **Explicit Module Dependencies** | `x-micro-contracts-depend-on` declares cross-module dependencies. `deps/` re-exports only the types the declared operations reach; enables impact analysis. |
31
31
  | 6 | **Screen Spec** | Declare frontend screen contracts (ViewModel, navigation, analytics events) in OpenAPI. One YAML drives typed navigation maps and event hooks. See **[Screen Spec](docs/screen-spec.md)**. |
32
32
 
33
33
  ---
@@ -205,7 +205,7 @@ project/
205
205
  | Extension | Type | Description |
206
206
  |-----------|------|-------------|
207
207
  | `x-micro-contracts-published` | boolean | Include in `contract-published` (compatibility SLA) |
208
- | `x-micro-contracts-non-exportable` | boolean | Mark as non-exportable (fails if used in published endpoints) |
208
+ | `x-micro-contracts-non-exportable` | boolean | Operation- or schema-level. Linting fails when a published endpoint can reach it (`PUBLIC_ENDPOINT_NON_EXPORTABLE`) |
209
209
  | `x-micro-contracts-depend-on` | string[] | Explicit dependencies on other modules' published APIs |
210
210
  | `x-private` | boolean | Schema-level. A published endpoint that can reach it fails linting (`PUBLIC_ENDPOINT_PRIVATE_RESPONSE`) |
211
211
 
@@ -214,7 +214,8 @@ items, `additionalProperties`, `allOf`/`oneOf`/`anyOf`, `$ref` targets) and ever
214
214
  part of an operation that reaches a schema: request bodies, parameters and
215
215
  responses of any status code, including through `components.requestBodies`,
216
216
  `components.parameters` and `components.responses`. `contract-published` contains
217
- exactly what that same reachability finds, so nothing can ship unchecked.
217
+ exactly what that same reachability finds, so nothing can ship unchecked. The same
218
+ reachability enforces `x-micro-contracts-non-exportable`.
218
219
 
219
220
  ### Screen Spec Extensions
220
221
 
@@ -272,6 +273,12 @@ import type { User } from '@project/contract/billing/deps/core';
272
273
  import type { User } from '@project/contract-published/core/schemas';
273
274
  ```
274
275
 
276
+ `deps/<target>.ts` re-exports named types only: those the declared operations
277
+ reach, plus their generated input types. Types the target publishes but no
278
+ declared operation reaches are not exposed. Each declared operation must exist
279
+ in the target module and be `x-micro-contracts-published: true` — otherwise
280
+ generation fails, since `contract-published` would not carry it.
281
+
275
282
  ---
276
283
 
277
284
  ## Configuration
package/cli-contract.yaml CHANGED
@@ -3,7 +3,7 @@ cli_contracts: 0.1.0
3
3
 
4
4
  info:
5
5
  title: micro-contracts CLI
6
- version: 0.17.19
6
+ version: 0.18.0
7
7
  description: >-
8
8
  Contract-first OpenAPI toolchain for TypeScript Web/API systems.
9
9
  Generates contract packages, server routes, and frontend clients