@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -1,93 +0,0 @@
-import type { Node } from "web-tree-sitter";
-import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
-import type { RustVisibility } from "./RustVisibility";
-/**
- * Provides grammar-level Rust extraction helpers for names, paths, attributes, and documentation.
- *
- * RustFileScanner uses these functions to retain syntax facts. RustModuleResolver
- * later decides crate reachability and public ownership from the scanner records.
- */
-export declare namespace RustSyntax {
-    /**
-     * Reads a supported Rust identifier spelling from a grammar node.
-     *
-     * Scanners use it for declaration and member names; unsupported syntax returns
-     * undefined so extraction can preserve uncertainty instead of inventing a name.
-     */
-    function name(node: Node | null): string | undefined;
-    /**
-     * Classifies the visibility modifier written on a Rust declaration.
-     *
-     * Bare `pub` is externally public, scoped forms are restricted, and omitted
-     * modifiers are private. Module resolution evaluates the resulting boundary.
-     */
-    function visibility(node: Node): RustVisibility;
-    /**
-     * Reads a statically supported Rust path as ordered segments.
-     *
-     * Generic wrappers are unwrapped while `crate`, `self`, and `super` remain
-     * literal segments for RustModuleResolver to interpret in its current module.
-     */
-    function path(node: Node | null): string[] | undefined;
-    /**
-     * Collects declared type-parameter names from a Rust item.
-     *
-     * Impl ownership resolution uses these names to distinguish local generic
-     * parameters from paths that must resolve to selected nominal declarations.
-     */
-    function typeParameters(node: Node): string[];
-    /**
-     * Collects outer attributes and outer documentation immediately preceding an item.
-     *
-     * Ordinary comments are skipped because Rust treats them as whitespace. The
-     * returned source order lets scanners attach documentation and inspect attributes.
-     */
-    function attributes(node: Node): Node[];
-    /**
-     * States whether a comment is ordinary Rust whitespace rather than documentation.
-     *
-     * Attribute collection skips these comments without treating them as evidence
-     * carriers or allowing them to interrupt a valid outer-attribute sequence.
-     */
-    function ordinaryComment(node: Node): boolean;
-    /**
-     * Reads the qualified name from a Rust attribute or its wrapper item.
-     *
-     * Scanner attribute policy uses the name to recognize documentation and report
-     * expansion risks; unsupported attribute shapes return undefined.
-     */
-    function attributeName(node: Node): string | undefined;
-    /**
-     * Returns the value expression of a Rust attribute or its wrapper item.
-     *
-     * Documentation-attribute handling validates this node as a supported static
-     * string before it creates a carrier; absent values return null.
-     */
-    function attributeValue(node: Node): Node | null;
-    /**
-     * States whether a Rust comment uses the outer documentation form.
-     *
-     * The scanner may attach only these comment carriers to following item sites.
-     */
-    function outerDocumentation(node: Node): boolean;
-    /**
-     * States whether a Rust comment uses the inner documentation form.
-     *
-     * Inner carriers document their containing module instead of the following item.
-     */
-    function innerDocumentation(node: Node): boolean;
-    /**
-     * Supplies delimiter rules for a Rust comment carrier.
-     *
-     * RustFileScanner uses the returned syntax to map text and preserve tag
-     * coordinates for line, block, ordinary, and documentation comment forms.
-     */
-    function comment(node: Node): IEvidenceCommentSyntax;
-    /**
-     * Supplies delimiter rules for a supported Rust string literal.
-     *
-     * Annotation scanning uses this result for ordinary and raw strings, whose
-     * contents can report unsupported tags but cannot authorize withdrawals.
-     */
-    function string(node: Node): IEvidenceCommentSyntax | undefined;
-}

package/lib/adapters/rust/RustSyntax.js

