@wrtnlabs/evidence 0.0.0

package/lib/parsers/EvidenceParseSession.d.ts

@@ -0,0 +1,141 @@
+import type { Node, QueryCapture, QueryMatch, Tree } from "web-tree-sitter";
+import type { IEvidenceSourceRange } from "../structures/IEvidenceSourceRange";
+/**
+ * Borrows one syntax tree and owns its query cache during an extraction callback.
+ *
+ * `EvidenceParser.parse` creates the session after verifying syntax completeness
+ * and disposes it before releasing the tree. Adapters can traverse `root`, query
+ * captures or matches, and convert nodes into serializable ranges. Nodes and
+ * query results remain borrowed; only copied names, ranges, and relationships
+ * may survive the callback.
+ *
+ * Every operation checks lifetime and node ownership. A query that cannot be
+ * compiled, needs unsupported external predicates, or exceeds its match limit
+ * rejects extraction rather than supplying an apparently complete subset.
+ *
+ * @example
+ * // Inside EvidenceParser.parse's callback:
+ * const range: IEvidenceSourceRange = session.range(session.root);
+ * // Return range, not session.root: the range is data, while the node is borrowed.
+ */
+export declare class EvidenceParseSession {
+    /**
+     * Tree borrowed from the parser runtime.
+     *
+     * Nodes passed to session operations must belong to this exact tree. The
+     * runtime deletes it only after the session has released its queries.
+     */
+    private readonly tree;
+    /**
+     * Source filename attached to session failures.
+     *
+     * Query and lifetime errors retain this location even when no valid node
+     * range is available for a more precise diagnostic.
+     */
+    private readonly file;
+    /**
+     * Whether the callback's query resources have been released.
+     *
+     * The closed flag prevents subsequent access to the borrowed tree and makes
+     * disposal idempotent without relying on native object state.
+     */
+    private closed;
+    /**
+     * Compiled queries owned by this session, keyed by exact query source.
+     *
+     * Repeated extraction queries reuse their compiled form. The cache is released
+     * before the runtime deletes the tree and cannot be shared across sessions.
+     */
+    private readonly queries;
+    /**
+     * Binds a complete tree to its callback-scoped extraction session.
+     *
+     * The runtime retains ownership of the tree; this session owns only compiled
+     * queries. Adapters receive an existing session instead of constructing one.
+     *
+     * @internal
+     */
+    constructor(
+    /**
+     * Tree borrowed from the parser runtime.
+     *
+     * Nodes passed to session operations must belong to this exact tree. The
+     * runtime deletes it only after the session has released its queries.
+     */
+    tree: Tree, 
+    /**
+     * Source filename attached to session failures.
+     *
+     * Query and lifetime errors retain this location even when no valid node
+     * range is available for a more precise diagnostic.
+     */
+    file: string);
+    /**
+     * Returns the borrowed root node while the session remains open.
+     *
+     * Traversal is valid only within the parse callback. Access after disposal
+     * throws a session-closed error instead of exposing an already released tree.
+     */
+    get root(): Node;
+    /**
+     * Copies a session-owned node's source coordinates into a serializable range.
+     *
+     * The range can safely escape the callback. Foreign-tree nodes and calls after
+     * disposal reject before coordinate conversion, preserving source ownership.
+     */
+    range(node: Node): IEvidenceSourceRange;
+    /**
+     * Runs a query and returns its flattened borrowed captures.
+     *
+     * Omit `node` to query the full root. A supplied node must belong to this tree.
+     * Compilation failures, unsupported predicates, and match-limit truncation
+     * throw, since incomplete captures cannot establish a public population.
+     */
+    captures(source: string, node?: Node): QueryCapture[];
+    /**
+     * Runs a query while retaining captures grouped by their matching pattern.
+     *
+     * Use matches when ownership depends on captures belonging to the same syntax
+     * occurrence. The default target is the root; ownership and completeness checks
+     * are the same as for `captures`, and returned nodes remain callback-scoped.
+     */
+    matches(source: string, node?: Node): QueryMatch[];
+    /**
+     * Closes the session and releases its compiled queries once.
+     *
+     * The runtime calls this before deleting the separately owned tree. Marking the
+     * session closed first prevents later API calls from accessing borrowed nodes.
+     *
+     * @internal
+     */
+    dispose(): void;
+    /**
+     * Compiles or reuses a query whose semantics the binding can fully evaluate.
+     *
+     * External and property predicates are refused before caching. Treating them
+     * as ignored filters would return incorrect captures while claiming a complete
+     * inventory; failed queries are deleted and reported against the source file.
+     */
+    private query;
+    /**
+     * Rejects a query result truncated by Tree-sitter's match limit.
+     *
+     * A truncated result can omit public declarations, so it must fail extraction
+     * rather than become a smaller coverage denominator.
+     */
+    private assertComplete;
+    /**
+     * Enforces the parse callback's lifetime boundary.
+     *
+     * Every exposed tree operation checks this state before touching native data,
+     * producing a stable session error after disposal.
+     */
+    private assertOpen;
+    /**
+     * Requires a live node from this session's own tree.
+     *
+     * A node from another callback may still be live but has a different source
+     * and lifetime. Reject it instead of reporting coordinates under this file.
+     */
+    private assertNode;
+}

