@wrtnlabs/evidence 0.0.0

package/lib/adapters/rust/RustSyntax.d.ts

@@ -0,0 +1,93 @@
+import type { Node } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { RustVisibility } from "./RustVisibility";
+/**
+ * Provides grammar-level Rust extraction helpers for names, paths, attributes, and documentation.
+ *
+ * RustFileScanner uses these functions to retain syntax facts. RustModuleResolver
+ * later decides crate reachability and public ownership from the scanner records.
+ */
+export declare namespace RustSyntax {
+    /**
+     * Reads a supported Rust identifier spelling from a grammar node.
+     *
+     * Scanners use it for declaration and member names; unsupported syntax returns
+     * undefined so extraction can preserve uncertainty instead of inventing a name.
+     */
+    function name(node: Node | null): string | undefined;
+    /**
+     * Classifies the visibility modifier written on a Rust declaration.
+     *
+     * Bare `pub` is externally public, scoped forms are restricted, and omitted
+     * modifiers are private. Module resolution evaluates the resulting boundary.
+     */
+    function visibility(node: Node): RustVisibility;
+    /**
+     * Reads a statically supported Rust path as ordered segments.
+     *
+     * Generic wrappers are unwrapped while `crate`, `self`, and `super` remain
+     * literal segments for RustModuleResolver to interpret in its current module.
+     */
+    function path(node: Node | null): string[] | undefined;
+    /**
+     * Collects declared type-parameter names from a Rust item.
+     *
+     * Impl ownership resolution uses these names to distinguish local generic
+     * parameters from paths that must resolve to selected nominal declarations.
+     */
+    function typeParameters(node: Node): string[];
+    /**
+     * Collects outer attributes and outer documentation immediately preceding an item.
+     *
+     * Ordinary comments are skipped because Rust treats them as whitespace. The
+     * returned source order lets scanners attach documentation and inspect attributes.
+     */
+    function attributes(node: Node): Node[];
+    /**
+     * States whether a comment is ordinary Rust whitespace rather than documentation.
+     *
+     * Attribute collection skips these comments without treating them as evidence
+     * carriers or allowing them to interrupt a valid outer-attribute sequence.
+     */
+    function ordinaryComment(node: Node): boolean;
+    /**
+     * Reads the qualified name from a Rust attribute or its wrapper item.
+     *
+     * Scanner attribute policy uses the name to recognize documentation and report
+     * expansion risks; unsupported attribute shapes return undefined.
+     */
+    function attributeName(node: Node): string | undefined;
+    /**
+     * Returns the value expression of a Rust attribute or its wrapper item.
+     *
+     * Documentation-attribute handling validates this node as a supported static
+     * string before it creates a carrier; absent values return null.
+     */
+    function attributeValue(node: Node): Node | null;
+    /**
+     * States whether a Rust comment uses the outer documentation form.
+     *
+     * The scanner may attach only these comment carriers to following item sites.
+     */
+    function outerDocumentation(node: Node): boolean;
+    /**
+     * States whether a Rust comment uses the inner documentation form.
+     *
+     * Inner carriers document their containing module instead of the following item.
+     */
+    function innerDocumentation(node: Node): boolean;
+    /**
+     * Supplies delimiter rules for a Rust comment carrier.
+     *
+     * RustFileScanner uses the returned syntax to map text and preserve tag
+     * coordinates for line, block, ordinary, and documentation comment forms.
+     */
+    function comment(node: Node): IEvidenceCommentSyntax;
+    /**
+     * Supplies delimiter rules for a supported Rust string literal.
+     *
+     * Annotation scanning uses this result for ordinary and raw strings, whose
+     * contents can report unsupported tags but cannot authorize withdrawals.
+     */
+    function string(node: Node): IEvidenceCommentSyntax | undefined;
+}

