@quillmark/quiver 0.2.0 → 0.4.0

package/dist/registry.js

@@ -1,115 +0,0 @@
-import { QuiverError } from "./errors.js";
-import { parseQuillRef } from "./ref.js";
-import { matchesSemverSelector, chooseHighestVersion } from "./semver.js";
-export class QuiverRegistry {
-    #engine;
-    #quivers;
-    /** Cache: canonical ref → pending or resolved Promise<QuillLike>. */
-    #cache = new Map();
-    constructor(args) {
-        this.#engine = args.engine;
-        // Validate no two quivers share Quiver.yaml.name → quiver_collision.
-        const seen = new Map();
-        for (const quiver of args.quivers) {
-            const existing = seen.get(quiver.name);
-            if (existing !== undefined) {
-                throw new QuiverError("quiver_collision", `Two quivers share the name "${quiver.name}": first quiver and a later quiver both declare this name. ` +
-                    `Quiver names must be unique within a registry.`, { quiverName: quiver.name });
-            }
-            seen.set(quiver.name, quiver.name);
-        }
-        this.#quivers = Object.freeze([...args.quivers]);
-    }
-    /**
-     * Resolves a selector ref → canonical ref (e.g. "memo" → "memo@1.1.0").
-     *
-     * Applies multi-quiver precedence (§4): scan quivers in order, first quiver
-     * with any matching candidate wins, highest match within that quiver returned.
-     *
-     * Throws:
-     *   - `invalid_ref` if ref fails parseQuillRef
-     *   - `quill_not_found` if no quiver has a matching candidate
-     */
-    async resolve(ref) {
-        // Throws invalid_ref on malformed input.
-        const parsed = parseQuillRef(ref);
-        for (const quiver of this.#quivers) {
-            const versions = quiver.versionsOf(parsed.name);
-            if (versions.length === 0)
-                continue;
-            // Filter by selector if present; otherwise all versions are candidates.
-            const candidates = parsed.selector === undefined
-                ? versions
-                : versions.filter((v) => matchesSemverSelector(v, parsed.selector));
-            if (candidates.length === 0)
-                continue;
-            // First quiver with any candidate wins — pick highest within that quiver.
-            const winner = chooseHighestVersion(candidates);
-            // chooseHighestVersion returns null only for empty arrays; candidates is non-empty.
-            return `${parsed.name}@${winner}`;
-        }
-        throw new QuiverError("quill_not_found", `No quill found for ref "${ref}" in any registered quiver.`, { ref });
-    }
-    /**
-     * Returns a render-ready QuillLike instance for a canonical ref.
-     * Materializes via engine.quill(tree) on first call; caches by canonical ref.
-     *
-     * Throws:
-     *   - `invalid_ref` if canonicalRef is not valid canonical x.y.z form
-     *   - `quill_not_found` if canonical ref doesn't map to a loaded quiver
-     *   - propagates I/O errors from loadTree unchanged
-     *   - propagates engine errors from engine.quill() unchanged (not wrapped)
-     */
-    async getQuill(canonicalRef) {
-        let entry = this.#cache.get(canonicalRef);
-        if (entry === undefined) {
-            entry = this.#loadQuill(canonicalRef).catch((err) => {
-                this.#cache.delete(canonicalRef);
-                throw err;
-            });
-            this.#cache.set(canonicalRef, entry);
-        }
-        return entry;
-    }
-    /** Internal: does the actual loading work for getQuill. */
-    async #loadQuill(canonicalRef) {
-        // Parse and validate canonical form (must be x.y.z).
-        const parsed = parseQuillRef(canonicalRef);
-        if (parsed.selectorDepth !== 3) {
-            throw new QuiverError("invalid_ref", `getQuill requires a canonical ref (x.y.z) but received "${canonicalRef}". ` +
-                `Use resolve() first to obtain a canonical ref.`, { ref: canonicalRef });
-        }
-        const version = parsed.selector;
-        // Find the first quiver that owns this exact (name, version) pair.
-        const owningQuiver = this.#quivers.find((q) => q.versionsOf(parsed.name).includes(version));
-        if (owningQuiver === undefined) {
-            throw new QuiverError("quill_not_found", `Quill "${canonicalRef}" was not found in any registered quiver.`, { ref: canonicalRef, version });
-        }
-        // Load the file tree — I/O errors propagate as-is.
-        const tree = await owningQuiver.loadTree(parsed.name, version);
-        // Materialize the Quill via the engine.
-        // Engine errors propagate unchanged — they are not QuiverErrors and we
-        // should not mask them. The caller's error-handling stack will see the
-        // engine's own error type directly.
-        const quill = this.#engine.quill(tree);
-        return quill;
-    }
-    /**
-     * Warms all quill refs across all composed quivers. Fail-fast.
-     *
-     * Calls loadTree + engine.quill(tree) for every known quill version in
-     * parallel. Already-cached refs resolve instantly (idempotent). Rejects on
-     * the first failure (Promise.all fail-fast semantics).
-     */
-    async warm() {
-        const promises = [];
-        for (const quiver of this.#quivers) {
-            for (const name of quiver.quillNames()) {
-                for (const version of quiver.versionsOf(name)) {
-                    promises.push(this.getQuill(`${name}@${version}`));
-                }
-            }
-        }
-        await Promise.all(promises);
-    }
-}

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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,33 +0,0 @@
-/**
- * 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 });
-        }
-    }
-}