package/lib/parsers/EvidenceParseSession.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceParseSession = void 0;
+const web_tree_sitter_1 = require("web-tree-sitter");
+const EvidenceParserError_1 = require("./EvidenceParserError");
+const TreeSitterRange_1 = require("../internal/TreeSitterRange");
+/**
+ * Borrows one syntax tree and owns its query cache during an extraction callback.
+ *
+ * `EvidenceParser.parse` creates the session after verifying syntax completeness
+ * and disposes it before releasing the tree. Adapters can traverse `root`, query
+ * captures or matches, and convert nodes into serializable ranges. Nodes and
+ * query results remain borrowed; only copied names, ranges, and relationships
+ * may survive the callback.
+ *
+ * Every operation checks lifetime and node ownership. A query that cannot be
+ * compiled, needs unsupported external predicates, or exceeds its match limit
+ * rejects extraction rather than supplying an apparently complete subset.
+ *
+ * @example
+ * // Inside EvidenceParser.parse's callback:
+ * const range: IEvidenceSourceRange = session.range(session.root);
+ * // Return range, not session.root: the range is data, while the node is borrowed.
+ */
+class EvidenceParseSession {
+    tree;
+    file;
+    /**
+     * Whether the callback's query resources have been released.
+     *
+     * The closed flag prevents subsequent access to the borrowed tree and makes
+     * disposal idempotent without relying on native object state.
+     */
+    closed = false;
+    /**
+     * Compiled queries owned by this session, keyed by exact query source.
+     *
+     * Repeated extraction queries reuse their compiled form. The cache is released
+     * before the runtime deletes the tree and cannot be shared across sessions.
+     */
+    queries = new Map();
+    /**
+     * Binds a complete tree to its callback-scoped extraction session.
+     *
+     * The runtime retains ownership of the tree; this session owns only compiled
+     * queries. Adapters receive an existing session instead of constructing one.
+     *
+     * @internal
+     */
+    constructor(
+    /**
+     * Tree borrowed from the parser runtime.
+     *
+     * Nodes passed to session operations must belong to this exact tree. The
+     * runtime deletes it only after the session has released its queries.
+     */
+    tree, 
+    /**
+     * Source filename attached to session failures.
+     *
+     * Query and lifetime errors retain this location even when no valid node
+     * range is available for a more precise diagnostic.
+     */
+    file) {
+        this.tree = tree;
+        this.file = file;
+    }
+    /**
+     * Returns the borrowed root node while the session remains open.
+     *
+     * Traversal is valid only within the parse callback. Access after disposal
+     * throws a session-closed error instead of exposing an already released tree.
+     */
+    get root() {
+        this.assertOpen();
+        return this.tree.rootNode;
+    }
+    /**
+     * Copies a session-owned node's source coordinates into a serializable range.
+     *
+     * The range can safely escape the callback. Foreign-tree nodes and calls after
+     * disposal reject before coordinate conversion, preserving source ownership.
+     */
+    range(node) {
+        this.assertNode(node);
+        return TreeSitterRange_1.TreeSitterRange.from(node);
+    }
+    /**
+     * Runs a query and returns its flattened borrowed captures.
+     *
+     * Omit `node` to query the full root. A supplied node must belong to this tree.
+     * Compilation failures, unsupported predicates, and match-limit truncation
+     * throw, since incomplete captures cannot establish a public population.
+     */
+    captures(source, node) {
+        const target = node ?? this.root;
+        this.assertNode(target);
+        const query = this.query(source);
+        const captures = query.captures(target);
+        this.assertComplete(query);
+        return captures;
+    }
+    /**
+     * Runs a query while retaining captures grouped by their matching pattern.
+     *
+     * Use matches when ownership depends on captures belonging to the same syntax
+     * occurrence. The default target is the root; ownership and completeness checks
+     * are the same as for `captures`, and returned nodes remain callback-scoped.
+     */
+    matches(source, node) {
+        const target = node ?? this.root;
+        this.assertNode(target);
+        const query = this.query(source);
+        const matches = query.matches(target);
+        this.assertComplete(query);
+        return matches;
+    }
+    /**
+     * Closes the session and releases its compiled queries once.
+     *
+     * The runtime calls this before deleting the separately owned tree. Marking the
+     * session closed first prevents later API calls from accessing borrowed nodes.
+     *
+     * @internal
+     */
+    dispose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const query of this.queries.values())
+            query.delete();
+        this.queries.clear();
+    }
+    /**
+     * Compiles or reuses a query whose semantics the binding can fully evaluate.
+     *
+     * External and property predicates are refused before caching. Treating them
+     * as ignored filters would return incorrect captures while claiming a complete
+     * inventory; failed queries are deleted and reported against the source file.
+     */
+    query(source) {
+        let query = this.queries.get(source);
+        if (query !== undefined)
+            return query;
+        try {
+            query = new web_tree_sitter_1.Query(this.tree.language, source);
+            // The binding exposes custom/property predicates without evaluating their semantics.
+            if (query.predicates.some((predicates) => predicates.length !== 0) ||
+                query.assertedProperties.some((properties) => Object.keys(properties).length !== 0) ||
+                query.refutedProperties.some((properties) => Object.keys(properties).length !== 0)) {
+                query.delete();
+                throw new Error("Query predicates requiring an external evaluator are unsupported.");
+            }
+            this.queries.set(source, query);
+            return query;
+        }
+        catch (cause) {
+            throw new EvidenceParserError_1.EvidenceParserError("query-invalid", this.file, "The adapter query is incompatible with this grammar or requires an unsupported predicate. Correct the query before extracting symbols.", undefined, { cause });
+        }
+    }
+    /**
+     * Rejects a query result truncated by Tree-sitter's match limit.
+     *
+     * A truncated result can omit public declarations, so it must fail extraction
+     * rather than become a smaller coverage denominator.
+     */
+    assertComplete(query) {
+        if (query.didExceedMatchLimit())
+            throw new EvidenceParserError_1.EvidenceParserError("query-incomplete", this.file, "The adapter query exceeded its match limit. Simplify the query before using its captures as a complete inventory.");
+    }
+    /**
+     * Enforces the parse callback's lifetime boundary.
+     *
+     * Every exposed tree operation checks this state before touching native data,
+     * producing a stable session error after disposal.
+     */
+    assertOpen() {
+        if (this.closed)
+            throw new EvidenceParserError_1.EvidenceParserError("session-closed", this.file, "This parse callback has ended; its borrowed nodes are no longer valid.");
+    }
+    /**
+     * Requires a live node from this session's own tree.
+     *
+     * A node from another callback may still be live but has a different source
+     * and lifetime. Reject it instead of reporting coordinates under this file.
+     */
+    assertNode(node) {
+        this.assertOpen();
+        if (node.tree !== this.tree)
+            throw new EvidenceParserError_1.EvidenceParserError("query-invalid", this.file, "The node belongs to another parse session.");
+    }
+}
+exports.EvidenceParseSession = EvidenceParseSession;

