@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/kotlin/IEvidenceKotlinDeclaration.d.ts

@@ -0,0 +1,99 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { IEvidenceKotlinTypeReference } from "./IEvidenceKotlinTypeReference";
+/**
+ * Represents one Kotlin declaration before overload families become inventory
+ * units.
+ *
+ * The scanner keeps source-level visibility, receiver, and alias information
+ * here because snapshot-wide resolution can change the semantic owner of an
+ * extension.
+ */
+export interface IEvidenceKotlinDeclaration {
+    /**
+     * Identifies this physical extraction record within the source snapshot.
+     *
+     * Receiver resolution and documentation attachments use this scanner-local
+     * value before unit materialization assigns a semantic ID.
+     */
+    id: string;
+    /**
+     * Gives the literal Kotlin name decoded from the declaration.
+     *
+     * The scanner combines it with receiver and lexical paths while preserving
+     * its source spelling for diagnostics.
+     */
+    name: string;
+    /**
+     * Classifies the declaration in Evidence's language-independent selector
+     * vocabulary.
+     *
+     * The adapter retains this category while reconciling package-scoped overload
+     * families.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Lists type-parameter names visible at this declaration's lexical scope.
+     *
+     * Deferred receiver parsing uses these names to reject type-variable
+     * receivers that static nominal lookup cannot resolve.
+     */
+    typeParameters: string[];
+    /**
+     * Holds the nominal target when this declaration introduces a type alias.
+     *
+     * Later receiver resolution expands it only in the source context where its
+     * imports and file-private visibility rules are valid.
+     */
+    aliasTarget?: IEvidenceKotlinTypeReference;
+    /**
+     * Retains the declared extension receiver before nominal lookup.
+     *
+     * Extension members belong to the resolved receiver type rather than to the
+     * file that happens to declare the extension.
+     */
+    receiver?: IEvidenceKotlinTypeReference;
+    /**
+     * Lists package and lexical ownership segments for the semantic unit.
+     *
+     * Receiver resolution may replace the extension's lexical owner with its
+     * resolved nominal receiver.
+     */
+    identity: string[];
+    /**
+     * Lists public accessor segments as projected from the source file.
+     *
+     * These remain distinct from `identity` so consumers can cite the public
+     * spelling of an extension declaration.
+     */
+    address: string[];
+    /**
+     * Retains the physical declaration site and content used by hosts and
+     * fingerprints.
+     *
+     * A reconciled overload family can retain several of these source
+     * occurrences.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * States whether this declaration and each containing owner are public.
+     *
+     * The adapter retains non-public records for receiver lookup but does not
+     * publish their units or addresses.
+     */
+    public: boolean;
+    /**
+     * Records Kotlin file-private visibility for nominal lookup.
+     *
+     * A same-named declaration in another file must not satisfy a receiver or
+     * alias reference that can only see this physical source.
+     */
+    filePrivate: boolean;
+    /**
+     * Identifies the containing declaration when this record is a member.
+     *
+     * Omission denotes a package-level declaration; materialization uses this
+     * link to propagate ownership and withdrawals.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/kotlin/IEvidenceKotlinDocumentation.d.ts

@@ -0,0 +1,39 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceKotlinDocumentationAttachment } from "./IEvidenceKotlinDocumentationAttachment";
+/**
+ * Represents a Kotlin documentation carrier or tag-bearing unsupported carrier.
+ *
+ * KDoc attachment is established from source adjacency, while tagged text in an
+ * ineligible carrier remains present for a host-level diagnostic.
+ */
+export interface IEvidenceKotlinDocumentation {
+    /**
+     * Identifies this physical KDoc or unsupported carrier within the scanned
+     * source.
+     *
+     * Attachments and host generation use this scanner-local value, which is
+     * distinct from a declaration's semantic identity.
+     */
+    id: string;
+    /**
+     * Locates the carrier's original half-open UTF-16 source span.
+     *
+     * The adapter preserves this range for diagnostics and annotation-range
+     * exclusion.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Defines the carrier delimiters and annotation-reading rules.
+     *
+     * KDoc parsing uses this syntax rather than guessing from raw source text.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Lists declaration sites that accept this carrier as KDoc.
+     *
+     * The scanner establishes these source-adjacent attachments before receiver
+     * and unit resolution.
+     */
+    attachments: IEvidenceKotlinDocumentationAttachment[];
+}

package/lib/adapters/kotlin/IEvidenceKotlinDocumentationAttachment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Connects a KDoc carrier to one extracted Kotlin declaration site.
+ *
+ * EvidenceKotlinFileScanner establishes this adjacency from source, then the
+ * documentation pass uses the pair to evaluate annotations for the relevant
+ * site without assigning the comment semantic ownership.
+ */
+export interface IEvidenceKotlinDocumentationAttachment {
+    /**
+     * Identifies the declaration extraction record that receives the KDoc.
+     *
+     * Consumers use this stable scanner-local ID to recover the declaration whose
+     * annotation is evaluated.
+     */
+    declarationId: string;
+    /**
+     * Identifies the physical declaration site covered by the KDoc.
+     *
+     * This distinguishes the adjacent source occurrence when one semantic unit
+     * has more than one declaration site.
+     */
+    siteId: string;
+}

package/lib/adapters/kotlin/IEvidenceKotlinFileAnalysis.d.ts

@@ -0,0 +1,47 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceKotlinDeclaration } from "./IEvidenceKotlinDeclaration";
+import type { IEvidenceKotlinDocumentation } from "./IEvidenceKotlinDocumentation";
+/**
+ * Holds the node-free Kotlin extraction retained after a parse session closes.
+ *
+ * Receiver and alias resolution consumes all selected files after scanning, so
+ * this boundary owns source-context facts without retaining parser objects.
+ */
+export interface IEvidenceKotlinFileAnalysis {
+    /**
+     * Retains the selected Kotlin source file that produced this analysis.
+     *
+     * Receiver resolution uses its physical identity for file-private lookup, and
+     * materialization uses its addresses for public citations.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Lists extracted declarations, including non-public lookup boundaries.
+     *
+     * `EvidenceKotlinReceivers` consumes the records across the snapshot before
+     * `EvidenceKotlinAdapter` selects public units.
+     */
+    declarations: IEvidenceKotlinDeclaration[];
+    /**
+     * Lists classified KDoc and unsupported annotation carriers from this file.
+     *
+     * The adapter preserves tagged unsupported carriers so they can produce
+     * host-level diagnostics.
+     */
+    documentation: IEvidenceKotlinDocumentation[];
+    /**
+     * Lists failures encountered while establishing this file's public surface.
+     *
+     * The adapter forwards them into the inventory together with the `complete`
+     * status.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether the scanner understood every surface-affecting form.
+     *
+     * Incomplete scans are propagated into the inventory so unsupported Kotlin
+     * syntax cannot make a coverage check pass with fewer units.
+     */
+    complete: boolean;
+}

