@wrtnlabs/evidence 0.0.0

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

@@ -0,0 +1,7 @@
+/**
+ * Identifies a C++ declaration owner that establishes structural graph scope.
+ *
+ * Nested scanning carries this kind with the scope path to determine member
+ * ownership and the public address shape of declarations it contains.
+ */
+export type CppScopeKind = "namespace" | "class" | "struct" | "union" | "enum";

package/lib/adapters/cpp/CppScopeKind.js

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

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

@@ -0,0 +1,31 @@
+import type { Node } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { CppAccess } from "./CppAccess";
+import type { CppDeclarationForm } from "./CppDeclarationForm";
+import type { ICppDeclaratorShape } from "./ICppDeclaratorShape";
+import type { ICppQualifiedName } from "./ICppQualifiedName";
+/**
+ * Provides C++ grammar helpers for names, declarators, comments, and modifiers.
+ *
+ * CppFileScanner uses these helpers to preserve C++-specific spelling and scope
+ * distinctions while it decides which supported declarations form graph units.
+ */
+export declare namespace CppSyntax {
+    function name(node: Node | null): string | undefined;
+    function qualifiedName(node: Node | null): ICppQualifiedName | undefined;
+    function declarators(node: Node): Node[];
+    function declarator(node: Node): ICppDeclaratorShape | undefined;
+    function recordForm(node: Node | null): Extract<CppDeclarationForm, "class" | "struct" | "union" | "enum"> | null;
+    function templateArity(node: Node): number;
+    function templateBody(node: Node): Node | undefined;
+    function storage(node: Node, value: string): boolean;
+    function topLevelConstObject(node: Node, declarator: Node): boolean;
+    function access(node: Node): CppAccess | undefined;
+    function isStaticAssertion(node: Node): boolean;
+    function guardedDeclarations(node: Node): Node[] | undefined;
+    function isInertDirective(node: Node): boolean;
+    function isDoxygen(node: Node): boolean;
+    function isTrailingDoxygen(node: Node): boolean;
+    function comment(node: Node): IEvidenceCommentSyntax;
+    function string(node: Node): IEvidenceCommentSyntax | undefined;
+}

