@effected/schemastore-cli 0.16.1 → 0.18.0

package/ConfigLoader.js

@@ -1,4 +1,4 @@
-import { isSchemastoreConfig } from "@effected/schemastore";
+import { SchemaVersioning, isSchemastoreConfig } from "@effected/schemastore";
 import { Effect, FileSystem, Path, Predicate, Schema } from "effect";
 import { createJiti } from "jiti";
 
@@ -19,14 +19,18 @@ 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, `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.
+* value, `name` is not a simple file base name, `outputDir`/`catalogDir` is
+* not a string, a `schemas` element is not resolved-schema-shaped (or its
+* `target`, `catalog`, or a `frozen` entry is not shaped), two outputs
+* resolve to one absolute path, a document resolves into `catalogDir`, or
+* `catalogDir` resolves to `outputDir` or to the merged catalog's path.
 *
 * @public
 */
 var ConfigLoadError = class extends Schema.TaggedError()("ConfigLoadError", {
+	/** The config file that failed to load. */
 	path: Schema.String,
+	/** Why it failed; the first line is the message, any remainder is detail such as a stack. */
 	reason: Schema.String
 }) {
 	get message() {
@@ -38,8 +42,9 @@ const describeCause = (cause) => cause instanceof Error ? cause.stack ?? cause.m
 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.name !== "string" || !SchemaVersioning.isSimpleName(config.name)) return "name is not a simple file base name";
 	if (typeof config.outputDir !== "string") return "outputDir is not a string";
-	if (typeof config.catalogPath !== "string") return "catalogPath is not a string";
+	if (typeof config.catalogDir !== "string") return "catalogDir 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)`;
@@ -48,12 +53,21 @@ const describeMalformed = (config) => {
 		for (const [j, frozen] of schema.frozen.entries()) if (!Predicate.isObject(frozen) || typeof frozen.version !== "string" || typeof frozen.path !== "string" || typeof frozen.$id !== "string" || typeof frozen.url !== "string") return `schemas[${index}].frozen[${j}] is not a frozen version (missing version/path/$id/url)`;
 	}
 };
