@effected/schemastore 0.18.0 → 0.20.0

package/InstanceValidator.js

@@ -0,0 +1,106 @@
+import { Context, Effect, Layer, Schema } from "effect";
+
+//#region src/InstanceValidator.ts
+/**
+* Indicates that the validation engine behind the {@link InstanceValidator}
+* contract failed as a *mechanism* — it could not run at all.
+*
+* By convention the error channel is reserved for exactly that: an instance
+* that fails the document is an {@link InstanceFinding} list (a value),
+* never an error. A document the engine cannot compile also lands here —
+* unlike {@link SchemaValidatorError}, whose subject IS the document, this
+* contract's subject is the instance, so a document that yields no verdict
+* means the engine could not run against that instance. Raised by
+* implementations of {@link InstanceValidatorShape.validate}.
+*
+* @public
+*/
+var InstanceValidatorError = class extends Schema.TaggedError()("InstanceValidatorError", { 
+/** The underlying engine failure, preserved structurally. */
+cause: Schema.Defect() }) {
+	get message() {
+		return "Instance validation engine failed";
+	}
+};
+/**
+* One problem a validation engine found with an instance: a value in a
+* report, never an error channel — the consumer decides what a finding
+* gates. Structurally the same report {@link ValidationFinding} is for a
+* schema document, but its pointer addresses the INSTANCE, so the two stay
+* separate types: a caller that mixes them up is a compile error, not a
+* silently misread pointer.
+*
+* @public
+*/
+var InstanceFinding = class extends Schema.Class("InstanceFinding")({
+	/** JSON pointer into the instance (`""` is the instance root). */
+	path: Schema.String,
+	/** Human-readable explanation from the engine. */
+	message: Schema.String,
+	/** The JSON Schema keyword the finding is about, when the engine names one. */
+	keyword: Schema.optionalKey(Schema.String)
+}) {};
+/** The default for an unstubbed {@link InstanceValidator.makeTest} member. */
+const notStubbed = (method) => () => Effect.die(/* @__PURE__ */ new Error(`InstanceValidator.makeTest: ${method}() was called but not stubbed — no honest default exists for a test double; pass a \`${method}\` override.`));
+/**
+* The payload-against-document validation contract — the question
+* {@link SchemaValidator} does not answer: not "is this document valid JSON
+* Schema", but "does this instance conform to the published document it
+* names in `$schema`". Decoding with the source Effect Schema is not a
+* substitute: that proves the instance matches the CODE, not the committed
+* document consumers actually fetch, and the two can drift.
+*
+* Like {@link SchemaValidator}, this package ships the contract and its
+* doubles only: skip validation with {@link InstanceValidator.noop}, stub it
+* with {@link InstanceValidator.layerTest}. The one real implementation is
+* `@effected/schemastore-cli`'s `AjvInstanceValidator.layer` — the same ajv
+* strict-mode setup `AjvValidator` gates documents with, pointed at an
+* instance — which the `schemastore validate` command composes for you and
+* which that package also exports for a program that drives the contract
+* itself. Keeping the engine there keeps `ajv` out of every application
+* that imports this package at runtime.
+*
+* @example
+* ```ts
+* import { InstanceValidator } from "@effected/schemastore";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const validator = yield* InstanceValidator;
+*   return yield* validator.validate({ type: "object" }, { any: "payload" });
+* });
+*
+* // Provide the engine at the edge — the CLI does this for you:
+* //   Effect.provide(program, AjvInstanceValidator.layer)   (from @effected/schemastore-cli)
+* Effect.runPromise(Effect.provide(program, InstanceValidator.noop));
+* // => []
+* ```
+*
+* @public
+*/
+var InstanceValidator = class InstanceValidator extends Context.Service()("@effected/schemastore/InstanceValidator") {
+	/**
+	* No-op: `validate` always succeeds with no findings, never consulting an
+	* engine. A pure `Layer.succeed`, bound to a const so the layer memoizes
+	* by reference. Use it to switch validation off deliberately — for the
+	* real engine, provide `AjvInstanceValidator.layer` from
+	* `@effected/schemastore-cli`.
+	*/
+	static noop = Layer.succeed(InstanceValidator, { validate: () => Effect.succeed([]) });
+	/**
+	* An in-memory double: stub only the members the test exercises; every
+	* other member **dies** with a defect naming itself. No member has an
+	* honest default — a fabricated clean pass would leak into consumer
+	* logic as fact (use {@link InstanceValidator.noop} when a test genuinely
+	* wants an always-clean validator).
+	*/
+	static makeTest = (overrides = {}) => ({
+		validate: notStubbed("validate"),
+		...overrides
+	});
+	/** {@link InstanceValidator.makeTest} behind `Layer.succeed`. */
+	static layerTest = (overrides = {}) => Layer.succeed(InstanceValidator, InstanceValidator.makeTest(overrides));
+};
+
+//#endregion
+export { InstanceFinding, InstanceValidator, InstanceValidatorError };