package/lib/adapters/cpp/CppSyntax.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CppSyntax = void 0;
+/**
+ * Provides C++ grammar helpers for names, declarators, comments, and modifiers.
+ *
+ * CppFileScanner uses these helpers to preserve C++-specific spelling and scope
+ * distinctions while it decides which supported declarations form graph units.
+ */
+var CppSyntax;
+(function (CppSyntax) {
+    function name(node) {
+        if (node === null)
+            return undefined;
+        if ([
+            "identifier",
+            "field_identifier",
+            "type_identifier",
+            "namespace_identifier",
+        ].includes(node.type))
+            return decode(node.text);
+        if (node.type === "destructor_name") {
+            const value = name(node.namedChildren[0] ?? null);
+            return value === undefined ? undefined : `~${value}`;
+        }
+        if (node.type === "operator_name")
+            return operator(node.text);
+        if (node.type === "operator_cast") {
+            const type = node.childForFieldName("type");
+            return type === null ? undefined : `operator ${normalize(type.text)}`;
+        }
+        return undefined;
+    }
+    CppSyntax.name = name;
+    function qualifiedName(node) {
+        if (node === null)
+            return undefined;
+        if (node.type === "qualified_identifier") {
+            const scope = qualifiedName(node.childForFieldName("scope"));
+            const member = qualifiedName(node.childForFieldName("name"));
+            if (member === undefined)
+                return undefined;
+            return {
+                segments: [...(scope?.segments ?? []), ...member.segments],
+                specialized: (scope?.specialized ?? false) || member.specialized,
+            };
+        }
+        if (node.type === "nested_namespace_specifier") {
+            const parts = node.namedChildren.flatMap((child) => {
+                const value = qualifiedName(child);
+                return value === undefined ? [] : [value];
+            });
+            return {
+                segments: parts.flatMap((part) => part.segments),
+                specialized: parts.some((part) => part.specialized),
+            };
+        }
+        if (node.type === "template_type" ||
+            node.type === "template_function" ||
+            node.type === "template_method" ||
+            node.type === "dependent_name") {
+            const wrapped = node.type === "dependent_name" ? node.namedChildren[0] : node;
+            if (wrapped === undefined)
+                return undefined;
+            if (wrapped.type === "dependent_name")
+                return undefined;
+            const value = name(wrapped.childForFieldName("name"));
+            const argumentsNode = wrapped.childForFieldName("arguments");
+            if (value === undefined || argumentsNode === null)
+                return undefined;
+            const argumentsList = argumentsNode.namedChildren.filter((child) => child.type !== "comment");
+            return {
+                segments: [`${value}\`${argumentsList.length}`],
+                specialized: argumentsList.length === 0 ||
+                    argumentsList.some((argument) => !templateParameter(argument)),
+            };
+        }
+        const value = name(node);
+        return value === undefined
+            ? undefined
+            : { segments: [value], specialized: false };
+    }
+    CppSyntax.qualifiedName = qualifiedName;
+    function declarators(node) {
+        return node.childrenForFieldName("declarator");
+    }
+    CppSyntax.declarators = declarators;
+    function declarator(node) {
+        let current = node;
+        let nearest = "direct";
+        while (current !== null) {
+            if (current.type === "operator_cast") {
+                const path = qualifiedName(current);
+                return path === undefined
+                    ? undefined
+                    : {
+                        path: path.segments,
+                        kind: "function",
+                        node,
+                        specialized: path.specialized,
+                    };
+            }
+            const path = qualifiedName(current);
+            if (path !== undefined)
+                return {
+                    path: path.segments,
+                    kind: nearest,
+                    node,
+                    specialized: path.specialized,
+                };
+            switch (current.type) {
+                case "init_declarator":
+                case "attributed_declarator":
+                    current = childDeclarator(current);
+                    break;
+                case "parenthesized_declarator":
+                    current = declaratorChild(current);
+                    break;
+                case "function_declarator":
+                case "abstract_function_declarator":
+                    nearest = "function";
+                    current = childDeclarator(current);
+                    break;
+                case "pointer_declarator":
+                case "pointer_type_declarator":
+                case "reference_declarator":
+                case "reference_type_declarator":
+                case "array_declarator":
+                    nearest = "object";
+                    current = childDeclarator(current);
+                    break;
+                default:
+                    current = childDeclarator(current);
+            }
+        }
+        return undefined;
+    }
+    CppSyntax.declarator = declarator;
+    function recordForm(node) {
+        if (node?.type === "class_specifier")
+            return "class";
+        if (node?.type === "struct_specifier")
+            return "struct";
+        if (node?.type === "union_specifier")
+            return "union";
+        if (node?.type === "enum_specifier")
+            return "enum";
+        return null;
+    }
+    CppSyntax.recordForm = recordForm;
+    function templateArity(node) {
+        const parameters = node.childForFieldName("parameters");
+        return parameters === null
+            ? 0
+            : parameters.namedChildren.filter((child) => child.type !== "comment")
+                .length;
+    }
+    CppSyntax.templateArity = templateArity;
+    function templateBody(node) {
+        return node.namedChildren.find((child) => child.type !== "template_parameter_list" &&
+            child.type !== "requires_clause" &&
+            child.type !== "comment");
+    }
+    CppSyntax.templateBody = templateBody;
+    function storage(node, value) {
+        return node.namedChildren.some((child) => child.type === "storage_class_specifier" && child.text === value);
+    }
+    CppSyntax.storage = storage;
+    function topLevelConstObject(node, declarator) {
+        const constantExpression = node.namedChildren.some((child) => child.text === "constexpr");
+        const external = ["extern", "inline"].some((value) => node.namedChildren.some((child) => child.text === value));
+        if (external)
+            return false;
+        if (constantExpression)
+            return true;
+        const baseConstant = node.namedChildren.some((child) => child.type === "type_qualifier" && child.text === "const");
+        const wrappers = [];
+        let current = declarator;
+        while (current !== null) {
+            if ([
+                "pointer_declarator",
+                "pointer_type_declarator",
+                "reference_declarator",
+                "reference_type_declarator",
+                "array_declarator",
+                "function_declarator",
+                "abstract_function_declarator",
+            ].includes(current.type))
+                wrappers.push(current);
+            current = childDeclarator(current);
+        }
+        for (let index = wrappers.length - 1; index >= 0; --index) {
+            const wrapper = wrappers[index];
+            if (wrapper === undefined)
+                continue;
+            if (wrapper.type === "array_declarator")
+                continue;
+            if (wrapper.type === "pointer_declarator" ||
+                wrapper.type === "pointer_type_declarator")
+                return wrapper.namedChildren.some((child) => child.type === "type_qualifier" && child.text === "const");
+            return false;
+        }
+        return baseConstant;
+    }
+    CppSyntax.topLevelConstObject = topLevelConstObject;
+    function access(node) {
+        const value = node.text.replace(/\s*:\s*$/u, "").trim();
+        return value === "public" || value === "protected" || value === "private"
+            ? value
+            : undefined;
+    }
+    CppSyntax.access = access;
+    function isStaticAssertion(node) {
+        return /^(?:_Static_assert|static_assert)\s*\(/u.test(node.text);
+    }
+    CppSyntax.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 guard = name(node.childForFieldName("name"));
+        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);
+    }
+    CppSyntax.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"));
+    }
+    CppSyntax.isInertDirective = isInertDirective;
+    function isDoxygen(node) {
+        return (node.type === "comment" &&
+            /^(?:\/\*\*|\/\*!|\/\/\/|\/\/!)/u.test(node.text));
+    }
+    CppSyntax.isDoxygen = isDoxygen;
+    function isTrailingDoxygen(node) {
+        return (node.type === "comment" &&
+            /^(?:\/\*\*<|\/\*!<|\/\/\/<|\/\/!<)/u.test(node.text));
+    }
+    CppSyntax.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,
+        };
+    }
+    CppSyntax.comment = comment;
+    function string(node) {
+        if (node.type === "string_literal") {
+            const opening = /^(?:u8|u|U|L)?"/u.exec(node.text)?.[0];
+            return opening === undefined
+                ? undefined
+                : {
+                    opening,
+                    closing: '"',
+                    tagBoundaries: true,
+                    allowWithdrawal: false,
+                };
+        }
+        if (node.type !== "raw_string_literal")
+            return undefined;
+        const opening = /^(?:u8|u|U|L)?R"([^ ()\\\t\r\n]*)\(/u.exec(node.text);
+        return opening === null
+            ? undefined
+            : {
+                opening: opening[0],
+                closing: `)${opening[1] ?? ""}"`,
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+    }
+    CppSyntax.string = string;
+    function childDeclarator(node) {
+        return node.childForFieldName("declarator") ?? declaratorChild(node);
+    }
+    function declaratorChild(node) {
+        return (node.namedChildren.find((child) => qualifiedName(child) !== undefined ||
+            child.type.endsWith("_declarator") ||
+            child.type === "parenthesized_declarator" ||
+            child.type === "operator_cast") ?? null);
+    }
+    function templateParameter(node) {
+        if (node.type === "parameter_pack_expansion") {
+            const pattern = node.childForFieldName("pattern");
+            return pattern !== null && templateParameter(pattern);
+        }
+        if (["identifier", "field_identifier", "type_identifier"].includes(node.type))
+            return true;
+        if (node.type !== "type_descriptor" || node.namedChildren.length !== 1)
+            return false;
+        const child = node.namedChildren[0];
+        return (child !== undefined &&
+            ["identifier", "type_identifier"].includes(child.type));
+    }
+    function operator(input) {
+        return `operator ${input.replace(/^operator\s*/u, "").trim()}`;
+    }
+    function normalize(input) {
+        return input.replace(/\s+/gu, " ").trim();
+    }
+    function decode(input) {
+        return input
+            .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;
+        });
+    }
+})(CppSyntax || (exports.CppSyntax = CppSyntax = {}));

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