package/lib/adapters/kotlin/IEvidenceKotlinResolvedType.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Describes a statically resolved Kotlin nominal receiver.
+ *
+ * EvidenceKotlinReceivers produces this result after lexical lookup and
+ * supported type alias expansion, then uses it to place extension declarations
+ * beneath their effective receiver address.
+ */
+export interface IEvidenceKotlinResolvedType {
+    /**
+     * Gives canonical package and declared-owner segments for the receiver.
+     *
+     * These segments become the receiver spelling in an extension identity and
+     * preserve declaration ownership rather than the import used to reach it.
+     */
+    segments: string[];
+    /**
+     * Indicates whether the effective receiver permits null.
+     *
+     * EvidenceKotlinReceivers preserves a nullable suffix from the source
+     * reference or from any selected alias expansion when constructing the
+     * extension address.
+     */
+    nullable: boolean;
+}

package/lib/adapters/kotlin/IEvidenceKotlinTypeReference.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Retains a Kotlin receiver reference for later static nominal lookup.
+ *
+ * EvidenceKotlinFileScanner records lookup candidates while file scope and
+ * imports are available, and EvidenceKotlinReceivers resolves the reference
+ * after declarations and supported aliases have been collected without invoking
+ * the Kotlin compiler.
+ */
+export interface IEvidenceKotlinTypeReference {
+    /**
+     * Names the physical source that supplied this receiver reference.
+     *
+     * EvidenceKotlinReceivers permits file-private aliases only from this file,
+     * preserving Kotlin visibility during deferred lookup.
+     */
+    file: string;
+    /**
+     * Lists nominal lookup candidates from lexical, imported, and package scope.
+     *
+     * EvidenceKotlinReceivers checks these paths in order and accepts exactly one
+     * visible declaration, so their ordering represents
+     * EvidenceKotlinFileScanner's precedence.
+     */
+    paths: string[][];
+    /**
+     * Provides a resolved external, qualified, or Kotlin-core type path.
+     *
+     * Omission means no such path is statically known, so lookup must find a
+     * selected declaration through {@link paths} or report an unresolved
+     * receiver.
+     */
+    external?: string[];
+    /**
+     * Records whether the parsed receiver reference has a nullable suffix.
+     *
+     * Alias resolution combines this value with nullability inherited from the
+     * expanded alias target.
+     */
+    nullable: boolean;
+    /**
+     * Explains why this receiver cannot use nominal static resolution.
+     *
+     * Omission permits EvidenceKotlinReceivers lookup; when present, callers
+     * preserve the unsupported-receiver diagnostic instead of guessing
+     * substitutions or imports.
+     */
+    problem?: string;
+}

package/lib/adapters/lua/EvidenceLuaAdapter.d.ts

