@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -0,0 +1,9 @@
+/**
+ * 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 EvidenceRubyMethodSide = "instance" | "singleton";

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

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

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

@@ -0,0 +1,92 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceRubyConstantPath } from "./IEvidenceRubyConstantPath";
+/**
+ * Provides grammar-level Ruby extraction helpers without public-surface
+ * decisions.
+ *
+ * EvidenceRubyFileScanner uses these functions to recognize statically readable
+ * syntax. Publication, visibility, and reopening policy remain in the scanner
+ * and adapter.
+ */
+export declare namespace EvidenceRubySyntax {
+    /**
+     * 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: EvidenceNode): 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: EvidenceNode): EvidenceNode[];
+    /**
+     * 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: EvidenceNode): 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: EvidenceNode | 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: EvidenceNode[]): 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: EvidenceNode): 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: EvidenceNode | null): IEvidenceRubyConstantPath | 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: EvidenceNode): 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: EvidenceNode): string | undefined;
+    /**
+     * Detects calls that generate a runtime constant instead of a declared
+     * container.
+     *
+     * EvidenceRubyFileScanner reports these forms as incomplete because their
+     * members cannot be derived from the declared source model without executing
+     * Ruby.
+     */
+    function generatedConstant(node: EvidenceNode | null): boolean;
+}