@@ -0,0 +1,7 @@
+/**
+ * Records whether C++ declaration visibility is known or deferred to qualification.
+ *
+ * A qualified member requires later owner resolution, whereas public and
+ * non-public declarations can be filtered directly from their lexical context.
+ */
+export type CppVisibility = "public" | "non-public" | "qualified";

package/lib/adapters/cpp/CppVisibility.js

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

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

@@ -0,0 +1,16 @@
+import { CppAdapter } from "./CppAdapter";
+/**
+ * Extracts explicit C++ public declarations and bounded aliases across a snapshot.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare class EvidenceCppAdapter extends CppAdapter {
+}

package/lib/adapters/cpp/EvidenceCppAdapter.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceCppAdapter = void 0;
+const CppAdapter_1 = require("./CppAdapter");
+/**
+ * Extracts explicit C++ public declarations and bounded aliases across a snapshot.
+ *
+ * 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.
+ *
+ * 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.
+ */
+class EvidenceCppAdapter extends CppAdapter_1.CppAdapter {
+}
+exports.EvidenceCppAdapter = EvidenceCppAdapter;

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

@@ -0,0 +1,44 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { CppAliasKind } from "./CppAliasKind";
+/**
+ * Records one statically readable C++ namespace alias or using declaration.
+ *
+ * CppFileScanner emits this physical record alongside declarations, and
+ * CppAdapter resolves public aliases after it materializes semantic units.
+ * Its scoped target and site let that later pass publish alias-derived
+ * addresses without confusing the alias with the selected target unit.
+ */
+export interface ICppAlias {
+    /** Stable scanner-local key used to associate the alias with its source analysis.
+     *
+     * It is not a public accessor or semantic unit identity. */
+    id: string;
+    /** Alias syntax that determines how the resolver follows its target.
+     *
+     * Namespace aliases and using declarations publish through different scopes. */
+    kind: CppAliasKind;
+    /** Alias spelling introduced in `scopeAddress`.
+     *
+     * The resolver appends this name while projecting a target address. */
+    name: string;
+    /** Semantic owner path in which the alias was declared.
+     *
+     * It prevents same-spelled aliases in separate scopes from colliding. */
+    scopeIdentity: string[];
+    /** Public path of the containing scope.
+     *
+     * This path supplies the prefix for addresses published through the alias. */
+    scopeAddress: string[];
+    /** Qualified target path as written by the supported static syntax.
+     *
+     * Resolution fails visibly when this path cannot name one selected unit. */
+    target: string[];
+    /** Source site whose documentation may carry annotations for this alias.
+     *
+     * The site stays physical even when the target unit is shared. */
+    site: IEvidenceUnitSite;
+    /** Whether the alias can publish a target into the configured population.
+     *
+     * Private aliases remain available for local resolution but expose no address. */
+    public: boolean;
+}

