@wrtnlabs/evidence 0.0.0

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

@@ -0,0 +1,103 @@
+import type { EvidenceParseSession } from "../../parsers/EvidenceParseSession";
+import type { IEvidenceSourceFile } from "../../structures/IEvidenceSourceFile";
+import type { IPostgresqlFileAnalysis } from "./IPostgresqlFileAnalysis";
+/**
+ * Extracts the supported PostgreSQL DDL surface from authoritative grammar nodes.
+ *
+ * It records unsupported schema changes as incomplete instead of producing a
+ * smaller declaration inventory that could make coverage pass.
+ */
+export declare class PostgresqlFileScanner {
+    private readonly session;
+    private readonly source;
+    /**
+     * Accumulates the serializable analysis for this source scan.
+     *
+     * References remain provisional until cross-file ownership resolution completes.
+     */
+    private readonly output;
+    /**
+     * Maps parser-node offsets to declarations created from that node.
+     *
+     * Comment attachment uses this transient map before the scanner returns its serializable output.
+     */
+    private readonly nodes;
+    /**
+     * Binds one borrowed PostgreSQL syntax tree and its UTF-16 source snapshot.
+     *
+     * Parser nodes are retained only for this scan and never escape in the analysis result.
+     */
+    constructor(session: EvidenceParseSession, source: IEvidenceSourceFile);
+    /**
+     * Visits supported statements and attaches adjacent SQL comments.
+     *
+     * Traversal stays at statement syntax so executable bodies and string examples cannot create units.
+     */
+    scan(): IPostgresqlFileAnalysis;
+    /**
+     * Dispatches supported DDL statements and rejects all other statement forms.
+     *
+     * The declared boundary is intentionally narrow because migrations require stateful evaluation.
+     */
+    private statement;
+    /**
+     * Publishes tables only when columns and a schema-qualified owner are explicit.
+     *
+     * Inferred schemas and search-path-dependent identities cannot form stable Evidence units.
+     */
+    private table;
+    /**
+     * Publishes a column while keeping foreign-key relations separately selectable.
+     *
+     * A column belongs to its table, whereas a relation has its own semantic identity.
+     */
+    private column;
+    /**
+     * Processes constraints as table semantics unless they declare a foreign-key relation.
+     *
+     * Unsupported dialect-specific keys and indexes are diagnosed before inventory materialization.
+     */
+    private constraint;
+    /**
+     * Publishes a foreign key using stable identities for composite endpoints.
+     *
+     * Anonymous constraints must retain endpoint meaning without depending on statement order.
+     */
+    private relation;
+    /**
+     * Extracts supported additive ALTER TABLE declarations.
+     *
+     * Destructive or stateful migrations require database history and are rejected by this snapshot scanner.
+     */
+    private alter;
+    /**
+     * Attaches supported COMMENT ON TABLE or COLUMN strings to their target identity.
+     *
+     * The resulting declaration site resolves against an existing owner after all files are scanned.
+     */
+    private commentStatement;
+    /**
+     * Creates one physical declaration with a file-independent semantic identity.
+     *
+     * Cross-file ALTER and COMMENT sites can therefore merge with the same selected declaration.
+     */
+    private declaration;
+    /**
+     * Establishes ownership for adjacent SQL comments before shared annotation parsing.
+     *
+     * Only standalone runs immediately before a declaration become documentation carriers.
+     */
+    private comments;
+    /**
+     * Identifies parser extras without interpreting their contents as DDL.
+     *
+     * Comments and marginalia are handled only by the documentation attachment pass.
+     */
+    private commentNode;
+    /**
+     * Marks unsupported surface-changing syntax as explicitly incomplete.
+     *
+     * The diagnostic preserves the failure rather than allowing coverage to use fewer obligations.
+     */
+    private problem;
+}

package/lib/adapters/postgresql/PostgresqlFileScanner.js

