@wrtnlabs/evidence 0.0.0

package/lib/adapters/ruby/RubyMethodSide.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Identifies the receiver side on which Ruby installs a method or generated attribute.
+ *
+ * Scanner contexts retain this distinction so instance and singleton members of
+ * the same container receive separate semantic identities and public addresses.
+ */
+export type RubyMethodSide = "instance" | "singleton";

package/lib/adapters/ruby/RubyMethodSide.js

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

package/lib/adapters/ruby/RubyScopeKind.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Classifies lexical Ruby scopes that can contain supported declarations.
+ *
+ * RubyFileScanner uses the current scope to decide which directives are valid and
+ * how declarations inherit container identity, receiver side, and visibility.
+ */
+export type RubyScopeKind = "class" | "module" | "singleton" | "top";

package/lib/adapters/ruby/RubyScopeKind.js

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

package/lib/adapters/ruby/RubySyntax.d.ts

@@ -0,0 +1,81 @@
+import type { Node } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IRubyConstantPath } from "./IRubyConstantPath";
+/**
+ * Provides grammar-level Ruby extraction helpers without public-surface decisions.
+ *
+ * RubyFileScanner uses these functions to recognize statically readable syntax.
+ * Publication, visibility, and reopening policy remain in the scanner and adapter.
+ */
+export declare namespace RubySyntax {
+    /**
+     * Reads the bare method name from a Ruby call node.
+     *
+     * Directive recognition uses this result only for ordinary identifier calls;
+     * other node forms remain unsupported rather than being guessed from text.
+     */
+    function callName(node: Node): string | undefined;
+    /**
+     * Returns the direct named arguments of a Ruby call node.
+     *
+     * Attribute, visibility, and alias directives inspect this collection before
+     * accepting literal arguments; non-call nodes deliberately produce no arguments.
+     */
+    function callArguments(node: Node): Node[];
+    /**
+     * States whether a Ruby call has an explicit receiver.
+     *
+     * The scanner rejects or classifies directives differently when a receiver
+     * changes their lexical effect, so this check does not interpret the receiver.
+     */
+    function hasReceiver(node: Node): boolean;
+    /**
+     * Reads a statically supported Ruby method spelling from a syntax node.
+     *
+     * Direct identifiers, constants, operators, and setters retain their source
+     * text; literal symbols and strings are delegated to literalName.
+     */
+    function methodName(node: Node | null): string | undefined;
+    /**
+     * Reads a flattened list of statically literal Ruby names.
+     *
+     * Nested arrays are expanded for directives that accept name lists. One dynamic
+     * element makes the whole result undefined so callers can report uncertainty.
+     */
+    function literalNames(nodes: Node[]): string[] | undefined;
+    /**
+     * Reads one interpolation-free Ruby symbol or string as a literal name.
+     *
+     * Escape sequences and interpolation make runtime content uncertain, so callers
+     * receive undefined instead of an approximated declaration name.
+     */
+    function literalName(node: Node): string | undefined;
+    /**
+     * Converts a supported Ruby constant expression into root-qualified path segments.
+     *
+     * The scanner uses absolute to distinguish `::Name` from lexical lookup while
+     * resolving containers, superclass paths, and generated-constant receivers.
+     */
+    function constantPath(node: Node | null): IRubyConstantPath | undefined;
+    /**
+     * Identifies the normalization rules for a supported Ruby documentation comment.
+     *
+     * Line RDoc and complete embedded RDoc blocks retain tag boundaries and permit
+     * withdrawals. Other comment forms return undefined and cannot become hosts.
+     */
+    function commentSyntax(node: Node): IEvidenceCommentSyntax | undefined;
+    /**
+     * Normalizes the explicit superclass spelling on a Ruby class declaration.
+     *
+     * Reopening reconciliation compares this normalized text only when a superclass
+     * is supplied, preserving the distinction between omission and conflict.
+     */
+    function superclass(node: Node): string | undefined;
+    /**
+     * Detects calls that generate a runtime constant instead of a declared container.
+     *
+     * RubyFileScanner reports these forms as incomplete because their members cannot
+     * be derived from the declared source model without executing Ruby.
+     */
+    function generatedConstant(node: Node | null): boolean;
+}