package/lib/adapters/cpp/ICppAlias.js

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

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

@@ -0,0 +1,55 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { CppDeclarationForm } from "./CppDeclarationForm";
+import type { CppVisibility } from "./CppVisibility";
+/**
+ * Captures one supported C++ declaration before semantic units are materialized.
+ *
+ * CppFileScanner records source occurrences in this form; CppAdapter groups
+ * compatible occurrences by identity, validates their declaration family, and
+ * publishes the resulting unit's addresses and sites. The record therefore
+ * keeps physical source facts separate from the semantic identity shared by
+ * declarations, definitions, and overloads.
+ */
+export interface ICppDeclaration {
+    /** Scanner-local key for attachments and family reconciliation.
+     *
+     * The adapter replaces this physical-record ID with a semantic unit ID. */
+    id: string;
+    /** Unqualified source spelling used in diagnostics and the published unit.
+     *
+     * Enclosing scopes remain in `identity` and `addresses`. */
+    name: string;
+    /** Evidence symbol category assigned after declaration-family materialization.
+     *
+     * It preserves the graph's language-independent selector vocabulary. */
+    symbol: EvidenceProgrammingSymbol;
+    /** C++ declaration form that controls compatibility within one family.
+     *
+     * Definitions and overloads are reconciled only among compatible forms. */
+    form: CppDeclarationForm;
+    /** Semantic qualified path used to merge compatible source occurrences.
+     *
+     * This identity is distinct from every public alias spelling. */
+    identity: string[];
+    /** Public accessor candidates projected from namespaces and using declarations.
+     *
+     * Each nested array retains segment boundaries for target resolution. */
+    addresses: string[][];
+    /** Physical declaration span retained for hosts and content fingerprints.
+     *
+     * A merged unit may retain several sites from compatible declarations. */
+    site: IEvidenceUnitSite;
+    /** Visibility result before public-address publication.
+     *
+     * Qualified declarations remain distinguishable until their owner is known. */
+    visibility: CppVisibility;
+    /** Whether this occurrence contributes an implementation body.
+     *
+     * Multiple bodies for one applicable family make the inventory incomplete. */
+    definition: boolean;
+    /** Semantic parent path for a member or enumerator.
+     *
+     * Omission denotes a declaration that owns its own top-level unit. */
+    parentIdentity?: string[];
+}

