@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -0,0 +1,7 @@
+/**
+ * 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 EvidencePythonResolutionMode = "public" | "declared";

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

@@ -0,0 +1,119 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+/**
+ * Provides grammar-specific Python syntax helpers without export decisions.
+ *
+ * EvidencePythonFileScanner uses these helpers to recognize supported
+ * declaration and documentation shapes while keeping public-surface policy in
+ * the scanner.
+ */
+export declare namespace EvidencePythonSyntax {
+    /**
+     * 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: EvidenceNode): EvidenceNode;
+    /**
+     * 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: EvidenceNode | 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: EvidenceNode): 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: EvidenceNode): 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: EvidenceNode): 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: EvidenceNode): 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: EvidenceNode): 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: EvidenceNode): 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: EvidenceNode): 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: EvidenceNode | 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: EvidenceNode): 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: EvidenceNode | null): EvidenceNode | 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: EvidenceNode): EvidenceNode[] | 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: EvidenceNode): boolean;
+}

package/lib/adapters/python/EvidencePythonSyntax.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidencePythonSyntax = void 0;
+/**
+ * Provides grammar-specific Python syntax helpers without export decisions.
+ *
+ * EvidencePythonFileScanner uses these helpers to recognize supported
+ * declaration and documentation shapes while keeping public-surface policy in
+ * the scanner.
+ */
+var EvidencePythonSyntax;
+(function (EvidencePythonSyntax) {
+    /**
+     * 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;
+    }
+    EvidencePythonSyntax.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;
+    }
+    EvidencePythonSyntax.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;
+    }
+    EvidencePythonSyntax.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"));
+    }
+    EvidencePythonSyntax.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];
+        });
+    }
+    EvidencePythonSyntax.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;
+    }
+    EvidencePythonSyntax.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"));
+    }
+    EvidencePythonSyntax.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"));
+    }
+    EvidencePythonSyntax.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,
+        };
+    }
+    EvidencePythonSyntax.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,
+        };
+    }
+    EvidencePythonSyntax.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;
+    }
+    EvidencePythonSyntax.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;
+    }
+    EvidencePythonSyntax.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;
+    }
+    EvidencePythonSyntax.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;
+    }
+    EvidencePythonSyntax.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")));
+    }
+    EvidencePythonSyntax.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");
+    }
+})(EvidencePythonSyntax || (exports.EvidencePythonSyntax = EvidencePythonSyntax = {}));

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

@@ -0,0 +1,24 @@
+import type { EvidencePythonAllState } from "./EvidencePythonAllState";
+/**
+ * Records the statically known portion of a module's `__all__` declaration.
+ *
+ * EvidencePythonExportResolver uses this state to choose between explicit
+ * exports and Python's underscore convention. Dynamic mutation stays incomplete
+ * because executing module code would make coverage depend on runtime state.
+ */
+export interface IEvidencePythonAll {
+    /**
+     * Whether `__all__` is absent, fully static, or changed dynamically.
+     *
+     * A dynamic state suppresses inference from arbitrary runtime mutations while
+     * allowing the scanner to retain the failure diagnostic.
+     */
+    state: EvidencePythonAllState;
+    /**
+     * Export names recovered from supported literal assignment and concatenation.
+     *
+     * The array preserves declaration order; the resolver later converts it to a
+     * set when it combines explicit exports with imported bindings.
+     */
+    names: string[];
+}

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

@@ -0,0 +1,53 @@
+import type { EvidencePythonBindingKind } from "./EvidencePythonBindingKind";
+/**
+ * Describes one source-ordered module binding used for static export
+ * resolution.
+ *
+ * The resolver selects the latest compatible binding for a name and follows
+ * imports without executing Python. Unsupported or ambiguous paths become
+ * diagnostics rather than silently reducing the public population.
+ */
+export interface IEvidencePythonBinding {
+    /**
+     * Binding form that determines how the resolver follows this entry.
+     *
+     * Local bindings point at scanned declaration roots; import forms require a
+     * source-snapshot module target.
+     */
+    kind: EvidencePythonBindingKind;
+    /**
+     * Source-order key for Python's later-binding-wins behavior.
+     *
+     * It is derived from the statement position with a local tie-breaker for
+     * entries in the same import statement.
+     */
+    order: number;
+    /**
+     * Name introduced in the containing module namespace.
+     *
+     * Omission represents an unusable or incomplete binding and prevents it from
+     * being selected as a public export.
+     */
+    localName?: string;
+    /**
+     * Declaration root selected by a local binding.
+     *
+     * Imports omit this field because their target must be resolved against
+     * another module before a declaration can be materialized.
+     */
+    root?: string;
+    /**
+     * Name requested from an imported module by a named import.
+     *
+     * Namespace and star imports omit it: their member name comes from the
+     * subsequent attribute lookup or the requesting public name.
+     */
+    importedName?: string;
+    /**
+     * Static absolute or relative module spelling from the import statement.
+     *
+     * Omission keeps an incomplete binding from resolving outside the scanned
+     * source snapshot.
+     */
+    specifier?: string;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Carries the structural ownership needed while scanning one Python class body.
+ *
+ * Nested functions and properties inherit these segments to keep their unit IDs
+ * stable, while exported addresses can still distinguish a class member from an
+ * instance member through the suffix selected by the scanner.
+ */
+export interface IEvidencePythonClassContext {
+    /**
+     * Full semantic path used to construct child unit identities.
+     *
+     * Every element names one enclosing declaration, in source nesting order.
+     */
+    identity: string[];
+    /**
+     * Public-address segments preceding a member declared in this class.
+     *
+     * The scanner appends a member's own segments without using this path as its
+     * semantic identity, because aliases may publish that identity elsewhere.
+     */
+    suffix: string[];
+    /**
+     * Module-level root binding under which this class is declared.
+     *
+     * Export resolution associates the root with a local binding before it emits
+     * public file-qualified addresses.
+     */
+    root: string;
+    /**
+     * Unit ID of the enclosing class declaration.
+     *
+     * Members use this parent so ancestor withdrawal directives hide the complete
+     * class surface during documentation materialization.
+     */
+    parentId: string;
+}

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

@@ -0,0 +1,47 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidencePythonDocumentationAttachment } from "./IEvidencePythonDocumentationAttachment";
+/**
+ * Retains one Python docstring or adjacent comment run after parsing.
+ *
+ * The scanner keeps source coordinates and either a precomputed mapping or the
+ * syntax needed to derive one. EvidencePythonAdapter attaches the text only
+ * after it knows which declarations are part of the public export surface.
+ */
+export interface IEvidencePythonDocumentation {
+    /**
+     * Stable identifier for this text region within its source file.
+     *
+     * It becomes the evidence-host ID when the text is supported and attached.
+     */
+    id: string;
+    /**
+     * Byte and coordinate range occupied by the original documentation text.
+     *
+     * Annotation ranges exclude this source slice from a unit fingerprint when it
+     * contains Evidence directives.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Delimiter rules for mapping a raw docstring or comment run on demand.
+     *
+     * Omission means `mapping` already carries the normalized documentation;
+     * neither form may be absent when the adapter parses evidence tags.
+     */
+    syntax?: IEvidenceCommentSyntax;
+    /**
+     * Normalized documentation text when scanning already established its shape.
+     *
+     * The adapter clones this mapping before tag parsing because attachment and
+     * withdrawal phases must not mutate scanner-owned analysis data.
+     */
+    mapping?: IEvidenceDocumentation;
+    /**
+     * Declaration positions and candidate units that this text can document.
+     *
+     * One text region can attach to several accessors at one position; export and
+     * withdrawal filtering determine its final visible host membership.
+     */
+    attachments: IEvidencePythonDocumentationAttachment[];
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Connects one parsed Python documentation region to a declaration position.
+ *
+ * Scanning retains this compact relationship after its Tree-sitter session
+ * closes. EvidencePythonAdapter later filters it by public reachability before
+ * creating evidence hosts, so a private declaration's docstring cannot document
+ * an exported unit by accident.
+ */
+export interface IEvidencePythonDocumentationAttachment {
+    /**
+     * Scanner-local identity of the declaration position that owns this text.
+     *
+     * Hosts use the same identity to avoid publishing a second undocumented host
+     * for a declaration that already has an attached docstring or comment run.
+     */
+    positionId: string;
+    /**
+     * Stable declaration-site identity shared by every unit at this position.
+     *
+     * A property getter and setter may have distinct units but one source site;
+     * the host records that common site once.
+     */
+    siteId: string;
+    /**
+     * Candidate unit receiving directives parsed from this documentation.
+     *
+     * The adapter discards this attachment unless export resolution publishes the
+     * unit, preserving Python's public-surface boundary.
+     */
+    unitId: string;
+}