@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -0,0 +1,40 @@
+/**
+ * Describes a Rust impl block before its local nominal owner is resolved.
+ *
+ * The scanner records source-level paths; EvidenceRustModuleResolver resolves
+ * them in the containing module and assigns member identities to the selected
+ * owner.
+ */
+export interface IEvidenceRustImplementation {
+    /**
+     * Stable scanner ID shared by declarations emitted from this impl block.
+     *
+     * The resolver uses it to select exactly this block's associated members.
+     */
+    id: string;
+    /**
+     * Module path relative to the scanned file where the impl appears.
+     *
+     * Placement prepends the file prefix before path resolution.
+     */
+    modulePath: string[];
+    /**
+     * Source path naming the implemented nominal type.
+     *
+     * It must resolve to one selected local struct or enum before members
+     * publish.
+     */
+    ownerPath: string[];
+    /**
+     * Source path naming the implemented trait, when this is a trait impl.
+     *
+     * Omission represents an inherent impl and produces no trait qualifier.
+     */
+    traitPath?: string[];
+    /**
+     * Type parameter names declared by the impl block.
+     *
+     * The resolver uses them to reject blanket impls without one nominal owner.
+     */
+    typeParameters: string[];
+}

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

@@ -0,0 +1,35 @@
+import type { IEvidenceRustDeclaration } from "./IEvidenceRustDeclaration";
+import type { IEvidenceRustFilePlacement } from "./IEvidenceRustFilePlacement";
+import type { IEvidenceRustModuleRecord } from "./IEvidenceRustModuleRecord";
+/**
+ * Locates one Rust declaration in the resolved selected crate graph.
+ *
+ * Resolver phases enrich scanner output with module placement and a semantic
+ * identity before materializing units and public addresses.
+ */
+export interface IEvidenceRustLocatedDeclaration {
+    /**
+     * Scanner record describing the declaration's syntax and local ownership.
+     *
+     * Its source site remains the provenance for the resulting Evidence unit.
+     */
+    declaration: IEvidenceRustDeclaration;
+    /**
+     * Selected file and crate prefix containing the declaration.
+     *
+     * Address publication uses this placement to preserve file-qualified targets.
+     */
+    placement: IEvidenceRustFilePlacement;
+    /**
+     * Resolved module that owns the declaration.
+     *
+     * Binding and export resolution start from this record.
+     */
+    module: IEvidenceRustModuleRecord;
+    /**
+     * Canonical crate-relative segments naming the declaration semantically.
+     *
+     * Reexports may add public paths without changing this identity.
+     */
+    identity: string[];
+}

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

@@ -0,0 +1,62 @@
+import type { IEvidenceRustDeclaration } from "./IEvidenceRustDeclaration";
+import type { IEvidenceRustFilePlacement } from "./IEvidenceRustFilePlacement";
+import type { IEvidenceRustUse } from "./IEvidenceRustUse";
+/**
+ * Represents one inline or file-backed module in the selected crate graph.
+ *
+ * The resolver uses module records as the scope for direct bindings, use
+ * declarations, and paths that lead to externally reachable declarations.
+ */
+export interface IEvidenceRustModuleRecord {
+    /**
+     * Stable serialized key combining the crate root and resolved module path.
+     *
+     * Internal maps use this key so same-named modules in different crates remain
+     * separate.
+     */
+    key: string;
+    /**
+     * Stable key identifying the crate that owns this module.
+     *
+     * Unit identities include this value to prevent cross-crate collisions.
+     */
+    rootKey: string;
+    /**
+     * Canonical module segments from the crate root to this module.
+     *
+     * Resolver path operations use this for `crate`, `self`, and `super` lookup.
+     */
+    path: string[];
+    /**
+     * Module segments relative to the placed file that supplied this record.
+     *
+     * The value lets the resolver find an inline module declaration in its source
+     * analysis.
+     */
+    localPath: string[];
+    /**
+     * File placement that provides this module's direct declarations.
+     *
+     * Reexport records carry this placement to retain a valid address carrier.
+     */
+    placement: IEvidenceRustFilePlacement;
+    /**
+     * Declaration that introduced this module, when it is not a crate root.
+     *
+     * Omission identifies the synthetic root module for a selected crate file.
+     */
+    declaration?: IEvidenceRustDeclaration;
+    /**
+     * Direct declarations grouped by their local Rust name.
+     *
+     * Multiple values preserve ambiguities so resolution can report them rather
+     * than choosing an arbitrary public target.
+     */
+    bindings: Map<string, IEvidenceRustDeclaration[]>;
+    /**
+     * Public use declarations written in this module.
+     *
+     * Export construction expands these after direct module bindings exist.
+     */
+    uses: IEvidenceRustUse[];
+}

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

