@wrtnlabs/evidence 0.0.0

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

@@ -0,0 +1,54 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+/**
+ * Represents one static Lua declaration or public alias before inventory reconciliation.
+ *
+ * Lua exports emerge from initialization values rather than declarations, so
+ * identity and reachable address remain separate until table ownership is known.
+ */
+export interface ILuaDeclaration {
+    /**
+     * Identifies the extracted value shared by aliases of that static value.
+     *
+     * This prevents several assignments or returned table paths from becoming
+     * several coverage units for one semantic declaration.
+     */
+    id: string;
+    /** Gives the canonical name selected for this public declaration.
+     *
+     * The adapter retains this source-derived spelling for unit naming and diagnostics while `address` carries its complete path.
+     */
+    name: string;
+    /** Classifies callable values as functions and tables or scalar fields as properties.
+     *
+     * This Evidence selector is assigned from static value shape without executing the Lua module.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /** Lists the file-local path that establishes this declaration's semantic identity.
+     *
+     * Alias projections share the identity of their original static value even when they publish another address.
+     */
+    identity: string[];
+    /** Lists the public path through which this occurrence projects the value.
+     *
+     * This can differ from `identity` when a local alias or returned table field exposes the same value.
+     */
+    address: string[];
+    /** Retains the physical source site and content used for Evidence hosts and fingerprints.
+     *
+     * Multiple alias projections can retain separate sites while materializing one semantic unit.
+     */
+    site: IEvidenceUnitSite;
+    /** States whether static initialization makes the value reachable through the public surface.
+     *
+     * The adapter keeps unreachable values for ownership analysis but excludes them from published units and addresses.
+     */
+    public: boolean;
+    /**
+     * Identifies the containing table declaration for a nested field.
+     *
+     * Parent withdrawal and visibility propagation follow this value instead of
+     * reconstructing ownership from a mutable Lua table path.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/lua/ILuaDeclaration.js

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

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

@@ -0,0 +1,31 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { ILuaDocumentationAttachment } from "./ILuaDocumentationAttachment";
+/**
+ * Represents a Lua documentation carrier or tag-bearing unsupported carrier.
+ *
+ * LuaDoc is retained independently of static value resolution so annotations on
+ * dynamic or detached source can be reported truthfully rather than discarded.
+ */
+export interface ILuaDocumentation {
+    /** Identifies this physical Lua documentation carrier within the scanned file.
+     *
+     * Attachments and generated hosts use this scanner-local ID, which does not name a semantic declaration.
+     */
+    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 delimiters and annotation-reading rules for this comment carrier.
+     *
+     * Documentation parsing uses the syntax instead of guessing from raw Lua source text.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /** Lists declaration sites that accept this carrier as attached LuaDoc.
+     *
+     * The scanner establishes attachment from source adjacency before static value reconciliation.
+     */
+    attachments: ILuaDocumentationAttachment[];
+}

package/lib/adapters/lua/ILuaDocumentation.js

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

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

@@ -0,0 +1,23 @@
+/**
+ * Connects a LuaDoc carrier to one extracted Lua declaration site.
+ *
+ * LuaFileScanner records this source-adjacent pair before static value handling,
+ * so the documentation pass can evaluate annotations without giving comments
+ * ownership of the declaration's semantic unit.
+ */
+export interface ILuaDocumentationAttachment {
+    /**
+     * Identifies the declaration extraction record that receives the LuaDoc.
+     *
+     * Consumers use this stable scanner-local ID to locate the declaration whose
+     * annotation needs evaluation.
+     */
+    declarationId: string;
+    /**
+     * Identifies the physical declaration site covered by the LuaDoc.
+     *
+     * This keeps an attachment at its adjacent source occurrence when aliases or
+     * table members cause one semantic unit to have several sites.
+     */
+    siteId: string;
+}

package/lib/adapters/lua/ILuaDocumentationAttachment.js

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

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

@@ -0,0 +1,39 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { ILuaDeclaration } from "./ILuaDeclaration";
+import type { ILuaDocumentation } from "./ILuaDocumentation";
+/**
+ * Holds the node-free Lua extraction retained after a parse session closes.
+ *
+ * Static initialization is interpreted only while scanning; this record carries
+ * the resulting public-value candidates into inventory materialization.
+ */
+export interface ILuaFileAnalysis {
+    /** Retains the selected Lua source file that produced this analysis.
+     *
+     * Its physical identity and configured addresses are used when units and comment hosts are materialized.
+     */
+    source: IEvidenceSourceFile;
+    /** Lists declarations and alias projections established by supported static initialization.
+     *
+     * `LuaAdapter` reconciles these node-free records into public units after scanning ends.
+     */
+    declarations: ILuaDeclaration[];
+    /** Lists classified LuaDoc and unsupported annotation carriers from this file.
+     *
+     * Tagged unsupported carriers remain available for diagnostics instead of silently disappearing.
+     */
+    documentation: ILuaDocumentation[];
+    /** Lists failures encountered while establishing the static public surface.
+     *
+     * The adapter forwards them into the inventory together with the `complete` boundary.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether static extraction understood every relevant source form.
+     *
+     * A false value keeps unsupported dynamic behavior visible to callers rather
+     * than treating an incomplete table projection as an empty public surface.
+     */
+    complete: boolean;
+}

package/lib/adapters/lua/ILuaFileAnalysis.js

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

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

@@ -0,0 +1,39 @@
+import type { Node } from "web-tree-sitter";
+import type { ILuaDeclaration } from "./ILuaDeclaration";
+/**
+ * Represents a statically understood Lua value during file scanning.
+ *
+ * LuaFileScanner keeps these records for bindings, table fields, aliases, and
+ * final module returns so it can construct public declarations without
+ * evaluating Lua; they are internal scanner state rather than serialized output.
+ */
+export interface ILuaValue {
+    /**
+     * Classifies the statically supported value without executing Lua.
+     *
+     * The scanner traverses `table` fields, emits `function` and `literal` values
+     * as declarations, and omits `nil` values from the public surface.
+     */
+    kind: "table" | "function" | "literal" | "nil";
+    /**
+     * Points to the source node that establishes this value's declaration site.
+     *
+     * LuaFileScanner derives a stable declaration ID and diagnostic location from
+     * this node, including a copied site for scalar alias assignments.
+     */
+    node: Node;
+    /**
+     * Maps statically named table fields to their understood values.
+     *
+     * Only `table` values populate this map; scalar, callable, and nil values use
+     * an empty map so table traversal has one uniform representation.
+     */
+    fields: Map<string, ILuaValue>;
+    /**
+     * Stores the declaration first published for this value's public path.
+     *
+     * Omission means the value is not yet public. Once set, aliases reuse this
+     * declaration to preserve one semantic identity across multiple addresses.
+     */
+    declaration?: ILuaDeclaration;
+}

package/lib/adapters/lua/ILuaValue.js

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

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

@@ -0,0 +1,114 @@
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Materializes statically established Lua declarations and documentation owners.
+ *
+ * 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 LuaAdapter implements IEvidenceAdapter {
+    /**
+     * 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.
+     */
+    readonly 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.
+     *
+     * LuaDocumentation 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;
+}