@effected/schemastore 0.1.2 → 0.2.1

package/SchemaPipeline.js

@@ -0,0 +1,200 @@
+import { DocumentLint } from "./DocumentLint.js";
+import { SchemaFile } from "./SchemaFile.js";
+import { SchemaValidator } from "./SchemaValidator.js";
+import { StoreDocument } from "./StoreDocument.js";
+import { Effect, Schema } from "effect";
+
+//#region src/SchemaPipeline.ts
+/**
+* One problem found while emitting a target, from either gate, normalized
+* so a single policy predicate can judge both.
+*
+* `DocumentLint` findings keep their own severity; engine findings are
+* `"warning"` — a document the engine rejects is not advisory.
+*
+* @public
+*/
+var PipelineFinding = class extends Schema.Class("PipelineFinding")({
+	/** Which gate produced it. */
+	source: Schema.Literals(["lint", "validator"]),
+	/** `"warning"` blocks under the default policy; `"advisory"` does not. */
+	severity: Schema.Literals(["warning", "advisory"]),
+	/** The lint check's name, or the engine keyword, when one is named. */
+	check: Schema.optionalKey(Schema.String),
+	/** JSON pointer into the flat document (`""` is the root). */
+	path: Schema.String,
+	/** Human-readable explanation. */
+	message: Schema.String
+}) {
+	/**
+	* What to call this finding when rendering it: the check name when the
+	* gate named one, the gate itself otherwise.
+	*
+	* Engine findings do not always carry a keyword, so without this every
+	* consumer that logs findings writes the same `finding.check ?? …`
+	* fallback.
+	*/
+	get label() {
+		return this.check ?? this.source;
+	}
+};
+/**
+* Indicates that at least one target's findings blocked under the active
+* gating policy. Carries every blocking finding, so a caller renders one
+* report instead of discovering problems one run at a time.
+*
+* @public
+*/
+var SchemaGateError = class extends Schema.TaggedErrorClass()("SchemaGateError", {
+	/** The `$id` of the target that failed the gate. */
+	$id: Schema.String,
+	/** Every finding that blocked, in discovery order. */
+	findings: Schema.Array(PipelineFinding)
+}) {
+	get message() {
+		return `Schema "${this.$id}" failed its gate with ${this.findings.length} blocking finding(s)`;
+	}
+};
+const defaultBlocking = (finding) => finding.severity === "warning";
+const gather = (document, options) => Effect.gen(function* () {
+	const validator = yield* SchemaValidator;
+	const lint = DocumentLint.lint(document).map((finding) => PipelineFinding.make({
+		source: "lint",
+		severity: finding.severity === "warning" ? "warning" : "advisory",
+		check: finding.check,
+		path: finding.path,
+		message: finding.message
+	}));
+	const validation = (yield* validator.validate(document.toJson(), options?.validator)).map((finding) => PipelineFinding.make({
+		source: "validator",
+		severity: "warning",
+		path: finding.path,
+		message: finding.message,
+		...finding.keyword !== void 0 ? { check: finding.keyword } : {}
+	}));
+	return [...lint, ...validation];
+});
+const blockingFindings = (findings, options) => findings.filter(options?.blocking ?? defaultBlocking);
+const gate = (target, findings, options) => {
+	const blocking = blockingFindings(findings, options);
+	return blocking.length > 0 ? Effect.fail(SchemaGateError.make({
+		$id: target.$id,
+		findings: blocking
+	})) : Effect.void;
+};
+/**
+* The emit pipeline over a target manifest: generate, lint, validate, gate,
+* write — the loop every consumer of this package was writing by hand.
+*
+* Requires `SchemaFile` and `SchemaValidator` in `R`; provide
+* `SchemaFile.layer` and `SchemaValidator.layer` (plus a platform
+* `FileSystem` / `Path`) at the edge. Findings come back as **values**, so
+* the package never chooses your log wording — but the gating decision,
+* which is the part that must not silently differ between consumers, has
+* one default and one override point.
+*
+* @example
+* ```ts
+* import { SchemaFile, SchemaPipeline, SchemaTarget, SchemaValidator } from "@effected/schemastore";
+* import { NodeServices } from "@effect/platform-node";
+* import { Effect, Layer, Schema } from "effect";
+*
+* const targets = [
+*   SchemaTarget.make({
+*     schema: Schema.Struct({ name: Schema.String }),
+*     $id: "https://example.com/config.schema.json",
+*     path: "schemas/config.schema.json",
+*   }),
+* ];
+*
+* const program = SchemaPipeline.run(targets).pipe(
+*   Effect.provide(Layer.mergeAll(SchemaFile.layer, SchemaValidator.layer)),
+*   Effect.provide(NodeServices.layer),
+* );
+* ```
+*
+* @public
+*/
+var SchemaPipeline = class SchemaPipeline {
+	constructor() {}
+	/**
+	* Run every target: build its document, gather both gates' findings,
+	* fail with a {@link SchemaGateError} if any block, and write otherwise.
+	*
+	* Targets are processed in order and the run stops at the first gate
+	* failure — a document that fails its gate is not written, and neither
+	* are the targets after it.
+	*/
+	static run(targets, options) {
+		return Effect.gen(function* () {
+			const files = yield* SchemaFile;
+			const results = [];
+			for (const target of targets) {
+				const document = yield* StoreDocument.fromSchema(target.schema, { $id: target.$id });
+				const findings = yield* gather(document, options);
+				yield* gate(target, findings, options);
+				const { outcome, change } = yield* files.write(target.path, document, options?.write);
+				results.push({
+					$id: target.$id,
+					path: target.path,
+					outcome,
+					change,
+					findings
+				});
+			}
+			return results;
+		});
+	}
+	/**
+	* The same walk with **no writes** — the drift-check counterpart, for a
+	* CI job asserting the committed schemas are current.
+	*
+	* Unlike {@link SchemaPipeline.run} this is **total over the targets**:
+	* it never stops at a failing gate, and reports `blocked` per target
+	* instead of failing. Reporting is the job here, and a repo with three
+	* broken documents should learn that in one run rather than fixing them
+	* one run at a time. A blocked target is still never mistaken for clean
+	* drift — `blocked` says so explicitly.
+	*
+	* The error channel is left to the mechanisms that genuinely cannot
+	* produce a report (generation, serialization, the engine, the read).
+	*/
+	static check(targets, options) {
+		return Effect.gen(function* () {
+			const files = yield* SchemaFile;
+			const results = [];
+			for (const target of targets) {
+				const document = yield* StoreDocument.fromSchema(target.schema, { $id: target.$id });
+				const findings = yield* gather(document, options);
+				const { wouldWrite, change } = yield* files.check(target.path, document, options?.write);
+				results.push({
+					$id: target.$id,
+					path: target.path,
+					wouldWrite,
+					blocked: blockingFindings(findings, options).length > 0,
+					change,
+					findings
+				});
+			}
+			return results;
+		});
+	}
+	/**
+	* {@link SchemaPipeline.run} for a single target, answering its one
+	* result directly — so a caller with one target does not index into an
+	* array and prove to the type system that element zero exists.
+	*/
+	static runOne(target, options) {
+		return SchemaPipeline.run([target], options).pipe(Effect.map((results) => results[0]));
+	}
+	/**
+	* {@link SchemaPipeline.check} for a single target, answering its one
+	* result directly.
+	*/
+	static checkOne(target, options) {
+		return SchemaPipeline.check([target], options).pipe(Effect.map((results) => results[0]));
+	}
+};
+
+//#endregion
+export { PipelineFinding, SchemaGateError, SchemaPipeline };