@@ -0,0 +1,431 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresqlFileScanner = void 0;
+const EvidenceDocumentation_1 = require("../../parsers/EvidenceDocumentation");
+const PostgresqlIdentity_1 = require("./PostgresqlIdentity");
+/**
+ * Extracts the supported PostgreSQL DDL surface from authoritative grammar nodes.
+ *
+ * It records unsupported schema changes as incomplete instead of producing a
+ * smaller declaration inventory that could make coverage pass.
+ */
+class PostgresqlFileScanner {
+    session;
+    source;
+    /**
+     * Accumulates the serializable analysis for this source scan.
+     *
+     * References remain provisional until cross-file ownership resolution completes.
+     */
+    output;
+    /**
+     * Maps parser-node offsets to declarations created from that node.
+     *
+     * Comment attachment uses this transient map before the scanner returns its serializable output.
+     */
+    nodes = new Map();
+    /**
+     * Binds one borrowed PostgreSQL syntax tree and its UTF-16 source snapshot.
+     *
+     * Parser nodes are retained only for this scan and never escape in the analysis result.
+     */
+    constructor(session, source) {
+        this.session = session;
+        this.source = source;
+        this.output = {
+            source,
+            declarations: [],
+            documentation: [],
+            diagnostics: [],
+            complete: true,
+            references: [],
+        };
+    }
+    /**
+     * Visits supported statements and attaches adjacent SQL comments.
+     *
+     * Traversal stays at statement syntax so executable bodies and string examples cannot create units.
+     */
+    scan() {
+        for (const node of this.session.root.namedChildren)
+            this.statement(node);
+        this.comments();
+        return this.output;
+    }
+    /**
+     * Dispatches supported DDL statements and rejects all other statement forms.
+     *
+     * The declared boundary is intentionally narrow because migrations require stateful evaluation.
+     */
+    statement(node) {
+        if (this.commentNode(node))
+            return;
+        if (node.type === "statement") {
+            for (const child of node.namedChildren)
+                this.statement(child);
+            return;
+        }
+        if (node.type === "create_table")
+            this.table(node);
+        else if (node.type === "create_schema") {
+            if (node.namedChildren.some((child) => child.type === "keyword_if" ||
+                (child.type === "identifier" &&
+                    PostgresqlIdentity_1.PostgresqlIdentity.identifier(child.text) === undefined)))
+                this.problem(node, "CREATE SCHEMA requires unconditional PostgreSQL identifiers without server-side name truncation.");
+        }
+        else if (node.type === "alter_table")
+            this.alter(node);
+        else if (node.type === "comment_statement")
+            this.commentStatement(node);
+        else
+            this.problem(node, `Statement '${node.type}' is outside the PostgreSQL declared DDL surface.`);
+    }
+    /**
+     * Publishes tables only when columns and a schema-qualified owner are explicit.
+     *
+     * Inferred schemas and search-path-dependent identities cannot form stable Evidence units.
+     */
+    table(node) {
+        const reference = node.namedChildren.find((child) => child.type === "object_reference");
+        const identity = reference === undefined ? undefined : PostgresqlIdentity_1.PostgresqlIdentity.path(reference);
+        const columns = node.namedChildren.find((child) => child.type === "column_definitions");
+        if (identity?.length !== 2 || columns === undefined) {
+            this.problem(node, "CREATE TABLE requires an explicit schema-qualified name and an explicit column list; search_path, LIKE, OF, and AS-derived schemas are unsupported.");
+            return;
+        }
+        const permitted = new Set([
+            "keyword_create",
+            "keyword_unlogged",
+            "keyword_table",
+            "object_reference",
+            "column_definitions",
+            "comment",
+            "marginalia",
+        ]);
+        if (node.namedChildren.some((child) => !permitted.has(child.type))) {
+            this.problem(node, "Conditional creation, inheritance, partitioning, and table options require PostgreSQL schema derivation that is not implemented.");
+            return;
+        }
+        const table = this.declaration(node, "model", identity);
+        for (const child of columns.namedChildren)
+            if (child.type === "column_definition")
+                this.column(child, table);
+            else if (child.type === "constraints") {
+                for (const constraint of child.namedChildren)
+                    if (!this.commentNode(constraint))
+                        this.constraint(constraint, table);
+            }
+            else if (!this.commentNode(child))
+                this.problem(child, "Unsupported table member can change the declared PostgreSQL schema.");
+    }
+    /**
+     * Publishes a column while keeping foreign-key relations separately selectable.
+     *
+     * A column belongs to its table, whereas a relation has its own semantic identity.
+     */
+    column(node, table) {
+        const nameNode = node.childForFieldName("name");
+        if (nameNode !== null && /^like$/iu.test(nameNode.text)) {
+            this.problem(node, "LIKE-derived columns depend on another table schema and are unsupported.");
+            return;
+        }
+        const name = nameNode === null
+            ? undefined
+            : PostgresqlIdentity_1.PostgresqlIdentity.identifier(nameNode.text);
+        if (name === undefined) {
+            this.problem(node, "The column identifier cannot be represented as a PostgreSQL name.");
+            return;
+        }
+        if (node.namedChildren.some((child) => [
+            "keyword_auto_increment",
+            "keyword_comment",
+            "direction",
+            "keyword_virtual",
+        ].includes(child.type))) {
+            this.problem(node, "This column uses syntax from another SQL dialect.");
+            return;
+        }
+        this.declaration(node, "column", [...table.identity, name], table.id);
+        if (node.namedChildren.some((child) => child.type === "keyword_references"))
+            this.relation(node, table, [name]);
+    }
+    /**
+     * Processes constraints as table semantics unless they declare a foreign-key relation.
+     *
+     * Unsupported dialect-specific keys and indexes are diagnosed before inventory materialization.
+     */
+    constraint(node, table, explicitName) {
+        if (node.namedChildren.some((child) => child.type === "keyword_references")) {
+            if (!node.namedChildren.some((child) => child.type === "keyword_foreign") ||
+                node.childForFieldName("name") !== null) {
+                this.problem(node, "PostgreSQL table foreign keys require FOREIGN KEY without a dialect-specific inline key name.");
+                return;
+            }
+            const columns = node.namedChildren.find((child) => child.type === "ordered_columns");
+            const local = (columns?.namedChildren ?? [])
+                .filter((child) => child.type === "column")
+                .map((child) => {
+                const name = child.childForFieldName("name");
+                return name === null
+                    ? undefined
+                    : PostgresqlIdentity_1.PostgresqlIdentity.identifier(name.text);
+            });
+            if (local.length === 0 || local.some((name) => name === undefined)) {
+                this.problem(node, "Foreign keys require explicit local column endpoints.");
+                return;
+            }
+            this.relation(node, table, local.filter((name) => name !== undefined), explicitName);
+        }
+        else if (node.namedChildren.some((child) => child.type === "keyword_index") ||
+            (node.namedChildren.some((child) => child.type === "keyword_key") &&
+                !node.namedChildren.some((child) => child.type === "keyword_primary")))
+            this.problem(node, "This table constraint uses non-PostgreSQL KEY or INDEX syntax.");
+    }
+    /**
+     * Publishes a foreign key using stable identities for composite endpoints.
+     *
+     * Anonymous constraints must retain endpoint meaning without depending on statement order.
+     */
+    relation(node, table, local, explicitName) {
+        const target = node.namedChildren.find((child) => child.type === "object_reference");
+        const identity = target === undefined ? undefined : PostgresqlIdentity_1.PostgresqlIdentity.path(target);
+        const targetIndex = target === undefined
+            ? -1
+            : node.namedChildren.findIndex((child) => child.id === target.id);
+        const remote = node.namedChildren
+            .slice(targetIndex + 1)
+            .filter((child) => child.type === "identifier")
+            .map((child) => PostgresqlIdentity_1.PostgresqlIdentity.identifier(child.text));
+        if (identity?.length !== 2 ||
+            remote.length !== local.length ||
+            remote.some((name) => name === undefined)) {
+            this.problem(node, "Foreign keys require schema-qualified referenced tables and equally sized explicit column endpoint lists.");
+            return;
+        }
+        const named = node.childForFieldName("name");
+        const name = explicitName ??
+            (node.type === "constraint" && named !== null
+                ? PostgresqlIdentity_1.PostgresqlIdentity.identifier(named.text)
+                : undefined);
+        const segment = name === undefined
+            ? `foreign key ${JSON.stringify(local)} references ${JSON.stringify([...identity, ...remote])}`
+            : `constraint ${name}`;
+        this.declaration(node, "relation", [...table.identity, segment], table.id);
+    }
+    /**
+     * Extracts supported additive ALTER TABLE declarations.
+     *
+     * Destructive or stateful migrations require database history and are rejected by this snapshot scanner.
+     */
+    alter(node) {
+        const target = node.namedChildren.find((child) => child.type === "object_reference");
+        const identity = target === undefined ? undefined : PostgresqlIdentity_1.PostgresqlIdentity.path(target);
+        if (identity?.length !== 2) {
+            this.problem(node, "ALTER TABLE requires an explicit schema-qualified selected table.");
+            return;
+        }
+        const permitted = new Set([
+            "keyword_alter",
+            "keyword_table",
+            "object_reference",
+            "add_column",
+            "add_constraint",
+            "comment",
+            "marginalia",
+        ]);
+        if (node.namedChildren.some((child) => !permitted.has(child.type))) {
+            this.problem(node, "Only unconditional ALTER TABLE ADD COLUMN and ADD CONSTRAINT are supported; renames, drops, type changes, and schema moves require migration evaluation.");
+            return;
+        }
+        const table = this.declaration(node, "model", identity);
+        table.merge = true;
+        this.output.references.push({
+            declarationId: table.id,
+            identity,
+            comment: false,
+        });
+        for (const child of node.namedChildren) {
+            if (child.type === "add_column") {
+                if (!child.namedChildren.some((part) => part.type === "keyword_add") ||
+                    child.namedChildren.some((part) => ["keyword_if", "column_position"].includes(part.type))) {
+                    this.problem(child, "ADD COLUMN must be unconditional PostgreSQL syntax without a positional clause.");
+                    continue;
+                }
+                const column = child.namedChildren.find((part) => part.type === "column_definition");
+                if (column !== undefined)
+                    this.column(column, table);
+            }
+            else if (child.type === "add_constraint") {
+                if (!child.namedChildren.some((part) => part.type === "keyword_constraint")) {
+                    this.problem(child, "PostgreSQL named constraints require ADD CONSTRAINT name.");
+                    continue;
+                }
+                const nameNode = child.namedChildren.find((part) => part.type === "identifier");
+                const name = nameNode === undefined
+                    ? undefined
+                    : PostgresqlIdentity_1.PostgresqlIdentity.identifier(nameNode.text);
+                const constraint = child.namedChildren.find((part) => part.type === "constraint");
+                if (constraint !== undefined && name !== undefined)
+                    this.constraint(constraint, table, name);
+                else
+                    this.problem(child, "ADD CONSTRAINT requires a supported explicit named constraint.");
+            }
+        }
+    }
+    /**
+     * Attaches supported COMMENT ON TABLE or COLUMN strings to their target identity.
+     *
+     * The resulting declaration site resolves against an existing owner after all files are scanned.
+     */
+    commentStatement(node) {
+        const column = node.namedChildren.some((child) => child.type === "keyword_column");
+        const table = node.namedChildren.some((child) => child.type === "keyword_table");
+        const target = node.namedChildren.find((child) => child.type === "object_reference");
+        const identity = target === undefined ? undefined : PostgresqlIdentity_1.PostgresqlIdentity.path(target);
+        const literal = node.namedChildren.find((child) => child.type === "literal");
+        if ((!column && !table) ||
+            identity?.length !== (column ? 3 : 2) ||
+            literal === undefined ||
+            !/^'(?:[^']|'')*'$/su.test(literal.text)) {
+            this.problem(node, "COMMENT requires one schema-qualified TABLE or COLUMN and an ordinary single-quoted string; NULL replacement and other targets are unsupported.");
+            return;
+        }
+        const declaration = this.declaration(node, column ? "column" : "model", identity);
+        declaration.site.id += ":comment";
+        declaration.merge = true;
+        this.output.references.push({
+            declarationId: declaration.id,
+            identity,
+            comment: true,
+        });
+        const mapped = EvidenceDocumentation_1.EvidenceDocumentation.read(this.source.content, "pending", this.session.range(literal), {
+            opening: "'",
+            closing: "'",
+            tagBoundaries: false,
+            allowWithdrawal: true,
+        });
+        let text = "";
+        const offsets = [];
+        const ends = [];
+        for (let index = 0; index < mapped.text.length; ++index) {
+            text += mapped.text[index];
+            offsets.push(mapped.offsets[index] ?? literal.startIndex);
+            if (mapped.text[index] === "'" && mapped.text[index + 1] === "'")
+                ++index;
+            ends.push(mapped.ends[index] ?? literal.endIndex);
+        }
+        offsets.push(literal.endIndex - 1);
+        this.output.documentation.push({
+            id: `${declaration.id}:comment`,
+            range: this.session.range(literal),
+            attachments: [
+                { declarationId: declaration.id, siteId: declaration.site.id },
+            ],
+            mapped: { ...mapped, text, offsets, ends },
+        });
+    }
+    /**
+     * Creates one physical declaration with a file-independent semantic identity.
+     *
+     * Cross-file ALTER and COMMENT sites can therefore merge with the same selected declaration.
+     */
+    declaration(node, symbol, identity, ownerDeclarationId) {
+        const id = `postgresql:${this.source.id}:${node.startIndex}:${symbol}`;
+        const range = this.session.range(node);
+        const declaration = {
+            id,
+            name: identity.at(-1) ?? "",
+            symbol,
+            identity,
+            address: identity,
+            site: {
+                id: `${id}:site`,
+                file: this.source.physicalPath,
+                range,
+                content: [range],
+            },
+            public: true,
+            ...(ownerDeclarationId === undefined ? {} : { ownerDeclarationId }),
+        };
+        this.output.declarations.push(declaration);
+        const declarations = this.nodes.get(node.startIndex) ?? [];
+        declarations.push(declaration);
+        this.nodes.set(node.startIndex, declarations);
+        return declaration;
+    }
+    /**
+     * Establishes ownership for adjacent SQL comments before shared annotation parsing.
+     *
+     * Only standalone runs immediately before a declaration become documentation carriers.
+     */
+    comments() {
+        const comments = this.session.root.descendantsOfType([
+            "comment",
+            "marginalia",
+        ]);
+        for (let index = 0; index < comments.length; ++index) {
+            const first = comments[index];
+            if (first === undefined)
+                continue;
+            const standalone = /^[ \t]*$/u.test(this.source.content.slice(this.source.content.lastIndexOf("\n", first.startIndex - 1) + 1, first.startIndex));
+            let last = first;
+            while (standalone &&
+                first.type === "comment" &&
+                comments[index + 1]?.type === "comment") {
+                const next = comments[index + 1];
+                if (next === undefined ||
+                    !/^\r?\n[ \t]*$/u.test(this.source.content.slice(last.endIndex, next.startIndex)))
+                    break;
+                last = next;
+                ++index;
+            }
+            const next = Array.from(this.nodes.keys())
+                .filter((offset) => offset >= last.endIndex)
+                .sort((a, b) => a - b)[0];
+            const attached = next !== undefined &&
+                standalone &&
+                /^[ \t]*(?:\r?\n[ \t]*)?$/u.test(this.source.content.slice(last.endIndex, next));
+            const declarations = attached ? (this.nodes.get(next) ?? []) : [];
+            const range = {
+                start: this.session.range(first).start,
+                end: this.session.range(last).end,
+            };
+            const doc = {
+                id: `postgresql:${this.source.id}:documentation:${first.startIndex}`,
+                range,
+                attachments: declarations.map((declaration) => ({
+                    declarationId: declaration.id,
+                    siteId: declaration.site.id,
+                })),
+            };
+            this.output.documentation.push(doc);
+        }
+    }
+    /**
+     * Identifies parser extras without interpreting their contents as DDL.
+     *
+     * Comments and marginalia are handled only by the documentation attachment pass.
+     */
+    commentNode(node) {
+        return node.type === "comment" || node.type === "marginalia";
+    }
+    /**
+     * Marks unsupported surface-changing syntax as explicitly incomplete.
+     *
+     * The diagnostic preserves the failure rather than allowing coverage to use fewer obligations.
+     */
+    problem(node, message) {
+        this.output.complete = false;
+        this.output.diagnostics.push({
+            code: "postgresql-unsupported-syntax",
+            severity: "error",
+            message,
+            repair: "Use explicit schema-qualified CREATE TABLE declarations and supported additive DDL, or implement this PostgreSQL construct before checking coverage.",
+            location: {
+                file: this.source.physicalPath,
+                range: this.session.range(node),
+            },
+        });
+    }
+}
+exports.PostgresqlFileScanner = PostgresqlFileScanner;

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