package/lib/adapters/ruby/EvidenceRubySyntax.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceRubySyntax = void 0;
+/**
+ * Provides grammar-level Ruby extraction helpers without public-surface
+ * decisions.
+ *
+ * EvidenceRubyFileScanner uses these functions to recognize statically readable
+ * syntax. Publication, visibility, and reopening policy remain in the scanner
+ * and adapter.
+ */
+var EvidenceRubySyntax;
+(function (EvidenceRubySyntax) {
+    /**
+     * 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;
+    }
+    EvidenceRubySyntax.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 ?? [];
+    }
+    EvidenceRubySyntax.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;
+    }
+    EvidenceRubySyntax.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);
+    }
+    EvidenceRubySyntax.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;
+    }
+    EvidenceRubySyntax.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("");
+    }
+    EvidenceRubySyntax.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],
+            };
+    }
+    EvidenceRubySyntax.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,
+        };
+    }
+    EvidenceRubySyntax.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();
+    }
+    EvidenceRubySyntax.superclass = superclass;
+    /**
+     * Detects calls that generate a runtime constant instead of a declared
+     * container.
+     *
+     * EvidenceRubyFileScanner 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"));
+    }
+    EvidenceRubySyntax.generatedConstant = generatedConstant;
+})(EvidenceRubySyntax || (exports.EvidenceRubySyntax = EvidenceRubySyntax = {}));

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * Represents a statically readable Ruby constant path and root qualification.
+ *
+ * EvidenceRubyFileScanner uses it to distinguish lexical nesting from top-level
+ * constants before reopened declarations and visibility transitions are
+ * reconciled.
+ */
+export interface IEvidenceRubyConstantPath {
+    /**
+     * Whether the source spelling begins at Ruby's top-level constant namespace.
+     *
+     * An absolute path bypasses the current lexical container during resolution.
+     */
+    absolute: boolean;
+    /**
+     * Constant names in source order after any root qualifier.
+     *
+     * The scanner combines these with lexical context only for relative paths.
+     */
+    segments: string[];
+}

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

@@ -0,0 +1,116 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { EvidenceRubyAttributeMode } from "./EvidenceRubyAttributeMode";
+import type { EvidenceRubyContainerKind } from "./EvidenceRubyContainerKind";
+import type { EvidenceRubyDeclarationForm } from "./EvidenceRubyDeclarationForm";
+import type { EvidenceRubyMethodSide } from "./EvidenceRubyMethodSide";
+import type { EvidenceRubyVisibility } from "./EvidenceRubyVisibility";
+/**
+ * Captures one Ruby declaration before reopenings and runtime-name families
+ * reconcile.
+ *
+ * EvidenceRubyAdapter groups compatible records into semantic units after
+ * source-order visibility changes, lexical ownership, and generated attribute
+ * surfaces are known.
+ */
+export interface IEvidenceRubyDeclaration {
+    /**
+     * Stable scanner identity for this declaration occurrence.
+     *
+     * Documentation attachments and materialization maps use it before grouping.
+     */
+    id: string;
+    /**
+     * Source name displayed by the resulting Evidence unit.
+     *
+     * It can differ from `runtimeName` for generated accessors and singleton
+     * members.
+     */
+    name: string;
+    /**
+     * Ruby runtime name used to detect replacement and reopening conflicts.
+     *
+     * Grouping cannot infer overloads because later Ruby definitions replace
+     * earlier ones.
+     */
+    runtimeName: string;
+    /**
+     * Evidence selector family assigned to this declaration.
+     *
+     * It distinguishes types, methods, and property-like constant or attribute
+     * surfaces.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Scanner form that establishes declaration-specific grouping rules.
+     *
+     * Constants, attributes, and methods have different redefinition boundaries.
+     */
+    form: EvidenceRubyDeclarationForm;
+    /**
+     * Semantic path used to group compatible declarations across files and
+     * reopenings.
+     *
+     * It remains separate from the file-qualified public address.
+     */
+    identity: string[];
+    /**
+     * Accessor segments published for this declaration in each selected source
+     * address.
+     *
+     * Method-side conventions remain encoded here rather than changing semantic
+     * identity.
+     */
+    address: string[];
+    /**
+     * Physical source site and content ranges contributing to this declaration.
+     *
+     * Reopened semantic units retain every compatible site for fingerprints and
+     * hosts.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Visibility in effect at this declaration's source position.
+     *
+     * Only public records can publish a group, while conflicts remain
+     * diagnostics.
+     */
+    visibility: EvidenceRubyVisibility;
+    /**
+     * Whether this record defines rather than merely declares a Ruby surface.
+     *
+     * The adapter uses it to identify competing constant and method replacements.
+     */
+    definition: boolean;
+    /**
+     * Enclosing type identity when this declaration has a structural Ruby owner.
+     *
+     * Omission denotes a top-level declaration with no parent unit.
+     */
+    ownerIdentity?: string[];
+    /**
+     * Nominal container form when this record establishes a class or module.
+     *
+     * Compatible reopenings must preserve this kind.
+     */
+    containerKind?: EvidenceRubyContainerKind;
+    /**
+     * Receiver side on which Ruby installs a method or generated accessor.
+     *
+     * It disambiguates instance and singleton APIs below one owner.
+     */
+    side?: EvidenceRubyMethodSide;
+    /**
+     * Reader or writer capability represented by an attribute macro record.
+     *
+     * Omission means this declaration did not arise from an attribute macro.
+     */
+    attributeMode?: EvidenceRubyAttributeMode;
+    /**
+     * Explicit superclass spelling on a class declaration.
+     *
+     * Compatible reopenings may omit it, but conflicting supplied values make
+     * analysis incomplete.
+     */
+    superclass?: string;
+}

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

@@ -0,0 +1,46 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceRubyDocumentationAttachment } from "./IEvidenceRubyDocumentationAttachment";
+/**
+ * Retains one Ruby comment run or annotation-bearing unsupported literal.
+ *
+ * EvidenceRubyAdapter attaches it after reopened declaration groups become
+ * public, keeping tags on invalid positions available for diagnostics rather
+ * than discarding them.
+ */
+export interface IEvidenceRubyDocumentation {
+    /**
+     * Stable identity for the source documentation region.
+     *
+     * It becomes the evidence-host ID after attachment or unsupported-host
+     * creation.
+     */
+    id: string;
+    /**
+     * Original text range occupied by the comment run or literal.
+     *
+     * Annotation ranges exclude this text from associated site fingerprints.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Delimiter rules used to map raw text when scanning did not precompute a
+     * mapping.
+     *
+     * Omission means `mapping` supplies normalized content for tag parsing.
+     */
+    syntax?: IEvidenceCommentSyntax;
+    /**
+     * Precomputed documentation mapping when the carrier needs custom
+     * normalization.
+     *
+     * The adapter uses this instead of syntax to retain original tag coordinates.
+     */
+    mapping?: IEvidenceDocumentation;
+    /**
+     * Declaration sites immediately documented by this carrier.
+     *
+     * Public-group and withdrawal filtering determine the final host membership.
+     */
+    attachments: IEvidenceRubyDocumentationAttachment[];
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Links one Ruby documentation carrier to a declaration site.
+ *
+ * Attachment remains keyed to scanner records until compatible reopenings merge
+ * into one public unit, which can have several physical documentation sites.
+ */
+export interface IEvidenceRubyDocumentationAttachment {
+    /**
+     * Scanner identity of the declaration receiving this comment.
+     *
+     * EvidenceRubyAdapter converts it to a published semantic unit before parsing
+     * tags.
+     */
+    declarationId: string;
+    /**
+     * Physical declaration-site identity shared by co-located accessors.
+     *
+     * Hosts group this site once even when it contributes to multiple units.
+     */
+    siteId: string;
+}

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

@@ -0,0 +1,45 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceRubyDeclaration } from "./IEvidenceRubyDeclaration";
+import type { IEvidenceRubyDocumentation } from "./IEvidenceRubyDocumentation";
+/**
+ * Preserves one Ruby file's serializable extraction after parsing.
+ *
+ * EvidenceRubyAdapter merges all analyses to reconcile reopened declarations,
+ * visibility, documentation attachment, and failures without retaining
+ * Tree-sitter nodes.
+ */
+export interface IEvidenceRubyFileAnalysis {
+    /**
+     * Selected source snapshot represented by this analysis.
+     *
+     * Its addresses define the files through which materialized units are
+     * published.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Lexical declarations awaiting reopening and public-owner reconciliation.
+     *
+     * Multiple entries may collapse into one semantic Ruby identity.
+     */
+    declarations: IEvidenceRubyDeclaration[];
+    /**
+     * Comment carriers and their immediate declaration attachments.
+     *
+     * Attachment is deferred until the destination declaration group is public.
+     */
+    documentation: IEvidenceRubyDocumentation[];
+    /**
+     * Classification failures that make this source population incomplete.
+     *
+     * The final inventory retains them instead of silently omitting uncertain
+     * APIs.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * Whether scanning fully classified this file's declared surface.
+     *
+     * False propagates through the merged inventory even when other files parse.
+     */
+    complete: boolean;
+}

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

@@ -0,0 +1,53 @@
+import type { EvidenceRubyContainerKind } from "./EvidenceRubyContainerKind";
+import type { EvidenceRubyMethodSide } from "./EvidenceRubyMethodSide";
+import type { EvidenceRubyScopeKind } from "./EvidenceRubyScopeKind";
+import type { EvidenceRubyVisibility } from "./EvidenceRubyVisibility";
+/**
+ * Carries mutable lexical state while scanning one Ruby scope.
+ *
+ * EvidenceRubyFileScanner updates this record as visibility and
+ * `module_function` change, so members receive the state in effect at their own
+ * source position.
+ */
+export interface IEvidenceRubyScopeContext {
+    /**
+     * Kind of lexical body that owns declarations scanned through this context.
+     *
+     * It determines which Ruby constructs can introduce members or alter
+     * visibility.
+     */
+    kind: EvidenceRubyScopeKind;
+    /**
+     * Semantic constant path for declarations nested in this scope.
+     *
+     * Reopened bodies with the same path later merge into one identity.
+     */
+    identity: string[];
+    /**
+     * Receiver side assigned to methods declared in the current body.
+     *
+     * It separates instance and singleton method addresses under the same owner.
+     */
+    side: EvidenceRubyMethodSide;
+    /**
+     * Visibility currently inherited by newly scanned declarations.
+     *
+     * Visibility modifiers mutate this value only for following members.
+     */
+    visibility: EvidenceRubyVisibility;
+    /**
+     * Whether module-function mode duplicates eligible instance methods as module
+     * APIs.
+     *
+     * The scanner records both resulting surfaces so later publication can
+     * reconcile them.
+     */
+    moduleFunction: boolean;
+    /**
+     * Nominal container form when this scope belongs to a class or module.
+     *
+     * Omission denotes top-level or singleton contexts that cannot be reopened as
+     * a type.
+     */
+    containerKind?: EvidenceRubyContainerKind;
+}