@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/cpp/EvidenceCppScopeKind.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 EvidenceCppScopeKind = "namespace" | "class" | "struct" | "union" | "enum";

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

@@ -0,0 +1,32 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { EvidenceCppAccess } from "./EvidenceCppAccess";
+import type { EvidenceCppDeclarationForm } from "./EvidenceCppDeclarationForm";
+import type { IEvidenceCppDeclaratorShape } from "./IEvidenceCppDeclaratorShape";
+import type { IEvidenceCppQualifiedName } from "./IEvidenceCppQualifiedName";
+/**
+ * Provides C++ grammar helpers for names, declarators, comments, and modifiers.
+ *
+ * EvidenceCppFileScanner uses these helpers to preserve C++-specific spelling
+ * and scope distinctions while it decides which supported declarations form
+ * graph units.
+ */
+export declare namespace EvidenceCppSyntax {
+    function name(node: EvidenceNode | null): string | undefined;
+    function qualifiedName(node: EvidenceNode | null): IEvidenceCppQualifiedName | undefined;
+    function declarators(node: EvidenceNode): EvidenceNode[];
+    function declarator(node: EvidenceNode): IEvidenceCppDeclaratorShape | undefined;
+    function recordForm(node: EvidenceNode | null): Extract<EvidenceCppDeclarationForm, "class" | "struct" | "union" | "enum"> | null;
+    function templateArity(node: EvidenceNode): number;
+    function templateBody(node: EvidenceNode): EvidenceNode | undefined;
+    function storage(node: EvidenceNode, value: string): boolean;
+    function topLevelConstObject(node: EvidenceNode, declarator: EvidenceNode): boolean;
+    function access(node: EvidenceNode): EvidenceCppAccess | undefined;
+    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/cpp/EvidenceCppSyntax.js

@@ -0,0 +1,343 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceCppSyntax = void 0;
+/**
+ * Provides C++ grammar helpers for names, declarators, comments, and modifiers.
+ *
+ * EvidenceCppFileScanner uses these helpers to preserve C++-specific spelling
+ * and scope distinctions while it decides which supported declarations form
+ * graph units.
+ */
+var EvidenceCppSyntax;
+(function (EvidenceCppSyntax) {
+    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;
+    }
+    EvidenceCppSyntax.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 };
+    }
+    EvidenceCppSyntax.qualifiedName = qualifiedName;
+    function declarators(node) {
+        return node.childrenForFieldName("declarator");
+    }
+    EvidenceCppSyntax.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;
+    }
+    EvidenceCppSyntax.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;
+    }
+    EvidenceCppSyntax.recordForm = recordForm;
+    function templateArity(node) {
+        const parameters = node.childForFieldName("parameters");
+        return parameters === null
+            ? 0
+            : parameters.namedChildren.filter((child) => child.type !== "comment")
+                .length;
+    }
+    EvidenceCppSyntax.templateArity = templateArity;
+    function templateBody(node) {
+        return node.namedChildren.find((child) => child.type !== "template_parameter_list" &&
+            child.type !== "requires_clause" &&
+            child.type !== "comment");
+    }
+    EvidenceCppSyntax.templateBody = templateBody;
+    function storage(node, value) {
+        return node.namedChildren.some((child) => child.type === "storage_class_specifier" && child.text === value);
+    }
+    EvidenceCppSyntax.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;
+    }
+    EvidenceCppSyntax.topLevelConstObject = topLevelConstObject;
+    function access(node) {
+        const value = node.text.replace(/\s*:\s*$/u, "").trim();
+        return value === "public" || value === "protected" || value === "private"
+            ? value
+            : undefined;
+    }
+    EvidenceCppSyntax.access = access;
+    function isStaticAssertion(node) {
+        return /^(?:_Static_assert|static_assert)\s*\(/u.test(node.text);
+    }
+    EvidenceCppSyntax.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);
+    }
+    EvidenceCppSyntax.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"));
+    }
+    EvidenceCppSyntax.isInertDirective = isInertDirective;
+    function isDoxygen(node) {
+        return (node.type === "comment" &&
+            /^(?:\/\*\*|\/\*!|\/\/\/|\/\/!)/u.test(node.text));
+    }
+    EvidenceCppSyntax.isDoxygen = isDoxygen;
+    function isTrailingDoxygen(node) {
+        return (node.type === "comment" &&
+            /^(?:\/\*\*<|\/\*!<|\/\/\/<|\/\/!<)/u.test(node.text));
+    }
+    EvidenceCppSyntax.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,
+        };
+    }
+    EvidenceCppSyntax.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,
+            };
+    }
+    EvidenceCppSyntax.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;
+        });
+    }
+})(EvidenceCppSyntax || (exports.EvidenceCppSyntax = EvidenceCppSyntax = {}));

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