@@ -1,244 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RustSyntax = void 0;
-/**
- * Provides grammar-level Rust extraction helpers for names, paths, attributes, and documentation.
- *
- * RustFileScanner uses these functions to retain syntax facts. RustModuleResolver
- * later decides crate reachability and public ownership from the scanner records.
- */
-var RustSyntax;
-(function (RustSyntax) {
-    /**
-     * Reads a supported Rust identifier spelling from a grammar node.
-     *
-     * Scanners use it for declaration and member names; unsupported syntax returns
-     * undefined so extraction can preserve uncertainty instead of inventing a name.
-     */
-    function name(node) {
-        return node !== null &&
-            (node.type === "identifier" ||
-                node.type === "field_identifier" ||
-                node.type === "type_identifier")
-            ? node.text
-            : undefined;
-    }
-    RustSyntax.name = name;
-    /**
-     * Classifies the visibility modifier written on a Rust declaration.
-     *
-     * Bare `pub` is externally public, scoped forms are restricted, and omitted
-     * modifiers are private. Module resolution evaluates the resulting boundary.
-     */
-    function visibility(node) {
-        const modifier = node.namedChildren.find((child) => child.type === "visibility_modifier");
-        if (modifier === undefined)
-            return "private";
-        return modifier.text.trim() === "pub" ? "public" : "restricted";
-    }
-    RustSyntax.visibility = visibility;
-    /**
-     * Reads a statically supported Rust path as ordered segments.
-     *
-     * Generic wrappers are unwrapped while `crate`, `self`, and `super` remain
-     * literal segments for RustModuleResolver to interpret in its current module.
-     */
-    function path(node) {
-        if (node === null)
-            return undefined;
-        const direct = name(node);
-        if (direct !== undefined)
-            return [direct];
-        if (node.type === "crate" || node.type === "self" || node.type === "super")
-            return [node.text];
-        if (node.type === "scoped_identifier" ||
-            node.type === "scoped_type_identifier") {
-            const prefix = path(node.childForFieldName("path"));
-            const suffix = name(node.childForFieldName("name"));
-            return prefix === undefined || suffix === undefined
-                ? undefined
-                : [...prefix, suffix];
-        }
-        if (node.type === "generic_type")
-            return path(node.childForFieldName("type"));
-        return undefined;
-    }
-    RustSyntax.path = path;
-    /**
-     * Collects declared type-parameter names from a Rust item.
-     *
-     * Impl ownership resolution uses these names to distinguish local generic
-     * parameters from paths that must resolve to selected nominal declarations.
-     */
-    function typeParameters(node) {
-        const parameters = node.childForFieldName("type_parameters");
-        if (parameters === null)
-            return [];
-        return parameters
-            .descendantsOfType("type_parameter")
-            .flatMap((parameter) => {
-            const declared = name(parameter.childForFieldName("name"));
-            return declared === undefined ? [] : [declared];
-        });
-    }
-    RustSyntax.typeParameters = typeParameters;
-    /**
-     * Collects outer attributes and outer documentation immediately preceding an item.
-     *
-     * Ordinary comments are skipped because Rust treats them as whitespace. The
-     * returned source order lets scanners attach documentation and inspect attributes.
-     */
-    function attributes(node) {
-        const output = [];
-        let previous = node.previousNamedSibling;
-        while (previous !== null &&
-            (previous.type === "attribute_item" ||
-                isOuterDocumentation(previous) ||
-                ordinaryComment(previous))) {
-            if (!ordinaryComment(previous))
-                output.push(previous);
-            previous = previous.previousNamedSibling;
-        }
-        return output.reverse();
-    }
-    RustSyntax.attributes = attributes;
-    /**
-     * States whether a comment is ordinary Rust whitespace rather than documentation.
-     *
-     * Attribute collection skips these comments without treating them as evidence
-     * carriers or allowing them to interrupt a valid outer-attribute sequence.
-     */
-    function ordinaryComment(node) {
-        return ((node.type === "line_comment" || node.type === "block_comment") &&
-            node.childForFieldName("outer") === null &&
-            node.childForFieldName("inner") === null);
-    }
-    RustSyntax.ordinaryComment = ordinaryComment;
-    /**
-     * Reads the qualified name from a Rust attribute or its wrapper item.
-     *
-     * Scanner attribute policy uses the name to recognize documentation and report
-     * expansion risks; unsupported attribute shapes return undefined.
-     */
-    function attributeName(node) {
-        const attribute = node.type === "attribute_item" || node.type === "inner_attribute_item"
-            ? (node.namedChildren.find((child) => child.type === "attribute") ??
-                null)
-            : node.type === "attribute"
-                ? node
-                : null;
-        if (attribute === null)
-            return undefined;
-        const head = attribute.namedChildren[0] ?? null;
-        const segments = path(head);
-        return segments === undefined ? undefined : segments.join("::");
-    }
-    RustSyntax.attributeName = attributeName;
-    /**
-     * Returns the value expression of a Rust attribute or its wrapper item.
-     *
-     * Documentation-attribute handling validates this node as a supported static
-     * string before it creates a carrier; absent values return null.
-     */
-    function attributeValue(node) {
-        const attribute = node.type === "attribute_item" || node.type === "inner_attribute_item"
-            ? (node.namedChildren.find((child) => child.type === "attribute") ??
-                null)
-            : node.type === "attribute"
-                ? node
-                : null;
-        return attribute === null
-            ? null
-            : (attribute.childForFieldName("value") ?? null);
-    }
-    RustSyntax.attributeValue = attributeValue;
-    /**
-     * States whether a Rust comment uses the outer documentation form.
-     *
-     * The scanner may attach only these comment carriers to following item sites.
-     */
-    function outerDocumentation(node) {
-        return isOuterDocumentation(node);
-    }
-    RustSyntax.outerDocumentation = outerDocumentation;
-    /**
-     * States whether a Rust comment uses the inner documentation form.
-     *
-     * Inner carriers document their containing module instead of the following item.
-     */
-    function innerDocumentation(node) {
-        return ((node.type === "line_comment" || node.type === "block_comment") &&
-            node.childForFieldName("inner") !== null);
-    }
-    RustSyntax.innerDocumentation = innerDocumentation;
-    /**
-     * Supplies delimiter rules for a Rust comment carrier.
-     *
-     * RustFileScanner uses the returned syntax to map text and preserve tag
-     * coordinates for line, block, ordinary, and documentation comment forms.
-     */
-    function comment(node) {
-        const outer = isOuterDocumentation(node);
-        const inner = innerDocumentation(node);
-        const opening = node.type === "line_comment"
-            ? outer
-                ? "///"
-                : inner
-                    ? "//!"
-                    : "//"
-            : outer
-                ? "/**"
-                : inner
-                    ? "/*!"
-                    : "/*";
-        return opening.startsWith("//")
-            ? {
-                opening,
-                closing: "",
-                linePrefix: opening,
-                tagBoundaries: true,
-                allowWithdrawal: true,
-            }
-            : {
-                opening,
-                closing: "*/",
-                linePrefix: "*",
-                tagBoundaries: true,
-                allowWithdrawal: true,
-            };
-    }
-    RustSyntax.comment = comment;
-    /**
-     * Supplies delimiter rules for a supported Rust string literal.
-     *
-     * Annotation scanning uses this result for ordinary and raw strings, whose
-     * contents can report unsupported tags but cannot authorize withdrawals.
-     */
-    function string(node) {
-        if (node.type === "string_literal")
-            return {
-                opening: '"',
-                closing: '"',
-                tagBoundaries: true,
-                allowWithdrawal: false,
-            };
-        if (node.type === "raw_string_literal") {
-            const match = /^(?:br|r)(#*)"/u.exec(node.text);
-            if (match === null)
-                return undefined;
-            const hashes = match[1] ?? "";
-            return {
-                opening: node.text.slice(0, match[0].length),
-                closing: `"${hashes}`,
-                tagBoundaries: true,
-                allowWithdrawal: false,
-            };
-        }
-        return undefined;
-    }
-    RustSyntax.string = string;
-    function isOuterDocumentation(node) {
-        return ((node.type === "line_comment" || node.type === "block_comment") &&
-            node.childForFieldName("outer") !== null);
-    }
-})(RustSyntax || (exports.RustSyntax = RustSyntax = {}));

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

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

package/lib/adapters/scala/IScalaDeclaration.d.ts

@@ -1,78 +0,0 @@
-import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
-import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
-/**
- * Represents a Scala source declaration before snapshot-wide overload reconciliation.
- *
- * The record preserves lexical identity separately from exported addresses so
- * singleton exports and overloads can be published without collapsing sites.
- */
-export interface IScalaDeclaration {
-    /**
-     * Identifies this declaration record within one Scala source analysis.
-     *
-     * Scanner attachments and export records use this ID before semantic units are materialized.
-     */
-    id: string;
-    /**
-     * Stores the declaration name as written in Scala source.
-     *
-     * Backtick delimiters are removed, while characters inside the literal name remain unchanged.
-     */
-    name: string;
-    /**
-     * Classifies the declaration as a public programming symbol.
-     *
-     * Unit materialization includes this kind in the semantic identity so types, functions, and properties cannot merge.
-     */
-    symbol: EvidenceProgrammingSymbol;
-    /**
-     * Names the package and lexical owners that define semantic identity.
-     *
-     * Export aliases reuse this path from their source declaration instead of introducing a second unit.
-     */
-    identity: string[];
-    /**
-     * Names this declaration through its physical file address.
-     *
-     * Forwarded exports retain their forwarding address even when their identity belongs to another source owner.
-     */
-    address: string[];
-    /**
-     * Supplies source names that a bounded export may use during lookup.
-     *
-     * These names are not automatically public addresses; limiting lookup to
-     * them prevents arbitrary textual paths from becoming aliases.
-     */
-    lookup: string[];
-    /**
-     * Locates the original declaration and the source ranges included in its fingerprint.
-     *
-     * Extension and enum context may prepend header ranges to the declaration's physical site.
-     */
-    site: IEvidenceUnitSite;
-    /**
-     * States whether this declaration and every lexical owner are unrestricted.
-     *
-     * Restricted declarations remain available for boundary analysis but do not become public units.
-     */
-    public: boolean;
-    /**
-     * Identifies a singleton object eligible to supply an exported member.
-     *
-     * Scala's export syntax is resolved only through these static object owners,
-     * avoiding an unsupported inference through arbitrary expressions.
-     */
-    object: boolean;
-    /**
-     * Records the Tree-sitter node spelling that produced this declaration.
-     *
-     * Materialization uses it to distinguish source declarations from forwarding export sites.
-     */
-    syntax: string;
-    /**
-     * Identifies the directly enclosing lexical declaration when one exists.
-     *
-     * Withdrawal and public visibility propagate through this extraction-level ownership chain.
-     */
-    ownerDeclarationId?: string;
-}

package/lib/adapters/scala/IScalaDocumentation.d.ts

@@ -1,35 +0,0 @@
-import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-import type { IScalaDocumentationAttachment } from "./IScalaDocumentationAttachment";
-/**
- * Represents a Scala documentation carrier or tag-bearing unsupported carrier.
- *
- * Scaladoc remains tied to its physical declaration site while later export
- * resolution may add addresses for the same semantic declaration.
- */
-export interface IScalaDocumentation {
-    /**
-     * Identifies this physical documentation carrier within its source analysis.
-     *
-     * Attachments use this key before the adapter materializes semantic units.
-     */
-    id: string;
-    /**
-     * Locates the half-open UTF-16 span occupied by the documentation carrier.
-     *
-     * Review fingerprints exclude this range from its attached declaration content.
-     */
-    range: IEvidenceSourceRange;
-    /**
-     * Describes delimiters and annotation rules for parsing this carrier.
-     *
-     * Documentation mapping preserves these rules while masking ineligible examples.
-     */
-    syntax: IEvidenceCommentSyntax;
-    /**
-     * Lists physical declaration sites directly attached to this carrier.
-     *
-     * Unsupported tagged carriers remain unattached for diagnostic host creation.
-     */
-    attachments: IScalaDocumentationAttachment[];
-}

package/lib/adapters/scala/IScalaDocumentationAttachment.d.ts

@@ -1,22 +0,0 @@
-/**
- * Associates parsed Scaladoc with one Scala declaration site.
- *
- * Scala scanning stores attachments separately from documentation mappings so
- * extraction can retain each comment's source range and every consuming site.
- */
-export interface IScalaDocumentationAttachment {
-    /**
-     * Identifies the declaration that owns the attached documentation.
-     *
-     * Consumers use this extraction identity to connect the mapping before
-     * semantic units are materialized.
-     */
-    declarationId: string;
-    /**
-     * Identifies the physical declaration site that received the comment.
-     *
-     * A declaration can have several sites, so this prevents attachment from
-     * being inferred from semantic identity alone.
-     */
-    siteId: string;
-}

package/lib/adapters/scala/IScalaExport.d.ts

@@ -1,29 +0,0 @@
-import type { IScalaDeclaration } from "./IScalaDeclaration";
-/**
- * Represents a Scala forwarding declaration awaiting source-member resolution.
- *
- * The scanner preserves the forwarder's host and site first, then resolves the
- * requested source member through lexical paths during export materialization.
- */
-export interface IScalaExport {
-    /**
-     * Holds the forwarding declaration and its original extraction metadata.
-     *
-     * Its site remains the public declaration site even when the target is
-     * declared in another object or file.
-     */
-    declaration: IScalaDeclaration;
-    /**
-     * Lists lexical paths at which the source singleton can be found.
-     *
-     * Each path is tried in declaration context because relative Scala references
-     * can resolve through nested owners.
-     */
-    paths: string[][];
-    /**
-     * Names the literal member requested from the resolved source object.
-     *
-     * Dynamic or computed exports are excluded before this record is created.
-     */
-    member: string;
-}

package/lib/adapters/scala/IScalaFileAnalysis.d.ts

@@ -1,50 +0,0 @@
-import type { IScalaExport } from "./IScalaExport";
-import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { IScalaDeclaration } from "./IScalaDeclaration";
-import type { IScalaDocumentation } from "./IScalaDocumentation";
-/**
- * Holds the node-free Scala extraction retained after a parse session closes.
- *
- * Export reconciliation needs declarations from the selected snapshot at once,
- * while parser state is intentionally released after each source scan.
- */
-export interface IScalaFileAnalysis {
-    /**
-     * Retains the selected source snapshot that produced this analysis.
-     *
-     * Later export and documentation passes use its paths and content after the parser session closes.
-     */
-    source: IEvidenceSourceFile;
-    /**
-     * Lists declarations extracted from this source, including non-public boundaries.
-     *
-     * Visibility is resolved during publication, while retained private records support export and withdrawal decisions.
-     */
-    declarations: IScalaDeclaration[];
-    /**
-     * Lists classified Scaladoc and tag-bearing unsupported carriers.
-     *
-     * The adapter materializes them into attached or unsupported hosts after unit publication.
-     */
-    documentation: IScalaDocumentation[];
-    /**
-     * Lists failures encountered while establishing the Scala public surface.
-     *
-     * Each diagnostic keeps the source inventory incomplete instead of allowing a smaller population to pass.
-     */
-    diagnostics: IEvidenceDiagnostic[];
-    /**
-     * Lists explicit forwarding exports awaiting selected-source resolution.
-     *
-     * Resolution runs after every selected file supplies declarations and lexical lookup paths.
-     */
-    exports: IScalaExport[];
-    /**
-     * States whether scanning classified every surface-affecting Scala form.
-     *
-     * The inventory carries a false value forward so incomplete export discovery
-     * cannot silently turn a missing obligation into a passing result.
-     */
-    complete: boolean;
-}

package/lib/adapters/scala/ScalaAdapter.d.ts

@@ -1,100 +0,0 @@
-import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
-import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
-import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
-/**
- * Builds Scala public inventories after resolving source-level export forwarding.
- *
- * File scans retain declaration owners, export records, and Scaladoc attachments.
- * Forwarded exports are resolved before semantic groups are published, ensuring
- * public aliases and documentation refer to the same underlying identity rather
- * than creating independent coverage units.
- */
-export declare class ScalaAdapter implements IEvidenceAdapter {
-    /**
-     * Artifact discriminator selecting Scala grammar and extraction rules.
-     *
-     * Population configuration uses this value to select public declarations and
-     * supported documentation carriers through the common adapter contract.
-     */
-    readonly type = "scala";
-    /**
-     * Builds a normalized Scala inventory from a validated, cloned snapshot.
-     *
-     * Export resolution and public unit grouping precede annotation materialization.
-     * Diagnostics preserve incomplete scans, and parser cleanup runs on every exit.
-     */
-    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
-    private scan;
-    /**
-     * Reconciles public Scala declarations into semantic units and physical addresses.
-     *
-     * Functions may merge overload sites, while conflicting non-function identities make the inventory incomplete.
-     */
-    private materializeUnits;
-    /**
-     * Resolves withdrawals before publishing attached documentation hosts.
-     *
-     * Initial parsing records withdrawals on units, then hidden owners suppress attached claims while preserving unsupported carriers for diagnostics.
-     */
-    private materializeDocumentation;
-    /**
-     * Retains public declaration sites even when they carry no documentation.
-     *
-     * Undocumented hosts let inspection and graph consumers address every visible unit without inventing annotation content.
-     */
-    private materializeUndocumentedHosts;
-    /**
-     * Groups published semantic owners by their physical declaration site.
-     *
-     * A single Scaladoc host may attach to several units at one site, while aliases sharing identity are deduplicated.
-     */
-    private attachmentGroups;
-    /**
-     * Creates an attached host or an explicitly unsupported documentation carrier.
-     *
-     * Missing site ownership produces a host with repair guidance so tag parsing can report an actionable diagnostic.
-     */
-    private host;
-    /**
-     * Parses Evidence tags only after the adapter establishes their host.
-     *
-     * Host classification determines whether parsed acknowledgements attach to units or remain unsupported diagnostics.
-     */
-    private parse;
-    /**
-     * Detects Evidence and withdrawal annotations outside masked documentation examples.
-     *
-     * This broader check keeps tag-bearing unattached carriers available for unsupported-host materialization.
-     */
-    private annotation;
-    /**
-     * Detects acknowledgement and review annotations on carriers owned by withdrawn units.
-     *
-     * Withdrawal-only tags do not create a visible host after their owning unit has been hidden.
-     */
-    private claimAnnotation;
-    /**
-     * Recognizes supported annotation names at documentation line boundaries.
-     *
-     * The withdrawal mode includes internal visibility tags; claim-only mode restricts matching to evidence and review tags.
-     */
-    private annotationPattern;
-    /**
-     * Follows explicit parent ownership to determine whether a unit is withdrawn.
-     *
-     * A visited set stops malformed ownership cycles, while any direct withdrawal hides the unit and every descendant.
-     */
-    private withdrawn;
-    /**
-     * Builds a Scala unit identity from programming kind and lexical identity.
-     *
-     * Matching function declarations therefore unify overload sites, while different symbol kinds remain distinct units.
-     */
-    private unitId;
-    /**
-     * Marks a public declaration conflict as incomplete analysis.
-     *
-     * The diagnostic is attached to the contributing source so coverage cannot pass after competing selected declarations share one identity.
-     */
-    private problem;
-}