@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/zig/EvidenceZigFileScanner.js

@@ -0,0 +1,559 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceZigFileScanner = void 0;
+const _assertGuard_1 = __importStar(require("typia/lib/internal/_assertGuard"));
+const typia_1 = __importDefault(require("typia"));
+/**
+ * Reads declared Zig namespaces without evaluating build or comptime code.
+ *
+ * It preserves physical declarations and alias projections separately, allowing
+ * later materialization to publish several paths for one semantic unit.
+ */
+class EvidenceZigFileScanner {
+    session;
+    source;
+    /**
+     * Collects serializable declarations, including intentional alias
+     * projections.
+     *
+     * Each entry preserves its physical site and public path before the parser
+     * session closes and later reconciliation merges aliases into canonical
+     * units.
+     */
+    declarations = [];
+    /**
+     * Indexes documentation carriers by their adjacent source-line position.
+     *
+     * Declaration attachment uses this grouping to find contiguous triple-slash
+     * comments without attaching ordinary comments or string literals by
+     * proximity.
+     */
+    documentation = new Map();
+    /**
+     * Collects unsupported public forms that prevent a complete population.
+     *
+     * The scan result uses a nonempty set to preserve extraction uncertainty in
+     * the final inventory instead of certifying only the recognized
+     * declarations.
+     */
+    diagnostics = [];
+    /**
+     * Borrows the real syntax tree for the bounded parser callback.
+     *
+     * The scanner copies source identity and ranges into records before
+     * returning, so no inventory state relies on a parser node after the callback
+     * ends.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+    }
+    /**
+     * Extracts explicit public declarations and classified annotation carriers.
+     *
+     * Carrier collection precedes alias resolution so documentation retains its
+     * original site while reconciliation decides which unit receives it.
+     */
+    scan() {
+        this.collectDocumentation();
+        this.scope(this.session.root, undefined, [], new Set());
+        return {
+            source: this.source,
+            declarations: this.declarations,
+            documentation: [...this.documentation.values()],
+            diagnostics: this.diagnostics,
+            complete: this.diagnostics.length === 0,
+        };
+    }
+    /**
+     * Visits supported namespace members while excluding local function bodies
+     * and tests.
+     *
+     * Only namespace scope can establish declared public surface, so unsupported
+     * comptime execution and namespace injection become incomplete diagnostics.
+     */
+    scope(body, owner, canonical, visited) {
+        for (const node of body.namedChildren) {
+            if (node.type === "comment" || node.type === "test_declaration")
+                continue;
+            if (node.type === "comptime_declaration") {
+                this.problem("comptime", "Namespace comptime execution may change exported declarations and cannot be evaluated from source.", node);
+                continue;
+            }
+            const field = node.type === "container_field";
+            if (field &&
+                body.type === "enum_declaration" &&
+                node.childForFieldName("name")?.text === "_")
+                continue;
+            const visible = field || node.children.some((child) => child.text === "pub");
+            if (node.type === "using_namespace_declaration") {
+                // Private namespace imports can also participate in public name lookup.
+                this.problem("usingnamespace", "Namespace injection requires resolving all imported public members and lookup conflicts.", node);
+                continue;
+            }
+            if (!visible)
+                continue;
+            if (![
+                "variable_declaration",
+                "function_declaration",
+                "container_field",
+            ].includes(node.type)) {
+                this.problem("source-form", `Unsupported public Zig namespace member '${node.type}'.`, node);
+                continue;
+            }
+            this.declaration(node, body, owner, canonical, undefined, visited);
+        }
+    }
+    /**
+     * Resolves bounded local aliases and establishes container ownership.
+     *
+     * Recursion is restricted to declarations in the current lexical container,
+     * preserving canonical identity while rejecting cycles and ambiguous
+     * targets.
+     */
+    declaration(node, scope, owner, canonical, exposed, visited) {
+        if (visited.has(node.startIndex)) {
+            this.problem("alias-cycle", "A public alias has cyclic local declaration ownership.", node);
+            return undefined;
+        }
+        const next = new Set(visited).add(node.startIndex);
+        const nameNode = node.childForFieldName("name") ??
+            node.namedChildren.find((child) => child.type === "identifier");
+        if (nameNode === undefined ||
+            nameNode === null ||
+            nameNode.type !== "identifier") {
+            this.problem("declaration-name", "A public field or declaration has no supported literal name; tuple fields require numeric ownership.", node);
+            return undefined;
+        }
+        const name = this.name(nameNode);
+        const duplicates = scope.namedChildren.filter((child) => {
+            const candidate = child.childForFieldName("name") ??
+                (child.type === "variable_declaration"
+                    ? child.namedChildren.find((part) => part.type === "identifier")
+                    : undefined);
+            return (candidate !== null &&
+                candidate !== undefined &&
+                this.name(candidate) === name);
+        });
+        if (duplicates.length > 1)
+            this.problem("duplicate-name", "This public namespace contains conflicting declarations with the same name.", node);
+        const address = [...(owner?.address ?? []), exposed ?? name];
+        const initializer = this.initializer(node);
+        const declaredType = node.childForFieldName("type");
+        const declaredMeta = declaredType !== null &&
+            this.metaType(declaredType, scope, new Set());
+        if (node.type === "variable_declaration" &&
+            (declaredType === null || declaredMeta) &&
+            node.children.some((child) => child.text === "const") &&
+            initializer?.type === "identifier") {
+            const matches = scope.namedChildren.filter((child) => ["variable_declaration", "function_declaration"].includes(child.type) &&
+                this.sameName(child.childForFieldName("name") ??
+                    child.namedChildren.find((part) => part.type === "identifier"), initializer));
+            const target = matches[0];
+            if (matches.length !== 1 || target === undefined) {
+                this.problem("alias-unresolved", "The public alias does not resolve to one declaration in its lexical container.", node);
+                return undefined;
+            }
+            if (this.scalar(target, scope, new Set()))
+                return this.add(node, name, "property", owner, [...canonical, name], address, false);
+            const original = this.declaration(target, scope, owner, canonical, exposed ?? name, next);
+            if (original === undefined)
+                return undefined;
+            const alias = this.add(node, original.name, original.symbol, owner, original.identity, address, true);
+            return alias;
+        }
+        const container = initializer !== undefined && CONTAINERS.has(initializer.type)
+            ? initializer
+            : undefined;
+        const primitiveType = initializer !== undefined && TYPE_FORMS.has(initializer.type);
+        const symbol = node.type === "container_field"
+            ? "property"
+            : node.type === "function_declaration"
+                ? "function"
+                : container !== undefined || primitiveType || declaredMeta
+                    ? "type"
+                    : "property";
+        const declaration = this.add(node, name, symbol, owner, [...canonical, name], address, exposed !== undefined);
+        if (node.type === "function_declaration") {
+            const returnType = node.childForFieldName("type");
+            const parameters = node.namedChildren.find((child) => child.type === "parameters");
+            const generic = parameters !== undefined &&
+                parameters.namedChildren.some((parameter) => parameter.children.some((child) => child.text === "comptime" || child.text === "anytype"));
+            if ((returnType !== null &&
+                this.metaType(returnType, scope, new Set())) ||
+                (returnType !== null &&
+                    (returnType.descendantsOfType([
+                        ...CONTAINERS,
+                        "builtin_function",
+                        "call_expression",
+                        "if_type_expression",
+                    ]).length !== 0 ||
+                        [
+                            ...CONTAINERS,
+                            "builtin_function",
+                            "call_expression",
+                            "if_type_expression",
+                        ].includes(returnType.type))) ||
+                (generic && returnType?.type !== "builtin_type"))
+                this.problem("type-producing-function", "Public type-producing or dependent generic return types require comptime instantiation to establish their reachable members.", node);
+            return declaration;
+        }
+        if (primitiveType &&
+            initializer !== undefined &&
+            initializer.descendantsOfType([
+                ...CONTAINERS,
+                "builtin_function",
+                "call_expression",
+                "if_type_expression",
+            ]).length !== 0)
+            this.problem("compound-type", "A compound public type contains anonymous or computed members requiring static ownership resolution.", node);
+        if (container !== undefined) {
+            if (container.type === "error_set_declaration") {
+                for (const member of container.namedChildren.filter((child) => child.type === "identifier")) {
+                    const memberName = this.name(member);
+                    this.add(member, memberName, "property", declaration, [...declaration.identity, memberName], [...address, memberName], false);
+                }
+            }
+            else
+                this.scope(container, declaration, declaration.identity, next);
+        }
+        else if (initializer?.type === "anonymous_struct_initializer") {
+            this.problem("anonymous-value", "Anonymous aggregate values require inferred field and tuple ownership; declare an explicit named container.", node);
+        }
+        else if (initializer !== undefined &&
+            declaredType === null &&
+            !VALUE_FORMS.has(initializer.type) &&
+            !primitiveType) {
+            this.problem("inferred-surface", "An inferred public value may expose a type, namespace, or generated members. Import, conditional, call, and comptime expressions require static ownership resolution.", node);
+        }
+        else if (declaredMeta && container === undefined && !primitiveType) {
+            this.problem("generated-type", "A public type value requires resolving its complete member surface without executing comptime code.", node);
+        }
+        if (declaredType !== null &&
+            ([
+                ...CONTAINERS,
+                "builtin_function",
+                "call_expression",
+                "if_type_expression",
+            ].includes(declaredType.type) ||
+                declaredType.descendantsOfType([
+                    ...CONTAINERS,
+                    "builtin_function",
+                    "call_expression",
+                    "if_type_expression",
+                ]).length !== 0))
+            this.problem("anonymous-field-type", "An anonymous or computed public declaration type requires nested member ownership; give the type an explicit declaration.", node);
+        return declaration;
+    }
+    /**
+     * Recognizes aliases of Zig's metatype in function return positions without
+     * execution.
+     *
+     * Type-producing returns require complete member discovery, so recognizing
+     * them allows the scanner to retain an incomplete boundary rather than infer
+     * one.
+     */
+    metaType(node, scope, visited) {
+        if (node.text === "type")
+            return true;
+        if (node.type !== "identifier" || visited.has(node.startIndex))
+            return false;
+        visited.add(node.startIndex);
+        const target = scope.namedChildren.find((child) => child.type === "variable_declaration" &&
+            this.sameName(child.namedChildren.find((part) => part.type === "identifier"), node));
+        const initializer = target === undefined ? undefined : this.initializer(target);
+        return (initializer !== undefined && this.metaType(initializer, scope, visited));
+    }
+    /**
+     * Distinguishes copied scalar values from identity-preserving namespace
+     * aliases.
+     *
+     * A scalar alias becomes its own property declaration; other aliases recurse
+     * to their original declaration so they share semantic identity and
+     * ownership.
+     */
+    scalar(node, scope, visited) {
+        if (visited.has(node.startIndex) || node.type !== "variable_declaration")
+            return false;
+        visited.add(node.startIndex);
+        const declared = node.childForFieldName("type");
+        if (declared !== null)
+            return declared.type === "builtin_type" && declared.text !== "type";
+        const initializer = this.initializer(node);
+        if (initializer === undefined)
+            return false;
+        if (VALUE_FORMS.has(initializer.type))
+            return true;
+        if (initializer.type !== "identifier")
+            return false;
+        const matches = scope.namedChildren.filter((child) => child.type === "variable_declaration" &&
+            this.sameName(child.namedChildren.find((part) => part.type === "identifier"), initializer));
+        const target = matches[0];
+        return (matches.length === 1 &&
+            target !== undefined &&
+            this.scalar(target, scope, visited));
+    }
+    /**
+     * Copies one physical declaration and its public path before the tree is
+     * released.
+     *
+     * The record includes parser-derived ranges, ownership, and attachment state
+     * so later adapter phases do not retain Tree-sitter nodes beyond the
+     * callback.
+     */
+    add(node, name, symbol, owner, identity, address, alias) {
+        const range = this.session.range(node);
+        const siteId = `zig:${this.source.id}:site:${node.startIndex}:${node.endIndex}`;
+        const declaration = {
+            id: `${siteId}:${JSON.stringify(address)}`,
+            name,
+            symbol,
+            identity,
+            address,
+            public: true,
+            alias,
+            site: {
+                id: siteId,
+                file: this.source.physicalPath,
+                range,
+                content: [range],
+            },
+            ...(owner === undefined ? {} : { ownerDeclarationId: owner.id }),
+        };
+        this.declarations.push(declaration);
+        this.attach(node, declaration);
+        return declaration;
+    }
+    /**
+     * Identifies a declaration initializer from syntax delimiters rather than
+     * source regexes.
+     *
+     * The first named child following an equals token supplies the supported
+     * static form used for alias, type, and inferred-surface classification.
+     */
+    initializer(node) {
+        const equals = node.children.find((child) => child.type === "=");
+        return equals === undefined
+            ? undefined
+            : node.namedChildren.find((child) => child.startIndex >= equals.endIndex && child.type !== "comment");
+    }
+    /**
+     * Compares bare and quoted spellings by their decoded Zig identifier.
+     *
+     * Alias lookup therefore treats a literal identifier and its supported quoted
+     * source spelling as the same declaration name within one lexical container.
+     */
+    sameName(left, right) {
+        return (left !== undefined &&
+            left !== null &&
+            this.name(left) === this.name(right));
+    }
+    /**
+     * Decodes literal Zig identifiers while preserving dots as one accessor
+     * segment.
+     *
+     * Unsupported escape syntax emits a diagnostic and returns the original text,
+     * preventing an invented decoded name from changing alias or address
+     * identity.
+     */
+    name(node) {
+        if (!node.text.startsWith('@"'))
+            return node.text;
+        try {
+            const parsed = JSON.parse(node.text.slice(1));
+            return (() => {
+                const __is = input => "string" === typeof input;
+                let _errorFactory;
+                return (input, errorFactory) => {
+                    if (false === __is(input)) {
+                        _errorFactory = errorFactory;
+                        ((input, _path, _exceptionable = true) => "string" === typeof input || _assertGuard_1._assertGuard(true, {
+                            method: "typia.assert",
+                            path: _path + "",
+                            expected: "string",
+                            value: input
+                        }, _errorFactory))(input, "$input", true);
+                    }
+                    return input;
+                };
+            })()(parsed);
+        }
+        catch {
+            this.problem("identifier-escape", "This quoted identifier uses an unsupported Zig escape; use a literal UTF-8 name or implement its escape decoding.", node);
+            return node.text;
+        }
+    }
+    /**
+     * Attaches an adjacent triple-slash group to its declaration.
+     *
+     * Only directly preceding standalone documentation comments qualify,
+     * preventing strings and ordinary comments from creating an accidental
+     * documentation host.
+     */
+    attach(node, declaration) {
+        const previous = node.previousNamedSibling;
+        if (previous === null ||
+            previous.type !== "comment" ||
+            !previous.text.startsWith("///") ||
+            previous.text.startsWith("////"))
+            return;
+        if (!/^\s*$/u.test(this.source.content.slice(previous.endIndex, node.startIndex)))
+            return;
+        const documentation = [...this.documentation.values()].find((item) => item.range.end.offset === previous.endIndex &&
+            item.syntax.opening === "///");
+        if (documentation === undefined)
+            return;
+        if (!documentation.attachments.some((attachment) => attachment.declarationId === declaration.id))
+            documentation.attachments.push({
+                declarationId: declaration.id,
+                siteId: declaration.site.id,
+            });
+    }
+    /**
+     * Classifies documentation comments and tag-bearing strings with UTF-16
+     * positions.
+     *
+     * Triple-slash runs form attachable documentation, while other carriers
+     * remain available only when they contain supported annotations that require
+     * diagnostics.
+     */
+    collectDocumentation() {
+        const nodes = this.session.root.descendantsOfType([
+            "comment",
+            "string",
+            "multiline_string",
+        ]);
+        const consumed = new Set();
+        for (const node of nodes) {
+            if (consumed.has(node.startIndex))
+                continue;
+            const doc = node.type === "comment" &&
+                node.text.startsWith("///") &&
+                !node.text.startsWith("////");
+            if (!doc &&
+                !/@(?:evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link|internal|hidden|ignore)\b/u.test(node.text))
+                continue;
+            let end = node;
+            if (doc) {
+                let next = end.nextNamedSibling;
+                while (next !== null &&
+                    next.type === "comment" &&
+                    next.text.startsWith("///") &&
+                    !next.text.startsWith("////") &&
+                    /^[ \t]*\r?\n[ \t]*$/u.test(this.source.content.slice(end.endIndex, next.startIndex))) {
+                    consumed.add(next.startIndex);
+                    end = next;
+                    next = end.nextNamedSibling;
+                }
+            }
+            const opening = doc
+                ? "///"
+                : node.type === "comment"
+                    ? node.text.startsWith("//!")
+                        ? "//!"
+                        : "//"
+                    : node.type === "multiline_string"
+                        ? "\\\\"
+                        : '"';
+            this.documentation.set(node.startIndex, {
+                id: `zig:${this.source.id}:documentation:${node.startIndex}`,
+                range: {
+                    start: this.session.range(node).start,
+                    end: this.session.range(end).end,
+                },
+                syntax: {
+                    opening,
+                    closing: node.type === "string" ? '"' : "",
+                    ...(doc ? { linePrefix: "///" } : {}),
+                    tagBoundaries: true,
+                    allowWithdrawal: doc,
+                },
+                attachments: [],
+            });
+        }
+    }
+    /**
+     * Records unsupported namespace semantics as actionable incomplete
+     * diagnostics.
+     *
+     * Duplicate suppression keeps one reported source location from producing
+     * repeated errors while ensuring every unsupported public form fails
+     * analysis.
+     */
+    problem(code, message, node) {
+        if (this.diagnostics.some((item) => item.code === `zig-${code}` &&
+            item.location?.range?.start?.offset === node.startIndex))
+            return;
+        this.diagnostics.push({
+            code: `zig-${code}`,
+            severity: "error",
+            message,
+            repair: "Use explicit supported Zig declarations or implement the reported static resolution before evaluating coverage.",
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.EvidenceZigFileScanner = EvidenceZigFileScanner;
+const CONTAINERS = new Set([
+    "struct_declaration",
+    "enum_declaration",
+    "union_declaration",
+    "opaque_declaration",
+    "error_set_declaration",
+]);
+const TYPE_FORMS = new Set([
+    "builtin_type",
+    "nullable_type",
+    "slice_type",
+    "pointer_type",
+    "array_type",
+    "error_union_type",
+    "function_signature",
+]);
+const VALUE_FORMS = new Set([
+    "integer",
+    "float",
+    "boolean",
+    "character",
+    "string",
+    "multiline_string",
+]);

package/lib/adapters/zig/IEvidenceZigDeclaration.d.ts

@@ -0,0 +1,76 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+/**
+ * Represents one explicit Zig declaration before public aliases are reconciled.
+ *
+ * A record separates semantic identity from the exported path because Zig
+ * aliases can expose one declaration at more than one address.
+ */
+export interface IEvidenceZigDeclaration {
+    /**
+     * Identifies this extracted declaration at one physical site and exposed
+     * path.
+     *
+     * Alias reconciliation uses the key to connect documentation attachments
+     * before it merges alias projections into their canonical semantic unit.
+     */
+    id: string;
+    /**
+     * Names the declaration in its defining Zig source container.
+     *
+     * The adapter preserves this canonical name when an alias publishes the same
+     * declaration under a different final public accessor segment.
+     */
+    name: string;
+    /**
+     * Classifies the declaration with Evidence's shared programming symbol.
+     *
+     * Unit materialization retains this classification when it merges physical
+     * sites and assigns the declaration's stable semantic identity.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Records the declaration's canonical lexical ownership path.
+     *
+     * This path defines semantic identity independently of aliases that expose
+     * the declaration through additional public accessors.
+     */
+    identity: string[];
+    /**
+     * Lists public accessor segments that reach this physical declaration.
+     *
+     * Alias projections may differ from {@link identity}; publication uses these
+     * segments to create every supported file-qualified public address.
+     */
+    address: string[];
+    /**
+     * Preserves the declaration's physical source site and fingerprint content.
+     *
+     * Materialization clones this site into the semantic unit so source review
+     * retains its location even after the parser session has closed.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Indicates whether the selected source exposes this declaration publicly.
+     *
+     * The adapter publishes only public records, while non-public boundaries can
+     * still be retained during extraction when needed for scanner
+     * classification.
+     */
+    public: boolean;
+    /**
+     * Marks a projection that contributes an additional public alias site.
+     *
+     * Alias projections do not create another unit; they allow target lookup and
+     * documentation hosts to retain every supported public spelling.
+     */
+    alias: boolean;
+    /**
+     * Identifies the explicit declaration that lexically owns this member.
+     *
+     * Omission marks a file-level declaration; otherwise materialization maps the
+     * owner to a unit parent so withdrawals propagate through the container
+     * tree.
+     */
+    ownerDeclarationId?: string;
+}

package/lib/adapters/zig/IEvidenceZigDocumentation.d.ts

@@ -0,0 +1,38 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceZigDocumentationAttachment } from "./IEvidenceZigDocumentationAttachment";
+/**
+ * Represents a Zig documentation carrier or tag-bearing unsupported carrier.
+ *
+ * The record retains source-mapped `///` text and ineligible annotation
+ * carriers until alias reconciliation determines the supported documentation
+ * host.
+ */
+export interface IEvidenceZigDocumentation {
+    /**
+     * Identifies this physical documentation carrier within its source analysis.
+     *
+     * Attachments use this key before the adapter materializes semantic units.
+     */
+    id: string;
+    /**
+     * Locates the half-open UTF-16 span occupied by the documentation carrier.
+     *
+     * Review fingerprints exclude this range from its attached declaration
+     * content.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Describes delimiters and annotation rules for parsing this carrier.
+     *
+     * Documentation mapping preserves these rules while masking ineligible
+     * examples.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Lists physical declaration sites directly attached to this carrier.
+     *
+     * Unsupported tagged carriers remain unattached for diagnostic host creation.
+     */
+    attachments: IEvidenceZigDocumentationAttachment[];
+}