@wrtnlabs/evidence 0.0.0

package/lib/adapters/c/CSyntax.js

@@ -0,0 +1,164 @@
+"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/EvidenceCAdapter.d.ts

@@ -0,0 +1,15 @@
+import { CAdapter } from "./CAdapter";
+/**
+ * Extracts C external declarations, tags, typedefs, and aggregate members.
+ *
+ * Identity reconciliation stays within each selected physical file. Public
+ * addresses preserve exact tag names and unambiguous typedef aliases, while
+ * attached Doxygen establishes evidence positions. Shared declarator sites do
+ * not require sibling variables to share semantic identity or fingerprint content.
+ *
+ * The adapter does not evaluate preprocessor branches, expand macros, traverse
+ * includes, or infer linker exports. Uncertainty affecting the selected public
+ * surface is reported instead of being removed from the denominator.
+ */
+export declare class EvidenceCAdapter extends CAdapter {
+}

package/lib/adapters/c/EvidenceCAdapter.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceCAdapter = void 0;
+const CAdapter_1 = require("./CAdapter");
+/**
+ * Extracts C external declarations, tags, typedefs, and aggregate members.
+ *
+ * Identity reconciliation stays within each selected physical file. Public
+ * addresses preserve exact tag names and unambiguous typedef aliases, while
+ * attached Doxygen establishes evidence positions. Shared declarator sites do
+ * not require sibling variables to share semantic identity or fingerprint content.
+ *
+ * The adapter does not evaluate preprocessor branches, expand macros, traverse
+ * includes, or infer linker exports. Uncertainty affecting the selected public
+ * surface is reported instead of being removed from the denominator.
+ */
+class EvidenceCAdapter extends CAdapter_1.CAdapter {
+}
+exports.EvidenceCAdapter = EvidenceCAdapter;

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

@@ -0,0 +1,74 @@
+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/ICDeclaration.js

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

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

@@ -0,0 +1,28 @@
+/**
+ * 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/ICDeclarationAddress.js

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

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

@@ -0,0 +1,23 @@
+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/ICDeclarationGroup.js

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

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

@@ -0,0 +1,30 @@
+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/ICDeclaratorShape.js

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

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

@@ -0,0 +1,36 @@
+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/ICDocumentation.js

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

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

@@ -0,0 +1,21 @@
+/**
+ * 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/ICDocumentationAttachment.js

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

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

@@ -0,0 +1,44 @@
+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/ICFileAnalysis.js

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

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

@@ -0,0 +1,21 @@
+/**
+ * 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/c/ICTypeContext.js

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

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

@@ -0,0 +1,7 @@
+/**
+ * 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/CppAccess.js

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

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

@@ -0,0 +1,50 @@
+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;
+}