@effected/engine 0.12.0 → 0.14.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.
@@ -0,0 +1,352 @@
1
+ import { Schema, SchemaTransformation } from "effect";
2
+ import { PipelineFinding, SchemaVersion } from "@effected/schemastore";
3
+
4
+ // src/schema/RunReport.ts
5
+ /**
6
+ * One line of a {@link DocumentDiff} hunk, mirroring `LineDiffLine` from
7
+ * `@effected/source`, which stays free of any dependency.
8
+ *
9
+ * @public
10
+ */
11
+ const LineDiffLineSchema = Schema.Struct({
12
+ kind: Schema.Literals([
13
+ "context",
14
+ "add",
15
+ "remove"
16
+ ]),
17
+ text: Schema.String,
18
+ /** 1-based line in the old text; absent on an `add`. */
19
+ oldLine: Schema.optionalKey(Schema.Number),
20
+ /** 1-based line in the new text; absent on a `remove`. */
21
+ newLine: Schema.optionalKey(Schema.Number),
22
+ /** Set on a line that is the last of its text and has no terminating newline. */
23
+ noNewline: Schema.optionalKey(Schema.Literal(true))
24
+ });
25
+ /**
26
+ * One {@link DocumentDiff} hunk, mirroring `LineDiffHunk` from `@effected/source`.
27
+ *
28
+ * @public
29
+ */
30
+ const LineDiffHunkSchema = Schema.Struct({
31
+ oldStart: Schema.Number,
32
+ oldLines: Schema.Number,
33
+ newStart: Schema.Number,
34
+ newLines: Schema.Number,
35
+ lines: Schema.Array(LineDiffLineSchema)
36
+ });
37
+ /**
38
+ * What differs between a document on disk and the generated one, line by line.
39
+ *
40
+ * @remarks
41
+ * Both sides are in the kit's canonical JSON layout, so hunk line numbers refer
42
+ * to that form, which is byte-identical to the file in a tab-indented repo. A
43
+ * document that does not parse diffs as its raw text, and a missing one as all
44
+ * additions.
45
+ *
46
+ * @public
47
+ */
48
+ var DocumentDiff = class extends Schema.Class("DocumentDiff")({
49
+ /** The hunks, for a consumer that draws its own diff. */
50
+ hunks: Schema.Array(LineDiffHunkSchema),
51
+ /** The same hunks as git-style unified text. */
52
+ unified: Schema.String
53
+ }) {};
54
+ /**
55
+ * One schema's line in the {@link RunReport}.
56
+ *
57
+ * @public
58
+ */
59
+ var SchemaReport = class extends Schema.Class("SchemaReport")({
60
+ $id: Schema.String,
61
+ path: Schema.String,
62
+ /** The schema's key in the config. */
63
+ name: Schema.String,
64
+ version: Schema.optionalKey(SchemaVersion),
65
+ published: Schema.Boolean,
66
+ /** What differs between the on-disk document and the generated one. */
67
+ change: Schema.Literals([
68
+ "none",
69
+ "annotations",
70
+ "contract",
71
+ "created"
72
+ ]),
73
+ /** The drift policy's verdict; a written schema under `onDrift: "warn"` keeps `"drift"`. */
74
+ verdict: Schema.Literals(["write", "drift"]),
75
+ /** The tolerance actually applied: this schema's own, or a flag's override over every schema. */
76
+ policy: Schema.Literals([
77
+ "strict",
78
+ "semantic",
79
+ "allow"
80
+ ]),
81
+ outcome: Schema.Literals([
82
+ "written",
83
+ "unchanged",
84
+ "would-write",
85
+ "drift",
86
+ "held",
87
+ "gate-failed"
88
+ ]),
89
+ /** The label to publish under instead — set only for a `contract` change on a pinned (non-prerelease) versioned schema. */
90
+ nextVersion: Schema.optionalKey(SchemaVersion),
91
+ /** Every OTHER advertised version this schema's frozen check verified. */
92
+ frozen: Schema.Array(SchemaVersion),
93
+ /** Every finding, blocking or not. */
94
+ findings: Schema.Array(PipelineFinding),
95
+ /** Present when `change` is not `none`. The report always carries it whole; a summary caps what it shows. */
96
+ diff: Schema.optionalKey(DocumentDiff)
97
+ }) {};
98
+ /**
99
+ * This config's own catalog slice, `<catalogDir>/<name>.json`: a bare
100
+ * SchemaStore catalog entry array holding every entry the config declares,
101
+ * rewritten wholesale — so a removed schema's entry drops out.
102
+ *
103
+ * @public
104
+ */
105
+ var CatalogSliceReport = class extends Schema.Class("CatalogSliceReport")({
106
+ /** The slice file: `<catalogDir>/<name>.json`. */
107
+ path: Schema.String,
108
+ /** How many entries the slice holds; `0` for an orphan. */
109
+ entries: Schema.Number,
110
+ /**
111
+ * `held` mirrors {@link SchemaOutcome}: the run refused every write.
112
+ * `orphaned`: no schema declares a catalog but the slice exists — stale
113
+ * under `check`, reported and left in place under `build` (the tool may
114
+ * not have written it).
115
+ */
116
+ outcome: Schema.Literals([
117
+ "written",
118
+ "unchanged",
119
+ "would-write",
120
+ "held",
121
+ "orphaned"
122
+ ]),
123
+ /**
124
+ * Present when no file matched `<name>.json` exactly and the volume
125
+ * resolved that exact path to the one listed file whose name matches it
126
+ * case-insensitively (a leftover `docs.json` for a config named `Docs`
127
+ * on a case-insensitive volume) — the on-disk path it claimed. Never set
128
+ * on a case-sensitive volume, where that file is another slice. On a
129
+ * case-insensitive volume two configs whose names differ only in case
130
+ * share, and overwrite, that one file.
131
+ */
132
+ caseFoldedMatch: Schema.optionalKey(Schema.String)
133
+ }) {};
134
+ /**
135
+ * One catalog URL or display name advertised more than once across the
136
+ * slices, discriminated by `kind`. The merged catalog refuses to pick a
137
+ * winner: for a URL, which entry a host serves would depend on which config
138
+ * built last; for a name, an editor or SchemaStore would show two entries
139
+ * it cannot tell apart. A name is compared over the entries the merge
140
+ * advertises — an entry that already lost its URL to another slice is
141
+ * reported once, as the URL conflict.
142
+ *
143
+ * @public
144
+ */
145
+ const CatalogConflict = Schema.Union([Schema.Struct({
146
+ kind: Schema.Literal("url"),
147
+ /** The entry `url` claimed more than once. */
148
+ url: Schema.String,
149
+ /** Every slice file advertising it, sorted; a slice listed twice declares it twice itself. */
150
+ slices: Schema.Array(Schema.String)
151
+ }), Schema.Struct({
152
+ kind: Schema.Literal("name"),
153
+ /** The entry `name` claimed more than once. */
154
+ name: Schema.String,
155
+ /** Every slice file advertising it, sorted; a slice listed twice declares it twice itself. */
156
+ slices: Schema.Array(Schema.String)
157
+ })]);
158
+ /**
159
+ * One slice the merge could not use, and why: `unreadable: <reason>` (a
160
+ * dangling symlink, a permission failure), `not JSON`, or the decode issue
161
+ * itself — `Expected array` for a document that is not an array,
162
+ * `Expected no excess property at [0]["extra"]` for an entry carrying a key
163
+ * a catalog entry does not declare — one semicolon-separated clause per issue.
164
+ *
165
+ * @public
166
+ */
167
+ var InvalidSlice = class extends Schema.Class("InvalidSlice")({
168
+ /** The slice file. */
169
+ path: Schema.String,
170
+ /** Why it cannot be merged. */
171
+ reason: Schema.String
172
+ }) {};
173
+ /**
174
+ * The merged catalog, `catalog.json` in `catalogDir`'s parent: every slice
175
+ * in `catalogDir` united and sorted by entry `url`, with the running
176
+ * config's slice replaced by the entries it computes now when it declares
177
+ * any — so `check` compares against what a build would produce. A config
178
+ * that declares none merges its orphaned slice as it sits on disk, as every
179
+ * other config sees it, so whichever config sharing the directory builds
180
+ * last writes the identical file.
181
+ *
182
+ * @public
183
+ */
184
+ var MergedCatalogReport = class extends Schema.Class("MergedCatalogReport")({
185
+ /** The merged file: `catalog.json` in `catalogDir`'s parent. */
186
+ path: Schema.String,
187
+ /** How many entries the merged file holds (or would hold); `0` for an orphan. */
188
+ entries: Schema.Number,
189
+ /**
190
+ * `written`/`unchanged`/`would-write`/`held` as for the slice.
191
+ * `orphaned`: no slice remains but the merged file exists — stale under
192
+ * `check`, left in place under `build`. `blocked`: a URL or name conflict or an
193
+ * invalid slice leaves no merged catalog to trust, so none is written
194
+ * (both modes fail).
195
+ */
196
+ outcome: Schema.Literals([
197
+ "written",
198
+ "unchanged",
199
+ "would-write",
200
+ "held",
201
+ "orphaned",
202
+ "blocked"
203
+ ]),
204
+ /** Every slice file the merge reads — the running config's own included when it declares entries — sorted. */
205
+ slices: Schema.Array(Schema.String),
206
+ /**
207
+ * Every URL, then every name, advertised more than once; each kind
208
+ * sorted by its value in code-unit order; empty when none.
209
+ */
210
+ conflicts: Schema.Array(CatalogConflict),
211
+ /**
212
+ * Every OTHER slice file that cannot be read (a dangling symlink, a
213
+ * permission failure), is not JSON, or is not a catalog entry array —
214
+ * one carrying a key a catalog entry does not declare included — sorted;
215
+ * empty when none. A slice that vanished between listing and reading is
216
+ * skipped, not listed.
217
+ */
218
+ invalid: Schema.Array(InvalidSlice)
219
+ }) {};
220
+ /**
221
+ * The catalog's line in the {@link RunReport}: this config's slice and the
222
+ * merged catalog, each present only when there is something to report.
223
+ *
224
+ * @public
225
+ */
226
+ var CatalogReport = class extends Schema.Class("CatalogReport")({
227
+ /** Present when the config declares a catalog entry, or declares none but its slice exists (`orphaned`). */
228
+ slice: Schema.optionalKey(CatalogSliceReport),
229
+ /** Present when any slice contributes, or none does but the merged file exists (`orphaned`). */
230
+ merged: Schema.optionalKey(MergedCatalogReport)
231
+ }) {};
232
+ const JsonSchemaReport = Schema.toEncoded(Schema.Struct({
233
+ ...SchemaReport.fields,
234
+ frozen: Schema.optionalKey(SchemaReport.fields.frozen)
235
+ }));
236
+ const JsonMergedReport = Schema.toEncoded(Schema.Struct({
237
+ ...MergedCatalogReport.fields,
238
+ conflicts: Schema.optionalKey(MergedCatalogReport.fields.conflicts),
239
+ invalid: Schema.optionalKey(MergedCatalogReport.fields.invalid)
240
+ }));
241
+ const JsonDocument = Schema.Struct({
242
+ mode: Schema.Literals(["build", "check"]),
243
+ configPath: Schema.String,
244
+ drift: Schema.Struct({
245
+ onDrift: Schema.Literals(["error", "warn"]),
246
+ policy: Schema.optionalKey(Schema.Literals([
247
+ "strict",
248
+ "semantic",
249
+ "allow"
250
+ ]))
251
+ }),
252
+ schemas: Schema.Array(JsonSchemaReport),
253
+ catalog: Schema.optionalKey(Schema.Struct({
254
+ slice: Schema.optionalKey(Schema.toEncoded(CatalogSliceReport)),
255
+ merged: Schema.optionalKey(JsonMergedReport)
256
+ })),
257
+ orphaned: Schema.optionalKey(Schema.Array(Schema.String)),
258
+ drifted: Schema.Boolean,
259
+ gateFailed: Schema.Boolean,
260
+ wrote: Schema.Boolean
261
+ });
262
+ const fromJsonDocument = (doc) => {
263
+ const { drift, schemas, catalog, ...rest } = doc;
264
+ return {
265
+ ...rest,
266
+ onDrift: drift.onDrift,
267
+ ...drift.policy !== void 0 ? { policy: drift.policy } : {},
268
+ schemas: schemas.map((schema) => ({
269
+ ...schema,
270
+ frozen: schema.frozen ?? []
271
+ })),
272
+ ...catalog !== void 0 ? { catalog: {
273
+ ...catalog.slice !== void 0 ? { slice: catalog.slice } : {},
274
+ ...catalog.merged !== void 0 ? { merged: {
275
+ ...catalog.merged,
276
+ conflicts: catalog.merged.conflicts ?? [],
277
+ invalid: catalog.merged.invalid ?? []
278
+ } } : {}
279
+ } } : {}
280
+ };
281
+ };
282
+ const toJsonDocument = (report) => {
283
+ const { onDrift, policy, schemas, catalog, ...rest } = report;
284
+ return {
285
+ ...rest,
286
+ drift: {
287
+ onDrift,
288
+ ...policy !== void 0 ? { policy } : {}
289
+ },
290
+ schemas: schemas.map(({ frozen, ...schema }) => ({
291
+ ...schema,
292
+ ...frozen.length > 0 ? { frozen } : {}
293
+ })),
294
+ ...catalog !== void 0 ? { catalog: {
295
+ ...catalog.slice !== void 0 ? { slice: catalog.slice } : {},
296
+ ...catalog.merged !== void 0 ? { merged: (({ conflicts, invalid, ...merged }) => ({
297
+ ...merged,
298
+ ...conflicts.length > 0 ? { conflicts } : {},
299
+ ...invalid.length > 0 ? { invalid } : {}
300
+ }))(catalog.merged) } : {}
301
+ } } : {}
302
+ };
303
+ };
304
+ /**
305
+ * The whole run, as a value: the renderers and the exit-code mapping read
306
+ * this and nothing else.
307
+ *
308
+ * @public
309
+ */
310
+ var RunReport = class RunReport extends Schema.Class("RunReport")({
311
+ mode: Schema.Literals(["build", "check"]),
312
+ configPath: Schema.String,
313
+ onDrift: Schema.Literals(["error", "warn"]),
314
+ policy: Schema.optionalKey(Schema.Literals([
315
+ "strict",
316
+ "semantic",
317
+ "allow"
318
+ ])),
319
+ /** One per config schema, in config order. */
320
+ schemas: Schema.Array(SchemaReport),
321
+ /** Absent when there is neither a slice nor a merged catalog to report. */
322
+ catalog: Schema.optionalKey(CatalogReport),
323
+ /**
324
+ * Every document sitting at a sibling shape of a path the config derives
325
+ * — the file an `appendVersion` flip or a `layout` change left behind
326
+ * under the old derived name — that no target, frozen version, catalog
327
+ * slice, or the merged catalog claims. `check` counts them stale; `build`
328
+ * reports and never deletes them (the tool may not have written them).
329
+ * Absent when none. In config order: schema by schema, the unversioned
330
+ * shape first, then each label's three other shapes.
331
+ */
332
+ orphaned: Schema.optionalKey(Schema.Array(Schema.String)),
333
+ /** At least one schema's verdict is `"drift"`. */
334
+ drifted: Schema.Boolean,
335
+ /** At least one schema failed its gate. */
336
+ gateFailed: Schema.Boolean,
337
+ /** At least one file was written. */
338
+ wrote: Schema.Boolean
339
+ }) {
340
+ /**
341
+ * The report as the CLI's `--format=json` document: `onDrift` and `policy`
342
+ * nest under `drift`, and an empty `frozen`, `conflicts` or `invalid` is left
343
+ * out. Decoding it gives back the same report, so a consumer of the CLI's
344
+ * stdout reads the class the MCP result encodes.
345
+ */
346
+ static Json = JsonDocument.pipe(Schema.decodeTo(RunReport, SchemaTransformation.transform({
347
+ decode: fromJsonDocument,
348
+ encode: toJsonDocument
349
+ })));
350
+ };
351
+
352
+ export { CatalogConflict, CatalogReport, CatalogSliceReport, DocumentDiff, InvalidSlice, LineDiffHunkSchema, LineDiffLineSchema, MergedCatalogReport, RunReport, SchemaReport };