@pgsql/lint 18.1.0

package/esm/file-runner.js

@@ -0,0 +1,221 @@
+/**
+ * Run the linter over SQL *source files* — migrations, `CREATE FUNCTION`
+ * scripts, anything on disk. This is the "local" entry point (CLI, pre-commit,
+ * editor): it finds every function definition in a file, lints each one, and
+ * re-anchors the findings to absolute file lines.
+ *
+ * The library entry point ({@link lintDefinition}) takes a single definition
+ * as safegres feeds it from `pg_get_functiondef`; this layer adds the file
+ * plumbing on top so a human or an agent can point it at `.sql` and get the
+ * same findings without a database.
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { parse } from 'pgsql-parser';
+import { lintDefinition } from './engine';
+import { findAll } from './walk';
+/** Count newlines before `offset` — the 0-based line the offset sits on. */
+function lineAtOffset(text, offset) {
+    let n = 0;
+    const end = Math.min(Math.max(offset, 0), text.length);
+    for (let i = 0; i < end; i++)
+        if (text.charCodeAt(i) === 10)
+            n++;
+    return n;
+}
+/** Printable `schema.name` of a `CreateFunctionStmt.funcname`. */
+function funcName(createFnStmt) {
+    const funcname = createFnStmt.funcname;
+    if (!Array.isArray(funcname))
+        return '<anonymous>';
+    const parts = funcname
+        .map((n) => {
+        const str = n.String;
+        return str && typeof str.sval === 'string' ? str.sval : '';
+    })
+        .filter((s) => s.length > 0);
+    return parts.length > 0 ? parts.join('.') : '<anonymous>';
+}
+/** The `LANGUAGE` of a `CreateFunctionStmt` (lower-cased), defaulting to `sql`. */
+function funcLanguage(createFnStmt) {
+    const options = createFnStmt.options;
+    if (Array.isArray(options)) {
+        for (const opt of options) {
+            const de = opt.DefElem;
+            if (de?.defname === 'language') {
+                const str = de.arg?.String;
+                if (str && typeof str.sval === 'string')
+                    return str.sval.toLowerCase();
+            }
+        }
+    }
+    return 'sql';
+}
+/**
+ * Split a SQL source string into the function definitions it contains. Each
+ * `CREATE FUNCTION` is sliced back out with its absolute start line, so a
+ * mixed migration (schema + tables + functions) yields one input per function
+ * rather than being treated as a single malformed definition.
+ */
+export async function sqlTextDefinitions(source, file) {
+    const parsed = (await parse(source));
+    const out = [];
+    for (const entry of parsed.stmts ?? []) {
+        const createFnStmt = entry.stmt ? findAll(entry.stmt, 'CreateFunctionStmt')[0] : undefined;
+        if (!createFnStmt)
+            continue;
+        const start = entry.stmt_location ?? 0;
+        const len = entry.stmt_len ?? source.length - start;
+        out.push({
+            text: source.slice(start, start + len),
+            language: funcLanguage(createFnStmt),
+            name: funcName(createFnStmt),
+            file,
+            startLine: lineAtOffset(source, start) // 0-based line the definition begins on
+        });
+    }
+    return out;
+}
+/**
+ * Lint a SQL source string that may contain many statements. Findings are
+ * re-anchored to absolute lines within `source`.
+ */
+export async function lintSqlText(source, options = {}) {
+    let inputs;
+    try {
+        inputs = await sqlTextDefinitions(source);
+    }
+    catch (err) {
+        return { file: '<source>', findings: [], parseError: err.message };
+    }
+    const findings = await lintInputs(inputs, options);
+    return { file: '<source>', findings };
+}
+/** Lint a set of adapter-produced definitions, re-anchored to file lines. */
+async function lintInputs(inputs, options) {
+    const findings = [];
+    for (const input of inputs) {
+        const subject = input.name ?? '<anonymous>';
+        const startLine = input.startLine ?? 0;
+        const { problems, suppressed } = await lintDefinition(input.text, input.language, subject, options);
+        const absLine = (p) => startLine + p.line; // p.line is 1-based within input.text
+        for (const p of problems)
+            findings.push(toFinding(p, subject, absLine(p), false));
+        for (const s of suppressed) {
+            findings.push(toFinding(s, subject, absLine(s), true, s.reason, s.scope));
+        }
+    }
+    findings.sort((a, b) => a.line - b.line || a.ruleId.localeCompare(b.ruleId));
+    return findings;
+}
+function toFinding(p, subject, line, acknowledged, reason, scope) {
+    const meta = {
+        ruleId: p.ruleId,
+        code: codeFor(p.ruleId),
+        line,
+        message: p.message,
+        severity: p.severity ?? 'error',
+        subject,
+        acknowledged,
+        context: p.context
+    };
+    if (p.hint)
+        meta.hint = p.hint;
+    if (acknowledged) {
+        meta.reason = reason ?? null;
+        meta.scope = scope;
+    }
+    return meta;
+}
+const RULE_CODE = {
+    'no-set-search-path': 'C1',
+    'no-variable-conflict': 'C2',
+    'require-qualified-refs': 'C3',
+    'no-dynamic-sql': 'C4'
+};
+function codeFor(ruleId) {
+    return RULE_CODE[ruleId] ?? ruleId;
+}
+/** Recursively collect `.sql` files under a directory. */
+async function sqlFilesUnder(dir) {
+    const out = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist')
+                continue;
+            out.push(...(await sqlFilesUnder(full)));
+        }
+        else if (e.isFile() && full.toLowerCase().endsWith('.sql')) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/** Resolve a mix of file and directory paths to a sorted list of `.sql` files. */
+export async function resolveSqlFiles(paths) {
+    const files = new Set();
+    for (const p of paths) {
+        const st = await fs.stat(p);
+        if (st.isDirectory()) {
+            for (const f of await sqlFilesUnder(p))
+                files.add(f);
+        }
+        else if (st.isFile()) {
+            files.add(p);
+        }
+    }
+    return [...files].sort();
+}
+/** Lint every `.sql` file reachable from `paths` (files or directories). */
+export async function lintFiles(paths, options = {}) {
+    const files = await resolveSqlFiles(paths);
+    const reports = [];
+    for (const file of files) {
+        const source = await fs.readFile(file, 'utf8');
+        const report = await lintSqlText(source, options);
+        reports.push({ ...report, file });
+    }
+    return reports;
+}
+/** A {@link SourceAdapter} over an in-memory SQL string. */
+export function sqlTextAdapter(source, file) {
+    return { id: 'sql-text', definitions: () => sqlTextDefinitions(source, file) };
+}
+/** A {@link SourceAdapter} over `.sql` files/directories on disk. */
+export function filesAdapter(paths) {
+    return {
+        id: 'files',
+        definitions: async () => {
+            const files = await resolveSqlFiles(paths);
+            const out = [];
+            for (const file of files) {
+                out.push(...(await sqlTextDefinitions(await fs.readFile(file, 'utf8'), file)));
+            }
+            return out;
+        }
+    };
+}
+/**
+ * Lint every definition an adapter yields, grouped into one {@link FileReport}
+ * per origin file. This is the generic entry point: `@pgsql/lint` ships file
+ * and sql-text adapters; a consumer (e.g. safegres over a live catalog) can
+ * pass its own.
+ */
+export async function lintSource(adapter, options = {}) {
+    const inputs = await adapter.definitions();
+    const byFile = new Map();
+    for (const input of inputs) {
+        const file = input.file ?? `<${adapter.id}>`;
+        const arr = byFile.get(file) ?? [];
+        arr.push(input);
+        byFile.set(file, arr);
+    }
+    const reports = [];
+    for (const [file, group] of byFile) {
+        reports.push({ file, findings: await lintInputs(group, options) });
+    }
+    reports.sort((a, b) => a.file.localeCompare(b.file));
+    return reports;
+}

