@wrtnlabs/evidence 0.0.0

package/lib/adapters/go/GoFileScanner.js

@@ -0,0 +1,288 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoFileScanner = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const GoSyntax_1 = require("./GoSyntax");
+const SourcePath_1 = require("../../internal/SourcePath");
+const SourceText_1 = require("../../internal/SourceText");
+/**
+ * Extracts Go declarations and documentation before package-wide ownership resolution.
+ *
+ * It keeps physical sites and comment adjacency local to the file while
+ * `GoAdapter` assigns receiver members to their package-wide semantic owners.
+ */
+class GoFileScanner {
+    session;
+    source;
+    declarations = [];
+    documentation = new Map();
+    commentDocumentation = new Map();
+    diagnostics = [];
+    reported = new Set();
+    text;
+    complete = true;
+    /**
+     * Creates a scanner for one Go parse session and selected source file.
+     *
+     * Comment runs are captured first because Go documentation attachment depends
+     * on exact source adjacency rather than declaration-family reconciliation.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+        this.text = new SourceText_1.SourceText(source.content);
+        this.collectCommentRuns();
+    }
+    /**
+     * Extracts the package clause and supported exported declarations from one file.
+     *
+     * A missing package clause or unsupported relevant form is retained as an
+     * incomplete analysis so package materialization cannot hide it.
+     */
+    scan() {
+        const packageClause = this.session.root.namedChildren.find((node) => node.type === "package_clause");
+        const packageName = GoSyntax_1.GoSyntax.name(packageClause === undefined
+            ? null
+            : (packageClause.namedChildren[0] ?? null));
+        if (packageName === undefined)
+            this.problem("go-package", "The Go source has no statically readable package clause.", "Add one valid package clause before declaring public package members.", packageClause ?? this.session.root);
+        for (const statement of this.session.root.namedChildren)
+            switch (statement.type) {
+                case "type_declaration":
+                    this.scanTypes(statement);
+                    break;
+                case "function_declaration":
+                    this.scanFunction(statement);
+                    break;
+                case "method_declaration":
+                    this.scanMethod(statement);
+                    break;
+                case "const_declaration":
+                case "var_declaration":
+                    this.scanProperties(statement);
+                    break;
+            }
+        this.collectLiteralAnnotations();
+        return {
+            source: this.source,
+            directory: SourcePath_1.SourcePath.slash(node_path_1.default.dirname(this.source.physicalPath)),
+            ...(packageName === undefined ? {} : { packageName }),
+            testFile: this.source.physicalPath.endsWith("_test.go"),
+            declarations: this.declarations,
+            documentation: Array.from(this.documentation.values()),
+            diagnostics: this.diagnostics,
+            complete: this.complete,
+        };
+    }
+    scanTypes(statement) {
+        const specs = statement.namedChildren.filter((node) => node.type === "type_spec" || node.type === "type_alias");
+        for (const spec of specs) {
+            const name = GoSyntax_1.GoSyntax.name(spec.childForFieldName("name"));
+            if (name === undefined || !GoSyntax_1.GoSyntax.exported(name))
+                continue;
+            const form = spec.type === "type_alias" ? "type-alias" : "defined-type";
+            this.addDeclaration(statement, spec, name, "type", form);
+            const value = spec.childForFieldName("type");
+            if (value?.type === "struct_type")
+                this.scanStruct(value, name);
+            else if (value?.type === "interface_type")
+                this.scanInterface(value, name);
+        }
+    }
+    scanStruct(structure, owner) {
+        const body = structure.namedChildren.find((node) => node.type === "field_declaration_list");
+        for (const field of body?.namedChildren ?? []) {
+            if (field.type !== "field_declaration")
+                continue;
+            const declared = GoSyntax_1.GoSyntax.names(field, "field_identifier");
+            const names = declared.length !== 0
+                ? declared
+                : [GoSyntax_1.GoSyntax.embeddedField(field.childForFieldName("type"))].filter((name) => name !== undefined);
+            if (declared.length === 0 && names.length === 0)
+                this.problem("go-embedded-field", `Struct '${owner}' has an embedded field whose declared name cannot be established.`, "Use a named field or a direct named, pointer, qualified, or generic embedded type.", field);
+            for (const name of names)
+                if (GoSyntax_1.GoSyntax.exported(name))
+                    this.addDeclaration(field, field, name, "property", "field", owner);
+        }
+    }
+    scanInterface(contract, owner) {
+        for (const member of contract.namedChildren) {
+            if (member.type !== "method_elem")
+                continue;
+            const name = GoSyntax_1.GoSyntax.name(member.childForFieldName("name"));
+            if (name !== undefined && GoSyntax_1.GoSyntax.exported(name))
+                this.addDeclaration(member, member, name, "function", "interface-method", owner);
+        }
+    }
+    scanFunction(statement) {
+        const name = GoSyntax_1.GoSyntax.name(statement.childForFieldName("name"));
+        if (name !== undefined && GoSyntax_1.GoSyntax.exported(name))
+            this.addDeclaration(statement, statement, name, "function", "function");
+    }
+    scanMethod(statement) {
+        const name = GoSyntax_1.GoSyntax.name(statement.childForFieldName("name"));
+        if (name === undefined || !GoSyntax_1.GoSyntax.exported(name))
+            return;
+        const owner = GoSyntax_1.GoSyntax.receiver(statement);
+        if (owner === undefined) {
+            this.problem("go-receiver", `Exported method '${name}' has no statically readable named receiver.`, "Declare the method on a local named type with an optional pointer or generic receiver.", statement);
+            return;
+        }
+        if (!GoSyntax_1.GoSyntax.exported(owner))
+            return;
+        this.addDeclaration(statement, statement, name, "function", "method", owner);
+    }
+    scanProperties(statement) {
+        const specification = statement.type === "const_declaration" ? "const_spec" : "var_spec";
+        for (const spec of statement.descendantsOfType(specification))
+            for (const name of GoSyntax_1.GoSyntax.names(spec, "identifier"))
+                if (GoSyntax_1.GoSyntax.exported(name))
+                    this.addDeclaration(statement, spec, name, "property", "property");
+    }
+    addDeclaration(group, position, name, symbol, form, owner) {
+        const identity = owner === undefined ? [name] : [owner, name];
+        const declarationId = `go:${this.source.id}:declaration:${symbol}:${JSON.stringify(identity)}:${position.startIndex}`;
+        const content = this.session.range(position);
+        const grouped = !group.equals(position);
+        const groupSite = this.site(group, grouped ? [] : [content]);
+        const positionSite = grouped ? this.site(position, [content]) : groupSite;
+        const sites = groupSite.id === positionSite.id
+            ? [groupSite]
+            : [groupSite, positionSite];
+        this.declarations.push({
+            id: declarationId,
+            name,
+            symbol,
+            form,
+            ...(owner === undefined ? {} : { owner }),
+            positionSiteId: positionSite.id,
+            sites,
+        });
+        this.attachPreceding(group, declarationId, groupSite.id);
+        if (!group.equals(position))
+            this.attachPreceding(position, declarationId, positionSite.id);
+    }
+    site(node, content) {
+        return {
+            id: this.siteId(node),
+            file: this.source.physicalPath,
+            range: this.session.range(node),
+            content,
+        };
+    }
+    attachPreceding(node, declarationId, siteId) {
+        const previous = node.previousNamedSibling;
+        if (previous === null ||
+            previous.type !== "comment" ||
+            previous.startPosition.column !== node.startPosition.column)
+            return;
+        const documentation = this.commentDocumentation.get(this.nodeKey(previous));
+        if (documentation === undefined ||
+            !this.standalone(documentation.range.start.offset))
+            return;
+        if (/\r?\n[ \t]*\r?\n/u.test(this.source.content.slice(documentation.range.end.offset, node.startIndex)))
+            return;
+        if (!documentation.attachments.some((attachment) => attachment.declarationId === declarationId &&
+            attachment.siteId === siteId))
+            documentation.attachments.push({ declarationId, siteId });
+    }
+    collectCommentRuns() {
+        const comments = this.session.root
+            .descendantsOfType("comment")
+            .sort((left, right) => left.startIndex - right.startIndex);
+        const consumed = new Set();
+        for (const first of comments) {
+            if (consumed.has(this.nodeKey(first)))
+                continue;
+            const sequence = [first];
+            consumed.add(this.nodeKey(first));
+            let last = first;
+            if (first.text.startsWith("//") && this.standalone(first.startIndex)) {
+                let next = last.nextNamedSibling;
+                while (next !== null &&
+                    next.type === "comment" &&
+                    next.text.startsWith("//") &&
+                    this.standalone(next.startIndex) &&
+                    next.startPosition.column === first.startPosition.column &&
+                    !/\r?\n[ \t]*\r?\n/u.test(this.source.content.slice(last.endIndex, next.startIndex))) {
+                    sequence.push(next);
+                    consumed.add(this.nodeKey(next));
+                    last = next;
+                    next = last.nextNamedSibling;
+                }
+            }
+            const range = this.text.range(first.startIndex, last.endIndex);
+            const documentation = this.ensureDocumentation(range, GoSyntax_1.GoSyntax.comment(first));
+            for (const comment of sequence)
+                this.commentDocumentation.set(this.nodeKey(comment), documentation);
+        }
+    }
+    /**
+     * Keeps trailing source comments separate from the next declaration's documentation.
+     *
+     * Go attaches documentation only from the leading comment run, so a preceding
+     * declaration's trailing comment must not become evidence for the next one.
+     */
+    standalone(offset) {
+        const start = this.source.content.lastIndexOf("\n", offset - 1) + 1;
+        return /^[ \t]*$/u.test(this.source.content.slice(start, offset));
+    }
+    collectLiteralAnnotations() {
+        const literals = [
+            ...this.session.root.descendantsOfType("interpreted_string_literal"),
+            ...this.session.root.descendantsOfType("raw_string_literal"),
+        ];
+        for (const literal of literals) {
+            const syntax = GoSyntax_1.GoSyntax.literal(literal);
+            if (syntax === undefined)
+                continue;
+            const raw = this.source.content.slice(literal.startIndex + syntax.opening.length, literal.endIndex - syntax.closing.length);
+            if (this.annotation(raw))
+                this.ensureDocumentation(this.session.range(literal), syntax);
+        }
+    }
+    ensureDocumentation(range, syntax) {
+        const key = `${range.start.offset}:${range.end.offset}`;
+        let documentation = this.documentation.get(key);
+        if (documentation === undefined) {
+            documentation = {
+                id: `go:${this.source.id}:documentation:${key}`,
+                range,
+                syntax,
+                attachments: [],
+            };
+            this.documentation.set(key, documentation);
+        }
+        return documentation;
+    }
+    annotation(raw) {
+        return /(?:^|[\r\n])[ \t]*@(evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link|internal|hidden|ignore)\b/u.test(raw);
+    }
+    nodeKey(node) {
+        return `${node.startIndex}:${node.endIndex}`;
+    }
+    siteId(node) {
+        return `go:${this.source.id}:site:${this.nodeKey(node)}`;
+    }
+    problem(code, message, repair, node) {
+        const key = `${code}:${node.startIndex}:${node.endIndex}`;
+        if (this.reported.has(key))
+            return;
+        this.reported.add(key);
+        this.complete = false;
+        this.diagnostics.push({
+            code,
+            severity: "error",
+            message,
+            repair,
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.GoFileScanner = GoFileScanner;

package/lib/adapters/go/GoPackageResolver.d.ts

@@ -0,0 +1,147 @@
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IGoFileAnalysis } from "./IGoFileAnalysis";
+/**
+ * Reconciles selected Go files into package-wide Evidence units and addresses.
+ *
+ * GoAdapter supplies one analysis per source file because receiver methods may
+ * depend on types in another file; this resolver restores Go's package boundary
+ * before the shared inventory is published.
+ */
+export declare class GoPackageResolver {
+    /**
+     * File-local extractions selected for this adapter pass.
+     *
+     * Their directory and package names establish the package groups to resolve.
+     */
+    private readonly analyses;
+    /**
+     * Shared inventory that receives resolved units and reconciliation diagnostics.
+     *
+     * Its completeness flag is cleared whenever package resolution finds an error.
+     */
+    private readonly inventory;
+    /**
+     * Published units indexed by their package-wide semantic IDs.
+     *
+     * Materialization adds physical declaration sites to these units before they
+     * are appended to the caller-owned inventory.
+     */
+    private readonly units;
+    /**
+     * Unit IDs already associated with each package-local public identity.
+     *
+     * The resolver uses this map to report incompatible symbol kinds that would
+     * otherwise make one identity ambiguous.
+     */
+    private readonly identities;
+    /**
+     * Serialized addresses that have already been emitted for a unit.
+     *
+     * Several owner and member sources can contribute the same public address.
+     */
+    private readonly addresses;
+    /**
+     * Diagnostic fingerprints reported during this package reconciliation.
+     *
+     * Suppressing repeats keeps one input defect from producing redundant errors.
+     */
+    private readonly reported;
+    /**
+     * Creates a resolver for the selected Go file analyses and destination inventory.
+     *
+     * The analyses remain immutable input; published units, addresses, and
+     * diagnostics are added to the provided inventory during {@link publish}.
+     */
+    constructor(
+    /**
+     * File-local extractions selected for this adapter pass.
+     *
+     * Their directory and package names establish the package groups to resolve.
+     */
+    analyses: IGoFileAnalysis[], 
+    /**
+     * Shared inventory that receives resolved units and reconciliation diagnostics.
+     *
+     * Its completeness flag is cleared whenever package resolution finds an error.
+     */
+    inventory: IEvidenceInventory);
+    /**
+     * Resolves all selected declarations and publishes their package-wide units.
+     *
+     * The returned map lets GoAdapter associate scanner-local documentation with
+     * the unit ID that survived receiver and package-boundary reconciliation.
+     *
+     * @returns Scanner-local declaration IDs mapped to their published unit IDs.
+     */
+    publish(): Map<string, string>;
+    /**
+     * Adds one declaration to its resolved unit and publishes its public addresses.
+     *
+     * Compatible physical declarations contribute sites to one unit; conflicting
+     * declarations remain visible through diagnostics instead of being discarded.
+     */
+    private materialize;
+    /**
+     * Emits each configured source address that can publicly name a resolved unit.
+     *
+     * Member addresses inherit paths from both their own file and selected owner
+     * files, because either file may be the configured public entry point.
+     */
+    private publishAddresses;
+    /**
+     * Verifies that selected files form compatible ordinary and external test packages.
+     *
+     * Go permits one ordinary package and its matching `_test` package per
+     * directory; other combinations make package-wide identity unreliable.
+     */
+    private validatePackages;
+    /**
+     * Finds the ordinary package name represented by a test-only file selection.
+     *
+     * A lone package is its own base, while a matching external test package
+     * identifies the base through Go's required `_test` suffix.
+     */
+    private testPackageBase;
+    /**
+     * Records an incompatible-package diagnostic for every affected file group.
+     *
+     * The directory is the Go package boundary, so no unit from this group can be
+     * trusted as a single semantic package population.
+     */
+    private packageProblem;
+    /**
+     * Wraps a physical declaration with the package-wide ID it would publish under.
+     *
+     * This transient form keeps source context available while ownership checks
+     * determine whether the declaration is eligible for materialization.
+     */
+    private entry;
+    /**
+     * Serializes a stable unit ID from the Go package boundary and semantic identity.
+     *
+     * File paths are deliberately absent because declarations in several package
+     * files may represent one public unit.
+     */
+    private unitId;
+    /**
+     * Produces a package-scoped lookup key for an exported owner type name.
+     *
+     * The package component prevents same-named types in different directories
+     * from satisfying each other's methods.
+     */
+    private ownerKey;
+    /**
+     * Produces the normalized package identity shared by compatible file analyses.
+     *
+     * Both directory and package clause are required because either alone can
+     * collide across the selected source set.
+     */
+    private packageKey;
+    /**
+     * Adds one deduplicated package-resolution failure to the shared inventory.
+     *
+     * Reporting also marks the inventory incomplete, preventing a bad package
+     * population from appearing as successful reduced coverage.
+     */
+    private problem;
+}