@wrtnlabs/evidence 0.0.0

package/lib/adapters/php/PhpDocumentation.d.ts

@@ -0,0 +1,18 @@
+import type { IEvidenceDocumentation } from "../../structures/IEvidenceDocumentation";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IPhpDocumentation } from "./IPhpDocumentation";
+/**
+ * Reads PHPDoc while preserving source mappings and masking code examples.
+ *
+ * The PHP adapter supplies attached carriers here before shared tag parsing, so
+ * diagnostics retain their original source positions after examples are hidden.
+ */
+export declare namespace PhpDocumentation {
+    /**
+     * Maps a classified carrier and removes ineligible example text without moving offsets.
+     *
+     * The returned documentation keeps the shared parser's coordinates while its
+     * masked text prevents annotations in PHPDoc examples from becoming evidence.
+     */
+    function read(source: IEvidenceSourceFile, documentation: IPhpDocumentation, hostId: string): IEvidenceDocumentation;
+}

package/lib/adapters/php/PhpDocumentation.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PhpDocumentation = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+/**
+ * Reads PHPDoc while preserving source mappings and masking code examples.
+ *
+ * The PHP adapter supplies attached carriers here before shared tag parsing, so
+ * diagnostics retain their original source positions after examples are hidden.
+ */
+var PhpDocumentation;
+(function (PhpDocumentation) {
+    /**
+     * Maps a classified carrier and removes ineligible example text without moving offsets.
+     *
+     * The returned documentation keeps the shared parser's coordinates while its
+     * masked text prevents annotations in PHPDoc examples from becoming evidence.
+     */
+    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),
+        };
+    }
+    PhpDocumentation.read = read;
+    /**
+     * Masks HTML examples and Markdown-indented code in parsed PHPDoc text.
+     *
+     * Fenced regions remain the shared tag parser's responsibility; this helper
+     * only removes examples whose characters must retain their mapped offsets.
+     */
+    function mask(input) {
+        const characters = input.split("");
+        const htmlCode = /<(pre|code)\b[^>]*>[\s\S]*?<\/\1\s*>/giu;
+        for (const match of input.matchAll(htmlCode))
+            hide(characters, match.index, match.index + match[0].length);
+        const lines = input.split("\n");
+        const indents = lines.filter((line) => line.trim() !== "").map(indentation);
+        const baseline = indents.reduce((minimum, indent) => Math.min(minimum, indent), Infinity);
+        let offset = 0;
+        for (const line of lines) {
+            if (indentation(line) >= baseline + 4)
+                hide(characters, offset, offset + line.length);
+            offset += line.length + 1;
+        }
+        return characters.join("");
+    }
+    /**
+     * Counts Markdown indentation after the documentation delimiter is removed.
+     *
+     * `mask` uses the result to establish the common indentation baseline before
+     * recognizing lines that belong to an indented code example.
+     */
+    function indentation(line) {
+        let spaces = 0;
+        for (const character of line) {
+            if (character === " ")
+                ++spaces;
+            else if (character === "\t")
+                spaces += 4 - (spaces % 4);
+            else
+                break;
+        }
+        return spaces;
+    }
+    /**
+     * Replaces example characters with spaces while retaining original line boundaries.
+     *
+     * Preserved length and newlines keep offsets from `EvidenceDocumentation` valid
+     * for diagnostics and source-range attachment after masking.
+     */
+    function hide(characters, start, end) {
+        for (let index = start; index < end; ++index)
+            if (characters[index] !== "\n" && characters[index] !== "\r")
+                characters[index] = " ";
+    }
+})(PhpDocumentation || (exports.PhpDocumentation = PhpDocumentation = {}));

package/lib/adapters/php/PhpFileScanner.d.ts

