@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/c/CSyntax.js

@@ -1,164 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CSyntax = void 0;
-/**
- * Provides C grammar helpers for names, declarators, comments, and modifiers.
- *
- * CFileScanner uses these syntactic facts to construct declarations and
- * documentation records without assigning public-surface policy to this namespace.
- */
-var CSyntax;
-(function (CSyntax) {
-    function name(node) {
-        if (node === null ||
-            !["identifier", "field_identifier", "type_identifier"].includes(node.type))
-            return undefined;
-        return node.text
-            .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;
-        });
-    }
-    CSyntax.name = name;
-    function declarators(node) {
-        return node.childrenForFieldName("declarator");
-    }
-    CSyntax.declarators = declarators;
-    function declarator(node) {
-        let current = node;
-        let nearest = "direct";
-        while (current !== null) {
-            const value = name(current);
-            if (value !== undefined)
-                return { name: value, kind: nearest, node };
-            switch (current.type) {
-                case "init_declarator":
-                case "attributed_declarator":
-                    current = childDeclarator(current);
-                    break;
-                case "parenthesized_declarator":
-                    current = declaratorChild(current);
-                    break;
-                case "function_declarator":
-                    nearest = "function";
-                    current = childDeclarator(current);
-                    break;
-                case "pointer_declarator":
-                case "array_declarator":
-                    nearest = "object";
-                    current = childDeclarator(current);
-                    break;
-                default:
-                    current = childDeclarator(current);
-            }
-        }
-        return undefined;
-    }
-    CSyntax.declarator = declarator;
-    function tagForm(node) {
-        if (node?.type === "struct_specifier")
-            return "struct";
-        if (node?.type === "union_specifier")
-            return "union";
-        if (node?.type === "enum_specifier")
-            return "enum";
-        return null;
-    }
-    CSyntax.tagForm = tagForm;
-    function storage(node, value) {
-        return node.namedChildren.some((child) => child.type === "storage_class_specifier" && child.text === value);
-    }
-    CSyntax.storage = storage;
-    function isStaticAssertion(node) {
-        return /^(?:_Static_assert|static_assert)\s*\(/u.test(node.text);
-    }
-    CSyntax.isStaticAssertion = isStaticAssertion;
-    function guardedDeclarations(node) {
-        if (node.type !== "preproc_ifdef" || !/^#\s*ifndef\b/u.test(node.text))
-            return undefined;
-        if (node.childForFieldName("alternative") !== null)
-            return undefined;
-        const nameNode = node.childForFieldName("name");
-        const guard = name(nameNode);
-        if (guard === undefined)
-            return undefined;
-        const body = node.namedChildren.slice(1);
-        const definition = body[0];
-        if (definition?.type !== "preproc_def" ||
-            name(definition.childForFieldName("name")) !== guard)
-            return undefined;
-        return body.slice(1);
-    }
-    CSyntax.guardedDeclarations = guardedDeclarations;
-    function isInertDirective(node) {
-        if (node.type !== "preproc_call")
-            return false;
-        const directive = node.childForFieldName("directive")?.text;
-        const argumentNode = node.childForFieldName("argument");
-        const argument = argumentNode === null ? undefined : argumentNode.text.trim();
-        return (directive === "#undef" ||
-            directive === "#line" ||
-            (directive === "#pragma" && argument === "once"));
-    }
-    CSyntax.isInertDirective = isInertDirective;
-    function isDoxygen(node) {
-        return (node.type === "comment" &&
-            /^(?:\/\*\*|\/\*!|\/\/\/|\/\/!)/u.test(node.text));
-    }
-    CSyntax.isDoxygen = isDoxygen;
-    function isTrailingDoxygen(node) {
-        return (node.type === "comment" &&
-            /^(?:\/\*\*<|\/\*!<|\/\/\/<|\/\/!<)/u.test(node.text));
-    }
-    CSyntax.isTrailingDoxygen = isTrailingDoxygen;
-    function comment(node) {
-        for (const opening of ["///<", "//!<", "///", "//!", "//"])
-            if (node.text.startsWith(opening))
-                return {
-                    opening,
-                    closing: "",
-                    linePrefix: opening,
-                    tagBoundaries: true,
-                    allowWithdrawal: opening !== "//",
-                };
-        for (const opening of ["/**<", "/*!<", "/**", "/*!", "/*"])
-            if (node.text.startsWith(opening))
-                return {
-                    opening,
-                    closing: "*/",
-                    linePrefix: "*",
-                    tagBoundaries: true,
-                    allowWithdrawal: opening !== "/*",
-                };
-        return {
-            opening: "/*",
-            closing: "*/",
-            tagBoundaries: true,
-            allowWithdrawal: false,
-        };
-    }
-    CSyntax.comment = comment;
-    function string(node) {
-        if (node.type !== "string_literal")
-            return undefined;
-        const prefix = /^(?:u8|u|U|L)?"/u.exec(node.text)?.[0];
-        return prefix === undefined
-            ? undefined
-            : {
-                opening: prefix,
-                closing: '"',
-                tagBoundaries: true,
-                allowWithdrawal: false,
-            };
-    }
-    CSyntax.string = string;
-    function childDeclarator(node) {
-        return node.childForFieldName("declarator") ?? declaratorChild(node);
-    }
-    function declaratorChild(node) {
-        return (node.namedChildren.find((child) => name(child) !== undefined ||
-            child.type.endsWith("_declarator") ||
-            child.type === "parenthesized_declarator") ?? null);
-    }
-})(CSyntax || (exports.CSyntax = CSyntax = {}));

package/lib/adapters/c/ICDeclaration.d.ts

@@ -1,74 +0,0 @@
-import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
-import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
-import type { CDeclarationForm } from "./CDeclarationForm";
-import type { ICDeclarationAddress } from "./ICDeclarationAddress";
-/**
- * Captures one supported C declaration before file-local identity reconciliation.
- *
- * `CFileScanner` creates this record without retaining a Tree-sitter node. The
- * adapter later groups compatible records by `identity`, expands their public
- * addresses, and uses `site` to retain the physical source location that may
- * host a Doxygen annotation.
- */
-export interface ICDeclaration {
-    /**
-     * Stable scanner-local key used by documentation attachments and grouping.
-     *
-     * Materialization replaces this physical-record key with the group's semantic unit ID.
-     */
-    id: string;
-    /**
-     * Source spelling of this declared entity, without its enclosing path.
-     *
-     * The adapter uses `identity` and `addresses` for the enclosing semantic and public paths.
-     */
-    name: string;
-    /**
-     * Graph symbol category published when the declaration becomes a unit.
-     *
-     * It preserves Evidence's language-independent target selection vocabulary.
-     */
-    symbol: EvidenceProgrammingSymbol;
-    /**
-     * C source form that determines conflict and alias reconciliation rules.
-     *
-     * Only compatible forms may contribute to one materialized declaration family.
-     */
-    form: CDeclarationForm;
-    /**
-     * Canonical semantic path used to group compatible declarations in one file.
-     *
-     * It is distinct from alias spellings that may appear in `addresses`.
-     */
-    identity: string[];
-    /**
-     * Public spelling candidates, including supported tag and typedef aliases.
-     *
-     * Materialization publishes only unambiguous candidates under its canonical-prefix rules.
-     */
-    addresses: ICDeclarationAddress[];
-    /**
-     * Source position and content span preserved for fingerprinting and hosts.
-     *
-     * Compatible declarations may contribute distinct physical sites to one unit.
-     */
-    site: IEvidenceUnitSite;
-    /**
-     * Whether this occurrence supplies a body rather than only a declaration.
-     *
-     * Repeated bodies in an otherwise incompatible family make the inventory incomplete.
-     */
-    definition: boolean;
-    /**
-     * Owning aggregate declaration when this record is a field or enumerator.
-     *
-     * Omission identifies a declaration that owns a top-level unit.
-     */
-    ownerDeclarationId?: string;
-    /**
-     * Struct, union, or enum tag when that namespace names this declaration.
-     *
-     * The tag can provide a public address separate from the ordinary identifier.
-     */
-    tagName?: string;
-}

package/lib/adapters/c/ICDeclarationAddress.d.ts

@@ -1,28 +0,0 @@
-/**
- * Describes one public C path emitted from a declaration.
- *
- * A declaration can be reached through its ordinary identifier and, where the
- * language permits it, a tag or typedef spelling. `canonical` distinguishes the
- * spelling that establishes identity from aliases that must yield to a canonical
- * declaration occupying one of their prefixes.
- */
-export interface ICDeclarationAddress {
-    /**
-     * Ordered accessor segments used by Evidence target resolution.
-     *
-     * Segment boundaries preserve the exact public spelling of this C path.
-     */
-    segments: string[];
-    /**
-     * Whether this path is the declaration's language-namespace spelling.
-     *
-     * Canonical paths take precedence over aliases that would otherwise collide.
-     */
-    canonical: boolean;
-    /**
-     * Canonical prefixes that suppress this alias when they are already occupied.
-     *
-     * They prevent a typedef or tag alias from changing an existing semantic owner's address.
-     */
-    aliasPrefixes: string[][];
-}

package/lib/adapters/c/ICDeclarationGroup.d.ts

@@ -1,23 +0,0 @@
-import type { ICDeclaration } from "./ICDeclaration";
-/**
- * Collects C declarations that claim one file-local semantic identity.
- *
- * The C adapter deliberately limits this group to one physical source file:
- * equal names in separate translation units do not prove C linkage equivalence.
- * Materialization uses the members to detect incompatible forms and duplicate
- * definitions before it publishes a single Evidence unit.
- */
-export interface ICDeclarationGroup {
-    /**
-     * File-qualified identifier shared by every member of the group.
-     *
-     * The adapter uses it as the materialized unit ID within this physical source boundary.
-     */
-    id: string;
-    /**
-     * Declarations whose forms and definitions must be mutually compatible.
-     *
-     * Their sites and addresses become the selected unit only after validation succeeds.
-     */
-    declarations: ICDeclaration[];
-}

package/lib/adapters/c/ICDeclaratorShape.d.ts

@@ -1,30 +0,0 @@
-import type { Node } from "web-tree-sitter";
-import type { CDeclaratorKind } from "./CDeclaratorKind";
-/**
- * Represents the static information recoverable from one C declarator subtree.
- *
- * C declarations can wrap names in pointer, array, parenthesized, and function
- * declarators. The scanner separates the readable identifier and effective
- * entity kind from the original node so callers can classify it without trying
- * to evaluate C types or macros.
- */
-export interface ICDeclaratorShape {
-    /**
-     * Declared identifier read from the effective direct declarator.
-     *
-     * The scanner combines it with its enclosing context to create a declaration identity.
-     */
-    name: string;
-    /**
-     * Whether the effective declarator denotes a direct, function, or object entity.
-     *
-     * The scanner routes the shape to callable or object extraction with this classification.
-     */
-    kind: CDeclaratorKind;
-    /**
-     * Original declarator subtree used to derive source sites and diagnostics.
-     *
-     * Retaining the node keeps physical locations tied to the declarator that supplied the name.
-     */
-    node: Node;
-}

package/lib/adapters/c/ICDocumentation.d.ts

@@ -1,36 +0,0 @@
-import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
-import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
-import type { ICDocumentationAttachment } from "./ICDocumentationAttachment";
-/**
- * Stores a C comment or literal that may carry Evidence tags.
- *
- * The scanner retains carriers even when no supported declaration accepts them.
- * That distinction lets the adapter publish a diagnostic host for misplaced
- * annotations instead of silently discarding an annotation requested by source.
- */
-export interface ICDocumentation {
-    /**
-     * Stable source-range key used to deduplicate one documentation carrier.
-     *
-     * It identifies the physical carrier rather than a declaration or semantic unit.
-     */
-    id: string;
-    /**
-     * Exact carrier range, later excluded from the source fingerprint as needed.
-     *
-     * The adapter also uses it as the host location for parsed or unsupported annotations.
-     */
-    range: IEvidenceSourceRange;
-    /**
-     * Delimiters and tag-boundary rules required to parse the carrier's text.
-     *
-     * Documentation reading uses this syntax rather than guessing from raw source.
-     */
-    syntax: IEvidenceCommentSyntax;
-    /**
-     * Supported declaration sites to which this carrier attaches.
-     *
-     * Unattached tag-bearing carriers remain available for unsupported-host diagnostics.
-     */
-    attachments: ICDocumentationAttachment[];
-}

package/lib/adapters/c/ICDocumentationAttachment.d.ts

@@ -1,21 +0,0 @@
-/**
- * Associates one Doxygen carrier with one eligible C declaration position.
- *
- * A declaration can expose several sites through grouped declarators, so the
- * declaration key alone is insufficient. The site key identifies the exact
- * host retained by inventory materialization.
- */
-export interface ICDocumentationAttachment {
-    /**
-     * Scanner-local declaration key for the semantic owner candidate.
-     *
-     * Materialization maps it to a selected unit only after declaration grouping.
-     */
-    declarationId: string;
-    /**
-     * Physical declaration site that accepts the preceding documentation.
-     *
-     * It prevents a shared declaration family from borrowing a different occurrence's comment.
-     */
-    siteId: string;
-}

package/lib/adapters/c/ICFileAnalysis.d.ts

@@ -1,44 +0,0 @@
-import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
-import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
-import type { ICDeclaration } from "./ICDeclaration";
-import type { ICDocumentation } from "./ICDocumentation";
-/**
- * Preserves all C extraction facts that survive one parser session.
- *
- * `CFileScanner` returns this node-free record so the shared parser can close
- * before cross-record reconciliation begins. The adapter combines declarations
- * and documentation with the captured source, while `diagnostics` and
- * `complete` ensure a partial scan cannot masquerade as a complete inventory.
- */
-export interface ICFileAnalysis {
-    /**
-     * Captured physical source and the configured addresses that expose it.
-     *
-     * Materialization uses the source to place units, hosts, and diagnostics in the snapshot.
-     */
-    source: IEvidenceSourceFile;
-    /**
-     * Supported declarations discovered in this file before grouping.
-     *
-     * The adapter reconciles them only with compatible records from the same source.
-     */
-    declarations: ICDeclaration[];
-    /**
-     * Doxygen or tag-bearing carriers recorded independently of attachment success.
-     *
-     * This preserves unsupported annotations for diagnostics instead of silently dropping them.
-     */
-    documentation: ICDocumentation[];
-    /**
-     * Parsing and extraction findings attributed to this source file.
-     *
-     * The adapter copies them into the final inventory rather than shrinking its population.
-     */
-    diagnostics: IEvidenceDiagnostic[];
-    /**
-     * Whether scanning found every construct needed for a trustworthy result.
-     *
-     * A false value prevents a partial source surface from passing coverage checks.
-     */
-    complete: boolean;
-}

package/lib/adapters/c/ICTypeContext.d.ts

@@ -1,21 +0,0 @@
-/**
- * Carries the enclosing aggregate or enum while its nested C members are scanned.
- *
- * Fields and enumerators derive their ownership and semantic path from this
- * context. Keeping the declaration key as well as the path allows later
- * materialization to attach the member to the exact selected parent unit.
- */
-export interface ICTypeContext {
-    /**
-     * Scanner-local declaration key for the enclosing aggregate or enum.
-     *
-     * Nested declarations retain it until the adapter resolves their selected parent unit.
-     */
-    declarationId: string;
-    /**
-     * Canonical enclosing path prepended to each nested member identity.
-     *
-     * It keeps member identity separate from any tag or typedef public address.
-     */
-    identity: string[];
-}

package/lib/adapters/cpp/CppAccess.d.ts

@@ -1,7 +0,0 @@
-/**
- * Represents the access section currently governing a C++ member declaration.
- *
- * CppFileScanner carries this value through nested records so their visibility
- * can account for both the member's section and its containing type.
- */
-export type CppAccess = "public" | "protected" | "private";

package/lib/adapters/cpp/CppAdapter.d.ts

@@ -1,50 +0,0 @@
-import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
-import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
-import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
-/**
- * Reconciles C++ declaration families, public aliases, and documentation ownership.
- *
- * The scanner records lexical declarations and qualified definitions before the
- * snapshot-wide materializer decides which occurrences belong to one unit.
- * Alias resolution can then project public paths without changing canonical
- * identity. Documentation is attached only after those relationships are known.
- *
- * The pipeline carries conflicts and unsupported source forms into incomplete
- * output. It does not replace C++ lookup, preprocessing, or instantiation with
- * name-based guesses merely to produce a smaller public inventory.
- */
-export declare class CppAdapter implements IEvidenceAdapter {
-    /**
-     * C++ artifact discriminator used by the public adapter.
-     *
-     * The configured type selects C++ grammar and ownership policy even for header
-     * extensions also accepted by C; extension overlap does not choose semantics.
-     */
-    readonly type = "cpp";
-    /**
-     * Builds a C++ inventory from an owned copy of the source snapshot.
-     *
-     * Parsing precedes declaration and alias reconciliation, followed by annotation
-     * materialization and common inventory validation. Failures retain diagnostics,
-     * and the invocation's parser closes regardless of the extraction outcome.
-     */
-    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
-    private scan;
-    private materializeUnits;
-    private checkGroup;
-    private resolveAliases;
-    private aliasCandidates;
-    private addAddress;
-    private materializeDocumentation;
-    private materializeUndocumentedHosts;
-    private attachmentGroups;
-    private host;
-    private parse;
-    private annotation;
-    private claimAnnotation;
-    private annotationPattern;
-    private withdrawn;
-    private unitId;
-    private typeId;
-    private problem;
-}