@effected/schemastore-cli 0.19.0 → 0.21.0

package/README.md

@@ -119,7 +119,7 @@ schemastore validate <payload.json> [config] [--schema <path|$id|url>] [--format
 
 - 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 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.
+- `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 or entry name advertised more than once across the 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 or name and its slices or the invalid slice, and the merged file is left as it is until the configs or slices are fixed.
 - `validate` answers the question the publication story exists for: does THIS payload conform to the published document it names? The reference is the `--schema` flag or the payload's own `$schema`, resolved file-first and then against every identity a config schema derives (a target `$id`, a frozen version's `$id`/`url`, the catalog `url`) — CI validates an action's output against the committed document with no third-party tool and no network fetch. The payload's `$schema` self-reference is the pointer naming the document: it is stripped before validating only when the resolved document does not declare `$schema` as a root property, since a generated document's `additionalProperties: false` would otherwise reject the very self-reference that names it. A document that does declare `$schema` — the `HostedSchema` pattern above, where the source struct carries `$schema: Schema.Literal(...)` and the generated document requires and const-constrains the key — validates the payload verbatim. A non-conforming payload fails (exit `1`) with one finding per problem, each carrying the JSON pointer into the instance and the keyword; `--format=json` writes one report document to stdout and moves the human lines to stderr.
 - `--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 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.
@@ -154,13 +154,15 @@ Findings come back as values — `ValidationFinding` pointers into the document
 
 ## Exit codes
 
+A failure is reported on stderr in the `@effected/cli` standard form: a status line naming the error and its message, the message's further lines, and, when the failure happened inside one of the command's spans, an `in: …` line naming them (a missing config, raised before any span, prints none). It is painted at a terminal, plain for an agent, and written for the log under GitHub Actions. Read the exit code, not the line's shape.
+
 | 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, a merged catalog blocked by a URL two slices advertise or an invalid slice, — 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), or — for `validate` — a payload that does not conform to the resolved document (one finding per problem, pointer and keyword each) |
+| 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 or name advertised twice or an invalid slice, — 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), or — for `validate` — a payload that does not conform to the resolved document (one finding per problem, pointer and keyword each) |
 | 2 | config not found, failed to load, failed `defineConfig` validation, a `catalogDir` that is a file or cannot be listed (checked before anything is written), or — for `validate` — a payload that cannot be read or parsed, or a `--schema`/`$schema` reference that is neither an existing file nor an identity any config schema derives, or names a document that cannot be read or parsed |
 | 3 | infrastructure failure (for `validate`, an engine mechanism failure — a document the instance engine cannot compile — included) |
-| 64 | usage error (for `validate`, a payload with no `$schema` and no `--schema` given, included) |
+| 64 | usage error (for `validate`, a payload with no `$schema` and no `--schema` given, included); `--wizard` is the kit's prompt-gated flag, so a run that is not interactive (a pipe, CI, an agent) leaves it out of help and rejects it at `64` (it was accepted at `0` before the command moved onto `CliRuntime.main`) |
 
 ## License
 

package/Report.js

@@ -29,6 +29,7 @@ const sliceLine = (slice) => {
 		default: return slice.outcome;
 	}
 };
