@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/java/IEvidenceJavaDocumentation.d.ts

@@ -0,0 +1,37 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceJavaDocumentationAttachment } from "./IEvidenceJavaDocumentationAttachment";
+/**
+ * Retains a Javadoc carrier and its scanner-established declaration
+ * attachments.
+ *
+ * EvidenceJavaAdapter consumes these physical records after scanning to create
+ * evidence hosts and diagnose unsupported annotations without reparsing
+ * comments.
+ */
+export interface IEvidenceJavaDocumentation {
+    /**
+     * Stable physical-comment ID used by attachments and tag parsing.
+     *
+     * It does not identify a semantic Java declaration.
+     */
+    id: string;
+    /**
+     * Exact comment range retained for diagnostics and fingerprint exclusion.
+     *
+     * Only this span is decoded as a Javadoc annotation carrier.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Delimiter details needed to read the Javadoc text accurately.
+     *
+     * Evidence parsing consumes this syntax instead of inferring comments again.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Declaration sites established by source adjacency during scanning.
+     *
+     * Later family reconciliation never widens this attachment relationship.
+     */
+    attachments: IEvidenceJavaDocumentationAttachment[];
+}

package/lib/adapters/java/IEvidenceJavaDocumentationAttachment.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Connects a Javadoc carrier to one physical Java declaration site.
+ *
+ * EvidenceJavaFileScanner records this source adjacency, and
+ * EvidenceJavaAdapter maps the local declaration to a reconciled unit without
+ * sharing the comment across overloads.
+ */
+export interface IEvidenceJavaDocumentationAttachment {
+    /**
+     * Scanner-local declaration receiving this Javadoc carrier.
+     *
+     * Materialization maps it to a reconciled semantic unit.
+     */
+    declarationId: string;
+    /**
+     * Physical site that owns an evidence host for the declaration.
+     *
+     * This avoids treating comments as transferable among overloads.
+     */
+    siteId: string;
+}

package/lib/adapters/java/IEvidenceJavaFileAnalysis.d.ts

@@ -0,0 +1,43 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceJavaDeclaration } from "./IEvidenceJavaDeclaration";
+import type { IEvidenceJavaDocumentation } from "./IEvidenceJavaDocumentation";
+/**
+ * Stores a node-free extraction of one Java source file after parsing closes.
+ *
+ * EvidenceJavaAdapter aggregates these records to reconcile overload families,
+ * attach Javadoc hosts, and preserve extraction failures in the final
+ * inventory.
+ */
+export interface IEvidenceJavaFileAnalysis {
+    /**
+     * Source snapshot owning all extracted Java records.
+     *
+     * Its configured paths later receive the published accessor addresses.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Declarations awaiting family reconciliation and public filtering.
+     *
+     * Records retain sites after the parser session has closed.
+     */
+    declarations: IEvidenceJavaDeclaration[];
+    /**
+     * Javadoc carriers with scanner-proven declaration attachments.
+     *
+     * Annotation-bearing but unsupported carriers remain diagnosable.
+     */
+    documentation: IEvidenceJavaDocumentation[];
+    /**
+     * Extraction errors that must survive into the inventory.
+     *
+     * They prevent partial parsing from becoming passing smaller coverage.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * Whether the scanner represented every relevant supported construct.
+     *
+     * The adapter carries this status through final inventory validation.
+     */
+    complete: boolean;
+}

package/lib/adapters/java/IEvidenceJavaTypeContext.d.ts

@@ -0,0 +1,41 @@
+import type { EvidenceJavaTypeKind } from "./EvidenceJavaTypeKind";
+/**
+ * Carries an enclosing Java type's state while its nested declarations are
+ * scanned.
+ *
+ * EvidenceJavaFileScanner passes this context through type bodies so
+ * descendants retain their structural identity, public address prefix, and
+ * inherited visibility.
+ */
+export interface IEvidenceJavaTypeContext {
+    /**
+     * Enclosing type's scanner-local declaration record.
+     *
+     * Nested members use it to retain their structural owner.
+     */
+    declarationId: string;
+    /**
+     * Semantic path inherited by nested declarations.
+     *
+     * It determines unit identity rather than public file qualification.
+     */
+    identity: string[];
+    /**
+     * Public accessor prefix inherited from the enclosing type.
+     *
+     * Java members extend it when publishing targetable addresses.
+     */
+    address: string[];
+    /**
+     * Type form that determines supported nested declaration treatment.
+     *
+     * The scanner preserves this classification while walking members.
+     */
+    kind: EvidenceJavaTypeKind;
+    /**
+     * Whether this owner exposes nested declarations through public API.
+     *
+     * Non-public ancestry suppresses child publication even if a child is public.
+     */
+    public: boolean;
+}

package/lib/adapters/javascript/EvidenceJavaScriptAdapter.d.ts

