@pgsql/lint 18.1.1 → 18.2.0

package/README.md

@@ -46,11 +46,49 @@ 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
+pgsql-lint . --ignore 'sql/,**/generated/**' # exclude generated trees
+pgsql-lint --changed                    # only .sql that this branch touched
+pgsql-lint --changed origin/main        # …against an explicit base
 ```
 
 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.
 
+### Changed files only
+
+`--changed[=<base>]` lints just the `.sql` files a branch touched, so a CI gate
+costs a second instead of scanning the whole tree. The base defaults to the pull
+request's base branch (`$GITHUB_BASE_REF`) and otherwise to the repository's
+default branch; the diff is taken against `git merge-base HEAD <base>`, so
+commits landed on the base branch afterwards don't widen the set. Uncommitted and
+untracked changes are included, deleted/renamed-away paths are dropped, and a
+shallow clone or detached checkout (no resolvable merge base) falls back to the
+working-tree diff against `HEAD`. Nothing changed is an exit-0 pass.
+
+### Config file
+
+`.pgsqllintrc.json`, discovered by walking up from the working directory (or
+passed with `--config <file>`; `--no-config` skips discovery). The keys mirror the
+flags, and any flag overrides the file:
+
+```json
+{
+  "extends": "./ci/lint-base.json",
+  "paths": ["packages", "application/app"],
+  "ignore": ["sql/", "application/constructive/", "**/generated/**"],
+  "warn": ["require-qualified-refs"],
+  "off": ["C2"]
+}
+```
+
+`paths` supplies the default targets when none are given on the command line, so
+`pgsql-lint` and `pgsql-lint --changed` need no arguments. `extends` names another
+config *file* — a path relative to the file that declared it, or an npm module —
+and the inheriting file wins key by key. Ignore patterns are gitignore-flavoured
+globs relative to the config file's directory: `*` within a segment, `**` across
+segments, a plain path excludes the whole subtree, and an unanchored pattern
+matches at any segment boundary (`/` anchors it to the root).
+
 ## Suppressions
 
 ESLint / Prettier-style comments, authored in the function body (they survive

package/changed.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Changed-file detection for `--changed`, so a CI gate (or a human before a
+ * commit) pays only for the SQL that a branch actually touched.
+ *
+ * Modelled on pgpm's bundle-drift check (`pgpm/core/src/packaging/check.ts` in
+ * constructive): resolve a base ref (explicit → `origin/$GITHUB_BASE_REF` in a
+ * PR → the repository's default branch), diff `HEAD` against the **merge base**
+ * so unrelated commits on the base branch don't widen the set, and union that
+ * with uncommitted/untracked working-tree changes. Deleted paths are dropped —
+ * there is nothing left on disk to lint.
+ */
+/**
+ * Resolve the ref to diff against. An explicit `base` wins; otherwise the PR
+ * base branch (`origin/$GITHUB_BASE_REF`) when running in GitHub Actions;
+ * otherwise the repository's default branch. `undefined` means "no base" and
+ * the caller falls back to working-tree changes only.
+ */
+export declare function resolveChangedBase(base?: string, cwd?: string): string | undefined;
+export interface ChangedFilesResult {
+    /** Absolute paths of changed files that still exist on disk. */
+    files: string[];
+    /** The base ref used, if any. */
+    base?: string;
+    /** The merge base actually diffed against, if one was resolvable. */
+    mergeBase?: string;
+}
+/**
+ * Collect the files that differ from `base` (via `git merge-base`) plus any
+ * uncommitted/untracked working-tree changes. Falls back to `git diff HEAD`
+ * when no base is resolvable or no merge base exists — a shallow clone or a
+ * detached CI checkout — rather than failing the run.
+ */
+export declare function changedFiles(options?: {
+    cwd?: string;
+    base?: string;
+}): ChangedFilesResult;
+/** {@link changedFiles}, narrowed to `.sql`. */
+export declare function changedSqlFiles(options?: {
+    cwd?: string;
+    base?: string;
+}): ChangedFilesResult;

package/changed.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Changed-file detection for `--changed`, so a CI gate (or a human before a
+ * commit) pays only for the SQL that a branch actually touched.
+ *
+ * Modelled on pgpm's bundle-drift check (`pgpm/core/src/packaging/check.ts` in
+ * constructive): resolve a base ref (explicit → `origin/$GITHUB_BASE_REF` in a
+ * PR → the repository's default branch), diff `HEAD` against the **merge base**
+ * so unrelated commits on the base branch don't widen the set, and union that
+ * with uncommitted/untracked working-tree changes. Deleted paths are dropped —
+ * there is nothing left on disk to lint.
+ */
+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.resolveChangedBase = resolveChangedBase;
+exports.changedFiles = changedFiles;
+exports.changedSqlFiles = changedSqlFiles;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+function git(args, cwd) {
+    return (0, child_process_1.execFileSync)('git', args, {
+        cwd,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 64 * 1024 * 1024
+    });
+}
+function tryGit(args, cwd) {
+    try {
+        return git(args, cwd);
+    }
+    catch {
+        return null;
+    }
+}
+/** The repository's default branch as a remote-tracking ref, when discoverable. */
+function defaultBranch(cwd) {
+    const head = tryGit(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], cwd);
+    if (head && head.trim())
+        return head.trim();
+    for (const candidate of ['origin/main', 'origin/master', 'main', 'master']) {
+        if (tryGit(['rev-parse', '--verify', '--quiet', candidate], cwd))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Resolve the ref to diff against. An explicit `base` wins; otherwise the PR
+ * base branch (`origin/$GITHUB_BASE_REF`) when running in GitHub Actions;
+ * otherwise the repository's default branch. `undefined` means "no base" and
+ * the caller falls back to working-tree changes only.
+ */
+function resolveChangedBase(base, cwd = process.cwd()) {
+    if (base && base.trim())
+        return base.trim();
+    const prBase = process.env.GITHUB_BASE_REF;
+    if (prBase && prBase.trim()) {
+        const ref = `origin/${prBase.trim()}`;
+        if (tryGit(['rev-parse', '--verify', '--quiet', ref], cwd))
+            return ref;
+        return prBase.trim();
+    }
+    return defaultBranch(cwd);
+}
+/** Parse `git status --porcelain` into paths (rename target wins). */
+function workingTreePaths(cwd) {
+    const out = [];
+    // `-uall` lists untracked *files*; the default collapses a new directory to
+    // the directory name, which would hide every file a new module adds.
+    const status = tryGit(['status', '--porcelain', '-uall'], cwd) ?? '';
+    for (const rawLine of status.split('\n')) {
+        const line = rawLine.trimEnd();
+        if (!line)
+            continue;
+        let p = line.slice(3);
+        const arrow = p.indexOf(' -> ');
+        if (arrow !== -1)
+            p = p.slice(arrow + 4);
+        p = p.replace(/^"|"$/g, '');
+        if (p)
+            out.push(p);
+    }
+    return out;
+}
+/**
+ * Collect the files that differ from `base` (via `git merge-base`) plus any
+ * uncommitted/untracked working-tree changes. Falls back to `git diff HEAD`
+ * when no base is resolvable or no merge base exists — a shallow clone or a
+ * detached CI checkout — rather than failing the run.
+ */
+function changedFiles(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!tryGit(['rev-parse', '--git-dir'], cwd)) {
+        throw new Error(`--changed needs a git repository; ${cwd} is not inside one`);
+    }
+    const files = new Set(workingTreePaths(cwd));
+    const base = resolveChangedBase(options.base, cwd);
+    let mergeBase;
+    if (base) {
+        const found = tryGit(['merge-base', 'HEAD', base], cwd);
+        mergeBase = found?.trim() || undefined;
+    }
+    // No base, or no common ancestor (shallow clone / detached checkout): the
+    // uncommitted diff against HEAD is all the history we can see.
+    const diffArgs = mergeBase
+        ? ['diff', '--name-only', '--diff-filter=ACMR', mergeBase, 'HEAD']
+        : ['diff', '--name-only', '--diff-filter=ACMR', 'HEAD'];
+    for (const rawLine of (tryGit(diffArgs, cwd) ?? '').split('\n')) {
+        const p = rawLine.trim();
+        if (p)
+            files.add(p);
+    }
+    const abs = [];
+    for (const rel of files) {
+        const full = path.resolve(cwd, rel);
+        // Deleted or renamed-away paths have nothing left to lint.
+        if ((0, fs_1.existsSync)(full) && (0, fs_1.statSync)(full).isFile())
+            abs.push(full);
+    }
+    return { files: abs.sort(), base, mergeBase };
+}
+/** {@link changedFiles}, narrowed to `.sql`. */
+function changedSqlFiles(options = {}) {
+    const result = changedFiles(options);
+    return { ...result, files: result.files.filter((f) => f.toLowerCase().endsWith('.sql')) };
+}

package/cli.d.ts

@@ -2,11 +2,13 @@
 /**
  * `pgsql-lint` — lint SQL source files for the convention rules.
  *
- *   pgsql-lint <path…> [--rules a,b] [--warn a,b] [--off a,b] [--json] [--quiet]
+ *   pgsql-lint <path…> [--changed[=<base>]] [--ignore <globs>] [--rules a,b]
+ *              [--warn a,b] [--off a,b] [--config <file>] [--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.
+ * `.sql`), and default to `paths` from the config file. 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

@@ -3,19 +3,58 @@
 /**
  * `pgsql-lint` — lint SQL source files for the convention rules.
  *
- *   pgsql-lint <path…> [--rules a,b] [--warn a,b] [--off a,b] [--json] [--quiet]
+ *   pgsql-lint <path…> [--changed[=<base>]] [--ignore <globs>] [--rules a,b]
+ *              [--warn a,b] [--off a,b] [--config <file>] [--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.
+ * `.sql`), and default to `paths` from the config file. 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 __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;
+    };
+})();
 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 fs_1 = require("fs");
 const minimist_1 = __importDefault(require("minimist"));
+const path = __importStar(require("path"));
+const changed_1 = require("./changed");
+const config_1 = require("./config");
 const file_runner_1 = require("./file-runner");
 const rules_1 = require("./rules");
 const HELP = `pgsql-lint — source-level SQL/PL/pgSQL convention linter