@@ -0,0 +1,79 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IPhpFileAnalysis } from "./IPhpFileAnalysis";
+/**
+ * Extracts explicit PHP declarations without executing source or runtime loaders.
+ *
+ * The scanner follows lexical syntax only and reports dynamic surface changes
+ * that would make a static Evidence inventory incomplete.
+ */
+export declare class PhpFileScanner {
+    private readonly session;
+    private readonly source;
+    /**
+     * Accumulates declarations and diagnostics in lexical source order.
+     *
+     * The output is serializable and does not retain parser-node ownership after scanning.
+     */
+    private readonly declarations;
+    /**
+     * Stores PHPDoc carriers, including unsupported attachment positions.
+     *
+     * Their offsets allow later annotation parsing to report the original source location.
+     */
+    private readonly documentation;
+    /**
+     * Records failures that prevent a complete declared PHP surface.
+     *
+     * The scan returns these diagnostics instead of silently omitting dynamic declarations.
+     */
+    private readonly diagnostics;
+    /**
+     * Maps original source content to UTF-16 Evidence coordinates.
+     *
+     * PHPDoc attachment and diagnostics retain positions from this unnormalized snapshot.
+     */
+    private readonly text;
+    /**
+     * Binds one parsed PHP source snapshot for lexical extraction.
+     *
+     * The scanner borrows the parser session only for this operation.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Extracts namespaces, nominal types, functions, and visible members.
+     *
+     * Dynamic declarations are diagnosed so the output cannot imply a complete static surface.
+     */
+    scan(): IPhpFileAnalysis;
+    /**
+     * Traverses namespace scopes without creating namespace Evidence units.
+     *
+     * Both semicolon and bracketed forms affect lexical ownership of contained declarations.
+     */
+    private scanScope;
+    /**
+     * Creates one fingerprinted declaration and attaches adjacent PHPDoc.
+     *
+     * Each declaration keeps its physical site while its identity represents lexical ownership.
+     */
+    private add;
+    /**
+     * Reports dynamic global declarations, including ones nested in function bodies.
+     *
+     * Runtime declaration creation can add public surface absent from lexical analysis.
+     */
+    private dynamicSurface;
+    /**
+     * Distinguishes declared-field writes from detectable runtime property creation.
+     *
+     * Dynamic public fields must be diagnosed because they escape the static inventory.
+     */
+    private dynamicProperties;
+    /**
+     * Records unsupported surface-changing syntax at its original source range.
+     *
+     * Duplicate diagnostics are suppressed while the analysis remains explicitly incomplete.
+     */
+    private problem;
+}

package/lib/adapters/php/PhpFileScanner.js

