@pgsql/lint 18.1.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pgsql/lint",
+  "version": "18.1.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Source-level SQL/PL/pgSQL convention linter: fully-qualified references, no search_path, no dynamic SQL, with ESLint-style inline waivers. Pure AST, no database.",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/pgsql-parser/tree/main/packages/lint#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/pgsql-parser"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/pgsql-parser/issues"
+  },
+  "bin": {
+    "pgsql-lint": "cli.js"
+  },
+  "scripts": {
+    "copy": "makage assets",
+    "clean": "makage clean dist",
+    "prepublishOnly": "npm run build",
+    "build": "npm run clean && tsc && tsc -p tsconfig.esm.json && npm run copy",
+    "build:dev": "npm run clean && tsc --declarationMap && tsc -p tsconfig.esm.json && npm run copy",
+    "dev": "ts-node src/cli",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@pgsql/traverse": "18.7.1",
+    "chalk": "^4.1.0",
+    "libpg-query": "18.1.2",
+    "minimist": "1.2.8",
+    "pgsql-parser": "18.2.1"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.5",
+    "makage": "^0.1.8"
+  },
+  "keywords": [
+    "sql",
+    "postgres",
+    "postgresql",
+    "pg",
+    "ast",
+    "lint",
+    "linter",
+    "plpgsql",
+    "search_path",
+    "dynamic-sql"
+  ],
+  "gitHead": "a437944187066a60705bcf11fda60bc457fa14e5"
+}

package/parse-unit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 type { LintUnit } from './types';
+/**
+ * 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 declare function parseUnit(text: string, language: string, name?: string): Promise<LintUnit>;

package/parse-unit.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUnit = parseUnit;
+const libpg_query_1 = require("libpg-query");
+const pgsql_parser_1 = require("pgsql-parser");
+const walk_1 = require("./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.
+ */
+async function parseUnit(text, language, name) {
+    const lines = text.split('\n');
+    const base = { text, lines, language, name, fragments: [], dynamicSql: [] };
+    let sqlAst;
+    try {
+        sqlAst = await (0, pgsql_parser_1.parse)(text);
+    }
+    catch (err) {
+        return { ...base, parseError: `definition failed to parse: ${err.message}` };
+    }
+    const createFnStmt = (0, walk_1.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 (0, pgsql_parser_1.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 (0, libpg_query_1.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 (0, pgsql_parser_1.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/rules/index.d.ts

@@ -0,0 +1,10 @@
+import type { LintRule } from '../types';
+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 declare const LINT_RULES: LintRule[];
+export declare const LINT_RULES_BY_ID: Map<string, LintRule>;
+export declare const LINT_RULES_BY_CODE: Map<string, LintRule>;
+export { noDynamicSql, noSetSearchPath, noVariableConflict, requireQualifiedRefs };

package/rules/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireQualifiedRefs = exports.noVariableConflict = exports.noSetSearchPath = exports.noDynamicSql = exports.LINT_RULES_BY_CODE = exports.LINT_RULES_BY_ID = exports.LINT_RULES = void 0;
+const no_dynamic_sql_1 = require("./no-dynamic-sql");
+Object.defineProperty(exports, "noDynamicSql", { enumerable: true, get: function () { return no_dynamic_sql_1.noDynamicSql; } });
+const no_set_search_path_1 = require("./no-set-search-path");
+Object.defineProperty(exports, "noSetSearchPath", { enumerable: true, get: function () { return no_set_search_path_1.noSetSearchPath; } });
+const no_variable_conflict_1 = require("./no-variable-conflict");
+Object.defineProperty(exports, "noVariableConflict", { enumerable: true, get: function () { return no_variable_conflict_1.noVariableConflict; } });
+const require_qualified_refs_1 = require("./require-qualified-refs");
+Object.defineProperty(exports, "requireQualifiedRefs", { enumerable: true, get: function () { return require_qualified_refs_1.requireQualifiedRefs; } });
+/** The lint rules, in report order. */
+exports.LINT_RULES = [
+    no_set_search_path_1.noSetSearchPath,
+    require_qualified_refs_1.requireQualifiedRefs,
+    no_variable_conflict_1.noVariableConflict,
+    no_dynamic_sql_1.noDynamicSql
+];
+exports.LINT_RULES_BY_ID = new Map(exports.LINT_RULES.map((r) => [r.id, r]));
+exports.LINT_RULES_BY_CODE = new Map(exports.LINT_RULES.map((r) => [r.code, r]));

package/rules/no-dynamic-sql.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `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`).
+ */
+import type { LintRule } from '../types';
+export declare const noDynamicSql: LintRule;

package/rules/no-dynamic-sql.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * `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`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noDynamicSql = void 0;
+exports.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/rules/no-set-search-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `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 type { LintRule } from '../types';
+export declare const noSetSearchPath: LintRule;

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

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noSetSearchPath = void 0;
+const util_1 = require("../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: (0, util_1.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;
+}
+exports.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/rules/no-variable-conflict.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `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.
+ */
+import type { LintRule } from '../types';
+export declare const noVariableConflict: LintRule;

package/rules/no-variable-conflict.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noVariableConflict = void 0;
+const RE = /^\s*#variable_conflict\b\s*(\S+)?/i;
+exports.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/rules/require-qualified-refs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `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 type { LintRule } from '../types';
+export declare const requireQualifiedRefs: LintRule;

package/rules/require-qualified-refs.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * `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()`, …).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireQualifiedRefs = void 0;
+const walk_1 = require("../walk");
+function cteNames(ast) {
+    const out = new Set();
+    for (const cte of (0, walk_1.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 (0, walk_1.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;
+}
+exports.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);
+    }
+};

package/suppressions.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+import type { SuppressionScope } from './types';
+/** The directive keyword(s) recognised when none is configured explicitly. */
+export declare const DEFAULT_KEYWORDS: string[];
+export interface SuppressionMatch {
+    scope: SuppressionScope;
+    reason: string | null;
+}
+export interface SuppressionResolution {
+    /** The directive silences the finding. */
+    suppressed: boolean;
+    scope?: SuppressionScope;
+    reason?: string | null;
+    /** A directive matched but lacked a required reason, so it does not apply. */
+    invalidMissingReason?: boolean;
+}
+/** Parsed suppression state for one definition, queryable by (rule, line). */
+export declare class Suppressions {
+    private readonly lineDirectives;
+    private readonly intervals;
+    private readonly fileDirectives;
+    constructor(lines: string[], keywords?: string[]);
+    private match;
+    /**
+     * Resolve whether a finding is suppressed. `reasonRequired` rules are only
+     * silenced by a directive that carries a reason.
+     */
+    resolve(ruleId: string, line: number, reasonRequired: boolean): SuppressionResolution;
+}