@effected/engine 0.11.0 → 0.13.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/schema.d.ts ADDED
@@ -0,0 +1,1084 @@
1
+ import { CanonicalJsonError, DriftTolerance, DriftVerdict, InstanceValidator, InstanceValidatorError, OnDrift, PipelineFinding, SchemaConversionError, SchemaFile, SchemaFileReadError, SchemaFileWriteError, SchemaValidator, SchemaValidatorError, SchemastoreConfig, UndeclaredAnnotationKeyError, WriteChange } from "@effected/schemastore";
2
+ import { Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
3
+ /**
4
+ * The shipped `InstanceValidator` implementation: the same ajv strict-mode
5
+ * setup `AjvValidator` gates documents with — the declared `KeywordFamilies`
6
+ * keywords and the standard `ajv-formats` vocabulary registered, through the
7
+ * one shared `makeAjv` — pointed at a payload instance instead of the
8
+ * meta-schema.
9
+ *
10
+ * @remarks
11
+ * Lives in the tool, not the library, for the same reason `AjvValidator`
12
+ * does: `@effected/schemastore` owns the `InstanceValidator` contract and
13
+ * its doubles, an application that imports it at runtime never pulls an
14
+ * engine, and `effected schema validate` composes this layer at its edge. It is
15
+ * exported for a program that validates payloads itself and wants the same
16
+ * verdict the command gives — a document the `check` gate admits always compiles
17
+ * here, so the two engines cannot drift.
18
+ *
19
+ * `validate` compiles the document and runs the instance against it. An
20
+ * instance the document rejects answers `InstanceFinding` values — ajv's
21
+ * structured `instancePath` pointer and `keyword` preserved, `allErrors`
22
+ * on, so one run reports every problem, not just the first. A document the
23
+ * engine cannot compile (a meta-schema failure, a strict-mode rejection, a
24
+ * declared keyword whose NAME ajv's grammar refuses) fails
25
+ * `InstanceValidatorError`: unlike `AjvValidator`, whose subject IS the
26
+ * document, this contract's subject is the instance, and a document that
27
+ * yields no verdict is the engine failing to run as a mechanism. The
28
+ * document's own gate is `SchemaValidator`'s job — `effected schema check` runs
29
+ * it before a document is ever published.
30
+ *
31
+ * `strict` defaults to `true` — SchemaStore's gate. Each call builds its own
32
+ * ajv instance, so documents sharing an `$id` never collide.
33
+ *
34
+ * @example
35
+ * ```ts
36
+ * import { InstanceValidator } from "@effected/schemastore";
37
+ * import { AjvInstanceValidator } from "@effected/engine/schema";
38
+ * import { Effect } from "effect";
39
+ *
40
+ * const program = Effect.gen(function* () {
41
+ * const validator = yield* InstanceValidator;
42
+ * return yield* validator.validate({ type: "object" }, { any: "payload" });
43
+ * });
44
+ *
45
+ * Effect.runPromise(Effect.provide(program, AjvInstanceValidator.layer));
46
+ * // => []
47
+ * ```
48
+ *
49
+ * @public
50
+ */
51
+ export declare class AjvInstanceValidator {
52
+ private constructor();
53
+ /** The engine, as an `InstanceValidator` layer. */
54
+ static readonly layer: Layer.Layer<InstanceValidator>;
55
+ }
56
+ /**
57
+ * The shipped `SchemaValidator` implementation: ajv strict mode over the
58
+ * Draft-07 meta-schema, with every declared `KeywordFamilies` keyword and
59
+ * the standard `ajv-formats` vocabulary registered.
60
+ *
61
+ * @remarks
62
+ * Lives in the tool, not the library, so `ajv` is a cost only the tool pays:
63
+ * `@effected/schemastore` owns the `SchemaValidator` contract and its doubles,
64
+ * an application that imports it at runtime never pulls an engine, and
65
+ * `SchemaRun` composes this layer at its edge. It is exported for a program that
66
+ * drives `SchemaPipeline` itself and wants the same verdict the command gives.
67
+ *
68
+ * `validate` checks the document against the Draft-07 meta-schema and then
69
+ * compiles it, reporting BOTH as `ValidationFinding` values: meta-schema
70
+ * failures keep ajv's structured `instancePath` and `keyword`, while a
71
+ * rejection ajv raises by *throwing* becomes a root-pathed finding — both a
72
+ * strict-mode compile failure and a declared keyword whose NAME ajv's own
73
+ * grammar (`/^[a-z_$][a-z0-9_$:-]*$/i`) refuses, such as an `x-ai-*` key
74
+ * carrying a dot or a space. The error channel stays reserved for the engine
75
+ * failing as a mechanism (`SchemaValidatorError`).
76
+ *
77
+ * The ajv setup is `internal/ajv.ts`'s `makeAjv`, shared with
78
+ * `AjvInstanceValidator` so a document this gate admits always compiles in
79
+ * the instance engine too — the two verdicts cannot drift.
80
+ *
81
+ * `strict` defaults to `true` — SchemaStore's gate. Each call builds its own
82
+ * ajv instance, so documents sharing an `$id` never collide. Registering the
83
+ * declared families keeps the engine's verdict consistent with
84
+ * `DocumentLint`'s through the same predicate, so the two cannot drift; the
85
+ * plugin's `formatMaximum` / `formatMinimum` limit keywords are deliberately
86
+ * NOT registered, because the lint answers those as unknown keywords.
87
+ * @example
88
+ * ```ts
89
+ * import { SchemaValidator } from "@effected/schemastore";
90
+ * import { AjvValidator } from "@effected/engine/schema";
91
+ * import { Effect } from "effect";
92
+ *
93
+ * const program = Effect.gen(function* () {
94
+ * const validator = yield* SchemaValidator;
95
+ * return yield* validator.validate({ type: "object" });
96
+ * });
97
+ *
98
+ * Effect.runPromise(Effect.provide(program, AjvValidator.layer));
99
+ * // => []
100
+ * ```
101
+ *
102
+ * @public
103
+ */
104
+ export declare class AjvValidator {
105
+ private constructor();
106
+ /** The engine, as a `SchemaValidator` layer. */
107
+ static readonly layer: Layer.Layer<SchemaValidator>;
108
+ }
109
+ declare const ConfigNotFoundError_base: Schema.Class<ConfigNotFoundError, Schema.TaggedStruct<"ConfigNotFoundError", {
110
+ /** The directories walked (discovery) or the one explicit path checked. */
111
+ readonly searched: Schema.$Array<Schema.String>;
112
+ }>, import("effect/Cause").YieldableError>;
113
+ /**
114
+ * No `schemastore.config.*` was found — by upward discovery from the working
115
+ * directory, or at the explicit path handed to `--config`.
116
+ *
117
+ * @public
118
+ */
119
+ export declare class ConfigNotFoundError extends ConfigNotFoundError_base {
120
+ get message(): string;
121
+ }
122
+ declare const ConfigLoadError_base: Schema.Class<ConfigLoadError, Schema.TaggedStruct<"ConfigLoadError", {
123
+ /** The config file that failed to load. */
124
+ readonly path: Schema.String;
125
+ /** Why it failed; the first line is the message, any remainder is detail such as a stack. */
126
+ readonly reason: Schema.String;
127
+ }>, import("effect/Cause").YieldableError>;
128
+ /**
129
+ * The config file exists but could not be turned into a `SchemastoreConfig`:
130
+ * the module threw on import, its default export is not a `defineConfig(...)`
131
+ * value, a field the pipeline reads is malformed (`name` not a simple file
132
+ * base name, `outputDir`/`catalogDir` not a string, `onDrift` or a schema's
133
+ * `drift` outside its literal set, a `schemas` element, its `target`,
134
+ * `catalog` or a `frozen` entry not shaped — the catalog decoded as a whole
135
+ * `CatalogEntry`, so a non-string `fileMatch` element or `versions` value
136
+ * fails too — every such issue reported at once, each as
137
+ * `<message> at <path>`), two outputs
138
+ * resolve to one absolute path, a document resolves into `catalogDir`, or
139
+ * `catalogDir` resolves to `outputDir` or to the merged catalog's path.
140
+ *
141
+ * @public
142
+ */
143
+ export declare class ConfigLoadError extends ConfigLoadError_base {
144
+ get message(): string;
145
+ }
146
+ /**
147
+ * A loaded config: where it came from and its contents with every relative
148
+ * `path` (`outputDir`, `catalogDir`, each schema's current target, and every
149
+ * frozen predecessor) resolved against `directory`.
150
+ *
151
+ * @public
152
+ */
153
+ interface LoadedConfig {
154
+ /** The absolute path of the config file. */
155
+ readonly path: string;
156
+ /** The directory containing the config file; every relative path in `config` is resolved against it. */
157
+ readonly directory: string;
158
+ /** The config, with its paths resolved. */
159
+ readonly config: SchemastoreConfig;
160
+ }
161
+ /**
162
+ * Options for {@link ConfigLoader.load}.
163
+ *
164
+ * @public
165
+ */
166
+ interface ConfigLoadOptions {
167
+ /** An explicit config path (`--config`), resolved against `cwd`. Skips discovery. */
168
+ readonly explicit?: string;
169
+ /** Where discovery starts and what `explicit` is resolved against. */
170
+ readonly cwd: string;
171
+ /** The last directory discovery checks; see {@link ConfigLoader.discover}. Does not bound `explicit`. */
172
+ readonly ceiling?: string;
173
+ /**
174
+ * The module importer. Defaults to a `jiti` importer that transpiles the
175
+ * consumer's TypeScript in place and evaluates it afresh on every call;
176
+ * injectable so tests can hand in a module value without touching disk.
177
+ */
178
+ readonly importModule?: (path: string) => Promise<unknown>;
179
+ }
180
+ /**
181
+ * Finds and loads a `schemastore.config.*` file.
182
+ *
183
+ * @remarks
184
+ * `discover` walks upward from a start directory checking
185
+ * {@link ConfigLoader.CONFIG_NAMES} in order at each level, so the nearest
186
+ * directory wins and, within one directory, `.ts` beats `.mjs`. `load` either
187
+ * takes the explicit path or discovers one, imports it, checks the default
188
+ * export is a `defineConfig(...)` value, and resolves relative paths against
189
+ * the config's directory.
190
+ *
191
+ * Each `load` evaluates the config, and the TypeScript and `.json` it imports,
192
+ * afresh. A `type: module` or CommonJS package keeps one instance across reloads.
193
+ * An imported `.mjs`, `.cjs` or `.js` under `type: module` stays cached by Node's
194
+ * ESM loader, and a sibling workspace package resolved to built `.js` under
195
+ * `type: module` is the same case: an edit to any of these is not seen until the
196
+ * process restarts, so restart a long-lived server to pick one up. An untyped
197
+ * package of ESM `.js` gets a new instance on each reload.
198
+ *
199
+ * @public
200
+ */
201
+ export declare class ConfigLoader {
202
+ private constructor();
203
+ /** The file names discovery looks for, in preference order. */
204
+ static readonly CONFIG_NAMES: ReadonlyArray<string>;
205
+ /**
206
+ * Walk upward from `start` until a config file is found; fails with the
207
+ * list of directories searched when none is.
208
+ *
209
+ * @remarks
210
+ * With a `ceiling`, the walk checks that directory and stops, comparing real
211
+ * paths so a link cannot walk past it. A server answering an agent passes one:
212
+ * a config is code, and on a checkout under a shared directory such as `/tmp`
213
+ * the one found above it is someone else's. A `start` outside the ceiling
214
+ * searches nothing rather than walking unbounded. Omitted, the walk runs to the
215
+ * filesystem root, which is right when a person ran the command.
216
+ */
217
+ static readonly discover: (start: string, ceiling?: string | undefined) => Effect.Effect<string, ConfigNotFoundError, FileSystem.FileSystem | Path.Path>;
218
+ /** This config's own catalog slice: `<catalogDir>/<name>.json`. */
219
+ static slicePath(config: SchemastoreConfig, path: Path.Path): string;
220
+ /**
221
+ * The merged catalog every config sharing `catalogDir` maintains:
222
+ * `catalog.json` in `catalogDir`'s parent (`<outputDir>/catalog.json` under
223
+ * the default `catalogDir`).
224
+ */
225
+ static mergedCatalogPath(config: SchemastoreConfig, path: Path.Path): string;
226
+ /**
227
+ * Resolve every relative `path` in the config (`outputDir`, `catalogDir`,
228
+ * each schema's current target, and every frozen predecessor) against
229
+ * `directory`; absolute paths are left alone. `defineConfig` already
230
+ * prefixes `outputDir` onto every target/frozen `path`, so resolving them
231
+ * against the config directory equals resolving against the resolved
232
+ * `outputDir`. The result keeps the `defineConfig` brand and the version
233
+ * stamp of the copy that produced it.
234
+ */
235
+ static readonly resolvePaths: (config: SchemastoreConfig, directory: string) => Effect.Effect<SchemastoreConfig, never, Path.Path>;
236
+ /** Locate, import and validate the config; see {@link ConfigLoadOptions}. */
237
+ static readonly load: (options: ConfigLoadOptions) => Effect.Effect<LoadedConfig, ConfigLoadError | ConfigNotFoundError, FileSystem.FileSystem | Path.Path>;
238
+ }
239
+ /**
240
+ * One line of a {@link DocumentDiff} hunk, mirroring `LineDiffLine` from
241
+ * `@effected/source`, which stays free of any dependency.
242
+ *
243
+ * @public
244
+ */
245
+ export declare const LineDiffLineSchema: Schema.Struct<{
246
+ readonly kind: Schema.Literals<readonly ["context", "add", "remove"]>;
247
+ readonly text: Schema.String;
248
+ /** 1-based line in the old text; absent on an `add`. */
249
+ readonly oldLine: Schema.optionalKey<Schema.Number>;
250
+ /** 1-based line in the new text; absent on a `remove`. */
251
+ readonly newLine: Schema.optionalKey<Schema.Number>;
252
+ /** Set on a line that is the last of its text and has no terminating newline. */
253
+ readonly noNewline: Schema.optionalKey<Schema.Literal<true>>;
254
+ }>;
255
+ /**
256
+ * One {@link DocumentDiff} hunk, mirroring `LineDiffHunk` from `@effected/source`.
257
+ *
258
+ * @public
259
+ */
260
+ export declare const LineDiffHunkSchema: Schema.Struct<{
261
+ readonly oldStart: Schema.Number;
262
+ readonly oldLines: Schema.Number;
263
+ readonly newStart: Schema.Number;
264
+ readonly newLines: Schema.Number;
265
+ readonly lines: Schema.$Array<Schema.Struct<{
266
+ readonly kind: Schema.Literals<readonly ["context", "add", "remove"]>;
267
+ readonly text: Schema.String;
268
+ /** 1-based line in the old text; absent on an `add`. */
269
+ readonly oldLine: Schema.optionalKey<Schema.Number>;
270
+ /** 1-based line in the new text; absent on a `remove`. */
271
+ readonly newLine: Schema.optionalKey<Schema.Number>;
272
+ /** Set on a line that is the last of its text and has no terminating newline. */
273
+ readonly noNewline: Schema.optionalKey<Schema.Literal<true>>;
274
+ }>>;
275
+ }>;
276
+ declare const DocumentDiff_base: Schema.Class<DocumentDiff, Schema.Struct<{
277
+ /** The hunks, for a consumer that draws its own diff. */
278
+ readonly hunks: Schema.$Array<Schema.Struct<{
279
+ readonly oldStart: Schema.Number;
280
+ readonly oldLines: Schema.Number;
281
+ readonly newStart: Schema.Number;
282
+ readonly newLines: Schema.Number;
283
+ readonly lines: Schema.$Array<Schema.Struct<{
284
+ readonly kind: Schema.Literals<readonly ["context", "add", "remove"]>;
285
+ readonly text: Schema.String;
286
+ /** 1-based line in the old text; absent on an `add`. */
287
+ readonly oldLine: Schema.optionalKey<Schema.Number>;
288
+ /** 1-based line in the new text; absent on a `remove`. */
289
+ readonly newLine: Schema.optionalKey<Schema.Number>;
290
+ /** Set on a line that is the last of its text and has no terminating newline. */
291
+ readonly noNewline: Schema.optionalKey<Schema.Literal<true>>;
292
+ }>>;
293
+ }>>;
294
+ /** The same hunks as git-style unified text. */
295
+ readonly unified: Schema.String;
296
+ }>, {}>;
297
+ /**
298
+ * What differs between a document on disk and the generated one, line by line.
299
+ *
300
+ * @remarks
301
+ * Both sides are in the kit's canonical JSON layout, so hunk line numbers refer
302
+ * to that form, which is byte-identical to the file in a tab-indented repo. A
303
+ * document that does not parse diffs as its raw text, and a missing one as all
304
+ * additions.
305
+ *
306
+ * @public
307
+ */
308
+ export declare class DocumentDiff extends DocumentDiff_base {}
309
+ /**
310
+ * What the run did with one schema.
311
+ *
312
+ * - `written` / `unchanged` — the `build` outcomes when the run wrote.
313
+ * - `would-write` — `check` mode: a build would touch the file.
314
+ * - `drift` — the drift policy refused it (and, under `onDrift: "error"`,
315
+ * held everything else).
316
+ * - `held` — the run wrote nothing because ANOTHER schema failed its gate
317
+ * or drifted under `onDrift: "error"`; this one was clean and would
318
+ * otherwise have been written. Reported by both modes: `check` reports
319
+ * what `build` would do, so it holds the same schemas a build holds.
320
+ * - `gate-failed` — a lint warning or engine finding blocked it.
321
+ *
322
+ * @public
323
+ */
324
+ type SchemaOutcome = "written" | "unchanged" | "would-write" | "drift" | "held" | "gate-failed";
325
+ declare const SchemaReport_base: Schema.Class<SchemaReport, Schema.Struct<{
326
+ readonly $id: Schema.String;
327
+ readonly path: Schema.String;
328
+ /** The schema's key in the config. */
329
+ readonly name: Schema.String;
330
+ readonly version: Schema.optionalKey<Schema.brand<Schema.String, "SchemaVersion">>;
331
+ readonly published: Schema.Boolean;
332
+ /** What differs between the on-disk document and the generated one. */
333
+ readonly change: Schema.Literals<readonly ["none", "annotations", "contract", "created"]>;
334
+ /** The drift policy's verdict; a written schema under `onDrift: "warn"` keeps `"drift"`. */
335
+ readonly verdict: Schema.Literals<readonly ["write", "drift"]>;
336
+ /** The tolerance actually applied: this schema's own, or a flag's override over every schema. */
337
+ readonly policy: Schema.Literals<readonly ["strict", "semantic", "allow"]>;
338
+ readonly outcome: Schema.Literals<readonly ["written", "unchanged", "would-write", "drift", "held", "gate-failed"]>;
339
+ /** The label to publish under instead — set only for a `contract` change on a pinned (non-prerelease) versioned schema. */
340
+ readonly nextVersion: Schema.optionalKey<Schema.brand<Schema.String, "SchemaVersion">>;
341
+ /** Every OTHER advertised version this schema's frozen check verified. */
342
+ readonly frozen: Schema.$Array<Schema.brand<Schema.String, "SchemaVersion">>;
343
+ /** Every finding, blocking or not. */
344
+ readonly findings: Schema.$Array<typeof PipelineFinding>;
345
+ /** Present when `change` is not `none`. The report always carries it whole; a summary caps what it shows. */
346
+ readonly diff: Schema.optionalKey<typeof DocumentDiff>;
347
+ }>, {}>;
348
+ /**
349
+ * One schema's line in the {@link RunReport}.
350
+ *
351
+ * @public
352
+ */
353
+ export declare class SchemaReport extends SchemaReport_base {}
354
+ declare const CatalogSliceReport_base: Schema.Class<CatalogSliceReport, Schema.Struct<{
355
+ /** The slice file: `<catalogDir>/<name>.json`. */
356
+ readonly path: Schema.String;
357
+ /** How many entries the slice holds; `0` for an orphan. */
358
+ readonly entries: Schema.Number;
359
+ /**
360
+ * `held` mirrors {@link SchemaOutcome}: the run refused every write.
361
+ * `orphaned`: no schema declares a catalog but the slice exists — stale
362
+ * under `check`, reported and left in place under `build` (the tool may
363
+ * not have written it).
364
+ */
365
+ readonly outcome: Schema.Literals<readonly ["written", "unchanged", "would-write", "held", "orphaned"]>;
366
+ /**
367
+ * Present when no file matched `<name>.json` exactly and the volume
368
+ * resolved that exact path to the one listed file whose name matches it
369
+ * case-insensitively (a leftover `docs.json` for a config named `Docs`
370
+ * on a case-insensitive volume) — the on-disk path it claimed. Never set
371
+ * on a case-sensitive volume, where that file is another slice. On a
372
+ * case-insensitive volume two configs whose names differ only in case
373
+ * share, and overwrite, that one file.
374
+ */
375
+ readonly caseFoldedMatch: Schema.optionalKey<Schema.String>;
376
+ }>, {}>;
377
+ /**
378
+ * This config's own catalog slice, `<catalogDir>/<name>.json`: a bare
379
+ * SchemaStore catalog entry array holding every entry the config declares,
380
+ * rewritten wholesale — so a removed schema's entry drops out.
381
+ *
382
+ * @public
383
+ */
384
+ export declare class CatalogSliceReport extends CatalogSliceReport_base {}
385
+ /**
386
+ * One catalog URL or display name advertised more than once across the
387
+ * slices, discriminated by `kind`. The merged catalog refuses to pick a
388
+ * winner: for a URL, which entry a host serves would depend on which config
389
+ * built last; for a name, an editor or SchemaStore would show two entries
390
+ * it cannot tell apart. A name is compared over the entries the merge
391
+ * advertises — an entry that already lost its URL to another slice is
392
+ * reported once, as the URL conflict.
393
+ *
394
+ * @public
395
+ */
396
+ export declare const CatalogConflict: Schema.Union<readonly [Schema.Struct<{
397
+ readonly kind: Schema.Literal<"url">;
398
+ /** The entry `url` claimed more than once. */
399
+ readonly url: Schema.String;
400
+ /** Every slice file advertising it, sorted; a slice listed twice declares it twice itself. */
401
+ readonly slices: Schema.$Array<Schema.String>;
402
+ }>, Schema.Struct<{
403
+ readonly kind: Schema.Literal<"name">;
404
+ /** The entry `name` claimed more than once. */
405
+ readonly name: Schema.String;
406
+ /** Every slice file advertising it, sorted; a slice listed twice declares it twice itself. */
407
+ readonly slices: Schema.$Array<Schema.String>;
408
+ }>]>;
409
+ /**
410
+ * The type of a {@link (CatalogConflict:variable)}.
411
+ *
412
+ * @public
413
+ */
414
+ export type CatalogConflict = typeof CatalogConflict.Type;
415
+ declare const InvalidSlice_base: Schema.Class<InvalidSlice, Schema.Struct<{
416
+ /** The slice file. */
417
+ readonly path: Schema.String;
418
+ /** Why it cannot be merged. */
419
+ readonly reason: Schema.String;
420
+ }>, {}>;
421
+ /**
422
+ * One slice the merge could not use, and why: `unreadable: <reason>` (a
423
+ * dangling symlink, a permission failure), `not JSON`, or the decode issue
424
+ * itself — `Expected array` for a document that is not an array,
425
+ * `Expected no excess property at [0]["extra"]` for an entry carrying a key
426
+ * a catalog entry does not declare — one semicolon-separated clause per issue.
427
+ *
428
+ * @public
429
+ */
430
+ export declare class InvalidSlice extends InvalidSlice_base {}
431
+ declare const MergedCatalogReport_base: Schema.Class<MergedCatalogReport, Schema.Struct<{
432
+ /** The merged file: `catalog.json` in `catalogDir`'s parent. */
433
+ readonly path: Schema.String;
434
+ /** How many entries the merged file holds (or would hold); `0` for an orphan. */
435
+ readonly entries: Schema.Number;
436
+ /**
437
+ * `written`/`unchanged`/`would-write`/`held` as for the slice.
438
+ * `orphaned`: no slice remains but the merged file exists — stale under
439
+ * `check`, left in place under `build`. `blocked`: a URL or name conflict or an
440
+ * invalid slice leaves no merged catalog to trust, so none is written
441
+ * (both modes fail).
442
+ */
443
+ readonly outcome: Schema.Literals<readonly ["written", "unchanged", "would-write", "held", "orphaned", "blocked"]>;
444
+ /** Every slice file the merge reads — the running config's own included when it declares entries — sorted. */
445
+ readonly slices: Schema.$Array<Schema.String>;
446
+ /**
447
+ * Every URL, then every name, advertised more than once; each kind
448
+ * sorted by its value in code-unit order; empty when none.
449
+ */
450
+ readonly conflicts: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
451
+ readonly kind: Schema.Literal<"url">;
452
+ /** The entry `url` claimed more than once. */
453
+ readonly url: Schema.String;
454
+ /** Every slice file advertising it, sorted; a slice listed twice declares it twice itself. */
455
+ readonly slices: Schema.$Array<Schema.String>;
456
+ }>, Schema.Struct<{
457
+ readonly kind: Schema.Literal<"name">;
458
+ /** The entry `name` claimed more than once. */
459
+ readonly name: Schema.String;
460
+ /** Every slice file advertising it, sorted; a slice listed twice declares it twice itself. */
461
+ readonly slices: Schema.$Array<Schema.String>;
462
+ }>]>>;
463
+ /**
464
+ * Every OTHER slice file that cannot be read (a dangling symlink, a
465
+ * permission failure), is not JSON, or is not a catalog entry array —
466
+ * one carrying a key a catalog entry does not declare included — sorted;
467
+ * empty when none. A slice that vanished between listing and reading is
468
+ * skipped, not listed.
469
+ */
470
+ readonly invalid: Schema.$Array<typeof InvalidSlice>;
471
+ }>, {}>;
472
+ /**
473
+ * The merged catalog, `catalog.json` in `catalogDir`'s parent: every slice
474
+ * in `catalogDir` united and sorted by entry `url`, with the running
475
+ * config's slice replaced by the entries it computes now when it declares
476
+ * any — so `check` compares against what a build would produce. A config
477
+ * that declares none merges its orphaned slice as it sits on disk, as every
478
+ * other config sees it, so whichever config sharing the directory builds
479
+ * last writes the identical file.
480
+ *
481
+ * @public
482
+ */
483
+ export declare class MergedCatalogReport extends MergedCatalogReport_base {}
484
+ declare const CatalogReport_base: Schema.Class<CatalogReport, Schema.Struct<{
485
+ /** Present when the config declares a catalog entry, or declares none but its slice exists (`orphaned`). */
486
+ readonly slice: Schema.optionalKey<typeof CatalogSliceReport>;
487
+ /** Present when any slice contributes, or none does but the merged file exists (`orphaned`). */
488
+ readonly merged: Schema.optionalKey<typeof MergedCatalogReport>;
489
+ }>, {}>;
490
+ /**
491
+ * The catalog's line in the {@link RunReport}: this config's slice and the
492
+ * merged catalog, each present only when there is something to report.
493
+ *
494
+ * @public
495
+ */
496
+ export declare class CatalogReport extends CatalogReport_base {}
497
+ declare const RunReport_base: Schema.Class<RunReport, Schema.Struct<{
498
+ readonly mode: Schema.Literals<readonly ["build", "check"]>;
499
+ readonly configPath: Schema.String;
500
+ readonly onDrift: Schema.Literals<readonly ["error", "warn"]>;
501
+ readonly policy: Schema.optionalKey<Schema.Literals<readonly ["strict", "semantic", "allow"]>>;
502
+ /** One per config schema, in config order. */
503
+ readonly schemas: Schema.$Array<typeof SchemaReport>;
504
+ /** Absent when there is neither a slice nor a merged catalog to report. */
505
+ readonly catalog: Schema.optionalKey<typeof CatalogReport>;
506
+ /**
507
+ * Every document sitting at a sibling shape of a path the config derives
508
+ * — the file an `appendVersion` flip or a `layout` change left behind
509
+ * under the old derived name — that no target, frozen version, catalog
510
+ * slice, or the merged catalog claims. `check` counts them stale; `build`
511
+ * reports and never deletes them (the tool may not have written them).
512
+ * Absent when none. In config order: schema by schema, the unversioned
513
+ * shape first, then each label's three other shapes.
514
+ */
515
+ readonly orphaned: Schema.optionalKey<Schema.$Array<Schema.String>>;
516
+ /** At least one schema's verdict is `"drift"`. */
517
+ readonly drifted: Schema.Boolean;
518
+ /** At least one schema failed its gate. */
519
+ readonly gateFailed: Schema.Boolean;
520
+ /** At least one file was written. */
521
+ readonly wrote: Schema.Boolean;
522
+ }>, {}>;
523
+ /**
524
+ * The whole run, as a value: the renderers and the exit-code mapping read
525
+ * this and nothing else.
526
+ *
527
+ * @public
528
+ */
529
+ export declare class RunReport extends RunReport_base {
530
+ /**
531
+ * The report as the CLI's `--format=json` document: `onDrift` and `policy`
532
+ * nest under `drift`, and an empty `frozen`, `conflicts` or `invalid` is left
533
+ * out. Decoding it gives back the same report, so a consumer of the CLI's
534
+ * stdout reads the class the MCP result encodes.
535
+ */
536
+ static readonly Json: Schema.Codec<RunReport, unknown>;
537
+ }
538
+ declare const VersionMismatch_base: Schema.Class<VersionMismatch, Schema.Struct<{
539
+ /** The version of the copy of `@effected/schemastore` the tool was built against. */
540
+ readonly tool: Schema.String;
541
+ /** Every stamp that differs from `tool`. */
542
+ readonly found: Schema.$Array<Schema.Struct<{
543
+ /** What carries the stamp: `config`, or a schema's hosted identity. */
544
+ readonly where: Schema.String;
545
+ /** The stamped version. */
546
+ readonly version: Schema.String;
547
+ }>>;
548
+ /** Names both versions and how to align them. */
549
+ readonly message: Schema.String;
550
+ }>, {}>;
551
+ /**
552
+ * A config whose values came from a different `@effected/schemastore` than the
553
+ * one this tool was built against.
554
+ *
555
+ * @public
556
+ */
557
+ export declare class VersionMismatch extends VersionMismatch_base {}
558
+ declare const VersionMismatchError_base: Schema.Class<VersionMismatchError, Schema.TaggedStruct<"VersionMismatchError", {
559
+ /** The version of the copy of `@effected/schemastore` the tool was built against. */
560
+ readonly tool: Schema.String;
561
+ /** Every stamp that differs from `tool`. */
562
+ readonly found: Schema.$Array<Schema.Struct<{
563
+ /** What carries the stamp: `config`, or a schema's hosted identity. */
564
+ readonly where: Schema.String;
565
+ /** The stamped version. */
566
+ readonly version: Schema.String;
567
+ }>>;
568
+ /** Names both versions and how to align them. */
569
+ readonly message: Schema.String;
570
+ }>, import("effect/Cause").YieldableError>;
571
+ /**
572
+ * The run refused a version mismatch, before generating anything.
573
+ *
574
+ * @public
575
+ */
576
+ export declare class VersionMismatchError extends VersionMismatchError_base {}
577
+ /**
578
+ * Compares the `@effected/schemastore` versions stamped on a config's values
579
+ * with the version this tool was built against.
580
+ *
581
+ * @remarks
582
+ * The catalog normally keeps the two equal, but a partial bump can leave an older
583
+ * copy beside a newer one. A value from another copy is read only through
584
+ * `SchemastoreVersion.of`, because it may lack this copy's methods. A value with
585
+ * no stamp cannot be compared and is passed over, and so is `"0.0.0"` on either
586
+ * side, which is an unbuilt source run. Two copies at one version are
587
+ * indistinguishable, and are not the case this check targets.
588
+ *
589
+ * @public
590
+ */
591
+ export declare class VersionCheck {
592
+ private constructor();
593
+ /**
594
+ * The mismatch, or `Option.none()` when the stamps agree. `tool` defaults to
595
+ * this copy's `SchemastoreVersion.current`.
596
+ */
597
+ static inspect(config: SchemastoreConfig, tool?: string): Option.Option<VersionMismatch>;
598
+ }
599
+ /**
600
+ * Renders a {@link RunReport} for a terminal, a JSON consumer or a GitHub
601
+ * step summary.
602
+ *
603
+ * @public
604
+ */
605
+ export declare class Report {
606
+ private constructor();
607
+ /**
608
+ * stdout lines.
609
+ *
610
+ * @remarks
611
+ * The summary's `drift` count is the number of schemas whose VERDICT is
612
+ * `"drift"`, independent of `written`/`unchanged`: under
613
+ * `onDrift: "warn"` a drifting schema is written AND counted as drift,
614
+ * so the four counts need not sum to the schema total.
615
+ */
616
+ static human(report: RunReport): ReadonlyArray<string>;
617
+ /**
618
+ * stderr lines: one per drift written (or, under `check`, would be written)
619
+ * under `onDrift: "warn"`. Empty when the gate failed — nothing was (or
620
+ * would be) written, so there is no drift to warn about.
621
+ */
622
+ static warnings(report: RunReport): ReadonlyArray<string>;
623
+ /**
624
+ * One JSON document, stable key order: {@link RunReport.Json}'s encoding.
625
+ *
626
+ * @remarks
627
+ * A version mismatch the run went on past is not part of the report, so it is
628
+ * passed beside it and comes last, where `ValidateReport.Json` has it: an agent
629
+ * reading only stdout must see it. Without one the document is unchanged.
630
+ */
631
+ static json(report: RunReport, versionMismatch?: VersionMismatch): string;
632
+ /**
633
+ * The step-summary tables, then one fenced `diff` block per changed document,
634
+ * each capped; ends with a newline so a later append starts on its own line.
635
+ */
636
+ static markdown(report: RunReport): string;
637
+ }
638
+ declare const FrozenVersionMissingError_base: Schema.Class<FrozenVersionMissingError, Schema.TaggedStruct<"FrozenVersionMissingError", {
639
+ /** One entry per schema/version whose frozen file is missing or not a file. */
640
+ readonly missing: Schema.$Array<Schema.Struct<{
641
+ /** The schema's key in the config. */
642
+ readonly name: Schema.String;
643
+ /** The missing frozen version label. */
644
+ readonly version: Schema.String;
645
+ /** The path that does not exist. */
646
+ readonly path: Schema.String;
647
+ }>>;
648
+ }>, import("effect/Cause").YieldableError>;
649
+ /**
650
+ * Indicates that one or more schemas advertise a version label (via
651
+ * `ResolvedSchema.frozen`) whose file is missing on disk. Raised by
652
+ * {@link Runner.run} before anything is generated — a build must never
653
+ * publish a catalog pointing a frozen label at a 404. Every miss is
654
+ * collected and reported at once, not just the first.
655
+ *
656
+ * @public
657
+ */
658
+ export declare class FrozenVersionMissingError extends FrozenVersionMissingError_base {
659
+ get message(): string;
660
+ }
661
+ declare const FrozenVersionIdMismatchError_base: Schema.Class<FrozenVersionIdMismatchError, Schema.TaggedStruct<"FrozenVersionIdMismatchError", {
662
+ /** One entry per frozen file whose `$id` is not the derived one. */
663
+ readonly mismatched: Schema.$Array<Schema.Struct<{
664
+ /** The schema's key in the config. */
665
+ readonly name: Schema.String;
666
+ /** The frozen version label. */
667
+ readonly version: Schema.String;
668
+ /** The frozen file. */
669
+ readonly path: Schema.String;
670
+ /** The `$id` the config derives for this label. */
671
+ readonly expected: Schema.String;
672
+ /** The `$id` the file declares; absent when it declares none or does not parse. */
673
+ readonly actual: Schema.optionalKey<Schema.String>;
674
+ /** Why the file fails: a different `$id`, no `$id` at all, or text that is not JSON. */
675
+ readonly reason: Schema.Literals<readonly ["mismatch", "absent", "unparseable"]>;
676
+ }>>;
677
+ }>, import("effect/Cause").YieldableError>;
678
+ /**
679
+ * Indicates that one or more frozen files exist but do not declare the
680
+ * `$id` their `ResolvedSchema.frozen` entry derives — the file is
681
+ * absent an `$id`, declares a different one, or does not parse. Raised by
682
+ * {@link Runner.run} before anything is generated: a frozen document is
683
+ * the one file the derivation does not own, so it is the one place `$id`
684
+ * and the advertised URL can still disagree (a `baseUrl` change leaves
685
+ * every frozen file carrying the old host). Every mismatch is collected.
686
+ *
687
+ * @public
688
+ */
689
+ export declare class FrozenVersionIdMismatchError extends FrozenVersionIdMismatchError_base {
690
+ get message(): string;
691
+ }
692
+ declare const CatalogDirError_base: Schema.Class<CatalogDirError, Schema.TaggedStruct<"CatalogDirError", {
693
+ /** The `catalogDir` that could not be listed. */
694
+ readonly path: Schema.String;
695
+ /** Why, in words: `not a directory` for a file, `permission denied`, or the platform's own description. */
696
+ readonly reason: Schema.String;
697
+ }>, import("effect/Cause").YieldableError>;
698
+ /**
699
+ * `catalogDir` exists but cannot be listed — it is a file, or the listing
700
+ * failed (a permission failure, say). Every `*.json` file in `catalogDir` is
701
+ * a catalog slice, so without the listing there is no merged catalog to
702
+ * compute. Raised by {@link Runner.run} before anything is generated or
703
+ * written; a config problem, not a run outcome.
704
+ *
705
+ * @public
706
+ */
707
+ export declare class CatalogDirError extends CatalogDirError_base {
708
+ get message(): string;
709
+ }
710
+ /**
711
+ * What one schema's check established, which nothing about its siblings can
712
+ * change. Its final `outcome` can still become `held` when a sibling is refused,
713
+ * so that waits for {@link SchemaReport}.
714
+ *
715
+ * @public
716
+ */
717
+ interface SchemaChecked {
718
+ /** The schema's key in the config. */
719
+ readonly name: string;
720
+ /** What differs between the on-disk document and the generated one. */
721
+ readonly change: WriteChange;
722
+ /** The drift policy's verdict under the tolerance applied to this schema. */
723
+ readonly verdict: DriftVerdict;
724
+ /** Whether this schema's findings block a build. */
725
+ readonly blocked: boolean;
726
+ }
727
+ /**
728
+ * What {@link Runner.run} is asked to do.
729
+ *
730
+ * @public
731
+ */
732
+ interface RunOptions {
733
+ readonly mode: "build" | "check";
734
+ /** Where the config came from, echoed into the report. */
735
+ readonly configPath: string;
736
+ /** What a build does when it finds drift. */
737
+ readonly onDrift: OnDrift;
738
+ /** Present only when a flag forced one tolerance over every schema's own. */
739
+ readonly policy?: DriftTolerance;
740
+ /** Told as each schema's check finishes, before the next one starts. */
741
+ readonly onChecked?: (checked: SchemaChecked) => Effect.Effect<void>;
742
+ }
743
+ /**
744
+ * The shared `build` / `check` walk: verify every advertised frozen version
745
+ * exists, classify every current target through `DriftPolicy` over
746
+ * `SchemaPipeline.checkOne`, then write through `SchemaPipeline.run` only when
747
+ * nothing is refused.
748
+ *
749
+ * @remarks
750
+ * **The frozen check runs first, before anything is generated.** Every
751
+ * schema's `ResolvedSchema.frozen` versions are walked, and every miss
752
+ * is reported at once: a build fails typed with
753
+ * {@link FrozenVersionMissingError} listing every label with no file on disk
754
+ * — nothing is written — a catalog that points a label at a 404 is a worse
755
+ * failure than an early refusal. A file that is there is read, and must
756
+ * declare the `$id` its entry derives, else the run fails typed with
757
+ * {@link FrozenVersionIdMismatchError} (a different `$id`, none, or text
758
+ * that is not JSON) — a `baseUrl` change is a re-publish event for every
759
+ * frozen label, not a silent re-advertisement.
760
+ *
761
+ * **Drift is classified per schema, under that schema's own
762
+ * `ResolvedSchema.drift` tolerance — unless `options.policy` is set,
763
+ * in which case it overrides every schema's own for this run** (the `--drift`
764
+ * / `--force` flags). A build writes NOTHING when any schema fails its gate,
765
+ * or when any schema drifts under `onDrift: "error"` — a partial write would
766
+ * leave a repository half-bumped. Every otherwise-writable schema then
767
+ * reports `held`, so a reader sees why a clean schema was not written — in
768
+ * both modes, since `check` reports what `build` would do under the same
769
+ * flags. Both modes share one `SchemaFile`; the single `writing` predicate
770
+ * (`mode === "build" && !refused`) gates every write, schemas and the
771
+ * catalog files alike. Under `onDrift: "warn"` drifting schemas are written
772
+ * and keep their `"drift"` verdict for the renderer to shout about.
773
+ *
774
+ * **A document whose `change` is not `none` carries a {@link DocumentDiff}**,
775
+ * from the text the check read to the text a build writes, both in the kit's
776
+ * canonical layout. Its line numbers therefore refer to the canonical form,
777
+ * and a document that does not parse diffs as its raw text.
778
+ *
779
+ * **Every catalog entry the config declares lands in ONE slice file**,
780
+ * `<catalogDir>/<name>.json` — a bare SchemaStore catalog entry array,
781
+ * never one file per schema — serialized canonically, compared by parsed
782
+ * content against the file on disk, and rewritten wholesale only when
783
+ * different and only when the run is writing. When no schema declares one,
784
+ * no slice is written; a slice still on disk is reported `orphaned` (stale
785
+ * under `check`) and left in place — and still merged, so the merged
786
+ * catalog keeps advertising its entries until it is deleted by hand.
787
+ *
788
+ * **The merged catalog is the union of every slice in `catalogDir`**,
789
+ * written to `catalog.json` in `catalogDir`'s parent, sorted by entry
790
+ * `url`, and compared and written by the same rule. When the running
791
+ * config declares entries, its slice is replaced by the entries it
792
+ * computes now, so `check` compares against what a build would produce;
793
+ * when it declares none, its on-disk slice is merged as-is. The merge is
794
+ * therefore a pure function of disk plus the non-empty fresh entries, and
795
+ * whichever config sharing the directory builds last writes the identical
796
+ * file. A URL advertised by two
797
+ * slices, or a slice that is not JSON or not a catalog entry array, is
798
+ * reported and blocks the merged write (`blocked`) rather than being
799
+ * silently merged or dropped. With no slice file left in `catalogDir` and
800
+ * no entry declared, a merged file still on disk is `orphaned`.
801
+ * `catalogDir` is the one directory the Runner lists: every `*.json` file
802
+ * in it is a slice by construction. It is listed before anything is
803
+ * generated; one that is a file or cannot be listed fails typed with
804
+ * {@link CatalogDirError}, nothing written. The running config's own slice
805
+ * on disk is an exact `<name>.json` match, or — only when there is none,
806
+ * exactly one listed file case-folds to it, and the volume itself resolves
807
+ * the exact path to that file (a `stat` that succeeds, i.e. a
808
+ * case-insensitive volume) — that one file, reported as
809
+ * `CatalogSliceReport.caseFoldedMatch`. On a case-sensitive volume the
810
+ * variant is another slice: a case-only rename leftover blocks the merge on
811
+ * the first build like any other rename leftover.
812
+ *
813
+ * **A moved path leaves an orphan the derivation cannot see**: an
814
+ * `appendVersion` flip or a `layout` change renames a document's derived
815
+ * path, and the previously written file stays on disk under the old name —
816
+ * for a `published` label, its advertised URL keeps serving a stale
817
+ * document with no report. The derivation has exactly four shapes for a
818
+ * name and label (`<name>.json`, `<name>-<v>.json`, `<v>/<name>.json`,
819
+ * `<v>/<name>-<v>.json`), so both modes probe the sibling shapes of every
820
+ * label the config still knows and report each one that exists as a FILE
821
+ * and that no target, frozen version, catalog slice, or merged catalog claims in
822
+ * `RunReport.orphaned`. Nothing else on disk is looked at: an
823
+ * `outputDir` shared with another config, a deploy folder, or the
824
+ * repository root holds documents this config cannot tell from its own
825
+ * leftovers, so they are never reported. A `name` change is therefore not
826
+ * caught either — the old name is unknowable. Orphans are reported, never
827
+ * deleted: the tool may not have written them.
828
+ *
829
+ * @public
830
+ */
831
+ export declare class Runner {
832
+ private constructor();
833
+ static readonly run: (config: SchemastoreConfig, options: RunOptions) => Effect.Effect<RunReport, FrozenVersionMissingError | FrozenVersionIdMismatchError | CatalogDirError | SchemaConversionError | UndeclaredAnnotationKeyError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError | PlatformError.PlatformError, SchemaFile | SchemaValidator | FileSystem.FileSystem | Path.Path>;
834
+ }
835
+ declare const ConflictingFlagsError_base: Schema.Class<ConflictingFlagsError, Schema.TaggedStruct<"ConflictingFlagsError", {
836
+ readonly policy: Schema.String;
837
+ }>, import("effect/Cause").YieldableError>;
838
+ /**
839
+ * `--force` (shorthand for `--drift=allow`) was combined with an explicit
840
+ * `--drift` that is not `allow`. Contradictory, so refused as a usage
841
+ * error rather than silently resolving to `allow`.
842
+ *
843
+ * @public
844
+ */
845
+ export declare class ConflictingFlagsError extends ConflictingFlagsError_base {
846
+ get message(): string;
847
+ }
848
+ /**
849
+ * What one run was asked to do, as the flags or tool parameters said it.
850
+ *
851
+ * @public
852
+ */
853
+ interface SchemaRunInput {
854
+ readonly mode: "build" | "check";
855
+ /** An explicit config path, resolved against `cwd`; absent, discovery upward from `cwd`. */
856
+ readonly config?: string;
857
+ /** One tolerance over every schema's own. */
858
+ readonly drift?: DriftTolerance;
859
+ /** Overrides the config's `onDrift`. */
860
+ readonly onDrift?: OnDrift;
861
+ /** Sugar for `drift: "allow"`, and contradictory with any other `drift`. */
862
+ readonly force: boolean;
863
+ /** `"fail"` refuses a version mismatch; `"warn"` runs and carries it on the result. */
864
+ readonly versionMismatch: "fail" | "warn";
865
+ }
866
+ /**
867
+ * Progress through one run.
868
+ *
869
+ * @remarks
870
+ * `Started` precedes the walk and carries any version mismatch the run is going
871
+ * on past, so a front end can warn before a later failure loses it: an error from
872
+ * the walk does not carry it. `SchemaChecked` arrives as each schema's check
873
+ * finishes, before the next one starts, with what is known per schema. Whether a
874
+ * clean schema ends `held` depends on its siblings, so `SchemaDone`, the final
875
+ * state, follows the whole walk.
876
+ *
877
+ * @public
878
+ */
879
+ type SchemaProgress = {
880
+ readonly _tag: "Started";
881
+ readonly names: ReadonlyArray<string>;
882
+ readonly versionMismatch?: VersionMismatch;
883
+ } | ({
884
+ readonly _tag: "SchemaChecked";
885
+ } & SchemaChecked) | {
886
+ readonly _tag: "SchemaDone";
887
+ readonly report: SchemaReport;
888
+ };
889
+ /**
890
+ * What the process boundary supplies, and the test seams.
891
+ *
892
+ * @public
893
+ */
894
+ interface SchemaRunDeps {
895
+ /** Where config discovery starts and what an explicit path resolves against. */
896
+ readonly cwd: string;
897
+ /** The last directory discovery checks; omitted, the filesystem root. Set it when an agent, not a person, asked. */
898
+ readonly discoveryCeiling?: string;
899
+ /** The config module importer; omitted, `ConfigLoader`'s `jiti` default. */
900
+ readonly importModule?: (path: string) => Promise<unknown>;
901
+ /** The validator engine; omitted, `AjvValidator.layer`. */
902
+ readonly validator?: Layer.Layer<SchemaValidator>;
903
+ /** The instance-validation engine, which `validate` uses. */
904
+ readonly instanceValidator?: Layer.Layer<InstanceValidator>;
905
+ /** Told when the walk starts and of each schema's report. */
906
+ readonly onProgress?: (event: SchemaProgress) => Effect.Effect<void>;
907
+ }
908
+ declare const SchemaRunResult_base: Schema.Class<SchemaRunResult, Schema.Struct<{
909
+ readonly report: typeof RunReport;
910
+ readonly verdict: Schema.Literals<readonly ["ok", "gate-failed", "drift", "catalog-blocked", "stale"]>;
911
+ readonly versionMismatch: Schema.optionalKey<typeof VersionMismatch>;
912
+ }>, {}>;
913
+ /**
914
+ * One run's answer: the report, the verdict the front ends map to an exit code
915
+ * or return as data, and any version mismatch the run went on past.
916
+ *
917
+ * @public
918
+ */
919
+ export declare class SchemaRunResult extends SchemaRunResult_base {}
920
+ /**
921
+ * Runs one `build` or `check`.
922
+ *
923
+ * @remarks
924
+ * Before anything loads, `force` beside a `drift` other than `allow` fails
925
+ * {@link ConflictingFlagsError}. The version check runs right after the load and
926
+ * before anything is generated. A failing gate, refused drift, blocked catalog or
927
+ * stale tree is a verdict rather than a failure, so a front end can always show
928
+ * the report; the error channel holds a run that could not start or finish.
929
+ * `check` writes nothing: {@link Runner.run}'s one `writing` predicate decides
930
+ * that for documents, and appending the step summary is left to the CLI.
931
+ *
932
+ * @public
933
+ */
934
+ export declare class SchemaRun {
935
+ private constructor();
936
+ static readonly run: (input: SchemaRunInput, deps: SchemaRunDeps) => Effect.Effect<SchemaRunResult, ConflictingFlagsError | ConfigNotFoundError | ConfigLoadError | VersionMismatchError | FrozenVersionMissingError | FrozenVersionIdMismatchError | CatalogDirError | SchemaConversionError | UndeclaredAnnotationKeyError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError | SchemaFileWriteError | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path>;
937
+ }
938
+ declare const PayloadError_base: Schema.Class<PayloadError, Schema.TaggedStruct<"PayloadError", {
939
+ readonly path: Schema.String;
940
+ readonly reason: Schema.String;
941
+ }>, import("effect/Cause").YieldableError>;
942
+ /**
943
+ * The payload file could not be read or parsed: it does not exist, the
944
+ * filesystem refused it, or its contents are not JSON. Nothing was validated.
945
+ *
946
+ * @public
947
+ */
948
+ export declare class PayloadError extends PayloadError_base {
949
+ get message(): string;
950
+ }
951
+ declare const MissingSchemaRefError_base: Schema.Class<MissingSchemaRefError, Schema.TaggedStruct<"MissingSchemaRefError", {
952
+ readonly path: Schema.String;
953
+ }>, import("effect/Cause").YieldableError>;
954
+ /**
955
+ * The payload names no schema and none was given, so there is nothing to
956
+ * validate against. A usage error: the remedy is in how it was invoked.
957
+ *
958
+ * @public
959
+ */
960
+ export declare class MissingSchemaRefError extends MissingSchemaRefError_base {
961
+ get message(): string;
962
+ }
963
+ declare const SchemaResolutionError_base: Schema.Class<SchemaResolutionError, Schema.TaggedStruct<"SchemaResolutionError", {
964
+ readonly $ref: Schema.String;
965
+ readonly reason: Schema.String;
966
+ }>, import("effect/Cause").YieldableError>;
967
+ /**
968
+ * The schema reference resolved to no readable document: it is neither an
969
+ * existing file nor an identity any config schema derives (`$id`, a frozen
970
+ * `$id`/`url`, a catalog `url`), or the document it names could not be read or
971
+ * parsed.
972
+ *
973
+ * @public
974
+ */
975
+ export declare class SchemaResolutionError extends SchemaResolutionError_base {
976
+ get message(): string;
977
+ }
978
+ declare const SourcePoint_base: Schema.Class<SourcePoint, Schema.Struct<{
979
+ readonly file: Schema.String;
980
+ readonly line: Schema.Number;
981
+ readonly column: Schema.Number;
982
+ }>, {}>;
983
+ /**
984
+ * A place in a file. `line` and `column` are one-based, and `column` counts
985
+ * UTF-16 code units, as an editor does.
986
+ *
987
+ * @public
988
+ */
989
+ export declare class SourcePoint extends SourcePoint_base {}
990
+ declare const LocatedFinding_base: Schema.Class<LocatedFinding, Schema.Struct<{
991
+ /** A JSON pointer into the payload; `""` is the root. */
992
+ readonly path: Schema.String;
993
+ readonly message: Schema.String;
994
+ readonly keyword: Schema.optionalKey<Schema.String>;
995
+ readonly location: Schema.optionalKey<typeof SourcePoint>;
996
+ }>, {}>;
997
+ /**
998
+ * One way a payload fails its document, with where the offending value sits.
999
+ *
1000
+ * @remarks
1001
+ * `location` is omitted when the payload's tree could not be built. A pointer
1002
+ * that does not resolve, such as a missing required property's parent chain
1003
+ * ending early, points at the deepest node that does.
1004
+ *
1005
+ * @public
1006
+ */
1007
+ export declare class LocatedFinding extends LocatedFinding_base {}
1008
+ declare const ValidateReport_base: Schema.Class<ValidateReport, Schema.Struct<{
1009
+ /** The payload's resolved path. */
1010
+ readonly payload: Schema.String;
1011
+ /** The schema reference that was resolved. */
1012
+ readonly $ref: Schema.String;
1013
+ /** The resolved path of the document the payload was validated against. */
1014
+ readonly source: Schema.String;
1015
+ readonly valid: Schema.Boolean;
1016
+ readonly findings: Schema.$Array<typeof LocatedFinding>;
1017
+ /** Present when the config's values came from another `@effected/schemastore` and the run went on. */
1018
+ readonly versionMismatch: Schema.optionalKey<typeof VersionMismatch>;
1019
+ }>, {}>;
1020
+ /**
1021
+ * The answer to one `validate`. A payload that does not conform is
1022
+ * `valid: false`, an ordinary result.
1023
+ *
1024
+ * @public
1025
+ */
1026
+ export declare class ValidateReport extends ValidateReport_base {
1027
+ /**
1028
+ * The report as the CLI's `--format=json` document: `$ref` is `schema` and
1029
+ * `source` is `document`. Decoding it gives back the same report, so a consumer
1030
+ * of the CLI's stdout reads the class the MCP result encodes.
1031
+ */
1032
+ static readonly Json: Schema.Codec<ValidateReport, unknown>;
1033
+ }
1034
+ /**
1035
+ * What one `validate` was asked to do.
1036
+ *
1037
+ * @public
1038
+ */
1039
+ interface SchemaValidateInput {
1040
+ /** The payload file, resolved against `cwd`. */
1041
+ readonly payload: string;
1042
+ /** An explicit config path; used only when the reference is an identity, not a file. */
1043
+ readonly config?: string;
1044
+ /** The document: a file path or a config-derived identity; absent, the payload's own `$schema`. */
1045
+ readonly schema?: string;
1046
+ /** `"fail"` refuses a version mismatch; `"warn"` runs and carries it on the report. */
1047
+ readonly versionMismatch: "fail" | "warn";
1048
+ }
1049
+ /**
1050
+ * Validates one payload against a published schema document.
1051
+ *
1052
+ * @remarks
1053
+ * The reference (`schema`, else the payload's `$schema`) resolves file-first, then
1054
+ * against the config's derived identities, so only an identity loads the config
1055
+ * and only then is the version checked: `"fail"` refuses a mismatch and `"warn"`
1056
+ * carries it on the report. A `Started` event is told to `deps.onProgress` once
1057
+ * the config loads, carrying the mismatch, so a warn that is followed by a failure
1058
+ * can still be shown. A top-level string `$schema` on the payload is stripped
1059
+ * before validating unless the document declares it, and the rest goes verbatim.
1060
+ * Findings that do not conform are `valid: false`, never a failure. A leading BOM
1061
+ * is ignored, and `column` counts UTF-16 code units.
1062
+ *
1063
+ * @public
1064
+ */
1065
+ export declare class SchemaValidate {
1066
+ private constructor();
1067
+ static readonly run: (input: SchemaValidateInput, deps: SchemaRunDeps) => Effect.Effect<ValidateReport, PayloadError | MissingSchemaRefError | SchemaResolutionError | ConfigNotFoundError | ConfigLoadError | VersionMismatchError | InstanceValidatorError | PlatformError.PlatformError, FileSystem.FileSystem | Path.Path>;
1068
+ }
1069
+ /**
1070
+ * Appends a rendered {@link Report.markdown} document to `GITHUB_STEP_SUMMARY`.
1071
+ *
1072
+ * @public
1073
+ */
1074
+ export declare class StepSummary {
1075
+ private constructor();
1076
+ /**
1077
+ * `true` when appended; `false` when `GITHUB_STEP_SUMMARY` is unset or
1078
+ * empty, or when the read/write failed — a failure is logged at warning
1079
+ * and never fails the run it is reporting on.
1080
+ */
1081
+ static readonly append: (markdown: string) => Effect.Effect<boolean, never, FileSystem.FileSystem>;
1082
+ }
1083
+ export type { ConfigLoadOptions, LoadedConfig, RunOptions, SchemaChecked, SchemaOutcome, SchemaProgress, SchemaRunDeps, SchemaRunInput, SchemaValidateInput };
1084
+ //# sourceMappingURL=schema.d.ts.map