package/esm/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@pgsql/lint` — a source-level SQL/PL/pgSQL convention linter.
+ *
+ * It reasons about the *text* of a function definition — fully-qualified
+ * references, `search_path` settings, `#variable_conflict`, dynamic SQL — from
+ * its AST, and carries no `pg` / catalog dependency. The same engine runs over
+ * a `CREATE FUNCTION` from a migration, an editor buffer, or a definition read
+ * from a live catalog via `pg_get_functiondef`.
+ *
+ * Rules are injected as values, never discovered by npm name: build a linter
+ * with `createLinter({ rules, severity })` and pass your own rules in.
+ */
+export { lintDefinition, severityOf } from './engine';
+export { filesAdapter, lintFiles, lintSource, lintSqlText, resolveSqlFiles, sqlTextAdapter, sqlTextDefinitions } from './file-runner';
+export { createLinter } from './linter';
+export { parseUnit } from './parse-unit';
+export { LINT_RULES, LINT_RULES_BY_CODE, LINT_RULES_BY_ID, noDynamicSql, noSetSearchPath, noVariableConflict, requireQualifiedRefs } from './rules';
+export { DEFAULT_KEYWORDS, Suppressions } from './suppressions';
+export { defineRule } from './types';

package/esm/linter.js

@@ -0,0 +1,36 @@
+/**
+ * `createLinter` — the ecosystem entry point.
+ *
+ * A linter is nothing but a rule set + severities + directive keyword bound
+ * together. Rules are passed *in* as values (not discovered by npm name), so
+ * anyone can publish a rule package, `import` it, and add it here. Severity is
+ * configuration (ESLint-style `off` / `warn` / `error`), keyed by rule id or
+ * code, so a downstream consumer (safegres) keeps full control of how loud
+ * each rule is without duplicating any engine logic.
+ */
+import { lintDefinition } from './engine';
+import { filesAdapter, lintFiles, lintSource, lintSqlText, sqlTextAdapter } from './file-runner';
+import { LINT_RULES } from './rules';
+import { DEFAULT_KEYWORDS } from './suppressions';
+/** Build a {@link Linter} bound to a rule set, severities, and keyword. */
+export function createLinter(config = {}) {
+    const rules = config.rules ?? LINT_RULES;
+    const severity = config.severity ?? {};
+    const keyword = config.keyword ?? DEFAULT_KEYWORDS;
+    const bind = (options = {}) => ({
+        ruleSet: rules,
+        severity,
+        keyword,
+        rules: options.rules
+    });
+    return {
+        rules,
+        severity,
+        keyword,
+        lintDefinition: (text, language, name, options) => lintDefinition(text, language, name, bind(options)),
+        lintSqlText: (source, options) => lintSqlText(source, bind(options)),
+        lintFiles: (paths, options) => lintFiles(paths, bind(options)),
+        lintSource: (adapter, options) => lintSource(adapter, bind(options))
+    };
+}
+export { filesAdapter, sqlTextAdapter };

