@effected/schemastore 0.16.1 → 0.18.0

package/CatalogEntry.js

@@ -133,7 +133,7 @@ var CatalogEntry = class CatalogEntry extends Schema.Class("CatalogEntry")({
 		return CatalogEntry.lintFileMatch(this.fileMatch);
 	}
 	/**
-	* {@link CatalogEntry.lint} over a bare pattern list, for callers
+	* {@link CatalogEntry.lintFileMatch} over a bare pattern list, for callers
 	* checking patterns before an entry exists.
 	*/
 	static lintFileMatch(patterns) {

package/DriftPolicy.js

@@ -18,6 +18,18 @@ var DriftPolicy = class {
 		policy: "semantic",
 		onDrift: "error"
 	};
+	/**
+	* Answer `"write"` or `"drift"` for one target, given whether it is
+	* published and how its content changed.
+	*
+	* @example
+	* ```ts
+	* import { DriftPolicy } from "@effected/schemastore";
+	*
+	* DriftPolicy.classify({ published: true, change: "contract" }, "semantic");
+	* // => "drift"
+	* ```
+	*/
 	static classify(input, policy) {
 		if (!input.published || policy === "allow") return "write";
 		if (input.change === "contract") return "drift";

package/README.md

@@ -7,10 +7,10 @@
 
 Publish Effect Schemas as SchemaStore-shaped Draft-07 JSON Schema documents. Core `effect` already generates JSON Schema (`Schema.toJsonSchemaDocument`) and lowers it to Draft-07 (`JsonSchema.toDocumentDraft07`); this package owns what [SchemaStore](https://www.schemastore.org) and the editors expect around that output — the publication shape, the hosted identity a document is published under, the keyword-family gate, catalog entries, lints, versioning, canonical JSON and content-comparing file IO — and the [`schemastore`](https://www.npmjs.com/package/@effected/schemastore-cli) command runs all of it from one config file.
 
-> **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
@@ -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/SchemaPipeline.js

@@ -116,7 +116,7 @@ const gate = (target, findings, options) => {
 };
 /**
 * The emit pipeline over a target manifest: generate, lint, validate, gate,
-* write — the loop every consumer of this package was writing by hand.
+* and write each schema document.
 *
 * Requires `SchemaFile` and `SchemaValidator` in `R`; provide
 * `SchemaFile.layer` and an engine — `AjvValidator.layer` from

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,41 @@ 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}.
 *
+* @example
+* ```ts
+* import { defineConfig } from "@effected/schemastore";
+* import { Schema } from "effect";
+*
+* const Config = Schema.Struct({ name: Schema.String });
+*
+* export default defineConfig({
+* 	name: "my-tool",
+* 	outputDir: "schemas",
+* 	baseUrl: "https://example.com/schemas",
+* 	schemas: { config: { schema: Config } },
+* });
+* ```
+*
 * @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 +238,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

@@ -7,8 +7,7 @@ import { Effect, JsonPointer, JsonSchema, Result, Schema } from "effect";
 * The Draft-07 meta-schema URL SchemaStore documents declare as `$schema`.
 *
 * Deliberately carries the trailing `#` fragment: the SchemaStore corpus
-* (and the extraction source's committed files) use the fragment form,
-* where core's `JsonSchema.META_SCHEMA_URI_DRAFT_07` omits it.
+* uses the fragment form, where core's `JsonSchema.META_SCHEMA_URI_DRAFT_07` omits it.
 *
 * @public
 */
@@ -185,7 +184,7 @@ const collapseUniformTuples = (node, depth) => {
 * `#/$defs` `$ref` rewrite the lowering makes necessary — so every `$ref`
 * 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
+* arrays publishable through the strict ajv gate, 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.
@@ -299,8 +298,7 @@ var StoreDocument = class StoreDocument extends Schema.Class("StoreDocument")({
 	/**
 	* The flat SchemaStore publication shape: `$schema`, `$id`, the root
 	* schema's keywords spread at the top level, then the `$defs` pool.
-	* `$defs` is omitted when the pool is empty (a deliberate divergence
-	* from the extraction source, which always emitted the key).
+	* `$defs` is omitted when the pool is empty.
 	*/
 	toJson() {
 		return {

package/index.d.ts

@@ -52,8 +52,8 @@ type CanonicalJsonError = NonJsonValueError | JsonDepthExceededError;
  */
 interface CanonicalJsonOptions {
   /**
-   * Indentation unit: `"tab"` (the default, matching the repo formatter
-   * convention the extraction source committed its files under) or a
+   * Indentation unit: `"tab"` (the default, matching the formatter
+   * convention of most JSON schema repos) or a
    * space count — a non-negative integer (`0` emits multi-line output
    * with no leading indentation). Counts above 10 are honored as given,
    * deliberately diverging from `JSON.stringify`'s silent clamp to 10.
@@ -195,8 +195,7 @@ export declare class DocumentDiff {
  * The Draft-07 meta-schema URL SchemaStore documents declare as `$schema`.
  *
  * Deliberately carries the trailing `#` fragment: the SchemaStore corpus
- * (and the extraction source's committed files) use the fragment form,
- * where core's `JsonSchema.META_SCHEMA_URI_DRAFT_07` omits it.
+ * uses the fragment form, where core's `JsonSchema.META_SCHEMA_URI_DRAFT_07` omits it.
  *
  * @public
  */
@@ -341,7 +340,7 @@ declare const StoreDocument_base: Schema.Class<StoreDocument, Schema.Struct<{
  * `#/$defs` `$ref` rewrite the lowering makes necessary — so every `$ref`
  * 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
+ * arrays publishable through the strict ajv gate, 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.
@@ -404,8 +403,7 @@ export declare class StoreDocument extends StoreDocument_base {
   /**
    * The flat SchemaStore publication shape: `$schema`, `$id`, the root
    * schema's keywords spread at the top level, then the `$defs` pool.
-   * `$defs` is omitted when the pool is empty (a deliberate divergence
-   * from the extraction source, which always emitted the key).
+   * `$defs` is omitted when the pool is empty.
    */
   toJson(): Record<string, unknown>;
   /**
@@ -913,7 +911,7 @@ export declare class CatalogEntry extends CatalogEntry_base {
    */
   lint(): ReadonlyArray<CatalogLintFinding>;
   /**
-   * {@link CatalogEntry.lint} over a bare pattern list, for callers
+   * {@link CatalogEntry.lintFileMatch} over a bare pattern list, for callers
    * checking patterns before an entry exists.
    */
   static lintFileMatch(patterns: ReadonlyArray<string>): ReadonlyArray<CatalogLintFinding>;
@@ -1001,7 +999,9 @@ type OnDrift = "error" | "warn";
  * @public
  */
 interface DriftOptions {
+  /** How much change a published document may absorb. */
   readonly policy: DriftTolerance;
+  /** What a build does when it finds drift. */
   readonly onDrift: OnDrift;
 }
 /**
@@ -1026,6 +1026,18 @@ export declare class DriftPolicy {
   private constructor();
   /** `{ policy: "semantic", onDrift: "error" }` — what a config gets when it says nothing. */
   static readonly defaults: DriftOptions;
+  /**
+   * Answer `"write"` or `"drift"` for one target, given whether it is
+   * published and how its content changed.
+   *
+   * @example
+   * ```ts
+   * import { DriftPolicy } from "@effected/schemastore";
+   *
+   * DriftPolicy.classify({ published: true, change: "contract" }, "semantic");
+   * // => "drift"
+   * ```
+   */
   static classify(input: {
     readonly published: boolean;
     readonly change: WriteChange;
@@ -1246,8 +1258,7 @@ export declare class KeywordFamilies {
 /**
  * A single schema publication target: an Effect Schema source paired with
  * the identity and destination it is serialized under. A repo generating
- * SchemaStore artifacts declares one target per emitted document (the
- * extraction source's `{schema, $id, path}` triples, generalized).
+ * SchemaStore artifacts declares one target per emitted document.
  *
  * Not a `Schema.Class`: a target carries a live Effect Schema value, which
  * is program wiring rather than serializable data.
@@ -1263,9 +1274,7 @@ export interface SchemaTarget {
    * The catalog/file base name (`name.json` / `name-<version>.json`).
    *
    * Only the catalog path consumes it — a target that merely emits a file
-   * to `path` needs no name, and inventing one to
-   * satisfy the constructor duplicates the basename with no invariant
-   * tying the two together. Required whenever `version` is present, since
+   * to `path` needs no name. Required whenever `version` is present, since
    * versioned catalog naming is defined in terms of it.
    */
   readonly name?: string;
@@ -1538,8 +1547,7 @@ export declare class SchemaGateError extends SchemaGateError_base {
  *   any write. A target with no `version`, or with a prerelease label, is a
  *   document that replaces its predecessor in place and is rewritten as
  *   before.
- * - `"allow"` — classify and report only, never refuse: the pre-guard
- *   behaviour. Also the sanctioned REPAIR path for a published file whose
+ * - `"allow"` — classify and report only, never refuse. Also the sanctioned REPAIR path for a published file whose
  *   text no longer parses — `SchemaFile` classifies unparseable text as
  *   `"contract"` so it stays regenerable, and under the default that
  *   classification is refused.
@@ -1686,7 +1694,7 @@ interface SchemaPipelineOptions {
 }
 /**
  * The emit pipeline over a target manifest: generate, lint, validate, gate,
- * write — the loop every consumer of this package was writing by hand.
+ * and write each schema document.
  *
  * Requires `SchemaFile` and `SchemaValidator` in `R`; provide
  * `SchemaFile.layer` and an engine — `AjvValidator.layer` from
@@ -1890,6 +1898,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 +1915,21 @@ 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 +1982,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,14 +2018,34 @@ 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}.
  *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@effected/schemastore";
+ * import { Schema } from "effect";
+ *
+ * const Config = Schema.Struct({ name: Schema.String });
+ *
+ * export default defineConfig({
+ * 	name: "my-tool",
+ * 	outputDir: "schemas",
+ * 	baseUrl: "https://example.com/schemas",
+ * 	schemas: { config: { schema: Config } },
+ * });
+ * ```
+ *
  * @public
  */
 export declare const defineConfig: (input: SchemastoreConfigInput) => SchemastoreConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore",
-	"version": "0.16.1",
+	"version": "0.18.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,10 +38,10 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/semver": "^0.10.1"
+		"@effected/semver": "^0.11.0"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-rc.118"
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"