@wrtnlabs/evidence 0.0.0

package/lib/adapters/csharp/CSharpDeclarationForm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Enumerates C# source forms that establish supported semantic declarations.
+ *
+ * CSharpFileScanner uses the form to select identity and ownership rules before
+ * public accessibility filtering determines the published graph population.
+ */
+export type CSharpDeclarationForm = "class" | "struct" | "interface" | "record" | "record-struct" | "enum" | "delegate" | "method" | "field" | "property" | "event" | "enum-member" | "indexer" | "operator" | "conversion-operator";

package/lib/adapters/csharp/CSharpDeclarationForm.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/adapters/csharp/CSharpDocumentation.d.ts

@@ -0,0 +1,12 @@
+import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { ICSharpDocumentation } from "./ICSharpDocumentation";
+/**
+ * Reads C# XML documentation while masking code and example elements.
+ *
+ * The C# adapter retains mapped prose from the shared reader but hides example
+ * content so its code-like text cannot be interpreted as Evidence annotations.
+ */
+export declare namespace CSharpDocumentation {
+    function read(source: IEvidenceSourceFile, documentation: ICSharpDocumentation, hostId: string): IEvidenceDocumentation;
+}

package/lib/adapters/csharp/CSharpDocumentation.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CSharpDocumentation = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+/**
+ * Reads C# XML documentation while masking code and example elements.
+ *
+ * The C# adapter retains mapped prose from the shared reader but hides example
+ * content so its code-like text cannot be interpreted as Evidence annotations.
+ */
+var CSharpDocumentation;
+(function (CSharpDocumentation) {
+    function read(source, documentation, hostId) {
+        const parsed = EvidenceDocumentation_1.EvidenceDocumentation.read(source.content, hostId, documentation.range, documentation.syntax);
+        if (!documentation.syntax.allowWithdrawal)
+            return parsed;
+        return {
+            ...parsed,
+            text: mask(parsed.text),
+        };
+    }
+    CSharpDocumentation.read = read;
+    function mask(input) {
+        const characters = input.split("");
+        const examples = /<(c|code|example|pre)\b[^>]*>[\s\S]*?<\/\1\s*>/giu;
+        for (const match of input.matchAll(examples))
+            hide(characters, match.index, match.index + match[0].length);
+        return characters.join("");
+    }
+    function hide(characters, start, end) {
+        for (let index = start; index < end; ++index)
+            if (characters[index] !== "\n" && characters[index] !== "\r")
+                characters[index] = " ";
+    }
+})(CSharpDocumentation || (exports.CSharpDocumentation = CSharpDocumentation = {}));

package/lib/adapters/csharp/CSharpFileScanner.d.ts

@@ -0,0 +1,54 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { ICSharpFileAnalysis } from "./ICSharpFileAnalysis";
+/**
+ * Extracts C# namespaces, declarations, and XML documentation.
+ *
+ * It preserves declaration ownership and physical attachment decisions for
+ * `CSharpAdapter`, which reconciles partial families after parsing closes.
+ */
+export declare class CSharpFileScanner {
+    private readonly session;
+    private readonly source;
+    private readonly declarations;
+    private readonly documentation;
+    private readonly carrierDocumentation;
+    private readonly diagnostics;
+    private readonly reported;
+    private readonly text;
+    private complete;
+    /**
+     * Binds the scanner to one C# parser session and captured source file.
+     *
+     * XML documentation is collected first so declaration adjacency remains a
+     * property of the original source rather than a materialized unit.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Extracts supported file and block namespace declarations into a file record.
+     *
+     * Invalid namespace or declaration surfaces contribute diagnostics and preserve
+     * incompleteness for the adapter's final inventory.
+     */
+    scan(): ICSharpFileAnalysis;
+    private scanDeclaration;
+    private scanNamespace;
+    private scanType;
+    private scanField;
+    private scanNamedMember;
+    private scanEnumMember;
+    private scanIndexer;
+    private scanOperator;
+    private scanConversionOperator;
+    private addDeclaration;
+    private typeAddresses;
+    private memberAddresses;
+    private documentationFor;
+    private collectDocumentation;
+    private attach;
+    private ensureDocumentation;
+    private annotation;
+    private nodeKey;
+    private siteId;
+    private problem;
+}

