@pgsql/lint 18.1.0

package/esm/suppressions.js

@@ -0,0 +1,131 @@
+/**
+ * ESLint / Prettier-style suppression comments, embedded in the SQL body as
+ * `--` line comments. Because they live in the function source, a waiver
+ * authored in a migration survives `pg_get_functiondef` and is visible to any
+ * downstream consumer (a live-database audit, a pre-commit hook) — the comment
+ * is the single source of truth.
+ *
+ * Grammar (a `--` comment containing), with `<kw>` the directive keyword
+ * (`pgsql-lint` by default; `safegres` is also accepted):
+ *
+ *   <kw>-disable-next-line [<rule>…] [-- <reason>]   next physical line
+ *   <kw>-disable-line      [<rule>…] [-- <reason>]   this physical line
+ *   <kw>-disable           [<rule>…] [-- <reason>]   until a matching enable
+ *   <kw>-enable            [<rule>…]                 closes a disable range
+ *   <kw>-disable-file      [<rule>…] [-- <reason>]   the whole definition
+ *
+ * With no rule listed a directive applies to every rule. A reason follows a
+ * second `--` (ESLint style) or a `:`. Rules whose metadata requires a reason
+ * are *not* silenced by a reasonless directive — the finding stands, so a
+ * waiver is never silent.
+ */
+/** The directive keyword(s) recognised when none is configured explicitly. */
+export const DEFAULT_KEYWORDS = ['pgsql-lint', 'safegres'];
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function directiveRe(keywords) {
+    const kw = keywords.map(escapeRegExp).join('|');
+    return new RegExp(`(?:${kw})-(disable-next-line|disable-line|disable-file|disable|enable)\\b[ \\t]*([^\\r\\n]*)`, 'i');
+}
+function splitReason(rest) {
+    const dashIdx = rest.indexOf('--');
+    if (dashIdx >= 0) {
+        return { ruleSpec: rest.slice(0, dashIdx), reason: normalizeReason(rest.slice(dashIdx + 2)) };
+    }
+    const colonIdx = rest.indexOf(':');
+    if (colonIdx >= 0) {
+        return { ruleSpec: rest.slice(0, colonIdx), reason: normalizeReason(rest.slice(colonIdx + 1)) };
+    }
+    return { ruleSpec: rest, reason: null };
+}
+function normalizeReason(s) {
+    const t = s.trim().replace(/\*\/\s*$/, '').trim();
+    return t.length > 0 ? t : null;
+}
+function parseRules(ruleSpec) {
+    const parts = ruleSpec.split(/[\s,]+/).map((p) => p.trim()).filter((p) => p.length > 0);
+    return parts.length > 0 ? new Set(parts) : null;
+}
+/** Parsed suppression state for one definition, queryable by (rule, line). */
+export class Suppressions {
+    lineDirectives = [];
+    intervals = [];
+    fileDirectives = [];
+    constructor(lines, keywords = DEFAULT_KEYWORDS) {
+        const re = directiveRe(keywords);
+        // Range bookkeeping: an open disable per rule (and one for "all").
+        const open = new Map();
+        lines.forEach((text, i) => {
+            const line = i + 1;
+            const m = re.exec(text);
+            if (!m)
+                return;
+            const kind = m[1].toLowerCase();
+            const { ruleSpec, reason } = splitReason(m[2] ?? '');
+            const rules = parseRules(ruleSpec);
+            switch (kind) {
+                case 'disable-next-line':
+                    this.lineDirectives.push({ scope: 'next-line', targetLine: line + 1, rules, reason });
+                    break;
+                case 'disable-line':
+                    this.lineDirectives.push({ scope: 'line', targetLine: line, rules, reason });
+                    break;
+                case 'disable-file':
+                    this.fileDirectives.push({ rules, reason });
+                    break;
+                case 'disable': {
+                    const keys = rules ? [...rules] : [null];
+                    for (const k of keys)
+                        if (!open.has(k))
+                            open.set(k, { start: line, reason });
+                    break;
+                }
+                case 'enable': {
+                    const keys = rules ? [...rules] : [...open.keys()];
+                    for (const k of keys) {
+                        const o = open.get(k);
+                        if (o) {
+                            this.intervals.push({ rule: k, start: o.start, end: line, reason: o.reason });
+                            open.delete(k);
+                        }
+                    }
+                    break;
+                }
+            }
+        });
+        for (const [rule, o] of open) {
+            this.intervals.push({ rule, start: o.start, end: Number.POSITIVE_INFINITY, reason: o.reason });
+        }
+    }
+    match(ruleId, line) {
+        for (const f of this.fileDirectives) {
+            if (f.rules === null || f.rules.has(ruleId))
+                return { scope: 'file', reason: f.reason };
+        }
+        for (const d of this.lineDirectives) {
+            if (d.targetLine === line && (d.rules === null || d.rules.has(ruleId))) {
+                return { scope: d.scope, reason: d.reason };
+            }
+        }
+        for (const iv of this.intervals) {
+            if ((iv.rule === null || iv.rule === ruleId) && line >= iv.start && line < iv.end) {
+                return { scope: 'range', reason: iv.reason };
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolve whether a finding is suppressed. `reasonRequired` rules are only
+     * silenced by a directive that carries a reason.
+     */
+    resolve(ruleId, line, reasonRequired) {
+        const m = this.match(ruleId, line);
+        if (!m)
+            return { suppressed: false };
+        if (reasonRequired && (m.reason === null || m.reason.length === 0)) {
+            return { suppressed: false, invalidMissingReason: true, scope: m.scope };
+        }
+        return { suppressed: true, scope: m.scope, reason: m.reason };
+    }
+}

package/esm/types.js

@@ -0,0 +1,23 @@
+/**
+ * Source-level SQL/PL/pgSQL linter — types.
+ *
+ * This package is deliberately free of any `pg` / catalog dependency: it takes
+ * a function *definition* (the `CREATE FUNCTION …` text, as `pg_get_functiondef`
+ * returns it, or as authored in a migration) and returns findings. Everything
+ * here is decided from source text and its AST, so the linter runs the same in
+ * a migration, an editor, a pre-commit hook, or a live-database auditor.
+ */
+/**
+ * Authoring helper for third-party rules. A no-op at runtime (identity), it
+ * exists only to pin the `LintRule` shape at the call site so a rule package
+ * gets full type-checking without importing internals.
+ *
+ * @example
+ * export const noWritesInView = defineRule({
+ *   id: 'no-writes-in-view', code: 'X1', title: '…', reasonRequired: false,
+ *   run(unit) { return []; }
+ * });
+ */
+export function defineRule(rule) {
+    return rule;
+}

package/esm/util.js

@@ -0,0 +1,9 @@
+/** Absolute 1-based line of a char offset within `text`. */
+export function lineOfOffset(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 + 1;
+}

package/esm/walk.js

@@ -0,0 +1,14 @@
+/**
+ * The one AST helper the rules need, layered on `@pgsql/traverse`'s `walk`.
+ */
+import { walk } from '@pgsql/traverse';
+/** Find every node tagged with `tag` (e.g. `RangeVar`, `CommonTableExpr`). */
+export function findAll(root, tag) {
+    const out = [];
+    walk(root, (path) => {
+        if (path.tag === tag) {
+            out.push(path.node);
+        }
+    });
+    return out;
+}

package/file-runner.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 { LintOptions } from './engine';
+import type { LintDefinitionInput, Severity, SourceAdapter, SuppressionScope } from './types';
+/** A finding re-anchored to a source file. */
+export interface FileFinding {
+    ruleId: string;
+    /** Registry code, e.g. `C4`. */
+    code: string;
+    /** 1-based line within the file. */
+    line: number;
+    message: string;
+    hint?: string;
+    /** Configured severity (`error` by default; `warn` does not fail a run). */
+    severity: Severity;
+    /** The function it was found in, e.g. `app.grant_role`. */
+    subject: string;
+    /** True when a suppression comment acknowledged it (accepted risk, kept visible). */
+    acknowledged: boolean;
+    /** Waiver reason, when acknowledged and one was given. */
+    reason?: string | null;
+    /** Suppression scope, when acknowledged. */
+    scope?: SuppressionScope;
+    context?: Record<string, unknown>;
+}
+/** The result of linting one source file. */
+export interface FileReport {
+    file: string;
+    findings: FileFinding[];
+    /** A parse error on the whole file (not a single definition). */
+    parseError?: string;
+}
+/**
+ * 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 declare function sqlTextDefinitions(source: string, file?: string): Promise<LintDefinitionInput[]>;
+/**
+ * Lint a SQL source string that may contain many statements. Findings are
+ * re-anchored to absolute lines within `source`.
+ */
+export declare function lintSqlText(source: string, options?: LintOptions): Promise<FileReport>;
+/** Resolve a mix of file and directory paths to a sorted list of `.sql` files. */
+export declare function resolveSqlFiles(paths: string[]): Promise<string[]>;
+/** Lint every `.sql` file reachable from `paths` (files or directories). */
+export declare function lintFiles(paths: string[], options?: LintOptions): Promise<FileReport[]>;
+/** A {@link SourceAdapter} over an in-memory SQL string. */
+export declare function sqlTextAdapter(source: string, file?: string): SourceAdapter;
+/** A {@link SourceAdapter} over `.sql` files/directories on disk. */
+export declare function filesAdapter(paths: string[]): SourceAdapter;
+/**
+ * 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 declare function lintSource(adapter: SourceAdapter, options?: LintOptions): Promise<FileReport[]>;

package/file-runner.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sqlTextDefinitions = sqlTextDefinitions;
+exports.lintSqlText = lintSqlText;
+exports.resolveSqlFiles = resolveSqlFiles;
+exports.lintFiles = lintFiles;
+exports.sqlTextAdapter = sqlTextAdapter;
+exports.filesAdapter = filesAdapter;
+exports.lintSource = lintSource;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const pgsql_parser_1 = require("pgsql-parser");
+const engine_1 = require("./engine");
+const walk_1 = require("./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.
+ */
+async function sqlTextDefinitions(source, file) {
+    const parsed = (await (0, pgsql_parser_1.parse)(source));
+    const out = [];
+    for (const entry of parsed.stmts ?? []) {
+        const createFnStmt = entry.stmt ? (0, walk_1.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`.
+ */
+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 (0, engine_1.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_1.promises.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. */
+async function resolveSqlFiles(paths) {
+    const files = new Set();
+    for (const p of paths) {
+        const st = await fs_1.promises.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). */
+async function lintFiles(paths, options = {}) {
+    const files = await resolveSqlFiles(paths);
+    const reports = [];
+    for (const file of files) {
+        const source = await fs_1.promises.readFile(file, 'utf8');
+        const report = await lintSqlText(source, options);
+        reports.push({ ...report, file });
+    }
+    return reports;
+}
+/** A {@link SourceAdapter} over an in-memory SQL string. */
+function sqlTextAdapter(source, file) {
+    return { id: 'sql-text', definitions: () => sqlTextDefinitions(source, file) };
+}
+/** A {@link SourceAdapter} over `.sql` files/directories on disk. */
+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_1.promises.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.
+ */
+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/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@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 type { LintOptions } from './engine';
+export { lintDefinition, severityOf } from './engine';
+export { FileFinding, FileReport, filesAdapter, lintFiles, lintSource, lintSqlText, resolveSqlFiles, sqlTextAdapter, sqlTextDefinitions } from './file-runner';
+export type { CallOptions, Linter, LinterConfig } from './linter';
+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 type { DynamicSqlSite, LintDefinitionInput, LintProblem, LintResult, LintRule, LintRuleMeta, LintUnit, Severity, SeverityMap, SourceAdapter, SqlFragment, SuppressedProblem, SuppressionScope } from './types';
+export { defineRule } from './types';

package/index.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * `@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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineRule = exports.Suppressions = exports.DEFAULT_KEYWORDS = exports.requireQualifiedRefs = exports.noVariableConflict = exports.noSetSearchPath = exports.noDynamicSql = exports.LINT_RULES_BY_ID = exports.LINT_RULES_BY_CODE = exports.LINT_RULES = exports.parseUnit = exports.createLinter = exports.sqlTextDefinitions = exports.sqlTextAdapter = exports.resolveSqlFiles = exports.lintSqlText = exports.lintSource = exports.lintFiles = exports.filesAdapter = exports.severityOf = exports.lintDefinition = void 0;
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "lintDefinition", { enumerable: true, get: function () { return engine_1.lintDefinition; } });
+Object.defineProperty(exports, "severityOf", { enumerable: true, get: function () { return engine_1.severityOf; } });
+var file_runner_1 = require("./file-runner");
+Object.defineProperty(exports, "filesAdapter", { enumerable: true, get: function () { return file_runner_1.filesAdapter; } });
+Object.defineProperty(exports, "lintFiles", { enumerable: true, get: function () { return file_runner_1.lintFiles; } });
+Object.defineProperty(exports, "lintSource", { enumerable: true, get: function () { return file_runner_1.lintSource; } });
+Object.defineProperty(exports, "lintSqlText", { enumerable: true, get: function () { return file_runner_1.lintSqlText; } });
+Object.defineProperty(exports, "resolveSqlFiles", { enumerable: true, get: function () { return file_runner_1.resolveSqlFiles; } });
+Object.defineProperty(exports, "sqlTextAdapter", { enumerable: true, get: function () { return file_runner_1.sqlTextAdapter; } });
+Object.defineProperty(exports, "sqlTextDefinitions", { enumerable: true, get: function () { return file_runner_1.sqlTextDefinitions; } });
+var linter_1 = require("./linter");
+Object.defineProperty(exports, "createLinter", { enumerable: true, get: function () { return linter_1.createLinter; } });
+var parse_unit_1 = require("./parse-unit");
+Object.defineProperty(exports, "parseUnit", { enumerable: true, get: function () { return parse_unit_1.parseUnit; } });
+var rules_1 = require("./rules");
+Object.defineProperty(exports, "LINT_RULES", { enumerable: true, get: function () { return rules_1.LINT_RULES; } });
+Object.defineProperty(exports, "LINT_RULES_BY_CODE", { enumerable: true, get: function () { return rules_1.LINT_RULES_BY_CODE; } });
+Object.defineProperty(exports, "LINT_RULES_BY_ID", { enumerable: true, get: function () { return rules_1.LINT_RULES_BY_ID; } });
+Object.defineProperty(exports, "noDynamicSql", { enumerable: true, get: function () { return rules_1.noDynamicSql; } });
+Object.defineProperty(exports, "noSetSearchPath", { enumerable: true, get: function () { return rules_1.noSetSearchPath; } });
+Object.defineProperty(exports, "noVariableConflict", { enumerable: true, get: function () { return rules_1.noVariableConflict; } });
+Object.defineProperty(exports, "requireQualifiedRefs", { enumerable: true, get: function () { return rules_1.requireQualifiedRefs; } });
+var suppressions_1 = require("./suppressions");
+Object.defineProperty(exports, "DEFAULT_KEYWORDS", { enumerable: true, get: function () { return suppressions_1.DEFAULT_KEYWORDS; } });
+Object.defineProperty(exports, "Suppressions", { enumerable: true, get: function () { return suppressions_1.Suppressions; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "defineRule", { enumerable: true, get: function () { return types_1.defineRule; } });

package/linter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `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 { LintOptions } from './engine';
+import { FileReport, filesAdapter, sqlTextAdapter } from './file-runner';
+import type { LintResult, LintRule, SeverityMap, SourceAdapter } from './types';
+/** Configuration for a {@link Linter}. */
+export interface LinterConfig {
+    /** The rule set. Defaults to the built-in C1–C4. */
+    rules?: LintRule[];
+    /** Per-rule severity, keyed by id or code. Unmapped rules default to `error`. */
+    severity?: SeverityMap;
+    /** Suppression directive keyword(s). Defaults to `['pgsql-lint', 'safegres']`. */
+    keyword?: string | string[];
+}
+/** Narrow a single call to a subset of the linter's rules. */
+export type CallOptions = Pick<LintOptions, 'rules'>;
+/**
+ * A linter bound to a rule set, severities, and keyword. Build one with your
+ * own rules and point it at definitions, SQL text, files, or a custom adapter.
+ *
+ * @example
+ * const linter = createLinter({
+ *   rules: [...LINT_RULES, noWritesInView],
+ *   severity: { 'require-qualified-refs': 'warn', C2: 'off' }
+ * });
+ * await linter.lintFiles(['./migrations']);
+ */
+export interface Linter {
+    readonly rules: LintRule[];
+    readonly severity: SeverityMap;
+    readonly keyword: string | string[];
+    /** Lint one function definition (e.g. from `pg_get_functiondef`). */
+    lintDefinition: (text: string, language: string, name?: string, options?: CallOptions) => Promise<LintResult>;
+    /** Lint a SQL source string containing any number of statements. */
+    lintSqlText: (source: string, options?: CallOptions) => Promise<FileReport>;
+    /** Lint every `.sql` file reachable from `paths` (files or directories). */
+    lintFiles: (paths: string[], options?: CallOptions) => Promise<FileReport[]>;
+    /** Lint every definition a {@link SourceAdapter} yields. */
+    lintSource: (adapter: SourceAdapter, options?: CallOptions) => Promise<FileReport[]>;
+}
+/** Build a {@link Linter} bound to a rule set, severities, and keyword. */
+export declare function createLinter(config?: LinterConfig): Linter;
+export { filesAdapter, sqlTextAdapter };

package/linter.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sqlTextAdapter = exports.filesAdapter = void 0;
+exports.createLinter = createLinter;
+const engine_1 = require("./engine");
+const file_runner_1 = require("./file-runner");
+Object.defineProperty(exports, "filesAdapter", { enumerable: true, get: function () { return file_runner_1.filesAdapter; } });
+Object.defineProperty(exports, "sqlTextAdapter", { enumerable: true, get: function () { return file_runner_1.sqlTextAdapter; } });
+const rules_1 = require("./rules");
+const suppressions_1 = require("./suppressions");
+/** Build a {@link Linter} bound to a rule set, severities, and keyword. */
+function createLinter(config = {}) {
+    const rules = config.rules ?? rules_1.LINT_RULES;
+    const severity = config.severity ?? {};
+    const keyword = config.keyword ?? suppressions_1.DEFAULT_KEYWORDS;
+    const bind = (options = {}) => ({
+        ruleSet: rules,
+        severity,
+        keyword,
+        rules: options.rules
+    });
+    return {
+        rules,
+        severity,
+        keyword,
+        lintDefinition: (text, language, name, options) => (0, engine_1.lintDefinition)(text, language, name, bind(options)),
+        lintSqlText: (source, options) => (0, file_runner_1.lintSqlText)(source, bind(options)),
+        lintFiles: (paths, options) => (0, file_runner_1.lintFiles)(paths, bind(options)),
+        lintSource: (adapter, options) => (0, file_runner_1.lintSource)(adapter, bind(options))
+    };
+}