@effected/schemastore 0.16.1 → 0.17.0

package/README.md

@@ -61,6 +61,7 @@ import { defineConfig } from "@effected/schemastore";
 import { OutputSchemaIdentity, ReleaseOutput } from "./src/schema/output.js";
 
 export default defineConfig({
+  name: "silk-release-action",
   outputDir: "schemas",
   schemas: {
     [OutputSchemaIdentity.name]: { schema: ReleaseOutput, hosted: OutputSchemaIdentity },
@@ -130,7 +131,7 @@ const program = SchemaPipeline.run(targets).pipe(
 ## What the library owns
 
 - `HostedSchema` — a schema's hosted identity (`github`, `schemastore`, `custom`), deriving `$id`, the catalog URL and the file name for the current or any advertised version.
-- `defineConfig` — the `schemastore.config.ts` contract: validated with one `Schema.Struct` per level (a typo'd key is named, every issue on an entry reported at once), every path and URL derived from the entry key and its identity, frozen labels resolved, a branded result the CLI recognises.
+- `defineConfig` — the `schemastore.config.ts` contract: validated with one `Schema.Struct` per level (a typo'd key is named, every issue on an entry reported at once), a required config `name` (the base name of its catalog slice), every path and URL derived from the entry key and its identity, frozen labels resolved, a branded result the CLI recognises.
 - `StoreDocument` — assembly: `fromSchema` / `fromSchemaResult`, the `draft07` constructor for hand-built documents, the flat `toJson()` publication shape, `serializeResult()`, `DRAFT_07_META_SCHEMA`.
 - `KeywordFamilies` — the one registry of declared non-standard keyword families (the vscode five, `x-taplo`, `x-tombi-`, `x-intellij-`, and the house `x-ai-` machine-annotation namespace). Anything outside it fails `fromSchema` with `UndeclaredAnnotationKeyError`; nothing is silently dropped.
 - `SchemaVersioning` / `SchemaVersion` — one-to-three-component version labels, `Order`, `latest`, `isPinned`, `next`, and the `fileName` / `schemaUrl` / `catalogUrls` derivations.

package/SchemastoreConfig.js

@@ -50,11 +50,12 @@ const EntryInput = Schema.Struct({
 	rootAnnotations: Schema.optionalKey(OptionsInput)
 });
 const ConfigInput = Schema.Struct({
+	name: Schema.String,
 	outputDir: Schema.NonEmptyString,
 	baseUrl: Schema.optionalKey(Schema.String),
 	drift: Schema.optionalKey(DriftToleranceInput),
 	onDrift: Schema.optionalKey(OnDriftInput),
-	catalogPath: Schema.optionalKey(Schema.NonEmptyString),
+	catalogDir: Schema.optionalKey(Schema.NonEmptyString),
 	schemas: Schema.Record(Schema.String, Schema.Unknown)
 });
 const DECODE_OPTIONS = {
@@ -156,6 +157,12 @@ const normalizePath = (raw) => {
 	}
 	return `${absolute ? "/" : ""}${out.join("/")}`;
 };
+const assertCatalogDirHoldsOnlySlices = (catalogDir, outputDir, documents) => {
+	const dir = normalizePath(catalogDir);
+	if (dir === normalizePath(`${catalogDir}/../catalog.json`)) fail(`catalogDir "${catalogDir}" must not be the merged catalog's path (catalog.json in its parent)`);
+	if (dir === normalizePath(outputDir)) fail(`catalogDir "${catalogDir}" must not be outputDir: every *.json file in it is read as a catalog slice`);
+	for (const document of documents) if (normalizePath(`${document}/..`) === dir) fail(`output path "${document}" sits in catalogDir "${catalogDir}", which holds only catalog slices`);
+};
 const assertUniquePaths = (paths) => {
 	const seen = /* @__PURE__ */ new Set();
 	for (const p of paths) {
@@ -189,18 +196,26 @@ const assertUniquePaths = (paths) => {
 * {@link HostedSchema}, or one built from `baseUrl`/`versions`/`current`/
 * `layout` and the config default — is validated by `HostedSchema` itself
 * (a `hosted` entry must be keyed by `hosted.name` and must not spell those
-* four fields beside it); a schema key must be a simple file base name; a
-* `catalog` is required under `baseUrl: "schemastore"`; an empty `schemas`
-* record is rejected; and an output path (a target, a frozen file, or the
-* catalog path) declared twice is rejected after a lexical normalisation
-* (`./`, `..`, trailing `/`) — the CLI's loader re-checks on the resolved
-* absolute paths. Branding the result lets a loader recognise a config
+* four fields beside it); the config `name` is required (a missing one
+* fails `defineConfig: name is required — …`, naming what it is for), and
+* it and every schema key must be simple file base names; a `catalog` is required under
+* `baseUrl: "schemastore"`; an empty `schemas` record is rejected; a
+* `catalogDir` that is `outputDir`, that is the merged catalog's own path,
+* or that a derived document sits directly in, is rejected (every `*.json`
+* file there is read as a catalog slice); and an output path (a target, a frozen file, this config's
+* catalog slice `<catalogDir>/<name>.json`, or the merged catalog
+* `catalog.json` in `catalogDir`'s parent) declared twice is rejected after
+* a lexical normalisation (`./`, `..`, trailing `/`) — the CLI's loader
+* re-checks on the resolved absolute paths. Branding the result lets a loader recognise a config
 * module's default export via {@link isSchemastoreConfig}.
 *
 * @public
 */
 const defineConfig = (input) => {
-	const config = decodeOrThrow(ConfigInput, withoutUndefined(input), "");
+	const raw = withoutUndefined(input);
+	if (Predicate.isObject(raw) && !Array.isArray(raw) && !Object.hasOwn(raw, "name")) return fail("name is required — the base name of this config's catalog slice (<catalogDir>/<name>.json)");
+	const config = decodeOrThrow(ConfigInput, raw, "");
+	if (!SchemaVersioning.isSimpleName(config.name)) return fail(`name "${config.name}" must be a simple file base name (no separators, no whitespace)`);
 	const outputDir = trimSlashes(config.outputDir);
 	if (Object.keys(config.schemas).length === 0) return fail("at least one schema is required");
 	const defaults = {
@@ -208,13 +223,20 @@ const defineConfig = (input) => {
 		drift: config.drift ?? DriftPolicy.defaults.policy
 	};
 	const schemas = Object.entries(config.schemas).map(([name, entry]) => resolveEntry(name, entry, defaults, outputDir));
-	const catalogPath = config.catalogPath ?? `${outputDir}/catalog.json`;
-	assertUniquePaths([...schemas.flatMap((s) => [s.target.path, ...s.frozen.map((f) => f.path)]), catalogPath]);
+	const catalogDir = config.catalogDir !== void 0 ? trimSlashes(config.catalogDir) : `${outputDir}/catalogs`;
+	const documents = schemas.flatMap((s) => [s.target.path, ...s.frozen.map((f) => f.path)]);
+	assertCatalogDirHoldsOnlySlices(catalogDir, outputDir, documents);
+	assertUniquePaths([
+		...documents,
+		`${catalogDir}/${config.name}.json`,
+		`${catalogDir}/../catalog.json`
+	]);
 	return {
 		[ConfigBrand]: true,
+		name: config.name,
 		outputDir,
 		onDrift: config.onDrift ?? DriftPolicy.defaults.onDrift,
-		catalogPath,
+		catalogDir,
 		schemas
 	};
 };

package/index.d.ts

@@ -1890,6 +1890,15 @@ interface SchemaEntryInput {
  * @public
  */
 interface SchemastoreConfigInput {
+  /**
+   * This config's identity: the base name of the catalog slice it owns
+   * (`<catalogDir>/<name>.json`). Configs sharing a `catalogDir` must each
+   * carry a distinct one — distinct case-insensitively, since on a
+   * case-insensitive volume `docs` and `Docs` name one file and overwrite
+   * each other; it must be a simple file base name (no separators, no
+   * whitespace).
+   */
+  readonly name: string;
   /** The directory every derived `path` is written under; a trailing slash is trimmed. */
   readonly outputDir: string;
   /** The default {@link SchemaEntryInput.baseUrl} for an entry that declares none. */
@@ -1898,8 +1907,20 @@ interface SchemastoreConfigInput {
   readonly drift?: DriftTolerance;
   /** What a build does when it finds drift. Defaults to `"error"`. */
   readonly onDrift?: OnDrift;
-  /** Where the assembled catalog is written. Defaults to `<outputDir>/catalog.json`. */
-  readonly catalogPath?: string;
+  /**
+   * The directory of catalog slices, one per config: this config writes its
+   * own entries to `<catalogDir>/<name>.json`, and the CLI maintains the
+   * merged `catalog.json` — every slice in the directory, united — in the
+   * directory's parent. Defaults to `<outputDir>/catalogs`, so
+   * the merged catalog lands at `<outputDir>/catalog.json`. Every `*.json`
+   * file in it is read as a slice, so it holds nothing else, must not be
+   * `outputDir` itself, and must not be the merged catalog's own path.
+   * Every config that shares a merged catalog must share the same
+   * `catalogDir`, under a `name` unique case-insensitively among them: two sibling directories (`schemas/catalogs`,
+   * `schemas/more`) both merge into `schemas/catalog.json` from different
+   * slice sets and overwrite each other — no single config can detect it.
+   */
+  readonly catalogDir?: string;
   /**
    * The schemas to derive, keyed by file base name — the key IS the
    * `name` every derived path and URL is built from, so it must be a
@@ -1952,12 +1973,14 @@ interface ResolvedSchema {
  */
 interface SchemastoreConfig {
   readonly [ConfigBrand]: true;
+  /** This config's identity: the base name of its catalog slice. */
+  readonly name: string;
   /** The directory every derived `path` is written under, trailing slash trimmed. */
   readonly outputDir: string;
   /** What a build does when it finds drift. */
   readonly onDrift: OnDrift;
-  /** Where the assembled catalog is written. */
-  readonly catalogPath: string;
+  /** The directory of catalog slices; this config's own is `<catalogDir>/<name>.json`. */
+  readonly catalogDir: string;
   /** Every schema, resolved. */
   readonly schemas: ReadonlyArray<ResolvedSchema>;
 }
@@ -1986,12 +2009,17 @@ interface SchemastoreConfig {
  * {@link HostedSchema}, or one built from `baseUrl`/`versions`/`current`/
  * `layout` and the config default — is validated by `HostedSchema` itself
  * (a `hosted` entry must be keyed by `hosted.name` and must not spell those
- * four fields beside it); a schema key must be a simple file base name; a
- * `catalog` is required under `baseUrl: "schemastore"`; an empty `schemas`
- * record is rejected; and an output path (a target, a frozen file, or the
- * catalog path) declared twice is rejected after a lexical normalisation
- * (`./`, `..`, trailing `/`) — the CLI's loader re-checks on the resolved
- * absolute paths. Branding the result lets a loader recognise a config
+ * four fields beside it); the config `name` is required (a missing one
+ * fails `defineConfig: name is required — …`, naming what it is for), and
+ * it and every schema key must be simple file base names; a `catalog` is required under
+ * `baseUrl: "schemastore"`; an empty `schemas` record is rejected; a
+ * `catalogDir` that is `outputDir`, that is the merged catalog's own path,
+ * or that a derived document sits directly in, is rejected (every `*.json`
+ * file there is read as a catalog slice); and an output path (a target, a frozen file, this config's
+ * catalog slice `<catalogDir>/<name>.json`, or the merged catalog
+ * `catalog.json` in `catalogDir`'s parent) declared twice is rejected after
+ * a lexical normalisation (`./`, `..`, trailing `/`) — the CLI's loader
+ * re-checks on the resolved absolute paths. Branding the result lets a loader recognise a config
  * module's default export via {@link isSchemastoreConfig}.
  *
  * @public

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore",
-	"version": "0.16.1",
+	"version": "0.17.0",
 	"private": false,
 	"description": "Build, validate, version and publish SchemaStore-shaped Draft-07 JSON Schema documents from Effect Schema sources: document assembly, ajv strict-mode validation, structural lints, catalog entries, canonical JSON and a content-comparing emit pipeline.",
 	"keywords": [