@@ -0,0 +1,8 @@
+/**
+ * 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 EvidenceCppVisibility = "public" | "non-public" | "qualified";

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

@@ -0,0 +1,62 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceCppAliasKind } from "./EvidenceCppAliasKind";
+/**
+ * Records one statically readable C++ namespace alias or using declaration.
+ *
+ * EvidenceCppFileScanner emits this physical record alongside declarations, and
+ * EvidenceCppAdapter 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 IEvidenceCppAlias {
+    /**
+     * 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: EvidenceCppAliasKind;
+    /**
+     * 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/IEvidenceCppDeclaration.d.ts

@@ -0,0 +1,77 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { EvidenceCppDeclarationForm } from "./EvidenceCppDeclarationForm";
+import type { EvidenceCppVisibility } from "./EvidenceCppVisibility";
+/**
+ * Captures one supported C++ declaration before semantic units are
+ * materialized.
+ *
+ * EvidenceCppFileScanner records source occurrences in this form;
+ * EvidenceCppAdapter 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 IEvidenceCppDeclaration {
+    /**
+     * 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: EvidenceCppDeclarationForm;
+    /**
+     * 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: EvidenceCppVisibility;
+    /**
+     * 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/IEvidenceCppDeclarationGroup.d.ts

@@ -0,0 +1,27 @@
+import type { IEvidenceCppDeclaration } from "./IEvidenceCppDeclaration";
+/**
+ * Collects C++ declaration occurrences that materialize one semantic unit.
+ *
+ * EvidenceCppAdapter 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 IEvidenceCppDeclaration records and the final Evidence
+ * inventory.
+ */
+export interface IEvidenceCppDeclarationGroup {
+    /**
+     * Semantic unit ID shared by every declaration in this group.
+     *
+     * EvidenceCppAdapter 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: IEvidenceCppDeclaration[];
+}

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

@@ -0,0 +1,42 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { EvidenceCppDeclaratorKind } from "./EvidenceCppDeclaratorKind";
+/**
+ * Describes the readable name and outer entity kind of one C++ declarator.
+ *
+ * EvidenceCppSyntax derives this transient tree-sitter-backed shape while
+ * unwrapping a declarator. EvidenceCppFileScanner 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 IEvidenceCppDeclaratorShape {
+    /**
+     * Qualified declarator segments as the grammar exposes them.
+     *
+     * EvidenceCppFileScanner 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: EvidenceCppDeclaratorKind;
+    /**
+     * Original declarator node retained for source-site extraction.
+     *
+     * EvidenceCppFileScanner passes this node to declaration creation so the
+     * physical site follows the declarator even when an enclosing syntax node
+     * supplied the readable path.
+     */
+    node: EvidenceNode;
+    /**
+     * 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/IEvidenceCppDocumentation.d.ts

@@ -0,0 +1,39 @@
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+import type { IEvidenceSourceRange } from "../../structures/IEvidenceSourceRange";
+import type { IEvidenceCppDocumentationAttachment } from "./IEvidenceCppDocumentationAttachment";
+/**
+ * Captures one C++ documentation carrier that may contain Evidence tags.
+ *
+ * EvidenceCppFileScanner collects supported Doxygen and tag-bearing unsupported
+ * carriers, then records their physical attachments. EvidenceCppAdapter 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 IEvidenceCppDocumentation {
+    /**
+     * 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: IEvidenceCppDocumentationAttachment[];
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Records one scanner-established relationship between documentation and a C++
+ * declaration site.
+ *
+ * `EvidenceCppFileScanner` creates these records while source adjacency is
+ * available. `EvidenceCppAdapter` uses the declaration ID to find the selected
+ * unit and the site ID to create the physical documentation host, preserving
+ * distinct overload and alias locations.
+ */
+export interface IEvidenceCppDocumentationAttachment {
+    /**
+     * Scanner-local declaration or alias record that receives the documentation.
+     *
+     * `EvidenceCppAdapter` resolves this ID to a selected semantic unit only
+     * after family and alias reconciliation, so it is not itself a public address
+     * or unit identity.
+     */
+    declarationId: string;
+    /**
+     * Physical declaration site at which the documentation becomes an evidence
+     * host.
+     *
+     * This remains separate from `declarationId` because one selected unit can
+     * have multiple source sites; grouping by this ID prevents a comment from
+     * being attached to unrelated overload or alias locations.
+     */
+    siteId: string;
+}