@effected/schemastore 0.9.1 → 0.11.0

package/SchemastoreConfig.js

@@ -1,42 +1,147 @@
 import { SchemaVersioning } from "./SchemaVersioning.js";
 import { CatalogEntry } from "./CatalogEntry.js";
 import { DriftPolicy } from "./DriftPolicy.js";
-import { Schema } from "effect";
+import { SchemaTarget } from "./SchemaTarget.js";
+import { Option, Predicate, Result, Schema } from "effect";
 
 //#region src/SchemastoreConfig.ts
 const ConfigBrand = Symbol.for("@effected/schemastore/SchemastoreConfig");
-const DriftSchema = Schema.Struct({
-	policy: Schema.optionalKey(Schema.Literals([
-		"strict",
-		"semantic",
-		"allow"
-	])),
-	onDrift: Schema.optionalKey(Schema.Literals(["error", "warn"]))
-});
-const CatalogConfigSchema = Schema.Struct({
-	name: Schema.String.check(Schema.isMinLength(1)),
-	description: Schema.String,
-	fileMatch: Schema.Array(Schema.String),
-	baseUrl: Schema.String.check(Schema.isMinLength(1)),
-	path: Schema.String.check(Schema.isMinLength(1))
-});
-const decodeOrThrow = (schema, value, what) => {
-	const result = Schema.decodeUnknownResult(schema)(value);
-	if (result._tag === "Failure") throw new Error(`defineConfig: invalid ${what}: ${String(result.failure)}`);
-	return result.success;
+/** The host SchemaStore-hosted documents declare in `$id`. @public */
+const SCHEMASTORE_ID_BASE = "https://json.schemastore.org";
+/** The host SchemaStore's `catalog.json` points `url` at. @public */
+const SCHEMASTORE_CATALOG_BASE = "https://www.schemastore.org";
+const DRIFT_TOLERANCES = [
+	"strict",
+	"semantic",
+	"allow"
+];
+const ON_DRIFT = ["error", "warn"];
+const LAYOUTS = ["flat", "versioned"];
+const fail = (message) => {
+	throw new Error(`defineConfig: ${message}`);
 };
-const versionsByName = (schemas) => {
-	const map = /* @__PURE__ */ new Map();
-	for (const target of schemas) {
-		if (target.name === void 0 || target.version === void 0) continue;
-		const version = target.version;
-		const versions = map.get(target.name) ?? [];
+const trimSlashes = (dir) => {
+	let end = dir.length;
+	while (end > 1 && dir.charCodeAt(end - 1) === 47) end -= 1;
+	return dir.slice(0, end);
+};
+const resolveHosting = (name, baseUrl, layout) => {
+	if (baseUrl === void 0) return fail(`schema "${name}" has no baseUrl and the config declares no default`);
+	if (typeof baseUrl !== "string") return fail(`schema "${name}" has a baseUrl that is not a string`);
+	if (baseUrl.length === 0) return fail(`schema "${name}" has no baseUrl and the config declares no default`);
+	if (layout !== void 0 && !LAYOUTS.includes(layout)) return fail(`schema "${name}" has an invalid layout "${String(layout)}"; expected "flat" or "versioned"`);
+	if (baseUrl === "schemastore") {
+		if (layout !== void 0) return fail(`schema "${name}" declares layout "${layout}" under baseUrl "schemastore", which serves only the flat layout`);
+		return {
+			idBase: SCHEMASTORE_ID_BASE,
+			catalogBase: SCHEMASTORE_CATALOG_BASE,
+			layout: "flat"
+		};
+	}
+	if (!baseUrl.startsWith("https://") || baseUrl.length === 8) return fail(`schema "${name}" has baseUrl "${baseUrl}"; expected "schemastore" or an https:// URL`);
+	return {
+		idBase: baseUrl,
+		catalogBase: baseUrl,
+		layout: layout ?? "versioned"
+	};
+};
+const parseLabel = (name, label) => {
+	if (typeof label !== "string") return fail(`schema "${name}" has a version label that is not a string: ${String(label)}`);
+	return Result.getOrThrowWith(SchemaVersioning.parseResult(label), (error) => /* @__PURE__ */ new Error(`defineConfig: schema "${name}" has an invalid version label "${label}": ${error.message}`));
+};
+const resolveVersions = (name, entry) => {
+	if (entry.versions === void 0) {
+		if (entry.current !== void 0) return fail(`schema "${name}" declares current "${entry.current}" without versions`);
+		return;
+	}
+	if (!Array.isArray(entry.versions)) return fail(`schema "${name}" declares versions that is not an array`);
+	if (entry.versions.length === 0) return fail(`schema "${name}" declares versions as an empty array; omit versions for an unversioned schema`);
+	const versions = [];
+	for (const label of entry.versions) {
+		const version = parseLabel(name, label);
 		const duplicate = versions.find((v) => SchemaVersioning.Order(v, version) === 0);
-		if (duplicate !== void 0) throw new Error(`defineConfig: schema "${target.name}" declares the same version twice, as "${duplicate}" and "${version}"`);
+		if (duplicate !== void 0) return fail(`schema "${name}" declares the same version twice, as "${duplicate}" and "${version}"`);
 		versions.push(version);
-		map.set(target.name, versions);
 	}
-	return map;
+	const newest = Option.getOrThrow(SchemaVersioning.latest(versions));
+	if (entry.current === void 0) return {
+		versions,
+		current: newest
+	};
+	const current = parseLabel(name, entry.current);
+	const match = versions.find((v) => SchemaVersioning.Order(v, current) === 0);
+	if (match === void 0) return fail(`schema "${name}" declares current "${entry.current}" which is not one of its versions`);
+	return {
+		versions,
+		current: match
+	};
+};
+const isDriftTolerance = (value) => DRIFT_TOLERANCES.includes(value);
+const resolveConfigDrift = (value) => {
+	if (value === void 0) return DriftPolicy.defaults.policy;
+	return isDriftTolerance(value) ? value : fail(`config has an invalid drift tolerance "${String(value)}"`);
+};
+const resolveSchemaDrift = (name, value, fallback) => {
+	if (value === void 0) return fallback;
+	return isDriftTolerance(value) ? value : fail(`schema "${name}" has an invalid drift tolerance "${String(value)}"`);
+};
+const resolveEntry = (name, entry, defaults, outputDir) => {
+	if (!SchemaVersioning.isSimpleName(name)) return fail(`schema "${name}" must be keyed by a simple file base name (no separators, no whitespace)`);
+	if (!Predicate.isObject(entry)) return fail(`schema "${name}" must be an object`);
+	if (!Schema.isSchema(entry.schema)) return fail(`schema "${name}" has a schema that is not an Effect Schema`);
+	if (entry.published !== void 0 && typeof entry.published !== "boolean") return fail(`schema "${name}" has a published that is not a boolean`);
+	const baseUrl = entry.baseUrl ?? defaults.baseUrl;
+	const hosting = resolveHosting(name, baseUrl, entry.layout);
+	const versioned = resolveVersions(name, entry);
+	if (baseUrl === "schemastore" && entry.catalog === void 0) return fail(`schema "${name}" must declare a catalog block under baseUrl "schemastore"`);
+	if (entry.catalog !== void 0 && (!Predicate.isObject(entry.catalog) || !Array.isArray(entry.catalog.fileMatch) || typeof entry.catalog.description !== "string")) return fail(`schema "${name}" declares an invalid catalog block (expected { description, fileMatch[] })`);
+	if (entry.catalog !== void 0 && entry.catalog.fileMatch.length === 0) return fail(`schema "${name}" declares a catalog with an empty fileMatch`);
+	const file = (version) => `${outputDir}/${SchemaVersioning.fileName(name, version, hosting.layout)}`;
+	const urlOf = (base) => (version) => SchemaVersioning.schemaUrl(base, name, version, hosting.layout);
+	const idOf = urlOf(hosting.idBase);
+	const catalogUrlOf = urlOf(hosting.catalogBase);
+	const current = versioned?.current;
+	const target = current === void 0 ? SchemaTarget.make({
+		schema: entry.schema,
+		$id: idOf(current),
+		name,
+		path: file(current),
+		published: entry.published ?? false,
+		...entry.jsonSchema !== void 0 ? { jsonSchema: entry.jsonSchema } : {},
+		...entry.rootAnnotations !== void 0 ? { rootAnnotations: entry.rootAnnotations } : {}
+	}) : SchemaTarget.make({
+		schema: entry.schema,
+		$id: idOf(current),
+		name,
+		path: file(current),
+		version: current,
+		published: entry.published ?? false,
+		...entry.jsonSchema !== void 0 ? { jsonSchema: entry.jsonSchema } : {},
+		...entry.rootAnnotations !== void 0 ? { rootAnnotations: entry.rootAnnotations } : {}
+	});
+	const frozen = versioned === void 0 ? [] : versioned.versions.filter((v) => v !== versioned.current).map((version) => ({
+		version,
+		path: file(version),
+		url: catalogUrlOf(version)
+	}));
+	const catalog = entry.catalog === void 0 ? void 0 : CatalogEntry.assemble({
+		name,
+		description: entry.catalog.description,
+		fileMatch: entry.catalog.fileMatch,
+		baseUrl: hosting.catalogBase,
+		layout: hosting.layout,
+		...versioned !== void 0 ? {
+			versions: versioned.versions,
+			current: versioned.current
+		} : {}
+	});
+	return {
+		name,
+		target,
+		frozen,
+		drift: resolveSchemaDrift(name, entry.drift, defaults.drift),
+		...catalog !== void 0 ? { catalog } : {}
+	};
 };
 const normalizePath = (raw) => {
 	const absolute = raw.startsWith("/");
@@ -52,11 +157,11 @@ const normalizePath = (raw) => {
 	}
 	return `${absolute ? "/" : ""}${out.join("/")}`;
 };
-const assertUniquePaths = (schemas, catalog) => {
+const assertUniquePaths = (paths) => {
 	const seen = /* @__PURE__ */ new Set();
-	for (const p of [...schemas.map((target) => target.path), ...catalog.map((entry) => entry.path)]) {
+	for (const p of paths) {
 		const normalized = normalizePath(p);
-		if (seen.has(normalized)) throw new Error(`defineConfig: output path "${p}" is declared twice`);
+		if (seen.has(normalized)) fail(`output path "${p}" is declared twice`);
 		seen.add(normalized);
 	}
 };
@@ -64,46 +169,57 @@ const assertUniquePaths = (schemas, catalog) => {
 * Validate and assemble a `schemastore.config.ts` value.
 *
 * @remarks
-* Pure: no IO, no Effect. Identity-with-validation over the input, filling
-* drift defaults, deriving each catalog entry's `versions` from EVERY
-* versioned schema of that name (published or not — the entry is what gets
-* submitted to become published), and branding the result so a loader can
-* recognise a config module's default export. Throws a plain `Error` on a
-* bad input; the CLI wraps it into its typed config-load error. Rejects an
-* output `path` declared twice across schemas and catalog entries, compared
-* after a lexical normalisation (`./`, `..`, trailing `/`); the CLI's loader
-* re-checks on the resolved absolute paths.
+* Pure: no IO, no Effect. `$id`, the write `path` and every catalog URL are
+* derived from ONE layout (`outputDir`, `baseUrl` and `layout`) so they
+* cannot disagree with each other. `versions` names every label a schema
+* advertises; `current` (default: the newest under
+* {@link SchemaVersioning.Order}) is the one generated at `target`, and every
+* other label becomes a {@link FrozenVersion} the CLI verifies but does not
+* regenerate. `baseUrl: "schemastore"` expands to
+* {@link SCHEMASTORE_ID_BASE} for `$id` and {@link SCHEMASTORE_CATALOG_BASE}
+* for the catalog URL, forcing the `"flat"` layout; any other `baseUrl` is
+* used as one base for both, defaulting to the `"versioned"` layout.
+*
+* Throws a plain `Error` (never a raw `TypeError`) naming the offending
+* schema on: a non-object `input`; an empty `schemas` record; a
+* missing/empty `outputDir`; a schema key that is not a simple file base
+* name; a schema whose `schema` is not an Effect Schema; a schema with no
+* `baseUrl` anywhere, or a `baseUrl` that is not a string; a `baseUrl` that
+* is neither `"schemastore"` nor an `https://` URL; a `versions` that is not
+* an array, or an empty `versions` array; a version label (or `current`)
+* that is not a string, or an otherwise invalid version label; two labels
+* spelling the same version; `current` given without `versions`, or naming
+* one not among them; a non-boolean `published`; `layout` declared under
+* `baseUrl: "schemastore"`; a missing `catalog` under
+* `baseUrl: "schemastore"`, or one with an empty `fileMatch`; an invalid
+* `drift` or top-level `onDrift`; and an output path (a target, a frozen
+* file, or the catalog path) declared twice, compared after a lexical
+* normalisation (`./`, `..`, trailing `/`) — the CLI's loader re-checks on
+* the resolved absolute paths. Branding the result lets a loader recognise a
+* config module's default export via {@link isSchemastoreConfig}.
 *
 * @public
 */
 const defineConfig = (input) => {
-	if (!Array.isArray(input.schemas) || input.schemas.length === 0) throw new Error("defineConfig: at least one schema is required");
-	const drift = decodeOrThrow(DriftSchema, input.drift ?? {}, "drift block");
-	const versions = versionsByName(input.schemas);
-	const catalog = (input.catalog ?? []).map((raw) => {
-		const config = decodeOrThrow(CatalogConfigSchema, raw, `catalog entry "${String(raw.name)}"`);
-		const found = versions.get(config.name);
-		if (found === void 0) throw new Error(`defineConfig: catalog entry "${config.name}" matches no versioned schema`);
-		return {
-			config,
-			entry: CatalogEntry.assemble({
-				name: config.name,
-				description: config.description,
-				fileMatch: config.fileMatch,
-				baseUrl: config.baseUrl,
-				versions: found
-			})
-		};
-	});
-	assertUniquePaths(input.schemas, catalog.map((c) => c.config));
+	if (!Predicate.isObject(input)) return fail("expected a config object");
+	if (typeof input.outputDir !== "string" || input.outputDir.length === 0) return fail("outputDir is required");
+	const outputDir = trimSlashes(input.outputDir);
+	if (!Predicate.isObject(input.schemas) || Object.keys(input.schemas).length === 0) return fail("at least one schema is required");
+	if (input.onDrift !== void 0 && !ON_DRIFT.includes(input.onDrift)) return fail(`invalid onDrift "${String(input.onDrift)}"`);
+	if (input.catalogPath !== void 0 && (typeof input.catalogPath !== "string" || input.catalogPath.length === 0)) return fail("catalogPath must be a non-empty string when given");
+	const defaults = {
+		baseUrl: input.baseUrl,
+		drift: resolveConfigDrift(input.drift)
+	};
+	const schemas = Object.entries(input.schemas).map(([name, entry]) => resolveEntry(name, entry, defaults, outputDir));
+	const catalogPath = input.catalogPath ?? `${outputDir}/catalog.json`;
+	assertUniquePaths([...schemas.flatMap((s) => [s.target.path, ...s.frozen.map((f) => f.path)]), catalogPath]);
 	return {
 		[ConfigBrand]: true,
-		schemas: input.schemas,
-		catalog,
-		drift: {
-			policy: drift.policy ?? DriftPolicy.defaults.policy,
-			onDrift: drift.onDrift ?? DriftPolicy.defaults.onDrift
-		}
+		outputDir,
+		onDrift: input.onDrift ?? DriftPolicy.defaults.onDrift,
+		catalogPath,
+		schemas
 	};
 };
 /**
@@ -115,4 +231,4 @@ const defineConfig = (input) => {
 const isSchemastoreConfig = (value) => typeof value === "object" && value !== null && value[ConfigBrand] === true;
 
 //#endregion
-export { defineConfig, isSchemastoreConfig };
+export { SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, defineConfig, isSchemastoreConfig };

package/StoreDocument.js

@@ -1,6 +1,6 @@
 import { CanonicalJson } from "./CanonicalJson.js";
 import { KeywordFamilies } from "./KeywordFamilies.js";
-import { Effect, JsonSchema, Result, Schema } from "effect";
+import { Effect, JsonPointer, JsonSchema, Result, Schema } from "effect";
 
 //#region src/StoreDocument.ts
 /**
@@ -36,7 +36,10 @@ var SchemaConversionError = class extends Schema.TaggedError()("SchemaConversion
 /**
 * Indicates that a caller-supplied `includeAnnotationKey` admitted an
 * annotation key outside the declared keyword families
-* ({@link KeywordFamilies}).
+* ({@link KeywordFamilies}), or that a
+* {@link StoreDocumentOptions.rootAnnotations} override names a key outside
+* the admitted set (the standard annotation keywords plus the declared
+* families).
 *
 * Raised by {@link StoreDocument.fromSchema}. This package emits
 * SchemaStore-compatible documents only, so the declared families are the
@@ -47,7 +50,8 @@ var SchemaConversionError = class extends Schema.TaggedError()("SchemaConversion
 *
 * The predicate itself cannot be introspected, so the offending keys are
 * the ones it actually admitted while the document was being generated: a
-* key the source schema never annotates cannot appear here.
+* key the source schema never annotates cannot appear here. Override keys,
+* by contrast, are checked up front, before anything is generated.
 *
 * @public
 */
@@ -63,6 +67,48 @@ var UndeclaredAnnotationKeyError = class extends Schema.TaggedError()("Undeclare
 	}
 };
 const DEFINITIONS_REF_PREFIX = /^#\/definitions(?=\/|$)/;
+const STANDARD_ANNOTATION_KEYWORDS = /* @__PURE__ */ new Set([
+	"title",
+	"description",
+	"$comment",
+	"default",
+	"examples",
+	"readOnly",
+	"writeOnly",
+	"contentMediaType",
+	"contentEncoding"
+]);
+const countRefs = (node, ref) => {
+	if (Array.isArray(node)) {
+		let count = 0;
+		for (const item of node) count += countRefs(item, ref);
+		return count;
+	}
+	if (typeof node === "object" && node !== null) {
+		let count = 0;
+		for (const [key, value] of Object.entries(node)) {
+			if (KeywordFamilies.isDeclared(key)) continue;
+			count += key === "$ref" && value === ref ? 1 : countRefs(value, ref);
+		}
+		return count;
+	}
+	return 0;
+};
+const applyRootAnnotations = (root, defs, annotations) => {
+	const keys = Object.keys(root);
+	const ref = keys.length === 1 && keys[0] === "$ref" ? root.$ref : void 0;
+	const path = typeof ref === "string" ? JsonPointer.parseUriFragment(ref) : void 0;
+	const pool = path !== void 0 && path.length === 2 && path[0] === "$defs" ? defs[path[1]] : void 0;
+	const entry = typeof pool === "object" && pool !== null && !Array.isArray(pool) ? pool : void 0;
+	const shared = entry !== void 0 && typeof ref === "string" && countRefs(defs, ref) > 0;
+	if (shared) delete root.$ref;
+	const target = entry !== void 0 && !shared ? entry : root;
+	for (const [key, value] of Object.entries(annotations)) {
+		if (value === void 0) continue;
+		target[key] = value;
+	}
+	if (shared) root.allOf = [{ $ref: ref }];
+};
 var RewriteDepthExceeded = class {
 	_tag = "RewriteDepthExceeded";
 };
@@ -153,6 +199,11 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 	*/
 	static fromSchemaResult(source, options) {
 		try {
+			const refusedOverrides = Object.keys(options.rootAnnotations ?? {}).filter((key) => !STANDARD_ANNOTATION_KEYWORDS.has(key) && !KeywordFamilies.isDeclared(key));
+			if (refusedOverrides.length > 0) return Result.fail(UndeclaredAnnotationKeyError.make({
+				$id: options.$id,
+				keys: [...refusedOverrides].sort()
+			}));
 			const userIncludes = options.jsonSchema?.includeAnnotationKey;
 			const undeclared = /* @__PURE__ */ new Set();
 			const document = Schema.toJsonSchemaDocument(source, {
@@ -171,6 +222,7 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 			const root = restoreDefsRefs(lowered.schema, 0);
 			const defs = Object.create(null);
 			for (const [name, definition] of Object.entries(lowered.definitions)) defs[name] = restoreDefsRefs(definition, 1);
+			if (options.rootAnnotations !== void 0) applyRootAnnotations(root, defs, options.rootAnnotations);
 			return Result.succeed(StoreDocument.make({
 				$schema: DRAFT_07_META_SCHEMA,
 				$id: options.$id,