package/README.md

@@ -131,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), 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.
+- `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, an optional `catalog.name` display name (defaulting to the key, unique within the config) that renames the catalog entry and nothing else, 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

@@ -32,6 +32,7 @@ const LayoutInput = Schema.Literals(members({
 const EffectSchemaInput = Schema.declare((u) => Schema.isSchema(u), { expected: "an Effect Schema" });
 const OptionsInput = Schema.declare((u) => Predicate.isObject(u), { expected: "an object" });
 const CatalogBlockInput = Schema.Struct({
+	name: Schema.optionalKey(Schema.NonEmptyString),
 	description: Schema.String,
 	fileMatch: Schema.NonEmptyArray(Schema.String)
 });
@@ -63,6 +64,10 @@ const DECODE_OPTIONS = {
 	errors: "all"
 };
 const withoutUndefined = (input) => Predicate.isObject(input) && !Array.isArray(input) ? Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0)) : input;
+const withoutUndefinedCatalog = (entry) => Predicate.isObject(entry) && !Array.isArray(entry) && "catalog" in entry ? {
+	...entry,
+	catalog: withoutUndefined(entry.catalog)
+} : entry;
 const decodeOrThrow = (schema, input, prefix) => Result.getOrThrowWith(Schema.decodeUnknownResult(schema)(input, DECODE_OPTIONS), (error) => /* @__PURE__ */ new Error(`defineConfig: ${prefix}${error.message.replace(/\n\s*/g, " ")}`));
 const resolveIdentity = (name, entry, defaultBaseUrl) => {
 	if (entry.hosted !== void 0) {
@@ -91,7 +96,7 @@ const resolveIdentity = (name, entry, defaultBaseUrl) => {
 };
 const resolveEntry = (name, input, defaults, outputDir) => {
 	if (!SchemaVersioning.isSimpleName(name)) return fail(`schema "${name}" must be keyed by a simple file base name (no separators, no whitespace)`);
-	const entry = decodeOrThrow(EntryInput, withoutUndefined(input), `schema "${name}" `);
+	const entry = decodeOrThrow(EntryInput, withoutUndefinedCatalog(withoutUndefined(input)), `schema "${name}" `);
 	const hosted = resolveIdentity(name, entry, defaults.baseUrl);
 	if (hosted.baseUrl === "schemastore" && entry.catalog === void 0) return fail(`schema "${name}" must declare a catalog block under baseUrl "schemastore"`);
 	const versions = hosted.resolvedVersions;
@@ -124,7 +129,8 @@ const resolveEntry = (name, input, defaults, outputDir) => {
 		url: hosted.urlFor(version)
 	}));
 	const catalog = entry.catalog === void 0 ? void 0 : CatalogEntry.assemble({
-		name,
+		name: entry.catalog.name ?? name,
+		fileBaseName: name,
 		description: entry.catalog.description,
 		fileMatch: entry.catalog.fileMatch,
 		baseUrl: hosted.catalogBase,
@@ -163,6 +169,15 @@ const assertCatalogDirHoldsOnlySlices = (catalogDir, outputDir, documents) => {
 	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 assertUniqueCatalogNames = (schemas) => {
+	const owners = /* @__PURE__ */ new Map();
+	for (const schema of schemas) {
+		if (schema.catalog === void 0) continue;
+		const owner = owners.get(schema.catalog.name);
+		if (owner !== void 0) fail(`schemas "${owner}" and "${schema.name}" both name their catalog entry "${schema.catalog.name}"`);
+		owners.set(schema.catalog.name, schema.name);
+	}
+};
 const assertUniquePaths = (paths) => {
 	const seen = /* @__PURE__ */ new Set();
 	for (const p of paths) {
@@ -199,7 +214,9 @@ const assertUniquePaths = (paths) => {
 * 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
+* `baseUrl: "schemastore"`; two cataloged schemas whose catalog
+* entries resolve to one `name` (a `catalog.name`, else the key) are
+* rejected, naming both keys; 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
@@ -238,6 +255,7 @@ const defineConfig = (input) => {
 		drift: config.drift ?? DriftPolicy.defaults.policy
 	};
 	const schemas = Object.entries(config.schemas).map(([name, entry]) => resolveEntry(name, entry, defaults, outputDir));
+	assertUniqueCatalogNames(schemas);
 	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);

package/index.d.ts

@@ -1173,6 +1173,135 @@ export declare class HostedSchema extends HostedSchema_base {
   private parseLabel;
 }
 //#endregion
+//#region src/InstanceValidator.d.ts
+declare const InstanceValidatorError_base: Schema.Class<InstanceValidatorError, Schema.TaggedStruct<"InstanceValidatorError", {
+  /** The underlying engine failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that the validation engine behind the {@link InstanceValidator}
+ * contract failed as a *mechanism* — it could not run at all.
+ *
+ * By convention the error channel is reserved for exactly that: an instance
+ * that fails the document is an {@link InstanceFinding} list (a value),
+ * never an error. A document the engine cannot compile also lands here —
+ * unlike {@link SchemaValidatorError}, whose subject IS the document, this
+ * contract's subject is the instance, so a document that yields no verdict
+ * means the engine could not run against that instance. Raised by
+ * implementations of {@link InstanceValidatorShape.validate}.
+ *
+ * @public
+ */
+export declare class InstanceValidatorError extends InstanceValidatorError_base {
+  get message(): string;
+}
+declare const InstanceFinding_base: Schema.Class<InstanceFinding, Schema.Struct<{
+  /** JSON pointer into the instance (`""` is the instance root). */
+  readonly path: Schema.String;
+  /** Human-readable explanation from the engine. */
+  readonly message: Schema.String;
+  /** The JSON Schema keyword the finding is about, when the engine names one. */
+  readonly keyword: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One problem a validation engine found with an instance: a value in a
+ * report, never an error channel — the consumer decides what a finding
+ * gates. Structurally the same report {@link ValidationFinding} is for a
+ * schema document, but its pointer addresses the INSTANCE, so the two stay
+ * separate types: a caller that mixes them up is a compile error, not a
+ * silently misread pointer.
+ *
+ * @public
+ */
+export declare class InstanceFinding extends InstanceFinding_base {}
+/**
+ * Options for {@link InstanceValidatorShape.validate}.
+ *
+ * @public
+ */
+interface InstanceValidatorOptions {
+  /**
+   * Whether the engine runs its strictest mode (ajv `strict: true` — the
+   * SchemaStore default gate) when compiling the document. Defaults to
+   * `true`; implementations treat an omitted value as strict.
+   */
+  readonly strict?: boolean;
+}
+/**
+ * The shape of the {@link InstanceValidator} service — what an implementation
+ * provides.
+ *
+ * @public
+ */
+interface InstanceValidatorShape {
+  /**
+   * Validates an arbitrary JSON instance against a schema document with a
+   * real JSON Schema engine. An empty array is a clean pass; an instance
+   * the document rejects answers findings as values, each carrying a JSON
+   * pointer into the instance. The error channel is reserved for the
+   * engine failing as a mechanism ({@link InstanceValidatorError}),
+   * including a document the engine cannot compile.
+   */
+  readonly validate: (document: Record<string, unknown>, instance: unknown, options?: InstanceValidatorOptions) => Effect.Effect<ReadonlyArray<InstanceFinding>, InstanceValidatorError>;
+}
+declare const InstanceValidator_base: Context.ServiceClass<InstanceValidator, "@effected/schemastore/InstanceValidator", InstanceValidatorShape>;
+/**
+ * The payload-against-document validation contract — the question
+ * {@link SchemaValidator} does not answer: not "is this document valid JSON
+ * Schema", but "does this instance conform to the published document it
+ * names in `$schema`". Decoding with the source Effect Schema is not a
+ * substitute: that proves the instance matches the CODE, not the committed
+ * document consumers actually fetch, and the two can drift.
+ *
+ * Like {@link SchemaValidator}, this package ships the contract and its
+ * doubles only: skip validation with {@link InstanceValidator.noop}, stub it
+ * with {@link InstanceValidator.layerTest}. The one real implementation is
+ * `@effected/schemastore-cli`'s `AjvInstanceValidator.layer` — the same ajv
+ * strict-mode setup `AjvValidator` gates documents with, pointed at an
+ * instance — which the `schemastore validate` command composes for you and
+ * which that package also exports for a program that drives the contract
+ * itself. Keeping the engine there keeps `ajv` out of every application
+ * that imports this package at runtime.
+ *
+ * @example
+ * ```ts
+ * import { InstanceValidator } from "@effected/schemastore";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const validator = yield* InstanceValidator;
+ *   return yield* validator.validate({ type: "object" }, { any: "payload" });
+ * });
+ *
+ * // Provide the engine at the edge — the CLI does this for you:
+ * //   Effect.provide(program, AjvInstanceValidator.layer)   (from @effected/schemastore-cli)
+ * Effect.runPromise(Effect.provide(program, InstanceValidator.noop));
+ * // => []
+ * ```
+ *
+ * @public
+ */
+export declare class InstanceValidator extends InstanceValidator_base {
+  /**
+   * No-op: `validate` always succeeds with no findings, never consulting an
+   * engine. A pure `Layer.succeed`, bound to a const so the layer memoizes
+   * by reference. Use it to switch validation off deliberately — for the
+   * real engine, provide `AjvInstanceValidator.layer` from
+   * `@effected/schemastore-cli`.
+   */
+  static readonly noop: Layer.Layer<InstanceValidator>;
+  /**
+   * An in-memory double: stub only the members the test exercises; every
+   * other member **dies** with a defect naming itself. No member has an
+   * honest default — a fabricated clean pass would leak into consumer
+   * logic as fact (use {@link InstanceValidator.noop} when a test genuinely
+   * wants an always-clean validator).
+   */
+  static readonly makeTest: (overrides?: Partial<InstanceValidatorShape>) => InstanceValidatorShape;
+  /** {@link InstanceValidator.makeTest} behind `Layer.succeed`. */
+  static readonly layerTest: (overrides?: Partial<InstanceValidatorShape>) => Layer.Layer<InstanceValidator>;
+}
+//#endregion
 //#region src/KeywordFamilies.d.ts
 /**
  * The one owner of the declared non-standard keyword families, in two
@@ -1810,6 +1939,16 @@ declare const ConfigBrand: unique symbol;
  * @public
  */
 interface CatalogInput {
+  /**
+   * The entry's display name in the catalog — what an editor or SchemaStore
+   * shows. Defaults to the schema's key. Only the catalog entry's `name`
+   * changes: the key still names the file, `$id` and every catalog URL, so
+   * a versioned `<version>/<name>.json` layout keeps its short file names.
+   * Must be non-empty, and unique among the config's cataloged schemas
+   * (compared after defaulting, so it must not equal another cataloged
+   * schema's key either).
+   */
+  readonly name?: string;
   /** The catalog description. */
   readonly description: string;
   /** Glob patterns editors match files against; must be non-empty. */
@@ -2021,7 +2160,9 @@ interface SchemastoreConfig {
  * 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
+ * `baseUrl: "schemastore"`; two cataloged schemas whose catalog
+ * entries resolve to one `name` (a `catalog.name`, else the key) are
+ * rejected, naming both keys; 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
@@ -2057,5 +2198,5 @@ export declare const defineConfig: (input: SchemastoreConfigInput) => Schemastor
  */
 export declare const isSchemastoreConfig: (value: unknown) => value is SchemastoreConfig;
 //#endregion
-export type { CanonicalJsonError, CanonicalJsonOptions, CatalogInput, CatalogUrls, CheckResult, ContractChangePolicy, CustomHostedSchemaInput, DriftOptions, DriftTolerance, DriftVerdict, FrozenVersion, GitHubHostedSchemaInput, HostedSchemaVersionsInput, OnDrift, PipelineCheckResult, PipelineResult, ResolvedSchema, SchemaChange, SchemaEntryInput, SchemaFileShape, SchemaLayout, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, SchemastoreConfig, SchemastoreConfigInput, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
+export type { CanonicalJsonError, CanonicalJsonOptions, CatalogInput, CatalogUrls, CheckResult, ContractChangePolicy, CustomHostedSchemaInput, DriftOptions, DriftTolerance, DriftVerdict, FrozenVersion, GitHubHostedSchemaInput, HostedSchemaVersionsInput, InstanceValidatorOptions, InstanceValidatorShape, OnDrift, PipelineCheckResult, PipelineResult, ResolvedSchema, SchemaChange, SchemaEntryInput, SchemaFileShape, SchemaLayout, SchemaPipelineOptions, SchemaValidatorOptions, SchemaValidatorShape, SchemaWriteOptions, SchemastoreConfig, SchemastoreConfigInput, StoreDocumentOptions, WriteChange, WriteOutcome, WriteResult };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -6,6 +6,7 @@ import { DocumentDiff } from "./DocumentDiff.js";
 import { DocumentLint, DocumentLintFinding } from "./DocumentLint.js";
 import { DriftPolicy } from "./DriftPolicy.js";
 import { HostedSchema, SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE } from "./HostedSchema.js";
+import { InstanceFinding, InstanceValidator, InstanceValidatorError } from "./InstanceValidator.js";
 import { SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError } from "./SchemaFile.js";
 import { SchemaValidator, SchemaValidatorError, ValidationFinding } from "./SchemaValidator.js";
 import { DRAFT_07_META_SCHEMA, SchemaConversionError, StoreDocument, UndeclaredAnnotationKeyError } from "./StoreDocument.js";
@@ -13,4 +14,4 @@ import { ContractChangeTarget, PipelineFinding, SchemaContractChangeError, Schem
 import { SchemaTarget } from "./SchemaTarget.js";
 import { defineConfig, isSchemastoreConfig } from "./SchemastoreConfig.js";
 
-export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, DriftPolicy, HostedSchema, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding, defineConfig, isSchemastoreConfig };
+export { CanonicalJson, CatalogEntry, CatalogLintFinding, ContractChangeTarget, DRAFT_07_META_SCHEMA, DocumentDiff, DocumentLint, DocumentLintFinding, DriftPolicy, HostedSchema, InstanceFinding, InstanceValidator, InstanceValidatorError, InvalidSchemaVersionError, JsonDepthExceededError, KeywordFamilies, NonJsonValueError, PipelineFinding, SCHEMASTORE_CATALOG_BASE, SCHEMASTORE_ID_BASE, SchemaContractChangeError, SchemaConversionError, SchemaFile, SchemaFileNotFoundError, SchemaFileReadError, SchemaFileWriteError, SchemaGateError, SchemaPipeline, SchemaTarget, SchemaValidator, SchemaValidatorError, SchemaVersion, SchemaVersioning, StoreDocument, UndeclaredAnnotationKeyError, ValidationFinding, defineConfig, isSchemastoreConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/schemastore",
-	"version": "0.18.0",
+	"version": "0.20.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": [