@wrtnlabs/evidence 0.0.0

package/lib/adapters/lua/LuaDocumentation.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LuaDocumentation = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+/**
+ * Reads Lua documentation while preserving source mappings and masking examples.
+ *
+ * LuaFileScanner supplies classified carriers to this boundary, which normalizes
+ * their text through the shared mapper and suppresses examples before the tag
+ * parser can treat them as Evidence annotations.
+ */
+var LuaDocumentation;
+(function (LuaDocumentation) {
+    /**
+     * Maps one classified carrier into shared documentation data.
+     *
+     * Example text is replaced after shared parsing preserves original offsets, so
+     * diagnostics and attachments still cite locations in the source file.
+     */
+    function read(source, documentation, hostId) {
+        const parsed = EvidenceDocumentation_1.EvidenceDocumentation.read(source.content, hostId, documentation.range, documentation.syntax);
+        return {
+            ...parsed,
+            text: mask(parsed.text),
+        };
+    }
+    LuaDocumentation.read = read;
+    /**
+     * Masks HTML examples and Markdown-indented code in parsed documentation text.
+     *
+     * Shared tag parsing already handles fenced code; this pass preserves all line
+     * boundaries while removing other example regions from annotation recognition.
+     */
+    function mask(input) {
+        const characters = input.split("");
+        const htmlCode = /<(pre|code)\b[^>]*>[\s\S]*?<\/\1\s*>/giu;
+        for (const match of input.matchAll(htmlCode))
+            hide(characters, match.index, match.index + match[0].length);
+        const lines = input.split("\n");
+        const indents = lines.filter((line) => line.trim() !== "").map(indentation);
+        const baseline = indents.reduce((minimum, indent) => Math.min(minimum, indent), Infinity);
+        let offset = 0;
+        for (const line of lines) {
+            if (indentation(line) >= baseline + 4)
+                hide(characters, offset, offset + line.length);
+            offset += line.length + 1;
+        }
+        return characters.join("");
+    }
+    /**
+     * Counts visual Markdown indentation after documentation delimiters are removed.
+     *
+     * Tabs advance to the next four-column boundary so indented-code detection
+     * follows Markdown's column semantics instead of raw character count.
+     */
+    function indentation(line) {
+        let spaces = 0;
+        for (const character of line) {
+            if (character === " ")
+                ++spaces;
+            else if (character === "\t")
+                spaces += 4 - (spaces % 4);
+            else
+                break;
+        }
+        return spaces;
+    }
+    /**
+     * Replaces an example span with spaces while retaining line boundaries.
+     *
+     * Keeping newlines and carriage returns preserves offsets shared with the
+     * original documentation carrier and prevents later source mappings from drifting.
+     */
+    function hide(characters, start, end) {
+        for (let index = start; index < end; ++index)
+            if (characters[index] !== "\n" && characters[index] !== "\r")
+                characters[index] = " ";
+    }
+})(LuaDocumentation || (exports.LuaDocumentation = LuaDocumentation = {}));

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

