@wrtnlabs/evidence 0.0.0

package/lib/adapters/java/EvidenceJavaAdapter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceJavaAdapter = void 0;
+const JavaAdapter_1 = require("./JavaAdapter");
+/**
+ * Extracts Java source-public declarations and attached Javadoc from selected files.
+ *
+ * Analysis publishes top-level and nested types with methods grouped by owner and
+ * name. Its boundary is explicit source visibility, independent of JPMS package
+ * export enforcement. Overload sites remain available for documentation ownership
+ * even when they contribute to one semantic method family.
+ *
+ * The adapter does not execute annotation processors or synthesize inherited,
+ * record, or enum methods absent from source. Supply generated source explicitly
+ * when those declarations belong in the configured population.
+ */
+class EvidenceJavaAdapter extends JavaAdapter_1.JavaAdapter {
+}
+exports.EvidenceJavaAdapter = EvidenceJavaAdapter;

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

@@ -0,0 +1,65 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { JavaDeclarationForm } from "./JavaDeclarationForm";
+/**
+ * Records one Java declaration before its public unit and overload family are materialized.
+ *
+ * JavaFileScanner creates these physical records, and JavaAdapter reconciles
+ * compatible records into the language-independent Evidence inventory.
+ */
+export interface IJavaDeclaration {
+    /**
+     * Scanner-local declaration key for Javadoc attachments and reconciliation.
+     *
+     * It is replaced by a stable semantic unit ID during materialization.
+     */
+    id: string;
+    /**
+     * Unqualified source name used for unit display and member addressing.
+     *
+     * Package and enclosing type segments live in `identity`.
+     */
+    name: string;
+    /**
+     * Shared graph selector category for this Java declaration.
+     *
+     * It keeps Java syntax within the common programming-unit model.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Java declaration form that controls overload and type-family compatibility.
+     *
+     * Incompatible forms must remain visible as extraction failures.
+     */
+    form: JavaDeclarationForm;
+    /**
+     * Canonical package-qualified semantic path for family reconciliation.
+     *
+     * This identity remains independent of source file public addresses.
+     */
+    identity: string[];
+    /**
+     * Public accessor path emitted when the declaration is reachable.
+     *
+     * Segment boundaries preserve real structural containment.
+     */
+    address: string[];
+    /**
+     * Physical declaration site used for hosts and content fingerprints.
+     *
+     * Compatible records can contribute multiple sites to one unit.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Whether Java visibility and ancestor context permit publication.
+     *
+     * The adapter does not expose private declarations merely because they parse.
+     */
+    public: boolean;
+    /**
+     * Scanner-local enclosing declaration for a member or nested type.
+     *
+     * Omission denotes a package-level declaration.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/java/IJavaDeclaration.js

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

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

@@ -0,0 +1,35 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IJavaDocumentationAttachment } from "./IJavaDocumentationAttachment";
+/**
+ * Retains a Javadoc carrier and its scanner-established declaration attachments.
+ *
+ * JavaAdapter consumes these physical records after scanning to create evidence
+ * hosts and diagnose unsupported annotations without reparsing comments.
+ */
+export interface IJavaDocumentation {
+    /**
+     * 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: IJavaDocumentationAttachment[];
+}

package/lib/adapters/java/IJavaDocumentation.js

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

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

@@ -0,0 +1,20 @@
+/**
+ * Connects a Javadoc carrier to one physical Java declaration site.
+ *
+ * JavaFileScanner records this source adjacency, and JavaAdapter maps the local
+ * declaration to a reconciled unit without sharing the comment across overloads.
+ */
+export interface IJavaDocumentationAttachment {
+    /**
+     * 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/IJavaDocumentationAttachment.js

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

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

@@ -0,0 +1,42 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IJavaDeclaration } from "./IJavaDeclaration";
+import type { IJavaDocumentation } from "./IJavaDocumentation";
+/**
+ * Stores a node-free extraction of one Java source file after parsing closes.
+ *
+ * JavaAdapter aggregates these records to reconcile overload families, attach
+ * Javadoc hosts, and preserve extraction failures in the final inventory.
+ */
+export interface IJavaFileAnalysis {
+    /**
+     * 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: IJavaDeclaration[];
+    /**
+     * Javadoc carriers with scanner-proven declaration attachments.
+     *
+     * Annotation-bearing but unsupported carriers remain diagnosable.
+     */
+    documentation: IJavaDocumentation[];
+    /**
+     * 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/IJavaFileAnalysis.js

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

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

@@ -0,0 +1,39 @@
+import type { JavaTypeKind } from "./JavaTypeKind";
+/**
+ * Carries an enclosing Java type's state while its nested declarations are scanned.
+ *
+ * JavaFileScanner passes this context through type bodies so descendants retain
+ * their structural identity, public address prefix, and inherited visibility.
+ */
+export interface IJavaTypeContext {
+    /**
+     * 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: JavaTypeKind;
+    /**
+     * 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/java/IJavaTypeContext.js

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

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

@@ -0,0 +1,45 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Materializes Java public declaration families and their attached Javadoc.
+ *
+ * The scanner establishes source visibility, lexical owners, and physical sites.
+ * Unit materialization reconciles supported callable families before comments
+ * become evidence hosts, retaining distinct sites without counting each overload
+ * as an unrelated public name. This boundary concerns declared Java visibility,
+ * not module export policy or compiler-generated members.
+ *
+ * Source failures and incomplete scans remain visible in the returned inventory.
+ * Each invocation owns its parser lifetime and mutable extraction state.
+ */
+export declare class JavaAdapter implements IEvidenceAdapter {
+    /**
+     * Java artifact discriminator for grammar selection and unit classification.
+     *
+     * The public adapter uses this fixed language for both claim hosts and reference
+     * targets; it does not infer another language from a selected source filename.
+     */
+    readonly type = "java";
+    /**
+     * Extracts source-public Java declarations from a captured snapshot.
+     *
+     * Input is validated and copied before asynchronous scanning. Units precede
+     * Javadoc materialization so declaration families own their actual comment
+     * positions, and parser cleanup runs after either success or failure.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    private materializeUnits;
+    private materializeDocumentation;
+    private materializeUndocumentedHosts;
+    private attachmentGroups;
+    private host;
+    private parse;
+    private annotation;
+    private claimAnnotation;
+    private annotationPattern;
+    private withdrawn;
+    private unitId;
+    private problem;
+}