@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/python/PythonResolutionMode.d.ts

@@ -1,7 +0,0 @@
-/**
- * Selects whether a Python lookup is constrained by a module's public surface.
- *
- * Star imports require public lookup, whereas named imports may resolve a
- * declared module attribute even when that name is not publicly re-exported.
- */
-export type PythonResolutionMode = "public" | "declared";

package/lib/adapters/python/PythonSyntax.d.ts

@@ -1,115 +0,0 @@
-import type { Node } from "web-tree-sitter";
-import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
-/**
- * Provides grammar-specific Python syntax helpers without export decisions.
- *
- * PythonFileScanner uses these helpers to recognize supported declaration and
- * documentation shapes while keeping public-surface policy in the scanner.
- */
-export declare namespace PythonSyntax {
-    /**
-     * Unwraps a decorated definition to its underlying declaration node.
-     *
-     * Callers retain the wrapper separately when its range or decorators affect
-     * documentation attachment and static-versus-instance member classification.
-     */
-    function definition(node: Node): Node;
-    /**
-     * Returns an identifier's source spelling when the node is a simple name.
-     *
-     * Other grammar forms remain unsupported instead of being coerced into a
-     * potentially incorrect declaration or binding name.
-     */
-    function name(node: Node | null): string | undefined;
-    /**
-     * Extracts the leftmost identifier from a Python type-alias declaration.
-     *
-     * The scanner requires this static name before it can create an owned type
-     * unit or a module binding for the alias.
-     */
-    function typeAliasName(node: Node): string | undefined;
-    /**
-     * Returns the simple left-side name of an assignment expression.
-     *
-     * Destructuring and attribute assignments intentionally return no name so the
-     * scanner can distinguish unsupported dynamic surfaces from declarations.
-     */
-    function assignmentName(node: Node): string | undefined;
-    /**
-     * Collects canonical decorator spellings from a decorated declaration wrapper.
-     *
-     * Method scanning uses these spellings to recognize static, class, property,
-     * and cached-property ownership without evaluating arbitrary decorators.
-     */
-    function decoratorNames(wrapper: Node): string[];
-    /**
-     * Returns the first parameter name of a function definition when recoverable.
-     *
-     * Initializer scanning treats this name as the instance receiver for direct
-     * field assignments; missing or complex forms do not establish instance fields.
-     */
-    function parameterName(node: Node): string | undefined;
-    /**
-     * Returns the direct object name of an attribute expression.
-     *
-     * Instance-field extraction combines this with {@link attributeName} to accept
-     * only assignments on the initializer's statically identified receiver.
-     */
-    function attributeObject(node: Node): string | undefined;
-    /**
-     * Returns the direct member name of an attribute expression.
-     *
-     * A non-attribute expression has no eligible member name and remains outside
-     * the scanner's supported direct-receiver assignment form.
-     */
-    function attributeName(node: Node): string | undefined;
-    /**
-     * Builds documentation mapping syntax for a non-interpolated string literal.
-     *
-     * Interpolated strings are omitted because runtime interpolation prevents the
-     * scanner from treating their text as stable Evidence documentation.
-     */
-    function stringSyntax(node: Node): IEvidenceCommentSyntax | undefined;
-    /**
-     * Returns the line-comment syntax used for Python comment documentation.
-     *
-     * The fixed mapping lets adjacent standalone `#` comment runs support Evidence
-     * tags with the same withdrawal behavior as supported docstrings.
-     */
-    function commentSyntax(): IEvidenceCommentSyntax;
-    /**
-     * Resolves a supported literal list or tuple expression to its string members.
-     *
-     * Static `+` composition and parentheses are accepted for `__all__`; any
-     * dynamic value returns undefined so the scanner preserves incompleteness.
-     */
-    function literalSequence(node: Node | null): string[] | undefined;
-    /**
-     * Reads one plain static Python string literal for an export-name sequence.
-     *
-     * Escapes, line breaks, and prefixes other than `u` or `U` are rejected so
-     * the literal value need not be interpreted by executing Python syntax.
-     */
-    function literalString(node: Node): string | undefined;
-    /**
-     * Returns the leading expression node when a suite begins with a docstring.
-     *
-     * Leading comments are skipped, but the first executable statement must be a
-     * supported string expression for attachment to the enclosing declaration.
-     */
-    function docstring(body: Node | null): Node | undefined;
-    /**
-     * Splits a supported docstring expression into its source string literals.
-     *
-     * Bytes and f-string components are excluded because their runtime semantics
-     * cannot supply stable documentation text for Evidence annotations.
-     */
-    function docstringParts(node: Node): Node[] | undefined;
-    /**
-     * Detects a `TypeAlias` annotation on a simple assignment.
-     *
-     * The scanner uses this syntactic marker to classify the assigned declaration
-     * as a type unit while leaving other assignments as properties.
-     */
-    function typeAliasAnnotation(node: Node): boolean;
-}