package/lib/adapters/ruby/RubySyntax.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RubySyntax = void 0;
+/**
+ * Provides grammar-level Ruby extraction helpers without public-surface decisions.
+ *
+ * RubyFileScanner uses these functions to recognize statically readable syntax.
+ * Publication, visibility, and reopening policy remain in the scanner and adapter.
+ */
+var RubySyntax;
+(function (RubySyntax) {
+    /**
+     * Reads the bare method name from a Ruby call node.
+     *
+     * Directive recognition uses this result only for ordinary identifier calls;
+     * other node forms remain unsupported rather than being guessed from text.
+     */
+    function callName(node) {
+        if (node.type !== "call")
+            return undefined;
+        const method = node.childForFieldName("method");
+        return method?.type === "identifier" ? method.text : undefined;
+    }
+    RubySyntax.callName = callName;
+    /**
+     * Returns the direct named arguments of a Ruby call node.
+     *
+     * Attribute, visibility, and alias directives inspect this collection before
+     * accepting literal arguments; non-call nodes deliberately produce no arguments.
+     */
+    function callArguments(node) {
+        if (node.type !== "call")
+            return [];
+        return node.childForFieldName("arguments")?.namedChildren ?? [];
+    }
+    RubySyntax.callArguments = callArguments;
+    /**
+     * States whether a Ruby call has an explicit receiver.
+     *
+     * The scanner rejects or classifies directives differently when a receiver
+     * changes their lexical effect, so this check does not interpret the receiver.
+     */
+    function hasReceiver(node) {
+        return node.type === "call" && node.childForFieldName("receiver") !== null;
+    }
+    RubySyntax.hasReceiver = hasReceiver;
+    /**
+     * Reads a statically supported Ruby method spelling from a syntax node.
+     *
+     * Direct identifiers, constants, operators, and setters retain their source
+     * text; literal symbols and strings are delegated to literalName.
+     */
+    function methodName(node) {
+        if (node === null)
+            return undefined;
+        if (node.type === "identifier" ||
+            node.type === "constant" ||
+            node.type === "operator" ||
+            node.type === "setter")
+            return node.text;
+        return literalName(node);
+    }
+    RubySyntax.methodName = methodName;
+    /**
+     * Reads a flattened list of statically literal Ruby names.
+     *
+     * Nested arrays are expanded for directives that accept name lists. One dynamic
+     * element makes the whole result undefined so callers can report uncertainty.
+     */
+    function literalNames(nodes) {
+        const output = [];
+        for (const node of nodes) {
+            if (node.type === "array") {
+                const nested = literalNames(node.namedChildren);
+                if (nested === undefined)
+                    return undefined;
+                output.push(...nested);
+                continue;
+            }
+            const name = literalName(node);
+            if (name === undefined)
+                return undefined;
+            output.push(name);
+        }
+        return output;
+    }
+    RubySyntax.literalNames = literalNames;
+    /**
+     * Reads one interpolation-free Ruby symbol or string as a literal name.
+     *
+     * Escape sequences and interpolation make runtime content uncertain, so callers
+     * receive undefined instead of an approximated declaration name.
+     */
+    function literalName(node) {
+        if (node.type === "simple_symbol")
+            return node.text.slice(1);
+        if (node.type !== "string" && node.type !== "delimited_symbol")
+            return undefined;
+        if (node.descendantsOfType("interpolation").length !== 0 ||
+            node.descendantsOfType("escape_sequence").length !== 0)
+            return undefined;
+        return node.namedChildren
+            .filter((child) => child.type === "string_content")
+            .map((child) => child.text)
+            .join("");
+    }
+    RubySyntax.literalName = literalName;
+    /**
+     * Converts a supported Ruby constant expression into root-qualified path segments.
+     *
+     * The scanner uses absolute to distinguish `::Name` from lexical lookup while
+     * resolving containers, superclass paths, and generated-constant receivers.
+     */
+    function constantPath(node) {
+        if (node === null)
+            return undefined;
+        if (node.type === "constant")
+            return { absolute: false, segments: [node.text] };
+        if (node.type !== "scope_resolution")
+            return undefined;
+        const name = node.childForFieldName("name");
+        if (name?.type !== "constant")
+            return undefined;
+        const scope = node.childForFieldName("scope");
+        if (scope === null)
+            return node.text.startsWith("::")
+                ? { absolute: true, segments: [name.text] }
+                : undefined;
+        const parent = constantPath(scope);
+        return parent === undefined
+            ? undefined
+            : {
+                absolute: parent.absolute,
+                segments: [...parent.segments, name.text],
+            };
+    }
+    RubySyntax.constantPath = constantPath;
+    /**
+     * Identifies the normalization rules for a supported Ruby documentation comment.
+     *
+     * Line RDoc and complete embedded RDoc blocks retain tag boundaries and permit
+     * withdrawals. Other comment forms return undefined and cannot become hosts.
+     */
+    function commentSyntax(node) {
+        if (node.type !== "comment")
+            return undefined;
+        if (node.text.startsWith("#"))
+            return {
+                opening: "#",
+                closing: "",
+                linePrefix: "#",
+                tagBoundaries: true,
+                allowWithdrawal: true,
+            };
+        if (!node.text.startsWith("=begin"))
+            return undefined;
+        const openingEnd = node.text.indexOf("\n");
+        const closingStart = node.text.lastIndexOf("=end");
+        if (openingEnd < 0 || closingStart <= openingEnd)
+            return undefined;
+        return {
+            opening: node.text.slice(0, openingEnd + 1),
+            closing: node.text.slice(closingStart),
+            tagBoundaries: true,
+            allowWithdrawal: true,
+        };
+    }
+    RubySyntax.commentSyntax = commentSyntax;
+    /**
+     * Normalizes the explicit superclass spelling on a Ruby class declaration.
+     *
+     * Reopening reconciliation compares this normalized text only when a superclass
+     * is supplied, preserving the distinction between omission and conflict.
+     */
+    function superclass(node) {
+        const superclass = node.childForFieldName("superclass");
+        if (superclass === null)
+            return undefined;
+        return superclass.text.replace(/^\s*</u, "").replace(/\s+/gu, " ").trim();
+    }
+    RubySyntax.superclass = superclass;
+    /**
+     * Detects calls that generate a runtime constant instead of a declared container.
+     *
+     * RubyFileScanner reports these forms as incomplete because their members cannot
+     * be derived from the declared source model without executing Ruby.
+     */
+    function generatedConstant(node) {
+        if (node?.type !== "call")
+            return false;
+        const method = callName(node);
+        const receiver = node.childForFieldName("receiver");
+        const path = constantPath(receiver);
+        if (path === undefined)
+            return false;
+        const owner = path.segments.join("::");
+        return ((method === "new" &&
+            (owner === "Class" || owner === "Module" || owner === "Struct")) ||
+            (method === "define" && owner === "Data"));
+    }
+    RubySyntax.generatedConstant = generatedConstant;
+})(RubySyntax || (exports.RubySyntax = RubySyntax = {}));