@@ -25,17 +64,29 @@ Usage:
 
 Arguments:
   path                 One or more .sql files or directories (scanned recursively).
+                       Defaults to "paths" from the config file.
 
 Options:
+  --changed[=<base>]   Lint only .sql files that differ from <base> (default: the
+                       PR base branch, else the repository default branch), using
+                       the merge base, plus working-tree changes. Exits 0 when
+                       nothing changed.
+  --ignore <globs>     Exclude paths (comma-separated, repeatable).
   --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).
+  --config <file>      Config file to use (default: nearest .pgsqllintrc.json).
+  --no-config          Ignore any config file.
   --json               Emit findings as JSON.
   --quiet              Only print active findings (hide acknowledged waivers).
   -h, --help           Show this help.
   -v, --version        Show version.
 
+Config file (.pgsqllintrc.json, discovered upward from cwd; flags override it):
+  { "extends": "./base.json", "rules": [], "warn": [], "off": [],
+    "ignore": ["sql/", "**/generated/**"], "keyword": [], "paths": ["packages"] }
+
 Rules:
 ${rules_1.LINT_RULES.map((r) => `  ${r.code}  ${r.id}  —  ${r.title}`).join('\n')}
 
@@ -43,33 +94,114 @@ Suppress inline (in the function body):
   -- pgsql-lint-disable-next-line no-dynamic-sql -- lookup-only: <why>
 `;
 function csv(v) {
-    if (!v)
+    if (v === undefined)
         return undefined;
-    const parts = v.split(',').map((s) => s.trim()).filter(Boolean);
+    const parts = (Array.isArray(v) ? v : [v])
+        .flatMap((s) => s.split(','))
+        .map((s) => s.trim())
+        .filter(Boolean);
     return parts.length > 0 ? parts : undefined;
 }
+/**
+ * Own version. In the repo the compiled CLI sits in `dist/`, but the published
+ * package flattens `dist/` to its root, so `../package.json` only resolves in
+ * one of the two layouts — try both rather than crashing on `--version`.
+ */
+function packageVersion() {
+    for (const candidate of ['../package.json', './package.json']) {
+        try {
+            return require(candidate).version;
+        }
+        catch {
+            // Wrong layout; try the next candidate.
+        }
+    }
+    return 'unknown';
+}
+/**
+ * `--changed` takes an *optional* value, which minimist cannot express: with
+ * `string: ['changed']` it would swallow a following path. Bind the next token
+ * only when it is not a flag and not an existing path — i.e. when it reads as a
+ * git ref — and otherwise rewrite the flag to an empty value.
+ */
+function normalizeChanged(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] !== '--changed') {
+            out.push(args[i]);
+            continue;
+        }
+        const next = args[i + 1];
+        if (next && !next.startsWith('-') && !(0, fs_1.existsSync)(next)) {
+            out.push(`--changed=${next}`);
+            i++;
+        }
+        else {
+            out.push('--changed=');
+        }
+    }
+    return out;
+}
 async function main() {
-    const argv = (0, minimist_1.default)(process.argv.slice(2), {
+    const raw = process.argv.slice(2);
+    // Handled here rather than as a minimist boolean: `config` also takes a value.
+    const noConfig = raw.includes('--no-config');
+    const argv = (0, minimist_1.default)(normalizeChanged(raw.filter((a) => a !== '--no-config')), {
         boolean: ['json', 'quiet', 'help', 'version'],
-        string: ['rules', 'warn', 'off', 'keyword'],
+        string: ['rules', 'warn', 'off', 'keyword', 'changed', 'ignore', 'config'],
         alias: { h: 'help', v: 'version' }
     });
     if (argv.version) {
-        console.log(require('../package.json').version);
+        console.log(packageVersion());
         return;
     }
-    if (argv.help || argv._.length === 0) {
+    const cwd = process.cwd();
+    const loaded = noConfig
+        ? { config: {} }
+        : (0, config_1.loadLintConfig)({ cwd, configFile: argv.config || undefined });
+    const fileConfig = loaded.config;
+    const baseDir = (0, config_1.configDir)(loaded, cwd);
+    const useChanged = argv.changed !== undefined;
+    const paths = argv._.length > 0
+        ? argv._
+        : (fileConfig.paths ?? []).map((p) => path.resolve(baseDir, p));
+    if (argv.help || (!useChanged && paths.length === 0)) {
         console.log(HELP);
-        process.exit(argv._.length === 0 && !argv.help ? 1 : 0);
+        process.exit(argv.help ? 0 : 1);
     }
-    const rules = csv(argv.rules);
-    const keyword = csv(argv.keyword);
+    const rules = csv(argv.rules) ?? fileConfig.rules;
+    const keyword = csv(argv.keyword) ?? (fileConfig.keyword ? csv(fileConfig.keyword) : undefined);
+    const ignore = csv(argv.ignore) ?? fileConfig.ignore;
     const severity = {};
-    for (const id of csv(argv.warn) ?? [])
+    for (const id of csv(argv.warn) ?? fileConfig.warn ?? [])
         severity[id] = 'warn';
-    for (const id of csv(argv.off) ?? [])
+    for (const id of csv(argv.off) ?? fileConfig.off ?? [])
         severity[id] = 'off';
-    const reports = await (0, file_runner_1.lintFiles)(argv._, { rules, keyword, severity });
+    let targets;
+    if (useChanged) {
+        const changed = (0, changed_1.changedSqlFiles)({ cwd, base: argv.changed || undefined });
+        // Nothing to lint is a pass, not an error — the common case on a branch
+        // that touched no SQL at all.
+        if (changed.files.length === 0) {
+            if (argv.json)
+                console.log('[]');
+            else
+                console.log(chalk_1.default.green('0 errors'), chalk_1.default.gray('(no changed .sql files)'));
+            process.exit(0);
+        }
+        targets = paths.length > 0 ? withinPaths(changed.files, paths) : changed.files;
+        if (targets.length === 0) {
+            if (argv.json)
+                console.log('[]');
+            else
+                console.log(chalk_1.default.green('0 errors'), chalk_1.default.gray('(no changed .sql files under the given paths)'));
+            process.exit(0);
+        }
+    }
+    else {
+        targets = paths;
+    }
+    const reports = await (0, file_runner_1.lintFiles)(targets, { rules, keyword, severity, ignore, cwd: baseDir });
     if (argv.json) {
         console.log(JSON.stringify(reports, null, 2));
     }
@@ -109,6 +241,16 @@ async function main() {
     }
     process.exit(errors > 0 ? 1 : 0);
 }
+/** Keep only changed files that sit inside one of the requested paths. */
+function withinPaths(files, paths) {
+    const roots = paths.map((p) => path.resolve(p));
+    return files.filter((file) => roots.some((root) => {
+        if (file === root)
+            return true;
+        const rel = path.relative(root, file);
+        return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+    }));
+}
 function formatFinding(f) {
     const loc = chalk_1.default.gray(`${String(f.line).padStart(4)}`);
     const tag = f.acknowledged

package/config.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Config-file support — so a repository states its lint policy once, in a file,
+ * instead of repeating flags in every workflow step and every shell history.
+ *
+ * The keys mirror the CLI flags exactly (`rules`, `warn`, `off`, `ignore`,
+ * `keyword`, `paths`), and a flag always overrides the file. Discovery walks up
+ * from `cwd` looking for `.pgsqllintrc.json` / `.pgsqllintrc`.
+ *
+ * `extends` names another config *file* (a relative path resolved against the
+ * file that declared it, or a resolvable npm module). This package has no
+ * built-in presets — its rule set is injected as values, not discovered by name
+ * — so unlike safegres's `extends: "safegres:constructive"` there is nothing to
+ * name but a file.
+ */
+/** The shape of `.pgsqllintrc.json`. Every key mirrors a CLI flag. */
+export interface LintConfigFile {
+    /** Another config file to inherit from (path, or npm module). */
+    extends?: string | string[];
+    /** Rule ids/codes to run (default: all). */
+    rules?: string[];
+    /** Rules reported as warnings. */
+    warn?: string[];
+    /** Rules disabled entirely. */
+    off?: string[];
+    /** Glob patterns to exclude. */
+    ignore?: string[];
+    /** Suppression directive keyword(s). */
+    keyword?: string | string[];
+    /** Default paths to lint when none are given on the command line. */
+    paths?: string[];
+}
+export declare const CONFIG_FILENAMES: readonly [".pgsqllintrc.json", ".pgsqllintrc"];
+/** Walk up from `cwd` for the first config file. */
+export declare function findConfigFile(cwd?: string): string | undefined;
+export interface LoadedLintConfig {
+    config: LintConfigFile;
+    /** The file the config was read from, when one was found. */
+    filepath?: string;
+}
+/**
+ * Load the effective config: an explicit `configFile`, else the nearest
+ * discovered one, else empty. Paths in `ignore`/`paths` stay as written — the
+ * caller resolves them against the config file's directory (see `configDir`).
+ */
+export declare function loadLintConfig(params?: {
+    cwd?: string;
+    configFile?: string;
+}): LoadedLintConfig;
+/** The directory a discovered config's relative paths resolve against. */
+export declare function configDir(loaded: LoadedLintConfig, cwd?: string): string;