package/lib/adapters/cpp/ICppDeclaration.js

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

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

@@ -0,0 +1,25 @@
+import type { ICppDeclaration } from "./ICppDeclaration";
+/**
+ * Collects C++ declaration occurrences that materialize one semantic unit.
+ *
+ * CppAdapter builds these groups from scanner records using `id`, then uses
+ * their declarations to determine public ownership, validate compatible
+ * declaration and definition families, and construct the unit's sites. It
+ * bridges physical ICppDeclaration records and the final Evidence inventory.
+ */
+export interface ICppDeclarationGroup {
+    /**
+     * Semantic unit ID shared by every declaration in this group.
+     *
+     * CppAdapter derives it from the declarations' symbol and qualified identity
+     * before using it as the unit ID and as the key for public-group selection.
+     */
+    id: string;
+    /**
+     * Physical declaration occurrences assigned to the semantic unit.
+     *
+     * The adapter compares their forms, visibility, and definitions before it
+     * copies selected sites and public addresses into the materialized unit.
+     */
+    declarations: ICppDeclaration[];
+}

package/lib/adapters/cpp/ICppDeclarationGroup.js

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

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

@@ -0,0 +1,42 @@
+import type { Node } from "web-tree-sitter";
+import type { CppDeclaratorKind } from "./CppDeclaratorKind";
+/**
+ * Describes the readable name and outer entity kind of one C++ declarator.
+ *
+ * CppSyntax derives this transient tree-sitter-backed shape while unwrapping a
+ * declarator. CppFileScanner consumes it to classify callable and object
+ * declarations, construct their identities, and reject specializations that
+ * cannot use the adapter's common addressing model.
+ */
+export interface ICppDeclaratorShape {
+    /**
+     * Qualified declarator segments as the grammar exposes them.
+     *
+     * CppFileScanner combines this path with the enclosing scope when needed,
+     * then uses the final segment for the declaration name and the preceding
+     * segments to identify its semantic parent.
+     */
+    path: string[];
+    /**
+     * Outermost declaration category inferred while unwrapping the declarator.
+     *
+     * The scanner uses this category to route the shape to callable or object
+     * extraction instead of inferring that distinction from the name alone.
+     */
+    kind: CppDeclaratorKind;
+    /**
+     * Original declarator node retained for source-site extraction.
+     *
+     * CppFileScanner passes this node to declaration creation so the physical
+     * site follows the declarator even when an enclosing syntax node supplied
+     * the readable path.
+     */
+    node: Node;
+    /**
+     * Whether the readable path denotes a specialized template entity.
+     *
+     * Specialized declarations are reported as unsupported because they cannot
+     * share the primary template's common public accessor.
+     */
+    specialized: boolean;
+}

package/lib/adapters/cpp/ICppDeclaratorShape.js

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

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

@@ -0,0 +1,30 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { ICppDocumentationAttachment } from "./ICppDocumentationAttachment";
+/**
+ * Captures one C++ documentation carrier that may contain Evidence tags.
+ *
+ * CppFileScanner collects supported Doxygen and tag-bearing unsupported
+ * carriers, then records their physical attachments. CppAdapter later reads
+ * the carrier with its syntax, maps attachments through materialized units,
+ * and emits attached or unsupported Evidence hosts without treating a comment
+ * as a declaration itself.
+ */
+export interface ICppDocumentation {
+    /** Stable comment key referenced by source attachments and evidence parsing.
+     *
+     * It identifies the physical comment, not a semantic declaration. */
+    id: string;
+    /** Exact source span excluded from content fingerprints after annotation parsing.
+     *
+     * The range preserves the carrier location for diagnostics. */
+    range: IEvidenceSourceRange;
+    /** Delimiter and indentation rules required to read this Doxygen carrier.
+     *
+     * Evidence parsing uses the syntax instead of guessing from raw source text. */
+    syntax: IEvidenceCommentSyntax;
+    /** Supported declaration sites that accept this carrier as documentation.
+     *
+     * Attachment is established during scanning before alias materialization. */
+    attachments: ICppDocumentationAttachment[];
+}

package/lib/adapters/cpp/ICppDocumentation.js

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