@wrtnlabs/evidence 0.0.0 → 0.1.0

package/lib/adapters/java/EvidenceJavaDocumentation.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceJavaDocumentation = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+const EvidenceDocumentationExamples_1 = require("../../parsers/EvidenceDocumentationExamples");
+/**
+ * Reads Javadoc while masking inline and preformatted code examples.
+ *
+ * The adapter preserves original source coordinates while removing example text
+ * from tag parsing, so code-looking annotations cannot create evidence
+ * records.
+ */
+var EvidenceJavaDocumentation;
+(function (EvidenceJavaDocumentation) {
+    /**
+     * Maps one Java documentation carrier and removes its code examples.
+     *
+     * Javadoc applies native inline-tag precedence before HTML pairing. Other
+     * Java comment forms retain their shared mapping because they do not own this
+     * syntax.
+     */
+    function read(source, documentation, hostId) {
+        const parsed = EvidenceDocumentation_1.EvidenceDocumentation.read(source.content, hostId, documentation.range, documentation.syntax);
+        if (documentation.syntax.opening !== "/**")
+            return parsed;
+        return {
+            ...parsed,
+            text: mask(parsed.text),
+        };
+    }
+    EvidenceJavaDocumentation.read = read;
+    /**
+     * Masks native Javadoc and HTML examples without changing mapped coordinates.
+     *
+     * Inline tags are hidden before HTML pairing so their literal markup cannot
+     * consume ordinary documentation between two separate examples.
+     */
+    function mask(input) {
+        const characters = input.split("");
+        const markdown = EvidenceDocumentationExamples_1.EvidenceDocumentationExamples.markdownCode(input);
+        const openings = ["{@code", "{@literal", "{@snippet"];
+        for (const opening of openings)
+            for (let index = input.indexOf(opening); index >= 0;) {
+                if (markdown[index] === true) {
+                    index = input.indexOf(opening, index + opening.length);
+                    continue;
+                }
+                const end = closingBrace(input, index);
+                hide(characters, index, end);
+                index = input.indexOf(opening, Math.max(end, index + opening.length));
+            }
+        EvidenceDocumentationExamples_1.EvidenceDocumentationExamples.maskHtml(characters, input, ["pre", "code"]);
+        return characters.join("");
+    }
+    /**
+     * Finds the balanced end of one native Javadoc inline example.
+     *
+     * Nested braces belong to the inline body. An unmatched opening owns the rest
+     * of the documentation carrier so its contents cannot become annotations.
+     */
+    function closingBrace(input, start) {
+        let depth = 0;
+        for (let index = start; index < input.length; ++index) {
+            const character = input[index];
+            if (character === "{")
+                ++depth;
+            else if (character === "}" && --depth === 0)
+                return index + 1;
+        }
+        return input.length;
+    }
+    /**
+     * Replaces a Javadoc example span while preserving mapped source positions.
+     *
+     * Newline bytes remain intact so annotations after the example retain their
+     * original diagnostic and host ranges.
+     */
+    function hide(characters, start, end) {
+        for (let index = start; index < end; ++index)
+            if (characters[index] !== "\n" && characters[index] !== "\r")
+                characters[index] = " ";
+    }
+})(EvidenceJavaDocumentation || (exports.EvidenceJavaDocumentation = EvidenceJavaDocumentation = {}));

package/lib/adapters/java/EvidenceJavaFileScanner.d.ts

@@ -0,0 +1,53 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IEvidenceJavaFileAnalysis } from "./IEvidenceJavaFileAnalysis";
+/**
+ * Extracts Java packages, declarations, and Javadoc before family
+ * materialization.
+ *
+ * Ownership and visibility are recorded from selected source only;
+ * `EvidenceJavaAdapter` later reconciles compatible declaration families into
+ * graph units.
+ */
+export declare class EvidenceJavaFileScanner {
+    private readonly session;
+    private readonly source;
+    private readonly declarations;
+    private readonly documentation;
+    private readonly carrierDocumentation;
+    private readonly diagnostics;
+    private readonly reported;
+    private readonly text;
+    private complete;
+    /**
+     * Creates a scanner for one Java parse session and source snapshot.
+     *
+     * Javadoc carriers are collected before declaration walking so their physical
+     * attachment cannot be confused with same-named declarations elsewhere.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Produces node-free package declarations, documentation, and diagnostics.
+     *
+     * The result records unsupported relevant forms as incomplete rather than
+     * allowing the adapter to publish a falsely complete smaller inventory.
+     */
+    scan(): IEvidenceJavaFileAnalysis;
+    private scanType;
+    private scanTypeBody;
+    private scanRecordComponents;
+    private scanField;
+    private scanMethod;
+    private scanEnumConstant;
+    private scanAnnotationElement;
+    private typePublic;
+    private memberPublic;
+    private addDeclaration;
+    private collectDocumentation;
+    private attach;
+    private ensureDocumentation;
+    private annotation;
+    private nodeKey;
+    private siteId;
+    private problem;
+}

