@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/parsers/EvidenceDocumentationExamples.js

@@ -0,0 +1,377 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceDocumentationExamples = void 0;
+/**
+ * Coordinates example masking shared by programming-language documentation
+ * readers.
+ *
+ * Several documentation syntaxes permit both Markdown code and HTML example
+ * elements. Their precedence must be decided across the whole comment before an
+ * adapter looks for Evidence Graph tags; otherwise a literal `<pre>` in one
+ * fence can consume real prose and annotations after that fence.
+ */
+var EvidenceDocumentationExamples;
+(function (EvidenceDocumentationExamples) {
+    /**
+     * Finds the least indentation shared by nonempty documentation lines.
+     *
+     * Comment-prefix removal can leave one ordinary padding column. Fence and
+     * indented-code decisions must measure from that baseline rather than from
+     * the physical source column or fully trimmed text.
+     */
+    function baseline(input) {
+        const values = input
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .map((line) => indentation(line));
+        return values.length === 0 ? 0 : Math.min(...values);
+    }
+    EvidenceDocumentationExamples.baseline = baseline;
+    /**
+     * Recognizes one Markdown fence within three columns of a document baseline.
+     *
+     * Four-column indentation denotes an indented code line and cannot open or
+     * close a fence. Backtick info text containing another backtick is likewise
+     * rejected by Markdown's fence grammar.
+     */
+    function fence(line, documentBaseline) {
+        let cursor = 0;
+        let columns = 0;
+        while (cursor < line.length) {
+            if (line[cursor] === " ")
+                ++columns;
+            else if (line[cursor] === "\t")
+                columns += 4 - (columns % 4);
+            else
+                break;
+            ++cursor;
+        }
+        if (columns - documentBaseline < 0 || columns - documentBaseline > 3)
+            return undefined;
+        const marker = line[cursor];
+        if (marker !== "`" && marker !== "~")
+            return undefined;
+        const start = cursor;
+        while (line[cursor] === marker)
+            ++cursor;
+        const length = cursor - start;
+        if (length < 3)
+            return undefined;
+        const remainder = line.slice(cursor);
+        if (marker === "`" && remainder.includes("`"))
+            return undefined;
+        return { marker, length, remainder };
+    }
+    EvidenceDocumentationExamples.fence = fence;
+    /**
+     * Masks HTML example regions without changing source coordinates.
+     *
+     * Tags inside Markdown fences or closed inline-code spans are literals and do
+     * not participate in pairing. In the default HTML mode, slash syntax does not
+     * self-close supported non-void elements; C# selects XML mode so its true
+     * self-closing elements mask only their tag. Matched regions and openings
+     * that remain active through the host end become spaces while CR/LF bytes
+     * remain intact, preserving the source map already owned by the adapter.
+     */
+    function maskHtml(characters, input, names, xmlSelfClosing = false) {
+        const inert = mapMarkdownCode(input);
+        markExistingMasks(inert, characters, input);
+        hideHtmlComments(characters, input, inert);
+        const selected = new Set(names.map((name) => name.toLowerCase()));
+        const openings = [];
+        for (const tag of markupTags(input)) {
+            if (!selected.has(tag.name) || inert[tag.start] === true)
+                continue;
+            const { closing, name, selfClosing } = tag;
+            if (!closing && (!selfClosing || !xmlSelfClosing)) {
+                openings.push([name, tag.start]);
+                continue;
+            }
+            if (selfClosing && !closing) {
+                hide(characters, tag.start, tag.end);
+                continue;
+            }
+            const opening = openings.findLastIndex(([candidate]) => candidate === name);
+            if (opening < 0)
+                continue;
+            hide(characters, openings[opening]?.[1] ?? tag.start, tag.end);
+            // Closing an ancestor implicitly closes selected descendants in HTML.
+            // Remove them together so none can claim the visible suffix through EOF.
+            openings.splice(opening);
+        }
+        // The earliest unmatched opening owns every later nested or sibling opening
+        // through EOF, so one range preserves their complete rendered boundary.
+        const unclosed = openings[0];
+        if (unclosed !== undefined)
+            hide(characters, unclosed[1], input.length);
+    }
+    EvidenceDocumentationExamples.maskHtml = maskHtml;
+    /**
+     * Masks HTML comments before Evidence Graph tag lines are classified.
+     *
+     * Comment delimiters inside Markdown code remain literal. Closed and unclosed
+     * real comments retain their newline bytes and source length so every visible
+     * annotation after a close keeps its original mapping.
+     */
+    function maskHtmlComments(characters, input) {
+        hideHtmlComments(characters, input, mapMarkdownCode(input));
+    }
+    EvidenceDocumentationExamples.maskHtmlComments = maskHtmlComments;
+    /**
+     * Identifies Markdown fenced, indented, and closed inline code coordinates.
+     *
+     * Adapter-native documentation syntax consults this map before opening its
+     * own example state, preventing literal native delimiters from spanning real
+     * documentation outside a Markdown example.
+     */
+    function markdownCode(input) {
+        return mapMarkdownCode(input);
+    }
+    EvidenceDocumentationExamples.markdownCode = markdownCode;
+})(EvidenceDocumentationExamples || (exports.EvidenceDocumentationExamples = EvidenceDocumentationExamples = {}));
+/**
+ * Adds adapter-native example ranges to the shared precedence map.
+ *
+ * Doxygen, Javadoc, and Scaladoc mask their own code syntax before HTML
+ * pairing. Comparing the coordinate-preserving character buffer with the
+ * original input prevents literal tags in those regions from crossing into
+ * ordinary prose.
+ */
+function markExistingMasks(inert, characters, input) {
+    for (let index = 0; index < input.length; ++index)
+        if (characters[index] !== input[index])
+            inert[index] = true;
+}
+/**
+ * Makes real HTML comment regions inert for later documentation passes.
+ *
+ * The caller-provided precedence map already identifies Markdown code. Once an
+ * HTML comment opens, its first close wins even if the enclosed text resembles
+ * another Markdown construct.
+ */
+function hideHtmlComments(characters, input, inert) {
+    const markupInert = [...inert];
+    for (const tag of markupTags(input))
+        mark(markupInert, tag.start, tag.end);
+    let opening;
+    for (const match of input.matchAll(/<!--|-->/gu)) {
+        const index = match.index;
+        if (index === undefined)
+            continue;
+        if (opening === undefined) {
+            if (match[0] === "<!--" && markupInert[index] !== true)
+                opening = index;
+            continue;
+        }
+        if (match[0] !== "-->")
+            continue;
+        const end = index + match[0].length;
+        hide(characters, opening, end);
+        mark(inert, opening, end);
+        opening = undefined;
+    }
+    if (opening !== undefined) {
+        hide(characters, opening, input.length);
+        mark(inert, opening, input.length);
+    }
+}
+/**
+ * Builds the precedence map used before any HTML tag pairing occurs.
+ *
+ * Fence closing rules retain marker kind and minimum delimiter length. Prose
+ * lines are then scanned for closed inline-code spans, leaving unmatched
+ * backticks available as ordinary text instead of hiding the rest of a
+ * comment.
+ */
+function mapMarkdownCode(input) {
+    const output = new Array(input.length).fill(false);
+    const documentBaseline = EvidenceDocumentationExamples.baseline(input);
+    let fenceMarker;
+    let fenceLength = 0;
+    let offset = 0;
+    const lines = input.split("\n");
+    for (const rawLine of lines) {
+        const delimiter = EvidenceDocumentationExamples.fence(rawLine, documentBaseline);
+        if (fenceMarker !== undefined) {
+            mark(output, offset, offset + rawLine.length);
+            if (delimiter !== undefined &&
+                delimiter.marker === fenceMarker &&
+                delimiter.length >= fenceLength &&
+                delimiter.remainder.trim() === "") {
+                fenceMarker = undefined;
+                fenceLength = 0;
+            }
+        }
+        else if (indentation(rawLine) >= documentBaseline + 4) {
+            mark(output, offset, offset + rawLine.length);
+        }
+        else if (delimiter !== undefined) {
+            fenceMarker = delimiter.marker;
+            fenceLength = delimiter.length;
+            mark(output, offset, offset + rawLine.length);
+        }
+        else
+            markInlineCode(output, rawLine, offset);
+        offset += rawLine.length + 1;
+    }
+    return output;
+}
+/**
+ * Measures leading documentation padding in visual columns.
+ *
+ * Tabs advance to the next four-column stop so baseline-relative fence
+ * classification agrees with the indented-code boundary used by the readers.
+ */
+function indentation(line) {
+    let columns = 0;
+    for (const character of line) {
+        if (character === " ")
+            ++columns;
+        else if (character === "\t")
+            columns += 4 - (columns % 4);
+        else
+            break;
+    }
+    return columns;
+}
+/**
+ * Marks closed backtick spans on one prose line.
+ *
+ * Opening and closing runs must have equal length, and escaped runs cannot act
+ * as delimiters. This keeps tag-shaped examples inert without suppressing HTML
+ * after an unmatched or differently sized run.
+ */
+function markInlineCode(output, line, offset) {
+    let cursor = 0;
+    while (cursor < line.length) {
+        const opening = line.indexOf("`", cursor);
+        if (opening < 0)
+            return;
+        const length = delimiterLength(line, opening);
+        if (escaped(line, opening)) {
+            cursor = opening + length;
+            continue;
+        }
+        let closing = opening + length;
+        while (closing < line.length) {
+            closing = line.indexOf("`", closing);
+            if (closing < 0)
+                return;
+            const candidate = delimiterLength(line, closing);
+            if (candidate === length && !escaped(line, closing)) {
+                mark(output, offset + opening, offset + closing + length);
+                cursor = closing + length;
+                break;
+            }
+            closing += candidate;
+        }
+        if (closing < 0 || closing >= line.length)
+            return;
+    }
+}
+/**
+ * Measures one contiguous backtick run from its opening offset.
+ *
+ * Inline-code pairing requires an exact delimiter length, so callers advance by
+ * the whole run instead of reconsidering its interior characters.
+ */
+function delimiterLength(line, start) {
+    let end = start;
+    while (line[end] === "`")
+        ++end;
+    return end - start;
+}
+/**
+ * Reports whether a Markdown backslash run escapes one delimiter.
+ *
+ * Only an odd number of immediately preceding slashes neutralizes the backtick;
+ * an even run represents literal slashes and leaves the delimiter active.
+ */
+function escaped(line, index) {
+    let slashes = 0;
+    for (let cursor = index - 1; cursor >= 0; --cursor) {
+        if (line[cursor] !== "\\")
+            break;
+        ++slashes;
+    }
+    return slashes % 2 === 1;
+}
+/**
+ * Marks one half-open source interval as inert documentation.
+ *
+ * The boolean map shares exact offsets with the original text and is consumed
+ * before HTML pairing, so this helper never changes its length.
+ */
+function mark(output, start, end) {
+    for (let index = start; index < end; ++index)
+        output[index] = true;
+}
+/**
+ * Replaces a half-open example range while retaining newline bytes and length.
+ *
+ * EvidenceDocumentation has already mapped this text to physical source
+ * offsets, so deleting content or normalizing line endings would corrupt every
+ * subsequent diagnostic range.
+ */
+function hide(characters, start, end) {
+    for (let index = start; index < end; ++index)
+        if (characters[index] !== "\n" && characters[index] !== "\r")
+            characters[index] = " ";
+}
+/**
+ * Tokenizes markup elements with quote-aware tag boundaries.
+ *
+ * Scanning every element as one token prevents comment or example delimiters in
+ * quoted attributes from entering later passes. End tags accept only whitespace
+ * after their name, matching the deliberately bounded documentation syntax.
+ */
+function markupTags(input) {
+    const output = [];
+    let cursor = 0;
+    while (cursor < input.length) {
+        const start = input.indexOf("<", cursor);
+        if (start < 0)
+            break;
+        let nameStart = start + 1;
+        const closing = input[nameStart] === "/";
+        if (closing)
+            ++nameStart;
+        let nameEnd = nameStart;
+        while (nameEnd < input.length &&
+            /[A-Za-z0-9:-]/u.test(input[nameEnd] ?? ""))
+            ++nameEnd;
+        if (nameEnd === nameStart) {
+            cursor = start + 1;
+            continue;
+        }
+        let quote;
+        let end = nameEnd;
+        for (; end < input.length; ++end) {
+            const character = input[end];
+            if (quote !== undefined) {
+                if (character === quote)
+                    quote = undefined;
+            }
+            else if (character === "'" || character === '"')
+                quote = character;
+            else if (character === ">")
+                break;
+        }
+        if (end >= input.length)
+            break;
+        ++end;
+        const name = input.slice(nameStart, nameEnd).toLowerCase();
+        const remainder = input.slice(nameEnd, end - 1);
+        if ((!closing || remainder.trim() === "") &&
+            (remainder === "" || /^[\s/]/u.test(remainder)))
+            output.push({
+                start,
+                end,
+                name,
+                closing,
+                selfClosing: !closing && /\/\s*$/u.test(remainder),
+            });
+        cursor = end;
+    }
+    return output;
+}