-const describeDuplicatePath = (config) => {
+const describeClashingPath = (config, path) => {
+	const documents = config.schemas.flatMap((schema) => [schema.target.path, ...schema.frozen.map((f) => f.path)]);
+	const catalogDir = path.normalize(config.catalogDir);
+	if (catalogDir === path.normalize(ConfigLoader.mergedCatalogPath(config, path))) return `catalogDir "${config.catalogDir}" must not be the merged catalog's path (catalog.json in its parent)`;
+	if (catalogDir === path.normalize(config.outputDir)) return `catalogDir "${config.catalogDir}" must not be outputDir: every *.json file in it is read as a catalog slice`;
+	for (const document of documents) if (path.normalize(path.dirname(document)) === catalogDir) return `output path "${document}" sits in catalogDir "${config.catalogDir}", which holds only catalog slices`;
 	const seen = /* @__PURE__ */ new Set();
-	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);
+	for (const p of [
+		...documents,
+		ConfigLoader.slicePath(config, path),
+		ConfigLoader.mergedCatalogPath(config, path)
+	]) {
+		const normalized = path.normalize(p);
+		if (seen.has(normalized)) return `output path "${p}" is declared twice after resolution`;
+		seen.add(normalized);
 	}
 };
 /**
@@ -98,8 +112,20 @@ var ConfigLoader = class ConfigLoader {
 			dir = parent;
 		}
 	});
+	/** This config's own catalog slice: `<catalogDir>/<name>.json`. */
+	static slicePath(config, path) {
+		return path.join(config.catalogDir, `${config.name}.json`);
+	}
+	/**
+	* The merged catalog every config sharing `catalogDir` maintains:
+	* `catalog.json` in `catalogDir`'s parent (`<outputDir>/catalog.json` under
+	* the default `catalogDir`).
+	*/
+	static mergedCatalogPath(config, path) {
+		return path.join(path.dirname(config.catalogDir), "catalog.json");
+	}
 	/**
-	* Resolve every relative `path` in the config (`outputDir`, `catalogPath`,
+	* Resolve every relative `path` in the config (`outputDir`, `catalogDir`,
 	* 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
@@ -112,7 +138,7 @@ var ConfigLoader = class ConfigLoader {
 		return {
 			...config,
 			outputDir: absolute(config.outputDir),
-			catalogPath: absolute(config.catalogPath),
+			catalogDir: absolute(config.catalogDir),
 			schemas: config.schemas.map((schema) => ({
 				...schema,
 				target: {
@@ -155,7 +181,7 @@ var ConfigLoader = class ConfigLoader {
 		}));
 		const directory = path.dirname(configPath);
 		const config = yield* ConfigLoader.resolvePaths(exported, directory);
-		const duplicate = describeDuplicatePath(config);
+		const duplicate = describeClashingPath(config, path);
 		if (duplicate !== void 0) return yield* Effect.fail(new ConfigLoadError({
 			path: configPath,
 			reason: duplicate

package/README.md

@@ -7,10 +7,10 @@
 
 The `schemastore` command: build and check SchemaStore-shaped JSON Schema documents from a `schemastore.config.ts`. It is the companion to [`@effected/schemastore`](https://www.npmjs.com/package/@effected/schemastore), which owns the pipeline and every type a config needs; this package ships the plumbing every consumer used to write by hand — the config loader, the drift policy, the frozen-label checks, the catalog file, exit codes, a GitHub step summary — once, as a `bin`. It is also where the validation engine lives: `AjvValidator`, ajv in strict mode, composed by the command and exported for a program that drives the pipeline itself, so the library stays free of ajv.
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered
@@ -60,6 +60,8 @@ import { defineConfig } from "@effected/schemastore";
 import { OutputSchemaIdentity, ReleaseOutput } from "./src/schema/output.js";
 
 export default defineConfig({
+  // This config's identity: its catalog slice is catalogs/<name>.json.
+  name: "silk-release-action",
   // Relative paths resolve against this file's directory.
   outputDir: "schemas",
   schemas: {
@@ -79,10 +81,11 @@ export default defineConfig({
 
 `schema:build` writes `schemas/5.2/silk-release-action.output-5.2.json`; `schema:check` in CI fails whenever a build would write anything. Bumping the version is one constant, and once a label has shipped it stays in `versions` as a frozen file the command verifies but never regenerates.
 
-A schema published to SchemaStore itself uses `HostedSchema.schemastore` and declares its catalog entry; the command assembles every entry into one `catalog.json`:
+A schema published to SchemaStore itself uses `HostedSchema.schemastore` and declares its catalog entry; the command assembles every entry into the config's catalog slice and the merged `catalog.json`:
 
 ```ts
 export default defineConfig({
+  name: "okfit",
   outputDir: "schemas",
   schemas: {
     okfit: {
@@ -102,7 +105,8 @@ export default defineConfig({
 - `appendVersion` (default `true`) keeps SchemaStore's `-<version>` file suffix; `false` lets the version directory name the file alone (`schemas/6.0/output.json`) and requires the `"versioned"` layout. Like `baseUrl`, it belongs to `hosted` when that is given, and flipping it is a re-publish event for every frozen label.
 - `published` (default `false`) marks a version other people already depend on: an unpublished schema regenerates in place through any change, a published one is held to the drift policy.
 - `drift` (`strict` / `semantic` / `allow`, default `semantic`) and `onDrift` (`error` / `warn`) are top-level defaults; `drift`, `published`, `jsonSchema` and `rootAnnotations` may be set per entry. Objects are emitted closed (`additionalProperties: false`); `jsonSchema: { onExcessProperty: "ignore" }` reopens one document.
-- `catalog` is required under SchemaStore hosting and optional under a custom host; every entry lands in ONE file at `catalogPath` (default `<outputDir>/catalog.json`).
+- `name` (required, top-level) is the config's identity: a simple file base name, distinct among configs sharing a `catalogDir` — case-insensitively, since on a case-insensitive volume `docs` and `Docs` are one slice file that each build overwrites. When `<name>.json` is absent from the listing but the volume resolves it to a file differing only in case (a case-insensitive volume), that file is claimed as the config's slice and flagged on its report line; on a case-sensitive volume the file is another slice, so a case-only rename leftover blocks the merge until it is deleted, like any rename leftover.
+- `catalog` is required under SchemaStore hosting and optional under a custom host. Every entry the config declares lands in ONE slice file, `<catalogDir>/<name>.json` (`catalogDir` defaults to `<outputDir>/catalogs`), and the command maintains the merged `catalog.json` in `catalogDir`'s parent — `<outputDir>/catalog.json` by default — as the union of every slice there, sorted by `url`. Several configs can therefore share one `outputDir`: each rewrites only its own slice, and whichever builds last writes the identical merged file, so `check` is green for all of them. `catalogDir` holds slices only: `defineConfig` rejects one that is `outputDir`, that is the merged catalog's own path, or that a derived document sits in. Every config that shares a merged catalog must share the same `catalogDir` — sibling directories merging into one `catalog.json` overwrite each other, and no single config can see it.
 - A typo'd key anywhere in the config is named and rejected, never ignored, and every issue on an entry is reported at once.
 
 ## Commands
@@ -113,10 +117,10 @@ schemastore check [config] [--drift=strict|semantic|allow] [--on-drift=error|war
 ```
 
 - Before anything is generated, every frozen label is verified — present on disk, and self-identified by the derived `$id`.
-- `build` generates every schema, runs the gates (the structural lint and ajv strict mode), applies the drift policy, and writes what passes — content-compared, so an unchanged file is untouched — plus the catalog file when any entry declares one.
-- `check` is the identical walk with no writes: it reports what `build` would do under the same flags and exits the same way, and also fails (exit `1`) whenever a build would write anything — a stale or missing document is fixed by running `schemastore build` and committing the result. A `catalog.json` left behind after the last `catalog` block was removed is reported `orphaned` and fails `check` the same way, but `build` never deletes it: delete the file by hand, or restore a `catalog` block. So is a document left behind under an old derived name — an `appendVersion` flip or a `layout` change moved its path, and nothing claims the old file any more: both commands probe the sibling shapes (`<name>.json`, `<name>-<v>.json`, `<v>/<name>.json`, `<v>/<name>-<v>.json`) of every label the config still declares and report each one that exists as an orphaned document, failed by `check`, never deleted by `build`. Nothing else in `outputDir` is looked at, so sharing it with another config, a deploy folder, or the repository root is safe (unless two configs derive the same schema name and version under different layouts into it); a `name` change or a dropped label leaves a file the command cannot know about — delete those by hand.
+- `build` generates every schema, runs the gates (the structural lint and ajv strict mode), applies the drift policy, and writes what passes — content-compared, so an unchanged file is untouched — plus the config's catalog slice when any entry declares one, and the merged catalog over every slice.
+- `check` is the identical walk with no writes: it reports what `build` would do under the same flags and exits the same way, and also fails (exit `1`) whenever a build would write anything — a stale or missing document is fixed by running `schemastore build` and committing the result. A catalog slice left behind after the config's last `catalog` block was removed is reported `orphaned` and fails `check` the same way, but `build` never deletes it — and the merged catalog keeps advertising its entries until it is gone: delete the file by hand, or restore a `catalog` block; a merged `catalog.json` with no slice left is orphaned the same way. So is a document left behind under an old derived name — an `appendVersion` flip or a `layout` change moved its path, and nothing claims the old file any more: both commands probe the sibling shapes (`<name>.json`, `<name>-<v>.json`, `<v>/<name>.json`, `<v>/<name>-<v>.json`) of every label the config still declares and report each one that exists as an orphaned document, failed by `check`, never deleted by `build`. Nothing else in `outputDir` is looked at, so sharing it with another config, a deploy folder, or the repository root is safe (unless two configs derive the same schema name and version under different layouts into it); a `name` change or a dropped label leaves a file the command cannot know about — delete those by hand. A catalog URL advertised by two slices, or a slice that cannot be read or is not a catalog entry array (an undeclared key included), blocks the merged catalog: both commands fail (exit `1`) naming the URL and its slices or the invalid slice, and the merged file is left as it is until the configs or slices are fixed.
 - `--drift` and `--on-drift` override the config for one run; `--force` is sugar for `--drift=allow` (combined with a different explicit `--drift` it is a usage error).
-- `--format=json` emits one JSON document on stdout (per-schema outcome and effective tolerance, the catalog outcome, the `orphaned` document paths when any, `drift: { onDrift, policy? }`); human text moves to stderr. When `GITHUB_STEP_SUMMARY` is set, both commands append a markdown table.
+- `--format=json` emits one JSON document on stdout (per-schema outcome and effective tolerance, the catalog slice and merged-catalog outcomes, the `orphaned` document paths when any, `drift: { onDrift, policy? }`); human text moves to stderr. When `GITHUB_STEP_SUMMARY` is set, both commands append a markdown table.
 
 ## The engine, as a library export
 
@@ -140,8 +144,8 @@ Findings come back as values; the error channel carries `SchemaValidatorError` o
 | code | meaning |
 | ---- | -------------------------------------------------------------------------- |
 | 0 | success, including drift under `onDrift: warn` |
-| 1 | drift under `onDrift: error` (one line per drifting schema: `$id`, change, current and next version), a gate failure, a missing or mis-identified frozen version, or — for `check` — anything `build` would write or an output nothing claims (an orphaned catalog file, or an orphaned document at a sibling shape of a derived path) |
-| 2 | config not found, failed to load, or failed `defineConfig` validation |
+| 1 | drift under `onDrift: error` (one line per drifting schema: `$id`, change, current and next version), a gate failure, a missing or mis-identified frozen version, a merged catalog blocked by a URL two slices advertise or an invalid slice, or — for `check` — anything `build` would write or an output nothing claims (an orphaned catalog slice or merged catalog, or an orphaned document at a sibling shape of a derived path) |
+| 2 | config not found, failed to load, failed `defineConfig` validation, or a `catalogDir` that is a file or cannot be listed (checked before anything is written) |
 | 3 | infrastructure failure |
 | 64 | usage error |
 

package/Report.js

@@ -17,16 +17,57 @@ const schemaLines = (schema, report) => {
 		default: return schema.outcome;
 	}
 };
-const catalogLine = (entry) => {
-	switch (entry.outcome) {
-		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)`;
-		case "orphaned": return `orphaned catalog ${entry.path} (no schema declares a catalog)`;
-		default: return entry.outcome;
+const sliceOwner = (slicePath) => (slicePath.split(/[\\/]/).pop() ?? slicePath).replace(/\.json$/, "");
+const sliceCounts = (slice) => slice.caseFoldedMatch !== void 0 ? `(${slice.entries} entries; claimed ${slice.caseFoldedMatch} by case-folded match for "${sliceOwner(slice.path)}")` : `(${slice.entries} entries)`;
+const sliceLine = (slice) => {
+	switch (slice.outcome) {
+		case "written": return `written catalog slice ${slice.path} ${sliceCounts(slice)}`;
+		case "unchanged": return `unchanged catalog slice ${slice.path} ${sliceCounts(slice)}`;
+		case "would-write": return `would write catalog slice ${slice.path} ${sliceCounts(slice)}`;
+		case "held": return `held catalog slice ${slice.path} ${sliceCounts(slice)}`;
+		case "orphaned": return `orphaned catalog slice ${slice.path} (no schema declares a catalog; the merged catalog keeps advertising its entries until it is deleted — delete it by hand; build never will)`;
+		default: return slice.outcome;
 	}
 };
+const mergedLines = (merged) => {
+	const counts = `(${merged.entries} entries from ${merged.slices.length} slice(s))`;
+	switch (merged.outcome) {
+		case "written": return [`written catalog ${merged.path} ${counts}`];
+		case "unchanged": return [`unchanged catalog ${merged.path} ${counts}`];
+		case "would-write": return [`would write catalog ${merged.path} ${counts}`];
+		case "held": return [`held catalog ${merged.path} ${counts}`];
+		case "orphaned": return [`orphaned catalog ${merged.path} (no catalog slice remains — delete it by hand; build never will)`];
+		case "blocked": return [
+			`CATALOG BLOCKED ${merged.path} (not written: fix the slices below)`,
+			...merged.conflicts.map((conflict) => `  url ${conflict.url} advertised by ${conflict.slices.join(", ")}`),
+			...merged.invalid.map(({ path, reason }) => `  slice ${path} is invalid: ${reason}`)
+		];
+		default: return merged.outcome;
+	}
+};
+const catalogLines = (catalog) => [...catalog.slice !== void 0 ? [sliceLine(catalog.slice)] : [], ...catalog.merged !== void 0 ? mergedLines(catalog.merged) : []];
+const catalogJson = (catalog) => ({
+	...catalog.slice !== void 0 ? { slice: {
+		path: catalog.slice.path,
+		entries: catalog.slice.entries,
+		outcome: catalog.slice.outcome,
+		...catalog.slice.caseFoldedMatch !== void 0 ? { caseFoldedMatch: catalog.slice.caseFoldedMatch } : {}
+	} } : {},
+	...catalog.merged !== void 0 ? { merged: {
+		path: catalog.merged.path,
+		entries: catalog.merged.entries,
+		outcome: catalog.merged.outcome,
+		slices: catalog.merged.slices,
+		...catalog.merged.conflicts.length > 0 ? { conflicts: catalog.merged.conflicts.map(({ url, slices }) => ({
+			url,
+			slices
+		})) } : {},
+		...catalog.merged.invalid.length > 0 ? { invalid: catalog.merged.invalid.map(({ path, reason }) => ({
+			path,
+			reason
+		})) } : {}
+	} } : {}
+});
 const orphanedLine = (orphan) => `orphaned document ${orphan} (no target, frozen version, or catalog entry claims it — delete it by hand; build never will)`;
 const driftClause = (report) => `drift ${report.policy !== void 0 ? `${report.policy} (flag)` : "per schema (config)"}, on-drift ${report.onDrift}`;
 const summaryLine = (report) => {
@@ -37,7 +78,8 @@ const summaryLine = (report) => {
 	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(" | ")} |`;
+const tableCell = (cell) => cell.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+const tableRow = (columns) => `| ${columns.map(tableCell).join(" | ")} |`;
 /**
 * Renders a {@link RunReport} for a terminal, a JSON consumer or a GitHub
 * step summary.
@@ -58,7 +100,7 @@ var Report = class {
 	static human(report) {
 		const lines = [];
 		for (const schema of report.schemas) lines.push(...schemaLines(schema, report));
-		if (report.catalog !== void 0) lines.push(catalogLine(report.catalog));
+		if (report.catalog !== void 0) lines.push(...catalogLines(report.catalog));
 		for (const orphan of report.orphaned ?? []) lines.push(orphanedLine(orphan));
 		lines.push(summaryLine(report));
 		return lines;
@@ -101,11 +143,7 @@ var Report = class {
 					message: finding.message
 				}))
 			})),
-			...report.catalog !== void 0 ? { catalog: {
-				path: report.catalog.path,
-				entries: report.catalog.entries,
-				outcome: report.catalog.outcome
-			} } : {},
+			...report.catalog !== void 0 ? { catalog: catalogJson(report.catalog) } : {},
 			...report.orphaned !== void 0 ? { orphaned: report.orphaned } : {},
 			drifted: report.drifted,
 			gateFailed: report.gateFailed,
@@ -139,19 +177,31 @@ var Report = class {
 			schema.change,
 			schema.outcome
 		]));
-		if (report.catalog !== void 0) lines.push("", tableRow([
-			"catalog",
-			"entries",
-			"outcome"
-		]), tableRow([
-			"---",
-			"---",
-			"---"
-		]), tableRow([
-			report.catalog.path,
-			String(report.catalog.entries),
-			report.catalog.outcome
-		]));
+		if (report.catalog !== void 0) {
+			const { slice, merged } = report.catalog;
+			lines.push("", tableRow([
+				"catalog",
+				"file",
+				"entries",
+				"outcome"
+			]), tableRow([
+				"---",
+				"---",
+				"---",
+				"---"
+			]), ...slice !== void 0 ? [tableRow([
+				"slice",
+				slice.path,
+				String(slice.entries),
+				slice.caseFoldedMatch !== void 0 ? `${slice.outcome} (case-folded match: ${slice.caseFoldedMatch})` : slice.outcome
+			])] : [], ...merged !== void 0 ? [tableRow([
+				"merged",
+				merged.path,
+				String(merged.entries),
+				merged.outcome
+			])] : []);
+			if (merged !== void 0 && (merged.conflicts.length > 0 || merged.invalid.length > 0)) lines.push("", tableRow(["catalog problem", "slices"]), tableRow(["---", "---"]), ...merged.conflicts.map((conflict) => tableRow([`url ${conflict.url}`, conflict.slices.join(", ")])), ...merged.invalid.map(({ path, reason }) => tableRow([`invalid: ${reason}`, path])));
+		}
 		if (report.orphaned !== void 0) lines.push("", tableRow(["orphaned document", "claimed by"]), tableRow(["---", "---"]), ...report.orphaned.map((orphan) => tableRow([orphan, "nothing — delete by hand"])));
 		lines.push("");
 		if (report.gateFailed) {

package/Runner.js

@@ -1,5 +1,6 @@
+import { ConfigLoader } from "./ConfigLoader.js";
 import { CanonicalJson, CatalogEntry, DriftPolicy, SchemaPipeline, SchemaVersioning } from "@effected/schemastore";
-import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { Effect, FileSystem, Option, Path, Result, Schema } from "effect";
 
 //#region src/Runner.ts
 /**
@@ -65,6 +66,32 @@ mismatched: Schema.Array(Schema.Struct({
 		return `${this.mismatched.length} frozen version(s) on disk do not carry their derived $id; nothing was written.\n${lines.join("\n")}`;
 	}
 };
+/**
+* `catalogDir` exists but cannot be listed — it is a file, or the listing
+* failed (a permission failure, say). Every `*.json` file in `catalogDir` is
+* a catalog slice, so without the listing there is no merged catalog to
+* compute. Raised by {@link Runner.run} before anything is generated or
+* written; a config problem, not a run outcome.
+*
+* @public
+*/
+var CatalogDirError = class extends Schema.TaggedError()("CatalogDirError", {
+	/** The `catalogDir` that could not be listed. */
+	path: Schema.String,
+	/** Why, in words: `not a directory` for a file, `permission denied`, or the platform's own description. */
+	reason: Schema.String
+}) {
+	get message() {
+		return `catalogDir ${this.path} cannot be listed (${this.reason}); it must be a directory holding only catalog slices, or not exist yet. Nothing was written.`;
+	}
+};
+const listingFailureReason = (error) => {
+	switch (error.reason._tag) {
+		case "BadResource": return "not a directory";
+		case "PermissionDenied": return "permission denied";
+		default: return error.reason.description ?? error.reason._tag;
+	}
+};
 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";
