@quillmark/quiver 0.1.0 → 0.2.0

package/dist/testing.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Plug-and-play test suite for Quiver authors.
+ *
+ * Usage (place this file next to your Quiver.yaml):
+ *
+ *   import { Quillmark } from "@quillmark/wasm";
+ *   import { runQuiverTests } from "@quillmark/quiver/testing";
+ *   const engine = await Quillmark.load();
+ *   runQuiverTests(import.meta.url, engine);
+ *
+ * Requires vitest in your devDependencies.
+ */
+import type { QuillmarkLike, QuillLike } from "./engine-types.js";
+export type { QuillmarkLike, QuillLike };
+/**
+ * Returns a lightweight mock engine and a record of every tree passed to it.
+ * Useful for writing custom test helpers; not intended as a substitute for the
+ * real engine in runQuiverTests (the mock performs no template compilation).
+ */
+export declare function makeMockEngine(): {
+    calls: Array<Map<string, Uint8Array>>;
+    engine: QuillmarkLike;
+};
+/**
+ * Registers a Vitest describe block that validates every quill version in the
+ * quiver at `sourceDirOrMetaUrl` against the provided Quillmark engine.
+ *
+ * Pass `import.meta.url` when your test file lives at the quiver root (next to
+ * Quiver.yaml). Pass an absolute directory path for any other layout.
+ *
+ * Each (quill, version) pair gets its own `it()` so failures are reported
+ * individually. The quiver and engine are initialised once in `beforeAll`.
+ *
+ * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml, all
+ * template files, and engine compilation via engine.quill(tree). A quill that
+ * contains a template error will cause its test to fail with the engine's own
+ * error message.
+ */
+export declare function runQuiverTests(sourceDirOrMetaUrl: string, engine: QuillmarkLike): void;

package/dist/testing.js

