@effected/schemastore 0.16.0 → 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/StoreDocument.js

@@ -128,6 +128,52 @@ const restoreDefsRefs = (node, depth) => {
 	}
 	return node;
 };
+const SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
+	"items",
+	"additionalItems",
+	"contains",
+	"additionalProperties",
+	"propertyNames",
+	"not",
+	"if",
+	"then",
+	"else"
+]);
+const SCHEMA_ARRAY_KEYWORDS = /* @__PURE__ */ new Set([
+	"allOf",
+	"anyOf",
+	"oneOf"
+]);
+const SCHEMA_MAP_KEYWORDS = /* @__PURE__ */ new Set([
+	"properties",
+	"patternProperties",
+	"definitions",
+	"$defs",
+	"dependencies"
+]);
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const collapseSchemaMap = (node, depth) => {
+	if (!isPlainObject(node)) return node;
+	const out = Object.create(null);
+	for (const [key, value] of Object.entries(node)) out[key] = isPlainObject(value) ? collapseUniformTuples(value, depth + 1) : value;
+	return out;
+};
+const collapseUniformTuples = (node, depth) => {
+	if (depth >= 256) throw new RewriteDepthExceeded();
+	if (!isPlainObject(node)) return node;
+	const out = Object.create(null);
+	for (const [key, value] of Object.entries(node)) if (SCHEMA_KEYWORDS.has(key)) out[key] = Array.isArray(value) ? value.map((item) => collapseUniformTuples(item, depth + 1)) : collapseUniformTuples(value, depth + 1);
+	else if (SCHEMA_ARRAY_KEYWORDS.has(key) && Array.isArray(value)) out[key] = value.map((item) => collapseUniformTuples(item, depth + 1));
+	else if (SCHEMA_MAP_KEYWORDS.has(key)) out[key] = collapseSchemaMap(value, depth + 1);
+	else out[key] = value;
+	const tuple = out.items;
+	const rest = out.additionalItems;
+	if (Array.isArray(tuple) && tuple.length > 0 && isPlainObject(rest) && tuple.every((element) => CanonicalJson.equals(element, rest))) {
+		out.items = rest;
+		delete out.additionalItems;
+	}
+	return out;
+};
 /**
 * A SchemaStore-shaped Draft-07 JSON Schema document assembled from an
 * Effect Schema source: `$schema` (the Draft-07 meta-schema) + `$id` + the
@@ -137,9 +183,11 @@ const restoreDefsRefs = (node, depth) => {
 * `Schema.toJsonSchemaDocument` (Draft 2020-12), core's
 * `JsonSchema.toDocumentDraft07` lowering, the `#/definitions` →
 * `#/$defs` `$ref` rewrite the lowering makes necessary — so every `$ref`
-* in a built document already resolves against the `$defs` pool — and the
-* gate that holds the document's non-standard surface to the declared
-* keyword families ({@link KeywordFamilies}). The package owns assembly and
+* in a built document already resolves against the `$defs` pool — the
+* uniform-tuple collapse that keeps open-ended `NonEmptyArray`-shaped
+* arrays publishable through the strict ajv gate (#818), and the gate that
+* holds the document's non-standard surface to the declared keyword
+* families ({@link KeywordFamilies}). The package owns assembly and
 * publication shape, not a JSON Schema engine.
 *
 * Annotated declared-family keys survive into the built document because
@@ -148,7 +196,12 @@ const restoreDefsRefs = (node, depth) => {
 * (2020-12 `prefixItems[i]` → Draft-07 `items[i]`, trailing `items` →
 * `additionalItems`). This package therefore does no re-grafting of its
 * own; it only declines to rewrite `$ref`-shaped strings *inside* those
-* opaque payloads.
+* opaque payloads. The one structural normalization it does own is the
+* uniform-tuple collapse: when every tuple element is content-equal to the
+* open rest schema — always true for `NonEmptyArray` — the tuple is
+* rewritten to a single-schema `items` with core's `minItems` untouched,
+* the shape ajv's strictTuples rule accepts; a heterogeneous head keeps the
+* tuple form.
 *
 * @public
 */
@@ -220,9 +273,9 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 				keys: [...undeclared].sort()
 			}));
 			const lowered = JsonSchema.toDocumentDraft07(document);
-			const root = restoreDefsRefs(lowered.schema, 0);
+			const root = collapseUniformTuples(restoreDefsRefs(lowered.schema, 0), 0);
 			const defs = Object.create(null);
-			for (const [name, definition] of Object.entries(lowered.definitions)) defs[name] = restoreDefsRefs(definition, 1);
+			for (const [name, definition] of Object.entries(lowered.definitions)) defs[name] = collapseUniformTuples(restoreDefsRefs(definition, 1), 1);
 			if (options.rootAnnotations !== void 0) applyRootAnnotations(root, defs, options.rootAnnotations);
 			return Result.succeed(StoreDocument.make({
 				$schema: DRAFT_07_META_SCHEMA,

package/index.d.ts

@@ -339,9 +339,11 @@ declare const StoreDocument_base: Schema.Class<StoreDocument, Schema.Struct<{
  * `Schema.toJsonSchemaDocument` (Draft 2020-12), core's
  * `JsonSchema.toDocumentDraft07` lowering, the `#/definitions` →
  * `#/$defs` `$ref` rewrite the lowering makes necessary — so every `$ref`
- * in a built document already resolves against the `$defs` pool — and the
- * gate that holds the document's non-standard surface to the declared
- * keyword families ({@link KeywordFamilies}). The package owns assembly and
+ * in a built document already resolves against the `$defs` pool — the
+ * uniform-tuple collapse that keeps open-ended `NonEmptyArray`-shaped
+ * arrays publishable through the strict ajv gate (#818), and the gate that
+ * holds the document's non-standard surface to the declared keyword
+ * families ({@link KeywordFamilies}). The package owns assembly and
  * publication shape, not a JSON Schema engine.
  *
  * Annotated declared-family keys survive into the built document because
@@ -350,7 +352,12 @@ declare const StoreDocument_base: Schema.Class<StoreDocument, Schema.Struct<{
  * (2020-12 `prefixItems[i]` → Draft-07 `items[i]`, trailing `items` →
  * `additionalItems`). This package therefore does no re-grafting of its
  * own; it only declines to rewrite `$ref`-shaped strings *inside* those
- * opaque payloads.
+ * opaque payloads. The one structural normalization it does own is the
+ * uniform-tuple collapse: when every tuple element is content-equal to the
+ * open rest schema — always true for `NonEmptyArray` — the tuple is
+ * rewritten to a single-schema `items` with core's `minItems` untouched,
+ * the shape ajv's strictTuples rule accepts; a heterogeneous head keeps the
+ * tuple form.
  *
  * @public
  */
@@ -1883,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. */
@@ -1891,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
@@ -1945,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>;
 }
@@ -1979,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.0",
+	"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": [
@@ -38,7 +38,7 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/semver": "^0.10.0"
+		"@effected/semver": "^0.10.1"
 	},
 	"peerDependencies": {
 		"effect": "4.0.0-rc.118"