@effected/schemastore 0.1.0

package/SchemaFile.js

@@ -0,0 +1,119 @@
+import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
+
+//#region src/SchemaFile.ts
+/**
+* Indicates that a schema file could not be read from the filesystem (a
+* filesystem error other than not-found).
+*
+* @public
+*/
+var SchemaFileReadError = class extends Schema.TaggedErrorClass()("SchemaFileReadError", {
+	/** The path that could not be read. */
+	path: Schema.String,
+	/** The underlying filesystem failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Failed to read schema file from "${this.path}"`;
+	}
+};
+/**
+* Indicates that no schema file exists at the expected path. Carries its
+* own tag for `catchTag` routing.
+*
+* @public
+*/
+var SchemaFileNotFoundError = class extends Schema.TaggedErrorClass()("SchemaFileNotFoundError", { 
+/** The path where the schema file was expected. */
+path: Schema.String }) {
+	get message() {
+		return `Schema file not found at "${this.path}"`;
+	}
+};
+/**
+* Indicates that a schema file could not be written to the filesystem.
+* Narrowed to the filesystem failure only — a serialization failure
+* surfaces as its own `CanonicalJsonError`, never wrapped here.
+*
+* @public
+*/
+var SchemaFileWriteError = class extends Schema.TaggedErrorClass()("SchemaFileWriteError", {
+	/** The path that could not be written. */
+	path: Schema.String,
+	/** The underlying filesystem failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Failed to write schema file to "${this.path}"`;
+	}
+};
+/**
+* Reads and writes emitted schema documents over core `FileSystem` /
+* `Path` — the package's one IO surface. The layer requires those
+* services; provide `@effect/platform-node`'s `NodeFileSystem` / `NodePath`
+* (or a bun equivalent) at the application boundary.
+*
+* `write` is write-if-changed: serialization goes through the owned
+* `CanonicalJson` (equal documents serialize to equal bytes), so an
+* unchanged document never touches the file — a generator committed to a
+* repo does not churn mtimes, and its CI drift check is `read` + compare.
+*
+* @example
+* ```ts
+* import { SchemaFile, StoreDocument } from "@effected/schemastore";
+* import { NodeFileSystem, NodePath } from "@effect/platform-node";
+* import { Effect, Layer, Schema } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const files = yield* SchemaFile;
+*   const document = yield* StoreDocument.fromSchema(Schema.Struct({ name: Schema.String }), {
+*     $id: "https://example.com/config.schema.json",
+*   });
+*   return yield* files.write("schemas/config.schema.json", document);
+* }).pipe(
+*   Effect.provide(SchemaFile.layer),
+*   Effect.provide(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer)),
+* );
+* ```
+*
+* @public
+*/
+var SchemaFile = class SchemaFile extends Context.Service()("@effected/schemastore/SchemaFile") {
+	/** Build the service implementation from `FileSystem` / `Path` in context; use {@link SchemaFile.layer} to provide it. */
+	static make = Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		return {
+			read: Effect.fn("SchemaFile.read")(function* (target) {
+				return yield* fs.readFileString(target).pipe(Effect.mapError((cause) => cause.reason._tag === "NotFound" ? SchemaFileNotFoundError.make({ path: target }) : SchemaFileReadError.make({
+					path: target,
+					cause
+				})));
+			}),
+			write: Effect.fn("SchemaFile.write")(function* (target, document, options) {
+				const text = yield* Effect.fromResult(document.serializeResult(options));
+				if ((yield* fs.readFileString(target).pipe(Effect.catch((cause) => cause.reason._tag === "NotFound" ? Effect.succeed(void 0) : Effect.fail(SchemaFileReadError.make({
+					path: target,
+					cause
+				}))))) === text) return "unchanged";
+				yield* fs.makeDirectory(path.dirname(target), { recursive: true }).pipe(Effect.mapError((cause) => SchemaFileWriteError.make({
+					path: target,
+					cause
+				})));
+				yield* fs.writeFileString(target, text).pipe(Effect.mapError((cause) => SchemaFileWriteError.make({
+					path: target,
+					cause
+				})));
+				return "written";
+			})
+		};
+	});
+	/**
+	* The live layer. Requires core `FileSystem` / `Path`, provided by the
+	* consumer's platform implementation at the edge.
+	*/
+	static layer = Layer.effect(SchemaFile, SchemaFile.make);
+};
+
+//#endregion
+export { SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError };

package/SchemaTarget.js

@@ -0,0 +1,30 @@
+//#region src/SchemaTarget.ts
+/**
+* Constructors for `SchemaTarget` values.
+*
+* @public
+*/
+var SchemaTarget = class {
+	constructor() {}
+	/**
+	* Builds a target. `$id`, `name` and `path` must be non-empty — an
+	* empty identity is a wiring mistake and throws.
+	*/
+	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}"`);
+		return {
+			schema: options.schema,
+			$id: options.$id,
+			name: options.name,
+			path: options.path,
+			...options.version !== void 0 ? { version: options.version } : {}
+		};
+	}
+};
+
+//#endregion
+export { SchemaTarget };

