@pgsql/lint 18.1.2 → 18.2.1

package/README.md

@@ -46,11 +46,52 @@ 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 base) falls back to working-tree
+changes only. Nothing changed is an exit-0 pass.
+
+Detection is [`git-changed`](https://npmjs.com/package/git-changed), shared with
+`pgpm package --check`, so the two agree on what "changed" means.
+
+### 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,39 @@
+/**
+ * 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.
+ *
+ * The git plumbing — base resolution, merge-base diff, working-tree union,
+ * rename targets, dropping paths that no longer exist — lives in `git-changed`,
+ * which is shared with pgpm's bundle-drift check. This module is the `.sql`
+ * filter over it, and the place where "no base" stays non-fatal: a lint gate
+ * that refuses to run on a shallow clone lints nothing, which is worse than
+ * linting the working tree.
+ */
+/**
+ * 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.
+ */
+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,44 @@
+"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.
+ *
+ * The git plumbing — base resolution, merge-base diff, working-tree union,
+ * rename targets, dropping paths that no longer exist — lives in `git-changed`,
+ * which is shared with pgpm's bundle-drift check. This module is the `.sql`
+ * filter over it, and the place where "no base" stays non-fatal: a lint gate
+ * that refuses to run on a shallow clone lints nothing, which is worse than
+ * linting the working tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveChangedBase = resolveChangedBase;
+exports.changedFiles = changedFiles;
+exports.changedSqlFiles = changedSqlFiles;
+const git_changed_1 = require("git-changed");
+/**
+ * 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()) {
+    return (0, git_changed_1.resolveBase)(base, cwd);
+}
+function collect(cwd, base, ext) {
+    if (!(0, git_changed_1.isRepo)(cwd)) {
+        throw new Error(`--changed needs a git repository; ${cwd} is not inside one`);
+    }
+    const result = (0, git_changed_1.changedFiles)({ cwd, base, ext });
+    return { files: result.paths, base: result.base, mergeBase: result.mergeBase };
+}
+/**
+ * Collect the files that differ from `base` (via `git merge-base`) plus any
+ * uncommitted/untracked working-tree changes.
+ */
+function changedFiles(options = {}) {
+    return collect(options.cwd ?? process.cwd(), options.base);
+}
+/** {@link changedFiles}, narrowed to `.sql`. */
+function changedSqlFiles(options = {}) {
+    return collect(options.cwd ?? process.cwd(), options.base, '.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;

package/config.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * 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.
+ */
+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.CONFIG_FILENAMES = void 0;
+exports.findConfigFile = findConfigFile;
+exports.loadLintConfig = loadLintConfig;
+exports.configDir = configDir;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+exports.CONFIG_FILENAMES = ['.pgsqllintrc.json', '.pgsqllintrc'];
+const KNOWN_KEYS = new Set([
+    '$schema',
+    'extends',
+    'rules',
+    'warn',
+    'off',
+    'ignore',
+    'keyword',
+    'paths'
+]);
+/** Walk up from `cwd` for the first config file. */
+function findConfigFile(cwd = process.cwd()) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        for (const name of exports.CONFIG_FILENAMES) {
+            const candidate = path.join(dir, name);
+            if ((0, fs_1.existsSync)(candidate))
+                return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function readConfigFile(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse((0, fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`could not parse ${file}: ${err.message}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${file}: expected a JSON object`);
+    }
+    const config = parsed;
+    const unknown = Object.keys(config).filter((k) => !KNOWN_KEYS.has(k));
+    if (unknown.length > 0) {
+        throw new Error(`${file}: unknown key(s) ${unknown.join(', ')} — expected any of ` +
+            `${[...KNOWN_KEYS].filter((k) => k !== '$schema').join(', ')}`);
+    }
+    return config;
+}
+/** Resolve an `extends` target: a path relative to `from`, or an npm module. */
+function resolveExtends(target, from) {
+    const asPath = path.resolve(path.dirname(from), target);
+    for (const candidate of [asPath, `${asPath}.json`]) {
+        if ((0, fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    try {
+        return require.resolve(target, { paths: [path.dirname(from)] });
+    }
+    catch {
+        throw new Error(`${from}: could not resolve "extends": ${target} — it is read as a path ` +
+            'relative to the file that declared it, or as an npm module');
+    }
+}
+/** Later layers win; array keys replace rather than merge. */
+function merge(base, over) {
+    const out = { ...base, ...over };
+    delete out.extends;
+    return out;
+}
+function expand(file, seen) {
+    if (seen.has(file))
+        throw new Error(`circular "extends" chain at ${file}`);
+    seen.add(file);
+    const config = readConfigFile(file);
+    const parents = config.extends
+        ? Array.isArray(config.extends)
+            ? config.extends
+            : [config.extends]
+        : [];
+    let acc = {};
+    for (const parent of parents) {
+        acc = merge(acc, expand(resolveExtends(parent, file), seen));
+    }
+    return merge(acc, config);
+}
+/**
+ * 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`).
+ */
+function loadLintConfig(params = {}) {
+    const cwd = params.cwd ?? process.cwd();
+    const filepath = params.configFile
+        ? path.resolve(cwd, params.configFile)
+        : findConfigFile(cwd);
+    if (!filepath)
+        return { config: {} };
+    if (!(0, fs_1.existsSync)(filepath))
+        throw new Error(`config file not found: ${filepath}`);
+    return { config: expand(filepath, new Set()), filepath };
+}
+/** The directory a discovered config's relative paths resolve against. */
+function configDir(loaded, cwd = process.cwd()) {
+    return loaded.filepath ? path.dirname(loaded.filepath) : cwd;
+}

package/esm/changed.js

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ *
+ * The git plumbing — base resolution, merge-base diff, working-tree union,
+ * rename targets, dropping paths that no longer exist — lives in `git-changed`,
+ * which is shared with pgpm's bundle-drift check. This module is the `.sql`
+ * filter over it, and the place where "no base" stays non-fatal: a lint gate
+ * that refuses to run on a shallow clone lints nothing, which is worse than
+ * linting the working tree.
+ */
+import { changedFiles as gitChangedFiles, isRepo, resolveBase } from 'git-changed';
+/**
+ * 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 function resolveChangedBase(base, cwd = process.cwd()) {
+    return resolveBase(base, cwd);
+}
+function collect(cwd, base, ext) {
+    if (!isRepo(cwd)) {
+        throw new Error(`--changed needs a git repository; ${cwd} is not inside one`);
+    }
+    const result = gitChangedFiles({ cwd, base, ext });
+    return { files: result.paths, base: result.base, mergeBase: result.mergeBase };
+}
+/**
+ * Collect the files that differ from `base` (via `git merge-base`) plus any
+ * uncommitted/untracked working-tree changes.
+ */
+export function changedFiles(options = {}) {
+    return collect(options.cwd ?? process.cwd(), options.base);
+}
+/** {@link changedFiles}, narrowed to `.sql`. */
+export function changedSqlFiles(options = {}) {
+    return collect(options.cwd ?? process.cwd(), options.base, '.sql');
+}