@@ -88,6 +115,141 @@ const parsesEqual = (existing, text) => {
 		return false;
 	}
 };
+const CatalogEntries = Schema.Array(CatalogEntry);
+const decodeSlice = (text) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return Result.fail("not JSON");
+	}
+	return Schema.decodeUnknownResult(CatalogEntries)(parsed, {
+		onExcessProperty: "error",
+		errors: "all"
+	}).pipe(Result.mapError((error) => error.message.replace(/\n\s+at /g, " at ").replace(/\n/g, "; ")));
+};
+const byCodeUnit = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const syncFile = Effect.fn("Runner.syncFile")(function* (file, text, writing, refused) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const existing = yield* orNone(fs.readFileString(file));
+	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(file), { recursive: true });
+		yield* fs.writeFileString(file, text);
+	}
+	return outcome;
+});
+const encodeEntries = (entries) => CanonicalJson.serialize(entries.map((entry) => Schema.encodeSync(CatalogEntry)(entry)));
+const syncCatalog = Effect.fn("Runner.syncCatalog")(function* (config, names, writing, refused) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const slicePath = path.normalize(ConfigLoader.slicePath(config, path));
+	const mergedPath = path.normalize(ConfigLoader.mergedCatalogPath(config, path));
+	const own = config.schemas.flatMap((schema) => schema.catalog !== void 0 ? [schema.catalog] : []);
+	const exact = `${config.name}.json`;
+	const folded = names.filter((name) => name.toLowerCase() === exact.toLowerCase());
+	const ownOnDisk = names.includes(exact) ? exact : own.length > 0 && folded.length === 1 && Result.isSuccess(yield* Effect.result(fs.stat(slicePath))) ? folded[0] : void 0;
+	const caseFolded = own.length > 0 && ownOnDisk !== void 0 && ownOnDisk !== exact ? { caseFoldedMatch: path.normalize(path.join(config.catalogDir, ownOnDisk)) } : {};
+	let slice;
+	if (own.length === 0) {
+		if (Option.isSome(yield* orNone(fs.stat(slicePath)))) slice = {
+			path: slicePath,
+			entries: 0,
+			outcome: "orphaned"
+		};
+	} else {
+		const outcome = yield* syncFile(slicePath, yield* encodeEntries(own), writing, refused);
+		slice = {
+			path: slicePath,
+			entries: own.length,
+			outcome,
+			...caseFolded
+		};
+	}
+	const sources = [];
+	const invalid = [];
+	for (const name of [...names].sort(byCodeUnit)) {
+		const file = path.normalize(path.join(config.catalogDir, name));
+		if (!name.endsWith(".json") || name === ownOnDisk && own.length > 0) continue;
+		const info = yield* Effect.result(fs.stat(file));
+		if (Result.isFailure(info)) {
+			if (info.failure.reason._tag !== "NotFound") invalid.push({
+				path: file,
+				reason: `unreadable: ${info.failure.reason._tag}`
+			});
+			else if (Result.isSuccess(yield* Effect.result(fs.readLink(file)))) invalid.push({
+				path: file,
+				reason: "unreadable: a dangling symlink"
+			});
+			continue;
+		}
+		if (info.success.type !== "File") continue;
+		const text = yield* Effect.result(fs.readFileString(file));
+		if (Result.isFailure(text)) {
+			if (text.failure.reason._tag !== "NotFound") invalid.push({
+				path: file,
+				reason: `unreadable: ${text.failure.reason._tag}`
+			});
+			continue;
+		}
+		const decoded = decodeSlice(text.success);
+		if (Result.isFailure(decoded)) invalid.push({
+			path: file,
+			reason: decoded.failure
+		});
+		else sources.push({
+			slice: file,
+			entries: decoded.success
+		});
+	}
+	if (own.length > 0) sources.push({
+		slice: slicePath,
+		entries: own
+	});
+	sources.sort((a, b) => byCodeUnit(a.slice, b.slice));
+	let merged;
+	if (sources.length === 0 && invalid.length === 0) {
+		if (Option.isSome(yield* orNone(fs.stat(mergedPath)))) merged = {
+			path: mergedPath,
+			entries: 0,
+			outcome: "orphaned",
+			slices: [],
+			conflicts: [],
+			invalid: []
+		};
+	} else {
+		const claims = /* @__PURE__ */ new Map();
+		const union = [];
+		for (const source of sources) for (const entry of source.entries) {
+			const claimants = claims.get(entry.url);
+			if (claimants === void 0) {
+				claims.set(entry.url, [source.slice]);
+				union.push(entry);
+			} else claimants.push(source.slice);
+		}
+		const conflicts = [...claims].filter(([, slices]) => slices.length > 1).map(([url, slices]) => ({
+			url,
+			slices: [...slices].sort(byCodeUnit)
+		})).sort((a, b) => byCodeUnit(a.url, b.url));
+		union.sort((a, b) => byCodeUnit(a.url, b.url));
+		const outcome = conflicts.length > 0 || invalid.length > 0 ? "blocked" : yield* syncFile(mergedPath, yield* encodeEntries(union), writing, refused);
+		merged = {
+			path: mergedPath,
+			entries: union.length,
+			outcome,
+			slices: sources.map((source) => source.slice),
+			conflicts,
+			invalid
+		};
+	}
+	const report = {
+		...slice !== void 0 ? { slice } : {},
+		...merged !== void 0 ? { merged } : {}
+	};
+	return slice === void 0 && merged === void 0 ? void 0 : report;
+});
 /**
 * The shared `build` / `check` walk: verify every advertised frozen version
 * exists, classify every current target through {@link DriftPolicy} over
@@ -116,16 +278,42 @@ const parsesEqual = (existing, text) => {
 * 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
+* catalog files 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. When no schema declares
-* one, nothing is written; a file still at `catalogPath` is reported
-* `orphaned` (stale under `check`) and left in place, and the report omits
-* `catalog` entirely only when there is no such file either.
+* **Every catalog entry the config declares lands in ONE slice file**,
+* `<catalogDir>/<name>.json` — a bare SchemaStore catalog entry array,
+* never one file per schema — serialized canonically, compared by parsed
+* content against the file on disk, and rewritten wholesale only when
+* different and only when the run is writing. When no schema declares one,
+* no slice is written; a slice still on disk is reported `orphaned` (stale
+* under `check`) and left in place — and still merged, so the merged
+* catalog keeps advertising its entries until it is deleted by hand.
+*
+* **The merged catalog is the union of every slice in `catalogDir`**,
+* written to `catalog.json` in `catalogDir`'s parent, sorted by entry
+* `url`, and compared and written by the same rule. When the running
+* config declares entries, its slice is replaced by the entries it
+* computes now, so `check` compares against what a build would produce;
+* when it declares none, its on-disk slice is merged as-is. The merge is
+* therefore a pure function of disk plus the non-empty fresh entries, and
+* whichever config sharing the directory builds last writes the identical
+* file. A URL advertised by two
+* slices, or a slice that is not JSON or not a catalog entry array, is
+* reported and blocks the merged write (`blocked`) rather than being
+* silently merged or dropped. With no slice file left in `catalogDir` and
+* no entry declared, a merged file still on disk is `orphaned`.
+* `catalogDir` is the one directory the Runner lists: every `*.json` file
+* in it is a slice by construction. It is listed before anything is
+* generated; one that is a file or cannot be listed fails typed with
+* {@link CatalogDirError}, nothing written. The running config's own slice
+* on disk is an exact `<name>.json` match, or — only when there is none,
+* exactly one listed file case-folds to it, and the volume itself resolves
+* the exact path to that file (a `stat` that succeeds, i.e. a
+* case-insensitive volume) — that one file, reported as
+* {@link CatalogSliceReport.caseFoldedMatch}. On a case-sensitive volume the
+* variant is another slice: a case-only rename leftover blocks the merge on
+* the first build like any other rename leftover.
 *
 * **A moved path leaves an orphan the derivation cannot see**: an
 * `appendVersion` flip or a `layout` change renames a document's derived
@@ -135,7 +323,7 @@ const parsesEqual = (existing, text) => {
 * name and label (`<name>.json`, `<name>-<v>.json`, `<v>/<name>.json`,
 * `<v>/<name>-<v>.json`), so both modes probe the sibling shapes of every
 * label the config still knows and report each one that exists as a FILE
-* and that no target, frozen version, or `catalogPath` claims in
+* and that no target, frozen version, catalog slice, or merged catalog claims in
 * {@link RunReport.orphaned}. Nothing else on disk is looked at: an
 * `outputDir` shared with another config, a deploy folder, or the
 * repository root holds documents this config cannot tell from its own
@@ -182,6 +370,12 @@ var Runner = class {
 		}
 		if (missing.length > 0) return yield* Effect.fail(new FrozenVersionMissingError({ missing }));
 		if (mismatched.length > 0) return yield* Effect.fail(new FrozenVersionIdMismatchError({ mismatched }));
+		const listing = yield* Effect.result(fs.readDirectory(config.catalogDir));
+		if (Result.isFailure(listing) && listing.failure.reason._tag !== "NotFound") return yield* Effect.fail(new CatalogDirError({
+			path: config.catalogDir,
+			reason: listingFailureReason(listing.failure)
+		}));
+		const catalogNames = Result.isSuccess(listing) ? listing.success : [];
 		const targets = config.schemas.map((schema) => schema.target);
 		const checks = yield* SchemaPipeline.check(targets, pipelineOptions);
 		const gateFailed = checks.some((check) => check.blocked);
@@ -225,31 +419,8 @@ var Runner = class {
 				...nextVersion !== void 0 ? { nextVersion } : {}
 			};
 		});
-		const entries = config.schemas.flatMap((schema) => schema.catalog !== void 0 ? [schema.catalog] : []);
-		let catalog;
-		if (entries.length === 0) {
-			const info = yield* orNone(fs.stat(config.catalogPath));
-			if (Option.isSome(info)) catalog = {
-				path: config.catalogPath,
-				entries: 0,
-				outcome: "orphaned"
-			};
-		} else {
-			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
-			};
-		}
-		const claimed = /* @__PURE__ */ new Set([path.normalize(config.catalogPath)]);
+		const catalog = yield* syncCatalog(config, catalogNames, writing, refused);
+		const claimed = /* @__PURE__ */ new Set([path.normalize(ConfigLoader.slicePath(config, path)), path.normalize(ConfigLoader.mergedCatalogPath(config, path))]);
 		for (const schema of config.schemas) {
 			claimed.add(path.normalize(schema.target.path));
 			for (const frozen of schema.frozen) claimed.add(path.normalize(frozen.path));
@@ -279,10 +450,10 @@ var Runner = class {
 			...orphaned.length > 0 ? { orphaned } : {},
 			drifted,
 			gateFailed,
-			wrote: schemas.some((s) => s.outcome === "written") || catalog?.outcome === "written"
+			wrote: schemas.some((s) => s.outcome === "written") || catalog?.slice?.outcome === "written" || catalog?.merged?.outcome === "written"
 		};
 	});
 };
 
 //#endregion