package/lib/adapters/ruby/RubyVisibility.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Represents Ruby method or constant visibility that the scanner can establish statically.
+ *
+ * RubyFileScanner updates it in source order, and RubyAdapter publishes only
+ * public records while retaining unsupported visibility changes as diagnostics.
+ */
+export type RubyVisibility = "private" | "protected" | "public";

package/lib/adapters/ruby/RubyVisibility.js

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

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

@@ -0,0 +1,15 @@
+import { RustAdapter } from "./RustAdapter";
+/**
+ * Extracts selected Rust crate modules, public re-exports, and local implementation members.
+ *
+ * Module placement and use resolution establish public paths before documentation
+ * is materialized. Outer or inner documentation and supported static doc attributes
+ * retain their physical attachment. Trait implementation paths carry an explicit
+ * literal implementation segment so different owners are not merged by method name.
+ *
+ * Cargo feature evaluation, macro expansion, custom module paths, and ownership
+ * of external types are outside the adapter boundary. Generated declarations
+ * must be present in selected source rather than inferred by executing a build.
+ */
+export declare class EvidenceRustAdapter extends RustAdapter {
+}

package/lib/adapters/rust/EvidenceRustAdapter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceRustAdapter = void 0;
+const RustAdapter_1 = require("./RustAdapter");
+/**
+ * Extracts selected Rust crate modules, public re-exports, and local implementation members.
+ *
+ * Module placement and use resolution establish public paths before documentation
+ * is materialized. Outer or inner documentation and supported static doc attributes
+ * retain their physical attachment. Trait implementation paths carry an explicit
+ * literal implementation segment so different owners are not merged by method name.
+ *
+ * Cargo feature evaluation, macro expansion, custom module paths, and ownership
+ * of external types are outside the adapter boundary. Generated declarations
+ * must be present in selected source rather than inferred by executing a build.
+ */
+class EvidenceRustAdapter extends RustAdapter_1.RustAdapter {
+}
+exports.EvidenceRustAdapter = EvidenceRustAdapter;

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