package/lib/adapters/rust/RustSyntax.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RustSyntax = void 0;
+/**
+ * Provides grammar-level Rust extraction helpers for names, paths, attributes, and documentation.
+ *
+ * RustFileScanner uses these functions to retain syntax facts. RustModuleResolver
+ * later decides crate reachability and public ownership from the scanner records.
+ */
+var RustSyntax;
+(function (RustSyntax) {
+    /**
+     * Reads a supported Rust identifier spelling from a grammar node.
+     *
+     * Scanners use it for declaration and member names; unsupported syntax returns
+     * undefined so extraction can preserve uncertainty instead of inventing a name.
+     */
+    function name(node) {
+        return node !== null &&
+            (node.type === "identifier" ||
+                node.type === "field_identifier" ||
+                node.type === "type_identifier")
+            ? node.text
+            : undefined;
+    }
+    RustSyntax.name = name;
+    /**
+     * Classifies the visibility modifier written on a Rust declaration.
+     *
+     * Bare `pub` is externally public, scoped forms are restricted, and omitted
+     * modifiers are private. Module resolution evaluates the resulting boundary.
+     */
+    function visibility(node) {
+        const modifier = node.namedChildren.find((child) => child.type === "visibility_modifier");
+        if (modifier === undefined)
+            return "private";
+        return modifier.text.trim() === "pub" ? "public" : "restricted";
+    }
+    RustSyntax.visibility = visibility;
+    /**
+     * Reads a statically supported Rust path as ordered segments.
+     *
+     * Generic wrappers are unwrapped while `crate`, `self`, and `super` remain
+     * literal segments for RustModuleResolver to interpret in its current module.
+     */
+    function path(node) {
+        if (node === null)
+            return undefined;
+        const direct = name(node);
+        if (direct !== undefined)
+            return [direct];
+        if (node.type === "crate" || node.type === "self" || node.type === "super")
+            return [node.text];
+        if (node.type === "scoped_identifier" ||
+            node.type === "scoped_type_identifier") {
+            const prefix = path(node.childForFieldName("path"));
+            const suffix = name(node.childForFieldName("name"));
+            return prefix === undefined || suffix === undefined
+                ? undefined
+                : [...prefix, suffix];
+        }
+        if (node.type === "generic_type")
+            return path(node.childForFieldName("type"));
+        return undefined;
+    }
+    RustSyntax.path = path;
+    /**
+     * Collects declared type-parameter names from a Rust item.
+     *
+     * Impl ownership resolution uses these names to distinguish local generic
+     * parameters from paths that must resolve to selected nominal declarations.
+     */
+    function typeParameters(node) {
+        const parameters = node.childForFieldName("type_parameters");
+        if (parameters === null)
+            return [];
+        return parameters
+            .descendantsOfType("type_parameter")
+            .flatMap((parameter) => {
+            const declared = name(parameter.childForFieldName("name"));
+            return declared === undefined ? [] : [declared];
+        });
+    }
+    RustSyntax.typeParameters = typeParameters;
+    /**
+     * Collects outer attributes and outer documentation immediately preceding an item.
+     *
+     * Ordinary comments are skipped because Rust treats them as whitespace. The
+     * returned source order lets scanners attach documentation and inspect attributes.
+     */
+    function attributes(node) {
+        const output = [];
+        let previous = node.previousNamedSibling;
+        while (previous !== null &&
+            (previous.type === "attribute_item" ||
+                isOuterDocumentation(previous) ||
+                ordinaryComment(previous))) {
+            if (!ordinaryComment(previous))
+                output.push(previous);
+            previous = previous.previousNamedSibling;
+        }
+        return output.reverse();
+    }
+    RustSyntax.attributes = attributes;
+    /**
+     * States whether a comment is ordinary Rust whitespace rather than documentation.
+     *
+     * Attribute collection skips these comments without treating them as evidence
+     * carriers or allowing them to interrupt a valid outer-attribute sequence.
+     */
+    function ordinaryComment(node) {
+        return ((node.type === "line_comment" || node.type === "block_comment") &&
+            node.childForFieldName("outer") === null &&
+            node.childForFieldName("inner") === null);
+    }
+    RustSyntax.ordinaryComment = ordinaryComment;
+    /**
+     * Reads the qualified name from a Rust attribute or its wrapper item.
+     *
+     * Scanner attribute policy uses the name to recognize documentation and report
+     * expansion risks; unsupported attribute shapes return undefined.
+     */
+    function attributeName(node) {
+        const attribute = node.type === "attribute_item" || node.type === "inner_attribute_item"
+            ? (node.namedChildren.find((child) => child.type === "attribute") ??
+                null)
+            : node.type === "attribute"
+                ? node
+                : null;
+        if (attribute === null)
+            return undefined;
+        const head = attribute.namedChildren[0] ?? null;
+        const segments = path(head);
+        return segments === undefined ? undefined : segments.join("::");
+    }
+    RustSyntax.attributeName = attributeName;
+    /**
+     * Returns the value expression of a Rust attribute or its wrapper item.
+     *
+     * Documentation-attribute handling validates this node as a supported static
+     * string before it creates a carrier; absent values return null.
+     */
+    function attributeValue(node) {
+        const attribute = node.type === "attribute_item" || node.type === "inner_attribute_item"
+            ? (node.namedChildren.find((child) => child.type === "attribute") ??
+                null)
+            : node.type === "attribute"
+                ? node
+                : null;
+        return attribute === null
+            ? null
+            : (attribute.childForFieldName("value") ?? null);
+    }
+    RustSyntax.attributeValue = attributeValue;
+    /**
+     * States whether a Rust comment uses the outer documentation form.
+     *
+     * The scanner may attach only these comment carriers to following item sites.
+     */
+    function outerDocumentation(node) {
+        return isOuterDocumentation(node);
+    }
+    RustSyntax.outerDocumentation = outerDocumentation;
+    /**
+     * States whether a Rust comment uses the inner documentation form.
+     *
+     * Inner carriers document their containing module instead of the following item.
+     */
+    function innerDocumentation(node) {
+        return ((node.type === "line_comment" || node.type === "block_comment") &&
+            node.childForFieldName("inner") !== null);
+    }
+    RustSyntax.innerDocumentation = innerDocumentation;
+    /**
+     * Supplies delimiter rules for a Rust comment carrier.
+     *
+     * RustFileScanner uses the returned syntax to map text and preserve tag
+     * coordinates for line, block, ordinary, and documentation comment forms.
+     */
+    function comment(node) {
+        const outer = isOuterDocumentation(node);
+        const inner = innerDocumentation(node);
+        const opening = node.type === "line_comment"
+            ? outer
+                ? "///"
+                : inner
+                    ? "//!"
+                    : "//"
+            : outer
+                ? "/**"
+                : inner
+                    ? "/*!"
+                    : "/*";
+        return opening.startsWith("//")
+            ? {
+                opening,
+                closing: "",
+                linePrefix: opening,
+                tagBoundaries: true,
+                allowWithdrawal: true,
+            }
+            : {
+                opening,
+                closing: "*/",
+                linePrefix: "*",
+                tagBoundaries: true,
+                allowWithdrawal: true,
+            };
+    }
+    RustSyntax.comment = comment;
+    /**
+     * Supplies delimiter rules for a supported Rust string literal.
+     *
+     * Annotation scanning uses this result for ordinary and raw strings, whose
+     * contents can report unsupported tags but cannot authorize withdrawals.
+     */
+    function string(node) {
+        if (node.type === "string_literal")
+            return {
+                opening: '"',
+                closing: '"',
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        if (node.type === "raw_string_literal") {
+            const match = /^(?:br|r)(#*)"/u.exec(node.text);
+            if (match === null)
+                return undefined;
+            const hashes = match[1] ?? "";
+            return {
+                opening: node.text.slice(0, match[0].length),
+                closing: `"${hashes}`,
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        }
+        return undefined;
+    }
+    RustSyntax.string = string;
+    function isOuterDocumentation(node) {
+        return ((node.type === "line_comment" || node.type === "block_comment") &&
+            node.childForFieldName("outer") !== null);
+    }
+})(RustSyntax || (exports.RustSyntax = RustSyntax = {}));

package/lib/adapters/rust/RustVisibility.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Represents source visibility relevant to Rust's externally reachable public surface.
+ *
+ * RustSyntax classifies modifiers into this reduced vocabulary. RustModuleResolver
+ * evaluates the value at module boundaries before it publishes a declaration.
+ */
+export type RustVisibility = "public" | "restricted" | "private" | "implicit";

package/lib/adapters/rust/RustVisibility.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/scala/EvidenceScalaAdapter.d.ts

@@ -0,0 +1,15 @@
+import { ScalaAdapter } from "./ScalaAdapter";
+/**
+ * Extracts explicit unrestricted Scala declarations and supported static exports.
+ *
+ * Selected Scala 2/3 source supplies package and lexical ownership. Singleton
+ * objects and package objects retain explicit literal owner segments, and attached
+ * Scaladoc supplies evidence hosts. Supported export projections preserve the
+ * defining declaration's identity rather than duplicating its coverage unit.
+ *
+ * Anonymous givens, wildcard or unresolved exports, inherited or synthesized
+ * members, macro expansion, derives/uses clauses, and extractor bindings are not
+ * inferred as a complete source-public population.
+ */
+export declare class EvidenceScalaAdapter extends ScalaAdapter {
+}

package/lib/adapters/scala/EvidenceScalaAdapter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceScalaAdapter = void 0;
+const ScalaAdapter_1 = require("./ScalaAdapter");
+/**
+ * Extracts explicit unrestricted Scala declarations and supported static exports.
+ *
+ * Selected Scala 2/3 source supplies package and lexical ownership. Singleton
+ * objects and package objects retain explicit literal owner segments, and attached
+ * Scaladoc supplies evidence hosts. Supported export projections preserve the
+ * defining declaration's identity rather than duplicating its coverage unit.
+ *
+ * Anonymous givens, wildcard or unresolved exports, inherited or synthesized
+ * members, macro expansion, derives/uses clauses, and extractor bindings are not
+ * inferred as a complete source-public population.
+ */
+class EvidenceScalaAdapter extends ScalaAdapter_1.ScalaAdapter {
+}
+exports.EvidenceScalaAdapter = EvidenceScalaAdapter;

package/lib/adapters/scala/IScalaDeclaration.d.ts

@@ -0,0 +1,78 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+/**
+ * Represents a Scala source declaration before snapshot-wide overload reconciliation.
+ *
+ * The record preserves lexical identity separately from exported addresses so
+ * singleton exports and overloads can be published without collapsing sites.
+ */
+export interface IScalaDeclaration {
+    /**
+     * Identifies this declaration record within one Scala source analysis.
+     *
+     * Scanner attachments and export records use this ID before semantic units are materialized.
+     */
+    id: string;
+    /**
+     * Stores the declaration name as written in Scala source.
+     *
+     * Backtick delimiters are removed, while characters inside the literal name remain unchanged.
+     */
+    name: string;
+    /**
+     * Classifies the declaration as a public programming symbol.
+     *
+     * Unit materialization includes this kind in the semantic identity so types, functions, and properties cannot merge.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Names the package and lexical owners that define semantic identity.
+     *
+     * Export aliases reuse this path from their source declaration instead of introducing a second unit.
+     */
+    identity: string[];
+    /**
+     * Names this declaration through its physical file address.
+     *
+     * Forwarded exports retain their forwarding address even when their identity belongs to another source owner.
+     */
+    address: string[];
+    /**
+     * Supplies source names that a bounded export may use during lookup.
+     *
+     * These names are not automatically public addresses; limiting lookup to
+     * them prevents arbitrary textual paths from becoming aliases.
+     */
+    lookup: string[];
+    /**
+     * Locates the original declaration and the source ranges included in its fingerprint.
+     *
+     * Extension and enum context may prepend header ranges to the declaration's physical site.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * States whether this declaration and every lexical owner are unrestricted.
+     *
+     * Restricted declarations remain available for boundary analysis but do not become public units.
+     */
+    public: boolean;
+    /**
+     * Identifies a singleton object eligible to supply an exported member.
+     *
+     * Scala's export syntax is resolved only through these static object owners,
+     * avoiding an unsupported inference through arbitrary expressions.
+     */
+    object: boolean;
+    /**
+     * Records the Tree-sitter node spelling that produced this declaration.
+     *
+     * Materialization uses it to distinguish source declarations from forwarding export sites.
+     */
+    syntax: string;
+    /**
+     * Identifies the directly enclosing lexical declaration when one exists.
+     *
+     * Withdrawal and public visibility propagate through this extraction-level ownership chain.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/scala/IScalaDeclaration.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/scala/IScalaDocumentation.d.ts

@@ -0,0 +1,35 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IScalaDocumentationAttachment } from "./IScalaDocumentationAttachment";
+/**
+ * Represents a Scala documentation carrier or tag-bearing unsupported carrier.
+ *
+ * Scaladoc remains tied to its physical declaration site while later export
+ * resolution may add addresses for the same semantic declaration.
+ */
+export interface IScalaDocumentation {
+    /**
+     * Identifies this physical documentation carrier within its source analysis.
+     *
+     * Attachments use this key before the adapter materializes semantic units.
+     */
+    id: string;
+    /**
+     * Locates the half-open UTF-16 span occupied by the documentation carrier.
+     *
+     * Review fingerprints exclude this range from its attached declaration content.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Describes delimiters and annotation rules for parsing this carrier.
+     *
+     * Documentation mapping preserves these rules while masking ineligible examples.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Lists physical declaration sites directly attached to this carrier.
+     *
+     * Unsupported tagged carriers remain unattached for diagnostic host creation.
+     */
+    attachments: IScalaDocumentationAttachment[];
+}

package/lib/adapters/scala/IScalaDocumentation.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/scala/IScalaDocumentationAttachment.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Associates parsed Scaladoc with one Scala declaration site.
+ *
+ * Scala scanning stores attachments separately from documentation mappings so
+ * extraction can retain each comment's source range and every consuming site.
+ */
+export interface IScalaDocumentationAttachment {
+    /**
+     * Identifies the declaration that owns the attached documentation.
+     *
+     * Consumers use this extraction identity to connect the mapping before
+     * semantic units are materialized.
+     */
+    declarationId: string;
+    /**
+     * Identifies the physical declaration site that received the comment.
+     *
+     * A declaration can have several sites, so this prevents attachment from
+     * being inferred from semantic identity alone.
+     */
+    siteId: string;
+}

package/lib/adapters/scala/IScalaDocumentationAttachment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/scala/IScalaExport.d.ts

@@ -0,0 +1,29 @@
+import type { IScalaDeclaration } from "./IScalaDeclaration";
+/**
+ * Represents a Scala forwarding declaration awaiting source-member resolution.
+ *
+ * The scanner preserves the forwarder's host and site first, then resolves the
+ * requested source member through lexical paths during export materialization.
+ */
+export interface IScalaExport {
+    /**
+     * Holds the forwarding declaration and its original extraction metadata.
+     *
+     * Its site remains the public declaration site even when the target is
+     * declared in another object or file.
+     */
+    declaration: IScalaDeclaration;
+    /**
+     * Lists lexical paths at which the source singleton can be found.
+     *
+     * Each path is tried in declaration context because relative Scala references
+     * can resolve through nested owners.
+     */
+    paths: string[][];
+    /**
+     * Names the literal member requested from the resolved source object.
+     *
+     * Dynamic or computed exports are excluded before this record is created.
+     */
+    member: string;
+}

package/lib/adapters/scala/IScalaExport.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/scala/IScalaFileAnalysis.d.ts

@@ -0,0 +1,50 @@
+import type { IScalaExport } from "./IScalaExport";
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IScalaDeclaration } from "./IScalaDeclaration";
+import type { IScalaDocumentation } from "./IScalaDocumentation";
+/**
+ * Holds the node-free Scala extraction retained after a parse session closes.
+ *
+ * Export reconciliation needs declarations from the selected snapshot at once,
+ * while parser state is intentionally released after each source scan.
+ */
+export interface IScalaFileAnalysis {
+    /**
+     * Retains the selected source snapshot that produced this analysis.
+     *
+     * Later export and documentation passes use its paths and content after the parser session closes.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Lists declarations extracted from this source, including non-public boundaries.
+     *
+     * Visibility is resolved during publication, while retained private records support export and withdrawal decisions.
+     */
+    declarations: IScalaDeclaration[];
+    /**
+     * Lists classified Scaladoc and tag-bearing unsupported carriers.
+     *
+     * The adapter materializes them into attached or unsupported hosts after unit publication.
+     */
+    documentation: IScalaDocumentation[];
+    /**
+     * Lists failures encountered while establishing the Scala public surface.
+     *
+     * Each diagnostic keeps the source inventory incomplete instead of allowing a smaller population to pass.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * Lists explicit forwarding exports awaiting selected-source resolution.
+     *
+     * Resolution runs after every selected file supplies declarations and lexical lookup paths.
+     */
+    exports: IScalaExport[];
+    /**
+     * States whether scanning classified every surface-affecting Scala form.
+     *
+     * The inventory carries a false value forward so incomplete export discovery
+     * cannot silently turn a missing obligation into a passing result.
+     */
+    complete: boolean;
+}

package/lib/adapters/scala/IScalaFileAnalysis.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });