@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -0,0 +1,19 @@
+import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceScalaDocumentation } from "./IEvidenceScalaDocumentation";
+/**
+ * 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.
+ */
+export declare namespace EvidenceScalaDocumentation {
+    /**
+     * Maps a documentation carrier and masks examples without moving source
+     * offsets.
+     *
+     * Non-Scaladoc carriers retain the shared parser mapping unchanged because
+     * only Scaladoc supports example masking here.
+     */
+    function read(source: IEvidenceSourceFile, documentation: IEvidenceScalaDocumentation, hostId: string): IEvidenceDocumentation;
+}

package/lib/adapters/scala/EvidenceScalaDocumentation.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceScalaDocumentation = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+const EvidenceDocumentationExamples_1 = require("../../parsers/EvidenceDocumentationExamples");
+/**
+ * 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 EvidenceScalaDocumentation;
+(function (EvidenceScalaDocumentation) {
+    /**
+     * Maps a documentation carrier and masks examples without moving source
+     * 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),
+        };
+    }
+    EvidenceScalaDocumentation.read = read;
+    /**
+     * Masks Scaladoc brace blocks, HTML code, and indented Markdown examples.
+     *
+     * Fenced examples remain for the shared tag parser, and replacement spaces
+     * preserve every unmasked source position.
+     */
+    function mask(input) {
+        const characters = input.split("");
+        const markdown = EvidenceDocumentationExamples_1.EvidenceDocumentationExamples.markdownCode(input);
+        let opening;
+        for (const match of input.matchAll(/\{\{\{|\}\}\}/gu)) {
+            const index = match.index;
+            if (opening === undefined) {
+                if (match[0] === "{{{" && markdown[index] !== true)
+                    opening = index;
+            }
+            else if (match[0] === "}}}") {
+                hide(characters, opening, index + match[0].length);
+                opening = undefined;
+            }
+        }
+        if (opening !== undefined)
+            hide(characters, opening, input.length);
+        EvidenceDocumentationExamples_1.EvidenceDocumentationExamples.maskHtml(characters, input, ["pre", "code"]);
+        const lines = input.split("\n");
+        const indents = lines
+            .filter((line) => line.trim() !== "")
+            .map((line) => indentation(line));
+        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 indentation after the 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 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] = " ";
+    }
+})(EvidenceScalaDocumentation || (exports.EvidenceScalaDocumentation = EvidenceScalaDocumentation = {}));

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

@@ -0,0 +1,19 @@
+import type { IEvidenceScalaFileAnalysis } from "./IEvidenceScalaFileAnalysis";
+/**
+ * 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 EvidenceScalaExports {
+    /**
+     * 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: IEvidenceScalaFileAnalysis[]): void;
+}

package/lib/adapters/scala/EvidenceScalaExports.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceScalaExports = void 0;
+const EvidenceTagParser_1 = require("../../parsers/EvidenceTagParser");
+const EvidenceScalaDocumentation_1 = require("./EvidenceScalaDocumentation");
+/**
+ * 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 EvidenceScalaExports;
+(function (EvidenceScalaExports) {
+    /**
+     * 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;
+            }
+    }
+    EvidenceScalaExports.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",
+                    }, EvidenceScalaDocumentation_1.EvidenceScalaDocumentation.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;
+    }
+})(EvidenceScalaExports || (exports.EvidenceScalaExports = EvidenceScalaExports = {}));

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

@@ -0,0 +1,135 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceScalaFileAnalysis } from "./IEvidenceScalaFileAnalysis";
+/**
+ * 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 EvidenceScalaFileScanner {
+    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(): IEvidenceScalaFileAnalysis;
+    /**
+     * 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;
+}