package/lib/adapters/java/EvidenceJavaFileScanner.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceJavaFileScanner = void 0;
+const EvidenceJavaSyntax_1 = require("./EvidenceJavaSyntax");
+const EvidenceSourceText_1 = require("../../internal/EvidenceSourceText");
+/**
+ * Extracts Java packages, declarations, and Javadoc before family
+ * materialization.
+ *
+ * Ownership and visibility are recorded from selected source only;
+ * `EvidenceJavaAdapter` later reconciles compatible declaration families into
+ * graph units.
+ */
+class EvidenceJavaFileScanner {
+    session;
+    source;
+    declarations = [];
+    documentation = new Map();
+    carrierDocumentation = new Map();
+    diagnostics = [];
+    reported = new Set();
+    text;
+    complete = true;
+    /**
+     * Creates a scanner for one Java parse session and source snapshot.
+     *
+     * Javadoc carriers are collected before declaration walking so their physical
+     * attachment cannot be confused with same-named declarations elsewhere.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+        this.text = new EvidenceSourceText_1.EvidenceSourceText(source.content);
+        this.collectDocumentation();
+    }
+    /**
+     * Produces node-free package declarations, documentation, and diagnostics.
+     *
+     * The result records unsupported relevant forms as incomplete rather than
+     * allowing the adapter to publish a falsely complete smaller inventory.
+     */
+    scan() {
+        const packageDeclaration = this.session.root.namedChildren.find((child) => child.type === "package_declaration");
+        const packagePath = EvidenceJavaSyntax_1.EvidenceJavaSyntax.packagePath(packageDeclaration);
+        for (const item of this.session.root.namedChildren)
+            switch (item.type) {
+                case "package_declaration":
+                case "import_declaration":
+                case "line_comment":
+                case "block_comment":
+                case "module_declaration":
+                    break;
+                case "class_declaration":
+                    this.scanType(item, packagePath, undefined, "class", "class");
+                    break;
+                case "interface_declaration":
+                    this.scanType(item, packagePath, undefined, "interface", "interface");
+                    break;
+                case "enum_declaration":
+                    this.scanType(item, packagePath, undefined, "enum", "enum");
+                    break;
+                case "annotation_type_declaration":
+                    this.scanType(item, packagePath, undefined, "annotation", "annotation");
+                    break;
+                case "record_declaration":
+                    this.scanType(item, packagePath, undefined, "record", "record");
+                    break;
+                default:
+                    if (EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(item, "public"))
+                        this.problem("java-public-form", `Public Java source form '${item.type}' is not classified by this adapter.`, "Add an explicit declaration-form rule before evaluating this public surface.", item);
+            }
+        return {
+            source: this.source,
+            declarations: this.declarations,
+            documentation: Array.from(this.documentation.values()),
+            diagnostics: this.diagnostics,
+            complete: this.complete,
+        };
+    }
+    scanType(item, packagePath, owner, kind, form) {
+        const name = EvidenceJavaSyntax_1.EvidenceJavaSyntax.name(item.childForFieldName("name"));
+        if (name === undefined) {
+            this.problem("java-type-name", `A Java ${form} declaration has no statically readable name.`, "Use one ordinary named declaration.", item);
+            return;
+        }
+        const identity = [
+            ...(owner === undefined ? packagePath : owner.identity),
+            name,
+        ];
+        const address = [...(owner?.address ?? []), name];
+        const visible = this.typePublic(item, owner);
+        const declaration = this.addDeclaration(item, item, EvidenceJavaSyntax_1.EvidenceJavaSyntax.javadoc(item), [this.session.range(item)], name, "type", form, identity, address, visible, owner?.declarationId);
+        const context = {
+            declarationId: declaration.id,
+            identity,
+            address,
+            kind,
+            public: visible,
+        };
+        if (kind === "record")
+            this.scanRecordComponents(item, context);
+        const body = item.childForFieldName("body");
+        if (body !== null)
+            this.scanTypeBody(body, context);
+    }
+    scanTypeBody(body, owner) {
+        for (const member of body.namedChildren)
+            switch (member.type) {
+                case "line_comment":
+                case "block_comment":
+                case "constructor_declaration":
+                case "compact_constructor_declaration":
+                case "static_initializer":
+                    break;
+                case "enum_body_declarations":
+                    this.scanTypeBody(member, owner);
+                    break;
+                case "class_declaration":
+                    this.scanType(member, [], owner, "class", "class");
+                    break;
+                case "interface_declaration":
+                    this.scanType(member, [], owner, "interface", "interface");
+                    break;
+                case "enum_declaration":
+                    this.scanType(member, [], owner, "enum", "enum");
+                    break;
+                case "annotation_type_declaration":
+                    this.scanType(member, [], owner, "annotation", "annotation");
+                    break;
+                case "record_declaration":
+                    this.scanType(member, [], owner, "record", "record");
+                    break;
+                case "field_declaration":
+                    this.scanField(member, owner, "field");
+                    break;
+                case "constant_declaration":
+                    this.scanField(member, owner, "interface-constant");
+                    break;
+                case "method_declaration":
+                    this.scanMethod(member, owner);
+                    break;
+                case "enum_constant":
+                    this.scanEnumConstant(member, owner);
+                    break;
+                case "annotation_type_element_declaration":
+                    this.scanAnnotationElement(member, owner);
+                    break;
+                default:
+                    if (EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(member, "public"))
+                        this.problem("java-public-form", `Public Java member form '${member.type}' is not classified by this adapter.`, "Add an explicit member rule before evaluating this public type.", member);
+            }
+    }
+    scanRecordComponents(item, owner) {
+        const parameters = item.childForFieldName("parameters");
+        for (const parameter of parameters === null
+            ? []
+            : parameters.namedChildren) {
+            if (parameter.type !== "formal_parameter" &&
+                parameter.type !== "spread_parameter")
+                continue;
+            const name = EvidenceJavaSyntax_1.EvidenceJavaSyntax.parameterName(parameter);
+            if (name === undefined)
+                continue;
+            this.addDeclaration(parameter, parameter, EvidenceJavaSyntax_1.EvidenceJavaSyntax.javadoc(parameter), [this.session.range(parameter)], name, "property", "record-component", [...owner.identity, name], [...owner.address, name], owner.public, owner.declarationId);
+        }
+    }
+    scanField(item, owner, form) {
+        const declarators = item.namedChildren.filter((child) => child.type === "variable_declarator");
+        const first = declarators[0];
+        if (first === undefined)
+            return;
+        const header = this.text.range(item.startIndex, first.startIndex);
+        const documentation = EvidenceJavaSyntax_1.EvidenceJavaSyntax.javadoc(item);
+        const visible = this.memberPublic(item, owner, form !== "field");
+        for (const declarator of declarators) {
+            const name = EvidenceJavaSyntax_1.EvidenceJavaSyntax.name(declarator.childForFieldName("name"));
+            if (name === undefined)
+                continue;
+            this.addDeclaration(declarator, item, documentation, [header, this.session.range(declarator)], name, "property", form, [...owner.identity, name], [...owner.address, name], visible, owner.declarationId);
+        }
+    }
+    scanMethod(item, owner) {
+        const name = EvidenceJavaSyntax_1.EvidenceJavaSyntax.name(item.childForFieldName("name"));
+        if (name === undefined)
+            return;
+        this.addDeclaration(item, item, EvidenceJavaSyntax_1.EvidenceJavaSyntax.javadoc(item), [this.session.range(item)], name, "function", "method", [...owner.identity, name], [...owner.address, name], this.memberPublic(item, owner, owner.kind === "interface"), owner.declarationId);
+    }
+    scanEnumConstant(item, owner) {
+        const name = EvidenceJavaSyntax_1.EvidenceJavaSyntax.name(item.childForFieldName("name"));
+        if (name === undefined)
+            return;
+        this.addDeclaration(item, item, EvidenceJavaSyntax_1.EvidenceJavaSyntax.javadoc(item), [this.session.range(item)], name, "property", "enum-constant", [...owner.identity, name], [...owner.address, name], owner.public, owner.declarationId);
+    }
+    scanAnnotationElement(item, owner) {
+        const name = EvidenceJavaSyntax_1.EvidenceJavaSyntax.name(item.childForFieldName("name"));
+        if (name === undefined)
+            return;
+        this.addDeclaration(item, item, EvidenceJavaSyntax_1.EvidenceJavaSyntax.javadoc(item), [this.session.range(item)], name, "property", "annotation-element", [...owner.identity, name], [...owner.address, name], owner.public, owner.declarationId);
+    }
+    typePublic(item, owner) {
+        if (owner === undefined)
+            return EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(item, "public");
+        if (!owner.public)
+            return false;
+        if (EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(item, "private"))
+            return false;
+        if (EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(item, "protected"))
+            return false;
+        return owner.kind === "interface" || owner.kind === "annotation"
+            ? true
+            : EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(item, "public");
+    }
+    memberPublic(item, owner, implicit) {
+        if (!owner.public)
+            return false;
+        if (EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(item, "private"))
+            return false;
+        if (EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(item, "protected"))
+            return false;
+        return implicit || EvidenceJavaSyntax_1.EvidenceJavaSyntax.hasModifier(item, "public");
+    }
+    addDeclaration(item, siteNode, documentationNode, content, name, symbol, form, identity, address, visible, ownerDeclarationId) {
+        const site = {
+            id: this.siteId(siteNode),
+            file: this.source.physicalPath,
+            range: this.text.range(documentationNode?.startIndex ?? siteNode.startIndex, siteNode.endIndex),
+            content,
+        };
+        const declaration = {
+            id: `java:${this.source.id}:declaration:${form}:${item.startIndex}:${name}`,
+            name,
+            symbol,
+            form,
+            identity,
+            address,
+            site,
+            public: visible,
+            ...(ownerDeclarationId === undefined ? {} : { ownerDeclarationId }),
+        };
+        this.declarations.push(declaration);
+        if (documentationNode !== null) {
+            const documentation = this.carrierDocumentation.get(this.nodeKey(documentationNode));
+            if (documentation !== undefined)
+                this.attach(documentation, declaration.id, site.id);
+        }
+        return declaration;
+    }
+    collectDocumentation() {
+        const comments = [
+            ...this.session.root.descendantsOfType("line_comment"),
+            ...this.session.root.descendantsOfType("block_comment"),
+        ];
+        for (const comment of comments) {
+            const syntax = EvidenceJavaSyntax_1.EvidenceJavaSyntax.comment(comment);
+            const range = this.session.range(comment);
+            const javadoc = comment.type === "block_comment" && comment.text.startsWith("/**");
+            const raw = this.source.content.slice(range.start.offset + syntax.opening.length, range.end.offset - syntax.closing.length);
+            if (!javadoc && !this.annotation(raw))
+                continue;
+            const documentation = this.ensureDocumentation(range, syntax);
+            this.carrierDocumentation.set(this.nodeKey(comment), documentation);
+        }
+        const literals = [...this.session.root.descendantsOfType("string_literal")];
+        for (const literal of literals) {
+            const syntax = EvidenceJavaSyntax_1.EvidenceJavaSyntax.string(literal);
+            if (syntax === undefined)
+                continue;
+            const raw = literal.text.slice(syntax.opening.length, literal.text.length - syntax.closing.length);
+            if (this.annotation(raw))
+                this.ensureDocumentation(this.session.range(literal), syntax);
+        }
+    }
+    attach(documentation, declarationId, siteId) {
+        if (!documentation.attachments.some((attachment) => attachment.declarationId === declarationId &&
+            attachment.siteId === siteId))
+            documentation.attachments.push({ declarationId, siteId });
+    }
+    ensureDocumentation(range, syntax) {
+        const key = `${range.start.offset}:${range.end.offset}`;
+        let documentation = this.documentation.get(key);
+        if (documentation === undefined) {
+            documentation = {
+                id: `java:${this.source.id}:documentation:${key}`,
+                range,
+                syntax,
+                attachments: [],
+            };
+            this.documentation.set(key, documentation);
+        }
+        return documentation;
+    }
+    annotation(raw) {
+        return /(?:^|[\r\n])[ \t]*@(evidenceExcludeReview|evidenceReview|evidenceExclude|evidence|link|internal|hidden|ignore)\b/u.test(raw);
+    }
+    nodeKey(node) {
+        return `${node.startIndex}:${node.endIndex}`;
+    }
+    siteId(node) {
+        return `java:${this.source.id}:site:${this.nodeKey(node)}`;
+    }
+    problem(code, message, repair, node) {
+        const key = `${code}:${node.startIndex}:${node.endIndex}`;
+        if (this.reported.has(key))
+            return;
+        this.reported.add(key);
+        this.complete = false;
+        this.diagnostics.push({
+            code,
+            severity: "error",
+            message,
+            repair,
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.EvidenceJavaFileScanner = EvidenceJavaFileScanner;

package/lib/adapters/java/EvidenceJavaSyntax.d.ts

@@ -0,0 +1,19 @@
+import type { Node as EvidenceNode } from "web-tree-sitter";
+import type { IEvidenceCommentSyntax } from "../../structures/IEvidenceCommentSyntax";
+/**
+ * Grammar-specific Java names, packages, modifiers, literals, and Javadoc.
+ *
+ * Java extraction uses these helpers to interpret parser nodes without
+ * resolving compiler symbols, preserving source-spelled ownership and
+ * documentation boundaries.
+ */
+export declare namespace EvidenceJavaSyntax {
+    function name(node: EvidenceNode | null): string | undefined;
+    function path(node: EvidenceNode | null): string[] | undefined;
+    function packagePath(node: EvidenceNode | undefined): string[];
+    function parameterName(node: EvidenceNode): string | undefined;
+    function hasModifier(node: EvidenceNode, modifier: string): boolean;
+    function javadoc(node: EvidenceNode): EvidenceNode | null;
+    function comment(node: EvidenceNode): IEvidenceCommentSyntax;
+    function string(node: EvidenceNode): IEvidenceCommentSyntax | undefined;
+}

package/lib/adapters/java/EvidenceJavaSyntax.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidenceJavaSyntax = void 0;
+/**
+ * Grammar-specific Java names, packages, modifiers, literals, and Javadoc.
+ *
+ * Java extraction uses these helpers to interpret parser nodes without
+ * resolving compiler symbols, preserving source-spelled ownership and
+ * documentation boundaries.
+ */
+var EvidenceJavaSyntax;
+(function (EvidenceJavaSyntax) {
+    function name(node) {
+        return node !== null && node.type === "identifier" ? node.text : undefined;
+    }
+    EvidenceJavaSyntax.name = name;
+    function path(node) {
+        if (node === null)
+            return undefined;
+        const direct = name(node);
+        if (direct !== undefined)
+            return [direct];
+        if (node.type !== "scoped_identifier")
+            return undefined;
+        const scope = path(node.childForFieldName("scope"));
+        const suffix = name(node.childForFieldName("name"));
+        return scope === undefined || suffix === undefined
+            ? undefined
+            : [...scope, suffix];
+    }
+    EvidenceJavaSyntax.path = path;
+    function packagePath(node) {
+        if (node === undefined)
+            return [];
+        for (const child of node.namedChildren) {
+            const candidate = path(child);
+            if (candidate !== undefined)
+                return candidate;
+        }
+        return [];
+    }
+    EvidenceJavaSyntax.packagePath = packagePath;
+    function parameterName(node) {
+        if (node.type === "formal_parameter")
+            return name(node.childForFieldName("name"));
+        if (node.type !== "spread_parameter")
+            return undefined;
+        const declarator = node.namedChildren.find((child) => child.type === "variable_declarator");
+        return declarator === undefined
+            ? undefined
+            : name(declarator.childForFieldName("name"));
+    }
+    EvidenceJavaSyntax.parameterName = parameterName;
+    function hasModifier(node, modifier) {
+        const modifiers = node.namedChildren.find((child) => child.type === "modifiers");
+        return modifiers === undefined
+            ? false
+            : modifiers.children.some((child) => child.type === modifier);
+    }
+    EvidenceJavaSyntax.hasModifier = hasModifier;
+    function javadoc(node) {
+        const previous = node.previousNamedSibling;
+        return previous !== null &&
+            previous.type === "block_comment" &&
+            previous.text.startsWith("/**")
+            ? previous
+            : null;
+    }
+    EvidenceJavaSyntax.javadoc = javadoc;
+    function comment(node) {
+        if (node.type === "line_comment")
+            return {
+                opening: "//",
+                closing: "",
+                linePrefix: "//",
+                tagBoundaries: true,
+                allowWithdrawal: false,
+            };
+        const javadoc = node.text.startsWith("/**");
+        return {
+            opening: javadoc ? "/**" : "/*",
+            closing: "*/",
+            tagBoundaries: true,
+            allowWithdrawal: javadoc,
+            ...(javadoc ? { linePrefix: "*" } : {}),
+        };
+    }
+    EvidenceJavaSyntax.comment = comment;
+    function string(node) {
+        if (node.type !== "string_literal")
+            return undefined;
+        const delimiter = node.text.startsWith('"""') ? '"""' : '"';
+        return {
+            opening: delimiter,
+            closing: delimiter,
+            tagBoundaries: true,
+            allowWithdrawal: false,
+        };
+    }
+    EvidenceJavaSyntax.string = string;
+})(EvidenceJavaSyntax || (exports.EvidenceJavaSyntax = EvidenceJavaSyntax = {}));

package/lib/adapters/java/EvidenceJavaTypeKind.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Java type context that determines implicit member visibility.
+ *
+ * Member extraction carries this context because interfaces, annotations, and
+ * other nominal forms supply different defaults when modifiers are omitted.
+ */
+export type EvidenceJavaTypeKind = "class" | "interface" | "enum" | "annotation" | "record";

package/lib/adapters/java/IEvidenceJavaDeclaration.d.ts

@@ -0,0 +1,67 @@
+import type { IEvidenceUnitSite } from "../../structures/IEvidenceUnitSite";
+import type { EvidenceProgrammingSymbol } from "../../typings/EvidenceProgrammingSymbol";
+import type { EvidenceJavaDeclarationForm } from "./EvidenceJavaDeclarationForm";
+/**
+ * Records one Java declaration before its public unit and overload family are
+ * materialized.
+ *
+ * EvidenceJavaFileScanner creates these physical records, and
+ * EvidenceJavaAdapter reconciles compatible records into the
+ * language-independent Evidence inventory.
+ */
+export interface IEvidenceJavaDeclaration {
+    /**
+     * Scanner-local declaration key for Javadoc attachments and reconciliation.
+     *
+     * It is replaced by a stable semantic unit ID during materialization.
+     */
+    id: string;
+    /**
+     * Unqualified source name used for unit display and member addressing.
+     *
+     * Package and enclosing type segments live in `identity`.
+     */
+    name: string;
+    /**
+     * Shared graph selector category for this Java declaration.
+     *
+     * It keeps Java syntax within the common programming-unit model.
+     */
+    symbol: EvidenceProgrammingSymbol;
+    /**
+     * Java declaration form that controls overload and type-family compatibility.
+     *
+     * Incompatible forms must remain visible as extraction failures.
+     */
+    form: EvidenceJavaDeclarationForm;
+    /**
+     * Canonical package-qualified semantic path for family reconciliation.
+     *
+     * This identity remains independent of source file public addresses.
+     */
+    identity: string[];
+    /**
+     * Public accessor path emitted when the declaration is reachable.
+     *
+     * Segment boundaries preserve real structural containment.
+     */
+    address: string[];
+    /**
+     * Physical declaration site used for hosts and content fingerprints.
+     *
+     * Compatible records can contribute multiple sites to one unit.
+     */
+    site: IEvidenceUnitSite;
+    /**
+     * Whether Java visibility and ancestor context permit publication.
+     *
+     * The adapter does not expose private declarations merely because they parse.
+     */
+    public: boolean;
+    /**
+     * Scanner-local enclosing declaration for a member or nested type.
+     *
+     * Omission denotes a package-level declaration.
+     */
+    ownerDeclarationId?: string;
+}