@pgsql/lint 18.1.2 → 18.2.1

package/esm/cli.js

@@ -2,15 +2,21 @@
 /**
  * `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.
  */
 import chalk from 'chalk';
+import { existsSync } from 'fs';
 import minimist from 'minimist';
+import * as path from 'path';
+import { changedSqlFiles } from './changed';
+import { configDir, loadLintConfig } from './config';
 import { lintFiles } from './file-runner';
 import { LINT_RULES } from './rules';
 const HELP = `pgsql-lint — source-level SQL/PL/pgSQL convention linter
@@ -20,17 +26,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:
 ${LINT_RULES.map((r) => `  ${r.code}  ${r.id}  —  ${r.title}`).join('\n')}
 
@@ -38,33 +56,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('-') && !existsSync(next)) {
+            out.push(`--changed=${next}`);
+            i++;
+        }
+        else {
+            out.push('--changed=');
+        }
+    }
+    return out;
+}
 async function main() {
-    const argv = minimist(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 = minimist(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: {} }
+        : loadLintConfig({ cwd, configFile: argv.config || undefined });
+    const fileConfig = loaded.config;
+    const baseDir = 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 lintFiles(argv._, { rules, keyword, severity });
+    let targets;
+    if (useChanged) {
+        const changed = 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.green('0 errors'), chalk.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.green('0 errors'), chalk.gray('(no changed .sql files under the given paths)'));
+            process.exit(0);
+        }
+    }
+    else {
+        targets = paths;
+    }
+    const reports = await lintFiles(targets, { rules, keyword, severity, ignore, cwd: baseDir });
     if (argv.json) {
         console.log(JSON.stringify(reports, null, 2));
     }
@@ -104,6 +203,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.gray(`${String(f.line).padStart(4)}`);
     const tag = f.acknowledged

package/esm/config.js

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+import { existsSync, readFileSync } from 'fs';
+import * as path from 'path';
+export const 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. */
+export function findConfigFile(cwd = process.cwd()) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        for (const name of CONFIG_FILENAMES) {
+            const candidate = path.join(dir, name);
+            if (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(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 (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`).
+ */
+export 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 (!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. */
+export function configDir(loaded, cwd = process.cwd()) {
+    return loaded.filepath ? path.dirname(loaded.filepath) : cwd;
+}

package/esm/file-runner.js

@@ -13,6 +13,7 @@ import { promises as fs } from 'fs';
 import * as path from 'path';
 import { parse } from 'pgsql-parser';
 import { lintDefinition } from './engine';
+import { applyIgnore } from './ignore';
 import { findAll } from './walk';
 /** Count newlines before `offset` — the 0-based line the offset sits on. */
 function lineAtOffset(text, offset) {
@@ -154,7 +155,7 @@ async function sqlFilesUnder(dir) {
     return out;
 }
 /** Resolve a mix of file and directory paths to a sorted list of `.sql` files. */
-export async function resolveSqlFiles(paths) {
+export async function resolveSqlFiles(paths, options = {}) {
     const files = new Set();
     for (const p of paths) {
         const st = await fs.stat(p);
@@ -166,11 +167,11 @@ export async function resolveSqlFiles(paths) {
             files.add(p);
         }
     }
-    return [...files].sort();
+    return applyIgnore([...files].sort(), options.ignore, options.cwd);
 }
 /** Lint every `.sql` file reachable from `paths` (files or directories). */
 export async function lintFiles(paths, options = {}) {
-    const files = await resolveSqlFiles(paths);
+    const files = await resolveSqlFiles(paths, { ignore: options.ignore, cwd: options.cwd });
     const reports = [];
     for (const file of files) {
         const source = await fs.readFile(file, 'utf8');
@@ -184,11 +185,11 @@ export function sqlTextAdapter(source, file) {
     return { id: 'sql-text', definitions: () => sqlTextDefinitions(source, file) };
 }
 /** A {@link SourceAdapter} over `.sql` files/directories on disk. */
-export function filesAdapter(paths) {
+export function filesAdapter(paths, options = {}) {
     return {
         id: 'files',
         definitions: async () => {
-            const files = await resolveSqlFiles(paths);
+            const files = await resolveSqlFiles(paths, options);
             const out = [];
             for (const file of files) {
                 out.push(...(await sqlTextDefinitions(await fs.readFile(file, 'utf8'), file)));

package/esm/ignore.js

@@ -0,0 +1,101 @@
+/**
+ * Path exclusion for the file runner — `--ignore` / `ignore` in a config file.
+ *
+ * Most repositories that lint SQL on disk also *generate* SQL on disk
+ * (packaged modules, introspected schemas, codegen output), and linting
+ * generated output is noise. Patterns are gitignore-flavoured globs matched
+ * against the path relative to `cwd`:
+ *
+ *   - `*` matches within a segment, `**` across segments, `?` one character.
+ *   - A pattern with no glob character matches that path *and everything under
+ *     it*, so `sql/` and `sql` both exclude `sql/app--1.0.0.sql`.
+ *   - An unanchored pattern (no leading `/`) also matches at any segment
+ *     boundary, so `generated/`, `**` patterns, and `*.gen.sql` all work.
+ *   - A leading `/` anchors the pattern to `cwd`.
+ */
+import * as path from 'path';
+/** Turn a glob into a `RegExp` source anchored at both ends. */
+function globToRegExpSource(glob) {
+    let out = '';
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === '*') {
+            if (glob[i + 1] === '*') {
+                // `**/` may match zero segments, so `**/gen/**` also matches `gen/x`.
+                if (glob[i + 2] === '/') {
+                    out += '(?:.*/)?';
+                    i += 2;
+                }
+                else {
+                    out += '.*';
+                    i += 1;
+                }
+            }
+            else {
+                out += '[^/]*';
+            }
+            continue;
+        }
+        if (ch === '?') {
+            out += '[^/]';
+            continue;
+        }
+        out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return out;
+}
+function compile(pattern) {
+    let p = pattern.trim().replace(/\\/g, '/');
+    if (!p || p.startsWith('#'))
+        return null;
+    const anchored = p.startsWith('/');
+    if (anchored)
+        p = p.slice(1);
+    p = p.replace(/^\.\//, '');
+    const dirOnly = p.endsWith('/');
+    if (dirOnly)
+        p = p.replace(/\/+$/, '');
+    if (!p)
+        return null;
+    // A plain path (or an explicit directory) excludes the subtree under it.
+    const source = /[*?]/.test(p) && !dirOnly
+        ? globToRegExpSource(p)
+        : `${globToRegExpSource(p)}(?:/.*)?`;
+    return { re: new RegExp(`^${source}$`), anchored };
+}
+/**
+ * Build a predicate that answers "is this file ignored?". Paths may be
+ * absolute or relative; both are compared as `cwd`-relative POSIX paths.
+ */
+export function makeIgnoreFilter(patterns = [], cwd = process.cwd()) {
+    const compiled = patterns.map(compile).filter((c) => c !== null);
+    if (compiled.length === 0)
+        return () => false;
+    return (file) => {
+        const rel = path.relative(cwd, path.resolve(cwd, file)).replace(/\\/g, '/');
+        // Outside cwd entirely — no relative pattern can meaningfully describe it.
+        if (rel.startsWith('../'))
+            return false;
+        const segments = rel.split('/');
+        for (const { re, anchored } of compiled) {
+            if (re.test(rel))
+                return true;
+            if (anchored)
+                continue;
+            // Unanchored: also try every suffix that starts at a segment boundary,
+            // so `generated/` matches `packages/x/generated/y.sql`.
+            for (let i = 1; i < segments.length; i++) {
+                if (re.test(segments.slice(i).join('/')))
+                    return true;
+            }
+        }
+        return false;
+    };
+}
+/** Filter a list of files through {@link makeIgnoreFilter}. */
+export function applyIgnore(files, patterns, cwd) {
+    if (!patterns || patterns.length === 0)
+        return files;
+    const ignored = makeIgnoreFilter(patterns, cwd);
+    return files.filter((f) => !ignored(f));
+}

package/esm/index.js

@@ -10,8 +10,11 @@
  * Rules are injected as values, never discovered by npm name: build a linter
  * with `createLinter({ rules, severity })` and pass your own rules in.
  */
+export { changedFiles, changedSqlFiles, resolveChangedBase } from './changed';
+export { CONFIG_FILENAMES, configDir, findConfigFile, loadLintConfig } from './config';
 export { lintDefinition, severityOf } from './engine';
 export { filesAdapter, lintFiles, lintSource, lintSqlText, resolveSqlFiles, sqlTextAdapter, sqlTextDefinitions } from './file-runner';
+export { applyIgnore, makeIgnoreFilter } from './ignore';
 export { createLinter } from './linter';
 export { parseUnit } from './parse-unit';
 export { LINT_RULES, LINT_RULES_BY_CODE, LINT_RULES_BY_ID, noDynamicSql, noSetSearchPath, noVariableConflict, requireQualifiedRefs } from './rules';

package/esm/linter.js

@@ -17,6 +17,7 @@ export function createLinter(config = {}) {
     const rules = config.rules ?? LINT_RULES;
     const severity = config.severity ?? {};
     const keyword = config.keyword ?? DEFAULT_KEYWORDS;
+    const { ignore, cwd } = config;
     const bind = (options = {}) => ({
         ruleSet: rules,
         severity,
@@ -29,7 +30,7 @@ export function createLinter(config = {}) {
         keyword,
         lintDefinition: (text, language, name, options) => lintDefinition(text, language, name, bind(options)),
         lintSqlText: (source, options) => lintSqlText(source, bind(options)),
-        lintFiles: (paths, options) => lintFiles(paths, bind(options)),
+        lintFiles: (paths, options) => lintFiles(paths, { ...bind(options), ignore, cwd }),
         lintSource: (adapter, options) => lintSource(adapter, bind(options))
     };
 }

package/file-runner.d.ts

@@ -51,14 +51,27 @@ export declare function sqlTextDefinitions(source: string, file?: string): Promi
  * re-anchored to absolute lines within `source`.
  */
 export declare function lintSqlText(source: string, options?: LintOptions): Promise<FileReport>;
+/** File-selection options layered on top of the lint options. */
+export interface FileLintOptions extends LintOptions {
+    /** Glob patterns to exclude (see `makeIgnoreFilter`). */
+    ignore?: string[];
+    /** Directory the `ignore` patterns are relative to (default `process.cwd()`). */
+    cwd?: string;
+}
 /** Resolve a mix of file and directory paths to a sorted list of `.sql` files. */
-export declare function resolveSqlFiles(paths: string[]): Promise<string[]>;
+export declare function resolveSqlFiles(paths: string[], options?: {
+    ignore?: string[];
+    cwd?: string;
+}): Promise<string[]>;
 /** Lint every `.sql` file reachable from `paths` (files or directories). */
-export declare function lintFiles(paths: string[], options?: LintOptions): Promise<FileReport[]>;
+export declare function lintFiles(paths: string[], options?: FileLintOptions): Promise<FileReport[]>;
 /** A {@link SourceAdapter} over an in-memory SQL string. */
 export declare function sqlTextAdapter(source: string, file?: string): SourceAdapter;
 /** A {@link SourceAdapter} over `.sql` files/directories on disk. */
-export declare function filesAdapter(paths: string[]): SourceAdapter;
+export declare function filesAdapter(paths: string[], options?: {
+    ignore?: string[];
+    cwd?: string;
+}): SourceAdapter;
 /**
  * Lint every definition an adapter yields, grouped into one {@link FileReport}
  * per origin file. This is the generic entry point: `@pgsql/lint` ships file

package/file-runner.js

@@ -55,6 +55,7 @@ const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const pgsql_parser_1 = require("pgsql-parser");
 const engine_1 = require("./engine");
+const ignore_1 = require("./ignore");
 const walk_1 = require("./walk");
 /** Count newlines before `offset` — the 0-based line the offset sits on. */
 function lineAtOffset(text, offset) {
@@ -196,7 +197,7 @@ async function sqlFilesUnder(dir) {
     return out;
 }
 /** Resolve a mix of file and directory paths to a sorted list of `.sql` files. */
-async function resolveSqlFiles(paths) {
+async function resolveSqlFiles(paths, options = {}) {
     const files = new Set();
     for (const p of paths) {
         const st = await fs_1.promises.stat(p);
@@ -208,11 +209,11 @@ async function resolveSqlFiles(paths) {
             files.add(p);
         }
     }
-    return [...files].sort();
+    return (0, ignore_1.applyIgnore)([...files].sort(), options.ignore, options.cwd);
 }
 /** Lint every `.sql` file reachable from `paths` (files or directories). */
 async function lintFiles(paths, options = {}) {
-    const files = await resolveSqlFiles(paths);
+    const files = await resolveSqlFiles(paths, { ignore: options.ignore, cwd: options.cwd });
     const reports = [];
     for (const file of files) {
         const source = await fs_1.promises.readFile(file, 'utf8');
@@ -226,11 +227,11 @@ function sqlTextAdapter(source, file) {
     return { id: 'sql-text', definitions: () => sqlTextDefinitions(source, file) };
 }
 /** A {@link SourceAdapter} over `.sql` files/directories on disk. */
-function filesAdapter(paths) {
+function filesAdapter(paths, options = {}) {
     return {
         id: 'files',
         definitions: async () => {
-            const files = await resolveSqlFiles(paths);
+            const files = await resolveSqlFiles(paths, options);
             const out = [];
             for (const file of files) {
                 out.push(...(await sqlTextDefinitions(await fs_1.promises.readFile(file, 'utf8'), file)));

package/ignore.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Path exclusion for the file runner — `--ignore` / `ignore` in a config file.
+ *
+ * Most repositories that lint SQL on disk also *generate* SQL on disk
+ * (packaged modules, introspected schemas, codegen output), and linting
+ * generated output is noise. Patterns are gitignore-flavoured globs matched
+ * against the path relative to `cwd`:
+ *
+ *   - `*` matches within a segment, `**` across segments, `?` one character.
+ *   - A pattern with no glob character matches that path *and everything under
+ *     it*, so `sql/` and `sql` both exclude `sql/app--1.0.0.sql`.
+ *   - An unanchored pattern (no leading `/`) also matches at any segment
+ *     boundary, so `generated/`, `**` patterns, and `*.gen.sql` all work.
+ *   - A leading `/` anchors the pattern to `cwd`.
+ */
+/**
+ * Build a predicate that answers "is this file ignored?". Paths may be
+ * absolute or relative; both are compared as `cwd`-relative POSIX paths.
+ */
+export declare function makeIgnoreFilter(patterns?: string[], cwd?: string): (file: string) => boolean;
+/** Filter a list of files through {@link makeIgnoreFilter}. */
+export declare function applyIgnore(files: string[], patterns?: string[], cwd?: string): string[];