@pgsql/lint 18.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Dan Lynch <pyramation@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# @pgsql/lint
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/pgsql-parser/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/pgsql-parser/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/pgsql-parser/blob/main/LICENSE-MIT"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@pgsql/lint"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/pgsql-parser?filename=packages%2Flint%2Fpackage.json"/></a>
+</p>
+
+A source-level SQL / PL/pgSQL **convention linter**. It reasons about the *text*
+of a `CREATE FUNCTION` definition — from its AST — and carries **no `pg` /
+catalog dependency**, so the exact same engine runs over a definition in a
+migration, an editor buffer, a pre-commit hook, or one read from a live catalog
+via `pg_get_functiondef`.
+
+## Installation
+
+```bash
+npm install @pgsql/lint
+```
+
+## Rules
+
+| Code | Id | Flags |
+|------|----|-------|
+| `C1` | `no-set-search-path` | `SET search_path` clause, or `set_config('search_path', …)` |
+| `C2` | `no-variable-conflict` | a PL/pgSQL `#variable_conflict` directive |
+| `C3` | `require-qualified-refs` | an unqualified relation reference (`FROM users` → `FROM app_public.users`) |
+| `C4` | `no-dynamic-sql` | `EXECUTE`, `EXECUTE … USING`, `FOR … IN EXECUTE` |
+
+The rules encode a single discipline: never depend on `search_path` — fully
+qualify everything (`C1` + `C3`) — don't paper over ambiguity (`C2`), and treat
+dynamic SQL as opaque and exceptional (`C4`).
+
+## CLI
+
+```bash
+pgsql-lint path/to/migrations           # a directory (scanned recursively for .sql)
+pgsql-lint schema.sql other.sql         # explicit files
+pgsql-lint . --rules no-dynamic-sql     # only some rules
+pgsql-lint . --warn require-qualified-refs   # downgrade to a warning (won't fail)
+pgsql-lint . --off C2                        # disable a rule (by id or code)
+pgsql-lint . --json                     # machine-readable
+```
+
+Exit code is `1` when any **error**-severity (and non-waived) finding remains,
+`0` otherwise — drop it straight into CI. `--warn` findings print but don't fail.
+
+## Suppressions
+
+ESLint / Prettier-style comments, authored in the function body (they survive
+`pg_get_functiondef`). The keyword is `pgsql-lint` (`safegres` is also accepted):
+
+```sql
+-- pgsql-lint-disable-next-line no-dynamic-sql -- lookup-only: building an IN-list of ints
+EXECUTE format('SELECT … WHERE id = ANY(%L)', ids);
+```
+
+Forms: `disable-next-line`, `disable-line`, `disable` … `enable` (a range), and
+`disable-file`. A directive with no rule listed applies to every rule; a reason
+follows a second `--` or a `:`.
+
+`no-dynamic-sql` **requires** a reason: a reasonless waiver does not silence it,
+so an approved use always documents *why* (`lookup-only` / `codegen`). Suppressed
+findings are reported as *acknowledged* accepted-risk, never dropped.
+
+## Programmatic API
+
+```ts
+import { lintDefinition, lintFiles, lintSqlText } from '@pgsql/lint';
+
+// one definition (e.g. from pg_get_functiondef)
+const { problems, suppressed } = await lintDefinition(defText, 'plpgsql');
+
+// a SQL source string with many statements
+const report = await lintSqlText(migrationSql);
+
+// files / directories on disk
+const reports = await lintFiles(['./migrations']);
+```
+
+## Custom rules & severity (building an ecosystem)
+
+Rules are **injected as values** — never discovered by a magic npm package name.
+A rule is a plain object; publish it, `import` it, and pass it to `createLinter`.
+Severity is *configuration* (ESLint-style `off` / `warn` / `error`), keyed by
+rule id or code, so a consumer stays in full control of how loud each rule is:
+
+```ts
+import { createLinter, defineRule, LINT_RULES } from '@pgsql/lint';
+
+const noWritesInView = defineRule({
+  id: 'no-writes-in-view',
+  code: 'X1',
+  title: 'views must be read-only',
+  reasonRequired: false,
+  run: (unit) => [/* … inspect unit.fragments / unit.dynamicSql … */]
+});
+
+const linter = createLinter({
+  rules: [...LINT_RULES, noWritesInView],
+  severity: { 'require-qualified-refs': 'warn', C2: 'off' }
+});
+
+await linter.lintFiles(['./migrations']);   // also lintDefinition / lintSqlText / lintSource
+```
+
+### Source adapters
+
+Rules are pure `unit → problems`; an **adapter** decides *where* the definitions
+come from. `@pgsql/lint` ships `filesAdapter` and `sqlTextAdapter`; a consumer
+(e.g. safegres, reading a live catalog via `pg_get_functiondef`) implements the
+`SourceAdapter` interface and passes it to `linter.lintSource(adapter)`.
+
+```ts
+interface SourceAdapter {
+  id: string;
+  definitions: () => Promise<LintDefinitionInput[]> | LintDefinitionInput[];
+}
+```
+
+---
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Related
+
+* [pgpm](https://pgpm.dev): A Postgres Package Manager that brings modular development to PostgreSQL with reusable packages, deterministic migrations, recursive dependency resolution, and tag-aware versioning.
+* [pgsql-test](https://www.npmjs.com/package/pgsql-test): Instant, isolated PostgreSQL databases for each test with automatic transaction rollbacks, context switching, and clean seeding for fast, reliable database testing.
+* [pgsql-seed](https://www.npmjs.com/package/pgsql-seed): PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
+* [pgsql-deparser](https://www.npmjs.com/package/pgsql-deparser): A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement `pgsql-parser`.
+* [@pgsql/parser](https://www.npmjs.com/package/@pgsql/parser): Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): A comprehensive utility library for PostgreSQL, offering type-safe AST node creation and enum value conversions, simplifying the construction and manipulation of PostgreSQL ASTs.
+* [@pgsql/traverse](https://www.npmjs.com/package/@pgsql/traverse): PostgreSQL AST traversal utilities for pgsql-parser, providing a visitor pattern for traversing PostgreSQL Abstract Syntax Tree nodes, similar to Babel's traverse functionality but specifically designed for PostgreSQL AST structures.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [libpg-query](https://github.com/constructive-io/libpg-query-node): The real PostgreSQL parser exposed for Node.js, used primarily in `pgsql-parser` for parsing and deparsing SQL queries.
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating Software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Software code or Software CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * `pgsql-lint` — lint SQL source files for the convention rules.
+ *
+ *   pgsql-lint <path…> [--rules a,b] [--warn a,b] [--off a,b] [--json] [--quiet]
+ *
+ * Paths may be files or directories (directories are scanned recursively for
+ * `.sql`). Exit code is 1 when any *error*-severity finding remains, 0
+ * otherwise — so it drops straight into a pre-commit hook or CI step. Findings
+ * downgraded with `--warn` print but never fail the run.
+ */
+export {};

package/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `pgsql-lint` — lint SQL source files for the convention rules.
+ *
+ *   pgsql-lint <path…> [--rules a,b] [--warn a,b] [--off a,b] [--json] [--quiet]
+ *
+ * Paths may be files or directories (directories are scanned recursively for
+ * `.sql`). Exit code is 1 when any *error*-severity finding remains, 0
+ * otherwise — so it drops straight into a pre-commit hook or CI step. Findings
+ * downgraded with `--warn` print but never fail the run.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chalk_1 = __importDefault(require("chalk"));
+const minimist_1 = __importDefault(require("minimist"));
+const file_runner_1 = require("./file-runner");
+const rules_1 = require("./rules");
+const HELP = `pgsql-lint — source-level SQL/PL/pgSQL convention linter
+
+Usage:
+  pgsql-lint <path...> [options]
+
+Arguments:
+  path                 One or more .sql files or directories (scanned recursively).
+
+Options:
+  --rules <ids>        Comma-separated rule ids/codes to run (default: all).
+  --warn <ids>         Report these rules as warnings (do not fail the run).
+  --off <ids>          Disable these rules entirely.
+  --keyword <kw>       Suppression directive keyword (default: pgsql-lint,safegres).
+  --json               Emit findings as JSON.
+  --quiet              Only print active findings (hide acknowledged waivers).
+  -h, --help           Show this help.
+  -v, --version        Show version.
+
+Rules:
+${rules_1.LINT_RULES.map((r) => `  ${r.code}  ${r.id}  —  ${r.title}`).join('\n')}
+
+Suppress inline (in the function body):
+  -- pgsql-lint-disable-next-line no-dynamic-sql -- lookup-only: <why>
+`;
+function csv(v) {
+    if (!v)
+        return undefined;
+    const parts = v.split(',').map((s) => s.trim()).filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+}
+async function main() {
+    const argv = (0, minimist_1.default)(process.argv.slice(2), {
+        boolean: ['json', 'quiet', 'help', 'version'],
+        string: ['rules', 'warn', 'off', 'keyword'],
+        alias: { h: 'help', v: 'version' }
+    });
+    if (argv.version) {
+        console.log(require('../package.json').version);
+        return;
+    }
+    if (argv.help || argv._.length === 0) {
+        console.log(HELP);
+        process.exit(argv._.length === 0 && !argv.help ? 1 : 0);
+    }
+    const rules = csv(argv.rules);
+    const keyword = csv(argv.keyword);
+    const severity = {};
+    for (const id of csv(argv.warn) ?? [])
+        severity[id] = 'warn';
+    for (const id of csv(argv.off) ?? [])
+        severity[id] = 'off';
+    const reports = await (0, file_runner_1.lintFiles)(argv._, { rules, keyword, severity });
+    if (argv.json) {
+        console.log(JSON.stringify(reports, null, 2));
+    }
+    let errors = 0;
+    let warnings = 0;
+    let acknowledged = 0;
+    for (const report of reports) {
+        if (report.parseError) {
+            if (!argv.json)
+                console.error(chalk_1.default.yellow(`⚠ ${report.file}: ${report.parseError}`));
+            continue;
+        }
+        const shown = report.findings.filter((f) => !f.acknowledged || !argv.quiet);
+        if (!argv.json && shown.length > 0) {
+            console.log(chalk_1.default.underline(report.file));
+            for (const f of shown)
+                console.log(formatFinding(f));
+            console.log('');
+        }
+        for (const f of report.findings) {
+            if (f.acknowledged)
+                acknowledged++;
+            else if (f.severity === 'warn')
+                warnings++;
+            else
+                errors++;
+        }
+    }
+    if (!argv.json) {
+        const parts = [];
+        parts.push(errors > 0 ? chalk_1.default.red(`${errors} error${errors === 1 ? '' : 's'}`) : chalk_1.default.green('0 errors'));
+        if (warnings > 0)
+            parts.push(chalk_1.default.yellow(`${warnings} warning${warnings === 1 ? '' : 's'}`));
+        if (acknowledged > 0)
+            parts.push(chalk_1.default.gray(`${acknowledged} acknowledged`));
+        console.log(parts.join(chalk_1.default.gray(', ')));
+    }
+    process.exit(errors > 0 ? 1 : 0);
+}
+function formatFinding(f) {
+    const loc = chalk_1.default.gray(`${String(f.line).padStart(4)}`);
+    const tag = f.acknowledged
+        ? chalk_1.default.gray('acknowledged')
+        : f.severity === 'warn'
+            ? chalk_1.default.yellow(`${f.code} warn`)
+            : chalk_1.default.red(`${f.code} error`);
+    const id = chalk_1.default.gray(f.ruleId);
+    let line = `  ${loc}  ${tag}  ${f.message}  ${id}  ${chalk_1.default.gray(f.subject)}`;
+    if (f.acknowledged && f.reason)
+        line += `\n        ${chalk_1.default.gray(`↳ waived (${f.scope}): ${f.reason}`)}`;
+    else if (f.hint)
+        line += `\n        ${chalk_1.default.gray(`↳ ${f.hint}`)}`;
+    return line;
+}
+main().catch((err) => {
+    console.error(chalk_1.default.red('Error:'), err.message || err);
+    process.exit(2);
+});

package/engine.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The lint engine: parse a definition, run the rules, then apply suppressions.
+ * Pure `source → result`, with no `pg` dependency, so it can be unit-tested on
+ * string literals and embedded anywhere.
+ *
+ * Rules and their severities are *injected*, never discovered by name: you pass
+ * the rule objects in (see `createLinter`), so a third-party rule ships as an
+ * ordinary import, not a magic `pgsql-lint-plugin-*` package.
+ */
+import type { LintResult, LintRule, Severity, SeverityMap } from './types';
+export interface LintOptions {
+    /** Restrict to these rule ids/codes; omit to run every rule in the set. */
+    rules?: string[];
+    /**
+     * The rule set to draw from. Defaults to the built-ins. Pass your own array
+     * (built-ins spread in plus custom rules) to extend the linter.
+     */
+    ruleSet?: LintRule[];
+    /** Per-rule severity, keyed by id or code. Unmapped rules default to `error`. */
+    severity?: SeverityMap;
+    /**
+     * Directive keyword(s) recognised in suppression comments. Defaults to
+     * `['pgsql-lint', 'safegres']`.
+     */
+    keyword?: string | string[];
+}
+/** Resolve a rule's configured severity (id wins over code; default `error`). */
+export declare function severityOf(rule: LintRule, severity?: SeverityMap): Severity;
+/** Lint a single function definition. */
+export declare function lintDefinition(text: string, language: string, name?: string, options?: LintOptions): Promise<LintResult>;

package/engine.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * The lint engine: parse a definition, run the rules, then apply suppressions.
+ * Pure `source → result`, with no `pg` dependency, so it can be unit-tested on
+ * string literals and embedded anywhere.
+ *
+ * Rules and their severities are *injected*, never discovered by name: you pass
+ * the rule objects in (see `createLinter`), so a third-party rule ships as an
+ * ordinary import, not a magic `pgsql-lint-plugin-*` package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.severityOf = severityOf;
+exports.lintDefinition = lintDefinition;
+const parse_unit_1 = require("./parse-unit");
+const rules_1 = require("./rules");
+const suppressions_1 = require("./suppressions");
+/** Resolve a rule's configured severity (id wins over code; default `error`). */
+function severityOf(rule, severity = {}) {
+    return severity[rule.id] ?? severity[rule.code] ?? 'error';
+}
+/** Lint a single function definition. */
+async function lintDefinition(text, language, name, options = {}) {
+    const active = [];
+    const suppressed = [];
+    const severity = options.severity ?? {};
+    let selected = options.ruleSet ?? rules_1.LINT_RULES;
+    if (options.rules) {
+        const wanted = new Set(options.rules);
+        selected = selected.filter((r) => wanted.has(r.id) || wanted.has(r.code));
+    }
+    // `off` rules never run.
+    selected = selected.filter((r) => severityOf(r, severity) !== 'off');
+    if (selected.length === 0)
+        return { problems: active, suppressed };
+    const unit = await (0, parse_unit_1.parseUnit)(text, language, name);
+    // An unparseable definition produces no lint findings — dynamic/opaque bodies
+    // are a downstream concern (e.g. a call-graph), not the linter's.
+    if (unit.parseError)
+        return { problems: active, suppressed };
+    const keywords = options.keyword
+        ? (Array.isArray(options.keyword) ? options.keyword : [options.keyword])
+        : suppressions_1.DEFAULT_KEYWORDS;
+    const suppressions = new suppressions_1.Suppressions(unit.lines, keywords);
+    for (const rule of selected) {
+        const sev = severityOf(rule, severity);
+        for (const problem of rule.run(unit)) {
+            const p = { ...problem, severity: sev };
+            const res = suppressions.resolve(p.ruleId, p.line, rule.reasonRequired);
+            if (res.suppressed) {
+                suppressed.push({ ...p, reason: res.reason ?? null, scope: res.scope });
+                continue;
+            }
+            if (res.invalidMissingReason) {
+                active.push({
+                    ...p,
+                    message: `${p.message} (suppression ignored: a reason is required)`,
+                    context: { ...p.context, invalidSuppression: 'missing-reason' }
+                });
+                continue;
+            }
+            active.push(p);
+        }
+    }
+    active.sort((a, b) => a.line - b.line || a.ruleId.localeCompare(b.ruleId));
+    return { problems: active, suppressed };
+}

package/esm/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * `pgsql-lint` — lint SQL source files for the convention rules.
+ *
+ *   pgsql-lint <path…> [--rules a,b] [--warn a,b] [--off a,b] [--json] [--quiet]
+ *
+ * Paths may be files or directories (directories are scanned recursively for
+ * `.sql`). Exit code is 1 when any *error*-severity finding remains, 0
+ * otherwise — so it drops straight into a pre-commit hook or CI step. Findings
+ * downgraded with `--warn` print but never fail the run.
+ */
+import chalk from 'chalk';
+import minimist from 'minimist';
+import { lintFiles } from './file-runner';
+import { LINT_RULES } from './rules';
+const HELP = `pgsql-lint — source-level SQL/PL/pgSQL convention linter
+
+Usage:
+  pgsql-lint <path...> [options]
+
+Arguments:
+  path                 One or more .sql files or directories (scanned recursively).
+
+Options:
+  --rules <ids>        Comma-separated rule ids/codes to run (default: all).
+  --warn <ids>         Report these rules as warnings (do not fail the run).
+  --off <ids>          Disable these rules entirely.
+  --keyword <kw>       Suppression directive keyword (default: pgsql-lint,safegres).
+  --json               Emit findings as JSON.
+  --quiet              Only print active findings (hide acknowledged waivers).
+  -h, --help           Show this help.
+  -v, --version        Show version.
+
+Rules:
+${LINT_RULES.map((r) => `  ${r.code}  ${r.id}  —  ${r.title}`).join('\n')}
+
+Suppress inline (in the function body):
+  -- pgsql-lint-disable-next-line no-dynamic-sql -- lookup-only: <why>
+`;
+function csv(v) {
+    if (!v)
+        return undefined;
+    const parts = v.split(',').map((s) => s.trim()).filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+}
+async function main() {
+    const argv = minimist(process.argv.slice(2), {
+        boolean: ['json', 'quiet', 'help', 'version'],
+        string: ['rules', 'warn', 'off', 'keyword'],
+        alias: { h: 'help', v: 'version' }
+    });
+    if (argv.version) {
+        console.log(require('../package.json').version);
+        return;
+    }
+    if (argv.help || argv._.length === 0) {
+        console.log(HELP);
+        process.exit(argv._.length === 0 && !argv.help ? 1 : 0);
+    }
+    const rules = csv(argv.rules);
+    const keyword = csv(argv.keyword);
+    const severity = {};
+    for (const id of csv(argv.warn) ?? [])
+        severity[id] = 'warn';
+    for (const id of csv(argv.off) ?? [])
+        severity[id] = 'off';
+    const reports = await lintFiles(argv._, { rules, keyword, severity });
+    if (argv.json) {
+        console.log(JSON.stringify(reports, null, 2));
+    }
+    let errors = 0;
+    let warnings = 0;
+    let acknowledged = 0;
+    for (const report of reports) {
+        if (report.parseError) {
+            if (!argv.json)
+                console.error(chalk.yellow(`⚠ ${report.file}: ${report.parseError}`));
+            continue;
+        }
+        const shown = report.findings.filter((f) => !f.acknowledged || !argv.quiet);
+        if (!argv.json && shown.length > 0) {
+            console.log(chalk.underline(report.file));
+            for (const f of shown)
+                console.log(formatFinding(f));
+            console.log('');
+        }
+        for (const f of report.findings) {
+            if (f.acknowledged)
+                acknowledged++;
+            else if (f.severity === 'warn')
+                warnings++;
+            else
+                errors++;
+        }
+    }
+    if (!argv.json) {
+        const parts = [];
+        parts.push(errors > 0 ? chalk.red(`${errors} error${errors === 1 ? '' : 's'}`) : chalk.green('0 errors'));
+        if (warnings > 0)
+            parts.push(chalk.yellow(`${warnings} warning${warnings === 1 ? '' : 's'}`));
+        if (acknowledged > 0)
+            parts.push(chalk.gray(`${acknowledged} acknowledged`));
+        console.log(parts.join(chalk.gray(', ')));
+    }
+    process.exit(errors > 0 ? 1 : 0);
+}
+function formatFinding(f) {
+    const loc = chalk.gray(`${String(f.line).padStart(4)}`);
+    const tag = f.acknowledged
+        ? chalk.gray('acknowledged')
+        : f.severity === 'warn'
+            ? chalk.yellow(`${f.code} warn`)
+            : chalk.red(`${f.code} error`);
+    const id = chalk.gray(f.ruleId);
+    let line = `  ${loc}  ${tag}  ${f.message}  ${id}  ${chalk.gray(f.subject)}`;
+    if (f.acknowledged && f.reason)
+        line += `\n        ${chalk.gray(`↳ waived (${f.scope}): ${f.reason}`)}`;
+    else if (f.hint)
+        line += `\n        ${chalk.gray(`↳ ${f.hint}`)}`;
+    return line;
+}
+main().catch((err) => {
+    console.error(chalk.red('Error:'), err.message || err);
+    process.exit(2);
+});

package/esm/engine.js

@@ -0,0 +1,62 @@
+/**
+ * The lint engine: parse a definition, run the rules, then apply suppressions.
+ * Pure `source → result`, with no `pg` dependency, so it can be unit-tested on
+ * string literals and embedded anywhere.
+ *
+ * Rules and their severities are *injected*, never discovered by name: you pass
+ * the rule objects in (see `createLinter`), so a third-party rule ships as an
+ * ordinary import, not a magic `pgsql-lint-plugin-*` package.
+ */
+import { parseUnit } from './parse-unit';
+import { LINT_RULES } from './rules';
+import { DEFAULT_KEYWORDS, Suppressions } from './suppressions';
+/** Resolve a rule's configured severity (id wins over code; default `error`). */
+export function severityOf(rule, severity = {}) {
+    return severity[rule.id] ?? severity[rule.code] ?? 'error';
+}
+/** Lint a single function definition. */
+export async function lintDefinition(text, language, name, options = {}) {
+    const active = [];
+    const suppressed = [];
+    const severity = options.severity ?? {};
+    let selected = options.ruleSet ?? LINT_RULES;
+    if (options.rules) {
+        const wanted = new Set(options.rules);
+        selected = selected.filter((r) => wanted.has(r.id) || wanted.has(r.code));
+    }
+    // `off` rules never run.
+    selected = selected.filter((r) => severityOf(r, severity) !== 'off');
+    if (selected.length === 0)
+        return { problems: active, suppressed };
+    const unit = await parseUnit(text, language, name);
+    // An unparseable definition produces no lint findings — dynamic/opaque bodies
+    // are a downstream concern (e.g. a call-graph), not the linter's.
+    if (unit.parseError)
+        return { problems: active, suppressed };
+    const keywords = options.keyword
+        ? (Array.isArray(options.keyword) ? options.keyword : [options.keyword])
+        : DEFAULT_KEYWORDS;
+    const suppressions = new Suppressions(unit.lines, keywords);
+    for (const rule of selected) {
+        const sev = severityOf(rule, severity);
+        for (const problem of rule.run(unit)) {
+            const p = { ...problem, severity: sev };
+            const res = suppressions.resolve(p.ruleId, p.line, rule.reasonRequired);
+            if (res.suppressed) {
+                suppressed.push({ ...p, reason: res.reason ?? null, scope: res.scope });
+                continue;
+            }
+            if (res.invalidMissingReason) {
+                active.push({
+                    ...p,
+                    message: `${p.message} (suppression ignored: a reason is required)`,
+                    context: { ...p.context, invalidSuppression: 'missing-reason' }
+                });
+                continue;
+            }
+            active.push(p);
+        }
+    }
+    active.sort((a, b) => a.line - b.line || a.ruleId.localeCompare(b.ruleId));
+    return { problems: active, suppressed };
+}