package/esm/parse-unit.js

@@ -0,0 +1,170 @@
+/**
+ * Turn a `CREATE FUNCTION …` definition into a {@link LintUnit}: the parsed
+ * SQL statement, the embedded body fragments, and the machinery to map any
+ * AST location back to an absolute line in the original text.
+ *
+ * Line mapping is the whole trick. PL/pgSQL statement line numbers are
+ * relative to the *body* (`prosrc`), and embedded SQL expressions are parsed
+ * in isolation, so both have to be re-anchored to the definition text before a
+ * finding — or a suppression comment — can be matched to them.
+ */
+import { parsePlPgSQL } from 'libpg-query';
+import { parse } from 'pgsql-parser';
+import { findAll } from './walk';
+/** Count newlines in `s[0..offset)` — i.e. how many lines precede `offset`. */
+function newlinesBefore(s, offset) {
+    let n = 0;
+    const end = Math.min(offset, s.length);
+    for (let i = 0; i < end; i++)
+        if (s.charCodeAt(i) === 10)
+            n++;
+    return n;
+}
+/** Absolute 1-based line of a char offset within `text`. */
+function lineOf(text, offset) {
+    return newlinesBefore(text, offset) + 1;
+}
+/** The body string of a `CreateFunctionStmt` (`AS $$ … $$`), or null. */
+function functionBody(createFnStmt) {
+    const options = createFnStmt.options;
+    if (!Array.isArray(options))
+        return null;
+    for (const opt of options) {
+        const de = opt.DefElem;
+        if (!de || de.defname !== 'as')
+            continue;
+        const arg = de.arg;
+        const list = arg?.List;
+        const items = list?.items;
+        if (!Array.isArray(items) || items.length === 0)
+            return null;
+        // A two-item AS (`obj_file`, `link_symbol`) is a C function — no SQL body.
+        if (items.length > 1)
+            return null;
+        const str = items[0].String;
+        const sval = str?.sval;
+        return typeof sval === 'string' ? sval : null;
+    }
+    return null;
+}
+/**
+ * Walk the PL/pgSQL JSON tree, collecting (a) every embedded SQL expression
+ * with the line number of its enclosing statement and (b) every dynamic-SQL
+ * site. Line numbers here are body-relative; the caller re-anchors them.
+ */
+function collectPlpgsql(node, currentLine, exprs, dynamic) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectPlpgsql(item, currentLine, exprs, dynamic);
+        return;
+    }
+    if (!node || typeof node !== 'object')
+        return;
+    const rec = node;
+    // A statement node carries its own line; descendants inherit it until the
+    // next statement re-sets it.
+    let line = currentLine;
+    for (const [key, value] of Object.entries(rec)) {
+        if (key.startsWith('PLpgSQL_stmt_')) {
+            const stmt = value;
+            if (typeof stmt.lineno === 'number')
+                line = stmt.lineno;
+            if (key === 'PLpgSQL_stmt_dynexecute') {
+                dynamic.push({ line, form: 'EXECUTE' });
+            }
+            else if (key === 'PLpgSQL_stmt_dynfors') {
+                dynamic.push({ line, form: 'FOR … IN EXECUTE' });
+            }
+        }
+    }
+    const expr = rec.PLpgSQL_expr;
+    if (expr && typeof expr.query === 'string') {
+        exprs.push({
+            query: expr.query,
+            parseMode: typeof expr.parseMode === 'number' ? expr.parseMode : 2,
+            line
+        });
+    }
+    for (const value of Object.values(rec))
+        collectPlpgsql(value, line, exprs, dynamic);
+}
+/** Reconstruct a parseable SQL string from a PL/pgSQL embedded expression. */
+function fragmentSql(query, parseMode) {
+    // parseMode 0 = full statement; 3 = assignment (strip the anchored target so
+    // the RHS parses); anything else is a bare expression.
+    if (parseMode === 0)
+        return query;
+    let q = query;
+    if (parseMode === 3) {
+        q = q.replace(/^\s*[a-zA-Z_"][\w$".]*(\[[^\]]*\])*\s*:?=\s*/, '');
+    }
+    return `SELECT ${q}`;
+}
+/**
+ * Parse a function definition into a {@link LintUnit}. Never throws: an
+ * unparseable definition comes back with `parseError` set and no fragments,
+ * so rules that need the AST simply find nothing.
+ */
+export async function parseUnit(text, language, name) {
+    const lines = text.split('\n');
+    const base = { text, lines, language, name, fragments: [], dynamicSql: [] };
+    let sqlAst;
+    try {
+        sqlAst = await parse(text);
+    }
+    catch (err) {
+        return { ...base, parseError: `definition failed to parse: ${err.message}` };
+    }
+    const createFnStmt = findAll(sqlAst, 'CreateFunctionStmt')[0];
+    if (!createFnStmt)
+        return { ...base, parseError: 'not a CREATE FUNCTION statement' };
+    const body = functionBody(createFnStmt);
+    const bodyOffset = body !== null ? text.indexOf(body) : -1;
+    const bodyStartLine = bodyOffset >= 0 ? lineOf(text, bodyOffset) : undefined;
+    const fragments = [];
+    const dynamicSql = [];
+    const lang = language.toLowerCase();
+    if (lang === 'sql' && body !== null && bodyStartLine !== undefined) {
+        // A SQL-language body is itself SQL: parse it whole. Locations are
+        // relative to the body, so re-anchor them onto the definition.
+        try {
+            const ast = await parse(body);
+            fragments.push({
+                ast,
+                lineForOffset: (offset) => bodyStartLine + newlinesBefore(body, offset)
+            });
+        }
+        catch {
+            // Body may contain positional parameters etc. that don't parse alone —
+            // leave it as no fragment rather than erroring the whole unit.
+        }
+    }
+    else if (lang === 'plpgsql') {
+        let plpgsql;
+        try {
+            plpgsql = await parsePlPgSQL(text);
+        }
+        catch (err) {
+            return { ...base, createFnStmt, bodyStartLine, parseError: `PL/pgSQL body failed to parse: ${err.message}` };
+        }
+        const exprs = [];
+        const dyn = [];
+        collectPlpgsql(plpgsql, 0, exprs, dyn);
+        const anchor = (bodyLine) => bodyStartLine !== undefined && bodyLine > 0 ? bodyStartLine + (bodyLine - 1) : (bodyStartLine ?? 1);
+        for (const d of dyn)
+            dynamicSql.push({ line: anchor(d.line), form: d.form });
+        for (const e of exprs) {
+            const sql = fragmentSql(e.query, e.parseMode);
+            let ast;
+            try {
+                ast = await parse(sql);
+            }
+            catch {
+                continue; // opaque fragment — not the linter's concern
+            }
+            const absLine = anchor(e.line);
+            fragments.push({ ast, lineForOffset: () => absLine });
+        }
+    }
+    return { ...base, createFnStmt, bodyStartLine, fragments, dynamicSql };
+}

