@pgsql/lint 18.1.0

package/suppressions.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Suppressions = exports.DEFAULT_KEYWORDS = void 0;
+/** The directive keyword(s) recognised when none is configured explicitly. */
+exports.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). */
+class Suppressions {
+    lineDirectives = [];
+    intervals = [];
+    fileDirectives = [];
+    constructor(lines, keywords = exports.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 };
+    }
+}
+exports.Suppressions = Suppressions;

package/types.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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.
+ */
+/** A parsed function definition, in the coordinate space the linter reports in. */
+export interface LintUnit {
+    /** The full definition text — the line/column space every finding refers to. */
+    text: string;
+    /** `text` split on `\n`, 1-based when indexed as `lines[line - 1]`. */
+    lines: string[];
+    /** `sql`, `plpgsql`, `c`, `internal`, … (lower-cased `pg_proc.prolang`). */
+    language: string;
+    /** Display name for messages, e.g. `app.grant_role(text)`. */
+    name?: string;
+    /** The `CreateFunctionStmt` AST node, when the text parsed as one. */
+    createFnStmt?: Record<string, unknown>;
+    /** Absolute line (1-based, within `text`) the function body's first char sits on. */
+    bodyStartLine?: number;
+    /** Embedded SQL fragments (body statements / expressions) with a line mapper. */
+    fragments: SqlFragment[];
+    /** Dynamic-SQL statements found in a PL/pgSQL body, by absolute line. */
+    dynamicSql: DynamicSqlSite[];
+    /** True when the definition (or its body) could not be parsed. */
+    parseError?: string;
+}
+/** One embedded SQL statement/expression, with a char-offset → absolute-line mapper. */
+export interface SqlFragment {
+    /** Parsed SQL AST for this fragment. */
+    ast: unknown;
+    /** Map a char offset within this fragment's source to an absolute line in `text`. */
+    lineForOffset: (offset: number) => number;
+}
+export interface DynamicSqlSite {
+    line: number;
+    /** `EXECUTE`, `EXECUTE … USING`, or `FOR … IN EXECUTE`. */
+    form: string;
+}
+/**
+ * How loud a rule is, per project. Severity is *configuration*, not a property
+ * of the rule (same model as ESLint): a rule declares only its identity, and
+ * the linter config decides `off` / `warn` / `error` per rule id or code.
+ *   - `off`   — the rule is not run.
+ *   - `warn`  — reported, but does not fail the run.
+ *   - `error` — reported and fails the run (drives a non-zero exit code).
+ */
+export type Severity = 'off' | 'warn' | 'error';
+/** A severity per rule, keyed by rule id (`no-dynamic-sql`) or code (`C4`). */
+export type SeverityMap = Record<string, Severity>;
+/** A single lint finding, before suppressions are applied. */
+export interface LintProblem {
+    ruleId: string;
+    /** Absolute line (1-based) within the definition. */
+    line: number;
+    message: string;
+    hint?: string;
+    /** Configured severity for the rule (`error` by default). */
+    severity?: Severity;
+    context?: Record<string, unknown>;
+}
+/** A problem that a suppression comment silenced — reported, never dropped. */
+export interface SuppressedProblem extends LintProblem {
+    /** The reason text from the directive, or null when none was given. */
+    reason: string | null;
+    scope: SuppressionScope;
+}
+export type SuppressionScope = 'next-line' | 'line' | 'range' | 'file';
+/** The result of linting one definition. */
+export interface LintResult {
+    /** Active findings — not suppressed. */
+    problems: LintProblem[];
+    /** Suppressed findings, kept for the "accepted risk" report bucket. */
+    suppressed: SuppressedProblem[];
+}
+/** Static metadata for a lint rule. */
+export interface LintRuleMeta {
+    /** ESLint-style stable id, e.g. `no-dynamic-sql`. */
+    id: string;
+    /** Registry code this rule maps to, e.g. `C4` (the `safegres:constructive` code). */
+    code: string;
+    title: string;
+    /**
+     * Whether a suppression of this rule must carry a reason. When true, a bare
+     * disable directive does not suppress — the finding stands — so a waiver is
+     * never silent. Only `no-dynamic-sql` requires it: it is the one rule we
+     * expect to be waived (lookup-only / codegen), and the waiver's whole value
+     * is the documented reason.
+     */
+    reasonRequired: boolean;
+}
+/** A lint rule: pure `unit → problems`. */
+export interface LintRule extends LintRuleMeta {
+    run: (unit: LintUnit) => LintProblem[];
+}
+/**
+ * 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 declare function defineRule(rule: LintRule): LintRule;
+/**
+ * A definition to lint, as produced by a {@link SourceAdapter}. This is the
+ * unit of work the engine consumes regardless of where it came from — a file,
+ * a live catalog (`pg_get_functiondef`), a git diff, an editor buffer.
+ */
+export interface LintDefinitionInput {
+    /** The full `CREATE FUNCTION …` text. */
+    text: string;
+    /** `sql`, `plpgsql`, … (lower-cased). */
+    language: string;
+    /** Display name for messages, e.g. `app.grant_role`. */
+    name?: string;
+    /** Origin file, when the definition came from disk. */
+    file?: string;
+    /**
+     * Absolute 0-based line the definition begins on within `file`. Findings
+     * are re-anchored by this so they point at the real file location.
+     */
+    startLine?: number;
+}
+/**
+ * A source of definitions to lint. Adapters are a *different* seam from rules:
+ * a rule is pure `unit → problems`, while an adapter decides *where* the
+ * definitions come from. `@pgsql/lint` ships file/source adapters; safegres is
+ * "the catalog adapter" over the same engine.
+ */
+export interface SourceAdapter {
+    /** A short id for diagnostics, e.g. `files`, `sql-text`, `catalog`. */
+    id: string;
+    /** Yield every definition this adapter can see. */
+    definitions: () => Promise<LintDefinitionInput[]> | LintDefinitionInput[];
+}

package/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineRule = defineRule;
+/**
+ * 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 []; }
+ * });
+ */
+function defineRule(rule) {
+    return rule;
+}

package/util.d.ts

@@ -0,0 +1,2 @@
+/** Absolute 1-based line of a char offset within `text`. */
+export declare function lineOfOffset(text: string, offset: number): number;

package/util.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineOfOffset = lineOfOffset;
+/** Absolute 1-based line of a char offset within `text`. */
+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/walk.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The one AST helper the rules need, layered on `@pgsql/traverse`'s `walk`.
+ */
+/** Find every node tagged with `tag` (e.g. `RangeVar`, `CommonTableExpr`). */
+export declare function findAll(root: unknown, tag: string): Record<string, unknown>[];

package/walk.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * The one AST helper the rules need, layered on `@pgsql/traverse`'s `walk`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAll = findAll;
+const traverse_1 = require("@pgsql/traverse");
+/** Find every node tagged with `tag` (e.g. `RangeVar`, `CommonTableExpr`). */
+function findAll(root, tag) {
+    const out = [];
+    (0, traverse_1.walk)(root, (path) => {
+        if (path.tag === tag) {
+            out.push(path.node);
+        }
+    });
+    return out;
+}