@effected/schemastore 0.10.0 → 0.11.0

package/CatalogEntry.js

@@ -98,7 +98,9 @@ var CatalogEntry = class CatalogEntry extends Schema.Class("CatalogEntry")({
 	* Assembles an entry from a catalog identity plus
 	* {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
 	* versioned mode (the `versions` map and latest-pointing `url` are
-	* derived), omit it for the unversioned mode. Throws an `Error` naming
+	* derived), omit it for the unversioned mode. `layout` (default
+	* `"flat"`) and `current` (default: the newest label) are forwarded to
+	* {@link SchemaVersioning.catalogUrls} verbatim. Throws an `Error` naming
 	* both spellings when two labels compare equal under
 	* {@link SchemaVersioning.Order} (`1.2` and `1.2.0`): each would be its
 	* own key and URL for one document.
@@ -108,7 +110,9 @@ var CatalogEntry = class CatalogEntry extends Schema.Class("CatalogEntry")({
 		const urls = SchemaVersioning.catalogUrls({
 			baseUrl: options.baseUrl,
 			name: options.fileBaseName ?? options.name,
-			...options.versions !== void 0 ? { versions: options.versions } : {}
+			...options.versions !== void 0 ? { versions: options.versions } : {},
+			...options.layout !== void 0 ? { layout: options.layout } : {},
+			...options.current !== void 0 ? { current: options.current } : {}
 		});
 		return CatalogEntry.make({
 			name: options.name,

package/SchemaVersioning.js

@@ -73,7 +73,7 @@ const bumpNext = (current, parsed, components) => {
 	}
 };
 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}"`);
+	if (!SchemaVersioning.isSimpleName(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;
@@ -182,22 +182,35 @@ var SchemaVersioning = class SchemaVersioning {
 		return reparsed.success;
 	}
 	/**
+	* Whether a name is a simple file base name — non-empty, no path
+	* separators, no whitespace — the rule every schema name is held to
+	* ({@link SchemaVersioning.fileName} throws on anything else; `defineConfig`
+	* rejects a schema key the same way). One predicate so the two cannot drift.
+	*/
+	static isSimpleName(name) {
+		return name.length > 0 && !/[/\\\s]/.test(name);
+	}
+	/**
 	* Derives the schema file name for a catalog name: `name.json`
-	* unversioned, `name-<version>.json` versioned.
+	* unversioned, `name-<version>.json` versioned under the `"flat"`
+	* layout (the default and the only shape SchemaStore serves), or
+	* `<version>/name-<version>.json` under `"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) {
+	static fileName(name, version, layout = "flat") {
 		assertSimpleName(name);
-		return version === void 0 ? `${name}.json` : `${name}-${version}.json`;
+		if (version === void 0) return `${name}.json`;
+		const file = `${name}-${version}.json`;
+		return layout === "versioned" ? `${version}/${file}` : file;
 	}
 	/**
 	* 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));
+	static schemaUrl(baseUrl, name, version, layout = "flat") {
+		return joinUrl(baseUrl, SchemaVersioning.fileName(name, version, layout));
 	}
 	/**
 	* Assembles the `url`/`versions` half of a catalog entry.
@@ -205,9 +218,19 @@ var SchemaVersioning = class SchemaVersioning {
 	* 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
+	* points at `current` (default: the newest label under
+	* {@link SchemaVersioning.Order}). An **empty** `versions` array is
 	* a contradiction (versioned mode with no versions) and throws — pass
-	* `undefined` for the unversioned mode.
+	* `undefined` for the unversioned mode. `current`, when given, must
+	* compare equal under {@link SchemaVersioning.Order} to a member of
+	* `versions` or this throws; `url` is built from that member's own
+	* spelling (the `versions` map's key), not from the `current` argument
+	* verbatim — so a differently-spelled equivalent (`"1.2"` matching a
+	* `"1.2.0"` member) still points `url` at the same file the map does.
+	*
+	* `layout` (default `"flat"`) is forwarded to every URL derivation, so
+	* `"versioned"` nests every map value and `url` under its own version
+	* directory.
 	*
 	* Labels are inserted in ascending {@link SchemaVersioning.Order}; see
 	* {@link CatalogUrls.versions} for why a bare-major key's serialized
@@ -215,14 +238,18 @@ var SchemaVersioning = class SchemaVersioning {
 	*/
 	static catalogUrls(options) {
 		const { baseUrl, name, versions } = options;
-		if (versions === void 0) return { url: SchemaVersioning.schemaUrl(baseUrl, name) };
+		const layout = options.layout ?? "flat";
+		if (versions === void 0) return { url: SchemaVersioning.schemaUrl(baseUrl, name, void 0, layout) };
 		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);
+		for (const version of ascending) map[version] = SchemaVersioning.schemaUrl(baseUrl, name, version, layout);
 		const newest = ascending[ascending.length - 1];
+		const requested = options.current ?? newest;
+		const current = ascending.find((v) => SchemaVersioning.Order(v, requested) === 0);
+		if (current === void 0) throw new Error(`catalogUrls: current "${requested}" is not one of the versions of "${name}"`);
 		return {
-			url: SchemaVersioning.schemaUrl(baseUrl, name, newest),
+			url: SchemaVersioning.schemaUrl(baseUrl, name, current, layout),
 			versions: map
 		};
 	}

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,49 +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 rawCatalog = input.catalog ?? [];
-	if (!Array.isArray(rawCatalog)) throw new Error("defineConfig: invalid catalog: expected an array of catalog entries");
-	const catalog = rawCatalog.map((raw) => {
-		const label = typeof raw === "object" && raw !== null ? String(raw.name) : String(raw);
-		const config = decodeOrThrow(CatalogConfigSchema, raw, `catalog entry "${label}"`);
-		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
 	};
 };
 /**
@@ -118,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/index.d.ts

@@ -650,6 +650,15 @@ export declare const SchemaVersion: Schema.brand<Schema.String, "SchemaVersion">
  * @public
  */
 export type SchemaVersion = typeof SchemaVersion.Type;
+/**
+ * Where a versioned document sits relative to its base: `flat` is
+ * `<name>-<version>.json` (the only shape SchemaStore serves), `versioned`
+ * nests it as `<version>/<name>-<version>.json`. An unversioned document is
+ * `<name>.json` under either.
+ *
+ * @public
+ */
+type SchemaLayout = "flat" | "versioned";
 /**
  * The `url`/`versions` half of a catalog entry, as assembled by
  * {@link SchemaVersioning.catalogUrls}.
@@ -756,28 +765,47 @@ export declare class SchemaVersioning {
    * the label and the ceiling rather than `SemVer.make`'s bare schema failure.
    */
   static next(current: SchemaVersion, change: WriteChange): SchemaVersion;
+  /**
+   * Whether a name is a simple file base name — non-empty, no path
+   * separators, no whitespace — the rule every schema name is held to
+   * ({@link SchemaVersioning.fileName} throws on anything else; `defineConfig`
+   * rejects a schema key the same way). One predicate so the two cannot drift.
+   */
+  static isSimpleName(name: string): boolean;
   /**
    * Derives the schema file name for a catalog name: `name.json`
-   * unversioned, `name-<version>.json` versioned.
+   * unversioned, `name-<version>.json` versioned under the `"flat"`
+   * layout (the default and the only shape SchemaStore serves), or
+   * `<version>/name-<version>.json` under `"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: string, version?: SchemaVersion): string;
+  static fileName(name: string, version?: SchemaVersion, layout?: SchemaLayout): string;
   /**
    * The canonical URL a schema file is hosted at: `baseUrl` joined with
    * {@link SchemaVersioning.fileName}.
    */
-  static schemaUrl(baseUrl: string, name: string, version?: SchemaVersion): string;
+  static schemaUrl(baseUrl: string, name: string, version?: SchemaVersion, layout?: SchemaLayout): string;
   /**
    * 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
+   * points at `current` (default: the newest label under
+   * {@link SchemaVersioning.Order}). An **empty** `versions` array is
    * a contradiction (versioned mode with no versions) and throws — pass
-   * `undefined` for the unversioned mode.
+   * `undefined` for the unversioned mode. `current`, when given, must
+   * compare equal under {@link SchemaVersioning.Order} to a member of
+   * `versions` or this throws; `url` is built from that member's own
+   * spelling (the `versions` map's key), not from the `current` argument
+   * verbatim — so a differently-spelled equivalent (`"1.2"` matching a
+   * `"1.2.0"` member) still points `url` at the same file the map does.
+   *
+   * `layout` (default `"flat"`) is forwarded to every URL derivation, so
+   * `"versioned"` nests every map value and `url` under its own version
+   * directory.
    *
    * Labels are inserted in ascending {@link SchemaVersioning.Order}; see
    * {@link CatalogUrls.versions} for why a bare-major key's serialized
@@ -787,6 +815,8 @@ export declare class SchemaVersioning {
     readonly baseUrl: string;
     readonly name: string;
     readonly versions?: ReadonlyArray<SchemaVersion>;
+    readonly layout?: SchemaLayout;
+    readonly current?: SchemaVersion;
   }): CatalogUrls;
 }
 //#endregion
@@ -836,7 +866,9 @@ export declare class CatalogEntry extends CatalogEntry_base {
    * Assembles an entry from a catalog identity plus
    * {@link SchemaVersioning.catalogUrls}' inputs: pass `versions` for the
    * versioned mode (the `versions` map and latest-pointing `url` are
-   * derived), omit it for the unversioned mode. Throws an `Error` naming
+   * derived), omit it for the unversioned mode. `layout` (default
+   * `"flat"`) and `current` (default: the newest label) are forwarded to
+   * {@link SchemaVersioning.catalogUrls} verbatim. Throws an `Error` naming
    * both spellings when two labels compare equal under
    * {@link SchemaVersioning.Order} (`1.2` and `1.2.0`): each would be its
    * own key and URL for one document.
@@ -848,6 +880,8 @@ export declare class CatalogEntry extends CatalogEntry_base {
     readonly baseUrl: string;
     readonly fileBaseName?: string;
     readonly versions?: ReadonlyArray<SchemaVersion>;
+    readonly layout?: SchemaLayout;
+    readonly current?: SchemaVersion;
   }): CatalogEntry;
   /**
    * The fileMatch hygiene lint over this entry's patterns — pure shape
@@ -1630,42 +1664,144 @@ export declare class SchemaPipeline {
 //#endregion
 //#region src/SchemastoreConfig.d.ts
 declare const ConfigBrand: unique symbol;
+/** The host SchemaStore-hosted documents declare in `$id`. @public */
+export declare const SCHEMASTORE_ID_BASE = "https://json.schemastore.org";
+/** The host SchemaStore's `catalog.json` points `url` at. @public */
+export declare const SCHEMASTORE_CATALOG_BASE = "https://www.schemastore.org";
 /**
- * One catalog entry a `schemastore.config.ts` declares: the SchemaStore
- * `catalog.json` fields plus where to write the assembled entry. The entry's
- * `versions` and `url` are derived by {@link defineConfig} from every
- * versioned schema of the same `name`.
+ * The SchemaStore `catalog.json` fields a schema entry declares, minus
+ * `url`/`versions` — those are derived from the entry's `baseUrl`, `layout`
+ * and `versions`/`current` by {@link defineConfig}, so they cannot disagree
+ * with the schema's own identity.
  *
  * @public
  */
-interface CatalogConfig {
-  readonly name: string;
+interface CatalogInput {
+  /** The catalog description. */
   readonly description: string;
+  /** Glob patterns editors match files against; must be non-empty. */
   readonly fileMatch: ReadonlyArray<string>;
-  readonly baseUrl: string;
-  /** Where to write the assembled entry; relative paths are resolved by the loader against the config file's directory. */
-  readonly path: string;
 }
 /**
- * What a `schemastore.config.ts` hands to {@link defineConfig}: the schema
- * targets, an optional catalog block and an optional partial drift block.
+ * One schema a `schemastore.config.ts` declares, keyed by its own file base
+ * name in {@link SchemastoreConfigInput.schemas}. `$id`, the write `path` and
+ * every catalog URL are derived from `outputDir`, `baseUrl` (this entry's, or
+ * the config's default) and `layout` — never spelled out by hand.
+ *
+ * @public
+ */
+interface SchemaEntryInput {
+  /** The Effect Schema source the document is generated from. */
+  readonly schema: Schema.Constraint;
+  /**
+   * Every version label this schema advertises. Omit for an unversioned
+   * schema (`<name>.json`). An empty array is rejected — omit the field
+   * instead. Two labels that compare equal under
+   * {@link SchemaVersioning.Order} (`"1.2"` and `"1.2.0"`) are rejected as
+   * one version spelled twice.
+   */
+  readonly versions?: ReadonlyArray<string>;
+  /**
+   * Which of `versions` is the one generated at this entry's `path`/`$id`;
+   * the rest become {@link ResolvedSchema.frozen} files the CLI verifies
+   * but does not regenerate. Defaults to the newest label under
+   * {@link SchemaVersioning.Order}. Requires `versions`, and must name one
+   * of them.
+   */
+  readonly current?: string;
+  /**
+   * Whether a consumer already depends on this document at this label —
+   * forwarded to {@link (SchemaTarget:class).(make:1)}. Defaults to `false`.
+   */
+  readonly published?: boolean;
+  /**
+   * Where this schema is hosted: the literal `"schemastore"` (the only
+   * value that expands `$id` to {@link SCHEMASTORE_ID_BASE} and the catalog
+   * URL to {@link SCHEMASTORE_CATALOG_BASE}, and forces the `"flat"`
+   * layout) or an `https://` URL used as ONE base for both `$id` and the
+   * catalog URL. Falls back to {@link SchemastoreConfigInput.baseUrl} when
+   * omitted; an entry with neither is rejected.
+   */
+  readonly baseUrl?: string;
+  /**
+   * How a versioned document's path/URL nests relative to its base — see
+   * {@link SchemaLayout}. Defaults to `"versioned"` for a custom `baseUrl`,
+   * and is rejected outright under `baseUrl: "schemastore"`, which serves
+   * only the flat layout.
+   */
+  readonly layout?: SchemaLayout;
+  /** Overrides {@link SchemastoreConfigInput.drift} for this schema. */
+  readonly drift?: DriftTolerance;
+  /**
+   * The catalog entry to assemble for this schema. Required under
+   * `baseUrl: "schemastore"` (every SchemaStore-hosted document is
+   * cataloged); optional under a custom host.
+   */
+  readonly catalog?: CatalogInput;
+  /** Forwarded to {@link (SchemaTarget:class).(make:1)}'s `jsonSchema`. */
+  readonly jsonSchema?: Schema.ToJsonSchemaOptions;
+  /** Forwarded to {@link (SchemaTarget:class).(make:1)}'s `rootAnnotations`. */
+  readonly rootAnnotations?: Readonly<Record<string, unknown>>;
+}
+/**
+ * What a `schemastore.config.ts` hands to {@link defineConfig}: a directory
+ * every derived path is written under, top-level defaults for `baseUrl` and
+ * `drift`, and the keyed set of schemas to derive.
  *
  * @public
  */
 interface SchemastoreConfigInput {
-  readonly schemas: ReadonlyArray<SchemaTarget>;
-  readonly catalog?: ReadonlyArray<CatalogConfig>;
-  readonly drift?: Partial<DriftOptions>;
+  /** The directory every derived `path` is written under; a trailing slash is trimmed. */
+  readonly outputDir: string;
+  /** The default {@link SchemaEntryInput.baseUrl} for an entry that declares none. */
+  readonly baseUrl?: string;
+  /** The default {@link SchemaEntryInput.drift} for an entry that declares none. Defaults to `"semantic"`. */
+  readonly drift?: DriftTolerance;
+  /** What a build does when it finds drift. Defaults to `"error"`. */
+  readonly onDrift?: OnDrift;
+  /** Where the assembled catalog is written. Defaults to `<outputDir>/catalog.json`. */
+  readonly catalogPath?: string;
+  /**
+   * The schemas to derive, keyed by file base name — the key IS the
+   * `name` every derived path and URL is built from, so it must be a
+   * simple file base name (no separators, no whitespace).
+   */
+  readonly schemas: Readonly<Record<string, SchemaEntryInput>>;
+}
+/**
+ * One version of a schema that is advertised (via `versions`) but not the
+ * one currently generated — a file the CLI verifies exists on disk before
+ * any write (existence only — content is never compared), never
+ * regenerates.
+ *
+ * @public
+ */
+interface FrozenVersion {
+  /** The frozen version label. */
+  readonly version: SchemaVersion;
+  /** The path the frozen file lives at. */
+  readonly path: string;
+  /** The catalog URL the frozen file is hosted at. */
+  readonly url: string;
 }
 /**
- * A validated catalog declaration paired with the `CatalogEntry` assembled
- * from it.
+ * One `defineConfig` schema entry, resolved: the {@link (SchemaTarget:interface)} to
+ * generate, its frozen predecessor versions, its effective drift tolerance,
+ * and its assembled catalog entry, if any.
  *
  * @public
  */
-interface CatalogTarget {
-  readonly config: CatalogConfig;
-  readonly entry: CatalogEntry;
+interface ResolvedSchema {
+  /** The schema's key in {@link SchemastoreConfigInput.schemas}. */
+  readonly name: string;
+  /** The target to generate at the current version (or the sole, unversioned target). */
+  readonly target: SchemaTarget;
+  /** Every OTHER advertised version, as a frozen file to verify. */
+  readonly frozen: ReadonlyArray<FrozenVersion>;
+  /** This entry's effective drift tolerance, after falling back to the config default. */
+  readonly drift: DriftTolerance;
+  /** The assembled catalog entry, when {@link SchemaEntryInput.catalog} was given. */
+  readonly catalog?: CatalogEntry;
 }
 /**
  * The validated, defaults-filled config {@link defineConfig} answers and the
@@ -1675,23 +1811,47 @@ interface CatalogTarget {
  */
 interface SchemastoreConfig {
   readonly [ConfigBrand]: true;
-  readonly schemas: ReadonlyArray<SchemaTarget>;
-  readonly catalog: ReadonlyArray<CatalogTarget>;
-  readonly drift: DriftOptions;
+  /** The directory every derived `path` is written under, trailing slash trimmed. */
+  readonly outputDir: string;
+  /** What a build does when it finds drift. */
+  readonly onDrift: OnDrift;
+  /** Where the assembled catalog is written. */
+  readonly catalogPath: string;
+  /** Every schema, resolved. */
+  readonly schemas: ReadonlyArray<ResolvedSchema>;
 }
 /**
  * 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
  */
@@ -1704,5 +1864,5 @@ export declare const defineConfig: (input: SchemastoreConfigInput) => Schemastor
  */
 export declare const isSchemastoreConfig: (value: unknown) => value is SchemastoreConfig;
 //#endregion
-export type { CanonicalJsonError, CanonicalJsonOptions, CatalogConfig, CatalogTarget, CatalogUrls, CheckResult, ContractChangePolicy, DriftOptions, DriftTolerance, DriftVerdict, OnDrift, PipelineCheckResult, PipelineResult, SchemaChange, SchemaFileShape, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, SchemastoreConfig, SchemastoreConfigInput, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
+export type { CanonicalJsonError, CanonicalJsonOptions, CatalogInput, CatalogUrls, CheckResult, ContractChangePolicy, DriftOptions, DriftTolerance, DriftVerdict, FrozenVersion, OnDrift, PipelineCheckResult, PipelineResult, ResolvedSchema, SchemaChange, SchemaEntryInput, SchemaFileShape, SchemaLayout, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, SchemastoreConfig, SchemastoreConfigInput, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -9,7 +9,7 @@ import { SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWri
 import { SchemaValidator, SchemaValidatorError, ValidationFinding } from "./SchemaValidator.js";
 import { DRAFT_07_META_SCHEMA, SchemaConversionError, StoreDocument, UndeclaredAnnotationKeyError } from "./StoreDocument.js";
 import { ContractChangeTarget, PipelineFinding, SchemaContractChangeError, SchemaGateError, SchemaPipeline } from "./SchemaPipeline.js";
-import { defineConfig, isSchemastoreConfig } from "./SchemastoreConfig.js";
 import { SchemaTarget } from "./SchemaTarget.js";
+import { SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, defineConfig, isSchemastoreConfig } from "./SchemastoreConfig.js";
 
-export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, DriftPolicy, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding, defineConfig, isSchemastoreConfig };
+export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, DriftPolicy, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding, defineConfig, isSchemastoreConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore",
-	"version": "0.10.0",
+	"version": "0.11.0",
 	"private": false,
 	"description": "Build, validate, version and publish SchemaStore-shaped Draft-07 JSON Schema documents from Effect Schema sources: document assembly, ajv strict-mode validation, structural lints, catalog entries, canonical JSON and a content-comparing emit pipeline.",
 	"keywords": [