@@ -0,0 +1,37 @@
+import type { IEvidenceRustExportRecord } from "./IEvidenceRustExportRecord";
+import type { IEvidenceRustFilePlacement } from "./IEvidenceRustFilePlacement";
+import type { IEvidenceRustLocatedDeclaration } from "./IEvidenceRustLocatedDeclaration";
+/**
+ * Records one public path through which a selected Rust declaration is
+ * reachable.
+ *
+ * Materialization turns each occurrence into addresses while keeping the
+ * declaration's semantic identity independent of aliases and reexports.
+ */
+export interface IEvidenceRustPublicOccurrence {
+    /**
+     * Resolved declaration reached through the public path.
+     *
+     * This supplies the unit identity and source site for materialization.
+     */
+    located: IEvidenceRustLocatedDeclaration;
+    /**
+     * Export edge that introduced the final path segment.
+     *
+     * Its carrier identifies the source context that can address the alias.
+     */
+    exported: IEvidenceRustExportRecord;
+    /**
+     * File placement carrying the namespace used to traverse the path.
+     *
+     * This can differ from the declaration's source file after a reexport.
+     */
+    namespaceCarrier: IEvidenceRustFilePlacement;
+    /**
+     * Crate-relative public accessor segments for this occurrence.
+     *
+     * Each alias contributes a separate path without duplicating the Evidence
+     * unit.
+     */
+    publicPath: string[];
+}

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

@@ -0,0 +1,36 @@
+import type { IEvidenceRustLocatedDeclaration } from "./IEvidenceRustLocatedDeclaration";
+/**
+ * Assigns one associated Rust item to its selected local nominal owner.
+ *
+ * Resolver materialization uses the relationship to publish public impl members
+ * beneath the owner type rather than as standalone declarations.
+ */
+export interface IEvidenceRustResolvedMember {
+    /**
+     * Located associated declaration emitted from the impl block.
+     *
+     * Its identity is updated after the owner and optional trait are resolved.
+     */
+    declaration: IEvidenceRustLocatedDeclaration;
+    /**
+     * Selected local struct or enum that semantically owns the member.
+     *
+     * Only one unambiguous nominal owner is supported for publication.
+     */
+    owner: IEvidenceRustLocatedDeclaration;
+    /**
+     * Trait-derived segment that distinguishes a trait impl from an inherent
+     * impl.
+     *
+     * Omission means the member belongs to an inherent impl.
+     */
+    qualifier?: string;
+    /**
+     * Declaration ID of the selected local trait, when the trait resolved
+     * locally.
+     *
+     * Materialization requires that trait to be publicly reachable before
+     * exposing its impl members.
+     */
+    localTraitId?: string;
+}

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

@@ -0,0 +1,35 @@
+import type { IEvidenceRustUseBinding } from "./IEvidenceRustUseBinding";
+/**
+ * Captures one unrestricted public Rust use declaration and its bindings.
+ *
+ * The scanner expands nested use trees into statically readable targets so the
+ * resolver can construct public aliases without retaining syntax nodes.
+ */
+export interface IEvidenceRustUse {
+    /**
+     * Stable ID for this use declaration.
+     *
+     * Resolver diagnostics use it to report an unsupported or ambiguous export
+     * once.
+     */
+    id: string;
+    /**
+     * Module path relative to the scanned file where the use appears.
+     *
+     * File placement supplies the crate-relative prefix during resolution.
+     */
+    modulePath: string[];
+    /**
+     * Statically expanded leaf bindings declared by the use tree.
+     *
+     * A binding may name, rename, or wildcard-export a target.
+     */
+    bindings: IEvidenceRustUseBinding[];
+    /**
+     * Source-site ID for attaching diagnostics to the declaration.
+     *
+     * It is distinct from the use ID so a scanner site can be shared
+     * consistently.
+     */
+    siteId: string;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Describes one statically spelled target within a public Rust use declaration.
+ *
+ * Use-tree expansion preserves each leaf separately so aliases and wildcard
+ * exports receive their Rust-specific resolution rules.
+ */
+export interface IEvidenceRustUseBinding {
+    /**
+     * Source path segments from the use declaration to the imported target.
+     *
+     * The resolver interprets crate, self, and super segments in the use module.
+     */
+    path: string[];
+    /**
+     * Public name assigned with `as`, when the binding renames its target.
+     *
+     * Omission publishes the target's final path segment.
+     */
+    alias?: string;
+    /**
+     * Whether this binding reexports all public names from its target module.
+     *
+     * A false value identifies one named import path.
+     */
+    wildcard: boolean;
+}

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

@@ -1,15 +1,118 @@
-import { ScalaAdapter } from "./ScalaAdapter";
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
 /**
- * Extracts explicit unrestricted Scala declarations and supported static exports.
+ * Builds Scala public inventories after resolving source-level export
+ * forwarding.
  *
- * Selected Scala 2/3 source supplies package and lexical ownership. Singleton
- * objects and package objects retain explicit literal owner segments, and attached
- * Scaladoc supplies evidence hosts. Supported export projections preserve the
- * defining declaration's identity rather than duplicating its coverage unit.
- *
- * Anonymous givens, wildcard or unresolved exports, inherited or synthesized
- * members, macro expansion, derives/uses clauses, and extractor bindings are not
- * inferred as a complete source-public population.
+ * 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 EvidenceScalaAdapter extends ScalaAdapter {
+export declare class EvidenceScalaAdapter implements IEvidenceAdapter<"scala"> {
+    /**
+     * 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.
+     */
+    get 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;
 }