-export { FrozenVersionIdMismatchError, FrozenVersionMissingError, Runner };
+export { CatalogDirError, FrozenVersionIdMismatchError, FrozenVersionMissingError, Runner };

package/cli/commands/build.js

@@ -9,7 +9,7 @@ import { Command } from "effect/cli";
 *
 * @public
 */
-const makeBuildCommand = (deps) => Command.make("build", commandFlags, (input) => execute("build", input, deps)).pipe(Command.withDescription("Generate, gate and write every schema and catalog entry the config declares"));
+const makeBuildCommand = (deps) => Command.make("build", commandFlags, (input) => execute("build", input, deps)).pipe(Command.withDescription("Generate, gate and write every schema the config declares, its catalog slice, and the merged catalog"));
 
 //#endregion
 export { makeBuildCommand };

package/cli/commands/check.js

@@ -7,13 +7,13 @@ import { Command } from "effect/cli";
 * `schemastore check`: the same walk as `build`, reported and never written.
 * The CI drift gate: it also fails when the committed documents are stale,
 * i.e. whenever `build` would write anything — and on the outputs nothing
-* claims (an orphaned catalog file, or a document left behind at a sibling
+* claims (an orphaned catalog slice or merged catalog, or a document left behind at a sibling
 * shape of a derived path), which `build` never deletes: remove them by
 * hand.
 *
 * @public
 */
-const makeCheckCommand = (deps) => Command.make("check", commandFlags, (input) => execute("check", input, deps)).pipe(Command.withDescription("Report what build would do, fail when it would write anything or refuse to, or when a catalog file or document is orphaned, and write nothing"));
+const makeCheckCommand = (deps) => Command.make("check", commandFlags, (input) => execute("check", input, deps)).pipe(Command.withDescription("Report what build would do, fail when it would write anything or refuse to, or when a catalog file or document is orphaned or the merged catalog is blocked, and write nothing"));
 
 //#endregion
 export { makeCheckCommand };

package/cli/execute.js

@@ -45,10 +45,35 @@ var GateError = class extends Schema.TaggedError()("GateError", { count: Schema.
 	}
 };
 /**
+* The merged catalog could not be assembled: a catalog URL is advertised by
+* more than one slice, or a slice in `catalogDir` is not a catalog entry
+* array. Nothing is merged silently, so the merged catalog was left as it
+* is. Exit `1` under both `build` and `check`: only an edit to the slices
+* or the configs clears it.
+*
+* @public
+*/
+var CatalogMergeError = class extends Schema.TaggedError()("CatalogMergeError", {
+	path: Schema.String,
+	conflicts: Schema.Array(Schema.Struct({
+		url: Schema.String,
+		slices: Schema.Array(Schema.String)
+	})),
+	invalid: Schema.Array(Schema.Struct({
+		path: Schema.String,
+		reason: Schema.String
+	}))
+}) {
+	get message() {
+		const lines = [...this.conflicts.map((conflict) => `  url ${conflict.url} is advertised by ${conflict.slices.join(", ")}`), ...this.invalid.map(({ path, reason }) => `  ${path} is invalid: ${reason}`)];
+		return `The merged catalog ${this.path} was not written.\n${lines.join("\n")}\nGive each catalog URL to exactly one config, and fix or delete every invalid slice.`;
+	}
+};
+/**
 * `check` found committed documents that differ from what the config
 * generates (or are missing), so a `build` would write — or outputs
-* nothing claims (an orphaned catalog file, an orphaned document), which
-* `build` never deletes. `check` is the CI drift gate, so a stale tree
+* nothing claims (an orphaned catalog slice or merged catalog, an orphaned
+* document), which `build` never deletes. `check` is the CI drift gate, so a stale tree
 * fails it. Exit `1`. `count` is every finding; `orphaned` the part of it
 * a build cannot clear, so the message names both remedies.
 *
@@ -99,9 +124,11 @@ const emit = Effect.fn("schemastore.emit")(function* (report, format) {
 * `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
+* `GateError`, then `DriftError`, then `CatalogMergeError`, then (for
+* `check` only) `StaleError`, each carrying exit `1` — when the report says
+* the run refused to write, the merged catalog was blocked by a URL
+* conflict or an invalid slice, 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.
 *
@@ -122,7 +149,8 @@ const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
 		...drift
 	}).pipe(Effect.provide(SchemaFile.layer), Effect.provide(deps.validator ?? AjvValidator.layer), Effect.catchTags({
 		FrozenVersionMissingError: (error) => Effect.fail(CliRuntime.reported(error, 1)),
-		FrozenVersionIdMismatchError: (error) => Effect.fail(CliRuntime.reported(error, 1))
+		FrozenVersionIdMismatchError: (error) => Effect.fail(CliRuntime.reported(error, 1)),
+		CatalogDirError: (error) => Effect.fail(CliRuntime.reported(error, 2))
 	}));
 	yield* emit(report, input.format);
 	yield* StepSummary.append(Report.markdown(report));
@@ -139,9 +167,16 @@ const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
 		}));
 		return yield* Effect.fail(CliRuntime.reported(new DriftError({ drifted }), 1));
 	}
+	const merged = report.catalog?.merged;
+	if (merged?.outcome === "blocked") return yield* Effect.fail(CliRuntime.reported(new CatalogMergeError({
+		path: merged.path,
+		conflicts: merged.conflicts,
+		invalid: merged.invalid
+	}), 1));
 	if (mode === "check") {
-		const orphaned = (report.catalog?.outcome === "orphaned" ? 1 : 0) + (report.orphaned?.length ?? 0);
-		const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + (report.catalog?.outcome === "would-write" ? 1 : 0) + orphaned;
+		const catalogFiles = [report.catalog?.slice?.outcome, merged?.outcome];
+		const orphaned = catalogFiles.filter((outcome) => outcome === "orphaned").length + (report.orphaned?.length ?? 0);
+		const count = report.schemas.filter((schema) => schema.outcome === "would-write").length + catalogFiles.filter((outcome) => outcome === "would-write").length + orphaned;
 		if (count > 0) return yield* Effect.fail(CliRuntime.reported(new StaleError({
 			count,
 			...orphaned > 0 ? { orphaned } : {}
@@ -150,4 +185,4 @@ const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
 });
 
 //#endregion
-export { ConflictingFlagsError, DriftError, GateError, StaleError, execute };
+export { CatalogMergeError, ConflictingFlagsError, DriftError, GateError, StaleError, execute };

package/cli/program.js

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

package/main.js

@@ -6,16 +6,11 @@ import { CliRuntime } from "@effected/cli";
 import { CliError } from "effect/cli";
 
 //#region src/main.ts
-/**
-* The assembled schemastore CLI program.
-*
-* @packageDocumentation
-*/
 const render = (error) => CliError.isCliError(error) && error._tag === "ShowHelp" ? [] : [error instanceof Error ? error.message : String(error)];
 const main = () => {
 	const run = program(process.argv.slice(2), {
 		cwd: process.cwd(),
-		version: "0.16.1"
+		version: "0.18.0"
 	}).pipe(Effect.provide(NodeServices.layer), CliRuntime.reportFailures({
 		exitCode: 3,
 		render

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore-cli",
-	"version": "0.16.1",
+	"version": "0.18.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": [
@@ -40,15 +40,18 @@
 		"schemastore": "bin/schemastore.js"
 	},
 	"dependencies": {
-		"@effect/platform-node": "4.0.0-rc.118",
-		"@effected/cli": "^0.10.0",
+		"@effect/platform-node": "^4.0.0",
+		"@effected/cli": "^0.11.0",
+		"@effected/env": "^0.1.0",
+		"@effected/glob": "^0.10.0",
+		"@effected/walker": "^0.15.0",
 		"ajv": "^8.20.0",
 		"ajv-formats": "^3.0.1",
 		"jiti": "^2.6.0"
 	},
 	"peerDependencies": {
-		"@effected/schemastore": "0.16.1",
-		"effect": "4.0.0-rc.118"
+		"@effected/schemastore": "0.18.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"