package/SchemaValidator.js

@@ -0,0 +1,91 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+//#region src/SchemaValidator.ts
+/**
+* Indicates that the validation engine behind the {@link SchemaValidator}
+* contract failed as a *mechanism* — it could not run at all.
+*
+* By convention the error channel is reserved for exactly that: a document
+* that fails the engine's gate is a {@link ValidationFinding} list (a
+* value), never an error. Raised by implementations of
+* {@link SchemaValidatorShape.validate}.
+*
+* @public
+*/
+var SchemaValidatorError = class extends Schema.TaggedErrorClass()("SchemaValidatorError", { 
+/** The underlying engine failure, preserved structurally. */
+cause: Schema.Defect() }) {
+	get message() {
+		return "Schema validation engine failed";
+	}
+};
+/**
+* One problem a validation engine found with a document: a value in a
+* report, never an error channel — the consumer decides what a finding
+* gates.
+*
+* @public
+*/
+var ValidationFinding = class extends Schema.Class("ValidationFinding")({
+	/** JSON pointer into the flat document (`""` is the root schema). */
+	path: Schema.String,
+	/** Human-readable explanation from the engine. */
+	message: Schema.String,
+	/** The JSON Schema keyword the finding is about, when the engine names one. */
+	keyword: Schema.optionalKey(Schema.String)
+}) {};
+/** 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.
+*
+* 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.
+*
+* @example
+* ```ts
+* import { SchemaValidator } from "@effected/schemastore";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const validator = yield* SchemaValidator;
+*   return yield* validator.validate({ type: "object" });
+* });
+*
+* Effect.runPromise(Effect.provide(program, SchemaValidator.noop));
+* // => []
+* ```
+*
+* @public
+*/
+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.
+	*/
+	static noop = Layer.succeed(SchemaValidator, { validate: () => Effect.succeed([]) });
+	/**
+	* An in-memory double: stub only the members the test exercises; every
+	* other member **dies** with a defect naming itself. No member has an
+	* honest default — a fabricated clean pass would leak into consumer
+	* logic as fact (use {@link SchemaValidator.noop} when a test genuinely
+	* wants an always-clean validator).
+	*/
+	static makeTest = (overrides = {}) => ({
+		validate: notStubbed("validate"),
+		...overrides
+	});
+	/** {@link SchemaValidator.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(SchemaValidator, SchemaValidator.makeTest(overrides));
+};
+
+//#endregion
+export { SchemaValidator, SchemaValidatorError, ValidationFinding };

package/SchemaVersioning.js

@@ -0,0 +1,153 @@
+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-]*))*)?$/;
+/**
+* Indicates that a string is not a valid SchemaStore version label.
+*
+* Raised by {@link SchemaVersioning.parse}.
+*
+* @public
+*/
+var InvalidSchemaVersionError = class extends Schema.TaggedErrorClass()("InvalidSchemaVersionError", { 
+/** The raw input string that failed to parse. */
+input: Schema.String }) {
+	get message() {
+		return `Invalid schema version label: "${this.input}"`;
+	}
+};
+/**
+* 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}).
+*
+* @public
+*/
+const SchemaVersion = Schema.String.check(Schema.isPattern(VERSION_PATTERN)).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}`);
+	if (Result.isFailure(result)) throw new Error(`SchemaVersion ordering invariant violated for label "${label}"`);
+	return result.success;
+};
+const assertSimpleName = (name) => {
+	if (name.length === 0 || /[/\\\s]/.test(name)) throw new Error(`Schema name must be a non-empty simple file base name, got "${name}"`);
+};
+const joinUrl = (baseUrl, file) => {
+	let end = baseUrl.length;
+	while (end > 0 && baseUrl.charCodeAt(end - 1) === 47) end -= 1;
+	return `${baseUrl.slice(0, end)}/${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).
+*
+* Version ordering follows SemVer precedence over labels padded to three
+* components, so `1.10` sorts above `1.9` and `2-beta` below `2`.
+*
+* @public
+*/
+var SchemaVersioning = class SchemaVersioning {
+	constructor() {}
+	/**
+	* Parses a version label. Pure and synchronous — the primitive form;
+	* {@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 }));
+	}
+	/**
+	* Effect form of {@link SchemaVersioning.parseResult}, adding only the
+	* `SchemaVersioning.parse` span. Defined in terms of the `Result`
+	* primitive — synchronous callers can use that variant directly.
+	*/
+	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).
+	*/
+	static Order = Order.make((a, b) => SemVer.Order(orderingKey(a), orderingKey(b)));
+	/**
+	* The highest version label by {@link SchemaVersioning.Order}, or
+	* `Option.none()` for an empty collection.
+	*/
+	static latest(versions) {
+		return versions.length === 0 ? Option.none() : Option.some(versions.reduce((max, v) => SchemaVersioning.Order(v, max) > 0 ? v : max));
+	}
+	/**
+	* Derives the schema file name for a catalog name: `name.json`
+	* unversioned, `name-<version>.json` versioned.
+	*
+	* The name must be a simple file base name (no separators, no
+	* whitespace); anything else is a wiring mistake and throws.
+	*/
+	static fileName(name, version) {
+		assertSimpleName(name);
+		return version === void 0 ? `${name}.json` : `${name}-${version}.json`;
+	}
+	/**
+	* The canonical URL a schema file is hosted at: `baseUrl` joined with
+	* {@link SchemaVersioning.fileName}.
+	*/
+	static schemaUrl(baseUrl, name, version) {
+		return joinUrl(baseUrl, SchemaVersioning.fileName(name, version));
+	}
+	/**
+	* Assembles the `url`/`versions` half of a catalog entry.
+	*
+	* Omitting `versions` selects the unversioned mode (`url` only,
+	* pointing at the plain `name.json`). Providing them selects the
+	* versioned mode: the `versions` map carries every label, and `url`
+	* points at the latest version's file. An **empty** `versions` array is
+	* 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.
+	*/
+	static catalogUrls(options) {
+		const { baseUrl, name, versions } = options;
+		if (versions === void 0) return { url: SchemaVersioning.schemaUrl(baseUrl, name) };
+		if (versions.length === 0) throw new Error(`catalogUrls received an empty versions array for "${name}": pass undefined for the unversioned mode`);
+		const ascending = [...versions].sort(SchemaVersioning.Order);
+		const map = {};
+		for (const version of ascending) map[version] = SchemaVersioning.schemaUrl(baseUrl, name, version);
+		const newest = ascending[ascending.length - 1];
+		return {
+			url: SchemaVersioning.schemaUrl(baseUrl, name, newest),
+			versions: map
+		};
+	}
+};
+
+//#endregion
+export { InvalidSchemaVersionError, SchemaVersion, SchemaVersioning };