package/SchemaTarget.js

@@ -7,20 +7,20 @@
 var SchemaTarget = class {
 	constructor() {}
 	/**
-	* Builds a target. `$id`, `name` and `path` must be non-empty — an
-	* empty identity is a wiring mistake and throws.
+	* Builds a target. `$id` and `path` must be non-empty — an empty
+	* identity is a wiring mistake and throws, as does an empty `name` when
+	* one is given. The `name`-with-`version` invariant is enforced by the
+	* overloads above; the runtime check remains for untyped callers.
 	*/
 	static make(options) {
-		for (const key of [
-			"$id",
-			"name",
-			"path"
-		]) if (options[key].length === 0) throw new Error(`SchemaTarget.make requires a non-empty "${key}"`);
+		for (const key of ["$id", "path"]) if (options[key].length === 0) throw new Error(`SchemaTarget.make requires a non-empty "${key}"`);
+		if (options.name !== void 0 && options.name.length === 0) throw new Error("SchemaTarget.make requires a non-empty \"name\" when one is given");
+		if (options.version !== void 0 && options.name === void 0) throw new Error("SchemaTarget.make requires a \"name\" when \"version\" is given (catalog naming is name-<version>.json)");
 		return {
 			schema: options.schema,
 			$id: options.$id,
-			name: options.name,
 			path: options.path,
+			...options.name !== void 0 ? { name: options.name } : {},
 			...options.version !== void 0 ? { version: options.version } : {}
 		};
 	}

package/SchemaValidator.js

@@ -1,4 +1,6 @@
+import { KeywordFamilies } from "./KeywordFamilies.js";
 import { Context, Effect, Layer, Schema } from "effect";
+import { Ajv } from "ajv";
 
 //#region src/SchemaValidator.ts
 /**
@@ -34,20 +36,41 @@ var ValidationFinding = class extends Schema.Class("ValidationFinding")({
 	/** The JSON Schema keyword the finding is about, when the engine names one. */
 	keyword: Schema.optionalKey(Schema.String)
 }) {};
