@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -0,0 +1,102 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { EvidenceRustVisibility } from "./EvidenceRustVisibility";
+/**
+ * Provides grammar-level Rust extraction helpers for names, paths, attributes,
+ * and documentation.
+ *
+ * EvidenceRustFileScanner uses these functions to retain syntax facts.
+ * EvidenceRustModuleResolver later decides crate reachability and public
+ * ownership from the scanner records.
+ */
+export declare namespace EvidenceRustSyntax {
+    /**
+     * 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: EvidenceNode | 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: EvidenceNode): EvidenceRustVisibility;
+    /**
+     * Reads a statically supported Rust path as ordered segments.
+     *
+     * Generic wrappers are unwrapped while `crate`, `self`, and `super` remain
+     * literal segments for EvidenceRustModuleResolver to interpret in its current
+     * module.
+     */
+    function path(node: EvidenceNode | 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: EvidenceNode): 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: EvidenceNode): EvidenceNode[];
+    /**
+     * 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: EvidenceNode): 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: EvidenceNode): 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: EvidenceNode): EvidenceNode | 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: EvidenceNode): 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: EvidenceNode): boolean;
+    /**
+     * Supplies delimiter rules for a Rust comment carrier.
+     *
+     * EvidenceRustFileScanner uses the returned syntax to map text and preserve
+     * tag coordinates for line, block, ordinary, and documentation comment
+     * forms.
+     */
+    function comment(node: EvidenceNode): 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: EvidenceNode): IEvidenceCommentSyntax | undefined;
+}

