@wrtnlabs/evidence 0.0.0

package/lib/adapters/scala/ScalaDocumentation.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScalaDocumentation = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+/**
+ * Reads Scaladoc while preserving source mappings and masking code examples.
+ *
+ * Evidence tag parsing receives the masked text so examples cannot create declarations, while original offsets remain valid for diagnostics and hosts.
+ */
+var ScalaDocumentation;
+(function (ScalaDocumentation) {
+    /**
+     * Maps a classified documentation carrier and masks ineligible examples without moving offsets.
+     *
+     * Non-Scaladoc carriers retain the shared parser mapping unchanged because only Scaladoc supports example masking here.
+     */
+    function read(source, documentation, hostId) {
+        const parsed = EvidenceDocumentation_1.EvidenceDocumentation.read(source.content, hostId, documentation.range, documentation.syntax);
+        if (documentation.syntax.opening !== "/**")
+            return parsed;
+        return {
+            ...parsed,
+            text: mask(parsed.text),
+        };
+    }
+    ScalaDocumentation.read = read;
+    /**
+     * Masks Scaladoc brace blocks, HTML code elements, and indented Markdown examples.
+     *
+     * Fenced examples are left for the shared tag parser, and replacement spaces preserve every unmasked source position.
+     */
+    function mask(input) {
+        const characters = input.split("");
+        for (const match of input.matchAll(/\{\{\{[\s\S]*?(?:\}\}\}|$)/gu))
+            hide(characters, match.index, match.index + match[0].length);
+        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 a line's Markdown indentation after its documentation delimiter is removed.
+     *
+     * Tabs advance to the next four-column boundary so mixed indentation uses the same threshold as spaces.
+     */
+    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 example characters with spaces while retaining original line boundaries.
+     *
+     * Newline and carriage-return characters remain intact so ranges and line numbers continue to map to source.
+     */
+    function hide(characters, start, end) {
+        for (let index = start; index < end; ++index)
+            if (characters[index] !== "\n" && characters[index] !== "\r")
+                characters[index] = " ";
+    }
+})(ScalaDocumentation || (exports.ScalaDocumentation = ScalaDocumentation = {}));

package/lib/adapters/scala/ScalaExports.d.ts

@@ -0,0 +1,16 @@
+import type { IScalaFileAnalysis } from "./IScalaFileAnalysis";
+/**
+ * Resolves named exports as alternate addresses of selected public source members.
+ *
+ * Export syntax has its own physical declaration and documentation site, while
+ * the forwarded member retains identity and withdrawal ownership at its source.
+ */
+export declare namespace ScalaExports {
+    /**
+     * Keeps source ownership and identity while attaching the export's own declaration site.
+     *
+     * Only one selected singleton owner can satisfy an export; ambiguity remains
+     * incomplete instead of choosing a same-named member from another object.
+     */
+    function resolve(analyses: IScalaFileAnalysis[]): void;
+}

package/lib/adapters/scala/ScalaExports.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScalaExports = void 0;
+const EvidenceTagParser_1 = require("../../parsers/EvidenceTagParser");
+const ScalaDocumentation_1 = require("./ScalaDocumentation");
+/**
+ * Resolves named exports as alternate addresses of selected public source members.
+ *
+ * Export syntax has its own physical declaration and documentation site, while
+ * the forwarded member retains identity and withdrawal ownership at its source.
+ */
+var ScalaExports;
+(function (ScalaExports) {
+    /**
+     * Keeps source ownership and identity while attaching the export's own declaration site.
+     *
+     * Only one selected singleton owner can satisfy an export; ambiguity remains
+     * incomplete instead of choosing a same-named member from another object.
+     */
+    function resolve(analyses) {
+        const declarations = analyses.flatMap((analysis) => analysis.declarations);
+        const hidden = withdrawals(analyses);
+        for (const analysis of analyses)
+            for (const exported of analysis.exports) {
+                if (hidden.has(exported.declaration.ownerDeclarationId ?? ""))
+                    continue;
+                let owners = [];
+                for (const path of exported.paths) {
+                    const candidates = declarations.filter((declaration) => (declaration.object || declaration.symbol !== "type") &&
+                        JSON.stringify(declaration.lookup) === JSON.stringify(path));
+                    owners =
+                        candidates.length === 1 && candidates[0]?.object === true
+                            ? candidates
+                            : [];
+                    if (candidates.length !== 0)
+                        break;
+                }
+                const candidate = owners.length === 1 ? owners[0] : undefined;
+                const owner = candidate !== undefined && staticObject(candidate, declarations)
+                    ? candidate
+                    : undefined;
+                const targets = owner === undefined
+                    ? []
+                    : declarations.filter((declaration) => declaration.ownerDeclarationId === owner.id &&
+                        declaration.name === exported.member &&
+                        declaration.public &&
+                        declaration.syntax !== "export_declaration");
+                const identities = new Set(targets.map((target) => `${target.symbol}:${JSON.stringify(target.identity)}`));
+                const target = identities.size === 1 ? targets[0] : undefined;
+                if (target === undefined ||
+                    [
+                        "class_definition",
+                        "trait_definition",
+                        "object_definition",
+                        "enum_definition",
+                        "package_object",
+                    ].includes(target.syntax) ||
+                    targets.some((candidate) => declarations.some((child) => child.ownerDeclarationId === candidate.id))) {
+                    analysis.complete = false;
+                    analysis.diagnostics.push({
+                        code: "scala-export-resolution",
+                        severity: "error",
+                        message: `Export '${exported.member}' requires one selected public object member without nested declarations. Missing, ambiguous, restricted, chained, and container exports cannot establish a complete surface.`,
+                        repair: "Select the declaring singleton object and export a named leaf member, or implement the required export resolution.",
+                        location: {
+                            file: analysis.source.physicalPath,
+                            range: exported.declaration.site.range,
+                        },
+                    });
+                    continue;
+                }
+                exported.declaration.public = true;
+                exported.declaration.name = target.name;
+                exported.declaration.identity = target.identity;
+                exported.declaration.symbol = target.symbol;
+                if (target.ownerDeclarationId === undefined)
+                    delete exported.declaration.ownerDeclarationId;
+                else
+                    exported.declaration.ownerDeclarationId = target.ownerDeclarationId;
+            }
+    }
+    ScalaExports.resolve = resolve;
+    /**
+     * Resolves lexical withdrawals before exports can expose alternate addresses.
+     *
+     * Attached withdrawal annotations seed hidden declarations, then explicit parent ownership propagates that state to descendants.
+     */
+    function withdrawals(analyses) {
+        const hidden = new Set();
+        const declarations = analyses.flatMap((analysis) => analysis.declarations);
+        for (const analysis of analyses)
+            for (const documentation of analysis.documentation) {
+                for (const attachment of documentation.attachments) {
+                    const parsed = EvidenceTagParser_1.EvidenceTagParser.parse(analysis.source.content, {
+                        id: documentation.id,
+                        file: analysis.source.physicalPath,
+                        range: documentation.range,
+                        origins: analysis.source.addresses.map((address) => address.absolute),
+                        siteId: attachment.siteId,
+                        unitIds: [attachment.declarationId],
+                        attachment: "attached",
+                    }, ScalaDocumentation_1.ScalaDocumentation.read(analysis.source, documentation, documentation.id));
+                    if (parsed.withdrawals.length !== 0)
+                        hidden.add(attachment.declarationId);
+                }
+            }
+        for (let previous = -1; previous !== hidden.size;) {
+            previous = hidden.size;
+            for (const declaration of declarations)
+                if (hidden.has(declaration.ownerDeclarationId ?? ""))
+                    hidden.add(declaration.id);
+        }
+        return hidden;
+    }
+    /**
+     * Requires an export owner path made entirely of singleton and package objects.
+     *
+     * Classes, traits, cycles, and unresolved parent records cannot supply a static source namespace for export resolution.
+     */
+    function staticObject(declaration, declarations) {
+        let current = declaration;
+        const visited = new Set();
+        while (current !== undefined) {
+            if (visited.has(current.id) ||
+                (!current.object && current.syntax !== "package_object"))
+                return false;
+            visited.add(current.id);
+            const parent = current.ownerDeclarationId;
+            current =
+                parent === undefined
+                    ? undefined
+                    : declarations.find((candidate) => candidate.id === parent);
+        }
+        return true;
+    }
+})(ScalaExports || (exports.ScalaExports = ScalaExports = {}));

package/lib/adapters/scala/ScalaFileScanner.d.ts

@@ -0,0 +1,111 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IScalaFileAnalysis } from "./IScalaFileAnalysis";
+/**
+ * Extracts explicit Scala 2/3 declarations while retaining unsupported surface boundaries.
+ *
+ * The scanner records lexical declarations and explicit exports separately so
+ * a later snapshot-wide pass can resolve singleton forwarding without inventing aliases.
+ */
+export declare class ScalaFileScanner {
+    private readonly session;
+    private readonly source;
+    /**
+     * Collects declaration records that remain valid after parsing closes.
+     *
+     * Each record retains source ranges and lexical ownership without holding a Tree-sitter node.
+     */
+    private readonly declarations;
+    /**
+     * Indexes Scaladoc and unsupported tag carriers by their original source offset.
+     *
+     * The offset permits adjacent declaration attachment without reparsing the carrier text.
+     */
+    private readonly documentation;
+    /**
+     * Collects explicit exports for resolution after every selected file is scanned.
+     *
+     * Deferring resolution lets a forwarding file find declarations from other selected sources.
+     */
+    private readonly exports;
+    /**
+     * Collects public-surface failures that prevent a passing smaller inventory.
+     *
+     * The returned analysis uses these diagnostics to mark extraction incomplete.
+     */
+    private readonly diagnostics;
+    /**
+     * Borrows syntax only during the common parser callback.
+     *
+     * Source identity and ranges are copied into the returned analysis because
+     * export resolution begins only after parser sessions have closed.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Produces a serializable inventory fragment.
+     *
+     * Documentation is collected first, then scopes are traversed without entering
+     * executable bodies, preserving source attachment and public-boundary semantics.
+     */
+    scan(): IScalaFileAnalysis;
+    /**
+     * Walks declaration scopes without descending into executable bodies or local definitions.
+     *
+     * Package clauses extend the current namespace, while nested declaration bodies establish lexical owners.
+     */
+    private scope;
+    /**
+     * Selects supported source declarations and their explicit lexical children.
+     *
+     * Unsupported public declaration forms are reported as incomplete instead of being guessed from syntax.
+     */
+    private visit;
+    /**
+     * Retains only statically bound value names from a Scala binding pattern.
+     *
+     * Identifiers, tuple patterns, and multi-name patterns expand into declarations; visible extractor or typed patterns report a boundary.
+     */
+    private bindings;
+    /**
+     * Creates one lexical declaration without synthesizing runtime or compiler members.
+     *
+     * The record captures visibility, address, lookup path, source site, and unsupported semantic boundaries for later publication.
+     */
+    private declare;
+    /**
+     * Determines whether a declaration is publicly visible through its lexical chain.
+     *
+     * Any private or protected modifier, or a restricted owner, excludes the declaration from the public population.
+     */
+    private visible;
+    /**
+     * Records supported named exports from selected singleton objects.
+     *
+     * Imports, wildcard selectors, givens, unqualified paths, and dynamic selectors report incomplete resolution rather than creating aliases.
+     */
+    private export;
+    /**
+     * Decodes a backticked Scala name into its literal accessor segment.
+     *
+     * Unquoted names retain their source text, while only the surrounding backticks are removed.
+     */
+    private name;
+    /**
+     * Attaches a Scaladoc carrier only when it immediately precedes a declaration through whitespace.
+     *
+     * Other comments, intervening syntax, and non-Scaladoc blocks remain unattached for unsupported-host handling.
+     */
+    private attach;
+    /**
+     * Classifies comments and tag-bearing literal strings without treating them as declarations.
+     *
+     * Scaladoc may attach to a declaration; other tag-shaped carriers remain available for diagnostics.
+     */
+    private collectDocumentation;
+    /**
+     * Reports an actionable incomplete-analysis boundary at the original syntax range.
+     *
+     * The repair directs authors toward supported explicit declarations before graph evaluation can use the inventory.
+     */
+    private problem;
+}