package/lib/parsers/EvidenceLanguageRegistry.d.ts

@@ -18,32 +18,36 @@ export declare namespace EvidenceLanguageRegistry {
      *
      * Callers may present this metadata or inspect its grammar provenance without
      * mutating the registry. A listed grammar has an Evidence adapter, but its
-     * presence does not mean its WASM asset has been acquired by a parser runtime.
+     * presence does not mean its WASM asset has been acquired by a parser
+     * runtime.
      */
     function list(): IEvidenceLanguage[];
     /**
      * Returns a copy of the certified database-language catalog.
      *
-     * Database types remain separate from programming types because their adapters
-     * expose model, column, and relation semantics rather than lexical declarations.
-     * The copy preserves the registry as the authoritative certification boundary.
+     * Database types remain separate from programming types because their
+     * adapters expose model, column, and relation semantics rather than lexical
+     * declarations. The copy preserves the registry as the authoritative
+     * certification boundary.
      */
     function databases(): IEvidenceDatabaseLanguage[];
     /**
      * Returns investigated language candidates that are not yet supported.
      *
      * Candidate records communicate grammar and adapter blockers to maintainers.
-     * They intentionally cannot be selected: publishing an unimplemented candidate
-     * as a language would imply an extraction boundary Evidence cannot enforce.
+     * They intentionally cannot be selected: publishing an unimplemented
+     * candidate as a language would imply an extraction boundary Evidence cannot
+     * enforce.
      */
     function candidates(): IEvidenceLanguageCandidate[];
     /**
-     * Selects the grammar registered for one configured type and logical filename.
+     * Selects the grammar registered for one configured type and logical
+     * filename.
      *
-     * Filenames are matched after separator normalization and basename extraction;
-     * a grammar is returned as a copy so parser acquisition cannot alter catalog
-     * metadata. Unsupported types and extensions throw typed parser errors instead
-     * of guessing from a shared extension such as `.sql` or `.h`.
+     * Filenames are matched after separator normalization and basename
+     * extraction; a grammar is returned as a copy so parser acquisition cannot
+     * alter catalog metadata. Unsupported types and extensions throw typed parser
+     * errors instead of guessing from a shared extension such as `.sql` or `.h`.
      */
     function select(type: EvidenceProgrammingType | EvidenceDatabaseType, file: string): IEvidenceLanguageGrammar;
 }