package/lib/adapters/csharp/CSharpFileScanner.js

@@ -0,0 +1,403 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CSharpFileScanner = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+const CSharpSyntax_1 = require("./CSharpSyntax");
+const SourceText_1 = require("../../internal/SourceText");
+/**
+ * Extracts C# namespaces, declarations, and XML documentation.
+ *
+ * It preserves declaration ownership and physical attachment decisions for
+ * `CSharpAdapter`, which reconciles partial families after parsing closes.
+ */
+class CSharpFileScanner {
+    session;
+    source;
+    declarations = [];
+    documentation = new Map();
+    carrierDocumentation = new Map();
+    diagnostics = [];
+    reported = new Set();
+    text;
+    complete = true;
+    /**
+     * Binds the scanner to one C# parser session and captured source file.
+     *
+     * XML documentation is collected first so declaration adjacency remains a
+     * property of the original source rather than a materialized unit.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+        this.text = new SourceText_1.SourceText(source.content);
+        this.collectDocumentation();
+    }
+    /**
+     * Extracts supported file and block namespace declarations into a file record.
+     *
+     * Invalid namespace or declaration surfaces contribute diagnostics and preserve
+     * incompleteness for the adapter's final inventory.
+     */
+    scan() {
+        let namespacePath = [];
+        let fileScoped = false;
+        for (const item of this.session.root.namedChildren) {
+            if (item.type === "file_scoped_namespace_declaration") {
+                const path = CSharpSyntax_1.CSharpSyntax.path(item.childForFieldName("name"));
+                if (path === undefined)
+                    this.problem("csharp-namespace-name", "A file-scoped C# namespace has no statically readable name.", "Use one identifier or dotted namespace name.", item);
+                else if (fileScoped)
+                    this.problem("csharp-file-namespace", "A C# source file declares more than one file-scoped namespace.", "Keep one file-scoped namespace in the selected source file.", item);
+                else {
+                    namespacePath = path;
+                    fileScoped = true;
+                }
+                continue;
+            }
+            this.scanDeclaration(item, namespacePath, undefined);
+        }
+        return {
+            source: this.source,
+            declarations: this.declarations,
+            documentation: Array.from(this.documentation.values()),
+            diagnostics: this.diagnostics,
+            complete: this.complete,
+        };
+    }
+    scanDeclaration(item, namespacePath, owner) {
+        switch (item.type) {
+            case "comment":
+            case "using_directive":
+            case "extern_alias_directive":
+            case "global_attribute_list":
+            case "global_statement":
+            case "constructor_declaration":
+            case "destructor_declaration":
+                return;
+            case "namespace_declaration":
+                if (owner === undefined)
+                    this.scanNamespace(item, namespacePath);
+                return;
+            case "class_declaration":
+                this.scanType(item, namespacePath, owner, "class", "class");
+                return;
+            case "struct_declaration":
+                this.scanType(item, namespacePath, owner, "struct", "struct");
+                return;
+            case "interface_declaration":
+                this.scanType(item, namespacePath, owner, "interface", "interface");
+                return;
+            case "record_declaration":
+                this.scanType(item, namespacePath, owner, "record", CSharpSyntax_1.CSharpSyntax.hasToken(item, "struct") ? "record-struct" : "record");
+                return;
+            case "enum_declaration":
+                this.scanType(item, namespacePath, owner, "enum", "enum");
+                return;
+            case "delegate_declaration":
+                this.scanType(item, namespacePath, owner, "delegate", "delegate");
+                return;
+            case "field_declaration":
+                if (owner !== undefined)
+                    this.scanField(item, owner, "field");
+                return;
+            case "event_field_declaration":
+                if (owner !== undefined)
+                    this.scanField(item, owner, "event");
+                return;
+            case "event_declaration":
+                if (owner !== undefined)
+                    this.scanNamedMember(item, owner, "event");
+                return;
+            case "property_declaration":
+                if (owner !== undefined)
+                    this.scanNamedMember(item, owner, "property");
+                return;
+            case "method_declaration":
+                if (owner !== undefined)
+                    this.scanNamedMember(item, owner, "method");
+                return;
+            case "indexer_declaration":
+                if (owner !== undefined)
+                    this.scanIndexer(item, owner);
+                return;
+            case "operator_declaration":
+                if (owner !== undefined)
+                    this.scanOperator(item, owner);
+                return;
+            case "conversion_operator_declaration":
+                if (owner !== undefined)
+                    this.scanConversionOperator(item, owner);
+                return;
+            case "preproc_if":
+                this.problem("csharp-preprocessor-conditional", "Conditional compilation can change the selected C# declaration population.", "Select preprocessed generated source or remove declaration-position conditional branches.", item);
+                return;
+            default:
+                if (CSharpSyntax_1.CSharpSyntax.hasModifier(item, "public"))
+                    this.problem("csharp-public-form", `Public C# source form '${item.type}' is not classified by this adapter.`, "Add an explicit declaration-form rule before evaluating this public surface.", item);
+        }
+    }
+    scanNamespace(item, prefix) {
+        const name = CSharpSyntax_1.CSharpSyntax.path(item.childForFieldName("name"));
+        if (name === undefined) {
+            this.problem("csharp-namespace-name", "A C# namespace declaration has no statically readable name.", "Use one identifier or dotted namespace name.", item);
+            return;
+        }
+        const body = item.childForFieldName("body");
+        if (body === null)
+            return;
+        const namespacePath = [...prefix, ...name];
+        for (const child of body.namedChildren)
+            this.scanDeclaration(child, namespacePath, undefined);
+    }
+    scanType(item, namespacePath, owner, kind, form) {
+        const name = CSharpSyntax_1.CSharpSyntax.name(item.childForFieldName("name"));
+        if (name === undefined) {
+            this.problem("csharp-type-name", `A C# ${form} declaration has no statically readable name.`, "Use one ordinary named declaration.", item);
+            return;
+        }
+        const arity = CSharpSyntax_1.CSharpSyntax.typeParameterArity(item);
+        const identityName = arity === 0 ? name : `${name}\`${arity}`;
+        const identity = [
+            ...(owner === undefined ? namespacePath : owner.identity),
+            identityName,
+        ];
+        const addresses = this.typeAddresses(owner?.addresses ?? [
+            { segments: namespacePath, canonical: true, aliasPrefixes: [] },
+        ], name, identityName);
+        const declaration = this.addDeclaration(item, item, this.documentationFor(item), [this.session.range(item)], name, "type", form, identity, addresses, owner?.kind === "interface", false, owner?.declarationId);
+        const context = {
+            declarationId: declaration.id,
+            identity,
+            addresses,
+            kind,
+        };
+        const body = item.childForFieldName("body");
+        if (body === null)
+            return;
+        if (kind === "enum") {
+            for (const member of body.namedChildren)
+                if (member.type === "enum_member_declaration")
+                    this.scanEnumMember(member, context);
+                else
+                    this.scanDeclaration(member, namespacePath, context);
+            return;
+        }
+        for (const member of body.namedChildren)
+            this.scanDeclaration(member, namespacePath, context);
+    }
+    scanField(item, owner, form) {
+        const variable = item.namedChildren.find((child) => child.type === "variable_declaration");
+        const declarators = variable === undefined
+            ? []
+            : variable.namedChildren.filter((child) => child.type === "variable_declarator");
+        const first = declarators[0];
+        if (first === undefined)
+            return;
+        const header = this.text.range(item.startIndex, first.startIndex);
+        const documentation = this.documentationFor(item);
+        const implicitPublic = owner.kind === "interface";
+        for (const declarator of declarators) {
+            const name = CSharpSyntax_1.CSharpSyntax.name(declarator.childForFieldName("name"));
+            if (name === undefined)
+                continue;
+            this.addDeclaration(declarator, item, documentation, [header, this.session.range(declarator)], name, "property", form, [...owner.identity, name], this.memberAddresses(owner, name), implicitPublic, false, owner.declarationId);
+        }
+    }
+    scanNamedMember(item, owner, form) {
+        const name = CSharpSyntax_1.CSharpSyntax.name(item.childForFieldName("name"));
+        if (name === undefined) {
+            this.problem("csharp-member-name", `A C# ${form} declaration has no statically readable name.`, "Use one ordinary named member declaration.", item);
+            return;
+        }
+        this.addDeclaration(item, item, this.documentationFor(item), [this.session.range(item)], name, form === "method" ? "function" : "property", form, [...owner.identity, name], this.memberAddresses(owner, name), owner.kind === "interface", CSharpSyntax_1.CSharpSyntax.explicitInterface(item), owner.declarationId);
+    }
+    scanEnumMember(item, owner) {
+        const name = CSharpSyntax_1.CSharpSyntax.name(item.childForFieldName("name"));
+        if (name === undefined)
+            return;
+        this.addDeclaration(item, item, this.documentationFor(item), [this.session.range(item)], name, "property", "enum-member", [...owner.identity, name], this.memberAddresses(owner, name), true, false, owner.declarationId);
+    }
+    scanIndexer(item, owner) {
+        const name = "this[]";
+        this.addDeclaration(item, item, this.documentationFor(item), [this.session.range(item)], name, "property", "indexer", [...owner.identity, name], this.memberAddresses(owner, name), owner.kind === "interface", CSharpSyntax_1.CSharpSyntax.explicitInterface(item), owner.declarationId);
+    }
+    scanOperator(item, owner) {
+        const name = CSharpSyntax_1.CSharpSyntax.operatorName(item);
+        if (name === undefined) {
+            this.problem("csharp-operator-name", "A C# operator declaration has no statically readable operator token.", "Use a grammar-supported operator declaration.", item);
+            return;
+        }
+        this.addDeclaration(item, item, this.documentationFor(item), [this.session.range(item)], name, "function", "operator", [...owner.identity, name], this.memberAddresses(owner, name), owner.kind === "interface", CSharpSyntax_1.CSharpSyntax.explicitInterface(item), owner.declarationId);
+    }
+    scanConversionOperator(item, owner) {
+        const name = CSharpSyntax_1.CSharpSyntax.conversionOperatorName(item);
+        if (name === undefined) {
+            this.problem("csharp-conversion-name", "A C# conversion operator has no statically readable kind or destination type.", "Use a grammar-supported implicit or explicit conversion declaration.", item);
+            return;
+        }
+        this.addDeclaration(item, item, this.documentationFor(item), [this.session.range(item)], name, "function", "conversion-operator", [...owner.identity, name], this.memberAddresses(owner, name), owner.kind === "interface", CSharpSyntax_1.CSharpSyntax.explicitInterface(item), owner.declarationId);
+    }
+    addDeclaration(item, siteNode, documentation, content, name, symbol, form, identity, addresses, implicitPublic, explicitInterface, ownerDeclarationId) {
+        const site = {
+            id: this.siteId(siteNode),
+            file: this.source.physicalPath,
+            range: this.text.range(documentation === undefined
+                ? siteNode.startIndex
+                : documentation.range.start.offset, siteNode.endIndex),
+            content,
+        };
+        const declaration = {
+            id: `csharp:${this.source.id}:declaration:${form}:${item.startIndex}:${name}`,
+            name,
+            symbol,
+            form,
+            identity,
+            addresses,
+            site,
+            accessibility: CSharpSyntax_1.CSharpSyntax.accessibility(siteNode),
+            implicitPublic,
+            partial: CSharpSyntax_1.CSharpSyntax.hasModifier(siteNode, "partial"),
+            explicitInterface,
+            ...(ownerDeclarationId === undefined ? {} : { ownerDeclarationId }),
+        };
+        this.declarations.push(declaration);
+        if (documentation !== undefined)
+            this.attach(documentation, declaration.id, site.id);
+        return declaration;
+    }
+    typeAddresses(bases, name, identityName) {
+        const names = name === identityName ? [name] : [identityName, name];
+        return bases.flatMap((base) => names.map((entry) => {
+            const segments = [...base.segments, entry];
+            return {
+                segments,
+                canonical: base.canonical && entry === identityName,
+                aliasPrefixes: entry === identityName
+                    ? base.aliasPrefixes
+                    : [...base.aliasPrefixes, segments],
+            };
+        }));
+    }
+    memberAddresses(owner, name) {
+        return owner.addresses.map((address) => ({
+            segments: [...address.segments, name],
+            canonical: address.canonical,
+            aliasPrefixes: address.aliasPrefixes,
+        }));
+    }
+    documentationFor(node) {
+        const previous = node.previousNamedSibling;
+        if (previous === null || !CSharpSyntax_1.CSharpSyntax.isXmlDocumentation(previous))
+            return undefined;
+        const documentation = this.carrierDocumentation.get(this.nodeKey(previous));
+        const gap = documentation === undefined
+            ? ""
+            : this.source.content.slice(documentation.range.end.offset, node.startIndex);
+        if (documentation === undefined ||
+            documentation.range.start.column !== node.startPosition.column + 1 ||
+            !/^\s*$/u.test(gap) ||
+            /\r?\n[ \t]*\r?\n/u.test(gap))
+            return undefined;
+        return documentation;
+    }
+    collectDocumentation() {
+        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("//")) {
+                let next = last.nextNamedSibling;
+                while (next !== null &&
+                    next.type === "comment" &&
+                    next.text.startsWith("///") === first.text.startsWith("///") &&
+                    next.startPosition.column === first.startPosition.column &&
+                    /^\s*$/u.test(this.source.content.slice(last.endIndex, next.startIndex)) &&
+                    !/\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 syntax = CSharpSyntax_1.CSharpSyntax.comment(first);
+            const supported = CSharpSyntax_1.CSharpSyntax.isXmlDocumentation(first);
+            const raw = EvidenceDocumentation_1.EvidenceDocumentation.read(this.source.content, "csharp-probe", range, syntax).text;
+            if (!supported && !this.annotation(raw))
+                continue;
+            const documentation = this.ensureDocumentation(range, syntax);
+            for (const comment of sequence)
+                this.carrierDocumentation.set(this.nodeKey(comment), documentation);
+        }
+        const literals = new Map();
+        for (const type of [
+            "string_literal",
+            "verbatim_string_literal",
+            "raw_string_literal",
+            "interpolated_string_expression",
+        ])
+            for (const literal of this.session.root.descendantsOfType(type))
+                literals.set(this.nodeKey(literal), literal);
+        for (const literal of literals.values()) {
+            const syntax = CSharpSyntax_1.CSharpSyntax.string(literal);
+            if (syntax === undefined)
+                continue;
+            const range = this.session.range(literal);
+            const raw = EvidenceDocumentation_1.EvidenceDocumentation.read(this.source.content, "csharp-probe", range, syntax).text;
+            if (this.annotation(raw))
+                this.ensureDocumentation(range, syntax);
+        }
+    }
+    attach(documentation, declarationId, siteId) {
+        if (!documentation.attachments.some((attachment) => attachment.declarationId === declarationId &&
+            attachment.siteId === siteId))
+            documentation.attachments.push({ declarationId, siteId });
+    }
+    ensureDocumentation(range, syntax) {
+        const key = `${range.start.offset}:${range.end.offset}`;
+        let documentation = this.documentation.get(key);
+        if (documentation === undefined) {
+            documentation = {
+                id: `csharp:${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 `csharp:${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.CSharpFileScanner = CSharpFileScanner;

package/lib/adapters/csharp/CSharpSyntax.d.ts

@@ -0,0 +1,23 @@
+import type { Node } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { CSharpAccessibility } from "./CSharpAccessibility";
+/**
+ * Provides C# grammar helpers for names, modifiers, documentation, and special members.
+ *
+ * CSharpFileScanner uses these helpers to classify source constructs and preserve
+ * C# accessibility and member spelling before it builds declaration records.
+ */
+export declare namespace CSharpSyntax {
+    function name(node: Node | null): string | undefined;
+    function path(node: Node | null): string[] | undefined;
+    function typeParameterArity(node: Node): number;
+    function hasModifier(node: Node, modifier: string): boolean;
+    function hasToken(node: Node, token: string): boolean;
+    function accessibility(node: Node): CSharpAccessibility;
+    function isXmlDocumentation(node: Node): boolean;
+    function comment(node: Node): IEvidenceCommentSyntax;
+    function explicitInterface(node: Node): boolean;
+    function operatorName(node: Node): string | undefined;
+    function conversionOperatorName(node: Node): string | undefined;
+    function string(node: Node): IEvidenceCommentSyntax | undefined;
+}