@@ -0,0 +1,167 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { ILuaFileAnalysis } from "./ILuaFileAnalysis";
+/**
+ * Resolves an explicit, non-executing Lua module initialization convention.
+ *
+ * Lua exports arise from values and table writes, so the scanner follows only
+ * supported static initialization and reports dynamic boundaries it cannot prove.
+ */
+export declare class LuaFileScanner {
+    private readonly session;
+    private readonly source;
+    /**
+     * Stores chunk-level bindings, including private local values.
+     *
+     * Static alias resolution consults this map before publishing globals or a
+     * returned module table, while function-local names use lexical lookup instead.
+     */
+    private readonly bindings;
+    /**
+     * Stores chunk globals that contribute independent public declarations.
+     *
+     * The scanner publishes these values after a returned table, preserving Lua's
+     * supported static global surface separately from module-table exports.
+     */
+    private readonly globals;
+    /**
+     * Retains the table returned by the supported module-return statement.
+     *
+     * Omission means no valid table return was found; a present table is published
+     * under the module address after all chunk initialization has been processed.
+     */
+    private returned;
+    /**
+     * Accumulates serializable public declarations and alias projections.
+     *
+     * Each publication contributes an address projection, while shared values reuse
+     * their first declaration identity to keep aliases from duplicating units.
+     */
+    private readonly declarations;
+    /**
+     * Indexes documentation carriers by the start offset of each comment line.
+     *
+     * Adjacent LuaDoc lines add keys for one extended carrier, allowing later
+     * declaration attachment to find that group's complete original source range.
+     */
+    private readonly documentation;
+    /**
+     * Collects diagnostics for unsupported surface-changing constructs.
+     *
+     * Any entry makes the returned file analysis incomplete, preventing dynamic
+     * Lua behavior from silently reducing the coverage population.
+     */
+    private readonly diagnostics;
+    /**
+     * Borrows the tree only for the active parser callback.
+     *
+     * The source remains authoritative for file identity and sites, while values
+     * are converted into serializable declarations before the session closes.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Establishes values and ownership before attaching documentation.
+     *
+     * Public aliases must resolve first so a comment attaches to the canonical
+     * declaration instead of a temporary local table projection.
+     */
+    scan(): ILuaFileAnalysis;
+    /**
+     * Processes deterministic chunk initialization without executing Lua.
+     *
+     * Only supported declarations, assignments, and one static module return can
+     * establish values; other chunk statements receive an incomplete-surface diagnostic.
+     */
+    private statement;
+    /**
+     * Reads one grammar list while excluding interleaved comments.
+     *
+     * Assignment and return handling need only semantic list entries, so comments
+     * cannot change arity checks or be mistaken for values.
+     */
+    private list;
+    /**
+     * Resolves one supported static value or an already established alias.
+     *
+     * Literal values receive the current declaration site, while table and function
+     * aliases retain identity so publication can preserve shared ownership.
+     */
+    private value;
+    /**
+     * Defines one binding or a previously absent literal table member.
+     *
+     * Reassignment, environment writes, and non-table owners are rejected because
+     * they can change a public declaration after its static identity is established.
+     */
+    private assign;
+    /**
+     * Adds one initial table field while rejecting replacement.
+     *
+     * Replacing a field could leave an obsolete declaration in the coverage
+     * denominator, so only the first non-nil static definition is retained.
+     */
+    private field;
+    /**
+     * Reads exact static accessor segments from a Lua expression.
+     *
+     * Numeric and computed keys are rejected instead of being conflated with string
+     * members, preserving the target spelling used for bindings and table fields.
+     */
+    private path;
+    /**
+     * Decodes a supported literal table key without changing its accessor spelling.
+     *
+     * Unescaped quoted and long strings have deterministic text; escaped strings
+     * require byte-string decoding and therefore produce a diagnostic instead.
+     */
+    private key;
+    /**
+     * Publishes a value address with one canonical identity and table owner.
+     *
+     * Recursive traversal projects table fields, detects cycles, and requires a
+     * shared value to retain the same structural owner across every public alias.
+     */
+    private publish;
+    /**
+     * Reports deferred writes and table escapes inside function bodies.
+     *
+     * Function execution can mutate an exported surface after chunk initialization,
+     * so the scanner marks writes, returns, and calls involving public tables incomplete.
+     */
+    private deferredMutations;
+    /**
+     * Detects exported-table references that may expose a mutable surface.
+     *
+     * Reads of known scalar or callable fields remain static, while passing a table,
+     * using `self`, or reaching an unknown field requires runtime alias analysis.
+     */
+    private tableReferences;
+    /**
+     * Resolves parameters and preceding lexical locals visible at one source node.
+     *
+     * The scope walk excludes later and sibling declarations so deferred-mutation
+     * checks do not mistake a local binding for a write to a public value.
+     */
+    private local;
+    /**
+     * Collects grouped LuaDoc lines and eligible long documentation comments.
+     *
+     * Unsupported tag-bearing carriers are also retained for diagnostics, while
+     * adjacent line comments become one carrier with an extended source range.
+     */
+    private comments;
+    /**
+     * Attaches an adjacent LuaDoc carrier to one static declaration site.
+     *
+     * Whitespace-only separation is permitted; any intervening syntax prevents
+     * attachment so a detached comment cannot annotate a later public declaration.
+     */
+    private attach;
+    /**
+     * Records one actionable diagnostic for an unproven public surface.
+     *
+     * Every unsupported boundary receives the original node range and makes this
+     * file's inventory incomplete, preserving failure instead of guessing exports.
+     */
+    private problem;
+}