@@ -0,0 +1,14 @@
+import type { IEvidenceInventory } from "../../structures/IEvidenceInventory";
+/** Keeps PostgreSQL COMMENT metadata out of declaration content fingerprints.
+ *
+ * COMMENT sites remain materialized for annotation ownership, while schema
+ * content review must remain stable when only its review metadata changes.
+ */
+export declare namespace PostgresqlFingerprint {
+    /** Recomputes affected content digests from DDL sites alone.
+     *
+     * The cloned inventory removes only COMMENT sites before indexing, preserving
+     * all declaration relationships used to derive the original fingerprint.
+     */
+    function apply(inventory: IEvidenceInventory): void;
+}

package/lib/adapters/postgresql/PostgresqlFingerprint.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresqlFingerprint = void 0;
+const EvidenceFingerprintIndex_1 = require("../../internal/EvidenceFingerprintIndex");
+/** Keeps PostgreSQL COMMENT metadata out of declaration content fingerprints.
+ *
+ * COMMENT sites remain materialized for annotation ownership, while schema
+ * content review must remain stable when only its review metadata changes.
+ */
+var PostgresqlFingerprint;
+(function (PostgresqlFingerprint) {
+    /** Recomputes affected content digests from DDL sites alone.
+     *
+     * The cloned inventory removes only COMMENT sites before indexing, preserving
+     * all declaration relationships used to derive the original fingerprint.
+     */
+    function apply(inventory) {
+        if (!inventory.complete)
+            return;
+        const semantic = structuredClone(inventory);
+        for (const unit of semantic.units)
+            unit.sites = unit.sites.filter((site) => !site.id.endsWith(":comment"));
+        const fingerprints = new EvidenceFingerprintIndex_1.EvidenceFingerprintIndex(semantic);
+        for (const unit of inventory.units)
+            if (unit.sites.some((site) => site.id.endsWith(":comment")))
+                unit.contentDigest = fingerprints.inspect(unit.id).contentDigest;
+    }
+    PostgresqlFingerprint.apply = apply;
+})(PostgresqlFingerprint || (exports.PostgresqlFingerprint = PostgresqlFingerprint = {}));

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