@@ -0,0 +1,346 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PhpFileScanner = void 0;
+const SourceText_1 = require("../../internal/SourceText");
+/**
+ * Extracts explicit PHP declarations without executing source or runtime loaders.
+ *
+ * The scanner follows lexical syntax only and reports dynamic surface changes
+ * that would make a static Evidence inventory incomplete.
+ */
+class PhpFileScanner {
+    session;
+    source;
+    /**
+     * Accumulates declarations and diagnostics in lexical source order.
+     *
+     * The output is serializable and does not retain parser-node ownership after scanning.
+     */
+    declarations = [];
+    /**
+     * Stores PHPDoc carriers, including unsupported attachment positions.
+     *
+     * Their offsets allow later annotation parsing to report the original source location.
+     */
+    documentation = new Map();
+    /**
+     * Records failures that prevent a complete declared PHP surface.
+     *
+     * The scan returns these diagnostics instead of silently omitting dynamic declarations.
+     */
+    diagnostics = [];
+    /**
+     * Maps original source content to UTF-16 Evidence coordinates.
+     *
+     * PHPDoc attachment and diagnostics retain positions from this unnormalized snapshot.
+     */
+    text;
+    /**
+     * Binds one parsed PHP source snapshot for lexical extraction.
+     *
+     * The scanner borrows the parser session only for this operation.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+        this.text = new SourceText_1.SourceText(source.content);
+    }
+    /**
+     * Extracts namespaces, nominal types, functions, and visible members.
+     *
+     * Dynamic declarations are diagnosed so the output cannot imply a complete static surface.
+     */
+    scan() {
+        for (const comment of this.session.root.descendantsOfType("comment")) {
+            if (!comment.text.startsWith("/**"))
+                continue;
+            this.documentation.set(comment.startIndex, {
+                id: `php:${this.source.id}:documentation:${comment.startIndex}`,
+                range: this.session.range(comment),
+                syntax: {
+                    opening: "/**",
+                    closing: "*/",
+                    linePrefix: "*",
+                    tagBoundaries: true,
+                    allowWithdrawal: true,
+                },
+                attachments: [],
+            });
+        }
+        if (this.session.root.descendantsOfType("php_tag").length === 0)
+            this.problem(this.session.root, "source-policy", "PHP source requires an opening <?php tag; tagless PHP-only files are not selected by this adapter.");
+        this.scanScope(this.session.root, [], undefined);
+        this.dynamicSurface(this.session.root);
+        this.dynamicProperties(this.session.root);
+        return {
+            source: this.source,
+            declarations: this.declarations,
+            documentation: [...this.documentation.values()],
+            diagnostics: this.diagnostics,
+            context: this.session.root
+                .descendantsOfType(["namespace_use_declaration", "declare_directive"])
+                .map((node) => node.text.replaceAll("\r\n", "\n")),
+            complete: this.diagnostics.length === 0,
+        };
+    }
+    /**
+     * Traverses namespace scopes without creating namespace Evidence units.
+     *
+     * Both semicolon and bracketed forms affect lexical ownership of contained declarations.
+     */
+    scanScope(node, initial, owner) {
+        let namespace = initial;
+        for (const child of node.namedChildren) {
+            if (child.type === "namespace_definition") {
+                const name = child.childForFieldName("name");
+                const segments = name === null
+                    ? []
+                    : name.descendantsOfType("name").map((part) => part.text);
+                const body = child.childForFieldName("body");
+                if (body === null)
+                    namespace = segments;
+                else
+                    this.scanScope(body, segments, undefined);
+            }
+            else if (TYPES.has(child.type)) {
+                const declaration = this.add(child, child, "type", namespace, owner);
+                const body = child.childForFieldName("body");
+                if (declaration !== undefined && body !== null)
+                    this.scanScope(body, namespace, declaration);
+            }
+            else if (child.type === "function_definition" ||
+                child.type === "method_declaration") {
+                this.add(child, child, "function", namespace, owner);
+                const methodName = child.childForFieldName("name");
+                if (owner !== undefined &&
+                    methodName !== null &&
+                    methodName.text.toLowerCase() === "__construct")
+                    for (const parameter of child.childForFieldName("parameters")
+                        ?.namedChildren ?? [])
+                        if (parameter.type === "property_promotion_parameter")
+                            this.add(parameter, parameter, "property", namespace, owner);
+            }
+            else if (child.type === "property_declaration" ||
+                child.type === "const_declaration") {
+                for (const element of child.namedChildren)
+                    if (element.type === "property_element" ||
+                        element.type === "const_element")
+                        this.add(element, child, "property", namespace, owner);
+            }
+            else if (child.type === "enum_case")
+                this.add(child, child, "property", namespace, owner);
+            else if (child.type === "use_declaration")
+                this.problem(child, "trait-composition", "Trait use and adaptation can add, rename, or hide members; trait composition is not implemented.");
+            else if (!IGNORED.has(child.type)) {
+                if (owner !== undefined)
+                    this.problem(child, "member-form", `PHP member '${child.type}' is not classified.`);
+                for (const declaration of child.descendantsOfType([
+                    ...TYPES,
+                    "function_definition",
+                ]))
+                    this.problem(declaration, "conditional-declaration", "A declaration inside executable control flow has runtime-dependent availability.");
+            }
+        }
+    }
+    /**
+     * Creates one fingerprinted declaration and attaches adjacent PHPDoc.
+     *
+     * Each declaration keeps its physical site while its identity represents lexical ownership.
+     */
+    add(item, carrier, symbol, namespace, owner) {
+        const nameNode = item.childForFieldName("name") ??
+            (item.type === "const_element" ? item.namedChildren[0] : null);
+        const name = nameNode === null || nameNode === undefined
+            ? undefined
+            : nameNode.text.replace(/^&\s*/u, "");
+        if (name === undefined || name.length === 0) {
+            this.problem(item, "declaration-name", "A PHP declaration has no static source name.");
+            return undefined;
+        }
+        const previous = carrier.previousNamedSibling;
+        const doc = previous?.type === "comment" &&
+            /^\s*$/u.test(this.source.content.slice(previous.endIndex, carrier.startIndex))
+            ? this.documentation.get(previous.startIndex)
+            : undefined;
+        const visibility = carrier.namedChildren.filter((child) => child.type === "visibility_modifier" && !child.text.includes("("));
+        const visible = (owner?.public ?? true) &&
+            !visibility.some((child) => child.text === "private" || child.text === "protected");
+        const identity = [...(owner?.identity ?? namespace), name];
+        const siteId = `php:${this.source.id}:site:${carrier.startIndex}`;
+        const declaration = {
+            id: `php:${this.source.id}:declaration:${item.startIndex}:${name}`,
+            name,
+            symbol,
+            form: item.type,
+            identity,
+            address: identity,
+            public: visible,
+            site: {
+                id: siteId,
+                file: this.source.physicalPath,
+                range: this.text.range(doc?.range?.start?.offset ?? carrier.startIndex, carrier.endIndex),
+                content: item.id === carrier.id
+                    ? [this.session.range(carrier)]
+                    : [
+                        this.text.range(carrier.startIndex, carrier.namedChildren.find((child) => child.type === item.type)?.startIndex ?? item.startIndex),
+                        this.session.range(item),
+                        ...carrier.namedChildren
+                            .filter((child) => child.type === "property_hook_list")
+                            .map((child) => this.session.range(child)),
+                    ],
+            },
+            ...(owner === undefined ? {} : { ownerDeclarationId: owner.id }),
+        };
+        this.declarations.push(declaration);
+        if (doc !== undefined)
+            doc.attachments.push({ declarationId: declaration.id, siteId });
+        return declaration;
+    }
+    /**
+     * Reports dynamic global declarations, including ones nested in function bodies.
+     *
+     * Runtime declaration creation can add public surface absent from lexical analysis.
+     */
+    dynamicSurface(root) {
+        const dynamicNames = new Set([
+            "eval",
+            "define",
+            "class_alias",
+            "spl_autoload_register",
+        ]);
+        for (const imported of root.descendantsOfType("namespace_use_declaration")) {
+            // Grouped imports have a namespace prefix and cannot name global builtins.
+            if (imported.childForFieldName("body") !== null)
+                continue;
+            for (const clause of imported.descendantsOfType("namespace_use_clause")) {
+                if ((clause.childForFieldName("type") ??
+                    imported.childForFieldName("type"))?.text !== "function")
+                    continue;
+                const importedName = clause.namedChildren[0];
+                const target = importedName === undefined
+                    ? undefined
+                    : importedName.text.replace(/^\\/u, "").toLowerCase();
+                const alias = clause.childForFieldName("alias");
+                if (target !== undefined && dynamicNames.has(target) && alias !== null)
+                    dynamicNames.add(alias.text.toLowerCase());
+            }
+        }
+        for (const node of root.descendantsOfType([
+            "include_expression",
+            "include_once_expression",
+            "require_expression",
+            "require_once_expression",
+        ]))
+            this.problem(node, "runtime-loader", "Runtime includes require execution and may change declarations; select explicit source files and remove runtime discovery from this population.");
+        for (const node of root.descendantsOfType("function_call_expression")) {
+            const target = node.childForFieldName("function");
+            if (target !== null &&
+                dynamicNames.has(target.text.replace(/^\\/u, "").toLowerCase()))
+                this.problem(node, "dynamic-declaration", `PHP ${target.text} can generate declarations or change their availability.`);
+        }
+        for (const node of root.descendantsOfType([
+            ...TYPES,
+            "function_definition",
+        ]))
+            if (node.parent !== null &&
+                !["program", "compound_statement"].includes(node.parent.type))
+                this.problem(node, "conditional-declaration", "Nested declarations can change the global public surface at runtime.");
+            else if (node.parent?.type === "compound_statement" &&
+                node.parent.parent?.type !== "namespace_definition")
+                this.problem(node, "conditional-declaration", "Declarations in executable blocks have runtime-dependent availability.");
+    }
+    /**
+     * Distinguishes declared-field writes from detectable runtime property creation.
+     *
+     * Dynamic public fields must be diagnosed because they escape the static inventory.
+     */
+    dynamicProperties(root) {
+        for (const member of root.descendantsOfType("member_access_expression")) {
+            if (member.childForFieldName("object")?.text !== "$this")
+                continue;
+            let written = member;
+            while (written.parent !== null &&
+                written.parent.type === "subscript_expression" &&
+                written.parent.namedChildren[0]?.id === written.id)
+                written = written.parent;
+            const mutation = written.parent;
+            if (mutation === null)
+                continue;
+            if (mutation.type === "update_expression") {
+                if (!mutation.namedChildren.some((child) => child.id === written.id))
+                    continue;
+            }
+            else if (![
+                "assignment_expression",
+                "augmented_assignment_expression",
+                "reference_assignment_expression",
+            ].includes(mutation.type) ||
+                mutation.childForFieldName("left")?.id !== written.id)
+                continue;
+            let container = member.parent;
+            while (container !== null &&
+                !TYPES.has(container.type) &&
+                container.type !== "anonymous_class")
+                container = container.parent;
+            if (container === null || container.type === "anonymous_class")
+                continue;
+            const ownerNode = container;
+            const owner = this.declarations.find((declaration) => declaration.form === ownerNode.type &&
+                declaration.site.range.end.offset === ownerNode.endIndex);
+            const name = member.childForFieldName("name");
+            if (owner !== undefined &&
+                name?.type === "name" &&
+                this.declarations.some((declaration) => declaration.ownerDeclarationId === owner.id &&
+                    declaration.symbol === "property" &&
+                    declaration.name === `$${name.text}`))
+                continue;
+            this.problem(member, "dynamic-property", "Writing a computed $this property or one not declared on this lexical type can add a public property at runtime; declare it explicitly or add inherited-property resolution.");
+        }
+    }
+    /**
+     * Records unsupported surface-changing syntax at its original source range.
+     *
+     * Duplicate diagnostics are suppressed while the analysis remains explicitly incomplete.
+     */
+    problem(node, code, message) {
+        if (this.diagnostics.some((diagnostic) => diagnostic.code === `php-${code}` &&
+            diagnostic.location?.range?.start?.offset === node.startIndex))
+            return;
+        this.diagnostics.push({
+            code: `php-${code}`,
+            severity: "error",
+            message,
+            repair: "Use explicit supported declarations or add PHP adapter support before evaluating coverage.",
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.PhpFileScanner = PhpFileScanner;
+/**
+ * Lists nominal PHP declarations whose members have an explicit lexical owner.
+ *
+ * The scanner uses these node kinds to establish class-like ownership while traversing bodies.
+ */
+const TYPES = new Set([
+    "class_declaration",
+    "interface_declaration",
+    "trait_declaration",
+    "enum_declaration",
+]);
+/**
+ * Lists syntax nodes that introduce no independently declared public symbol.
+ *
+ * Ignoring these nodes keeps traversal focused on syntax that can change the inventory.
+ */
+const IGNORED = new Set([
+    "php_tag",
+    "php_end_tag",
+    "text",
+    "text_interpolation",
+    "comment",
+    "namespace_use_declaration",
+    "empty_statement",
+]);

package/lib/adapters/postgresql/EvidencePostgresqlAdapter.d.ts

@@ -0,0 +1,26 @@
+import { SqlAdapter } from "../sql/SqlAdapter";
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+import type { IEvidenceSourceSnapshot } from "../../structures/IEvidenceSourceSnapshot";
+/**
+ * Extracts PostgreSQL table schemas with cross-file DDL and COMMENT ownership.
+ *
+ * PostgreSQL scanning and ownership resolution feed the shared SQL inventory
+ * materializer. A final fingerprint pass preserves review content semantics when
+ * annotation-only COMMENT statements add eligible documentation positions.
+ */
+export declare class EvidencePostgresqlAdapter extends SqlAdapter {
+    /**
+     * Selects PostgreSQL identity rules, scanning, and ownership resolution.
+     *
+     * These hooks interpret captured DDL through the pinned SQL grammar without
+     * executing statements against a database.
+     */
+    constructor();
+    /**
+     * Applies PostgreSQL COMMENT fingerprint policy after shared inventory extraction.
+     *
+     * Annotation-only COMMENT additions remain eligible hosts while the fingerprint
+     * layer avoids making review metadata invalidate the declaration it reviews.
+     */
+    analyze(snapshot: IEvidenceSourceSnapshot): Promise<IEvidenceInventory>;
+}

package/lib/adapters/postgresql/EvidencePostgresqlAdapter.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvidencePostgresqlAdapter = void 0;
+const SqlAdapter_1 = require("../sql/SqlAdapter");
+const PostgresqlFileScanner_1 = require("./PostgresqlFileScanner");
+const PostgresqlOwnership_1 = require("./PostgresqlOwnership");
+const PostgresqlFingerprint_1 = require("./PostgresqlFingerprint");
+/**
+ * Extracts PostgreSQL table schemas with cross-file DDL and COMMENT ownership.
+ *
+ * PostgreSQL scanning and ownership resolution feed the shared SQL inventory
+ * materializer. A final fingerprint pass preserves review content semantics when
+ * annotation-only COMMENT statements add eligible documentation positions.
+ */
+class EvidencePostgresqlAdapter extends SqlAdapter_1.SqlAdapter {
+    /**
+     * Selects PostgreSQL identity rules, scanning, and ownership resolution.
+     *
+     * These hooks interpret captured DDL through the pinned SQL grammar without
+     * executing statements against a database.
+     */
+    constructor() {
+        super({
+            type: "postgresql",
+            scan: (session, source) => new PostgresqlFileScanner_1.PostgresqlFileScanner(session, source).scan(),
+            resolve: PostgresqlOwnership_1.PostgresqlOwnership.resolve,
+        });
+    }
+    /**
+     * Applies PostgreSQL COMMENT fingerprint policy after shared inventory extraction.
+     *
+     * Annotation-only COMMENT additions remain eligible hosts while the fingerprint
+     * layer avoids making review metadata invalidate the declaration it reviews.
+     */
+    async analyze(snapshot) {
+        const inventory = await super.analyze(snapshot);
+        PostgresqlFingerprint_1.PostgresqlFingerprint.apply(inventory);
+        return inventory;
+    }
+}
+exports.EvidencePostgresqlAdapter = EvidencePostgresqlAdapter;

package/lib/adapters/postgresql/IPostgresqlFileAnalysis.d.ts

@@ -0,0 +1,16 @@
+import type { ISqlFileAnalysis } from "../sql/ISqlFileAnalysis";
+import type { IPostgresqlReference } from "./IPostgresqlReference";
+/**
+ * Extends SQL analysis with PostgreSQL declarations that need an existing owner.
+ *
+ * ALTER and COMMENT statements can contribute sites in a different file from
+ * the declaration whose semantic identity they extend.
+ */
+export interface IPostgresqlFileAnalysis extends ISqlFileAnalysis {
+    /**
+     * Lists declarations whose owner must be resolved after all files are scanned.
+     *
+     * Omission means this file has no ALTER or COMMENT sites needing cross-file ownership.
+     */
+    references?: IPostgresqlReference[];
+}

package/lib/adapters/postgresql/IPostgresqlFileAnalysis.js

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

package/lib/adapters/postgresql/IPostgresqlReference.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Requests ownership resolution for a PostgreSQL declaration site.
+ *
+ * The adapter uses this record after scanning all files to merge ALTER and
+ * COMMENT sites with the declaration identified by their SQL identity.
+ */
+export interface IPostgresqlReference {
+    /**
+     * Identifies the local declaration that receives the resolved owner.
+     *
+     * This ID remains stable while resolution replaces its provisional identity.
+     */
+    declarationId: string;
+    /**
+     * Names the schema-qualified table or column to resolve.
+     *
+     * Table identities have two segments, while column identities have three.
+     */
+    identity: string[];
+    /**
+     * Distinguishes a COMMENT site from an ALTER TABLE extension.
+     *
+     * Comment sites retain a separate physical address after ownership resolution.
+     */
+    comment: boolean;
+}

package/lib/adapters/postgresql/IPostgresqlReference.js

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