@effected/schemastore-cli 0.9.1 → 0.11.0

package/ConfigLoader.js

@@ -1,4 +1,4 @@
-import { Effect, FileSystem, Path, Schema } from "effect";
+import { Effect, FileSystem, Path, Predicate, Schema } from "effect";
 import { isSchemastoreConfig } from "@effected/schemastore";
 import { createJiti } from "jiti";
 
@@ -19,8 +19,9 @@ searched: Schema.Array(Schema.String) }) {
 /**
 * The config file exists but could not be turned into a `SchemastoreConfig`:
 * the module threw on import, its default export is not a `defineConfig(...)`
-* value, a `schemas` element is not `SchemaTarget`-shaped, or two outputs
-* resolve to one absolute path.
+* value, `outputDir`/`catalogPath` is not a string, a `schemas` element is
+* not resolved-schema-shaped (or its `target`, `catalog`, or a `frozen`
+* entry is not shaped), or two outputs resolve to one absolute path.
 *
 * @public
 */
@@ -34,16 +35,22 @@ var ConfigLoadError = class extends Schema.TaggedError()("ConfigLoadError", {
 };
 const jitiImport = (path) => createJiti(path, { interopDefault: true }).import(path);
 const describeCause = (cause) => cause instanceof Error ? cause.stack ?? cause.message : String(cause);
-const describeMalformedTarget = (schemas) => {
-	if (!Array.isArray(schemas)) return "schemas is not an array";
-	for (const [index, target] of schemas.entries()) {
-		const record = typeof target === "object" && target !== null ? target : void 0;
-		if (!(record !== void 0 && Schema.isSchema(record.schema) && typeof record.$id === "string" && typeof record.path === "string" && typeof record.published === "boolean")) return `schemas[${index}] is not a SchemaTarget (missing schema/$id/path/published)`;
+const isTargetShaped = (target) => Predicate.isObject(target) && Schema.isSchema(target.schema) && typeof target.$id === "string" && typeof target.path === "string" && typeof target.published === "boolean";
+const isCatalogEntryShaped = (catalog) => Predicate.isObject(catalog) && typeof catalog.name === "string" && typeof catalog.description === "string" && Array.isArray(catalog.fileMatch) && typeof catalog.url === "string";
+const describeMalformed = (config) => {
+	if (typeof config.outputDir !== "string") return "outputDir is not a string";
+	if (typeof config.catalogPath !== "string") return "catalogPath is not a string";
+	if (!Array.isArray(config.schemas)) return "schemas is not an array";
+	for (const [index, schema] of config.schemas.entries()) {
+		if (!Predicate.isObject(schema) || typeof schema.name !== "string" || !Array.isArray(schema.frozen) || typeof schema.drift !== "string") return `schemas[${index}] is not a resolved schema (missing name/target/frozen/drift)`;
+		if (!isTargetShaped(schema.target)) return `schemas[${index}].target is not a SchemaTarget (missing schema/$id/path/published)`;
+		if (schema.catalog !== void 0 && !isCatalogEntryShaped(schema.catalog)) return `schemas[${index}].catalog is not a catalog entry (missing name/description/fileMatch/url)`;
+		for (const [j, frozen] of schema.frozen.entries()) if (!Predicate.isObject(frozen) || typeof frozen.version !== "string" || typeof frozen.path !== "string" || typeof frozen.url !== "string") return `schemas[${index}].frozen[${j}] is not a frozen version (missing version/path/url)`;
 	}
 };
 const describeDuplicatePath = (config) => {
 	const seen = /* @__PURE__ */ new Set();
-	const paths = [...config.schemas.map((target) => target.path), ...config.catalog.map((c) => c.config.path)];
+	const paths = [...config.schemas.flatMap((schema) => [schema.target.path, ...schema.frozen.map((f) => f.path)]), config.catalogPath];
 	for (const p of paths) {
 		if (seen.has(p)) return `output path "${p}" is declared twice after resolution`;
 		seen.add(p);
@@ -92,25 +99,30 @@ var ConfigLoader = class ConfigLoader {
 		}
 	});
 	/**
-	* Resolve every relative `path` in the config (schema targets and catalog
-	* entries) against `directory`; absolute paths are left alone. The result
-	* keeps the `defineConfig` brand.
+	* Resolve every relative `path` in the config (`outputDir`, `catalogPath`,
+	* each schema's current target, and every frozen predecessor) against
+	* `directory`; absolute paths are left alone. `defineConfig` already
+	* prefixes `outputDir` onto every target/frozen `path`, so resolving them
+	* against the config directory equals resolving against the resolved
+	* `outputDir`. The result keeps the `defineConfig` brand.
 	*/
 	static resolvePaths = Effect.fn("ConfigLoader.resolvePaths")(function* (config, directory) {
 		const path = yield* Path.Path;
 		const absolute = (p) => path.isAbsolute(p) ? p : path.resolve(directory, p);
 		return {
 			...config,
-			schemas: config.schemas.map((target) => ({
-				...target,
-				path: absolute(target.path)
-			})),
-			catalog: config.catalog.map((c) => ({
-				...c,
-				config: {
-					...c.config,
-					path: absolute(c.config.path)
-				}
+			outputDir: absolute(config.outputDir),
+			catalogPath: absolute(config.catalogPath),
+			schemas: config.schemas.map((schema) => ({
+				...schema,
+				target: {
+					...schema.target,
+					path: absolute(schema.target.path)
+				},
+				frozen: schema.frozen.map((f) => ({
+					...f,
+					path: absolute(f.path)
+				}))
 			}))
 		};
 	});
@@ -136,7 +148,7 @@ var ConfigLoader = class ConfigLoader {
 			path: configPath,
 			reason: "default export is not a defineConfig(...) value from @effected/schemastore"
 		}));
-		const malformed = describeMalformedTarget(exported.schemas);
+		const malformed = describeMalformed(exported);
 		if (malformed !== void 0) return yield* Effect.fail(new ConfigLoadError({
 			path: configPath,
 			reason: malformed

package/README.md

@@ -38,37 +38,30 @@ pnpm add -D @effected/schemastore-cli @effected/schemastore effect
 Create `schemastore.config.ts` (also `.mts`, `.js`, `.mjs`). The CLI finds it by walking upward from the working directory, or takes its path as a positional argument. Relative `path` values resolve against the config file's directory.
 
 ```ts
-import { defineConfig, SchemaTarget } from "@effected/schemastore";
-import { ReleaseOutput, SCHEMA_URL } from "./src/schema/release-output.js";
+import { defineConfig } from "@effected/schemastore";
+import { OkfitConfig } from "./src/config-schema.js";
 
 export default defineConfig({
- schemas: [
-  SchemaTarget.make({
-   schema: ReleaseOutput,
-   $id: SCHEMA_URL,
-   name: "silk-release-action",
-   version: "5.0.0",
-   path: "schemas/silk-release-action-5.0.0.json",
+ outputDir: "schemas",
+ baseUrl: "schemastore",
+ schemas: {
+  okfit: {
+   schema: OkfitConfig,
+   versions: ["1.0"],
    published: true,
-   jsonSchema: { onExcessProperty: "error" },
-  }),
- ],
- catalog: [
-  {
-   name: "silk-release-action",
-   description: "Structured output of the silk-release GitHub Action",
-   fileMatch: ["silk-release-output.json"],
-   baseUrl: "https://raw.githubusercontent.com/savvy-web/silk-release-action/main/schemas",
-   path: "schemas/catalog-entry.json",
+   catalog: { description: "okfit configuration", fileMatch: ["okfit.toml", ".okfit.toml"] },
   },
- ],
- drift: { policy: "semantic", onDrift: "error" },
+ },
 });
 ```
 
-- `schemas` — at least one `SchemaTarget`; `published` (default `false`) marks a version other people depend on.
-- `catalog` — zero or more SchemaStore catalog entries; `versions` is derived from every versioned schema of that name. The entry's `url` and each `versions` value are derived as `<baseUrl>/<name>-<version>.json`, so every schema's `path` must sit directly under the directory `baseUrl` names and its `$id` must be that exact URL — the CLI does not yet cross-check them.
-- `drift` — the default policy for published schemas (`strict`, `semantic` or `allow`) and what drift means (`error` or `warn`). Defaults to `{ policy: "semantic", onDrift: "error" }`.
+A second label is appended to `versions` only once the first is published
+and its file already exists on disk — see "The lifecycle" in the
+`building-schemastore-schemas` skill's `drift-and-versioning.md` reference.
+A first-run config should declare a single label; naming an extra one before
+its file exists fails the build with `FrozenVersionMissingError`.
+
+`schemas` is keyed by file base name — the key IS the schema's `name`, and `$id`, the write `path` and every catalog URL derive from it, `outputDir` and `baseUrl`; there is no `$id` override. `versions` lists every label the catalog advertises; `current` (default: the newest) is the one generated at `path`/`$id`, and every other label becomes a **frozen** file the CLI verifies still exists on disk but never regenerates — advertising a frozen label with nothing on disk fails the build before anything is written. `published` (default `false`) marks a version other people already depend on. `baseUrl: "schemastore"` expands `$id` to `https://json.schemastore.org/…` and the catalog URL to `https://www.schemastore.org/…`; any other value is one `https://` base for both. `outputDir` and `onDrift` are top-level only; `baseUrl` and `drift` are top-level defaults an entry may override. `catalog` is required under `baseUrl: "schemastore"` and optional under a custom host. Every schema's declared `catalog` entry lands in ONE file at `catalogPath` (default `<outputDir>/catalog.json`) — never one file per schema.
 
 Then add two scripts:
 
@@ -88,10 +81,11 @@ schemastore build [config] [--drift=strict|semantic|allow] [--on-drift=error|war
 schemastore check [config] [--drift=strict|semantic|allow] [--on-drift=error|warn] [--force] [--format=human|json]
 ```
 
-- `build` generates every schema, runs the gates (structural lints and ajv strict mode), applies the drift policy, and writes what passes — content-compared, so unchanged files are untouched — along with each catalog entry.
-- `check` is the identical walk with no writes: it reports what `build` would do under the same flags and exits under the same conditions. It is the CI gate, so it also fails (exit `1`) whenever a build would write anything — a committed schema or catalog entry that differs from what the config generates, or is missing, is stale; run `schemastore build` and commit the result.
-- `--drift` and `--on-drift` override the config's `drift` block for one run; `--force` is sugar for `--drift=allow`.
-- `--format=json` emits one JSON document on stdout (config path, per-schema outcome, per-catalog-entry outcome, effective drift policy and its source); human text moves to stderr.
+- Before anything is generated, every advertised frozen version is checked for existence — a schema that advertises a label with nothing on disk fails with `FrozenVersionMissingError` (exit `1`) and nothing is written.
+- `build` generates every schema, runs the gates (structural lints and ajv strict mode), applies the drift policy, and writes what passes — content-compared, so unchanged files are untouched — along with the single `catalog.json` every declared catalog entry lands in.
+- `check` is the identical walk with no writes: it reports what `build` would do under the same flags and exits under the same conditions. It is the CI gate, so it also fails (exit `1`) whenever a build would write anything — a committed schema or catalog file that differs from what the config generates, or is missing, is stale; run `schemastore build` and commit the result.
+- `--drift` and `--on-drift` override the config's `drift` block for one run; `--force` is sugar for `--drift=allow` and nothing else — combined with an explicit non-`allow` `--drift` it is a usage error (exit 64), not a precedence question; `--force --drift=allow` is accepted.
+- `--format=json` emits one JSON document on stdout (config path, per-schema outcome and effective drift tolerance, the single catalog entry's outcome, and `drift: { onDrift, policy? }` — `policy` present only when a flag forced one tolerance over every schema's own); human text moves to stderr.
 - When `GITHUB_STEP_SUMMARY` is set, both commands append a markdown summary table.
 
 An unpublished schema is never drift: a contract change at a pinned but unpublished version rewrites the file in place.
@@ -101,7 +95,7 @@ An unpublished schema is never drift: a contract change at a pinned but unpublis
 | code | meaning |
 | ---- | -------------------------------------------------------------------------- |
 | 0 | success, including drift under `onDrift: warn` |
-| 1 | drift under `onDrift: error`, a gate failure, or — for `check` — any document `build` would write |
+| 1 | drift under `onDrift: error` (the error lists one line per drifting schema: `$id`, change, current and next version), a gate failure, a missing frozen version (`FrozenVersionMissingError`), or — for `check` — any document `build` would write |
 | 2 | config not found, failed to load, or failed `SchemastoreConfig` validation |
 | 3 | infrastructure failure |
 | 64 | usage error |

package/Report.js

@@ -3,32 +3,36 @@ const findingLine = (finding) => `  ${finding.label} at "${finding.path}": ${fin
 const blockingCount = (findings) => findings.filter((finding) => finding.severity === "warning").length;
 const suggestionClause = (schema) => schema.nextVersion !== void 0 && schema.nextVersion !== schema.version ? ` → suggest ${schema.nextVersion}` : "";
 const publishedClause = (schema) => schema.version !== void 0 ? ` at published ${schema.version}` : "";
+const policyClause = (schema, report) => report.policy === void 0 ? ` [policy ${schema.policy}]` : "";
+const frozenClause = (schema) => schema.frozen.length > 0 ? ` (frozen: ${schema.frozen.join(", ")})` : "";
 const schemaLines = (schema, report) => {
+	const suffix = `${policyClause(schema, report)}${frozenClause(schema)}`;
 	switch (schema.outcome) {
-		case "written": return [`written (${schema.change}) ${schema.path}`];
-		case "unchanged": return [`unchanged ${schema.path}`];
-		case "would-write": return [`would write (${schema.change}) ${schema.path}`];
-		case "drift": return [`DRIFT ${schema.change}${publishedClause(schema)}${suggestionClause(schema)} — ${schema.path}`];
-		case "held": return [`held (${report.gateFailed ? "gate failed elsewhere" : "drift elsewhere"}) ${schema.path}`];
-		case "gate-failed": return [`GATE FAILED ${schema.path} (${blockingCount(schema.findings)} blocking finding(s))`, ...schema.findings.map(findingLine)];
+		case "written": return [`written (${schema.change}) ${schema.path}${suffix}`];
+		case "unchanged": return [`unchanged ${schema.path}${suffix}`];
+		case "would-write": return [`would write (${schema.change}) ${schema.path}${suffix}`];
+		case "drift": return [`DRIFT ${schema.change}${publishedClause(schema)}${suggestionClause(schema)} — ${schema.path}${suffix}`];
+		case "held": return [`held (${report.gateFailed ? "gate failed elsewhere" : "drift elsewhere"}) ${schema.path}${suffix}`];
+		case "gate-failed": return [`GATE FAILED ${schema.path}${suffix} (${blockingCount(schema.findings)} blocking finding(s))`, ...schema.findings.map(findingLine)];
 		default: return schema.outcome;
 	}
 };
 const catalogLine = (entry) => {
 	switch (entry.outcome) {
-		case "written": return `written catalog ${entry.path}`;
-		case "unchanged": return `unchanged catalog ${entry.path}`;
-		case "would-write": return `would write catalog ${entry.path}`;
-		case "held": return `held catalog ${entry.path}`;
+		case "written": return `written catalog ${entry.path} (${entry.entries} entries)`;
+		case "unchanged": return `unchanged catalog ${entry.path} (${entry.entries} entries)`;
+		case "would-write": return `would write catalog ${entry.path} (${entry.entries} entries)`;
+		case "held": return `held catalog ${entry.path} (${entry.entries} entries)`;
 		default: return entry.outcome;
 	}
 };
+const driftClause = (report) => `drift ${report.policy !== void 0 ? `${report.policy} (flag)` : "per schema (config)"}, on-drift ${report.onDrift}`;
 const summaryLine = (report) => {
 	const written = report.schemas.filter((schema) => schema.outcome === "written").length;
 	const unchanged = report.schemas.filter((schema) => schema.outcome === "unchanged").length;
 	const drift = report.schemas.filter((schema) => schema.verdict === "drift").length;
 	const gateFailed = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;
-	return `${report.schemas.length} schema(s): ${written} written, ${unchanged} unchanged, ${drift} drift, ${gateFailed} gate failed — drift policy ${report.drift.policy}/${report.drift.onDrift} (${report.drift.source})`;
+	return `${report.schemas.length} schema(s): ${written} written, ${unchanged} unchanged, ${drift} drift, ${gateFailed} gate failed — ${driftClause(report)}`;
 };
 const warningLine = (schema, report) => `warning: DRIFT ${schema.change}${publishedClause(schema)} ${report.mode === "build" ? "written" : "would write"} under --on-drift=warn — ${schema.path}`;
 const tableRow = (columns) => `| ${columns.join(" | ")} |`;
@@ -40,11 +44,19 @@ const tableRow = (columns) => `| ${columns.join(" | ")} |`;
 */
 var Report = class {
 	constructor() {}
-	/** stdout lines. */
+	/**
+	* stdout lines.
+	*
+	* @remarks
+	* The summary's `drift` count is the number of schemas whose VERDICT is
+	* `"drift"`, independent of `written`/`unchanged`: under
+	* `onDrift: "warn"` a drifting schema is written AND counted as drift,
+	* so the four counts need not sum to the schema total.
+	*/
 	static human(report) {
 		const lines = [];
 		for (const schema of report.schemas) lines.push(...schemaLines(schema, report));
-		for (const entry of report.catalog) lines.push(catalogLine(entry));
+		if (report.catalog !== void 0) lines.push(catalogLine(report.catalog));
 		lines.push(summaryLine(report));
 		return lines;
 	}
@@ -54,7 +66,7 @@ var Report = class {
 	* would be) written, so there is no drift to warn about.
 	*/
 	static warnings(report) {
-		if (report.drift.onDrift !== "warn" || report.gateFailed) return [];
+		if (report.onDrift !== "warn" || report.gateFailed) return [];
 		return report.schemas.filter((schema) => schema.verdict === "drift").map((schema) => warningLine(schema, report));
 	}
 	/** One JSON document, stable key order. */
@@ -63,20 +75,21 @@ var Report = class {
 			mode: report.mode,
 			configPath: report.configPath,
 			drift: {
-				policy: report.drift.policy,
-				onDrift: report.drift.onDrift,
-				source: report.drift.source
+				onDrift: report.onDrift,
+				...report.policy !== void 0 ? { policy: report.policy } : {}
 			},
 			schemas: report.schemas.map((schema) => ({
 				$id: schema.$id,
 				path: schema.path,
-				...schema.name !== void 0 ? { name: schema.name } : {},
+				name: schema.name,
 				...schema.version !== void 0 ? { version: schema.version } : {},
 				published: schema.published,
 				change: schema.change,
 				verdict: schema.verdict,
+				policy: schema.policy,
 				outcome: schema.outcome,
 				...schema.nextVersion !== void 0 ? { nextVersion: schema.nextVersion } : {},
+				...schema.frozen.length > 0 ? { frozen: schema.frozen } : {},
 				findings: schema.findings.map((finding) => ({
 					source: finding.source,
 					severity: finding.severity,
@@ -85,11 +98,11 @@ var Report = class {
 					message: finding.message
 				}))
 			})),
-			catalog: report.catalog.map((entry) => ({
-				name: entry.name,
-				path: entry.path,
-				outcome: entry.outcome
-			})),
+			...report.catalog !== void 0 ? { catalog: {
+				path: report.catalog.path,
+				entries: report.catalog.entries,
+				outcome: report.catalog.outcome
+			} } : {},
 			drifted: report.drifted,
 			gateFailed: report.gateFailed,
 			wrote: report.wrote
@@ -102,6 +115,7 @@ var Report = class {
 		lines.push(tableRow([
 			"schema",
 			"version",
+			"frozen",
 			"published",
 			"change",
 			"outcome"
@@ -110,26 +124,37 @@ var Report = class {
 			"---",
 			"---",
 			"---",
+			"---",
 			"---"
 		]));
 		for (const schema of report.schemas) lines.push(tableRow([
-			schema.name ?? schema.$id,
+			schema.name,
 			schema.version ?? "",
+			schema.frozen.join(", "),
 			schema.published ? "yes" : "no",
 			schema.change,
 			schema.outcome
 		]));
-		if (report.catalog.length > 0) {
-			lines.push("", tableRow(["catalog", "outcome"]), tableRow(["---", "---"]));
-			for (const entry of report.catalog) lines.push(tableRow([entry.name, entry.outcome]));
-		}
+		if (report.catalog !== void 0) lines.push("", tableRow([
+			"catalog",
+			"entries",
+			"outcome"
+		]), tableRow([
+			"---",
+			"---",
+			"---"
+		]), tableRow([
+			report.catalog.path,
+			String(report.catalog.entries),
+			report.catalog.outcome
+		]));
 		lines.push("");
 		if (report.gateFailed) {
 			const failed = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;
 			lines.push(`**Gate:** ${failed} schema(s) failed`);
 		} else if (report.drifted) {
 			const drifted = report.schemas.filter((schema) => schema.verdict === "drift").length;
-			lines.push(`**Drift:** ${drifted} schema(s) drifted under ${report.drift.policy}/${report.drift.onDrift}`);
+			lines.push(`**Drift:** ${drifted} schema(s) drifted — ${driftClause(report)}`);
 		} else lines.push("**Drift:** none");
 		lines.push("");
 		return lines.join("\n");

package/Runner.js

@@ -1,45 +1,73 @@
-import { Effect, FileSystem, Path, Schema } from "effect";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
 import { CanonicalJson, CatalogEntry, DriftPolicy, SchemaPipeline, SchemaVersioning } from "@effected/schemastore";
 
 //#region src/Runner.ts
-const pipelineOptions = { contractChanges: "allow" };
-const catalogText = (target) => CanonicalJson.serialize(Schema.encodeSync(CatalogEntry)(target.entry));
-const jsonEqual = (a, b) => {
-	if (a === b) return true;
-	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => jsonEqual(v, b[i]));
-	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
-	const left = a;
-	const right = b;
-	const keys = Object.keys(left);
-	return keys.length === Object.keys(right).length && keys.every((k) => Object.hasOwn(right, k) && jsonEqual(left[k], right[k]));
+/**
+* Indicates that one or more schemas advertise a version label (via
+* {@link ResolvedSchema.frozen}) whose file is missing on disk. Raised by
+* {@link Runner.run} before anything is generated — a build must never
+* publish a catalog pointing a frozen label at a 404. Every miss is
+* collected and reported at once, not just the first.
+*
+* @public
+*/
+var FrozenVersionMissingError = class extends Schema.TaggedError()("FrozenVersionMissingError", { 
+/** One entry per schema/version whose frozen file is missing or not a file. */
+missing: Schema.Array(Schema.Struct({
+	/** The schema's key in the config. */
+	name: Schema.String,
+	/** The missing frozen version label. */
+	version: Schema.String,
+	/** The path that does not exist. */
+	path: Schema.String
+})) }) {
+	get message() {
+		const lines = this.missing.map((entry) => `  schema "${entry.name}" version ${entry.version}: ${entry.path}`);
+		return `${this.missing.length} frozen version(s) advertised but not on disk; nothing was written.\n${lines.join("\n")}`;
+	}
 };
-const sameJson = (existing, text) => {
+const pipelineOptions = { contractChanges: "allow" };
+const orNone = (read) => read.pipe(Effect.map(Option.some), Effect.catchIf((error) => error.reason._tag === "NotFound", () => Effect.succeed(Option.none())));
+const pendingOutcome = (wouldWrite, refused) => !wouldWrite ? "unchanged" : refused ? "held" : "would-write";
+const parsesEqual = (existing, text) => {
 	try {
-		return jsonEqual(JSON.parse(existing), JSON.parse(text));
+		return CanonicalJson.equals(JSON.parse(existing), JSON.parse(text));
 	} catch {
 		return false;
 	}
 };
 /**
-* The shared `build` / `check` walk: classify every schema through
-* {@link DriftPolicy} over `SchemaPipeline.check`, then write through
-* `SchemaPipeline.run` only when nothing is refused.
+* The shared `build` / `check` walk: verify every advertised frozen version
+* exists, classify every current target through {@link DriftPolicy} over
+* `SchemaPipeline.check`, then write through `SchemaPipeline.run` only when
+* nothing is refused.
 *
 * @remarks
-* A build writes NOTHING when any schema fails its gate, or when any schema
-* drifts under `onDrift: "error"` — a partial write would leave a
-* repository half-bumped. Every otherwise-writable schema then reports
-* `held`, so a reader sees why a clean schema was not written — in both
-* modes, since `check` reports what `build` would do under the same
-* flags. Both modes share one `SchemaFile`; the single `writing`
-* predicate (`mode === "build" && !refused`) gates every write, schemas
-* and catalog entries alike. Under `onDrift: "warn"` drifting schemas are
-* written and keep their `"drift"` verdict for the renderer to shout
-* about.
+* **The frozen check runs first, before anything is generated.** Every
+* schema's {@link ResolvedSchema.frozen} versions are walked, and every miss
+* is reported at once: a build fails typed with
+* {@link FrozenVersionMissingError} listing every label with no file on disk
+* — nothing is written — a catalog that points a label at a 404 is a worse
+* failure than an early refusal.
 *
-* Catalog entries follow the schemas: serialized canonically, compared by
-* parsed content against the file on disk, written only when different and
-* only when the run is writing.
+* **Drift is classified per schema, under that schema's own
+* {@link ResolvedSchema.drift} tolerance — unless `options.policy` is set,
+* in which case it overrides every schema's own for this run** (the `--drift`
+* / `--force` flags). A build writes NOTHING when any schema fails its gate,
+* or when any schema drifts under `onDrift: "error"` — a partial write would
+* leave a repository half-bumped. Every otherwise-writable schema then
+* reports `held`, so a reader sees why a clean schema was not written — in
+* both modes, since `check` reports what `build` would do under the same
+* flags. Both modes share one `SchemaFile`; the single `writing` predicate
+* (`mode === "build" && !refused`) gates every write, schemas and the
+* catalog file alike. Under `onDrift: "warn"` drifting schemas are written
+* and keep their `"drift"` verdict for the renderer to shout about.
+*
+* **Every catalog entry the config declares lands in ONE file** at
+* `config.catalogPath` — never one file per schema — serialized canonically
+* and compared by parsed content against the file on disk, written only
+* when different and only when the run is writing. The report omits
+* `catalog` entirely when no schema declared one.
 *
 * @public
 */
@@ -48,78 +76,89 @@ var Runner = class {
 	static run = Effect.fn("Runner.run")(function* (config, options) {
 		const fs = yield* FileSystem.FileSystem;
 		const path = yield* Path.Path;
-		const checks = yield* SchemaPipeline.check(config.schemas, pipelineOptions);
+		const missing = [];
+		for (const schema of config.schemas) for (const frozen of schema.frozen) {
+			const info = yield* orNone(fs.stat(frozen.path));
+			if (Option.isNone(info) || info.value.type !== "File") missing.push({
+				name: schema.name,
+				version: frozen.version,
+				path: frozen.path
+			});
+		}
+		if (missing.length > 0) return yield* Effect.fail(new FrozenVersionMissingError({ missing }));
+		const targets = config.schemas.map((schema) => schema.target);
+		const checks = yield* SchemaPipeline.check(targets, pipelineOptions);
 		const gateFailed = checks.some((check) => check.blocked);
 		const classified = checks.map((check, i) => {
-			const target = config.schemas[i];
+			const schema = config.schemas[i];
+			const target = schema.target;
+			const policy = options.policy ?? schema.drift;
 			return {
+				schema,
 				target,
 				check,
 				verdict: DriftPolicy.classify({
 					published: target.published,
 					change: check.change
-				}, options.drift.policy),
+				}, policy),
+				policy,
 				nextVersion: target.version !== void 0 && check.change === "contract" && SchemaVersioning.isPinned(target.version) ? SchemaVersioning.next(target.version, "contract") : void 0
 			};
 		});
 		const drifted = classified.some((entry) => entry.verdict === "drift");
-		const refused = gateFailed || drifted && options.drift.onDrift === "error";
+		const refused = gateFailed || drifted && options.onDrift === "error";
 		const writing = options.mode === "build" && !refused;
-		const written = writing ? yield* SchemaPipeline.run(config.schemas, pipelineOptions).pipe(Effect.catchTags({
+		const written = writing ? yield* SchemaPipeline.run(targets, pipelineOptions).pipe(Effect.catchTags({
 			SchemaGateError: (error) => Effect.die(error),
 			SchemaContractChangeError: (error) => Effect.die(error)
 		})) : void 0;
-		const schemas = classified.map(({ target, check, verdict, nextVersion }, i) => {
-			const outcome = check.blocked ? "gate-failed" : written !== void 0 ? written[i].outcome : verdict === "drift" ? "drift" : refused && check.wouldWrite ? "held" : check.wouldWrite ? "would-write" : "unchanged";
+		const schemas = classified.map(({ schema, target, check, verdict, policy, nextVersion }, i) => {
+			const outcome = check.blocked ? "gate-failed" : written !== void 0 ? written[i].outcome : verdict === "drift" ? "drift" : pendingOutcome(check.wouldWrite, refused);
 			return {
 				$id: target.$id,
 				path: target.path,
+				name: schema.name,
 				published: target.published,
 				change: check.change,
 				verdict,
+				policy,
 				outcome,
 				findings: check.findings,
-				...target.name !== void 0 ? { name: target.name } : {},
+				frozen: schema.frozen.map((frozen) => frozen.version),
 				...target.version !== void 0 ? { version: target.version } : {},
 				...nextVersion !== void 0 ? { nextVersion } : {}
 			};
 		});
-		const catalog = [];
-		for (const entry of config.catalog) {
-			const { name, path: file } = entry.config;
-			const text = yield* catalogText(entry);
-			if ((yield* fs.exists(file)) && sameJson(yield* fs.readFileString(file), text)) catalog.push({
-				name,
-				path: file,
-				outcome: "unchanged"
-			});
-			else if (!writing) catalog.push({
-				name,
-				path: file,
-				outcome: refused ? "held" : "would-write"
-			});
-			else {
-				yield* fs.makeDirectory(path.dirname(file), { recursive: true });
-				yield* fs.writeFileString(file, text);
-				catalog.push({
-					name,
-					path: file,
-					outcome: "written"
-				});
+		const entries = config.schemas.flatMap((schema) => schema.catalog !== void 0 ? [schema.catalog] : []);
+		let catalog;
+		if (entries.length > 0) {
+			const text = yield* CanonicalJson.serialize(entries.map((entry) => Schema.encodeSync(CatalogEntry)(entry)));
+			const existing = yield* orNone(fs.readFileString(config.catalogPath));
+			const same = Option.isSome(existing) && parsesEqual(existing.value, text);
+			const outcome = writing && !same ? "written" : pendingOutcome(!same, refused);
+			if (outcome === "written") {
+				yield* fs.makeDirectory(path.dirname(config.catalogPath), { recursive: true });
+				yield* fs.writeFileString(config.catalogPath, text);
 			}
+			catalog = {
+				path: config.catalogPath,
+				entries: entries.length,
+				outcome
+			};
 		}
 		return {
 			mode: options.mode,
 			configPath: options.configPath,
-			drift: options.drift,
+			onDrift: options.onDrift,
+			...options.policy !== void 0 ? { policy: options.policy } : {},
 			schemas,
-			catalog,
+			...catalog !== void 0 ? { catalog } : {},
 			drifted,
 			gateFailed,
-			wrote: schemas.some((s) => s.outcome === "written") || catalog.some((c) => c.outcome === "written")
+			wrote: schemas.some((s) => s.outcome === "written") || catalog?.outcome === "written"
 		};
 	});
 };
 
 //#endregion
-export { Runner };
+export { FrozenVersionMissingError, Runner };

package/cli/execute.js

@@ -7,15 +7,30 @@ import { Console, Effect, Option, Schema } from "effect";
 import { SchemaFile, SchemaValidator } from "@effected/schemastore";
 
 //#region src/cli/execute.ts
+const DriftedSchema = Schema.Struct({
+	$id: Schema.String,
+	change: Schema.Literals([
+		"none",
+		"created",
+		"annotations",
+		"contract"
+	]),
+	version: Schema.optionalKey(Schema.String),
+	nextVersion: Schema.optionalKey(Schema.String)
+});
 /**
 * A published schema drifted under `onDrift: "error"`, so nothing was
 * written. Exit `1`.
 *
 * @public
 */
-var DriftError = class extends Schema.TaggedError()("DriftError", { count: Schema.Number }) {
+var DriftError = class extends Schema.TaggedError()("DriftError", { drifted: Schema.Array(DriftedSchema) }) {
+	get count() {
+		return this.drifted.length;
+	}
 	get message() {
-		return `${this.count} published schema(s) drifted; nothing was written. Bump the drifting versions in the config, or re-run with --force to write anyway.`;
+		const lines = this.drifted.map((s) => `  ${s.$id}: ${s.change}${s.version !== void 0 ? ` at published ${s.version}` : ""}${s.nextVersion !== void 0 ? ` → suggest ${s.nextVersion}` : ""}`);
+		return `${this.count} published schema(s) drifted; nothing was written.\n${lines.join("\n")}\nBump the drifting versions in the config, or re-run with --force to write anyway.`;
 	}
 };
 /**
@@ -40,11 +55,23 @@ var StaleError = class extends Schema.TaggedError()("StaleError", { count: Schem
 		return `${this.count} document(s) are stale; run \`schemastore build\` and commit the result.`;
 	}
 };
-const effectiveDrift = (configured, input) => {
+/**
+* `--force` (shorthand for `--drift=allow`) was combined with an explicit
+* `--drift` that is not `allow`. Contradictory, so refused as a usage
+* error rather than silently resolving to `allow`. Exit `64`.
+*
+* @public
+*/
+var ConflictingFlagsError = class extends Schema.TaggedError()("ConflictingFlagsError", { policy: Schema.String }) {
+	get message() {
+		return `--force conflicts with --drift=${this.policy}: --force means --drift=allow`;
+	}
+};
+const effectiveDrift = (config, input) => {
+	const forced = input.force ? "allow" : Option.getOrUndefined(input.drift);
 	return {
-		policy: input.force ? "allow" : Option.getOrElse(input.drift, () => configured.policy),
-		onDrift: Option.getOrElse(input.onDrift, () => configured.onDrift),
-		source: input.force || Option.isSome(input.drift) || Option.isSome(input.onDrift) ? "flag" : "config"
+		onDrift: Option.getOrElse(input.onDrift, () => config.onDrift),
+		...forced !== void 0 ? { policy: forced } : {}
 	};
 };
 const emit = Effect.fn("schemastore.emit")(function* (report, format) {
@@ -58,29 +85,33 @@ const emit = Effect.fn("schemastore.emit")(function* (report, format) {
 * Run one `build` or `check`.
 *
 * @remarks
-* Loads the config, applies the flag overrides, runs the shared walk,
-* emits the report in the requested format, appends the step summary, and
-* fails typed — `GateError`, then `DriftError`, then (for `check` only)
-* `StaleError`, each carrying exit `1` — when the report says the run
-* refused to write or, under `check`, that a build would write. `SchemaFile` is built
-* here over the environment's `FileSystem`; the validator is
-* `deps.validator` or the real engine.
+* Before anything is loaded, `--force` combined with an explicit `--drift`
+* other than `allow` short-circuits with `ConflictingFlagsError` at exit
+* `64` — a usage error, not a run outcome. Otherwise loads the config,
+* applies the flag overrides, runs the shared walk, emits the report in the
+* requested format, appends the step summary, and fails typed —
+* `GateError`, then `DriftError`, then (for `check` only) `StaleError`,
+* each carrying exit `1` — when the report says the run refused to write
+* or, under `check`, that a build would write. `SchemaFile` is built here
+* over the environment's `FileSystem`; the validator is `deps.validator` or
+* the real engine.
 *
 * @public
 */
 const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
+	if (input.force && Option.isSome(input.drift) && input.drift.value !== "allow") return yield* Effect.fail(CliRuntime.reported(new ConflictingFlagsError({ policy: input.drift.value }), 64));
 	const loaded = yield* ConfigLoader.load({
 		cwd: deps.cwd,
 		...Option.isSome(input.config) ? { explicit: input.config.value } : {},
 		...deps.importModule !== void 0 ? { importModule: deps.importModule } : {}
 	});
-	const drift = effectiveDrift(loaded.config.drift, input);
+	const drift = effectiveDrift(loaded.config, input);
 	if (input.force) yield* Effect.logWarning(`--force: drift policy is allow for this run; a published document ${mode === "check" ? "would be" : "may be"} rewritten in place, which breaks every consumer pinned to its URL.`);
 	const report = yield* Runner.run(loaded.config, {
 		mode,
 		configPath: loaded.path,
-		drift
-	}).pipe(Effect.provide(SchemaFile.layer), Effect.provide(deps.validator ?? SchemaValidator.layer));
+		...drift
+	}).pipe(Effect.provide(SchemaFile.layer), Effect.provide(deps.validator ?? SchemaValidator.layer), Effect.catchTag("FrozenVersionMissingError", (error) => Effect.fail(CliRuntime.reported(error, 1))));
 	yield* emit(report, input.format);
 	yield* StepSummary.append(Report.markdown(report));
 	if (report.gateFailed) {
@@ -88,14 +119,19 @@ const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
 		return yield* Effect.fail(CliRuntime.reported(new GateError({ count }), 1));
 	}
 	if (report.drifted && drift.onDrift === "error") {
-		const count = report.schemas.filter((schema) => schema.verdict === "drift").length;
-		return yield* Effect.fail(CliRuntime.reported(new DriftError({ count }), 1));
+		const drifted = report.schemas.filter((schema) => schema.verdict === "drift").map((schema) => ({
+			$id: schema.$id,
+			change: schema.change,
+			...schema.version !== void 0 ? { version: schema.version } : {},
+			...schema.nextVersion !== void 0 ? { nextVersion: schema.nextVersion } : {}
+		}));
+		return yield* Effect.fail(CliRuntime.reported(new DriftError({ drifted }), 1));
 	}
 	if (mode === "check") {
-		const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + report.catalog.filter((entry) => entry.outcome === "would-write").length;
+		const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + (report.catalog?.outcome === "would-write" ? 1 : 0);
 		if (count > 0) return yield* Effect.fail(CliRuntime.reported(new StaleError({ count }), 1));
 	}
 });
 
 //#endregion
-export { DriftError, GateError, StaleError, execute };
+export { ConflictingFlagsError, DriftError, GateError, StaleError, execute };

package/cli/flags.js

@@ -17,13 +17,13 @@ const driftFlag = Flag.Literals("drift", [
 	"strict",
 	"semantic",
 	"allow"
-]).pipe(Flag.withDescription("Drift tolerance for published schemas; overrides the config's drift.policy"), Flag.optional);
+]).pipe(Flag.withDescription("Drift tolerance for published schemas; overrides every schema's drift"), Flag.optional);
 /**
 * `--on-drift`: what drift does, overriding the config.
 *
 * @public
 */
-const onDriftFlag = Flag.Literals("on-drift", ["error", "warn"]).pipe(Flag.withDescription("What drift does: refuse every write (error) or write and warn; overrides drift.onDrift"), Flag.optional);
+const onDriftFlag = Flag.Literals("on-drift", ["error", "warn"]).pipe(Flag.withDescription("What drift does: refuse every write (error) or write and warn; overrides the config's onDrift"), Flag.optional);
 /**
 * `--force`: shorthand for `--drift=allow`.
 *

package/cli/program.js

@@ -28,7 +28,8 @@ const trimLoadError = Effect.fn("schemastore.trimLoadError")(function* (error) {
 * Fails with the marked error the runtime maps to the exit code:
 * `ShowHelp` is `64` with parse errors and `0` without (help itself was
 * already rendered); `ConfigNotFoundError` / `ConfigLoadError` are `2`;
-* `DriftError` / `GateError` / `StaleError` arrive already marked `1`.
+* `ConflictingFlagsError` arrives already marked `64`; `DriftError` /
+* `GateError` / `StaleError` arrive already marked `1`.
 *
 * @public
 */

package/main.js

@@ -15,7 +15,7 @@ const render = (error) => CliError.isCliError(error) && error._tag === "ShowHelp
 const main = () => {
 	const run = program(process.argv.slice(2), {
 		cwd: process.cwd(),
-		version: "0.9.1"
+		version: "0.11.0"
 	}).pipe(Effect.provide(NodeServices.layer), CliRuntime.reportFailures({
 		exitCode: 3,
 		render

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore-cli",
-	"version": "0.9.1",
+	"version": "0.11.0",
 	"private": false,
 	"description": "The schemastore command: build and check SchemaStore-shaped JSON Schema documents from a schemastore.config.ts, with a per-schema published flag and a drift policy.",
 	"keywords": [
@@ -36,11 +36,11 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.115",
-		"@effected/cli": "^0.5.0",
+		"@effected/cli": "^0.5.1",
 		"jiti": "^2.6.0"
 	},
 	"peerDependencies": {
-		"@effected/schemastore": "0.9.1",
+		"@effected/schemastore": "0.11.0",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {