@wrtnlabs/evidence 0.0.0 → 0.1.0

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

@@ -0,0 +1,25 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { EvidenceCDeclarationForm } from "./EvidenceCDeclarationForm";
+import type { IEvidenceCDeclaratorShape } from "./IEvidenceCDeclaratorShape";
+/**
+ * Provides C grammar helpers for names, declarators, comments, and modifiers.
+ *
+ * EvidenceCFileScanner uses these syntactic facts to construct declarations and
+ * documentation records without assigning public-surface policy to this
+ * namespace.
+ */
+export declare namespace EvidenceCSyntax {
+    function name(node: EvidenceNode | null): string | undefined;
+    function declarators(node: EvidenceNode): EvidenceNode[];
+    function declarator(node: EvidenceNode): IEvidenceCDeclaratorShape | undefined;
+    function tagForm(node: EvidenceNode | null): Extract<EvidenceCDeclarationForm, "struct" | "union" | "enum"> | null;
+    function storage(node: EvidenceNode, value: string): boolean;
+    function isStaticAssertion(node: EvidenceNode): boolean;
+    function guardedDeclarations(node: EvidenceNode): EvidenceNode[] | undefined;
+    function isInertDirective(node: EvidenceNode): boolean;
+    function isDoxygen(node: EvidenceNode): boolean;
+    function isTrailingDoxygen(node: EvidenceNode): boolean;
+    function comment(node: EvidenceNode): IEvidenceCommentSyntax;
+    function string(node: EvidenceNode): IEvidenceCommentSyntax | undefined;
+}

package/lib/adapters/c/EvidenceCSyntax.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceCSyntax = void 0;
+/**
+ * Provides C grammar helpers for names, declarators, comments, and modifiers.
+ *
+ * EvidenceCFileScanner uses these syntactic facts to construct declarations and
+ * documentation records without assigning public-surface policy to this
+ * namespace.
+ */
+var EvidenceCSyntax;
+(function (EvidenceCSyntax) {
+    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;
+        });
+    }
+    EvidenceCSyntax.name = name;
+    function declarators(node) {
+        return node.childrenForFieldName("declarator");
+    }
+    EvidenceCSyntax.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;
+    }
+    EvidenceCSyntax.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;
+    }
+    EvidenceCSyntax.tagForm = tagForm;
+    function storage(node, value) {
+        return node.namedChildren.some((child) => child.type === "storage_class_specifier" && child.text === value);
+    }
+    EvidenceCSyntax.storage = storage;
+    function isStaticAssertion(node) {
+        return /^(?:_Static_assert|static_assert)\s*\(/u.test(node.text);
+    }
+    EvidenceCSyntax.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);
+    }
+    EvidenceCSyntax.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"));
+    }
+    EvidenceCSyntax.isInertDirective = isInertDirective;
+    function isDoxygen(node) {
+        return (node.type === "comment" &&
+            /^(?:\/\*\*|\/\*!|\/\/\/|\/\/!)/u.test(node.text));
+    }
+    EvidenceCSyntax.isDoxygen = isDoxygen;
+    function isTrailingDoxygen(node) {
+        return (node.type === "comment" &&
+            /^(?:\/\*\*<|\/\*!<|\/\/\/<|\/\/!<)/u.test(node.text));
+    }
+    EvidenceCSyntax.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,
+        };
+    }
+    EvidenceCSyntax.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,
+            };
+    }
+    EvidenceCSyntax.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);
+    }
+})(EvidenceCSyntax || (exports.EvidenceCSyntax = EvidenceCSyntax = {}));

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

@@ -0,0 +1,80 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { EvidenceCDeclarationForm } from "./EvidenceCDeclarationForm";
+import type { IEvidenceCDeclarationAddress } from "./IEvidenceCDeclarationAddress";
+/**
+ * Captures one supported C declaration before file-local identity
+ * reconciliation.
+ *
+ * `EvidenceCFileScanner` 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 IEvidenceCDeclaration {
+    /**
+     * 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: EvidenceCDeclarationForm;
+    /**
+     * 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: IEvidenceCDeclarationAddress[];
+    /**
+     * 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/IEvidenceCDeclarationAddress.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 IEvidenceCDeclarationAddress {
+    /**
+     * 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/IEvidenceCDeclarationGroup.d.ts

@@ -0,0 +1,25 @@
+import type { IEvidenceCDeclaration } from "./IEvidenceCDeclaration";
+/**
+ * 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 IEvidenceCDeclarationGroup {
+    /**
+     * 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: IEvidenceCDeclaration[];
+}

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

@@ -0,0 +1,34 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { EvidenceCDeclaratorKind } from "./EvidenceCDeclaratorKind";
+/**
+ * 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 IEvidenceCDeclaratorShape {
+    /**
+     * 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: EvidenceCDeclaratorKind;
+    /**
+     * 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: EvidenceNode;
+}

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

@@ -0,0 +1,41 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceCDocumentationAttachment } from "./IEvidenceCDocumentationAttachment";
+/**
+ * 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 IEvidenceCDocumentation {
+    /**
+     * 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: IEvidenceCDocumentationAttachment[];
+}

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

@@ -0,0 +1,22 @@
+/**
+ * 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 IEvidenceCDocumentationAttachment {
+    /**
+     * 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/IEvidenceCFileAnalysis.d.ts

@@ -0,0 +1,51 @@
+import type { IEvidenceDiagnostic } from "../../structures/IEvidenceDiagnostic";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceCDeclaration } from "./IEvidenceCDeclaration";
+import type { IEvidenceCDocumentation } from "./IEvidenceCDocumentation";
+/**
+ * Preserves all C extraction facts that survive one parser session.
+ *
+ * `EvidenceCFileScanner` 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 IEvidenceCFileAnalysis {
+    /**
+     * 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: IEvidenceCDeclaration[];
+    /**
+     * Doxygen or tag-bearing carriers recorded independently of attachment
+     * success.
+     *
+     * This preserves unsupported annotations for diagnostics instead of silently
+     * dropping them.
+     */
+    documentation: IEvidenceCDocumentation[];
+    /**
+     * 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/IEvidenceCTypeContext.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 IEvidenceCTypeContext {
+    /**
+     * 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/EvidenceCppAccess.d.ts

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

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

@@ -1,16 +1,54 @@
-import { CppAdapter } from "./CppAdapter";
+import type { IEvidenceAdapter } from "../../structures/IEvidenceAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
 /**
- * Extracts explicit C++ public declarations and bounded aliases across a snapshot.
+ * Reconciles C++ declaration families, public aliases, and documentation
+ * ownership.
  *
- * Analysis reconciles namespaces, types, callable families, qualified definitions,
- * templates, and public members from selected source. File-qualified addresses
- * retain template arity and operator names as literal segments, and attached
- * Doxygen supplies the documentation hosts used by graph policies.
+ * 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.
  *
- * This is declared-source analysis: it does not expand macros, traverse includes,
- * instantiate or specialize templates, perform inherited or friend lookup, or
- * evaluate module and linker visibility. Such public-surface dependencies cannot
- * be silently treated as absent declarations.
+ * 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 EvidenceCppAdapter extends CppAdapter {
+export declare class EvidenceCppAdapter implements IEvidenceAdapter<"cpp"> {
+    /**
+     * 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.
+     */
+    get 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;
 }