micro-contracts 0.17.14 → 0.17.16
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 +36 -5
- package/cli-contract.yaml +15 -5
- package/dist/external/insight-provider.js +2 -4
- package/dist/micro-contracts.bundle.mjs +354 -510
- package/dist/micro-contracts.bundle.mjs.map +4 -4
- package/docs/cli-reference.md +5 -5
- package/docs/development-guardrails.md +2 -2
- package/docs/screen-spec.md +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -207,6 +207,11 @@ project/
|
|
|
207
207
|
| `x-micro-contracts-published` | boolean | Include in `contract-published` (compatibility SLA) |
|
|
208
208
|
| `x-micro-contracts-non-exportable` | boolean | Mark as non-exportable (fails if used in published endpoints) |
|
|
209
209
|
| `x-micro-contracts-depend-on` | string[] | Explicit dependencies on other modules' published APIs |
|
|
210
|
+
| `x-private` | boolean | Schema-level. A published endpoint that can reach it fails linting (`PUBLIC_ENDPOINT_PRIVATE_RESPONSE`) |
|
|
211
|
+
|
|
212
|
+
"Can reach it" covers every way one schema refers to another: properties, array
|
|
213
|
+
items, `additionalProperties`, `allOf`/`oneOf`/`anyOf`, and `$ref` targets — the
|
|
214
|
+
same traversal that decides what `contract-published` contains.
|
|
210
215
|
|
|
211
216
|
### Screen Spec Extensions
|
|
212
217
|
|
|
@@ -278,16 +283,28 @@ Create `micro-contracts.config.yaml`. All paths support `{module}` placeholder.
|
|
|
278
283
|
| `contract.serviceTemplate` | string | no | Custom Handlebars template for service interface generation |
|
|
279
284
|
| `contractPublic.output` | string | yes | Output directory for public contract packages |
|
|
280
285
|
| `outputs.<id>.output` | string | yes | Output file path |
|
|
281
|
-
| `outputs.<id>.template` | string | yes | Handlebars template file path |
|
|
286
|
+
| `outputs.<id>.template` | string | yes | Handlebars template file path, used as written (resolved from the working directory) |
|
|
282
287
|
| `outputs.<id>.overwrite` | boolean | no | Overwrite existing files (default: `true`) |
|
|
283
288
|
| `outputs.<id>.condition` | string | no | `hasPublicEndpoints` \| `hasOverlays` \| `always` (default: `always`) |
|
|
284
289
|
| `outputs.<id>.enabled` | boolean | no | Enable/disable this output (default: `true`) |
|
|
285
290
|
| `outputs.<id>.config` | object | no | Template-specific configuration passed to context |
|
|
291
|
+
|
|
286
292
|
| `overlays.shared` | string[] | no | Overlay files applied to all modules |
|
|
287
293
|
| `overlays.collision` | string | no | `error` \| `warn` \| `last-wins` (default: `error`) |
|
|
288
294
|
| `docs.enabled` | boolean | no | Enable documentation generation (default: `true`) |
|
|
289
295
|
| `docs.template` | string | no | Documentation template |
|
|
290
296
|
| `sharedModuleName` | string | no | Shared module name for overlays |
|
|
297
|
+
| `server.output` | string | no | Output **file** path for generated routes (default: `server/src/{module}/routes.generated.ts`) |
|
|
298
|
+
| `server.template` | string | yes if `server` is declared | Handlebars template for the routes file |
|
|
299
|
+
| `server.servicesPath` | string | no | Path to the services object in Fastify (default: `fastify.services.{module}`) |
|
|
300
|
+
| `frontend.output` | string | no | Output **directory** for the client files (default: `frontend/src/{module}`) |
|
|
301
|
+
| `frontend.template` | string | yes if `frontend` is declared | Handlebars template for the client file |
|
|
302
|
+
| `frontend.client` | string | no | Client file name (default: `api.generated.ts`) |
|
|
303
|
+
| `frontend.service` | string | no | Service re-exports file name (default: `service.generated.ts`) |
|
|
304
|
+
|
|
305
|
+
`server` and `frontend` are the built-in equivalents of an `outputs` entry, kept for
|
|
306
|
+
existing configs. They generate only when declared, and only when no `outputs` entry
|
|
307
|
+
is configured — `outputs` supersedes them for a module. Prefer `outputs`.
|
|
291
308
|
|
|
292
309
|
### modules.\<name\>
|
|
293
310
|
|
|
@@ -304,6 +321,12 @@ Create `micro-contracts.config.yaml`. All paths support `{module}` placeholder.
|
|
|
304
321
|
| `dependsOn` | string[] | no | Dependencies (`{module}.{service}.{method}`) |
|
|
305
322
|
| `spectral` | string | no | Module-specific Spectral config path |
|
|
306
323
|
| `docs.enabled` | boolean | no | Override documentation generation |
|
|
324
|
+
| `server.*` | — | no | Override any `defaults.server` field |
|
|
325
|
+
| `server.enabled` | boolean | no | Disable built-in server generation for this module |
|
|
326
|
+
| `frontend.*` | — | no | Override any `defaults.frontend` field |
|
|
327
|
+
| `frontend.enabled` | boolean | no | Disable built-in frontend generation for this module |
|
|
328
|
+
|
|
329
|
+
Unknown keys are rejected: a mistyped key fails the run instead of being ignored.
|
|
307
330
|
|
|
308
331
|
### Example
|
|
309
332
|
|
|
@@ -351,8 +374,8 @@ Generate code from OpenAPI specifications.
|
|
|
351
374
|
| `-c, --config <path>` | Path to config file |
|
|
352
375
|
| `-m, --module <names>` | Module names, comma-separated (default: all) |
|
|
353
376
|
| `--contracts-only` | Generate contract packages only |
|
|
354
|
-
| `--server-only` | Generate server
|
|
355
|
-
| `--frontend-only` | Generate frontend
|
|
377
|
+
| `--server-only` | Generate server outputs only (outputs whose id contains `server`) |
|
|
378
|
+
| `--frontend-only` | Generate frontend outputs only (outputs whose id contains `frontend` or `client`) |
|
|
356
379
|
| `--docs-only` | Generate documentation only |
|
|
357
380
|
| `--skip-lint` | Skip linting before generation |
|
|
358
381
|
| `--no-manifest` | Skip manifest generation |
|
|
@@ -380,6 +403,14 @@ Lint OpenAPI specification.
|
|
|
380
403
|
|--------|-------------|
|
|
381
404
|
| `--strict` | Treat warnings as errors |
|
|
382
405
|
|
|
406
|
+
Every operation requires `x-micro-contracts-service` and `x-micro-contracts-method`,
|
|
407
|
+
and both must be valid TypeScript identifiers: they key route collection and service
|
|
408
|
+
grouping, and are emitted verbatim into generated type names. Operations missing them
|
|
409
|
+
would be dropped from every artifact, so they are errors (`MISSING_X_SERVICE`,
|
|
410
|
+
`MISSING_X_METHOD`, `INVALID_X_SERVICE`, `INVALID_X_METHOD`). In screen spec mode
|
|
411
|
+
(`screen: true`) operations are consumed via `TemplateContext.screens` and these rules
|
|
412
|
+
do not apply.
|
|
413
|
+
|
|
383
414
|
### check
|
|
384
415
|
|
|
385
416
|
Run guardrail checks.
|
|
@@ -412,8 +443,8 @@ Run full guardrails pipeline: **Gate 1,2 → Generate → Gate 3,4,5**.
|
|
|
412
443
|
| `--no-manifest` | Skip manifest generation |
|
|
413
444
|
| `--skip-lint` | Skip linting before generation |
|
|
414
445
|
| `--contracts-only` | Generate contract packages only |
|
|
415
|
-
| `--server-only` | Generate server
|
|
416
|
-
| `--frontend-only` | Generate frontend
|
|
446
|
+
| `--server-only` | Generate server outputs only (outputs whose id contains `server`) |
|
|
447
|
+
| `--frontend-only` | Generate frontend outputs only (outputs whose id contains `frontend` or `client`) |
|
|
417
448
|
| `--docs-only` | Generate documentation only |
|
|
418
449
|
| `--force` | Bypass input hash cache and always regenerate |
|
|
419
450
|
| `--no-cache` | Run without reading or writing input hash cache |
|
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.
|
|
6
|
+
version: 0.17.16
|
|
7
7
|
description: >-
|
|
8
8
|
Contract-first OpenAPI toolchain for TypeScript Web/API systems.
|
|
9
9
|
Generates contract packages, server routes, and frontend clients
|
|
@@ -92,13 +92,18 @@ command_sets:
|
|
|
92
92
|
default: false
|
|
93
93
|
|
|
94
94
|
- name: server-only
|
|
95
|
-
description:
|
|
95
|
+
description: >-
|
|
96
|
+
Generate server outputs only: outputs whose id contains 'server',
|
|
97
|
+
plus the built-in server section. Fails when no output matches.
|
|
96
98
|
schema:
|
|
97
99
|
type: boolean
|
|
98
100
|
default: false
|
|
99
101
|
|
|
100
102
|
- name: frontend-only
|
|
101
|
-
description:
|
|
103
|
+
description: >-
|
|
104
|
+
Generate frontend outputs only: outputs whose id contains
|
|
105
|
+
'frontend' or 'client', plus the built-in frontend section.
|
|
106
|
+
Fails when no output matches.
|
|
102
107
|
schema:
|
|
103
108
|
type: boolean
|
|
104
109
|
default: false
|
|
@@ -519,13 +524,18 @@ command_sets:
|
|
|
519
524
|
default: false
|
|
520
525
|
|
|
521
526
|
- name: server-only
|
|
522
|
-
description:
|
|
527
|
+
description: >-
|
|
528
|
+
Generate server outputs only: outputs whose id contains 'server',
|
|
529
|
+
plus the built-in server section. Fails when no output matches.
|
|
523
530
|
schema:
|
|
524
531
|
type: boolean
|
|
525
532
|
default: false
|
|
526
533
|
|
|
527
534
|
- name: frontend-only
|
|
528
|
-
description:
|
|
535
|
+
description: >-
|
|
536
|
+
Generate frontend outputs only: outputs whose id contains
|
|
537
|
+
'frontend' or 'client', plus the built-in frontend section.
|
|
538
|
+
Fails when no output matches.
|
|
529
539
|
schema:
|
|
530
540
|
type: boolean
|
|
531
541
|
default: false
|
|
@@ -4,12 +4,10 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import fs from "fs";
|
|
6
6
|
import path from "path";
|
|
7
|
-
import { createRequire } from "module";
|
|
8
7
|
import { loadConfig, loadOpenAPISpec } from "../generator/index.js";
|
|
9
8
|
import { extractDependencies } from "../types.js";
|
|
10
9
|
import { isMultiModuleConfig, resolveModuleConfig } from "../types.js";
|
|
11
|
-
|
|
12
|
-
const pkg = require("../../package.json");
|
|
10
|
+
import { VERSION } from "../version.js";
|
|
13
11
|
export const MICRO_CONTRACTS_INSIGHT_SOURCE = "micro-contracts";
|
|
14
12
|
const EVIDENCE_KIND = "api_contract_declaration";
|
|
15
13
|
const EDGE_WEIGHT = 0.9;
|
|
@@ -225,7 +223,7 @@ export function buildExternalInsight(projectRoot, options = {}) {
|
|
|
225
223
|
}
|
|
226
224
|
return {
|
|
227
225
|
source: MICRO_CONTRACTS_INSIGHT_SOURCE,
|
|
228
|
-
sourceVersion:
|
|
226
|
+
sourceVersion: VERSION,
|
|
229
227
|
generatedAt: new Date().toISOString(),
|
|
230
228
|
edges,
|
|
231
229
|
anchorMapping: [...anchorByDomain.values()],
|