@@ -0,0 +1,72 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { RustDeclarationForm } from "./RustDeclarationForm";
+import type { RustVisibility } from "./RustVisibility";
+/**
+ * Captures one Rust declaration before module reachability and impl ownership resolve.
+ *
+ * RustModuleResolver combines this lexical record with the selected crate graph;
+ * scanners do not assume that a visible spelling is externally reachable.
+ */
+export interface IRustDeclaration {
+    /**
+     * 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: RustDeclarationForm;
+    /**
+     * Lexical visibility controlling whether a use can publish this item.
+     *
+     * Its scope is evaluated at module boundaries rather than from the declaration alone.
+     */
+    visibility: RustVisibility;
+    /**
+     * 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/IRustDeclaration.js

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

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

@@ -0,0 +1,41 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IRustDocumentationAttachment } from "./IRustDocumentationAttachment";
+/**
+ * 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 IRustDocumentation {
+    /**
+     * 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: IRustDocumentationAttachment[];
+    /**
+     * 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/IRustDocumentation.js

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

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

@@ -0,0 +1,20 @@
+/**
+ * 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 IRustDocumentationAttachment {
+    /**
+     * 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/IRustDocumentationAttachment.js

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

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

@@ -0,0 +1,28 @@
+import type { IRustDeclaration } from "./IRustDeclaration";
+import type { IRustFilePlacement } from "./IRustFilePlacement";
+/**
+ * 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 IRustExportRecord {
+    /**
+     * 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: IRustDeclaration;
+    /**
+     * Selected file and crate placement owning the exposing module.
+     *
+     * Visibility checks need this module boundary as well as the declaration.
+     */
+    carrier: IRustFilePlacement;
+}

package/lib/adapters/rust/IRustExportRecord.js

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

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

@@ -0,0 +1,32 @@
+/**
+ * Records a file-backed Rust module awaiting selected-source resolution.
+ *
+ * RustModuleResolver maps the declaration to an included file or reports an
+ * incomplete crate graph instead of guessing filesystem or build-script behavior.
+ */
+export interface IRustExternalModule {
+    /**
+     * 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/IRustExternalModule.js

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

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

@@ -0,0 +1,66 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IRustDeclaration } from "./IRustDeclaration";
+import type { IRustDocumentation } from "./IRustDocumentation";
+import type { IRustExternalModule } from "./IRustExternalModule";
+import type { IRustImplementation } from "./IRustImplementation";
+import type { IRustUse } from "./IRustUse";
+/**
+ * Holds the node-free result of scanning one selected Rust source file.
+ *
+ * RustModuleResolver consumes this record after the Tree-sitter session closes,
+ * using its declarations and relationships to assemble the selected crate graph.
+ */
+export interface IRustFileAnalysis {
+    /**
+     * 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: IRustDeclaration[];
+    /**
+     * Documentation records attached while comment positions are still available.
+     *
+     * The resolver may move inner documentation to an externally loaded module.
+     */
+    documentation: IRustDocumentation[];
+    /**
+     * Out-of-line module declarations requiring selected-file resolution.
+     *
+     * Inline modules are represented directly in declarations and need no record.
+     */
+    externalModules: IRustExternalModule[];
+    /**
+     * 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: IRustImplementation[];
+    /**
+     * Public use declarations expanded into their statically spelled bindings.
+     *
+     * The resolver turns these bindings into exported public paths.
+     */
+    uses: IRustUse[];
+    /**
+     * 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/IRustFileAnalysis.js

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