@@ -1,6 +1,7 @@
-import { EcmaScriptAdapter } from "../ecmascript/EcmaScriptAdapter";
+import { EvidenceEcmaScriptAdapter } from "../ecmascript/EvidenceEcmaScriptAdapter";
 /**
- * Extracts static JavaScript module exports and bounded CommonJS initialization.
+ * Extracts static JavaScript module exports and bounded CommonJS
+ * initialization.
  *
  * The shared ECMAScript extractor classifies the selected files' module modes,
  * establishes declaration and JSDoc ownership, and publishes file-qualified
@@ -12,15 +13,22 @@ import { EcmaScriptAdapter } from "../ecmascript/EcmaScriptAdapter";
  * failures rather than silently omitted exports.
  *
  * @example
- * // A declared instance method is addressed as client.js#Client.prototype.send.
- * // Adding another supported export name does not create a second method unit.
+ *   // A declared instance method is addressed as client.js#Client.prototype.send.
+ *   // Adding another supported export name does not create a second method unit.
  */
-export declare class EvidenceJavaScriptAdapter extends EcmaScriptAdapter {
+export declare class EvidenceJavaScriptAdapter extends EvidenceEcmaScriptAdapter<"javascript"> {
     /**
      * Configures the shared extractor for JavaScript and JSX source.
      *
-     * The inherited analysis chooses module semantics from file and package context.
-     * No grammar or source is loaded until a snapshot is analyzed.
+     * The inherited analysis chooses module semantics from file and package
+     * context. No grammar or source is loaded until a snapshot is analyzed.
      */
     constructor();
+    /**
+     * JavaScript discriminator for the shared ECMAScript extraction pipeline.
+     *
+     * The literal return type lets adapter registries preserve this entry point's
+     * artifact identity without narrowing a shared base instance at runtime.
+     */
+    get type(): "javascript";
 }

package/lib/adapters/javascript/EvidenceJavaScriptAdapter.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EvidenceJavaScriptAdapter = void 0;
-const EcmaScriptAdapter_1 = require("../ecmascript/EcmaScriptAdapter");
+const EvidenceEcmaScriptAdapter_1 = require("../ecmascript/EvidenceEcmaScriptAdapter");
 /**
- * Extracts static JavaScript module exports and bounded CommonJS initialization.
+ * Extracts static JavaScript module exports and bounded CommonJS
+ * initialization.
  *
  * The shared ECMAScript extractor classifies the selected files' module modes,
  * establishes declaration and JSDoc ownership, and publishes file-qualified
@@ -15,18 +16,27 @@ const EcmaScriptAdapter_1 = require("../ecmascript/EcmaScriptAdapter");
  * failures rather than silently omitted exports.
  *
  * @example
- * // A declared instance method is addressed as client.js#Client.prototype.send.
- * // Adding another supported export name does not create a second method unit.
+ *   // A declared instance method is addressed as client.js#Client.prototype.send.
+ *   // Adding another supported export name does not create a second method unit.
  */
-class EvidenceJavaScriptAdapter extends EcmaScriptAdapter_1.EcmaScriptAdapter {
+class EvidenceJavaScriptAdapter extends EvidenceEcmaScriptAdapter_1.EvidenceEcmaScriptAdapter {
     /**
      * Configures the shared extractor for JavaScript and JSX source.
      *
-     * The inherited analysis chooses module semantics from file and package context.
-     * No grammar or source is loaded until a snapshot is analyzed.
+     * The inherited analysis chooses module semantics from file and package
+     * context. No grammar or source is loaded until a snapshot is analyzed.
      */
     constructor() {
-        super("javascript", "JavaScript");
+        super("JavaScript");
+    }
+    /**
+     * JavaScript discriminator for the shared ECMAScript extraction pipeline.
+     *
+     * The literal return type lets adapter registries preserve this entry point's
+     * artifact identity without narrowing a shared base instance at runtime.
+     */
+    get type() {
+        return "javascript";
     }
 }
 exports.EvidenceJavaScriptAdapter = EvidenceJavaScriptAdapter;

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

@@ -1,15 +1,119 @@
-import { KotlinAdapter } from "./KotlinAdapter";
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
 /**
- * Extracts explicit public Kotlin declarations and receiver-qualified extensions.
+ * Resolves Kotlin nominal receivers before publishing declaration and KDoc
+ * hosts.
  *
- * Analysis resolves supported nominal aliases and extension receivers across the
- * selected snapshot while retaining file-private and lexical ownership. Public
- * paths expose explicit companion owners and receiver segments; attached KDoc
- * supplies evidence without importing a compiler's generated member population.
- *
- * Scripts, expect/actual composition, delegated members, implicit override
- * visibility, and generic or unresolved extension receivers are not inferred.
- * Those boundaries must remain visible when they affect public completeness.
+ * 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 EvidenceKotlinAdapter extends KotlinAdapter {
+export declare class EvidenceKotlinAdapter implements IEvidenceAdapter<"kotlin"> {
+    /**
+     * 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.
+     */
+    get 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;
 }