package/lib/parsers/EvidenceLanguageRegistry.js

@@ -17,7 +17,8 @@ var EvidenceLanguageRegistry;
      *
      * Callers may present this metadata or inspect its grammar provenance without
      * mutating the registry. A listed grammar has an Evidence adapter, but its
-     * presence does not mean its WASM asset has been acquired by a parser runtime.
+     * presence does not mean its WASM asset has been acquired by a parser
+     * runtime.
      */
     function list() {
         return structuredClone(LANGUAGES);
@@ -26,9 +27,10 @@ var EvidenceLanguageRegistry;
     /**
      * Returns a copy of the certified database-language catalog.
      *
-     * Database types remain separate from programming types because their adapters
-     * expose model, column, and relation semantics rather than lexical declarations.
-     * The copy preserves the registry as the authoritative certification boundary.
+     * Database types remain separate from programming types because their
+     * adapters expose model, column, and relation semantics rather than lexical
+     * declarations. The copy preserves the registry as the authoritative
+     * certification boundary.
      */
     function databases() {
         return structuredClone(DATABASES);
@@ -38,20 +40,22 @@ var EvidenceLanguageRegistry;
      * Returns investigated language candidates that are not yet supported.
      *
      * Candidate records communicate grammar and adapter blockers to maintainers.
-     * They intentionally cannot be selected: publishing an unimplemented candidate
-     * as a language would imply an extraction boundary Evidence cannot enforce.
+     * They intentionally cannot be selected: publishing an unimplemented
+     * candidate as a language would imply an extraction boundary Evidence cannot
+     * enforce.
      */
     function candidates() {
         return structuredClone(CANDIDATES);
     }
     EvidenceLanguageRegistry.candidates = candidates;
     /**
-     * Selects the grammar registered for one configured type and logical filename.
+     * Selects the grammar registered for one configured type and logical
+     * filename.
      *
-     * Filenames are matched after separator normalization and basename extraction;
-     * a grammar is returned as a copy so parser acquisition cannot alter catalog
-     * metadata. Unsupported types and extensions throw typed parser errors instead
-     * of guessing from a shared extension such as `.sql` or `.h`.
+     * Filenames are matched after separator normalization and basename
+     * extraction; a grammar is returned as a copy so parser acquisition cannot
+     * alter catalog metadata. Unsupported types and extensions throw typed parser
+     * errors instead of guessing from a shared extension such as `.sql` or `.h`.
      */
     function select(type, file) {
         const language = [...LANGUAGES, ...DATABASES].find((entry) => entry.type === type);

package/lib/parsers/EvidenceParseSession.d.ts

@@ -1,22 +1,23 @@
 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.
+ * 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.
+ * `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.
+ *   // 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 {
     /**
@@ -43,8 +44,9 @@ export declare class EvidenceParseSession {
     /**
      * 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.
+     * 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;
     /**
@@ -74,37 +76,42 @@ export declare class EvidenceParseSession {
      * 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.
+     * 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.
+     * 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.
+     * 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.
+     * 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.
+     * The runtime calls this before deleting the separately owned tree. Marking
+     * the session closed first prevents later API calls from accessing borrowed
+     * nodes.
      *
      * @internal
      */
@@ -113,8 +120,9 @@ export declare class EvidenceParseSession {
      * 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.
+     * as ignored filters would return incorrect captures while claiming a
+     * complete inventory; failed queries are deleted and reported against the
+     * source file.
      */
     private query;
     /**