@@ -0,0 +1,108 @@
+/**
+ * Plug-and-play test suite for Quiver authors.
+ *
+ * Usage (place this file next to your Quiver.yaml):
+ *
+ *   import { Quillmark } from "@quillmark/wasm";
+ *   import { runQuiverTests } from "@quillmark/quiver/testing";
+ *   const engine = await Quillmark.load();
+ *   runQuiverTests(import.meta.url, engine);
+ *
+ * Requires vitest in your devDependencies.
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { readdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Quiver } from "./quiver.js";
+import { QuiverRegistry } from "./registry.js";
+/**
+ * Returns a lightweight mock engine and a record of every tree passed to it.
+ * Useful for writing custom test helpers; not intended as a substitute for the
+ * real engine in runQuiverTests (the mock performs no template compilation).
+ */
+export function makeMockEngine() {
+    const calls = [];
+    const engine = {
+        quill(tree) {
+            calls.push(tree);
+            return { render: () => ({ ok: true }) };
+        },
+    };
+    return { calls, engine };
+}
+function resolveSourceDir(sourceDirOrMetaUrl) {
+    if (sourceDirOrMetaUrl.startsWith("file://")) {
+        return fileURLToPath(new URL(".", sourceDirOrMetaUrl));
+    }
+    return sourceDirOrMetaUrl;
+}
+function discoverQuills(sourceDir) {
+    const quillsDir = join(sourceDir, "quills");
+    const results = [];
+    let nameDirs;
+    try {
+        nameDirs = readdirSync(quillsDir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const nameEntry of nameDirs) {
+        if (!nameEntry.isDirectory() || nameEntry.name.startsWith("."))
+            continue;
+        let versionDirs;
+        try {
+            versionDirs = readdirSync(join(quillsDir, nameEntry.name), {
+                withFileTypes: true,
+            });
+        }
+        catch {
+            continue;
+        }
+        for (const versionEntry of versionDirs) {
+            if (!versionEntry.isDirectory() || versionEntry.name.startsWith("."))
+                continue;
+            results.push({ name: nameEntry.name, version: versionEntry.name });
+        }
+    }
+    return results;
+}
+/**
+ * Registers a Vitest describe block that validates every quill version in the
+ * quiver at `sourceDirOrMetaUrl` against the provided Quillmark engine.
+ *
+ * Pass `import.meta.url` when your test file lives at the quiver root (next to
+ * Quiver.yaml). Pass an absolute directory path for any other layout.
+ *
+ * Each (quill, version) pair gets its own `it()` so failures are reported
+ * individually. The quiver and engine are initialised once in `beforeAll`.
+ *
+ * Validation covers the full loading pipeline: Quiver.yaml, Quill.yaml, all
+ * template files, and engine compilation via engine.quill(tree). A quill that
+ * contains a template error will cause its test to fail with the engine's own
+ * error message.
+ */
+export function runQuiverTests(sourceDirOrMetaUrl, engine) {
+    const sourceDir = resolveSourceDir(sourceDirOrMetaUrl);
+    // Enumerate quills synchronously so Vitest can collect test cases before
+    // any async work begins. Errors here (missing quills/ dir, unreadable dirs)
+    // surface as the "has at least one quill" test failing rather than a
+    // collection-time crash.
+    const quills = discoverQuills(sourceDir);
+    describe(`Quiver: ${basename(sourceDir)}`, () => {
+        let registry;
+        beforeAll(async () => {
+            const quiver = await Quiver.fromSourceDir(sourceDir);
+            registry = new QuiverRegistry({ engine, quivers: [quiver] });
+        });
+        it("has at least one quill", () => {
+            expect(quills).not.toHaveLength(0);
+        });
+        for (const { name, version } of quills) {
+            it(`${name}@${version} compiles without error`, async () => {
+                const quill = await registry.getQuill(`${name}@${version}`);
+                expect(typeof quill.render).toBe("function");
+            });
+        }
+    });
+}

package/dist/transports/fs-transport.d.ts

@@ -0,0 +1,14 @@
+/**
+ * FsTransport — Node-only packed quiver transport that reads from local disk.
+ * Internal; not exported from index.ts.
+ *
+ * Uses dynamic imports of node:fs/promises and node:path so the module can be
+ * imported in environments where those builtins are not available (the dynamic
+ * import only executes when fetchBytes is actually called).
+ */
+import type { PackedTransport } from "../packed-loader.js";
+export declare class FsTransport implements PackedTransport {
+    private rootDir;
+    constructor(rootDir: string);
+    fetchBytes(relativePath: string): Promise<Uint8Array>;
+}

package/dist/transports/fs-transport.js

@@ -0,0 +1,33 @@
+/**
+ * FsTransport — Node-only packed quiver transport that reads from local disk.
+ * Internal; not exported from index.ts.
+ *
+ * Uses dynamic imports of node:fs/promises and node:path so the module can be
+ * imported in environments where those builtins are not available (the dynamic
+ * import only executes when fetchBytes is actually called).
+ */
+import { QuiverError } from "../errors.js";
+export class FsTransport {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    async fetchBytes(relativePath) {
+        const { join, resolve } = await import("node:path");
+        const { readFile } = await import("node:fs/promises");
+        const rootResolved = resolve(this.rootDir);
+        const fullPath = resolve(join(this.rootDir, relativePath));
+        // Defense-in-depth: ensure resolved path stays within rootDir.
+        if (!fullPath.startsWith(rootResolved + "/") && fullPath !== rootResolved) {
+            throw new QuiverError("transport_error", `Path traversal detected: "${relativePath}" escapes quiver root`);
+        }
+        try {
+            const buf = await readFile(fullPath);
+            // Ensure we return a plain Uint8Array, not a Node.js Buffer subclass.
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+        catch (err) {
+            throw new QuiverError("transport_error", `Failed to read "${relativePath}" from packed quiver at "${this.rootDir}": ${err.message}`, { cause: err });
+        }
+    }
+}

package/dist/transports/http-transport.d.ts

@@ -0,0 +1,12 @@
+/**
+ * HttpTransport — browser-safe packed quiver transport that fetches via HTTP.
+ * Internal; not exported from index.ts.
+ *
+ * Uses globalThis.fetch — no node: imports at any level.
+ */
+import type { PackedTransport } from "../packed-loader.js";
+export declare class HttpTransport implements PackedTransport {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    fetchBytes(relativePath: string): Promise<Uint8Array>;
+}

package/dist/transports/http-transport.js

@@ -0,0 +1,33 @@
+/**
+ * HttpTransport — browser-safe packed quiver transport that fetches via HTTP.
+ * Internal; not exported from index.ts.
+ *
+ * Uses globalThis.fetch — no node: imports at any level.
+ */
+import { QuiverError } from "../errors.js";
+export class HttpTransport {
+    baseUrl;
+    constructor(baseUrl) {
+        // Normalize: ensure exactly one trailing slash.
+        this.baseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    }
+    async fetchBytes(relativePath) {
+        // Strip any leading slash from relativePath to avoid double slashes.
+        const cleanPath = relativePath.startsWith("/")
+            ? relativePath.slice(1)
+            : relativePath;
+        const url = `${this.baseUrl}${cleanPath}`;
+        let response;
+        try {
+            response = await globalThis.fetch(url);
+        }
+        catch (err) {
+            throw new QuiverError("transport_error", `Network error fetching "${url}": ${err.message}`, { cause: err });
+        }
+        if (!response.ok) {
+            throw new QuiverError("transport_error", `HTTP ${response.status} fetching "${url}"`);
+        }
+        const buffer = await response.arrayBuffer();
+        return new Uint8Array(buffer);
+    }
+}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@quillmark/quiver",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Quiver registry and packaging for Quillmark",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/quillmark/quiver"
+    "url": "git+https://github.com/nibsbin/quillmark-quiver.git"
   },
+  "bugs": {
+    "url": "https://github.com/nibsbin/quillmark-quiver/issues"
+  },
+  "homepage": "https://github.com/nibsbin/quillmark-quiver#readme",
   "keywords": [
     "quillmark",
     "quiver",
@@ -26,6 +30,10 @@
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
     }
   },
   "files": [
@@ -34,7 +42,13 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@quillmark/wasm": ">=0.59.0-rc.2"
+    "@quillmark/wasm": ">=0.59.0-rc.2",
+    "vitest": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
   },
   "dependencies": {
     "fflate": "^0.8.2",