package/lib/parsers/EvidenceParser.d.ts

@@ -0,0 +1,109 @@
+import { EvidenceParseSession } from "./EvidenceParseSession";
+import type { IEvidenceGrammar } from "../structures/IEvidenceGrammar";
+import type { IEvidenceParserInput } from "../structures/IEvidenceParserInput";
+import type { IEvidenceParserOptions } from "../structures/IEvidenceParserOptions";
+import type { IEvidenceParserState } from "../structures/IEvidenceParserState";
+/**
+ * Owns bounded Tree-sitter parse sessions with lazy, verified grammar acquisition.
+ *
+ * Create a parser for a group of source extractions, call `parse` for each file,
+ * then await `close`. Grammar selection uses the configured artifact and filename;
+ * acquisition starts only when that grammar is needed. Construction and metadata
+ * inspection do not initialize a language or parse source.
+ *
+ * Each request owns a native parser and tree. Its callback receives a borrowed
+ * session only after syntax completeness is established, and must return data
+ * that no longer depends on native objects. The concurrency slot remains held
+ * during asynchronous callback work, so a callback must not await another parse
+ * or close on the same pool: that work can wait for the callback's own slot.
+ *
+ * Cleanup runs for successful extraction and every failure path. Closing rejects
+ * new requests and waits for accepted callbacks; immutable process-wide grammar
+ * data can remain cached for later runtimes.
+ *
+ * @example
+ * const parser: EvidenceParser = new EvidenceParser({ concurrency: 2 });
+ * try {
+ *   const range: IEvidenceSourceRange = await parser.parse(
+ *     { type: "typescript", file: "api.ts", content: "export const value = 1;" },
+ *     (session: EvidenceParseSession): IEvidenceSourceRange =>
+ *       session.range(session.root),
+ *   );
+ * } finally {
+ *   await parser.close();
+ * }
+ */
+export declare class EvidenceParser {
+    /**
+     * Asset provider for pinned grammar metadata and verified bytes.
+     *
+     * Keeping one provider per runtime shares acquisition work without loading
+     * every registered grammar when the parser is constructed.
+     */
+    private readonly assets;
+    /**
+     * Admission queue and lifecycle boundary for parse callbacks.
+     *
+     * A slot covers acquisition, parsing, and the callback's asynchronous lifetime.
+     * Closing this queue prevents new work before native resources are discarded.
+     */
+    private readonly slots;
+    /**
+     * In-flight or fulfilled language loads keyed by grammar ID.
+     *
+     * Concurrent requests share a load. A rejected entry is removed so a later
+     * request can recover after acquisition or initialization becomes available.
+     */
+    private readonly languages;
+    /**
+     * Grammar IDs successfully loaded by this runtime.
+     *
+     * State inspection reports this history separately from pending loads, so a
+     * failed acquisition is not advertised as a usable language.
+     */
+    private readonly loaded;
+    /**
+     * Creates a lazy parser pool with a bounded callback count.
+     *
+     * The default permits four active requests. Options are validated immediately,
+     * but grammar acquisition and native parser allocation wait for `parse`.
+     */
+    constructor(options?: IEvidenceParserOptions);
+    /**
+     * Lists pinned grammar provenance without loading a language.
+     *
+     * The returned catalog describes acquisition inputs, including checksums and
+     * licenses. It does not imply that every grammar has a certified adapter or
+     * that any grammar has already been downloaded.
+     */
+    grammars(): Promise<IEvidenceGrammar[]>;
+    /**
+     * Reports admission state and successfully loaded grammar IDs.
+     *
+     * Reading state does not acquire assets or wait for pending parses. The returned
+     * counts describe this pool; the language list records its successful loads.
+     */
+    state(): IEvidenceParserState;
+    /**
+     * Extracts data from a complete syntax tree within a borrowed callback session.
+     *
+     * Syntax errors, missing nodes, and incompatible grammars reject before the
+     * callback can treat a partial tree as a complete declaration inventory.
+     * Callback failures propagate after the tree, parser, and slot are released.
+     *
+     * Callbacks may await work, but must not await another parse or close on this
+     * same pool. Copy names, ranges, and relationships into serializable values;
+     * returning a node, tree, or session would retain already released resources.
+     */
+    parse<T>(input: IEvidenceParserInput, closure: (session: EvidenceParseSession) => T | Promise<T>): Promise<T>;
+    /**
+     * Stops admission and waits for accepted parse callbacks to finish.
+     *
+     * Call this outside a parse callback to avoid waiting on the callback itself.
+     * Runtime-local load promises are released afterward; process-wide immutable
+     * grammar data remains reusable by other parser instances.
+     */
+    close(): Promise<void>;
+    private language;
+    private load;
+}