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 +12 -5
- package/cli-contract.yaml +1 -1
- package/dist/micro-contracts.bundle.mjs +279 -277
- package/dist/micro-contracts.bundle.mjs.map +3 -3
- package/docs/cli-reference.md +1 -1
- package/package.json +1 -1
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:
|
|
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—
|
|
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
|
|
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 |
|
|
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