package/StoreDocument.js

@@ -0,0 +1,142 @@
+import { KeywordFamilies } from "./KeywordFamilies.js";
+import { AnnotationCarriers } from "./AnnotationCarriers.js";
+import { CanonicalJson } from "./CanonicalJson.js";
+import { Effect, JsonSchema, Result, Schema } from "effect";
+
+//#region src/StoreDocument.ts
+/**
+* The Draft-07 meta-schema URL SchemaStore documents declare as `$schema`.
+*
+* Deliberately carries the trailing `#` fragment: the SchemaStore corpus
+* (and the extraction source's committed files) use the fragment form,
+* where core's `JsonSchema.META_SCHEMA_URI_DRAFT_07` omits it.
+*
+* @public
+*/
+const DRAFT_07_META_SCHEMA = "http://json-schema.org/draft-07/schema#";
+/**
+* Indicates that an Effect Schema could not be converted into a SchemaStore
+* document — core's JSON Schema generation rejected the schema, or the
+* generated document nested past the hardening cap.
+*
+* Raised by {@link StoreDocument.fromSchema}. The `cause` carries the
+* underlying failure for the operator; calling code branches on the tag.
+*
+* @public
+*/
+var SchemaConversionError = class extends Schema.TaggedErrorClass()("SchemaConversionError", {
+	/** The `$id` of the document that failed to build. */
+	$id: Schema.String,
+	/** The underlying conversion failure. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Failed to build SchemaStore document "${this.$id}"`;
+	}
+};
+const DEFINITIONS_REF_PREFIX = /^#\/definitions(?=\/|$)/;
+var RewriteDepthExceeded = class {
+	_tag = "RewriteDepthExceeded";
+};
+const carry = (source, target) => {
+	const result = AnnotationCarriers.carryResult(source, target);
+	if (Result.isFailure(result)) throw result.failure;
+	return result.success;
+};
+const restoreDefsRefs = (node, depth) => {
+	if (depth >= 256) throw new RewriteDepthExceeded();
+	if (Array.isArray(node)) return node.map((item) => restoreDefsRefs(item, depth + 1));
+	if (typeof node === "object" && node !== null) {
+		const out = Object.create(null);
+		for (const [key, value] of Object.entries(node)) out[key] = key === "$ref" && typeof value === "string" ? value.replace(DEFINITIONS_REF_PREFIX, "#/$defs") : restoreDefsRefs(value, depth + 1);
+		return out;
+	}
+	return node;
+};
+/**
+* A SchemaStore-shaped Draft-07 JSON Schema document assembled from an
+* Effect Schema source: `$schema` (the Draft-07 meta-schema) + `$id` + the
+* root schema + the `$defs` pool.
+*
+* {@link StoreDocument.fromSchema} owns the whole pipeline: core's
+* `Schema.toJsonSchemaDocument` (Draft 2020-12), core's
+* `JsonSchema.toDocumentDraft07` lowering, the `#/definitions` →
+* `#/$defs` `$ref` rewrite the lowering makes necessary — so every `$ref`
+* in a built document already resolves against the `$defs` pool — and the
+* {@link AnnotationCarriers} re-graft, so annotated non-standard keyword
+* families ({@link KeywordFamilies}) survive into the built document. The
+* package owns assembly and publication shape, not a JSON Schema engine.
+*
+* @public
+*/
+var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
+	/** The meta-schema URL ({@link DRAFT_07_META_SCHEMA}). */
+	$schema: Schema.String,
+	/** The canonical `$id` URL. */
+	$id: Schema.String,
+	/** The root schema's keywords, without the definitions pool. */
+	root: Schema.Record(Schema.String, Schema.Unknown),
+	/** The definitions pool, emitted under `$defs`. */
+	defs: Schema.Record(Schema.String, Schema.Unknown)
+}) {
+	/**
+	* Builds the document for an Effect Schema source. Pure and
+	* synchronous — the primitive form; {@link StoreDocument.fromSchema} is
+	* the same pipeline behind a span.
+	*/
+	static fromSchemaResult(source, options) {
+		try {
+			const userIncludes = options.jsonSchema?.includeAnnotationKey;
+			const document = Schema.toJsonSchemaDocument(source, {
+				...options.jsonSchema,
+				includeAnnotationKey: (key) => KeywordFamilies.isDeclared(key) || userIncludes?.(key) === true
+			});
+			const lowered = JsonSchema.toDocumentDraft07(document);
+			const root = carry(document.schema, restoreDefsRefs(lowered.schema, 0));
+			const defs = Object.create(null);
+			for (const [name, definition] of Object.entries(lowered.definitions)) defs[name] = carry(document.definitions[name], restoreDefsRefs(definition, 1));
+			return Result.succeed(StoreDocument.make({
+				$schema: DRAFT_07_META_SCHEMA,
+				$id: options.$id,
+				root,
+				defs
+			}));
+		} catch (cause) {
+			return Result.fail(SchemaConversionError.make({
+				$id: options.$id,
+				cause
+			}));
+		}
+	}
+	/**
+	* Effect form of {@link StoreDocument.fromSchemaResult}, adding only the
+	* `StoreDocument.fromSchema` span. Defined in terms of the `Result`
+	* primitive — synchronous callers can use that variant directly.
+	*/
+	static fromSchema = Effect.fn("StoreDocument.fromSchema")((source, options) => Effect.fromResult(StoreDocument.fromSchemaResult(source, options)));
+	/**
+	* The flat SchemaStore publication shape: `$schema`, `$id`, the root
+	* schema's keywords spread at the top level, then the `$defs` pool.
+	* `$defs` is omitted when the pool is empty (a deliberate divergence
+	* from the extraction source, which always emitted the key).
+	*/
+	toJson() {
+		return {
+			$schema: this.$schema,
+			$id: this.$id,
+			...this.root,
+			...Object.keys(this.defs).length > 0 ? { $defs: this.defs } : {}
+		};
+	}
+	/**
+	* Canonical JSON text of {@link StoreDocument.toJson}, via
+	* {@link CanonicalJson.serializeResult} — one serializer, so the
+	* document and any consumer-serialized value cannot drift.
+	*/
+	serializeResult(options) {
+		return CanonicalJson.serializeResult(this.toJson(), options);
+	}
+};
+
+//#endregion
+export { DRAFT_07_META_SCHEMA, SchemaConversionError, StoreDocument };