package/esm/rules/index.js

@@ -0,0 +1,14 @@
+import { noDynamicSql } from './no-dynamic-sql';
+import { noSetSearchPath } from './no-set-search-path';
+import { noVariableConflict } from './no-variable-conflict';
+import { requireQualifiedRefs } from './require-qualified-refs';
+/** The lint rules, in report order. */
+export const LINT_RULES = [
+    noSetSearchPath,
+    requireQualifiedRefs,
+    noVariableConflict,
+    noDynamicSql
+];
+export const LINT_RULES_BY_ID = new Map(LINT_RULES.map((r) => [r.id, r]));
+export const LINT_RULES_BY_CODE = new Map(LINT_RULES.map((r) => [r.code, r]));
+export { noDynamicSql, noSetSearchPath, noVariableConflict, requireQualifiedRefs };

package/esm/rules/no-dynamic-sql.js

@@ -0,0 +1,26 @@
+/**
+ * `no-dynamic-sql` (C4): a function must not use dynamic SQL.
+ *
+ * Dynamic SQL (`EXECUTE`, `EXECUTE … USING`, `FOR … IN EXECUTE`) is permitted
+ * only for lookup-only or code-generation work, and never for writes — but the
+ * string handed to `EXECUTE` is opaque to the parser, so we cannot statically
+ * tell read from write. The enforceable form is therefore: flag every site,
+ * and require a categorized waiver. This is the one rule whose suppression
+ * must carry a reason (see `reasonRequired`), so an approved use always names
+ * *why* (`lookup-only` / `codegen`).
+ */
+export const noDynamicSql = {
+    id: 'no-dynamic-sql',
+    code: 'C4',
+    title: 'Function must not use dynamic SQL',
+    reasonRequired: true,
+    run(unit) {
+        return unit.dynamicSql.map((site) => ({
+            ruleId: 'no-dynamic-sql',
+            line: site.line,
+            message: `Function uses dynamic SQL (${site.form})`,
+            hint: 'Avoid dynamic SQL. If it is genuinely lookup-only or code-generation (never a write), waive it with a reason: `-- pgsql-lint-disable-next-line no-dynamic-sql -- lookup-only: <why>`.',
+            context: { form: site.form }
+        }));
+    }
+};

