@effected/schemastore-cli 0.12.0 → 0.13.0

package/README.md

@@ -114,9 +114,9 @@ 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.
+- `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.
 - `--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, `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 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.
 
 ## The engine, as a library export
 
@@ -140,7 +140,7 @@ 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 |
+| 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 |
 | 3 | infrastructure failure |
 | 64 | usage error |

package/Report.js

@@ -27,6 +27,7 @@ const catalogLine = (entry) => {
 		default: return entry.outcome;
 	}
 };
+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) => {
 	const written = report.schemas.filter((schema) => schema.outcome === "written").length;
@@ -58,6 +59,7 @@ var Report = class {
 		const lines = [];
 		for (const schema of report.schemas) lines.push(...schemaLines(schema, report));
 		if (report.catalog !== void 0) lines.push(catalogLine(report.catalog));
+		for (const orphan of report.orphaned ?? []) lines.push(orphanedLine(orphan));
 		lines.push(summaryLine(report));
 		return lines;
 	}
@@ -104,6 +106,7 @@ var Report = class {
 				entries: report.catalog.entries,
 				outcome: report.catalog.outcome
 			} } : {},
+			...report.orphaned !== void 0 ? { orphaned: report.orphaned } : {},
 			drifted: report.drifted,
 			gateFailed: report.gateFailed,
 			wrote: report.wrote
@@ -149,6 +152,7 @@ var Report = class {
 			String(report.catalog.entries),
 			report.catalog.outcome
 		]));
+		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) {
 			const failed = report.schemas.filter((schema) => schema.outcome === "gate-failed").length;

package/Runner.js

@@ -127,6 +127,22 @@ const parsesEqual = (existing, text) => {
 * `orphaned` (stale under `check`) and left in place, and the report omits
 * `catalog` entirely only when there is no such file either.
 *
+* **A moved path leaves an orphan the derivation cannot see**: an
+* `appendVersion` flip or a `layout` change renames a document's derived
+* path, and the previously written file stays on disk under the old name —
+* for a `published` label, its advertised URL keeps serving a stale
+* document with no report. The derivation has exactly four shapes for a
+* 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
+* {@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
+* leftovers, so they are never reported. A `name` change is therefore not
+* caught either — the old name is unknowable. Orphans are reported, never
+* deleted: the CLI may not have written them.
+*
 * @public
 */
 var Runner = class {
@@ -233,6 +249,26 @@ var Runner = class {
 				outcome
 			};
 		}
+		const claimed = /* @__PURE__ */ new Set([path.normalize(config.catalogPath)]);
+		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));
+		}
+		const orphaned = [];
+		for (const schema of config.schemas) {
+			const labels = [schema.target.version, ...schema.frozen.map((frozen) => frozen.version)];
+			const shapes = [SchemaVersioning.fileName(schema.name), ...labels.flatMap((version) => version === void 0 ? [] : [
+				SchemaVersioning.fileName(schema.name, version, "flat"),
+				SchemaVersioning.fileName(schema.name, version, "versioned"),
+				SchemaVersioning.fileName(schema.name, version, "versioned", false)
+			])];
+			for (const shape of shapes) {
+				const file = path.normalize(path.join(config.outputDir, shape));
+				if (claimed.has(file)) continue;
+				const info = yield* orNone(fs.stat(file));
+				if (Option.isSome(info) && info.value.type === "File") orphaned.push(file);
+			}
+		}
 		return {
 			mode: options.mode,
 			configPath: options.configPath,
@@ -240,6 +276,7 @@ var Runner = class {
 			...options.policy !== void 0 ? { policy: options.policy } : {},
 			schemas,
 			...catalog !== void 0 ? { catalog } : {},
+			...orphaned.length > 0 ? { orphaned } : {},
 			drifted,
 			gateFailed,
 			wrote: schemas.some((s) => s.outcome === "written") || catalog?.outcome === "written"

package/cli/commands/check.js

@@ -6,11 +6,14 @@ import { Command } from "effect/unstable/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.
+* 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
+* 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, 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, and write nothing"));
 
 //#endregion
 export { makeCheckCommand };

package/cli/execute.js

@@ -46,14 +46,22 @@ var GateError = class extends Schema.TaggedError()("GateError", { count: Schema.
 };
 /**
 * `check` found committed documents that differ from what the config
-* generates (or are missing), so a `build` would write. `check` is the CI
-* drift gate, so a stale tree fails it. Exit `1`.
+* 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
+* fails it. Exit `1`. `count` is every finding; `orphaned` the part of it
+* a build cannot clear, so the message names both remedies.
 *
 * @public
 */
-var StaleError = class extends Schema.TaggedError()("StaleError", { count: Schema.Number }) {
+var StaleError = class extends Schema.TaggedError()("StaleError", {
+	count: Schema.Number,
+	orphaned: Schema.optionalKey(Schema.Number)
+}) {
 	get message() {
-		return `${this.count} document(s) are stale; run \`schemastore build\` and commit the result.`;
+		const orphaned = this.orphaned ?? 0;
+		const stale = this.count - orphaned;
+		return [...stale > 0 ? [`${stale} document(s) are stale; run \`schemastore build\` and commit the result.`] : [], ...orphaned > 0 ? [`${orphaned} orphaned output(s) must be deleted by hand; build never will.`] : []].join(" ");
 	}
 };
 /**
@@ -132,8 +140,12 @@ const execute = Effect.fn("schemastore.execute")(function* (mode, input, deps) {
 		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?.outcome === "would-write" || report.catalog?.outcome === "orphaned" ? 1 : 0);
-		if (count > 0) return yield* Effect.fail(CliRuntime.reported(new StaleError({ count }), 1));
+		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;
+		if (count > 0) return yield* Effect.fail(CliRuntime.reported(new StaleError({
+			count,
+			...orphaned > 0 ? { orphaned } : {}
+		}), 1));
 	}
 });
 

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.12.0"
+		version: "0.13.0"
 	}).pipe(Effect.provide(NodeServices.layer), CliRuntime.reportFailures({
 		exitCode: 3,
 		render

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore-cli",
-	"version": "0.12.0",
+	"version": "0.13.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": [
@@ -47,7 +47,7 @@
 		"jiti": "^2.6.0"
 	},
 	"peerDependencies": {
-		"@effected/schemastore": "0.12.0",
+		"@effected/schemastore": "0.13.0",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {