Include README and other cleanup

Author: jdesrosiers

.gitattributes

@@ -1 +1,2 @@
+*.png binary
 * text eol=lf

README.md

@@ -1,16 +1,85 @@
 # Hyperjump - JSON Schema Test Coverage
 
-## Usage
+This package provides tools for testing JSON Schemas and providing test coverage
+for schema files in your code base. Integration is provided for Vitest, but the
+component for collecting the coverage data is also exposed if you want to
+do some other integration.
 
-```bash
-rm ./.nyc_output/*
-npm test
-npx nyc report --reporter=html --extension .schema.json
-npx http-server coverage
+Validation is done by `@hyperjump/json-schema`, so you can use any version of
+JSON Schema supported by that package.
+
+```
+-------------|---------|----------|---------|---------|-------------------
+File         | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
+-------------|---------|----------|---------|---------|-------------------
+All files    |   81.81 |    66.66 |      80 |   88.88 |                   
+ schema.json |   81.81 |    66.66 |      80 |   88.88 | 5                 
+-------------|---------|----------|---------|---------|-------------------
+```
+
+![HTML coverage example](coverage.png)
+
+**Legend**
+- **Statements** = Keywords and subschemas
+- **Branches** = true/false branches for each keyword
+- **Functions** = Subschemas
+
+## Vitest
+
+Integration with vitest is provided as `@hyperjump/json-schema-coverage/vitest`.
+You'll need a vitest config specifically for running schema coverage.
+
+`vitest-schema.config.js`
+```JavaScript
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: "custom",
+      customProviderModule: "@hyperjump/json-schema-coverage/vitest"
+    }
+  }
+});
+```
+
+When you use the provided custom matcher `matchJsonSchema`/`toMatchJsonSchema`,
+if vitest has coverage is enabled, it will collect coverage data from those
+tests.
+
+```JavaScript
+import { describe, expect, test } from "vitest";
+import "@hyperjump/json-schema-coverage/vitest";
+
+describe("Worksheet", () => {
+  test("matches with uri", async () => {
+    await expect({ foo: 42 }).toMatchJsonSchema("./schema.json");
+  });
+
+  test("doesn't match with uri", async () => {
+    await expect({ foo: null }).not.toMatchJsonSchema("./schema.json");
+  });
+});
+```
+
+You can also use the matcher with inline schemas, but you only get coverage for
+file-based schemas.
+
+```JavaScript
+import { describe, expect, test } from "vitest";
+import "@hyperjump/json-schema-coverage/vitest";
+
+describe("Worksheet", () => {
+  test("matches with schema", async () => {
+    await expect("foo").to.matchJsonSchema({ type: "string" });
+  });
+
+  test("doesn't match with schema", async () => {
+    await expect(42).to.not.matchJsonSchema({ type: "string" });
+  });
+});
 ```
-## Legend
 
-Statements = Keywords
-Branches = true/false for each keyword
-Functions = Subschemas
+## TestCoverageEvaluationPlugin
 
+TODO

coverage.png

@@ -21,7 +21,7 @@
   },
   "scripts": {
     "lint": "eslint src",
-    "test": "vitest --watch=false",
+    "test": "vitest run",
     "type-check": "tsc --noEmit",
     "docs": "typedoc --excludeExternals"
   },
@@ -42,6 +42,8 @@
     "@hyperjump/json-schema": "^1.16.0",
     "@hyperjump/uri": "^1.3.1",
     "istanbul-lib-coverage": "^3.2.2",
+    "istanbul-lib-report": "^3.0.1",
+    "istanbul-reports": "^3.1.7",
     "moo": "^0.5.2",
     "pathe": "^2.0.3",
     "vfile": "^6.0.3"

package.json

@@ -43,6 +43,7 @@ export class TestCoverageEvaluationPlugin {
     }
 
     const schemaPath = fileURLToPath(schemaUri);
+    this.coverageMap[schemaPath].s[schemaUri]++;
     this.coverageMap[schemaPath].f[schemaUri]++;
   }
 
@@ -83,11 +84,17 @@ export class TestCoverageEvaluationPlugin {
             end: { line: node.position.start.line, column: node.position.start.column - 1 }
           };
 
+      const locRange = positionToRange(node.position);
+
+      // Create statement
+      this.coverageMap[schemaPath].statementMap[schemaLocation] = locRange;
+      this.coverageMap[schemaPath].s[schemaLocation] = 0;
+
       // Create function
       this.coverageMap[schemaPath].fnMap[schemaLocation] = {
         name: schemaLocation,
         decl: declRange,
-        loc: positionToRange(node.position),
+        loc: locRange,
         line: node.position.start.line
       };
       this.coverageMap[schemaPath].f[schemaLocation] = 0;

src/test-coverage-evaluation-plugin.js

@@ -1,14 +1,20 @@
 import { existsSync, readdirSync } from "node:fs";
 import * as fs from "node:fs/promises";
 import { createCoverageMap } from "istanbul-lib-coverage";
-import { resolve } from "pathe";
-import c from "tinyrainbow";
 import libReport from "istanbul-lib-report";
 import reports from "istanbul-reports";
+import { resolve } from "pathe";
+import c from "tinyrainbow";
 import { coverageConfigDefaults } from "vitest/config";
 
 /**
- * @import { BaseCoverageOptions, CoverageProvider, CoverageProviderModule, ResolvedCoverageOptions, Vitest} from "vitest"
+ * @import {
+ *   BaseCoverageOptions,
+ *   CoverageProvider,
+ *   CoverageProviderModule,
+ *   ResolvedCoverageOptions,
+ *   Vitest
+ * } from "vitest"
  * @import { CoverageMap, CoverageMapData } from "istanbul-lib-coverage"
  */
 
@@ -48,8 +54,7 @@ class JsonSchemaCoverageProvider {
         ctx.config.root,
         config.reportsDirectory || coverageConfigDefaults.reportsDirectory
       ),
-      reporter: resolveCoverageReporters(config.reporter || coverageConfigDefaults.reporter),
-      extension: ".schema.json"
+      reporter: resolveCoverageReporters(config.reporter || coverageConfigDefaults.reporter)
     };
 
     this.coverageFilesDirectory = "./.json-schema-coverage";
@@ -111,9 +116,7 @@ class JsonSchemaCoverageProvider {
     });
 
     if (this.hasTerminalReporter(this.options.reporter)) {
-      this.ctx.logger.log(
-        c.blue(" % ") + c.dim("Coverage report from ") + c.yellow(this.name)
-      );
+      this.ctx.logger.log(c.blue(" % ") + c.dim("Coverage report from ") + c.yellow(this.name));
     }
 
     for (const reporter of this.options.reporter) {
@@ -129,13 +132,12 @@ class JsonSchemaCoverageProvider {
 
   /** @type (reporters: ResolvedCoverageOptions["reporter"])=> boolean */
   hasTerminalReporter(reporters) {
-    return reporters.some(
-      ([reporter]) =>
-        reporter === "text"
+    return reporters.some(([reporter]) => {
+      return reporter === "text"
         || reporter === "text-summary"
         || reporter === "text-lcov"
-        || reporter === "teamcity"
-    );
+        || reporter === "teamcity";
+    });
   }
 
   /** @type () => CoverageMap */

src/vitest/json-schema-coverage-provider.js

@@ -3,6 +3,7 @@ import "vitest";
 
 declare module "vitest" {
   interface Matchers<R = unknown> {
-    matchJsonSchema: (uriOrSchema: string | SchemaObject) => Promise<R>;
+    matchJsonSchema: (uriOrSchema: string | SchemaObject | boolean) => Promise<R>;
+    toMatchJsonSchema: (uriOrSchema: string | SchemaObject | boolean) => Promise<R>;
   }
 }

src/vitest/json-schema-matcher.d.ts

@@ -11,50 +11,53 @@ import { BASIC } from "@hyperjump/json-schema/experimental";
 import { TestCoverageEvaluationPlugin } from "../test-coverage-evaluation-plugin.js";
 
 /**
- * @import { OutputUnit } from "@hyperjump/json-schema"
+ * @import { OutputUnit, SchemaObject } from "@hyperjump/json-schema"
+ * @import { AsyncExpectationResult } from "@vitest/expect"
  */
 
-expect.extend({
-  async matchJsonSchema(instance, uriOrSchema) {
-    /** @type OutputUnit */
-    let output;
+/** @type (instance: any, uriOrSchema: string | SchemaObject | boolean) => AsyncExpectationResult */
+const schemaMatcher = async (instance, uriOrSchema) => {
+  /** @type OutputUnit */
+  let output;
 
-    const isCoverageEnabled = existsSync(".json-schema-coverage");
-    const plugins = isCoverageEnabled
-      ? [new TestCoverageEvaluationPlugin()]
-      : [];
+  if (typeof uriOrSchema === "string") {
+    const uri = uriOrSchema;
 
-    if (typeof uriOrSchema === "string") {
-      const uri = uriOrSchema;
+    if (existsSync(".json-schema-coverage")) {
+      const testCoveragePlugin = new TestCoverageEvaluationPlugin();
 
       // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
       output = await validate(uri, instance, {
         outputFormat: BASIC,
-        plugins: plugins
+        plugins: [testCoveragePlugin]
       });
+
+      const coverageMapPath = `.json-schema-coverage/${randomUUID()}.json`;
+      const coverageMapJson = JSON.stringify(testCoveragePlugin.coverageMap);
+      await writeFile(coverageMapPath, coverageMapJson);
     } else {
-      const schema = uriOrSchema;
-      const uri = `urn:uuid:${randomUUID()}`;
-      registerSchema(schema, uri, "https://json-schema.org/draft/2020-12/schema");
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-        output = await validate(uri, instance, {
-          outputFormat: BASIC,
-          plugins: plugins
-        });
-      } finally {
-        unregisterSchema(uri);
-      }
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      output = await validate(uri, instance, BASIC);
     }
-
-    if (isCoverageEnabled) {
-      const testCoveragePlugin = plugins[0];
-      await writeFile(`.json-schema-coverage/${randomUUID()}.json`, JSON.stringify(testCoveragePlugin.coverageMap, null, "  "));
+  } else {
+    const schema = uriOrSchema;
+    const uri = `urn:uuid:${randomUUID()}`;
+    registerSchema(schema, uri, "https://json-schema.org/draft/2020-12/schema");
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      output = await validate(uri, instance, BASIC);
+    } finally {
+      unregisterSchema(uri);
     }
-
-    return {
-      pass: output.valid,
-      message: () => JSON.stringify(output, null, "  ")
-    };
   }
+
+  return {
+    pass: output.valid,
+    message: () => JSON.stringify(output, null, "  ")
+  };
+};
+
+expect.extend({
+  matchJsonSchema: schemaMatcher,
+  toMatchJsonSchema: schemaMatcher
 });