package/esm/rules/no-set-search-path.js

@@ -0,0 +1,64 @@
+/**
+ * `no-set-search-path` (C1): a function must never set `search_path`.
+ *
+ * House rule: rather than pin `search_path` (the usual CWE-426 mitigation for
+ * SECURITY DEFINER), we fully-qualify every reference and never touch the
+ * setting at all. This flags both forms:
+ *   - the declarative `CREATE FUNCTION … SET search_path = …` clause (this is
+ *     exactly what `pg_proc.proconfig` / `searchPathPinned` records), and
+ *   - a runtime `set_config('search_path', …)` in the body.
+ */
+import { lineOfOffset } from '../util';
+function optionSites(unit) {
+    const out = [];
+    const options = unit.createFnStmt?.options;
+    if (!Array.isArray(options))
+        return out;
+    for (const opt of options) {
+        const de = opt.DefElem;
+        if (!de || de.defname !== 'set')
+            continue;
+        const vss = de.arg?.VariableSetStmt;
+        if (!vss || vss.name !== 'search_path')
+            continue;
+        const loc = typeof de.location === 'number' ? de.location : 0;
+        out.push({
+            ruleId: 'no-set-search-path',
+            line: lineOfOffset(unit.text, loc),
+            message: 'Function sets search_path',
+            hint: 'Never set search_path. Fully-qualify every relation, function and type reference instead.',
+            context: { form: 'SET clause' }
+        });
+    }
+    return out;
+}
+function setConfigSites(unit) {
+    const out = [];
+    const re = /\bset_config\s*\(\s*'search_path'/i;
+    unit.lines.forEach((text, i) => {
+        if (re.test(text)) {
+            out.push({
+                ruleId: 'no-set-search-path',
+                line: i + 1,
+                message: 'Function sets search_path via set_config()',
+                hint: 'Never set search_path. Fully-qualify references instead of relying on it.',
+                context: { form: 'set_config()' }
+            });
+        }
+    });
+    return out;
+}
+export const noSetSearchPath = {
+    id: 'no-set-search-path',
+    code: 'C1',
+    title: 'Function must not set search_path',
+    reasonRequired: false,
+    run(unit) {
+        const byLine = new Map();
+        for (const p of [...optionSites(unit), ...setConfigSites(unit)]) {
+            if (!byLine.has(p.line))
+                byLine.set(p.line, p);
+        }
+        return [...byLine.values()].sort((a, b) => a.line - b.line);
+    }
+};

package/esm/rules/no-variable-conflict.js

@@ -0,0 +1,36 @@
+/**
+ * `no-variable-conflict` (C2): a PL/pgSQL body must not use a
+ * `#variable_conflict` directive.
+ *
+ * The directive papers over an ambiguity between a column name and a PL/pgSQL
+ * variable; the house style is to remove the ambiguity (rename the variable,
+ * qualify the column) rather than declare a winner. The directive is a
+ * compiler pragma that must start a line at the top of the body, so a line
+ * scan is exact — it never appears inside an expression or string.
+ */
+const RE = /^\s*#variable_conflict\b\s*(\S+)?/i;
+export const noVariableConflict = {
+    id: 'no-variable-conflict',
+    code: 'C2',
+    title: 'Function must not use #variable_conflict',
+    reasonRequired: false,
+    run(unit) {
+        if (unit.language.toLowerCase() !== 'plpgsql')
+            return [];
+        const out = [];
+        for (let i = 0; i < unit.lines.length; i++) {
+            const m = RE.exec(unit.lines[i]);
+            if (!m)
+                continue;
+            const mode = m[1] ?? '';
+            out.push({
+                ruleId: 'no-variable-conflict',
+                line: i + 1,
+                message: `Function uses #variable_conflict${mode ? ` ${mode}` : ''}`,
+                hint: 'Remove the directive and disambiguate explicitly: rename the variable or qualify the column reference.',
+                context: { mode }
+            });
+        }
+        return out;
+    }
+};

package/esm/rules/require-qualified-refs.js

@@ -0,0 +1,68 @@
+/**
+ * `require-qualified-refs` (C3): every relation reference must be
+ * schema-qualified.
+ *
+ * Banning `SET search_path` (C1) only removes the footgun; it does not make
+ * name resolution safe on its own. This is the rule that actually enforces the
+ * discipline: an unqualified `FROM users` resolves against whatever
+ * search_path happens to be, so it must be `FROM app_public.users`.
+ *
+ * v1 covers relation references (`RangeVar`). Names introduced by a CTE in the
+ * same query are excluded — they are not schema objects. Unqualified *function*
+ * calls are deferred (they need a built-in allowlist to avoid flagging
+ * `now()`, `count()`, …).
+ */
+import { findAll } from '../walk';
+function cteNames(ast) {
+    const out = new Set();
+    for (const cte of findAll(ast, 'CommonTableExpr')) {
+        if (typeof cte.ctename === 'string')
+            out.add(cte.ctename);
+    }
+    return out;
+}
+function fragmentProblems(fragment) {
+    const out = [];
+    const ctes = cteNames(fragment.ast);
+    const seen = new Set();
+    for (const rv of findAll(fragment.ast, 'RangeVar')) {
+        const relname = typeof rv.relname === 'string' ? rv.relname : undefined;
+        if (!relname)
+            continue;
+        if (typeof rv.schemaname === 'string' && rv.schemaname.length > 0)
+            continue;
+        if (ctes.has(relname))
+            continue;
+        const loc = typeof rv.location === 'number' ? rv.location : -1;
+        const line = fragment.lineForOffset(loc >= 0 ? loc : 0);
+        const key = `${line}:${relname}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({
+            ruleId: 'require-qualified-refs',
+            line,
+            message: `Unqualified relation reference "${relname}"`,
+            hint: 'Schema-qualify the reference (e.g. `app_public.' + relname + '`). Unqualified names resolve against search_path.',
+            context: { relation: relname }
+        });
+    }
+    return out;
+}
+export const requireQualifiedRefs = {
+    id: 'require-qualified-refs',
+    code: 'C3',
+    title: 'Relation references must be schema-qualified',
+    reasonRequired: false,
+    run(unit) {
+        const byKey = new Map();
+        for (const fragment of unit.fragments) {
+            for (const p of fragmentProblems(fragment)) {
+                const key = `${p.line}:${p.context.relation}`;
+                if (!byKey.has(key))
+                    byKey.set(key, p);
+            }
+        }
+        return [...byKey.values()].sort((a, b) => a.line - b.line);
+    }
+};