@@ -1,16 +1,124 @@
-import { LuaAdapter } from "./LuaAdapter";
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
 /**
- * Extracts explicit Lua globals and statically returned module-table fields.
+ * Materializes statically established Lua declarations and documentation
+ * owners.
  *
- * Literal fields and resolved local aliases establish the supported public
- * surface. Tables are property units; dot and colon methods use literal field
- * accessors rather than acquiring different identities from call syntax. Eligible
- * LuaDoc and long comments retain their declaration ownership.
- *
- * Dynamic mutation, metatables, require execution, computed or numeric keys, and
- * conditional initialization cannot establish this static denominator. Shared
- * values with distinct table owners also require a diagnostic instead of an
- * arbitrary owner assignment.
+ * The scanner records supported globals, returned-table fields, and local alias
+ * relationships without executing the module. Materialization publishes their
+ * semantic units before LuaDoc becomes evidence hosts, so a shared source value
+ * is not assigned an arbitrary table owner merely because a comment names it.
+ * Source and syntax uncertainty remain part of the final inventory status.
  */
-export declare class EvidenceLuaAdapter extends LuaAdapter {
+export declare class EvidenceLuaAdapter implements IEvidenceAdapter<"lua"> {
+    /**
+     * Lua discriminator for static global and module-table extraction.
+     *
+     * It selects Lua grammar and documentation rules. Tables remain property
+     * units rather than becoming type declarations by analogy with another
+     * language.
+     */
+    get type(): "lua";
+    /**
+     * Analyzes a copied Lua snapshot and returns reconciled public records.
+     *
+     * Declaration materialization precedes comment attachment, and common
+     * inventory validation checks the resulting ownership. The parser closes
+     * after success or failure; returned records contain no borrowed syntax
+     * nodes.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    /**
+     * Materializes literal aliases into units and physical public addresses.
+     *
+     * Shared declarations retain one unit identity while each selected source
+     * address remains visible; conflicting declarations make the inventory
+     * incomplete.
+     */
+    private materializeUnits;
+    /**
+     * Resolves withdrawals before publishing attached documentation hosts.
+     *
+     * Withdrawal propagation hides affected units first, then tag parsing
+     * publishes only visible attachment groups or an explicit unsupported
+     * annotation host.
+     */
+    private materializeDocumentation;
+    /**
+     * Publishes hosts for visible public declaration sites without documentation.
+     *
+     * These attached hosts preserve physical origin and unit membership for later
+     * graph and query consumers even when no tag carrier was parsed at the site.
+     */
+    private materializeUndocumentedHosts;
+    /**
+     * Groups published semantic owners by their physical declaration site.
+     *
+     * Multiple attachments at one site share a host and deduplicate unit IDs,
+     * while unpublished declarations do not create annotation ownership.
+     */
+    private attachmentGroups;
+    /**
+     * Creates an attached or explicitly unsupported documentation host.
+     *
+     * A host is attached only when it has both a declaration site and published
+     * units; otherwise its repair guidance explains why tags cannot affect
+     * coverage.
+     */
+    private host;
+    /**
+     * Parses Evidence tags after the adapter establishes their host boundary.
+     *
+     * EvidenceLuaDocumentation supplies normalized, example-masked text, ensuring
+     * tags inherit the attached or unsupported ownership selected by this
+     * adapter.
+     */
+    private parse;
+    /**
+     * Detects Evidence and withdrawal annotations outside masked examples.
+     *
+     * This broader scan decides whether an otherwise unattached carrier still
+     * needs an unsupported host and diagnostic processing.
+     */
+    private annotation;
+    /**
+     * Detects acknowledgement and review annotations on withdrawn carriers.
+     *
+     * Withdrawal-only tags are excluded so hidden declarations do not retain a
+     * carrier unless it can still contribute a claim-level annotation or review.
+     */
+    private claimAnnotation;
+    /**
+     * Recognizes supported annotation names at documentation line boundaries.
+     *
+     * The withdrawal mode includes hidden and ignore forms; ordinary claim
+     * parsing recognizes only evidence, exclusion, review, link, and internal
+     * annotations.
+     */
+    private annotationPattern;
+    /**
+     * Follows explicit parent ownership to determine effective withdrawal.
+     *
+     * A visited set prevents malformed ownership cycles from recursing forever,
+     * while a withdrawn ancestor hides each descendant from documentation hosts.
+     */
+    private withdrawn;
+    /**
+     * Builds a file-scoped unit identity that distinguishes programming kinds.
+     *
+     * Identity segments and the declaration symbol remain separate, allowing one
+     * Lua file to expose similarly named properties and functions without
+     * collision.
+     */
+    private unitId;
+    /**
+     * Records a declaration conflict and marks the Lua inventory incomplete.
+     *
+     * The diagnostic identifies the selected source file and preserves caller
+     * repair guidance, preventing ambiguous public identity from entering
+     * coverage.
+     */
+    private problem;
 }