@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/csharp/CSharpSyntax.js

@@ -1,174 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CSharpSyntax = void 0;
-/**
- * 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.
- */
-var CSharpSyntax;
-(function (CSharpSyntax) {
-    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;
-        });
-    }
-    CSharpSyntax.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];
-    }
-    CSharpSyntax.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;
-    }
-    CSharpSyntax.typeParameterArity = typeParameterArity;
-    function hasModifier(node, modifier) {
-        return node.namedChildren.some((child) => child.type === "modifier" && child.text === modifier);
-    }
-    CSharpSyntax.hasModifier = hasModifier;
-    function hasToken(node, token) {
-        return node.children.some((child) => child.type === token);
-    }
-    CSharpSyntax.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";
-    }
-    CSharpSyntax.accessibility = accessibility;
-    function isXmlDocumentation(node) {
-        return (node.type === "comment" &&
-            (node.text.startsWith("///") || node.text.startsWith("/**")));
-    }
-    CSharpSyntax.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,
-        };
-    }
-    CSharpSyntax.comment = comment;
-    function explicitInterface(node) {
-        return node.namedChildren.some((child) => child.type === "explicit_interface_specifier");
-    }
-    CSharpSyntax.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}`;
-    }
-    CSharpSyntax.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)}`;
-    }
-    CSharpSyntax.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,
-            };
-    }
-    CSharpSyntax.string = string;
-    function normalize(value) {
-        return value.replace(/\s+/gu, " ").trim();
-    }
-})(CSharpSyntax || (exports.CSharpSyntax = CSharpSyntax = {}));

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

@@ -1,7 +0,0 @@
-/**
- * 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 CSharpTypeKind = "class" | "struct" | "interface" | "record" | "enum" | "delegate";

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

@@ -1,63 +0,0 @@
-import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
-import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
-import type { CSharpAccessibility } from "./CSharpAccessibility";
-import type { CSharpDeclarationForm } from "./CSharpDeclarationForm";
-import type { ICSharpDeclarationAddress } from "./ICSharpDeclarationAddress";
-/**
- * Records one physical C# declaration before adapter-level family reconciliation.
- *
- * `CSharpFileScanner` creates this record with the declaration's syntax-derived
- * identity, addresses, visibility inputs, and documentation site. `CSharpAdapter`
- * groups compatible records into semantic units, so partial declarations and
- * overloads can retain their distinct source attachments while sharing one unit.
- */
-export interface ICSharpDeclaration {
-    /** 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: CSharpDeclarationForm;
-    /** 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: ICSharpDeclarationAddress[];
-    /** 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: CSharpAccessibility;
-    /** 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/ICSharpDeclarationAddress.d.ts

@@ -1,22 +0,0 @@
-/**
- * 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. `CSharpAdapter` uses their canonical
- * and alias-prefix provenance when publishing public addresses, preserving the
- * declaration's semantic identity independently from its accessible spellings.
- */
-export interface ICSharpDeclarationAddress {
-    /** 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/ICSharpDeclarationGroup.d.ts

@@ -1,19 +0,0 @@
-import type { ICSharpDeclaration } from "./ICSharpDeclaration";
-/**
- * Collects physical declarations that resolve to one C# semantic unit.
- *
- * `CSharpAdapter` 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 ICSharpDeclarationGroup {
-    /** 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: ICSharpDeclaration[];
-}

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

@@ -1,43 +0,0 @@
-import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-import type { ICSharpDocumentationAttachment } from "./ICSharpDocumentationAttachment";
-/**
- * Retains one C# XML documentation carrier until the adapter creates evidence hosts.
- *
- * CSharpFileScanner records its physical range, comment syntax, and accepted
- * declaration sites without binding it to a semantic unit. CSharpAdapter later
- * groups its attachments against published declarations, then parses the same
- * carrier either as attached documentation or as an unsupported annotation.
- */
-export interface ICSharpDocumentation {
-    /**
-     * 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.
-     *
-     * CSharpDocumentation 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: ICSharpDocumentationAttachment[];
-}

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

@@ -1,25 +0,0 @@
-/**
- * Records one scanner-approved ownership link from XML documentation to a C# declaration site.
- *
- * ICSharpDocumentation stores these physical links while parsing is still close
- * to source syntax. CSharpAdapter resolves the declaration record to a published
- * semantic unit and groups links by site when it creates evidence hosts.
- */
-export interface ICSharpDocumentationAttachment {
-    /**
-     * Identifies the scanner-local declaration that receives this XML documentation.
-     *
-     * CSharpAdapter 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/ICSharpFileAnalysis.d.ts

@@ -1,51 +0,0 @@
-import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { ICSharpDeclaration } from "./ICSharpDeclaration";
-import type { ICSharpDocumentation } from "./ICSharpDocumentation";
-/**
- * Carries one source file's C# extraction after its Tree-sitter session can close.
- *
- * CSharpFileScanner produces this node-free boundary between syntax traversal and
- * CSharpAdapter 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 ICSharpFileAnalysis {
-    /**
-     * Identifies the source snapshot from which this extraction was produced.
-     *
-     * CSharpAdapter 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: ICSharpDeclaration[];
-    /**
-     * 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: ICSharpDocumentation[];
-    /**
-     * 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/ICSharpTypeContext.d.ts

@@ -1,41 +0,0 @@
-import type { CSharpTypeKind } from "./CSharpTypeKind";
-import type { ICSharpDeclarationAddress } from "./ICSharpDeclarationAddress";
-/**
- * Carries the enclosing C# type state while the scanner traverses nested declarations.
- *
- * CSharpFileScanner 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 ICSharpTypeContext {
-    /**
-     * 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: ICSharpDeclarationAddress[];
-    /**
-     * 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: CSharpTypeKind;
-}

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

@@ -1,96 +0,0 @@
-import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
-import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
-import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
-/**
- * Resolves Dart library topology before publishing declarations and documentation.
- *
- * 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 DartAdapter implements IEvidenceAdapter {
-    /**
-     * 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.
-     */
-    readonly 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;
-}