package/lib/adapters/rust/EvidenceRustSyntax.js

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceRustSyntax = void 0;
+/**
+ * Provides grammar-level Rust extraction helpers for names, paths, attributes,
+ * and documentation.
+ *
+ * EvidenceRustFileScanner uses these functions to retain syntax facts.
+ * EvidenceRustModuleResolver later decides crate reachability and public
+ * ownership from the scanner records.
+ */
+var EvidenceRustSyntax;
+(function (EvidenceRustSyntax) {
+    /**
+     * 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;
+    }
+    EvidenceRustSyntax.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";
+    }
+    EvidenceRustSyntax.visibility = visibility;
+    /**
+     * Reads a statically supported Rust path as ordered segments.
+     *
+     * Generic wrappers are unwrapped while `crate`, `self`, and `super` remain
+     * literal segments for EvidenceRustModuleResolver 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;
+    }
+    EvidenceRustSyntax.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];
+        });
+    }
+    EvidenceRustSyntax.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();
+    }
+    EvidenceRustSyntax.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);
+    }
+    EvidenceRustSyntax.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("::");
+    }
+    EvidenceRustSyntax.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);
+    }
+    EvidenceRustSyntax.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);
+    }
+    EvidenceRustSyntax.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);
+    }
+    EvidenceRustSyntax.innerDocumentation = innerDocumentation;
+    /**
+     * Supplies delimiter rules for a Rust comment carrier.
+     *
+     * EvidenceRustFileScanner 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,
+            };
+    }
+    EvidenceRustSyntax.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;
+    }
+    EvidenceRustSyntax.string = string;
+    function isOuterDocumentation(node) {
+        return ((node.type === "line_comment" || node.type === "block_comment") &&
+            node.childForFieldName("outer") !== null);
+    }
+})(EvidenceRustSyntax || (exports.EvidenceRustSyntax = EvidenceRustSyntax = {}));

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

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

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

@@ -0,0 +1,79 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { EvidenceRustDeclarationForm } from "./EvidenceRustDeclarationForm";
+import type { EvidenceRustVisibility } from "./EvidenceRustVisibility";
+/**
+ * Captures one Rust declaration before module reachability and impl ownership
+ * resolve.
+ *
+ * EvidenceRustModuleResolver combines this lexical record with the selected
+ * crate graph; scanners do not assume that a visible spelling is externally
+ * reachable.
+ */
+export interface IEvidenceRustDeclaration {
+    /**
+     * Stable scanner identity for this declaration.
+     *
+     * Modules, implementations, and documentation attachments use it before
+     * semantic IDs exist.
+     */
+    id: string;
+    /**
+     * Lexical module segments containing the declaration.
+     *
+     * Public aliases expand from this location only after crate graph resolution.
+     */
+    modulePath: string[];
+    /**
+     * Source name used as the final identity or member segment.
+     *
+     * The resolver preserves this spelling while it derives public paths.
+     */
+    name: string;
+    /**
+     * Evidence selector family assigned to the declaration.
+     *
+     * Consumers distinguish nominal types, functions, and properties through this
+     * value.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Rust grammar form establishing the declaration.
+     *
+     * It selects the resolver's ownership and publication rules.
+     */
+    form: EvidenceRustDeclarationForm;
+    /**
+     * Lexical visibility controlling whether a use can publish this item.
+     *
+     * Its scope is evaluated at module boundaries rather than from the
+     * declaration alone.
+     */
+    visibility: EvidenceRustVisibility;
+    /**
+     * Source ranges used for documentation hosts and review fingerprints.
+     *
+     * They remain valid after the borrowed parser tree closes.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Enclosing declaration identity for directly lexical members.
+     *
+     * Omission leaves owner resolution to a separate impl record or module
+     * context.
+     */
+    ownerDeclarationId?: string;
+    /**
+     * Impl record supplying a nominal owner after cross-module resolution.
+     *
+     * Omission means this declaration has no impl-mediated ownership.
+     */
+    implementationId?: string;
+    /**
+     * Public child segment when this declaration is an impl member.
+     *
+     * Omission keeps non-member declarations from acquiring an artificial
+     * accessor.
+     */
+    memberSegment?: string;
+}

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

@@ -0,0 +1,44 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceRustDocumentationAttachment } from "./IEvidenceRustDocumentationAttachment";
+/**
+ * Retains one Rust documentation carrier, including unsupported tagged text.
+ *
+ * The adapter delays attachment until public occurrences and inherited
+ * withdrawals are known, while preserving unsupported annotations as
+ * diagnosable hosts.
+ */
+export interface IEvidenceRustDocumentation {
+    /**
+     * Stable source-region identity for this documentation carrier.
+     *
+     * It becomes the evidence-host ID after attachment or unsupported-host
+     * creation.
+     */
+    id: string;
+    /**
+     * Original documentation range excluded from its owner's review content.
+     *
+     * The range preserves tag coordinates after parser resources close.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Delimiter and tag rules for Rust line, block, and attribute documentation.
+     *
+     * EvidenceDocumentation uses them to retain source-to-text mappings.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Declaration sites directly associated with this carrier.
+     *
+     * Publication and withdrawal filtering decide which sites reach a visible
+     * host.
+     */
+    attachments: IEvidenceRustDocumentationAttachment[];
+    /**
+     * Module path receiving an inner comment that documents the module.
+     *
+     * Omission means the carrier attaches to item declarations instead.
+     */
+    innerModulePath?: string[];
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Links a Rust documentation carrier to one declaration site.
+ *
+ * Its scanner-local identifiers allow the adapter to group shared sites after
+ * aliases resolve without confusing documentation identity with public
+ * address.
+ */
+export interface IEvidenceRustDocumentationAttachment {
+    /**
+     * Scanner identity of the declaration receiving this documentation.
+     *
+     * The adapter resolves it to a published unit before tags can alter
+     * withdrawals.
+     */
+    declarationId: string;
+    /**
+     * Shared physical-site identity for co-located units.
+     *
+     * It makes their documentation produce one host instead of duplicates.
+     */
+    siteId: string;
+}

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

@@ -0,0 +1,29 @@
+import type { IEvidenceRustDeclaration } from "./IEvidenceRustDeclaration";
+import type { IEvidenceRustFilePlacement } from "./IEvidenceRustFilePlacement";
+/**
+ * Describes one public Rust module binding and the file that exposes its alias.
+ *
+ * Resolver traversal carries the declaration and its module placement together
+ * so visibility is evaluated at the binding boundary instead of the use site
+ * alone.
+ */
+export interface IEvidenceRustExportRecord {
+    /**
+     * Name introduced into the exporting module's public namespace.
+     *
+     * It forms the next segment when the resolver publishes an alias path.
+     */
+    name: string;
+    /**
+     * Lexical declaration reached by this binding before alias publication.
+     *
+     * Its semantic identity is retained even when several paths expose it.
+     */
+    declaration: IEvidenceRustDeclaration;
+    /**
+     * Selected file and crate placement owning the exposing module.
+     *
+     * Visibility checks need this module boundary as well as the declaration.
+     */
+    carrier: IEvidenceRustFilePlacement;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Records a file-backed Rust module awaiting selected-source resolution.
+ *
+ * EvidenceRustModuleResolver maps the declaration to an included file or
+ * reports an incomplete crate graph instead of guessing filesystem or
+ * build-script behavior.
+ */
+export interface IEvidenceRustExternalModule {
+    /**
+     * Scanner identity of the `mod` declaration introducing this module.
+     *
+     * Diagnostics refer to this source site when no selected file satisfies it.
+     */
+    declarationId: string;
+    /**
+     * Parent module path in which the child name resolves.
+     *
+     * It distinguishes equal module names declared under separate parents.
+     */
+    modulePath: string[];
+    /**
+     * Child module name from the declaration.
+     *
+     * The resolver combines it with `modulePath` to find the selected source.
+     */
+    name: string;
+    /**
+     * Whether a `#[path]` attribute supplies an explicit file spelling.
+     *
+     * This changes the selected-source lookup and prevents conventional-path
+     * guessing.
+     */
+    pathOverride: boolean;
+}

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

@@ -0,0 +1,67 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceRustDeclaration } from "./IEvidenceRustDeclaration";
+import type { IEvidenceRustDocumentation } from "./IEvidenceRustDocumentation";
+import type { IEvidenceRustExternalModule } from "./IEvidenceRustExternalModule";
+import type { IEvidenceRustImplementation } from "./IEvidenceRustImplementation";
+import type { IEvidenceRustUse } from "./IEvidenceRustUse";
+/**
+ * Holds the node-free result of scanning one selected Rust source file.
+ *
+ * EvidenceRustModuleResolver consumes this record after the Tree-sitter session
+ * closes, using its declarations and relationships to assemble the selected
+ * crate graph.
+ */
+export interface IEvidenceRustFileAnalysis {
+    /**
+     * Selected source file that supplied this extraction.
+     *
+     * Diagnostics and published addresses retain this file's physical and
+     * selected locations rather than relying on transient parser nodes.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Declarations read directly from this file.
+     *
+     * Their module paths remain relative to this file until module placement
+     * assigns them to a crate.
+     */
+    declarations: IEvidenceRustDeclaration[];
+    /**
+     * Documentation records attached while comment positions are still available.
+     *
+     * The resolver may move inner documentation to an externally loaded module.
+     */
+    documentation: IEvidenceRustDocumentation[];
+    /**
+     * Out-of-line module declarations requiring selected-file resolution.
+     *
+     * Inline modules are represented directly in declarations and need no record.
+     */
+    externalModules: IEvidenceRustExternalModule[];
+    /**
+     * Impl blocks whose members require nominal-owner resolution.
+     *
+     * The scanner preserves source paths because imports and module placement can
+     * affect the selected local owner.
+     */
+    implementations: IEvidenceRustImplementation[];
+    /**
+     * Public use declarations expanded into their statically spelled bindings.
+     *
+     * The resolver turns these bindings into exported public paths.
+     */
+    uses: IEvidenceRustUse[];
+    /**
+     * Errors found while scanning forms or attributes in this file.
+     *
+     * These diagnostics join resolver diagnostics in the final inventory.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * Whether scanning established the complete supported declaration population.
+     *
+     * False prevents an unsupported public form from silently shrinking coverage.
+     */
+    complete: boolean;
+}

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

@@ -0,0 +1,37 @@
+import type { IEvidenceRustFileAnalysis } from "./IEvidenceRustFileAnalysis";
+/**
+ * Assigns a selected Rust file to one crate root and module prefix.
+ *
+ * EvidenceRustModuleResolver creates placements before building module records,
+ * so the same scan result can be addressed in the crate namespace and source
+ * files.
+ */
+export interface IEvidenceRustFilePlacement {
+    /**
+     * EvidenceNode-free scan result for the selected file.
+     *
+     * This record owns declarations and diagnostics associated with the
+     * placement.
+     */
+    analysis: IEvidenceRustFileAnalysis;
+    /**
+     * Stable key for the crate root that contains the file.
+     *
+     * Module and unit keys include it to keep identical paths in separate crates
+     * distinct.
+     */
+    rootKey: string;
+    /**
+     * Module segments prepended to declarations scanned from the file.
+     *
+     * An empty prefix identifies a crate root file.
+     */
+    prefix: string[];
+    /**
+     * Declaration ID of the external module that selected this file, when any.
+     *
+     * Omission marks a root file or an inline-module context without an external
+     * declaration to attach.
+     */
+    moduleDeclarationId?: string;
+}