package/lib/adapters/python/PythonSyntax.js

@@ -1,298 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PythonSyntax = void 0;
-/**
- * Provides grammar-specific Python syntax helpers without export decisions.
- *
- * PythonFileScanner uses these helpers to recognize supported declaration and
- * documentation shapes while keeping public-surface policy in the scanner.
- */
-var PythonSyntax;
-(function (PythonSyntax) {
-    /**
-     * Unwraps a decorated definition to its underlying declaration node.
-     *
-     * Callers retain the wrapper separately when its range or decorators affect
-     * documentation attachment and static-versus-instance member classification.
-     */
-    function definition(node) {
-        return node.type === "decorated_definition"
-            ? (node.childForFieldName("definition") ?? node)
-            : node;
-    }
-    PythonSyntax.definition = definition;
-    /**
-     * Returns an identifier's source spelling when the node is a simple name.
-     *
-     * Other grammar forms remain unsupported instead of being coerced into a
-     * potentially incorrect declaration or binding name.
-     */
-    function name(node) {
-        return node?.type === "identifier" ? node.text : undefined;
-    }
-    PythonSyntax.name = name;
-    /**
-     * Extracts the leftmost identifier from a Python type-alias declaration.
-     *
-     * The scanner requires this static name before it can create an owned type
-     * unit or a module binding for the alias.
-     */
-    function typeAliasName(node) {
-        const left = node.childForFieldName("left");
-        if (left === null)
-            return undefined;
-        return left.descendantsOfType("identifier")[0]?.text;
-    }
-    PythonSyntax.typeAliasName = typeAliasName;
-    /**
-     * Returns the simple left-side name of an assignment expression.
-     *
-     * Destructuring and attribute assignments intentionally return no name so the
-     * scanner can distinguish unsupported dynamic surfaces from declarations.
-     */
-    function assignmentName(node) {
-        return name(node.childForFieldName("left"));
-    }
-    PythonSyntax.assignmentName = assignmentName;
-    /**
-     * Collects canonical decorator spellings from a decorated declaration wrapper.
-     *
-     * Method scanning uses these spellings to recognize static, class, property,
-     * and cached-property ownership without evaluating arbitrary decorators.
-     */
-    function decoratorNames(wrapper) {
-        if (wrapper.type !== "decorated_definition")
-            return [];
-        return wrapper.namedChildren
-            .filter((child) => child.type === "decorator")
-            .flatMap((decorator) => {
-            const expression = decorator.namedChildren[0];
-            const value = qualified(expression);
-            return value === undefined ? [] : [value];
-        });
-    }
-    PythonSyntax.decoratorNames = decoratorNames;
-    /**
-     * Returns the first parameter name of a function definition when recoverable.
-     *
-     * Initializer scanning treats this name as the instance receiver for direct
-     * field assignments; missing or complex forms do not establish instance fields.
-     */
-    function parameterName(node) {
-        const parameters = node.childForFieldName("parameters");
-        if (parameters === null)
-            return undefined;
-        const first = parameters.namedChildren[0];
-        if (first === undefined)
-            return undefined;
-        if (first.type === "identifier")
-            return first.text;
-        return first.descendantsOfType("identifier")[0]?.text;
-    }
-    PythonSyntax.parameterName = parameterName;
-    /**
-     * Returns the direct object name of an attribute expression.
-     *
-     * Instance-field extraction combines this with {@link attributeName} to accept
-     * only assignments on the initializer's statically identified receiver.
-     */
-    function attributeObject(node) {
-        if (node.type !== "attribute")
-            return undefined;
-        return name(node.childForFieldName("object"));
-    }
-    PythonSyntax.attributeObject = attributeObject;
-    /**
-     * Returns the direct member name of an attribute expression.
-     *
-     * A non-attribute expression has no eligible member name and remains outside
-     * the scanner's supported direct-receiver assignment form.
-     */
-    function attributeName(node) {
-        if (node.type !== "attribute")
-            return undefined;
-        return name(node.childForFieldName("attribute"));
-    }
-    PythonSyntax.attributeName = attributeName;
-    /**
-     * Builds documentation mapping syntax for a non-interpolated string literal.
-     *
-     * Interpolated strings are omitted because runtime interpolation prevents the
-     * scanner from treating their text as stable Evidence documentation.
-     */
-    function stringSyntax(node) {
-        if (node.type !== "string" ||
-            node.descendantsOfType("interpolation").length !== 0)
-            return undefined;
-        const opening = node.namedChildren.find((child) => child.type === "string_start")?.text;
-        const closing = node.namedChildren.find((child) => child.type === "string_end")?.text;
-        if (opening === undefined || closing === undefined)
-            return undefined;
-        return {
-            opening,
-            closing,
-            tagBoundaries: true,
-            allowWithdrawal: true,
-        };
-    }
-    PythonSyntax.stringSyntax = stringSyntax;
-    /**
-     * Returns the line-comment syntax used for Python comment documentation.
-     *
-     * The fixed mapping lets adjacent standalone `#` comment runs support Evidence
-     * tags with the same withdrawal behavior as supported docstrings.
-     */
-    function commentSyntax() {
-        return {
-            opening: "#",
-            closing: "",
-            linePrefix: "#",
-            tagBoundaries: true,
-            allowWithdrawal: true,
-        };
-    }
-    PythonSyntax.commentSyntax = commentSyntax;
-    /**
-     * Resolves a supported literal list or tuple expression to its string members.
-     *
-     * Static `+` composition and parentheses are accepted for `__all__`; any
-     * dynamic value returns undefined so the scanner preserves incompleteness.
-     */
-    function literalSequence(node) {
-        if (node === null)
-            return undefined;
-        if (node.type === "parenthesized_expression")
-            return literalSequence(node.namedChildren[0] ?? null);
-        if (node.type === "binary_operator") {
-            if (!node.children.some((child) => child.type === "+"))
-                return undefined;
-            const left = literalSequence(node.childForFieldName("left"));
-            const right = literalSequence(node.childForFieldName("right"));
-            return left === undefined || right === undefined
-                ? undefined
-                : [...left, ...right];
-        }
-        if (node.type !== "list" && node.type !== "tuple")
-            return undefined;
-        const output = [];
-        for (const child of node.namedChildren) {
-            const value = literalString(child);
-            if (value === undefined)
-                return undefined;
-            output.push(value);
-        }
-        return output;
-    }
-    PythonSyntax.literalSequence = literalSequence;
-    /**
-     * Reads one plain static Python string literal for an export-name sequence.
-     *
-     * Escapes, line breaks, and prefixes other than `u` or `U` are rejected so
-     * the literal value need not be interpreted by executing Python syntax.
-     */
-    function literalString(node) {
-        const syntax = stringSyntax(node);
-        if (syntax === undefined)
-            return undefined;
-        const quote = /(?:'''|"""|'|")$/u.exec(syntax.opening)?.[0];
-        if (quote === undefined || syntax.closing !== quote)
-            return undefined;
-        const prefix = syntax.opening.slice(0, -quote.length);
-        if (prefix !== "" && prefix !== "u" && prefix !== "U")
-            return undefined;
-        const value = node.text.slice(syntax.opening.length, node.text.length - syntax.closing.length);
-        return value.includes("\\") || value.includes("\n") || value.includes("\r")
-            ? undefined
-            : value;
-    }
-    PythonSyntax.literalString = literalString;
-    /**
-     * Returns the leading expression node when a suite begins with a docstring.
-     *
-     * Leading comments are skipped, but the first executable statement must be a
-     * supported string expression for attachment to the enclosing declaration.
-     */
-    function docstring(body) {
-        if (body === null)
-            return undefined;
-        const statement = body.namedChildren.find((child) => child.type !== "comment");
-        if (statement?.type !== "expression_statement")
-            return undefined;
-        const value = statement.namedChildren[0];
-        return value !== undefined && docstringParts(value) !== undefined
-            ? value
-            : undefined;
-    }
-    PythonSyntax.docstring = docstring;
-    /**
-     * Splits a supported docstring expression into its source string literals.
-     *
-     * Bytes and f-string components are excluded because their runtime semantics
-     * cannot supply stable documentation text for Evidence annotations.
-     */
-    function docstringParts(node) {
-        const strings = node.type === "string"
-            ? [node]
-            : node.type === "concatenated_string"
-                ? node.namedChildren
-                : undefined;
-        if (strings === undefined ||
-            strings.length === 0 ||
-            strings.some((string) => !docstringLiteral(string)))
-            return undefined;
-        return strings;
-    }
-    PythonSyntax.docstringParts = docstringParts;
-    /**
-     * Detects a `TypeAlias` annotation on a simple assignment.
-     *
-     * The scanner uses this syntactic marker to classify the assigned declaration
-     * as a type unit while leaving other assignments as properties.
-     */
-    function typeAliasAnnotation(node) {
-        const annotation = node.childForFieldName("type")?.text;
-        return (annotation === "TypeAlias" ||
-            (annotation !== undefined && annotation.endsWith(".TypeAlias")));
-    }
-    PythonSyntax.typeAliasAnnotation = typeAliasAnnotation;
-    /**
-     * Serializes a supported identifier, attribute, call, or parenthesized decorator expression.
-     *
-     * Decorator recognition requires only the callable's dotted spelling; other
-     * expression forms remain unclassified rather than being evaluated.
-     */
-    function qualified(node) {
-        if (node === undefined)
-            return undefined;
-        if (node.type === "identifier")
-            return node.text;
-        if (node.type === "attribute") {
-            const object = qualified(node.childForFieldName("object") ?? undefined);
-            const attribute = name(node.childForFieldName("attribute"));
-            return object === undefined || attribute === undefined
-                ? undefined
-                : `${object}.${attribute}`;
-        }
-        if (node.type === "call")
-            return qualified(node.childForFieldName("function") ?? undefined);
-        if (node.type === "parenthesized_expression")
-            return qualified(node.namedChildren[0]);
-        return undefined;
-    }
-    /**
-     * Checks whether a string literal can participate in a static Python docstring.
-     *
-     * Bytes and formatted literals are rejected because they cannot provide stable
-     * source text without runtime evaluation.
-     */
-    function docstringLiteral(node) {
-        const syntax = stringSyntax(node);
-        if (syntax === undefined)
-            return false;
-        const quote = /(?:'''|"""|'|")$/u.exec(syntax.opening)?.[0];
-        if (quote === undefined)
-            return false;
-        const prefix = syntax.opening.slice(0, -quote.length).toLowerCase();
-        return !prefix.includes("b") && !prefix.includes("f");
-    }
-})(PythonSyntax || (exports.PythonSyntax = PythonSyntax = {}));

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

@@ -1,20 +0,0 @@
-/**
- * Represents a statically readable Ruby constant path and root qualification.
- *
- * RubyFileScanner uses it to distinguish lexical nesting from top-level constants
- * before reopened declarations and visibility transitions are reconciled.
- */
-export interface IRubyConstantPath {
-    /**
-     * 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/IRubyDeclaration.d.ts

@@ -1,105 +0,0 @@
-import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
-import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
-import type { RubyAttributeMode } from "./RubyAttributeMode";
-import type { RubyContainerKind } from "./RubyContainerKind";
-import type { RubyDeclarationForm } from "./RubyDeclarationForm";
-import type { RubyMethodSide } from "./RubyMethodSide";
-import type { RubyVisibility } from "./RubyVisibility";
-/**
- * Captures one Ruby declaration before reopenings and runtime-name families reconcile.
- *
- * RubyAdapter groups compatible records into semantic units after source-order
- * visibility changes, lexical ownership, and generated attribute surfaces are known.
- */
-export interface IRubyDeclaration {
-    /**
-     * 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: RubyDeclarationForm;
-    /**
-     * 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: RubyVisibility;
-    /**
-     * 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?: RubyContainerKind;
-    /**
-     * Receiver side on which Ruby installs a method or generated accessor.
-     *
-     * It disambiguates instance and singleton APIs below one owner.
-     */
-    side?: RubyMethodSide;
-    /**
-     * Reader or writer capability represented by an attribute macro record.
-     *
-     * Omission means this declaration did not arise from an attribute macro.
-     */
-    attributeMode?: RubyAttributeMode;
-    /**
-     * 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/IRubyDocumentation.d.ts

@@ -1,42 +0,0 @@
-import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
-import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-import type { IRubyDocumentationAttachment } from "./IRubyDocumentationAttachment";
-/**
- * Retains one Ruby comment run or annotation-bearing unsupported literal.
- *
- * RubyAdapter attaches it after reopened declaration groups become public, keeping
- * tags on invalid positions available for diagnostics rather than discarding them.
- */
-export interface IRubyDocumentation {
-    /**
-     * 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: IRubyDocumentationAttachment[];
-}

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

@@ -1,20 +0,0 @@
-/**
- * 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 IRubyDocumentationAttachment {
-    /**
-     * Scanner identity of the declaration receiving this comment.
-     *
-     * RubyAdapter 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/IRubyFileAnalysis.d.ts

@@ -1,42 +0,0 @@
-import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { IRubyDeclaration } from "./IRubyDeclaration";
-import type { IRubyDocumentation } from "./IRubyDocumentation";
-/**
- * Preserves one Ruby file's serializable extraction after parsing.
- *
- * RubyAdapter merges all analyses to reconcile reopened declarations, visibility,
- * documentation attachment, and failures without retaining Tree-sitter nodes.
- */
-export interface IRubyFileAnalysis {
-    /**
-     * 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: IRubyDeclaration[];
-    /**
-     * Comment carriers and their immediate declaration attachments.
-     *
-     * Attachment is deferred until the destination declaration group is public.
-     */
-    documentation: IRubyDocumentation[];
-    /**
-     * 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;
-}