@effected/schemastore 0.17.0 → 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

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

@@ -209,6 +209,21 @@ const assertUniquePaths = (paths) => {
 * 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) => {

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
@@ -1916,9 +1924,10 @@ interface SchemastoreConfigInput {
    * 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.
+   * `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;
   /**
@@ -2022,6 +2031,21 @@ interface SchemastoreConfig {
  * 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.17.0",
+	"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"