@wrtnlabs/evidence 0.0.0

package/lib/adapters/kotlin/IKotlinDeclaration.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,31 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IKotlinDocumentationAttachment } from "./IKotlinDocumentationAttachment";
+/**
+ * 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 IKotlinDocumentation {
+    /** 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: IKotlinDocumentationAttachment[];
+}

package/lib/adapters/kotlin/IKotlinDocumentation.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,23 @@
+/**
+ * Connects a KDoc carrier to one extracted Kotlin declaration site.
+ *
+ * KotlinFileScanner 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 IKotlinDocumentationAttachment {
+    /**
+     * 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/IKotlinDocumentationAttachment.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,39 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IKotlinDeclaration } from "./IKotlinDeclaration";
+import type { IKotlinDocumentation } from "./IKotlinDocumentation";
+/**
+ * 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 IKotlinFileAnalysis {
+    /** 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.
+     *
+     * `KotlinReceivers` consumes the records across the snapshot before `KotlinAdapter` selects public units.
+     */
+    declarations: IKotlinDeclaration[];
+    /** Lists classified KDoc and unsupported annotation carriers from this file.
+     *
+     * The adapter preserves tagged unsupported carriers so they can produce host-level diagnostics.
+     */
+    documentation: IKotlinDocumentation[];
+    /** 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/IKotlinFileAnalysis.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,23 @@
+/**
+ * Describes a statically resolved Kotlin nominal receiver.
+ *
+ * KotlinReceivers 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 IKotlinResolvedType {
+    /**
+     * 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.
+     *
+     * KotlinReceivers 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/IKotlinResolvedType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,44 @@
+/**
+ * Retains a Kotlin receiver reference for later static nominal lookup.
+ *
+ * KotlinFileScanner records lookup candidates while file scope and imports are
+ * available, and KotlinReceivers resolves the reference after declarations and
+ * supported aliases have been collected without invoking the Kotlin compiler.
+ */
+export interface IKotlinTypeReference {
+    /**
+     * Names the physical source that supplied this receiver reference.
+     *
+     * KotlinReceivers 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.
+     *
+     * KotlinReceivers checks these paths in order and accepts exactly one visible
+     * declaration, so their ordering represents KotlinFileScanner'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 KotlinReceivers lookup; when present, callers preserve the
+     * unsupported-receiver diagnostic instead of guessing substitutions or imports.
+     */
+    problem?: string;
+}

package/lib/adapters/kotlin/IKotlinTypeReference.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,114 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Resolves Kotlin nominal receivers before publishing declaration and KDoc hosts.
+ *
+ * File analysis retains aliases, type parameters, and receiver candidates until
+ * the selected snapshot is available for lookup. Receiver resolution then updates
+ * ownership or records uncertainty before unit materialization. KDoc attachments
+ * join the resulting units through physical declaration sites, preserving the
+ * distinction between a receiver-qualified public path and its original source.
+ */
+export declare class KotlinAdapter implements IEvidenceAdapter {
+    /**
+     * Kotlin discriminator selecting KDoc and receiver-aware declaration rules.
+     *
+     * This fixes the language of inventory records; it does not widen selection to
+     * scripts or compiler-generated declarations absent from the snapshot.
+     */
+    readonly type = "kotlin";
+    /**
+     * Extracts and reconciles Kotlin declarations from an owned source snapshot.
+     *
+     * All files are scanned before receiver lookup. Resolution findings contribute
+     * to completeness before units and documentation are published, and the parser
+     * closes after both successful and failed materialization.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    /**
+     * Reconciles overload families and retains each physical declaration address.
+     *
+     * Functions sharing a Kotlin identity form one unit with multiple sites, while
+     * other duplicate identities remain a completeness error rather than a merge.
+     */
+    private materializeUnits;
+    /**
+     * Resolves withdrawals before publishing attached annotation hosts.
+     *
+     * Tags first populate unit withdrawals, then inherited hidden ownership filters
+     * visible hosts so withdrawn declarations cannot receive acknowledgements.
+     */
+    private materializeDocumentation;
+    /**
+     * Retains public declaration sites even when they carry no documentation.
+     *
+     * Evidence needs a host for every visible unit so unhosted checklist results
+     * can identify declarations that have no attached KDoc.
+     */
+    private materializeUndocumentedHosts;
+    /**
+     * Groups published semantic owners by their physical declaration site.
+     *
+     * One KDoc can attach to declarations that share a site, while duplicate unit
+     * IDs within that group are removed before the tag parser creates a host.
+     */
+    private attachmentGroups;
+    /**
+     * Creates an attached or explicitly unsupported documentation carrier.
+     *
+     * Annotation parsing still receives an unsupported carrier so misplaced KDoc
+     * produces an actionable diagnostic instead of disappearing from the graph.
+     */
+    private host;
+    /**
+     * Parses Evidence tags only after the adapter establishes their host.
+     *
+     * Kotlin-specific documentation normalization runs before the shared parser so
+     * source mappings and masked examples apply consistently to every host.
+     */
+    private parse;
+    /**
+     * Detects Evidence or withdrawal annotations outside masked examples.
+     *
+     * The broad pattern determines whether unowned KDoc needs an unsupported host
+     * for acknowledgements, reviews, and declaration-withdrawal tags.
+     */
+    private annotation;
+    /**
+     * Detects acknowledgements and reviews on withdrawn carriers.
+     *
+     * Withdrawal-only text does not keep a hidden declaration's host alive, but
+     * evidence and review tags still need diagnostics or graph records.
+     */
+    private claimAnnotation;
+    /**
+     * Recognizes supported annotation names at documentation line boundaries.
+     *
+     * Line anchoring prevents prose and masked examples containing tag-like text
+     * from manufacturing an annotation carrier.
+     */
+    private annotationPattern;
+    /**
+     * Follows explicit parent ownership to propagate withdrawal.
+     *
+     * The visited set breaks malformed ownership cycles; a unit is hidden when it
+     * or any reachable owner has a withdrawal record.
+     */
+    private withdrawn;
+    /**
+     * Separates programming kinds while unifying package-scoped overload identities.
+     *
+     * Kotlin function overloads intentionally share an identity, whereas symbol
+     * kind remains part of the key to keep types and properties distinct.
+     */
+    private unitId;
+    /**
+     * Marks a declaration conflict as incomplete analysis.
+     *
+     * The inventory keeps the diagnostic and source location, but cannot claim a
+     * complete public surface while one identity has conflicting declarations.
+     */
+    private problem;
+}