@effected/schemastore 0.18.0 → 0.19.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/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
@@ -2057,5 +2186,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.19.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": [