@effected/schemastore 0.7.0 → 0.9.0

package/CatalogEntry.js

@@ -39,6 +39,14 @@ const GENERIC_BASENAMES = /* @__PURE__ */ new Set([
 	"settings"
 ]);
 const COMPLEX_GLOB = /[{}[\]]|[?*+@!]\(|^!/;
+const assertDistinctVersions = (name, versions) => {
+	const seen = [];
+	for (const version of versions) {
+		const duplicate = seen.find((v) => SchemaVersioning.Order(v, version) === 0);
+		if (duplicate !== void 0) throw new Error(`CatalogEntry.assemble: "${name}" declares the same version twice, as "${duplicate}" and "${version}"`);
+		seen.push(version);
+	}
+};
 const lintPattern = (pattern) => {
 	const findings = [];
 	const basename = pattern.slice(pattern.lastIndexOf("/") + 1);
@@ -90,9 +98,13 @@ 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.
+	* derived), omit it for the unversioned mode. 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.
 	*/
 	static assemble(options) {
+		if (options.versions !== void 0) assertDistinctVersions(options.name, options.versions);
 		const urls = SchemaVersioning.catalogUrls({
 			baseUrl: options.baseUrl,
 			name: options.fileBaseName ?? options.name,

package/DriftPolicy.js

@@ -0,0 +1,30 @@
+//#region src/DriftPolicy.ts
+/**
+* Classifies one target's change against a drift tolerance.
+*
+* @remarks
+* Pure and synchronous. The lifecycle rule is fixed here so no caller
+* relitigates it: an unpublished target is NEVER drift — it is regenerated
+* in place until someone depends on its label. Gate failures (lint warnings,
+* validator findings) are not drift either and are not this module's
+* concern.
+*
+* @public
+*/
+var DriftPolicy = class {
+	constructor() {}
+	/** `{ policy: "semantic", onDrift: "error" }` — what a config gets when it says nothing. */
+	static defaults = {
+		policy: "semantic",
+		onDrift: "error"
+	};
+	static classify(input, policy) {
+		if (!input.published || policy === "allow") return "write";
+		if (input.change === "contract") return "drift";
+		if (input.change === "annotations" && policy === "strict") return "drift";
+		return "write";
+	}
+};
+
+//#endregion
+export { DriftPolicy };

package/README.md

@@ -71,10 +71,12 @@ console.log(Effect.runSync(program));
 //   "required": [
 //     "name"
 //   ],
-//   "additionalProperties": false
+//   "additionalProperties": true
 // }
 ```
 
+`additionalProperties: true` is core's default for a struct: `Schema.toJsonSchemaDocument` emits open objects unless told otherwise. A config schema usually wants the closed form, and `jsonSchema: { onExcessProperty: "error" }` in the options produces it; the same option lives on a pipeline target, below.
+
 `fromSchema` runs the whole pipeline — 2020-12 generation, Draft-07 lowering, the `$ref` rewrite and the declared-family gate — so every `$ref` in a built document already resolves against its `$defs` pool. `toJson()` is the flat publication shape (`$defs` omitted when empty) and `serializeResult` routes through the owned canonical serializer, tab-indented with a single trailing newline. If core cannot convert a schema, the failure is typed as `SchemaConversionError` and carries the `$id` and the structured cause.
 
 ## Annotate at the definition site
@@ -112,7 +114,7 @@ One thing the package does *not* do to a declared-family value is walk inside it
 
 ## Catalog entries and versioning
 
-`CatalogEntry` is the `catalog.json` entry as a `Schema.Class`, so decoding an existing entry and encoding one for submission are the same artifact. `SchemaVersion` is a **full three-component SemVer** label — `major.minor.patch` with an optional prerelease, enforced by `@effected/semver` — so ordering is plain SemVer precedence (`1.10.0` above `1.9.0`) and the label round-trips verbatim. Build metadata is rejected (`1.0.0+build.5` does not parse): SemVer precedence ignores it, so two labels differing only in build would compare equal and both claim to be the latest. Surrounding whitespace is rejected for the same round-tripping reason. The file-name convention is SchemaStore's own `<name>-<version>.json`; the label grammar is the one deliberate divergence, since the store's corpus uses partial labels like `1.2` that no SemVer parser accepts and that cannot be split back out of a file name unambiguously.
+`CatalogEntry` is the `catalog.json` entry as a `Schema.Class`, so decoding an existing entry and encoding one for submission are the same artifact. `SchemaVersion` is a **one-to-three-component** label — `major`, `major.minor` or `major.minor.patch` with an optional prerelease, matched by a grammar regex and then validated by `@effected/semver` over the label padded to three components — so ordering is plain SemVer precedence (`1.10.0` above `1.9.0`; `1`, `1.0` and `1.0.0` compare equal) and the label round-trips verbatim. Build metadata is rejected (`1.0.0+build.5` does not parse): SemVer precedence ignores it, so two labels differing only in build would compare equal and both claim to be the latest. Surrounding whitespace is rejected for the same round-tripping reason. The file-name convention is SchemaStore's own `<name>-<version>.json`, and partial labels like `1.2` — common in the store's corpus — are accepted as written; `defineConfig` refuses two spellings of one version under one name so a file name always maps back to one label.
 
 `SchemaVersioning.isPinned(version)` answers whether a label names a published document rather than a prerelease — SemVer §9 makes a prerelease's own instability explicit, so a contract change inside one breaks nobody's pin. It is the one predicate the pipeline's contract gate and `SchemaVersioning.next` both read, so the two can never disagree about the same label. `next(current, change)` is the version a `WriteChange` classification calls for: identity for anything but a `"contract"` change on a pinned label, otherwise a MINOR bump on the 0.x line (0.x treats MINOR as the breaking axis) or MAJOR above it — always strictly greater, never a minted prerelease.
 
@@ -243,6 +245,7 @@ const targets = [
     schema: Schema.Struct({ name: Schema.String }),
     $id: "https://example.com/config.schema.json",
     path: "schemas/config.schema.json",
+    jsonSchema: { onExcessProperty: "error" },
   }),
 ];
 
@@ -268,6 +271,8 @@ provide the same value cannot disagree about what the layer contains.
 
 A target names its schema, its `$id` and where the file goes. `name` is optional and only catalog naming reads it, so a file-only target like the one above does not repeat its path's basename; supply it when you also pass a `version`, since versioned naming is `<name>-<version>.json`.
 
+`jsonSchema` is optional too, and carries core's `Schema.ToJsonSchemaOptions` for that one target. Set it when the document's shape must not follow core's defaults: `onExcessProperty: "error"` keeps a published closed-object document closed, where the open-by-default generator would otherwise flip every struct's `additionalProperties` and the contract gate would refuse the rewrite. Living on the target rather than in the pipeline options keeps each document's generation contract self-describing.
+
 Both gates' findings normalize into one `PipelineFinding` shape, so a single predicate judges them. Gating is **policy, not mechanism**: `blocking` defaults to `severity === "warning"`, which is what `UnresolvedRef`, `UnknownKeyword` and `DepthExceeded` are. Replace the predicate rather than the loop when you disagree.
 
 ```ts
@@ -326,7 +331,7 @@ The classification is key-order insensitive and keyword-position aware, like the
 - `DocumentDiff` — `classify` puts two documents in `"none"` / `"annotations"` / `"contract"`, the signal for whether a change needs a new schema version, plus `isClean` for the clean case.
 - `SchemaPipeline` — the emit loop over a target manifest, two-phase and all-or-nothing across targets: `run` and `check`, the single-target `runOne` and `checkOne`, `PipelineFinding`, `SchemaGateError` and an overridable gating predicate, plus the contract gate (`ContractChangePolicy`, `ContractChangeTarget`, `SchemaContractChangeError`, `PipelineCheckResult.contractBlocked`) that refuses to rewrite a published document's validation contract in place.
 - `SchemaFile` — write-if-changed IO over core `FileSystem` / `Path`, comparing by content and answering what changed as a value; `check` is the non-writing drift half, answering `wouldWrite` alongside `change`.
-- `SchemaTarget` — the target manifest vocabulary: schema, `$id`, destination path, an optional name and an optional version that requires one.
+- `SchemaTarget` — the target manifest vocabulary: schema, `$id`, destination path, an optional name, an optional version that requires one, and optional per-target `jsonSchema` generation options.
 - `CanonicalJson` — the deterministic serializer with typed failures (`NonJsonValueError`, `JsonDepthExceededError`).
 
 ## License

package/SchemaPipeline.js

@@ -195,7 +195,10 @@ var SchemaPipeline = class SchemaPipeline {
 			const held = [];
 			const blocked = [];
 			for (const target of targets) {
-				const document = yield* StoreDocument.fromSchema(target.schema, { $id: target.$id });
+				const document = yield* StoreDocument.fromSchema(target.schema, {
+					$id: target.$id,
+					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {}
+				});
 				const findings = yield* gather(document, options);
 				yield* gate(target, findings, options);
 				const version = target.version;
@@ -248,7 +251,10 @@ var SchemaPipeline = class SchemaPipeline {
 			const files = yield* SchemaFile;
 			const results = [];
 			for (const target of targets) {
-				const document = yield* StoreDocument.fromSchema(target.schema, { $id: target.$id });
+				const document = yield* StoreDocument.fromSchema(target.schema, {
+					$id: target.$id,
+					...target.jsonSchema !== void 0 ? { jsonSchema: target.jsonSchema } : {}
+				});
 				const findings = yield* gather(document, options);
 				const { wouldWrite, change } = yield* files.check(target.path, document, options?.write);
 				results.push({

package/SchemaTarget.js

@@ -1,3 +1,6 @@
+import { SchemaVersioning } from "./SchemaVersioning.js";
+import { Result } from "effect";
+
 //#region src/SchemaTarget.ts
 /**
 * Constructors for `SchemaTarget` values.
@@ -10,18 +13,23 @@ var SchemaTarget = class {
 	* 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.
+	* overloads above; the runtime check remains for untyped callers. A
+	* string `version` that fails {@link SchemaVersioning.parseResult} throws,
+	* naming the invalid label.
 	*/
 	static make(options) {
 		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)");
+		const version = options.version === void 0 ? void 0 : Result.getOrThrowWith(SchemaVersioning.parseResult(options.version), (error) => /* @__PURE__ */ new Error(`SchemaTarget.make received an invalid version label "${options.version}": ${error.message}`));
 		return {
 			schema: options.schema,
 			$id: options.$id,
 			path: options.path,
+			published: options.published ?? false,
 			...options.name !== void 0 ? { name: options.name } : {},
-			...options.version !== void 0 ? { version: options.version } : {}
+			...version !== void 0 ? { version } : {},
+			...options.jsonSchema !== void 0 ? { jsonSchema: options.jsonSchema } : {}
 		};
 	}
 };

package/SchemaVersioning.js

@@ -2,9 +2,27 @@ import { Effect, Option, Order, Result, Schema } from "effect";
 import { SemVer } from "@effected/semver";
 
 //#region src/SchemaVersioning.ts
+const LABEL = /^(0|[1-9]\d*)(?:\.(0|[1-9]\d*)){0,2}(-[0-9A-Za-z.-]+)?$/;
+const split = (input) => {
+	if (!LABEL.test(input)) return;
+	const dash = input.indexOf("-");
+	const core = dash === -1 ? input : input.slice(0, dash);
+	const prerelease = dash === -1 ? "" : input.slice(dash);
+	return {
+		core: core.split("."),
+		prerelease
+	};
+};
+/** Pad a 1–3 component core to `major.minor.patch` so SemVer can order it. */
+const padded = (parts) => `${[
+	...parts.core,
+	"0",
+	"0"
+].slice(0, 3).join(".")}${parts.prerelease}`;
 const isVersionLabel = (input) => {
-	if (!SemVer.isValid(input)) return false;
-	const parsed = SemVer.parseResult(input);
+	const parts = split(input);
+	if (parts === void 0) return false;
+	const parsed = SemVer.parseResult(padded(parts));
 	return Result.isSuccess(parsed) && parsed.success.build.length === 0;
 };
 /**
@@ -22,29 +40,34 @@ input: Schema.String }) {
 	}
 };
 /**
-* 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.
+* A schema version label: a branded string holding one, two or three
+* dot-separated numeric components — `major`, `major.minor` or
+* `major.minor.patch` — with an optional SemVer prerelease. Build metadata
+* is rejected (see below).
 *
-* The label round-trips verbatim into file names and catalog `versions`
-* keys; ordering parses it directly (see {@link SchemaVersioning.Order}).
+* This matches SchemaStore's own corpus, which commonly uses partial labels
+* like `agripparc-1.2.json`. The label is preserved VERBATIM — it is the
+* file name and the URL — and a missing component is read as zero only for
+* ordering (see {@link SchemaVersioning.Order}), never rewritten into the
+* label itself.
 *
 * @public
 */
-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 SchemaVersion = Schema.String.check(Schema.makeFilter((value) => isVersionLabel(value) ? void 0 : "must be a major, major.minor or major.minor.patch version label")).pipe(Schema.brand("SchemaVersion"));
 const orderingKey = (label) => {
-	const result = SemVer.parseResult(label);
-	if (Result.isFailure(result)) throw new Error(`SchemaVersion ordering invariant violated for label "${label}"`);
+	const parts = split(label);
+	const result = parts === void 0 ? void 0 : SemVer.parseResult(padded(parts));
+	if (result === void 0 || Result.isFailure(result)) throw new Error(`SchemaVersion ordering invariant violated for label "${label}"`);
 	return result.success;
 };
-const bumpBreaking = (current, parsed) => {
+const bumpNext = (current, parsed, components) => {
 	try {
-		return parsed.major === 0 ? parsed.bump.minor() : parsed.bump.major();
+		const bumped = components === 1 ? parsed.bump.major() : parsed.bump.minor();
+		return [
+			bumped.major,
+			bumped.minor,
+			bumped.patch
+		].slice(0, components).join(".");
 	} catch (cause) {
 		throw new Error(`SchemaVersion bump invariant violated: "${current}" cannot be bumped past Number.MAX_SAFE_INTEGER (${Number.MAX_SAFE_INTEGER})`, { cause });
 	}
@@ -63,8 +86,10 @@ const joinUrl = (baseUrl, file) => {
 * — SchemaStore's own suffix convention — a `versions` map, and `url`
 * pointing at the latest version).
 *
-* 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`.
+* Version labels are 1–3 dot-separated numeric components with an optional
+* prerelease; ordering reads a missing component as zero and otherwise
+* follows plain SemVer precedence: `1.10` above `1.9`, `2.0.0-beta` below
+* `2.0.0`.
 *
 * @public
 */
@@ -112,6 +137,15 @@ var SchemaVersioning = class SchemaVersioning {
 		return orderingKey(version).prerelease.length === 0;
 	}
 	/**
+	* The number of dot-separated numeric components in a label's core:
+	* `1` for `"1"` (or `"1-beta"`), `2` for `"1.2"`, `3` for `"1.2.3"`.
+	*/
+	static components(version) {
+		const parts = split(version);
+		if (parts === void 0) throw new Error(`SchemaVersion components invariant violated for label "${version}"`);
+		return parts.core.length;
+	}
+	/**
 	* The version label a change classification calls for. Pure and
 	* synchronous; total over validated labels — a non-label input is a wiring
 	* bug and dies as a defect, the same as {@link SchemaVersioning.Order}.
@@ -123,13 +157,15 @@ var SchemaVersioning = class SchemaVersioning {
 	*   declares its own instability; the pipeline's `"block-versioned"`
 	*   policy uses the same {@link SchemaVersioning.isPinned}, so the gate
 	*   and the bump agree.
-	* - `major === 0` → MINOR bump (`0.4.0` → `0.5.0`): on the 0.x line MINOR
-	*   is the breaking axis.
-	* - otherwise → MAJOR bump (`5.0.0` → `6.0.0`).
+	* - otherwise → a MINOR bump, preserving the component count
+	*   ({@link SchemaVersioning.components}): `1.2.3` → `1.3.0`, `1.2` →
+	*   `1.3`, `0.4` → `0.5`. On a one-component label the only axis IS
+	*   major: `1` → `2`.
 	*
 	* The bump's job is to be strictly greater and conspicuous, NOT to encode
 	* SemVer compatibility: `DocumentDiff` cannot tell an added optional
 	* property from a removed required one, so every contract change reads as
+	* breaking — the author bumps MAJOR by hand when they know the change is
 	* breaking. Each label is its own file and URL, so an over-bump costs a
 	* file; an under-bump would overwrite a pinned document. `next` never
 	* introduces a prerelease from a stable input.
@@ -140,7 +176,7 @@ var SchemaVersioning = class SchemaVersioning {
 	*/
 	static next(current, change) {
 		if (change !== "contract" || !SchemaVersioning.isPinned(current)) return current;
-		const label = bumpBreaking(current, orderingKey(current)).toString();
+		const label = bumpNext(current, orderingKey(current), SchemaVersioning.components(current));
 		const reparsed = SchemaVersioning.parseResult(label);
 		if (Result.isFailure(reparsed)) throw new Error(`SchemaVersion bump invariant violated: "${current}" bumped to "${label}"`);
 		return reparsed.success;
@@ -173,13 +209,14 @@ 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} 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.
+	* Labels are inserted in ascending {@link SchemaVersioning.Order}, but a
+	* bare-major label (`"2"`) is array-index-like, so JavaScript enumerates
+	* it FIRST regardless of insertion order — the serialized order of the
+	* `versions` map is not meaningful when such a label is present. A two-
+	* or three-component label is never integer-like and keeps insertion
+	* order through serialization. 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/SchemastoreConfig.js

@@ -0,0 +1,118 @@
+import { SchemaVersioning } from "./SchemaVersioning.js";
+import { CatalogEntry } from "./CatalogEntry.js";
+import { DriftPolicy } from "./DriftPolicy.js";
+import { 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;
+};
+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 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}"`);
+		versions.push(version);
+		map.set(target.name, versions);
+	}
+	return map;
+};
+const normalizePath = (raw) => {
+	const absolute = raw.startsWith("/");
+	const out = [];
+	for (const segment of raw.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (out.length > 0 && out[out.length - 1] !== "..") out.pop();
+			else if (!absolute) out.push(segment);
+			continue;
+		}
+		out.push(segment);
+	}
+	return `${absolute ? "/" : ""}${out.join("/")}`;
+};
+const assertUniquePaths = (schemas, catalog) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const p of [...schemas.map((target) => target.path), ...catalog.map((entry) => entry.path)]) {
+		const normalized = normalizePath(p);
+		if (seen.has(normalized)) throw new Error(`defineConfig: output path "${p}" is declared twice`);
+		seen.add(normalized);
+	}
+};
+/**
+* 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.
+*
+* @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));
+	return {
+		[ConfigBrand]: true,
+		schemas: input.schemas,
+		catalog,
+		drift: {
+			policy: drift.policy ?? DriftPolicy.defaults.policy,
+			onDrift: drift.onDrift ?? DriftPolicy.defaults.onDrift
+		}
+	};
+};
+/**
+* Whether a value is a config produced by {@link defineConfig} — the check a
+* loader runs on a config module's default export.
+*
+* @public
+*/
+const isSchemastoreConfig = (value) => typeof value === "object" && value !== null && value[ConfigBrand] === true;
+
+//#endregion
+export { defineConfig, isSchemastoreConfig };

package/index.d.ts

@@ -577,17 +577,16 @@ export declare class InvalidSchemaVersionError extends InvalidSchemaVersionError
   get message(): string;
 }
 /**
- * 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).
+ * A schema version label: a branded string holding one, two or three
+ * dot-separated numeric components — `major`, `major.minor` or
+ * `major.minor.patch` — with an optional SemVer prerelease. 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}).
+ * This matches SchemaStore's own corpus, which commonly uses partial labels
+ * like `agripparc-1.2.json`. The label is preserved VERBATIM — it is the
+ * file name and the URL — and a missing component is read as zero only for
+ * ordering (see {@link SchemaVersioning.Order}), never rewritten into the
+ * label itself.
  *
  * @public
  */
@@ -608,9 +607,14 @@ interface CatalogUrls {
   /** The catalog `url` — the unversioned file, or the latest versioned file. */
   readonly url: string;
   /**
-   * The versioned catalog's `versions` map (label → url), inserted — and,
-   * since a three-component label can never be integer-like, enumerated
-   * and serialized — in ascending version order.
+   * The versioned catalog's `versions` map (label → url), inserted in
+   * ascending version order.
+   *
+   * A bare-major label (`"2"`) is array-index-like, so JavaScript
+   * enumerates it FIRST regardless of insertion order — the serialized
+   * order of such a key is therefore not meaningful. A two- or
+   * three-component label is never integer-like and keeps insertion order
+   * through serialization.
    */
   readonly versions?: Readonly<Record<string, string>>;
 }
@@ -620,8 +624,10 @@ interface CatalogUrls {
  * — SchemaStore's own suffix convention — a `versions` map, and `url`
  * pointing at the latest version).
  *
- * 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`.
+ * Version labels are 1–3 dot-separated numeric components with an optional
+ * prerelease; ordering reads a missing component as zero and otherwise
+ * follows plain SemVer precedence: `1.10` above `1.9`, `2.0.0-beta` below
+ * `2.0.0`.
  *
  * @public
  */
@@ -662,6 +668,11 @@ export declare class SchemaVersioning {
    * deadlock.
    */
   static isPinned(version: SchemaVersion): boolean;
+  /**
+   * The number of dot-separated numeric components in a label's core:
+   * `1` for `"1"` (or `"1-beta"`), `2` for `"1.2"`, `3` for `"1.2.3"`.
+   */
+  static components(version: SchemaVersion): 1 | 2 | 3;
   /**
    * The version label a change classification calls for. Pure and
    * synchronous; total over validated labels — a non-label input is a wiring
@@ -674,13 +685,15 @@ export declare class SchemaVersioning {
    *   declares its own instability; the pipeline's `"block-versioned"`
    *   policy uses the same {@link SchemaVersioning.isPinned}, so the gate
    *   and the bump agree.
-   * - `major === 0` → MINOR bump (`0.4.0` → `0.5.0`): on the 0.x line MINOR
-   *   is the breaking axis.
-   * - otherwise → MAJOR bump (`5.0.0` → `6.0.0`).
+   * - otherwise → a MINOR bump, preserving the component count
+   *   ({@link SchemaVersioning.components}): `1.2.3` → `1.3.0`, `1.2` →
+   *   `1.3`, `0.4` → `0.5`. On a one-component label the only axis IS
+   *   major: `1` → `2`.
    *
    * The bump's job is to be strictly greater and conspicuous, NOT to encode
    * SemVer compatibility: `DocumentDiff` cannot tell an added optional
    * property from a removed required one, so every contract change reads as
+   * breaking — the author bumps MAJOR by hand when they know the change is
    * breaking. Each label is its own file and URL, so an over-bump costs a
    * file; an under-bump would overwrite a pinned document. `next` never
    * introduces a prerelease from a stable input.
@@ -713,13 +726,14 @@ export declare 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} 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.
+   * Labels are inserted in ascending {@link SchemaVersioning.Order}, but a
+   * bare-major label (`"2"`) is array-index-like, so JavaScript enumerates
+   * it FIRST regardless of insertion order — the serialized order of the
+   * `versions` map is not meaningful when such a label is present. A two-
+   * or three-component label is never integer-like and keeps insertion
+   * order through serialization. Deriving ordering from the labels
+   * themselves (as {@link SchemaVersioning.latest} does) is still the
+   * robust read.
    */
   static catalogUrls(options: {
     readonly baseUrl: string;
@@ -774,7 +788,10 @@ 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.
+   * derived), omit it for the unversioned mode. 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.
    */
   static assemble(options: {
     readonly name: string;
@@ -844,6 +861,64 @@ export declare class DocumentLint {
   static lint(document: StoreDocument): ReadonlyArray<DocumentLintFinding>;
 }
 //#endregion
+//#region src/DriftPolicy.d.ts
+/**
+ * How much change a PUBLISHED schema document may absorb before a build is
+ * refused.
+ *
+ * @remarks
+ * - `"strict"` — any content change (`annotations` or `contract`) is drift.
+ * - `"semantic"` — only a `contract` change is drift; documentation-only
+ *   keywords rewrite in place.
+ * - `"allow"` — nothing is drift; the document rewrites in place.
+ *
+ * @public
+ */
+type DriftTolerance = "strict" | "semantic" | "allow";
+/**
+ * What a build does when it finds drift: refuse to write anything, or write
+ * and warn.
+ *
+ * @public
+ */
+type OnDrift = "error" | "warn";
+/**
+ * The drift settings a config declares and a CLI flag may override.
+ *
+ * @public
+ */
+interface DriftOptions {
+  readonly policy: DriftTolerance;
+  readonly onDrift: OnDrift;
+}
+/**
+ * The verdict for one target: write it, or hold it as drift.
+ *
+ * @public
+ */
+type DriftVerdict = "write" | "drift";
+/**
+ * Classifies one target's change against a drift tolerance.
+ *
+ * @remarks
+ * Pure and synchronous. The lifecycle rule is fixed here so no caller
+ * relitigates it: an unpublished target is NEVER drift — it is regenerated
+ * in place until someone depends on its label. Gate failures (lint warnings,
+ * validator findings) are not drift either and are not this module's
+ * concern.
+ *
+ * @public
+ */
+export declare class DriftPolicy {
+  private constructor();
+  /** `{ policy: "semantic", onDrift: "error" }` — what a config gets when it says nothing. */
+  static readonly defaults: DriftOptions;
+  static classify(input: {
+    readonly published: boolean;
+    readonly change: WriteChange;
+  }, policy: DriftTolerance): DriftVerdict;
+}
+//#endregion
 //#region src/KeywordFamilies.d.ts
 /**
  * The one owner of the declared non-standard keyword families, in two
@@ -969,6 +1044,30 @@ export interface SchemaTarget {
    * rewritten in place.
    */
   readonly version?: SchemaVersion;
+  /**
+   * Whether a consumer already depends on this document at this label.
+   *
+   * @remarks
+   * The lifecycle switch the drift policy reads: an unpublished target is
+   * always regenerated in place, a published one is held to the configured
+   * drift tolerance. Defaults to `false`. The library's own
+   * `contractChanges: "block-versioned"` policy keys on a pinned `version`,
+   * not on this flag — the CLI is what reads it.
+   */
+  readonly published: boolean;
+  /**
+   * Options passed through to {@link StoreDocument.fromSchema} (and, from
+   * there, core's `Schema.toJsonSchemaDocument`).
+   *
+   * A target-level field rather than a pipeline-wide default keeps each
+   * document's generation contract self-describing, so
+   * {@link SchemaPipeline} reproduces a document deterministically
+   * regardless of core's own default — for example, an `onExcessProperty`
+   * setting of `error` restores closed objects after rc.113 flipped that
+   * default open. See {@link StoreDocumentOptions.jsonSchema} for the
+   * `includeAnnotationKey` gate this option is also subject to.
+   */
+  readonly jsonSchema?: Schema.ToJsonSchemaOptions;
 }
 /**
  * Constructors for `SchemaTarget` values.
@@ -986,19 +1085,24 @@ export declare class SchemaTarget {
     readonly $id: string;
     readonly name?: string;
     readonly path: string;
+    readonly published?: boolean;
+    readonly jsonSchema?: Schema.ToJsonSchemaOptions;
   }): SchemaTarget;
   /**
    * Builds a versioned target. `name` is **required** here: versioned
    * catalog naming is `name-<version>.json`, so a version without a name
    * cannot be resolved — the overload pair makes that unrepresentable
-   * rather than a runtime throw.
+   * rather than a runtime throw. `version` also accepts a plain string
+   * label, parsed via {@link SchemaVersioning.parseResult}.
    */
   static make(options: {
     readonly schema: Schema.Constraint;
     readonly $id: string;
     readonly name: string;
     readonly path: string;
-    readonly version: SchemaVersion;
+    readonly version: SchemaVersion | string;
+    readonly published?: boolean;
+    readonly jsonSchema?: Schema.ToJsonSchemaOptions;
   }): SchemaTarget;
 }
 //#endregion
@@ -1460,5 +1564,81 @@ export declare class SchemaPipeline {
   static checkOne(target: SchemaTarget, options?: SchemaPipelineOptions): Effect.Effect<PipelineCheckResult, SchemaConversionError | UndeclaredAnnotationKeyError | SchemaValidatorError | CanonicalJsonError | SchemaFileReadError, SchemaFile | SchemaValidator>;
 }
 //#endregion
-export type { CanonicalJsonError, CanonicalJsonOptions, CatalogUrls, CheckResult, ContractChangePolicy, PipelineCheckResult, PipelineResult, SchemaChange, SchemaFileShape, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
+//#region src/SchemastoreConfig.d.ts
+declare const ConfigBrand: unique symbol;
+/**
+ * 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`.
+ *
+ * @public
+ */
+interface CatalogConfig {
+  readonly name: string;
+  readonly description: string;
+  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.
+ *
+ * @public
+ */
+interface SchemastoreConfigInput {
+  readonly schemas: ReadonlyArray<SchemaTarget>;
+  readonly catalog?: ReadonlyArray<CatalogConfig>;
+  readonly drift?: Partial<DriftOptions>;
+}
+/**
+ * A validated catalog declaration paired with the `CatalogEntry` assembled
+ * from it.
+ *
+ * @public
+ */
+interface CatalogTarget {
+  readonly config: CatalogConfig;
+  readonly entry: CatalogEntry;
+}
+/**
+ * The validated, defaults-filled config {@link defineConfig} answers and the
+ * CLI consumes. Recognisable via {@link isSchemastoreConfig}.
+ *
+ * @public
+ */
+interface SchemastoreConfig {
+  readonly [ConfigBrand]: true;
+  readonly schemas: ReadonlyArray<SchemaTarget>;
+  readonly catalog: ReadonlyArray<CatalogTarget>;
+  readonly drift: DriftOptions;
+}
+/**
+ * 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.
+ *
+ * @public
+ */
+export declare const defineConfig: (input: SchemastoreConfigInput) => SchemastoreConfig;
+/**
+ * Whether a value is a config produced by {@link defineConfig} — the check a
+ * loader runs on a config module's default export.
+ *
+ * @public
+ */
+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 };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -4,10 +4,12 @@ import { CatalogEntry, CatalogLintFinding } from "./CatalogEntry.js";
 import { KeywordFamilies } from "./KeywordFamilies.js";
 import { DocumentDiff } from "./DocumentDiff.js";
 import { DocumentLint, DocumentLintFinding } from "./DocumentLint.js";
+import { DriftPolicy } from "./DriftPolicy.js";
 import { SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError } from "./SchemaFile.js";
 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";
 
-export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore",
-	"version": "0.7.0",
+	"version": "0.9.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": [