+const conflictSubject = (conflict) => conflict.kind === "url" ? `url ${conflict.url}` : `name ${conflict.name}`;
 const mergedLines = (merged) => {
 	const counts = `(${merged.entries} entries from ${merged.slices.length} slice(s))`;
 	switch (merged.outcome) {
@@ -39,7 +40,7 @@ const mergedLines = (merged) => {
 		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.conflicts.map((conflict) => `  ${conflictSubject(conflict)} advertised by ${conflict.slices.join(", ")}`),
 			...merged.invalid.map(({ path, reason }) => `  slice ${path} is invalid: ${reason}`)
 		];
 		default: return merged.outcome;
@@ -58,10 +59,15 @@ const catalogJson = (catalog) => ({
 		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.conflicts.length > 0 ? { conflicts: catalog.merged.conflicts.map((conflict) => conflict.kind === "url" ? {
+			kind: conflict.kind,
+			url: conflict.url,
+			slices: conflict.slices
+		} : {
+			kind: conflict.kind,
+			name: conflict.name,
+			slices: conflict.slices
+		}) } : {},
 		...catalog.merged.invalid.length > 0 ? { invalid: catalog.merged.invalid.map(({ path, reason }) => ({
 			path,
 			reason
@@ -200,7 +206,7 @@ var Report = class {
 				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 (merged !== void 0 && (merged.conflicts.length > 0 || merged.invalid.length > 0)) lines.push("", tableRow(["catalog problem", "slices"]), tableRow(["---", "---"]), ...merged.conflicts.map((conflict) => tableRow([conflictSubject(conflict), 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("");

package/Runner.js

@@ -221,18 +221,31 @@ const syncCatalog = Effect.fn("Runner.syncCatalog")(function* (config, names, wr
 		};
 	} else {
 		const claims = /* @__PURE__ */ new Map();
+		const nameClaims = /* @__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);
+				const nameClaimants = nameClaims.get(entry.name);
+				if (nameClaimants === void 0) nameClaims.set(entry.name, [source.slice]);
+				else nameClaimants.push(source.slice);
 			} else claimants.push(source.slice);
 		}
-		const conflicts = [...claims].filter(([, slices]) => slices.length > 1).map(([url, slices]) => ({
-			url,
+		const repeated = (claimed) => [...claimed].filter(([, slices]) => slices.length > 1).sort(([a], [b]) => byCodeUnit(a, b)).map(([value, slices]) => ({
+			value,
 			slices: [...slices].sort(byCodeUnit)
-		})).sort((a, b) => byCodeUnit(a.url, b.url));
+		}));
+		const conflicts = [...repeated(claims).map(({ value, slices }) => ({
+			kind: "url",
+			url: value,
+			slices
+		})), ...repeated(nameClaims).map(({ value, slices }) => ({
+			kind: "name",
+			name: value,
+			slices
+		}))];
 		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 = {

package/cli/execute.js

@@ -45,8 +45,8 @@ 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
+* The merged catalog could not be assembled: a catalog URL or entry name is
+* advertised more than once across the slices, 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.
@@ -55,18 +55,23 @@ var GateError = class extends Schema.TaggedError()("GateError", { count: Schema.
 */
 var CatalogMergeError = class extends Schema.TaggedError()("CatalogMergeError", {
 	path: Schema.String,
-	conflicts: Schema.Array(Schema.Struct({
+	conflicts: Schema.Array(Schema.Union([Schema.Struct({
+		kind: Schema.Literal("url"),
 		url: Schema.String,
 		slices: Schema.Array(Schema.String)
-	})),
+	}), Schema.Struct({
+		kind: Schema.Literal("name"),
+		name: 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.`;
+		const lines = [...this.conflicts.map((conflict) => `  ${conflict.kind === "url" ? `url ${conflict.url}` : `name ${conflict.name}`} 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 and name to exactly one config, and fix or delete every invalid slice.`;
 	}
 };
 /**
@@ -126,7 +131,7 @@ const emit = Effect.fn("schemastore.emit")(function* (report, format) {
 * requested format, appends the step summary, and fails typed —
 * `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
+* the run refused to write, the merged catalog was blocked by a URL or name
 * 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

package/main.js

@@ -1,22 +1,34 @@
 import { loggerLayer, program } from "./cli/program.js";
-import { Effect } from "effect";
 import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { CliRuntime } from "@effected/cli";
-import { CliError } from "effect/cli";
 
 //#region src/main.ts
-const render = (error) => CliError.isCliError(error) && error._tag === "ShowHelp" ? [] : [error instanceof Error ? error.message : String(error)];
+/**
+* How `CliRuntime.main` runs the command: the kit's standard failure report, exit `3` for a typed error that carries
+* no code of its own (the infrastructure tier; every other code is marked where it is raised), and this module as the
+* program's own, so the report's span trail keeps the command's spans when it is installed under
+* `node_modules/@effected/` and leaves out the kit's.
+*/
+const mainOptions = {
+	exitCode: 3,
+	logger: loggerLayer,
+	env: { appModule: import.meta.url }
+};
+/**
+* The command under `CliRuntime.main` over `platform`: what `main` runs with `NodeServices.layer`, and what a test runs
+* with a test `Command.Environment`.
+*/
+const run = (args, deps, platform) => CliRuntime.main(program(args, deps), {
+	...mainOptions,
+	platform
+});
 const main = () => {
-	const run = program(process.argv.slice(2), {
+	NodeRuntime.runMain(run(process.argv.slice(2), {
 		cwd: process.cwd(),
-		version: "0.19.0"
-	}).pipe(Effect.provide(NodeServices.layer), CliRuntime.reportFailures({
-		exitCode: 3,
-		render
-	}), Effect.provide(loggerLayer));
-	NodeRuntime.runMain(run);
+		version: "0.21.0"
+	}, NodeServices.layer));
 };
 
 //#endregion
-export { main };
+export { main, mainOptions, run };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore-cli",
-	"version": "0.19.0",
+	"version": "0.21.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": [
@@ -41,7 +41,7 @@
 	},
 	"dependencies": {
 		"@effect/platform-node": "^4.0.0",
-		"@effected/cli": "^0.11.0",
+		"@effected/cli": "^0.12.0",
 		"@effected/env": "^0.1.0",
 		"@effected/glob": "^0.10.0",
 		"@effected/walker": "^0.15.0",
@@ -50,7 +50,7 @@
 		"jiti": "^2.6.0"
 	},
 	"peerDependencies": {
-		"@effected/schemastore": "0.19.0",
+		"@effected/schemastore": "0.21.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {