@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/go/EvidenceGoPackageResolver.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceGoPackageResolver = void 0;
+/**
+ * Reconciles selected Go files into package-wide Evidence units and addresses.
+ *
+ * EvidenceGoAdapter 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.
+ */
+class EvidenceGoPackageResolver {
+    analyses;
+    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.
+     */
+    units = new Map();
+    /**
+     * 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.
+     */
+    identities = new Map();
+    /**
+     * Serialized addresses that have already been emitted for a unit.
+     *
+     * Several owner and member sources can contribute the same public address.
+     */
+    addresses = new Set();
+    /**
+     * Diagnostic fingerprints reported during this package reconciliation.
+     *
+     * Suppressing repeats keeps one input defect from producing redundant errors.
+     */
+    reported = new Set();
+    /**
+     * 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, 
+    /**
+     * Shared inventory that receives resolved units and reconciliation
+     * diagnostics.
+     *
+     * Its completeness flag is cleared whenever package resolution finds an
+     * error.
+     */
+    inventory) {
+        this.analyses = analyses;
+        this.inventory = inventory;
+    }
+    /**
+     * Resolves all selected declarations and publishes their package-wide units.
+     *
+     * The returned map lets EvidenceGoAdapter 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() {
+        this.validatePackages();
+        const entries = this.analyses.flatMap((analysis) => analysis.packageName === undefined
+            ? []
+            : analysis.declarations.map((declaration) => this.entry(analysis, declaration)));
+        const types = new Map();
+        for (const entry of entries) {
+            if (entry.declaration.symbol !== "type")
+                continue;
+            const key = this.ownerKey(entry.analysis, entry.declaration.name);
+            const declarations = types.get(key) ?? [];
+            declarations.push(entry);
+            types.set(key, declarations);
+        }
+        const published = new Map();
+        for (const entry of entries) {
+            const owner = entry.declaration.owner;
+            const owners = owner === undefined
+                ? []
+                : (types.get(this.ownerKey(entry.analysis, owner)) ?? []);
+            if (owner !== undefined) {
+                const eligible = entry.declaration.form === "method"
+                    ? owners.filter((candidate) => candidate.declaration.form === "defined-type")
+                    : owners;
+                if (eligible.length === 0) {
+                    const method = entry.declaration.form === "method";
+                    this.problem(method ? "go-receiver" : "go-owner", entry.analysis, method
+                        ? `Exported Go method '${owner}.${entry.declaration.name}' has no selected local defined receiver type.`
+                        : `Exported Go member '${owner}.${entry.declaration.name}' has no selected local owner type.`, method
+                        ? "Include the receiver's defined type in this package population or remove the method from the selected files."
+                        : "Include the owning type declaration in this package population.", JSON.stringify([entry.declaration.id, "owner"]));
+                    continue;
+                }
+            }
+            this.materialize(entry, owners);
+            published.set(entry.declaration.id, entry.unitId);
+        }
+        this.inventory.units.push(...this.units.values());
+        return published;
+    }
+    /**
+     * 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.
+     */
+    materialize(entry, owners) {
+        const declaration = entry.declaration;
+        const identity = declaration.owner === undefined
+            ? [declaration.name]
+            : [declaration.owner, declaration.name];
+        const identityKey = JSON.stringify([
+            this.packageKey(entry.analysis),
+            identity,
+        ]);
+        const previousIdentity = this.identities.get(identityKey);
+        if (previousIdentity !== undefined && previousIdentity !== entry.unitId)
+            this.problem("go-identity-conflict", entry.analysis, `Go public identity '${identity.join(".")}' is declared with conflicting symbol kinds.`, "Rename one declaration or select a source set with one compatible public identity.", `${identityKey}:kind`);
+        else
+            this.identities.set(identityKey, entry.unitId);
+        let unit = this.units.get(entry.unitId);
+        if (unit === undefined) {
+            unit = {
+                id: entry.unitId,
+                type: "go",
+                symbol: declaration.symbol,
+                identity,
+                name: declaration.name,
+                sites: structuredClone(declaration.sites),
+                withdrawals: [],
+                ...(declaration.owner === undefined
+                    ? {}
+                    : {
+                        parentId: this.unitId(entry.analysis, "type", [
+                            declaration.owner,
+                        ]),
+                    }),
+            };
+            this.units.set(entry.unitId, unit);
+        }
+        else {
+            this.problem("go-declaration-conflict", entry.analysis, `Go public identity '${identity.join(".")}' has more than one selected declaration.`, "Narrow the configured source set or remove declarations duplicated across build-constrained files.", `${identityKey}:duplicate`);
+            for (const site of declaration.sites)
+                if (!unit.sites.some((candidate) => candidate.id === site.id))
+                    unit.sites.push(structuredClone(site));
+        }
+        this.publishAddresses(entry, owners);
+    }
+    /**
+     * 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.
+     */
+    publishAddresses(entry, owners) {
+        const identity = entry.declaration.owner === undefined
+            ? [entry.declaration.name]
+            : [entry.declaration.owner, entry.declaration.name];
+        const sources = [
+            entry.analysis.source,
+            ...owners.map((owner) => owner.analysis.source),
+        ];
+        for (const source of sources)
+            for (const location of source.addresses) {
+                const address = {
+                    unitId: entry.unitId,
+                    file: location.absolute,
+                    segments: identity,
+                };
+                const key = JSON.stringify(address);
+                if (this.addresses.has(key))
+                    continue;
+                this.addresses.add(key);
+                this.inventory.addresses.push(address);
+            }
+    }
+    /**
+     * 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.
+     */
+    validatePackages() {
+        const directories = new Map();
+        for (const analysis of this.analyses) {
+            if (analysis.packageName === undefined)
+                continue;
+            const files = directories.get(analysis.directory) ?? [];
+            files.push(analysis);
+            directories.set(analysis.directory, files);
+        }
+        for (const [directory, files] of directories) {
+            const ordinary = new Set(files.flatMap((file) => !file.testFile && file.packageName !== undefined
+                ? [file.packageName]
+                : []));
+            if (ordinary.size > 1) {
+                this.packageProblem(directory, files);
+                continue;
+            }
+            const base = Array.from(ordinary)[0] ??
+                this.testPackageBase(files.map((file) => file.packageName));
+            if (base === undefined ||
+                files.some((file) => file.packageName !== base &&
+                    !(file.testFile && file.packageName === `${base}_test`)))
+                this.packageProblem(directory, files);
+        }
+    }
+    /**
+     * 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.
+     */
+    testPackageBase(names) {
+        const packages = Array.from(new Set(names.filter((name) => name !== undefined)));
+        if (packages.length === 1)
+            return packages[0];
+        return packages.find((name) => packages.includes(`${name}_test`));
+    }
+    /**
+     * 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.
+     */
+    packageProblem(directory, analyses) {
+        const names = Array.from(new Set(analyses.map((analysis) => analysis.packageName)))
+            .filter((name) => name !== undefined)
+            .sort((left, right) => left.localeCompare(right, "en"));
+        this.problem("go-package-boundary", analyses[0], `Selected Go directory '${directory}' contains incompatible packages: ${names.join(", ")}.`, "Select one ordinary package and, when needed, only its matching external _test package.", JSON.stringify([directory, names, "packages"]));
+    }
+    /**
+     * 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.
+     */
+    entry(analysis, declaration) {
+        const identity = declaration.owner === undefined
+            ? [declaration.name]
+            : [declaration.owner, declaration.name];
+        return {
+            analysis,
+            declaration,
+            unitId: this.unitId(analysis, declaration.symbol, identity),
+        };
+    }
+    /**
+     * 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.
+     */
+    unitId(analysis, symbol, identity) {
+        return `go:${this.packageKey(analysis)}:${symbol}:${JSON.stringify(identity)}`;
+    }
+    /**
+     * 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.
+     */
+    ownerKey(analysis, name) {
+        return JSON.stringify([this.packageKey(analysis), name]);
+    }
+    /**
+     * 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.
+     */
+    packageKey(analysis) {
+        return JSON.stringify([analysis.directory, analysis.packageName]);
+    }
+    /**
+     * 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.
+     */
+    problem(code, analysis, message, repair, key) {
+        if (this.reported.has(key))
+            return;
+        this.reported.add(key);
+        this.inventory.complete = false;
+        this.inventory.diagnostics.push({
+            code,
+            severity: "error",
+            message,
+            repair,
+            ...(analysis === undefined
+                ? {}
+                : { location: { file: analysis.source.physicalPath } }),
+        });
+    }
+}
+exports.EvidenceGoPackageResolver = EvidenceGoPackageResolver;

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

@@ -0,0 +1,18 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+/**
+ * Grammar-specific Go spelling and ownership helpers.
+ *
+ * Go extraction uses these helpers to recognize exported identifiers,
+ * receivers, embedded fields, comments, and literal carriers directly from
+ * Tree-sitter nodes.
+ */
+export declare namespace EvidenceGoSyntax {
+    function name(node: EvidenceNode | null): string | undefined;
+    function names(node: EvidenceNode, type: string): string[];
+    function exported(name: string): boolean;
+    function receiver(node: EvidenceNode): string | undefined;
+    function embeddedField(node: EvidenceNode | null): string | undefined;
+    function comment(node: EvidenceNode): IEvidenceCommentSyntax;
+    function literal(node: EvidenceNode): IEvidenceCommentSyntax | undefined;
+}

package/lib/adapters/go/EvidenceGoSyntax.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceGoSyntax = void 0;
+/**
+ * Grammar-specific Go spelling and ownership helpers.
+ *
+ * Go extraction uses these helpers to recognize exported identifiers,
+ * receivers, embedded fields, comments, and literal carriers directly from
+ * Tree-sitter nodes.
+ */
+var EvidenceGoSyntax;
+(function (EvidenceGoSyntax) {
+    function name(node) {
+        return node !== null &&
+            (node.type === "identifier" ||
+                node.type === "field_identifier" ||
+                node.type === "type_identifier" ||
+                node.type === "package_identifier")
+            ? node.text
+            : undefined;
+    }
+    EvidenceGoSyntax.name = name;
+    function names(node, type) {
+        return node.namedChildren
+            .filter((child) => child.type === type)
+            .map((child) => child.text);
+    }
+    EvidenceGoSyntax.names = names;
+    function exported(name) {
+        const first = Array.from(name)[0];
+        return first !== undefined && /^\p{Lu}$/u.test(first);
+    }
+    EvidenceGoSyntax.exported = exported;
+    function receiver(node) {
+        const parameters = node.childForFieldName("receiver");
+        if (parameters === null)
+            return undefined;
+        const declaration = parameters.namedChildren.find((child) => child.type === "parameter_declaration");
+        return receiverName(declaration === undefined ? null : declaration.childForFieldName("type"));
+    }
+    EvidenceGoSyntax.receiver = receiver;
+    function embeddedField(node) {
+        return typeName(node);
+    }
+    EvidenceGoSyntax.embeddedField = embeddedField;
+    function comment(node) {
+        if (node.text.startsWith("//"))
+            return {
+                opening: "//",
+                closing: "",
+                linePrefix: "//",
+                tagBoundaries: true,
+                allowWithdrawal: true,
+            };
+        return {
+            opening: "/*",
+            closing: "*/",
+            linePrefix: "*",
+            tagBoundaries: true,
+            allowWithdrawal: true,
+        };
+    }
+    EvidenceGoSyntax.comment = comment;
+    function literal(node) {
+        if (node.type === "interpreted_string_literal")
+            return {
+                opening: '"',
+                closing: '"',
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        if (node.type === "raw_string_literal")
+            return {
+                opening: "`",
+                closing: "`",
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        return undefined;
+    }
+    EvidenceGoSyntax.literal = literal;
+    function typeName(node) {
+        if (node === null)
+            return undefined;
+        const direct = name(node);
+        if (direct !== undefined)
+            return direct;
+        if (node.type === "qualified_type")
+            return name(node.childForFieldName("name"));
+        if (node.type === "generic_type")
+            return typeName(node.childForFieldName("type"));
+        if (node.type === "pointer_type" || node.type === "parenthesized_type")
+            return typeName(node.namedChildren[0] ?? null);
+        return undefined;
+    }
+    function receiverName(node) {
+        if (node === null)
+            return undefined;
+        const direct = name(node);
+        if (direct !== undefined)
+            return direct;
+        if (node.type === "generic_type")
+            return receiverName(node.childForFieldName("type"));
+        if (node.type === "pointer_type" || node.type === "parenthesized_type")
+            return receiverName(node.namedChildren[0] ?? null);
+        return undefined;
+    }
+})(EvidenceGoSyntax || (exports.EvidenceGoSyntax = EvidenceGoSyntax = {}));

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

@@ -0,0 +1,58 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { EvidenceGoDeclarationForm } from "./EvidenceGoDeclarationForm";
+/**
+ * Records one exported Go declaration before package-wide ownership is
+ * resolved.
+ *
+ * EvidenceGoFileScanner creates these physical records, and
+ * EvidenceGoPackageResolver combines compatible records into the semantic units
+ * that Evidence publishes.
+ */
+export interface IEvidenceGoDeclaration {
+    /**
+     * Scanner-local identifier used to attach documentation before
+     * reconciliation.
+     *
+     * The resolver replaces this physical key with a package-wide unit ID.
+     */
+    id: string;
+    /**
+     * Unqualified exported name displayed by the resulting evidence unit.
+     *
+     * A member's owner, when present, supplies the preceding identity segment.
+     */
+    name: string;
+    /**
+     * Common graph category assigned to the declaration's Go symbol.
+     *
+     * This lets downstream selection use the language-independent symbol model.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Go syntax form used to resolve receivers and compatible declarations.
+     *
+     * Package materialization accepts only local defined types as method
+     * receivers.
+     */
+    form: EvidenceGoDeclarationForm;
+    /**
+     * Exported enclosing type name for a member or receiver method.
+     *
+     * Omission means that the declaration belongs directly to the package
+     * surface.
+     */
+    owner?: string;
+    /**
+     * Physical declaration-site identifier used when attaching evidence hosts.
+     *
+     * It remains distinct even when several sites materialize one semantic unit.
+     */
+    positionSiteId: string;
+    /**
+     * Physical source spans that contribute this declaration's evidence content.
+     *
+     * The resolver preserves every compatible site in the published unit.
+     */
+    sites: IEvidenceUnitSite[];
+}

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

@@ -0,0 +1,37 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceGoDocumentationAttachment } from "./IEvidenceGoDocumentationAttachment";
+/**
+ * Retains a Go documentation carrier and its scanner-established attachments.
+ *
+ * EvidenceGoAdapter reads these records after parsing closes to create
+ * documentation hosts and report unsupported annotations without reinterpreting
+ * the source.
+ */
+export interface IEvidenceGoDocumentation {
+    /**
+     * Stable comment-run identifier referenced by scanner attachments.
+     *
+     * It identifies source text rather than a semantic package member.
+     */
+    id: string;
+    /**
+     * Exact source range decoded as documentation and excluded from fingerprints.
+     *
+     * The range also anchors diagnostics for unsupported annotations.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Line-comment syntax used to recover normalized documentation text.
+     *
+     * Evidence parsing relies on this captured syntax after parsing closes.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Declaration sites accepted as the comment run's direct owners.
+     *
+     * Package reconciliation does not attach it to same-named declarations
+     * elsewhere.
+     */
+    attachments: IEvidenceGoDocumentationAttachment[];
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Connects a Go documentation carrier to one physical declaration site.
+ *
+ * EvidenceGoFileScanner establishes this adjacency, and EvidenceGoAdapter later
+ * maps the local declaration to its package-wide unit without transferring the
+ * comment.
+ */
+export interface IEvidenceGoDocumentationAttachment {
+    /**
+     * Scanner-local declaration that owns the adjacent Go comment run.
+     *
+     * The adapter resolves it to a package-wide semantic unit later.
+     */
+    declarationId: string;
+    /**
+     * Physical declaration site that becomes the evidence host.
+     *
+     * A shared Go unit can still retain documentation at several source sites.
+     */
+    siteId: string;
+}

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

@@ -0,0 +1,61 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceGoDeclaration } from "./IEvidenceGoDeclaration";
+import type { IEvidenceGoDocumentation } from "./IEvidenceGoDocumentation";
+/**
+ * Stores a node-free extraction of one Go source file after parsing closes.
+ *
+ * EvidenceGoAdapter collects these file fragments, while
+ * EvidenceGoPackageResolver uses their directory and package context to publish
+ * package-wide evidence units.
+ */
+export interface IEvidenceGoFileAnalysis {
+    /**
+     * Source snapshot from which this package fragment was extracted.
+     *
+     * Its addresses become public file paths after package reconciliation.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Normalized directory used to group Go files into one package scope.
+     *
+     * Directory identity prevents same-named packages from being merged globally.
+     */
+    directory: string;
+    /**
+     * Package clause name when the source supplied a statically readable clause.
+     *
+     * Omission is an extraction failure, not an empty package.
+     */
+    packageName?: string;
+    /**
+     * Whether this file belongs to Go's test package surface.
+     *
+     * Package materialization uses it to preserve Go's separate test visibility.
+     */
+    testFile: boolean;
+    /**
+     * Exported declaration records awaiting package-wide receiver resolution.
+     *
+     * Records remain physical so their documentation sites stay distinct.
+     */
+    declarations: IEvidenceGoDeclaration[];
+    /**
+     * Comment runs and their scanner-established declaration attachments.
+     *
+     * Unattached annotation carriers are retained for actionable diagnostics.
+     */
+    documentation: IEvidenceGoDocumentation[];
+    /**
+     * Problems that make this package fragment incomplete.
+     *
+     * The adapter preserves them instead of silently dropping declarations.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * Whether relevant supported source constructs were fully extracted.
+     *
+     * False propagates through package materialization to coverage evaluation.
+     */
+    complete: boolean;
+}

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

@@ -0,0 +1,28 @@
+import type { IEvidenceGoDeclaration } from "./IEvidenceGoDeclaration";
+import type { IEvidenceGoFileAnalysis } from "./IEvidenceGoFileAnalysis";
+/**
+ * Associates one physical Go declaration with its package-wide semantic unit.
+ *
+ * EvidenceGoPackageResolver uses this transient record to collect declaration
+ * sites, resolve receiver ownership, and emit public addresses for the unit.
+ */
+export interface IEvidenceGoMaterializedDeclaration {
+    /**
+     * File analysis owning the declaration's physical source and package context.
+     *
+     * It supplies file paths and documentation during final materialization.
+     */
+    analysis: IEvidenceGoFileAnalysis;
+    /**
+     * Original scanner record contributing one site to the semantic unit.
+     *
+     * Receiver ownership may cause several records to share `unitId`.
+     */
+    declaration: IEvidenceGoDeclaration;
+    /**
+     * Package-wide semantic identity assigned after receiver resolution.
+     *
+     * This ID, rather than the scanner key, drives graph coverage counting.
+     */
+    unitId: string;
+}