+const collectDeclaredKeywords = (node, into, depth) => {
+	if (depth >= 256 || typeof node !== "object" || node === null) return;
+	if (Array.isArray(node)) {
+		for (const element of node) collectDeclaredKeywords(element, into, depth + 1);
+		return;
+	}
+	for (const [key, value] of Object.entries(node)) {
+		if (KeywordFamilies.isDeclared(key)) into.add(key);
+		collectDeclaredKeywords(value, into, depth + 1);
+	}
+};
+const findingFromAjvError = (error) => ValidationFinding.make({
+	path: error.instancePath,
+	message: error.message ?? "schema is not valid",
+	keyword: error.keyword
+});
 /** The default for an unstubbed {@link SchemaValidator.makeTest} member. */
 const notStubbed = (method) => () => Effect.die(/* @__PURE__ */ new Error(`SchemaValidator.makeTest: ${method}() was called but not stubbed — no honest default exists for a test double; pass a \`${method}\` override.`));
 /**
-* Contract for real-engine JSON Schema document validation — the seam
-* through which SchemaStore's own gate (ajv strict mode) reaches this
-* package without ajv ever entering its dependency graph.
+* Real-engine JSON Schema document validation, closed by default over ajv —
+* the engine SchemaStore's own gate is defined in terms of.
 *
-* This is a contract-only service: {@link SchemaValidator.noop} is the sole
-* implementation this package ships, and it validates nothing. The consumer
-* closes the seam with a real engine at the application edge — e.g. an ajv
-* adapter whose `validate` compiles the document with
-* `new Ajv({ strict: true, allErrors: true })` and answers compile failures
-* as findings. `DocumentLint` remains the owned, always-available
-* structural half of the validation story.
+* {@link SchemaValidator.layer} is the shipped implementation: provide it and
+* validation works, with no adapter to write. The service stays an interface
+* so a test can swap it ({@link SchemaValidator.layerTest}) or skip it
+* ({@link SchemaValidator.noop}), and so a consumer standardized on a
+* different engine can substitute one — but writing an adapter is no longer
+* the price of admission. `DocumentLint` remains the owned, engine-free
+* structural half of the validation story, and answers questions ajv does
+* not (SchemaStore's own hygiene conventions).
+*
+* The shipped layer registers every declared {@link KeywordFamilies} keyword
+* present in the document before compiling, so ajv strict mode does not
+* reject the language-server families `DocumentLint` deliberately allows —
+* one predicate governs both verdicts.
 *
 * @example
 * ```ts
@@ -59,7 +82,7 @@ const notStubbed = (method) => () => Effect.die(/* @__PURE__ */ new Error(`Schem
 *   return yield* validator.validate({ type: "object" });
 * });
 *
-* Effect.runPromise(Effect.provide(program, SchemaValidator.noop));
+* Effect.runPromise(Effect.provide(program, SchemaValidator.layer));
 * // => []
 * ```
 *
@@ -67,9 +90,45 @@ const notStubbed = (method) => () => Effect.die(/* @__PURE__ */ new Error(`Schem
 */
 var SchemaValidator = class SchemaValidator extends Context.Service()("@effected/schemastore/SchemaValidator") {
 	/**
-	* No-op default: `validate` always succeeds with no findings, never
-	* consulting an engine. A pure `Layer.succeed`, bound to a const so the
-	* layer memoizes by reference.
+	* The shipped ajv implementation — the default a consumer provides.
+	*
+	* `validate` checks the document against the Draft-07 meta-schema and
+	* then compiles it, reporting BOTH as {@link ValidationFinding} values:
+	* meta-schema failures keep ajv's structured `instancePath` and
+	* `keyword`, while a strict-mode rejection (which ajv raises by throwing
+	* at compile time) becomes a root-pathed finding. The error channel
+	* stays reserved for the engine failing as a mechanism.
+	*
+	* `strict` defaults to `true` — SchemaStore's gate. Each call builds its
+	* own ajv instance, so documents sharing an `$id` never collide.
+	*/
+	static layer = Layer.succeed(SchemaValidator, { validate: (document, options) => Effect.try({
+		try: () => {
+			const ajv = new Ajv({
+				strict: options?.strict ?? true,
+				allErrors: true
+			});
+			const declared = /* @__PURE__ */ new Set();
+			collectDeclaredKeywords(document, declared, 0);
+			for (const keyword of declared) ajv.addKeyword({ keyword });
+			if (!ajv.validateSchema(document)) return (ajv.errors ?? []).map(findingFromAjvError);
+			try {
+				ajv.compile(document);
+			} catch (cause) {
+				return [ValidationFinding.make({
+					path: "",
+					message: cause instanceof Error ? cause.message : String(cause)
+				})];
+			}
+			return [];
+		},
+		catch: (cause) => SchemaValidatorError.make({ cause })
+	}) });
+	/**
+	* No-op: `validate` always succeeds with no findings, never consulting an
+	* engine. A pure `Layer.succeed`, bound to a const so the layer memoizes
+	* by reference. Use it to switch validation off deliberately — for the
+	* real engine, provide {@link SchemaValidator.layer}.
 	*/
 	static noop = Layer.succeed(SchemaValidator, { validate: () => Effect.succeed([]) });
 	/**

package/SchemaVersioning.js

@@ -2,19 +2,11 @@ import { Effect, Option, Order, Result, Schema } from "effect";
 import { SemVer } from "@effected/semver";
 
 //#region src/SchemaVersioning.ts
-/**
-* SchemaStore version labels are dotted numerics with one to three
-* components and an optional prerelease — `1`, `1.2`, `1.2.3`,
-* `1.2-beta.1` — per the catalog's versioned-schema convention
-* (`agripparc-1.2.json`). They are deliberately NOT strict SemVer: most
-* real catalog labels are two-part. Leading zeros are rejected on every
-* numeric identifier — core components and numeric prerelease identifiers
-* alike (SemVer §9 semantics: `0` is legal, `01` is not, alphanumerics
-* like `0abc` are) — so no two distinct labels can collide under numeric
-* ordering, and every accepted label survives the SemVer pad the ordering
-* performs (see `orderingKey`).
-*/
-const VERSION_PATTERN = /^(0|[1-9]\d*)(\.(0|[1-9]\d*)){0,2}(-(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?$/;
+const isVersionLabel = (input) => {
+	if (!SemVer.isValid(input)) return false;
+	const parsed = SemVer.parseResult(input);
+	return Result.isSuccess(parsed) && parsed.success.build.length === 0;
+};
 /**
 * Indicates that a string is not a valid SchemaStore version label.
 *
@@ -30,22 +22,23 @@ input: Schema.String }) {
 	}
 };
 /**
-* A SchemaStore version label: a branded string validated against the
-* catalog's version grammar (`major[.minor[.patch]][-prerelease]`). The
-* label round-trips verbatim into file names and catalog `versions` keys;
-* ordering pads it to a full SemVer internally (see
-* {@link SchemaVersioning.Order}).
+* A schema version label: a branded string holding a **full three-component
+* SemVer** — `major.minor.patch` with an optional prerelease, validated by
+* `@effected/semver` itself. Build metadata is rejected (see below).
+*
+* `1.2` and `1` are NOT accepted, though SchemaStore's own corpus uses such
+* labels: requiring all three components makes a label unambiguous to split
+* back out of `<name>-<version>.json` or its URL, which is what consumers
+* do with it. The file-name convention around the label stays SchemaStore's.
+*
+* The label round-trips verbatim into file names and catalog `versions`
+* keys; ordering parses it directly (see {@link SchemaVersioning.Order}).
 *
 * @public
 */
-const SchemaVersion = Schema.String.check(Schema.isPattern(VERSION_PATTERN)).pipe(Schema.brand("SchemaVersion"));
+const SchemaVersion = Schema.String.check(Schema.makeFilter((value) => isVersionLabel(value) ? void 0 : "must be a full major.minor.patch SemVer label")).pipe(Schema.brand("SchemaVersion"));
 const orderingKey = (label) => {
-	const hyphen = label.indexOf("-");
-	const core = hyphen === -1 ? label : label.slice(0, hyphen);
-	const prerelease = hyphen === -1 ? "" : label.slice(hyphen);
-	const parts = core.split(".");
-	while (parts.length < 3) parts.push("0");
-	const result = SemVer.parseResult(`${parts.join(".")}${prerelease}`);
+	const result = SemVer.parseResult(label);
 	if (Result.isFailure(result)) throw new Error(`SchemaVersion ordering invariant violated for label "${label}"`);
 	return result.success;
 };
@@ -59,11 +52,12 @@ const joinUrl = (baseUrl, file) => {
 };
 /**
 * Both SchemaStore catalog modes as pure derivations: unversioned (a plain
-* `name.json` file, `url` only) and versioned (`name-<version>.json` files,
-* a `versions` map, and `url` pointing at the latest version).
+* `name.json` file, `url` only) and versioned (`name-<version>.json` files
+* — SchemaStore's own suffix convention — a `versions` map, and `url`
+* pointing at the latest version).
 *
-* Version ordering follows SemVer precedence over labels padded to three
-* components, so `1.10` sorts above `1.9` and `2-beta` below `2`.
+* Version labels are full three-component SemVer, so ordering is plain
+* SemVer precedence: `1.10.0` above `1.9.0`, `2.0.0-beta` below `2.0.0`.
 *
 * @public
 */
@@ -74,7 +68,7 @@ var SchemaVersioning = class SchemaVersioning {
 	* {@link SchemaVersioning.parse} is the same check behind a span.
 	*/
 	static parseResult(input) {
-		return VERSION_PATTERN.test(input) ? Result.succeed(input) : Result.fail(InvalidSchemaVersionError.make({ input }));
+		return isVersionLabel(input) ? Result.succeed(input) : Result.fail(InvalidSchemaVersionError.make({ input }));
 	}
 	/**
 	* Effect form of {@link SchemaVersioning.parseResult}, adding only the
@@ -83,9 +77,9 @@ var SchemaVersioning = class SchemaVersioning {
 	*/
 	static parse = Effect.fn("SchemaVersioning.parse")((input) => Effect.fromResult(SchemaVersioning.parseResult(input)));
 	/**
-	* `Order` instance over version labels: SemVer precedence after padding
-	* missing components with zeros. `1.10` sorts above `1.9` (numeric, not
-	* lexical) and `2-beta` below `2` (prerelease precedence).
+	* `Order` instance over version labels: plain SemVer precedence.
+	* `1.10.0` sorts above `1.9.0` (numeric, not lexical) and `2.0.0-beta`
+	* below `2.0.0` (prerelease precedence).
 	*/
 	static Order = Order.make((a, b) => SemVer.Order(orderingKey(a), orderingKey(b)));
 	/**
@@ -123,16 +117,13 @@ var SchemaVersioning = class SchemaVersioning {
 	* a contradiction (versioned mode with no versions) and throws — pass
 	* `undefined` for the unversioned mode.
 	*
-	* Labels are inserted in ascending {@link SchemaVersioning.Order}, but
-	* the SchemaStore catalog format requires `versions` to be a JSON
-	* *object*, and JavaScript enumerates array-index-like keys first: a
-	* bare-major label (`"2"`) always enumerates — and therefore
-	* serializes — before every dotted label, regardless of insertion. The
-	* resulting enumeration order is: bare-major labels ascending
-	* numerically, then all other labels ascending. For label sets with no
-	* bare majors this is fully ascending; mixed sets interleave, so
-	* consumers must derive ordering from the labels themselves (as
-	* {@link SchemaVersioning.latest} does), never from key position.
+	* Labels are inserted in ascending {@link SchemaVersioning.Order} and
+	* stay that way on serialization. Requiring three components is what
+	* buys this: JavaScript enumerates array-index-like keys first, so the
+	* old grammar's bare-major label (`"2"`) jumped ahead of every dotted
+	* one regardless of insertion order. No SemVer label is integer-like,
+	* so that hazard is gone. Deriving ordering from the labels themselves
+	* (as {@link SchemaVersioning.latest} does) is still the robust read.
 	*/
 	static catalogUrls(options) {
 		const { baseUrl, name, versions } = options;

package/StoreDocument.js

@@ -79,6 +79,36 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 	/** The definitions pool, emitted under `$defs`. */
 	defs: Schema.Record(Schema.String, Schema.Unknown)
 }) {
+	/**
+	* Builds a Draft-07 document from its parts, filling `$schema` with
+	* {@link DRAFT_07_META_SCHEMA}.
+	*
+	* `fromSchema` sets the meta-schema unconditionally; hand-building a
+	* value with `make` otherwise means importing the constant just to
+	* repeat what the package already knows. `$schema` stays a real field
+	* rather than a defaulted one — it declares the document's dialect, and
+	* a document that does not say which dialect it is written in is worse
+	* than one that repeats itself — so this is a constructor, not a
+	* default.
+	*
+	* @example
+	* ```ts
+	* import { StoreDocument } from "@effected/schemastore";
+	*
+	* const document = StoreDocument.draft07({
+	*   $id: "https://example.com/config.schema.json",
+	*   root: { type: "object" },
+	* });
+	* ```
+	*/
+	static draft07(options) {
+		return StoreDocument.make({
+			$schema: DRAFT_07_META_SCHEMA,
+			$id: options.$id,
+			root: options.root,
+			defs: options.defs ?? {}
+		});
+	}
 	/**
 	* Builds the document for an Effect Schema source. Pure and
 	* synchronous — the primitive form; {@link StoreDocument.fromSchema} is