@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/csharp/EvidenceCSharpSyntax.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceCSharpSyntax = void 0;
+/**
+ * Provides C# grammar helpers for names, modifiers, documentation, and special
+ * members.
+ *
+ * EvidenceCSharpFileScanner uses these helpers to classify source constructs
+ * and preserve C# accessibility and member spelling before it builds
+ * declaration records.
+ */
+var EvidenceCSharpSyntax;
+(function (EvidenceCSharpSyntax) {
+    function name(node) {
+        if (node === null || node.type !== "identifier")
+            return undefined;
+        const value = node.text.startsWith("@") ? node.text.slice(1) : node.text;
+        return value
+            .replace(/\\u([0-9A-Fa-f]{4})/gu, (_match, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+            .replace(/\\U([0-9A-Fa-f]{8})/gu, (match, hex) => {
+            const codePoint = Number.parseInt(hex, 16);
+            return codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : match;
+        });
+    }
+    EvidenceCSharpSyntax.name = name;
+    function path(node) {
+        if (node === null)
+            return undefined;
+        const direct = name(node);
+        if (direct !== undefined)
+            return [direct];
+        if (node.type !== "qualified_name")
+            return undefined;
+        const qualifier = path(node.childForFieldName("qualifier"));
+        const suffix = name(node.childForFieldName("name"));
+        return qualifier === undefined || suffix === undefined
+            ? undefined
+            : [...qualifier, suffix];
+    }
+    EvidenceCSharpSyntax.path = path;
+    function typeParameterArity(node) {
+        const parameters = node.namedChildren.find((child) => child.type === "type_parameter_list");
+        return parameters === undefined
+            ? 0
+            : parameters.namedChildren.filter((child) => child.type === "type_parameter").length;
+    }
+    EvidenceCSharpSyntax.typeParameterArity = typeParameterArity;
+    function hasModifier(node, modifier) {
+        return node.namedChildren.some((child) => child.type === "modifier" && child.text === modifier);
+    }
+    EvidenceCSharpSyntax.hasModifier = hasModifier;
+    function hasToken(node, token) {
+        return node.children.some((child) => child.type === token);
+    }
+    EvidenceCSharpSyntax.hasToken = hasToken;
+    function accessibility(node) {
+        const modifiers = new Set(node.namedChildren
+            .filter((child) => child.type === "modifier")
+            .map((child) => child.text));
+        if (modifiers.has("public"))
+            return "public";
+        if (modifiers.has("private") && modifiers.has("protected"))
+            return "private-protected";
+        if (modifiers.has("protected") && modifiers.has("internal"))
+            return "protected-internal";
+        if (modifiers.has("private"))
+            return "private";
+        if (modifiers.has("protected"))
+            return "protected";
+        if (modifiers.has("internal"))
+            return "internal";
+        if (modifiers.has("file"))
+            return "file";
+        return "default";
+    }
+    EvidenceCSharpSyntax.accessibility = accessibility;
+    function isXmlDocumentation(node) {
+        return (node.type === "comment" &&
+            (node.text.startsWith("///") || node.text.startsWith("/**")));
+    }
+    EvidenceCSharpSyntax.isXmlDocumentation = isXmlDocumentation;
+    function comment(node) {
+        if (node.text.startsWith("///"))
+            return {
+                opening: "///",
+                closing: "",
+                linePrefix: "///",
+                tagBoundaries: true,
+                allowWithdrawal: true,
+            };
+        if (node.text.startsWith("//"))
+            return {
+                opening: "//",
+                closing: "",
+                linePrefix: "//",
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        const documentation = node.text.startsWith("/**");
+        return {
+            opening: documentation ? "/**" : "/*",
+            closing: "*/",
+            linePrefix: "*",
+            tagBoundaries: true,
+            allowWithdrawal: documentation,
+        };
+    }
+    EvidenceCSharpSyntax.comment = comment;
+    function explicitInterface(node) {
+        return node.namedChildren.some((child) => child.type === "explicit_interface_specifier");
+    }
+    EvidenceCSharpSyntax.explicitInterface = explicitInterface;
+    function operatorName(node) {
+        const operator = node.childForFieldName("operator");
+        if (operator === null)
+            return undefined;
+        const checked = node.children.some((child) => child.type === "checked");
+        return `operator ${checked ? "checked " : ""}${operator.text}`;
+    }
+    EvidenceCSharpSyntax.operatorName = operatorName;
+    function conversionOperatorName(node) {
+        const type = node.childForFieldName("type");
+        if (type === null)
+            return undefined;
+        const conversion = node.children.some((child) => child.type === "implicit")
+            ? "implicit"
+            : node.children.some((child) => child.type === "explicit")
+                ? "explicit"
+                : undefined;
+        const checked = node.children.some((child) => child.type === "checked");
+        return conversion === undefined
+            ? undefined
+            : `${conversion} operator ${checked ? "checked " : ""}${normalize(type.text)}`;
+    }
+    EvidenceCSharpSyntax.conversionOperatorName = conversionOperatorName;
+    function string(node) {
+        const rawOpening = node.namedChildren.find((child) => child.type === "raw_string_start");
+        const rawClosing = node.namedChildren.find((child) => child.type === "raw_string_end");
+        if (rawOpening !== undefined && rawClosing !== undefined)
+            return {
+                opening: rawOpening.text,
+                closing: rawClosing.text + (node.text.endsWith("u8") ? "u8" : ""),
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        if (node.type === "verbatim_string_literal")
+            return {
+                opening: '@"',
+                closing: node.text.endsWith('"u8') ? '"u8' : '"',
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        if (node.type === "string_literal")
+            return {
+                opening: '"',
+                closing: node.text.endsWith('"u8') ? '"u8' : '"',
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        if (node.type !== "interpolated_string_expression")
+            return undefined;
+        const opening = /^(?:\$+@?"|@\$+")/u.exec(node.text)?.[0];
+        return opening === undefined
+            ? undefined
+            : {
+                opening,
+                closing: node.text.endsWith('"u8') ? '"u8' : '"',
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+    }
+    EvidenceCSharpSyntax.string = string;
+    function normalize(value) {
+        return value.replace(/\s+/gu, " ").trim();
+    }
+})(EvidenceCSharpSyntax || (exports.EvidenceCSharpSyntax = EvidenceCSharpSyntax = {}));

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

@@ -0,0 +1,8 @@
+/**
+ * Identifies the C# type context that governs nested ownership and visibility.
+ *
+ * The scanner carries this context into member extraction to apply
+ * type-specific accessibility defaults and construct public address segments
+ * consistently.
+ */
+export type EvidenceCSharpTypeKind = "class" | "struct" | "interface" | "record" | "enum" | "delegate";

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

@@ -0,0 +1,91 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { EvidenceCSharpAccessibility } from "./EvidenceCSharpAccessibility";
+import type { EvidenceCSharpDeclarationForm } from "./EvidenceCSharpDeclarationForm";
+import type { IEvidenceCSharpDeclarationAddress } from "./IEvidenceCSharpDeclarationAddress";
+/**
+ * Records one physical C# declaration before adapter-level family
+ * reconciliation.
+ *
+ * `EvidenceCSharpFileScanner` creates this record with the declaration's
+ * syntax-derived identity, addresses, visibility inputs, and documentation
+ * site. `EvidenceCSharpAdapter` groups compatible records into semantic units,
+ * so partial declarations and overloads can retain their distinct source
+ * attachments while sharing one unit.
+ */
+export interface IEvidenceCSharpDeclaration {
+    /**
+     * Scanner-local key used by documentation attachments and family grouping.
+     *
+     * The adapter replaces it with one semantic unit ID during materialization.
+     */
+    id: string;
+    /**
+     * Unqualified source name displayed for the materialized unit.
+     *
+     * Containment belongs to `identity` and public path candidates.
+     */
+    name: string;
+    /**
+     * Graph selector category assigned to this C# declaration.
+     *
+     * It keeps language-specific syntax within the shared programming vocabulary.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Declaration form used to reconcile compatible partials and overloads.
+     *
+     * Incompatible forms for the same identity remain extraction failures.
+     */
+    form: EvidenceCSharpDeclarationForm;
+    /**
+     * Canonical semantic path independent of aliases and physical source
+     * location.
+     *
+     * The adapter uses it to merge one declaration family.
+     */
+    identity: string[];
+    /**
+     * Address candidates carrying canonical and alias-prefix provenance.
+     *
+     * This structure prevents aliases from obscuring the real public owner.
+     */
+    addresses: IEvidenceCSharpDeclarationAddress[];
+    /**
+     * Source location retained as an eligible documentation host and fingerprint
+     * site.
+     *
+     * Partial declarations can contribute several sites to one unit.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Explicit accessibility extracted from C# modifiers.
+     *
+     * Publication combines it with context-sensitive implicit accessibility.
+     */
+    accessibility: EvidenceCSharpAccessibility;
+    /**
+     * Whether C# supplies public accessibility when no modifier was written.
+     *
+     * This preserves language defaults without treating every omission as public.
+     */
+    implicitPublic: boolean;
+    /**
+     * Whether this declaration participates in C# partial-type materialization.
+     *
+     * The adapter merges compatible parts while retaining their physical sites.
+     */
+    partial: boolean;
+    /**
+     * Whether the member has an explicit interface implementation.
+     *
+     * Such members do not expose the ordinary public address spelling.
+     */
+    explicitInterface: boolean;
+    /**
+     * Enclosing declaration record for a nested member.
+     *
+     * Omission identifies a namespace-level declaration.
+     */
+    ownerDeclarationId?: string;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Describes one public-address candidate for a C# declaration.
+ *
+ * The scanner derives candidates from namespace, type, and member containment,
+ * including aliases introduced by C# syntax. `EvidenceCSharpAdapter` uses their
+ * canonical and alias-prefix provenance when publishing public addresses,
+ * preserving the declaration's semantic identity independently from its
+ * accessible spellings.
+ */
+export interface IEvidenceCSharpDeclarationAddress {
+    /**
+     * Segmented public accessor for this declaration spelling.
+     *
+     * Segments avoid treating literal dots in names as containment.
+     */
+    segments: string[];
+    /**
+     * Whether this spelling is the declaration family's ordinary address.
+     *
+     * Alias candidates are suppressed when a canonical owner is present.
+     */
+    canonical: boolean;
+    /**
+     * Alias paths that must remain unoccupied before this address is published.
+     *
+     * This protects ownership when source aliases shadow an ordinary declaration.
+     */
+    aliasPrefixes: string[][];
+}

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

@@ -0,0 +1,24 @@
+import type { IEvidenceCSharpDeclaration } from "./IEvidenceCSharpDeclaration";
+/**
+ * Collects physical declarations that resolve to one C# semantic unit.
+ *
+ * `EvidenceCSharpAdapter` builds these groups while materializing a source
+ * snapshot and checks the contained declarations for compatible partial or
+ * overload forms. The group bridges scanner-local declaration records and the
+ * single published Evidence unit, retaining every contributing site and address
+ * candidate.
+ */
+export interface IEvidenceCSharpDeclarationGroup {
+    /**
+     * Semantic family key shared by compatible partial and overload declarations.
+     *
+     * It is used internally before the final unit is emitted.
+     */
+    id: string;
+    /**
+     * Physical declarations contributing sites and public address candidates.
+     *
+     * The adapter rejects incompatible families instead of guessing an owner.
+     */
+    declarations: IEvidenceCSharpDeclaration[];
+}

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

@@ -0,0 +1,47 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceCSharpDocumentationAttachment } from "./IEvidenceCSharpDocumentationAttachment";
+/**
+ * Retains one C# XML documentation carrier until the adapter creates evidence
+ * hosts.
+ *
+ * EvidenceCSharpFileScanner records its physical range, comment syntax, and
+ * accepted declaration sites without binding it to a semantic unit.
+ * EvidenceCSharpAdapter later groups its attachments against published
+ * declarations, then parses the same carrier either as attached documentation
+ * or as an unsupported annotation.
+ */
+export interface IEvidenceCSharpDocumentation {
+    /**
+     * Identifies this carrier throughout scanning and host materialization.
+     *
+     * The scanner derives the key from the source-comment range. It remains
+     * distinct from declaration, site, and semantic unit identifiers because one
+     * carrier can attach to multiple physical declarations.
+     */
+    id: string;
+    /**
+     * Locates the complete XML documentation carrier in the physical source file.
+     *
+     * The adapter uses this span for hosts, annotation-range exclusions, and
+     * diagnostics. Evidence tags are read only from these exact source bytes.
+     */
+    range: IEvidenceSourceRange;
+    /**
+     * Preserves the comment form required to normalize the carrier's XML text.
+     *
+     * EvidenceCSharpDocumentation passes it to the shared documentation reader so
+     * line delimiters and indentation are removed according to the original
+     * syntax.
+     */
+    syntax: IEvidenceCommentSyntax;
+    /**
+     * Names the declaration sites that the scanner accepted as this carrier's
+     * owners.
+     *
+     * Each attachment preserves both a scanner-local declaration and its physical
+     * site. Materialization uses this list to form hosts; it never broadens
+     * ownership by searching nearby source text.
+     */
+    attachments: IEvidenceCSharpDocumentationAttachment[];
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Records one scanner-approved ownership link from XML documentation to a C#
+ * declaration site.
+ *
+ * IEvidenceCSharpDocumentation stores these physical links while parsing is
+ * still close to source syntax. EvidenceCSharpAdapter resolves the declaration
+ * record to a published semantic unit and groups links by site when it creates
+ * evidence hosts.
+ */
+export interface IEvidenceCSharpDocumentationAttachment {
+    /**
+     * Identifies the scanner-local declaration that receives this XML
+     * documentation.
+     *
+     * EvidenceCSharpAdapter looks up this key in its published-declaration map to
+     * find the semantic unit. It is not a stable unit ID because partial
+     * declarations can later merge into one family.
+     */
+    declarationId: string;
+    /**
+     * Identifies the physical declaration site that owns the resulting evidence
+     * host.
+     *
+     * Grouping by this value keeps documentation attached to the source
+     * occurrence that established adjacency, so separate partial declarations
+     * cannot borrow each other's comments.
+     */
+    siteId: string;
+}

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

@@ -0,0 +1,54 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceCSharpDeclaration } from "./IEvidenceCSharpDeclaration";
+import type { IEvidenceCSharpDocumentation } from "./IEvidenceCSharpDocumentation";
+/**
+ * Carries one source file's C# extraction after its Tree-sitter session can
+ * close.
+ *
+ * EvidenceCSharpFileScanner produces this node-free boundary between syntax
+ * traversal and EvidenceCSharpAdapter materialization. The adapter reconciles
+ * declarations across files, maps documentation to hosts, and propagates
+ * incomplete extraction to the final inventory without retaining parser nodes.
+ */
+export interface IEvidenceCSharpFileAnalysis {
+    /**
+     * Identifies the source snapshot from which this extraction was produced.
+     *
+     * EvidenceCSharpAdapter uses its physical path for diagnostics and hosts and
+     * its configured addresses when publishing declaration accessors.
+     */
+    source: IEvidenceSourceFile;
+    /**
+     * Collects C# declarations that still require partial-family reconciliation.
+     *
+     * Each record retains its physical site and documentation attachment identity
+     * after parsing closes. Materialization merges compatible declarations and
+     * decides which ones expose public units.
+     */
+    declarations: IEvidenceCSharpDeclaration[];
+    /**
+     * Collects XML documentation carriers with scanner-established attachments.
+     *
+     * Attached carriers supply evidence tags for published units. Unattached or
+     * unsupported annotation carriers remain available so the adapter can report
+     * their diagnostics instead of silently discarding them.
+     */
+    documentation: IEvidenceCSharpDocumentation[];
+    /**
+     * Reports extraction problems that prevent this analysis from representing
+     * its full source surface.
+     *
+     * The adapter copies these diagnostics to the final inventory and treats the
+     * file as incomplete, preventing missing declarations from reducing
+     * coverage.
+     */
+    diagnostics: IEvidenceDiagnostic[];
+    /**
+     * States whether the scanner extracted every relevant supported construct.
+     *
+     * A false value propagates from unsupported or invalid source surfaces and
+     * prevents coverage from passing with a partial file population.
+     */
+    complete: boolean;
+}

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

@@ -0,0 +1,44 @@
+import type { EvidenceCSharpTypeKind } from "./EvidenceCSharpTypeKind";
+import type { IEvidenceCSharpDeclarationAddress } from "./IEvidenceCSharpDeclarationAddress";
+/**
+ * Carries the enclosing C# type state while the scanner traverses nested
+ * declarations.
+ *
+ * EvidenceCSharpFileScanner creates this context for each type and passes it to
+ * member and nested-type scans. It keeps structural ownership, semantic
+ * identity, and public address candidates aligned without repeatedly deriving
+ * them from syntax.
+ */
+export interface IEvidenceCSharpTypeContext {
+    /**
+     * Identifies the scanner-local declaration record for the enclosing type.
+     *
+     * Nested declarations store this value as their ownerDeclarationId so later
+     * materialization can preserve parent units and resolve public visibility.
+     */
+    declarationId: string;
+    /**
+     * Supplies the semantic path that nested declarations extend.
+     *
+     * The scanner appends each nested declaration name to this canonical
+     * identity. It remains separate from public addresses because aliases may
+     * expose other valid access paths.
+     */
+    identity: string[];
+    /**
+     * Supplies the public address candidates that nested declarations extend.
+     *
+     * Member scanning appends its name to every candidate while preserving
+     * canonical and alias-prefix provenance. Partial types can therefore
+     * contribute more than one valid public prefix.
+     */
+    addresses: IEvidenceCSharpDeclarationAddress[];
+    /**
+     * Classifies the enclosing type form for nested-member scanning.
+     *
+     * The scanner uses this value to apply interface-specific implicit-public
+     * semantics without reinterpreting the enclosing type's syntax for each
+     * member.
+     */
+    kind: EvidenceCSharpTypeKind;
+}

package/lib/adapters/dart/EvidenceDartAdapter.d.ts

@@ -1,15 +1,104 @@
-import { DartAdapter } from "./DartAdapter";
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
 /**
- * Extracts Dart public declarations across defining libraries, parts, and static exports.
+ * Resolves Dart library topology before publishing declarations and
+ * documentation.
  *
- * Library resolution checks reciprocal part ownership before publishing aliases.
- * Supported show/hide exports project public paths without changing the defining
- * declaration's semantic identity. Attached Dart documentation remains associated
- * with its original declaration site through these projections.
- *
- * Package and SDK export URIs, conditional exports, augmentation, and members
- * absent from selected source are outside this boundary. Missing part dependencies
- * remain observable so watch can recover when their source appears.
+ * File scans record directives and physical declarations. Reciprocal part
+ * resolution establishes defining-library ownership, then unit materialization
+ * and show/hide export publication expose aliases without duplicating
+ * identities. Documentation is attached after those owners exist. Missing
+ * library inputs remain dependencies so a later watch cycle can observe their
+ * creation.
  */
-export declare class EvidenceDartAdapter extends DartAdapter {
+export declare class EvidenceDartAdapter implements IEvidenceAdapter<"dart"> {
+    /**
+     * Dart artifact discriminator for library-aware extraction.
+     *
+     * The public entry point uses this fixed language for grammar selection and
+     * inventory records, independently of claim or reference role.
+     */
+    get type(): "dart";
+    /**
+     * Builds an owned Dart inventory from captured source and library directives.
+     *
+     * Topology resolution runs before declarations are grouped by library.
+     * Source, topology, and syntax failures preserve incomplete status, and
+     * parser cleanup runs even if publication or documentation materialization
+     * throws.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+    private scan;
+    /**
+     * Reconciles library declarations and retains every physical declaration
+     * address.
+     *
+     * This occurs before unit materialization so parts and exports share library
+     * identity.
+     */
+    private materializeUnits;
+    /**
+     * Resolves withdrawals before publishing attached annotation hosts.
+     *
+     * Hidden Dart declarations cannot create claim or review hosts.
+     */
+    private materializeDocumentation;
+    /**
+     * Retains public declaration sites even when they carry no documentation.
+     *
+     * These hosts keep missing documentation visible to graph evaluation.
+     */
+    private materializeUndocumentedHosts;
+    /**
+     * Groups published semantic owners by their physical declaration site.
+     *
+     * One documentation carrier can attach to declarations that share a source
+     * span.
+     */
+    private attachmentGroups;
+    /**
+     * Creates an attached or explicitly unsupported documentation carrier.
+     *
+     * Unsupported carriers remain available for a source-located diagnostic.
+     */
+    private host;
+    /**
+     * Parses Evidence tags only after the adapter establishes their host.
+     *
+     * Tag parsing requires the resolved attachment and unit ownership.
+     */
+    private parse;
+    /**
+     * Detects Evidence or withdrawal annotations outside masked examples.
+     *
+     * Detached annotation carriers still need an unsupported host diagnostic.
+     */
+    private annotation;
+    /**
+     * Detects acknowledgements and reviews on withdrawn carriers.
+     *
+     * Such carriers cannot also produce ordinary claim hosts.
+     */
+    private claimAnnotation;
+    /**
+     * Recognizes supported annotation names at documentation line boundaries.
+     *
+     * Boundary matching prevents prose and examples from becoming tag syntax.
+     */
+    private annotationPattern;
+    /**
+     * Follows explicit parent ownership to propagate withdrawal.
+     *
+     * The visited set terminates malformed ownership cycles.
+     */
+    private withdrawn;
+    /**
+     * Separates defining libraries and programming kinds while merging
+     * complementary accessors.
+     *
+     * Unit IDs remain stable across parts that contribute one public Dart
+     * declaration.
+     */
+    private unitId;
 }