Update TypeDocs with some documentation. Also change export names.

Author: jdesrosiers

README.md

@@ -62,14 +62,14 @@ By default, it will track coverage for any file with a `*.schema.json`,
 `vitest-schema.config.js`
 ```TypeScript
 import { defineConfig } from "vitest/config";
-import type { JsonSchemaCoverageProviderOptions } from "@hyperjump/json-schema-coverage/vitest-coverage-provider";
+import type { JsonSchemaCoverageProviderOptions } from "@hyperjump/json-schema-coverage/vitest/coverage-provider";
 
 export default defineConfig({
   test: {
     include: ["schema-tests/"],
     coverage: {
       provider: "custom",
-      customProviderModule: "@hyperjump/json-schema-coverage/vitest-coverage-provider",
+      customProviderModule: "@hyperjump/json-schema-coverage/vitest/coverage-provider",
       include: ["schemas/**/*.json"] // Optional
     } as JsonSchemaCoverageProviderOptions
   }
@@ -107,7 +107,7 @@ for the validation to work.
 
 ```JavaScript
 import { describe, expect, test } from "vitest";
-import { registerSchema, unregisterSchema } from "@hyperjump/json-schema-coverage/vitest-matchers";
+import { registerSchema, unregisterSchema } from "@hyperjump/json-schema-coverage/vitest";
 
 describe("Worksheet", () => {
   beforeEach(async () => {
@@ -155,7 +155,7 @@ describe("Worksheet", () => {
 These are the functions available when working with the vitest integration.
 
 ```JavaScript
-import { ... } from "@hyperjump/json-schema-coverage/vitest-matchers"
+import { ... } from "@hyperjump/json-schema-coverage/vitest"
 ```
 
 - **matchJsonSchema**: (uriOrSchema: string | SchemaObject | boolean) => Promise\<void>

package.json

@@ -17,15 +17,15 @@
   "type": "module",
   "exports": {
     ".": "./src/index.js",
-    "./vitest-matchers": "./src/vitest/matchers.js",
-    "./vitest-coverage-provider": "./src/vitest/coverage-provider.js"
+    "./vitest": "./src/vitest/index.js",
+    "./vitest/coverage-provider": "./src/vitest/coverage-provider.js"
   },
   "scripts": {
     "lint": "eslint src",
     "test": "vitest run --config src/vitest/vitest-json-schema.config.js",
     "test:coverage": "vitest run --coverage",
     "type-check": "tsc --noEmit",
-    "docs": "typedoc --excludeExternals"
+    "docs": "typedoc"
   },
   "devDependencies": {
     "@stylistic/eslint-plugin": "*",

src/coverage-map-service.d.ts

@@ -1,8 +1,34 @@
 import { CoverageMapData } from "istanbul-lib-coverage";
 
+/**
+ * The `CoverageMapService` creates [istanbul](https://istanbul.js.org/)
+ * coverage maps for your schemas and stores them for use by the
+ * `TestCoverageEvaluationPlugin`. A coverage map stores the file positions of
+ * all the keywords, schemas, and branches in a schema.
+ */
 export class CoverageMapService {
+  /**
+   * This method takes a file path to a schema, generates a coverage map for it,
+   * and stores it for later use. It returns the identifier for the schema
+   * (usually the value of `$id`).
+   */
   addFromFile(schemaPath: string): Promise<string>;
+
+  /**
+   * If you have a coverage map you created yourself or got from some other
+   * source, you can add it using this method. You probably don't need this. Use
+   * `addFromFile` to create and store the coverage map for you.
+   */
   addCoverageMap(coverageMap: CoverageMapData): void;
+
+  /**
+   * Get the file path for the schema that is identified by the given URI.
+   */
   getSchemaPath(schemaUri: string): string;
+
+  /**
+   * Retrieve a coverage map that was previously added through `addFromFile` or
+   * `addCoverageMap`.
+   */
   getCoverageMap(schemaUri: string): CoverageMapData;
 }

src/index.js

@@ -1,2 +1,4 @@
+/** @module low-level-api */
+
 export * from "./test-coverage-evaluation-plugin.js";
 export * from "./coverage-map-service.js";

src/test-coverage-evaluation-plugin.d.ts

@@ -8,6 +8,14 @@ import type { JsonNode } from "@hyperjump/json-schema/instance/experimental";
 import type { CoverageMapData } from "istanbul-lib-coverage";
 import type { CoverageMapService } from "./coverage-map-service.d.ts";
 
+/**
+ * The `TestCoverageEvaluationPlugin` hooks into the evaluation process of the
+ * [@hyperjump/json-schema](https://github.com/hyperjump-io/json-schema)
+ * validator and uses the `CoverageMapService` to record when a keyword or
+ * schema is visited. Once the evaluation process is completed, it contains an
+ * [istanbul](https://istanbul.js.org/) coverage file. These files can then be
+ * used to generate any report that supports [istanbul](https://istanbul.js.org/).
+ */
 export class TestCoverageEvaluationPlugin implements EvaluationPlugin {
   constructor(coverageService?: CoverageMapService);
   coverage: CoverageMapData;

src/vitest/__snapshots__/index.test.js.snap

@@ -0,0 +1,14 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Worksheet > match failure returns BASIC output 1`] = `
+"{
+  "valid": false,
+  "errors": [
+    {
+      "keyword": "https://json-schema.org/keyword/type",
+      "absoluteKeywordLocation": "https://example.com/main#/type",
+      "instanceLocation": "#"
+    }
+  ]
+}"
+`;

src/vitest/index.d.ts

@@ -0,0 +1,42 @@
+import type { SchemaObject } from "@hyperjump/json-schema";
+import type { AsyncExpectationResult } from "@vitest/expect";
+import "vitest";
+
+declare module "vitest" {
+  interface Matchers<R = unknown> {
+    matchJsonSchema: (uriOrSchema: string | SchemaObject | boolean) => Promise<R>;
+    toMatchJsonSchema: (uriOrSchema: string | SchemaObject | boolean) => Promise<R>;
+  }
+}
+
+/**
+ * Register a schema in your code base by it's path.
+ *
+ * _**NOTE**: This is **not** the same as the function from
+ * [@hyperjump/json-schema](https://github.com/hyperjump-io/json-schema) that takes a schema._
+ */
+export const registerSchema: (filePath: string) => Promise<void>;
+
+/**
+ * Remove a registered schema in your code base by it's path.
+ *
+ * _**NOTE**: This is **not** the same as the function from
+ * [@hyperjump/json-schema](https://github.com/hyperjump-io/json-schema) that takes the schema's `$id`._
+ */
+export const unregisterSchema: (filePath: string) => Promise<void>;
+
+/**
+ * A vitest matcher that can be used to validate a JSON-compatible value. It
+ * can take a relative or full URI for a schema in your codebase. Use relative
+ * URIs to reference a file and full URIs to reference the `$id` of a schema
+ * you registered using the `registerSchema` function.
+ *
+ * You can use this matcher with an inline schema as well, but you will only
+ * get coverage for schemas that are in files.
+ *
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const matchJsonSchema: (instance: any, uriOrSchema: string | SchemaObject | boolean) => AsyncExpectationResult;
+export const toMatchJsonSchema: typeof matchJsonSchema;
+
+export { loadDialect, defineVocabulary, addKeyword } from "@hyperjump/json-schema/experimental";

src/vitest/matchers.js renamed to src/vitest/index.js

@@ -1,3 +1,4 @@
+/** @module vitest */
 import { expect } from "vitest";
 import { matchJsonSchema, toMatchJsonSchema } from "./json-schema-matchers.js";
 

src/vitest/matchers.test.js renamed to src/vitest/index.test.js

@@ -1,7 +1,7 @@
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { registerSchema, unregisterSchema } from "./matchers.js";
+import { registerSchema, unregisterSchema } from "./index.js";
 
 describe("Worksheet", () => {
   test("matches with schema", async () => {

src/vitest/json-schema-matchers.js

@@ -12,7 +12,7 @@ import { toAbsoluteIri } from "@hyperjump/uri";
 
 /**
  * @import { OutputUnit, SchemaObject } from "@hyperjump/json-schema"
- * @import * as API from "./matchers.d.ts"
+ * @import * as API from "./index.d.ts"
  */
 
 const coverageFilesDirectory = ".json-schema-coverage";