@@ -0,0 +1,20 @@
+import type { Node } from "web-tree-sitter";
+/**
+ * Decodes PostgreSQL identifiers without relying on the session search path.
+ *
+ * The PostgreSQL scanner requires explicit schema paths so snapshot extraction stays deterministic.
+ */
+export declare namespace PostgresqlIdentity {
+    /**
+     * Preserves quoted case and literal dots while folding unquoted ASCII case.
+     *
+     * The result is a semantic segment, so a quoted dot never creates another path segment.
+     */
+    function identifier(raw: string): string | undefined;
+    /**
+     * Reads segmented identifiers from a grammar-owned object reference.
+     *
+     * Invalid or missing identifier segments leave the path unresolved for the caller to diagnose.
+     */
+    function path(node: Node): string[] | undefined;
+}

package/lib/adapters/postgresql/PostgresqlIdentity.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresqlIdentity = void 0;
+/**
+ * Decodes PostgreSQL identifiers without relying on the session search path.
+ *
+ * The PostgreSQL scanner requires explicit schema paths so snapshot extraction stays deterministic.
+ */
+var PostgresqlIdentity;
+(function (PostgresqlIdentity) {
+    /**
+     * Preserves quoted case and literal dots while folding unquoted ASCII case.
+     *
+     * The result is a semantic segment, so a quoted dot never creates another path segment.
+     */
+    function identifier(raw) {
+        if (/^"(?:[^"]|"")+"$/u.test(raw)) {
+            const decoded = raw.slice(1, -1).replaceAll('""', '"');
+            return Buffer.byteLength(decoded, "utf8") <= 63 ? decoded : undefined;
+        }
+        if (Buffer.byteLength(raw, "utf8") > 63)
+            return undefined;
+        return /^[A-Za-z_\u00c0-\u017f][A-Za-z_0-9\u00c0-\u017f]*$/u.test(raw)
+            ? raw.replace(/[A-Z]/gu, (letter) => letter.toLowerCase())
+            : undefined;
+    }
+    PostgresqlIdentity.identifier = identifier;
+    /**
+     * Reads segmented identifiers from a grammar-owned object reference.
+     *
+     * Invalid or missing identifier segments leave the path unresolved for the caller to diagnose.
+     */
+    function path(node) {
+        const identifiers = node.descendantsOfType("identifier");
+        const names = (node.type === "identifier" ? [node] : identifiers).map((identifierNode) => identifier(identifierNode.text));
+        return names.length !== 0 && names.every((name) => name !== undefined)
+            ? names
+            : undefined;
+    }
+    PostgresqlIdentity.path = path;
+})(PostgresqlIdentity || (exports.PostgresqlIdentity = PostgresqlIdentity = {}));

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

@@ -0,0 +1,14 @@
+import type { ISqlFileAnalysis } from "../sql/ISqlFileAnalysis";
+/** Reconciles ALTER and COMMENT sites independently of selected file ordering.
+ *
+ * PostgreSQL permits extension statements in other files, so publication waits
+ * until a unique selected declaration can establish their semantic ownership.
+ */
+export declare namespace PostgresqlOwnership {
+    /** Resolves every deferred extension against exactly one declaration.
+     *
+     * Ambiguity makes analysis incomplete rather than allowing an ALTER or COMMENT
+     * to silently attach to an arbitrary same-named table.
+     */
+    function resolve(input: ISqlFileAnalysis[]): void;
+}