@pgsql/lint 18.3.3 → 18.3.5

package/README.md

@@ -36,6 +36,10 @@ Agent skill (rules, CLI, authoring new rules):
 | `C3` | `require-qualified-refs` | an unqualified relation reference (`FROM users` → `FROM app_public.users`) |
 | `C4` | `no-dynamic-sql` | `EXECUTE`, `EXECUTE … USING`, `FOR … IN EXECUTE` |
 
+A definition the parser rejects is reported as `parse-error` (`P0`) rather than
+skipped: no rule ran over it, so it is not clean. Downgrade it like any rule
+(`--warn parse-error`) when the parser, not the SQL, is at fault.
+
 The rules encode a single discipline: never depend on `search_path` — fully
 qualify everything (`C1` + `C3`) — don't paper over ambiguity (`C2`), and treat
 dynamic SQL as opaque and exceptional (`C4`).

package/cli.js

@@ -209,11 +209,6 @@ async function main() {
     let warnings = 0;
     let acknowledged = 0;
     for (const report of reports) {
-        if (report.parseError) {
-            if (!argv.json)
-                console.error(chalk_1.default.yellow(`⚠ ${report.file}: ${report.parseError}`));
-            continue;
-        }
         const shown = report.findings.filter((f) => !f.acknowledged || !argv.quiet);
         if (!argv.json && shown.length > 0) {
             console.log(chalk_1.default.underline(report.file));

package/engine.d.ts

@@ -7,7 +7,7 @@
  * the rule objects in (see `createLinter`), so a third-party rule ships as an
  * ordinary import, not a magic `pgsql-lint-plugin-*` package.
  */
-import type { LintResult, LintRule, Severity, SeverityMap } from './types';
+import type { LintResult, LintRule, LintRuleMeta, Severity, SeverityMap } from './types';
 export interface LintOptions {
     /** Restrict to these rule ids/codes; omit to run every rule in the set. */
     rules?: string[];
@@ -25,6 +25,12 @@ export interface LintOptions {
     keyword?: string | string[];
 }
 /** Resolve a rule's configured severity (id wins over code; default `error`). */
-export declare function severityOf(rule: LintRule, severity?: SeverityMap): Severity;
+export declare function severityOf(rule: LintRuleMeta, severity?: SeverityMap): Severity;
+/**
+ * The pseudo-rule a parse failure is reported under. Not a {@link LintRule}
+ * (it has no `run`): it exists so the failure has an id/code a consumer can
+ * configure (`off` / `warn`) exactly like a rule.
+ */
+export declare const PARSE_ERROR: LintRuleMeta;
 /** Lint a single function definition. */
 export declare function lintDefinition(text: string, language: string, name?: string, options?: LintOptions): Promise<LintResult>;

package/engine.js

@@ -9,6 +9,7 @@
  * ordinary import, not a magic `pgsql-lint-plugin-*` package.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARSE_ERROR = void 0;
 exports.severityOf = severityOf;
 exports.lintDefinition = lintDefinition;
 const parse_unit_1 = require("./parse-unit");
@@ -18,6 +19,17 @@ const suppressions_1 = require("./suppressions");
 function severityOf(rule, severity = {}) {
     return severity[rule.id] ?? severity[rule.code] ?? 'error';
 }
+/**
+ * The pseudo-rule a parse failure is reported under. Not a {@link LintRule}
+ * (it has no `run`): it exists so the failure has an id/code a consumer can
+ * configure (`off` / `warn`) exactly like a rule.
+ */
+exports.PARSE_ERROR = {
+    id: 'parse-error',
+    code: 'P0',
+    title: 'Definition could not be parsed',
+    reasonRequired: false
+};
 /** Lint a single function definition. */
 async function lintDefinition(text, language, name, options = {}) {
     const active = [];
@@ -33,10 +45,11 @@ async function lintDefinition(text, language, name, options = {}) {
     if (selected.length === 0)
         return { problems: active, suppressed };
     const unit = await (0, parse_unit_1.parseUnit)(text, language, name);
-    // An unparseable definition produces no lint findings — dynamic/opaque bodies
-    // are a downstream concern (e.g. a call-graph), not the linter's.
+    // An unparseable definition was checked by no rule. That is never a pass:
+    // the failure is returned so the caller reports it (the file runner turns
+    // it into a `parse-error` finding).
     if (unit.parseError)
-        return { problems: active, suppressed };
+        return { problems: active, suppressed, parseError: unit.parseError };
     const keywords = options.keyword
         ? (Array.isArray(options.keyword) ? options.keyword : [options.keyword])
         : suppressions_1.DEFAULT_KEYWORDS;

package/esm/cli.js

@@ -171,11 +171,6 @@ async function main() {
     let warnings = 0;
     let acknowledged = 0;
     for (const report of reports) {
-        if (report.parseError) {
-            if (!argv.json)
-                console.error(chalk.yellow(`⚠ ${report.file}: ${report.parseError}`));
-            continue;
-        }
         const shown = report.findings.filter((f) => !f.acknowledged || !argv.quiet);
         if (!argv.json && shown.length > 0) {
             console.log(chalk.underline(report.file));

package/esm/engine.js

@@ -14,6 +14,17 @@ import { DEFAULT_KEYWORDS, Suppressions } from './suppressions';
 export function severityOf(rule, severity = {}) {
     return severity[rule.id] ?? severity[rule.code] ?? 'error';
 }
+/**
+ * The pseudo-rule a parse failure is reported under. Not a {@link LintRule}
+ * (it has no `run`): it exists so the failure has an id/code a consumer can
+ * configure (`off` / `warn`) exactly like a rule.
+ */
+export const PARSE_ERROR = {
+    id: 'parse-error',
+    code: 'P0',
+    title: 'Definition could not be parsed',
+    reasonRequired: false
+};
 /** Lint a single function definition. */
 export async function lintDefinition(text, language, name, options = {}) {
     const active = [];
@@ -29,10 +40,11 @@ export async function lintDefinition(text, language, name, options = {}) {
     if (selected.length === 0)
         return { problems: active, suppressed };
     const unit = await parseUnit(text, language, name);
-    // An unparseable definition produces no lint findings — dynamic/opaque bodies
-    // are a downstream concern (e.g. a call-graph), not the linter's.
+    // An unparseable definition was checked by no rule. That is never a pass:
+    // the failure is returned so the caller reports it (the file runner turns
+    // it into a `parse-error` finding).
     if (unit.parseError)
-        return { problems: active, suppressed };
+        return { problems: active, suppressed, parseError: unit.parseError };
     const keywords = options.keyword
         ? (Array.isArray(options.keyword) ? options.keyword : [options.keyword])
         : DEFAULT_KEYWORDS;

package/esm/file-runner.js

@@ -12,18 +12,10 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { parse } from 'pgsql-parser';
-import { lintDefinition } from './engine';
+import { lintDefinition, PARSE_ERROR, severityOf } from './engine';
 import { applyIgnore } from './ignore';
+import { newlinesBeforeByte, sliceBytes, utf8 } from './util';
 import { findAll } from './walk';
-/** Count newlines before `offset` — the 0-based line the offset sits on. */
-function lineAtOffset(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;
-}
 /** Printable `schema.name` of a `CreateFunctionStmt.funcname`. */
 function funcName(createFnStmt) {
     const funcname = createFnStmt.funcname;
@@ -57,22 +49,26 @@ function funcLanguage(createFnStmt) {
  * `CREATE FUNCTION` is sliced back out with its absolute start line, so a
  * mixed migration (schema + tables + functions) yields one input per function
  * rather than being treated as a single malformed definition.
+ *
+ * `stmt_location` / `stmt_len` are byte offsets into the UTF-8 source, so the
+ * slicing happens over the encoded bytes (see `util.ts`).
  */
 export async function sqlTextDefinitions(source, file) {
     const parsed = (await parse(source));
+    const bytes = utf8(source);
     const out = [];
     for (const entry of parsed.stmts ?? []) {
         const createFnStmt = entry.stmt ? findAll(entry.stmt, 'CreateFunctionStmt')[0] : undefined;
         if (!createFnStmt)
             continue;
         const start = entry.stmt_location ?? 0;
-        const len = entry.stmt_len ?? source.length - start;
+        const len = entry.stmt_len ?? bytes.length - start;
         out.push({
-            text: source.slice(start, start + len),
+            text: sliceBytes(bytes, start, len),
             language: funcLanguage(createFnStmt),
             name: funcName(createFnStmt),
             file,
-            startLine: lineAtOffset(source, start) // 0-based line the definition begins on
+            startLine: newlinesBeforeByte(bytes, start) // 0-based line the definition begins on
         });
     }
     return out;
@@ -87,7 +83,9 @@ export async function lintSqlText(source, options = {}) {
         inputs = await sqlTextDefinitions(source);
     }
     catch (err) {
-        return { file: '<source>', findings: [], parseError: err.message };
+        const message = err.message;
+        const finding = parseErrorFinding(message, '<file>', 1, options);
+        return { file: '<source>', findings: finding ? [finding] : [], parseError: message };
     }
     const findings = await lintInputs(inputs, options);
     return { file: '<source>', findings };
@@ -98,7 +96,12 @@ async function lintInputs(inputs, options) {
     for (const input of inputs) {
         const subject = input.name ?? '<anonymous>';
         const startLine = input.startLine ?? 0;
-        const { problems, suppressed } = await lintDefinition(input.text, input.language, subject, options);
+        const { problems, suppressed, parseError } = await lintDefinition(input.text, input.language, subject, options);
+        if (parseError) {
+            const finding = parseErrorFinding(parseError, subject, startLine + 1, options);
+            if (finding)
+                findings.push(finding);
+        }
         const absLine = (p) => startLine + p.line; // p.line is 1-based within input.text
         for (const p of problems)
             findings.push(toFinding(p, subject, absLine(p), false));
@@ -129,6 +132,7 @@ function toFinding(p, subject, line, acknowledged, reason, scope) {
     return meta;
 }
 const RULE_CODE = {
+    [PARSE_ERROR.id]: PARSE_ERROR.code,
     'no-set-search-path': 'C1',
     'no-variable-conflict': 'C2',
     'require-qualified-refs': 'C3',
@@ -137,6 +141,28 @@ const RULE_CODE = {
 function codeFor(ruleId) {
     return RULE_CODE[ruleId] ?? ruleId;
 }
+/**
+ * A definition (or file) the parser rejected. Nothing in it was checked, so
+ * the failure is reported as a finding rather than dropped: an unparseable
+ * function would otherwise pass every rule by default. Severity is configured
+ * like any rule (`parse-error` / `P0`): `error` unless downgraded, and `off`
+ * drops it like any other rule turned off.
+ */
+function parseErrorFinding(message, subject, line, options) {
+    const severity = severityOf(PARSE_ERROR, options.severity);
+    if (severity === 'off')
+        return undefined;
+    return {
+        ruleId: PARSE_ERROR.id,
+        code: PARSE_ERROR.code,
+        line,
+        message: `Definition could not be parsed, so no rule was checked: ${message}`,
+        hint: 'Fix the syntax (or, if the parser is wrong, downgrade `parse-error` in the lint config).',
+        severity,
+        subject,
+        acknowledged: false
+    };
+}
 /** Recursively collect `.sql` files under a directory. */
 async function sqlFilesUnder(dir) {
     const out = [];

package/esm/index.js

@@ -12,7 +12,7 @@
  */
 export { changedFiles, changedSqlFiles, resolveChangedBase } from './changed';
 export { CONFIG_FILENAMES, configDir, findConfigFile, loadLintConfig } from './config';
-export { lintDefinition, severityOf } from './engine';
+export { lintDefinition, PARSE_ERROR, severityOf } from './engine';
 export { filesAdapter, lintFiles, lintSource, lintSqlText, resolveSqlFiles, sqlTextAdapter, sqlTextDefinitions } from './file-runner';
 export { applyIgnore, makeIgnoreFilter } from './ignore';
 export { createLinter } from './linter';

package/esm/parse-unit.js

@@ -10,19 +10,16 @@
  */
 import { parsePlPgSQL } from 'libpg-query';
 import { parse } from 'pgsql-parser';
+import { newlinesBeforeByte, utf8 } from './util';
 import { findAll } from './walk';
-/** Count newlines in `s[0..offset)` — i.e. how many lines precede `offset`. */
-function newlinesBefore(s, offset) {
+/** Absolute 1-based line of a char offset within `text`. */
+function lineOf(text, offset) {
     let n = 0;
-    const end = Math.min(offset, s.length);
+    const end = Math.min(offset, text.length);
     for (let i = 0; i < end; i++)
-        if (s.charCodeAt(i) === 10)
+        if (text.charCodeAt(i) === 10)
             n++;
-    return n;
-}
-/** Absolute 1-based line of a char offset within `text`. */
-function lineOf(text, offset) {
-    return newlinesBefore(text, offset) + 1;
+    return n + 1;
 }
 /** The body string of a `CreateFunctionStmt` (`AS $$ … $$`), or null. */
 function functionBody(createFnStmt) {
@@ -125,13 +122,14 @@ export async function parseUnit(text, language, name) {
     const dynamicSql = [];
     const lang = language.toLowerCase();
     if (lang === 'sql' && body !== null && bodyStartLine !== undefined) {
-        // A SQL-language body is itself SQL: parse it whole. Locations are
-        // relative to the body, so re-anchor them onto the definition.
+        // A SQL-language body is itself SQL: parse it whole. Locations are byte
+        // offsets relative to the body, so re-anchor them onto the definition.
         try {
             const ast = await parse(body);
+            const bodyBytes = utf8(body);
             fragments.push({
                 ast,
-                lineForOffset: (offset) => bodyStartLine + newlinesBefore(body, offset)
+                lineForOffset: (offset) => bodyStartLine + newlinesBeforeByte(bodyBytes, offset)
             });
         }
         catch {

package/esm/util.js

@@ -1,9 +1,31 @@
-/** Absolute 1-based line of a char offset within `text`. */
-export function lineOfOffset(text, offset) {
+/**
+ * Offset arithmetic. Every location libpg_query reports — `stmt_location`,
+ * `stmt_len`, a node's `location` — is a **byte** offset into the UTF-8 source,
+ * while a JS string is indexed by UTF-16 code unit. The two agree only while
+ * the text is pure ASCII: one `→` or `—` earlier in a file shifts every later
+ * offset, and a definition sliced by character then fails to parse. So slice
+ * and count newlines over the UTF-8 bytes, never over the string.
+ */
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** The UTF-8 bytes of `text` — the coordinate space parser offsets live in. */
+export function utf8(text) {
+    return encoder.encode(text);
+}
+/** `bytes[start, start + len)` decoded back to a string. */
+export function sliceBytes(bytes, start, len) {
+    return decoder.decode(bytes.subarray(start, start + len));
+}
+/** Count newline bytes in `bytes[0, byteOffset)` — the 0-based line the offset sits on. */
+export function newlinesBeforeByte(bytes, byteOffset) {
     let n = 0;
-    const end = Math.min(Math.max(offset, 0), text.length);
+    const end = Math.min(Math.max(byteOffset, 0), bytes.length);
     for (let i = 0; i < end; i++)
-        if (text.charCodeAt(i) === 10)
+        if (bytes[i] === 10)
             n++;
-    return n + 1;
+    return n;
+}
+/** Absolute 1-based line of a parser (byte) offset within `text`. */
+export function lineOfOffset(text, byteOffset) {
+    return newlinesBeforeByte(utf8(text), byteOffset) + 1;
 }

package/file-runner.d.ts

@@ -44,6 +44,9 @@ export interface FileReport {
  * `CREATE FUNCTION` is sliced back out with its absolute start line, so a
  * mixed migration (schema + tables + functions) yields one input per function
  * rather than being treated as a single malformed definition.
+ *
+ * `stmt_location` / `stmt_len` are byte offsets into the UTF-8 source, so the
+ * slicing happens over the encoded bytes (see `util.ts`).
  */
 export declare function sqlTextDefinitions(source: string, file?: string): Promise<LintDefinitionInput[]>;
 /**

package/file-runner.js

@@ -56,16 +56,8 @@ const path = __importStar(require("path"));
 const pgsql_parser_1 = require("pgsql-parser");
 const engine_1 = require("./engine");
 const ignore_1 = require("./ignore");
+const util_1 = require("./util");
 const walk_1 = require("./walk");
-/** Count newlines before `offset` — the 0-based line the offset sits on. */
-function lineAtOffset(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;
-}
 /** Printable `schema.name` of a `CreateFunctionStmt.funcname`. */
 function funcName(createFnStmt) {
     const funcname = createFnStmt.funcname;
@@ -99,22 +91,26 @@ function funcLanguage(createFnStmt) {
  * `CREATE FUNCTION` is sliced back out with its absolute start line, so a
  * mixed migration (schema + tables + functions) yields one input per function
  * rather than being treated as a single malformed definition.
+ *
+ * `stmt_location` / `stmt_len` are byte offsets into the UTF-8 source, so the
+ * slicing happens over the encoded bytes (see `util.ts`).
  */
 async function sqlTextDefinitions(source, file) {
     const parsed = (await (0, pgsql_parser_1.parse)(source));
+    const bytes = (0, util_1.utf8)(source);
     const out = [];
     for (const entry of parsed.stmts ?? []) {
         const createFnStmt = entry.stmt ? (0, walk_1.findAll)(entry.stmt, 'CreateFunctionStmt')[0] : undefined;
         if (!createFnStmt)
             continue;
         const start = entry.stmt_location ?? 0;
-        const len = entry.stmt_len ?? source.length - start;
+        const len = entry.stmt_len ?? bytes.length - start;
         out.push({
-            text: source.slice(start, start + len),
+            text: (0, util_1.sliceBytes)(bytes, start, len),
             language: funcLanguage(createFnStmt),
             name: funcName(createFnStmt),
             file,
-            startLine: lineAtOffset(source, start) // 0-based line the definition begins on
+            startLine: (0, util_1.newlinesBeforeByte)(bytes, start) // 0-based line the definition begins on
         });
     }
     return out;
@@ -129,7 +125,9 @@ async function lintSqlText(source, options = {}) {
         inputs = await sqlTextDefinitions(source);
     }
     catch (err) {
-        return { file: '<source>', findings: [], parseError: err.message };
+        const message = err.message;
+        const finding = parseErrorFinding(message, '<file>', 1, options);
+        return { file: '<source>', findings: finding ? [finding] : [], parseError: message };
     }
     const findings = await lintInputs(inputs, options);
     return { file: '<source>', findings };
@@ -140,7 +138,12 @@ async function lintInputs(inputs, options) {
     for (const input of inputs) {
         const subject = input.name ?? '<anonymous>';
         const startLine = input.startLine ?? 0;
-        const { problems, suppressed } = await (0, engine_1.lintDefinition)(input.text, input.language, subject, options);
+        const { problems, suppressed, parseError } = await (0, engine_1.lintDefinition)(input.text, input.language, subject, options);
+        if (parseError) {
+            const finding = parseErrorFinding(parseError, subject, startLine + 1, options);
+            if (finding)
+                findings.push(finding);
+        }
         const absLine = (p) => startLine + p.line; // p.line is 1-based within input.text
         for (const p of problems)
             findings.push(toFinding(p, subject, absLine(p), false));
@@ -171,6 +174,7 @@ function toFinding(p, subject, line, acknowledged, reason, scope) {
     return meta;
 }
 const RULE_CODE = {
+    [engine_1.PARSE_ERROR.id]: engine_1.PARSE_ERROR.code,
     'no-set-search-path': 'C1',
     'no-variable-conflict': 'C2',
     'require-qualified-refs': 'C3',
@@ -179,6 +183,28 @@ const RULE_CODE = {
 function codeFor(ruleId) {
     return RULE_CODE[ruleId] ?? ruleId;
 }
+/**
+ * A definition (or file) the parser rejected. Nothing in it was checked, so
+ * the failure is reported as a finding rather than dropped: an unparseable
+ * function would otherwise pass every rule by default. Severity is configured
+ * like any rule (`parse-error` / `P0`): `error` unless downgraded, and `off`
+ * drops it like any other rule turned off.
+ */
+function parseErrorFinding(message, subject, line, options) {
+    const severity = (0, engine_1.severityOf)(engine_1.PARSE_ERROR, options.severity);
+    if (severity === 'off')
+        return undefined;
+    return {
+        ruleId: engine_1.PARSE_ERROR.id,
+        code: engine_1.PARSE_ERROR.code,
+        line,
+        message: `Definition could not be parsed, so no rule was checked: ${message}`,
+        hint: 'Fix the syntax (or, if the parser is wrong, downgrade `parse-error` in the lint config).',
+        severity,
+        subject,
+        acknowledged: false
+    };
+}
 /** Recursively collect `.sql` files under a directory. */
 async function sqlFilesUnder(dir) {
     const out = [];

package/index.d.ts

@@ -15,7 +15,7 @@ export { changedFiles, changedSqlFiles, resolveChangedBase } from './changed';
 export type { LintConfigFile, LoadedLintConfig } from './config';
 export { CONFIG_FILENAMES, configDir, findConfigFile, loadLintConfig } from './config';
 export type { LintOptions } from './engine';
-export { lintDefinition, severityOf } from './engine';
+export { lintDefinition, PARSE_ERROR, severityOf } from './engine';
 export { FileFinding, FileLintOptions, FileReport, filesAdapter, lintFiles, lintSource, lintSqlText, resolveSqlFiles, sqlTextAdapter, sqlTextDefinitions } from './file-runner';
 export { applyIgnore, makeIgnoreFilter } from './ignore';
 export type { CallOptions, Linter, LinterConfig } from './linter';

package/index.js

@@ -12,7 +12,7 @@
  * with `createLinter({ rules, severity })` and pass your own rules in.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defineRule = exports.Suppressions = exports.DEFAULT_KEYWORDS = exports.requireQualifiedRefs = exports.noVariableConflict = exports.noSetSearchPath = exports.noDynamicSql = exports.LINT_RULES_BY_ID = exports.LINT_RULES_BY_CODE = exports.LINT_RULES = exports.parseUnit = exports.createLinter = exports.makeIgnoreFilter = exports.applyIgnore = exports.sqlTextDefinitions = exports.sqlTextAdapter = exports.resolveSqlFiles = exports.lintSqlText = exports.lintSource = exports.lintFiles = exports.filesAdapter = exports.severityOf = exports.lintDefinition = exports.loadLintConfig = exports.findConfigFile = exports.configDir = exports.CONFIG_FILENAMES = exports.resolveChangedBase = exports.changedSqlFiles = exports.changedFiles = void 0;
+exports.defineRule = exports.Suppressions = exports.DEFAULT_KEYWORDS = exports.requireQualifiedRefs = exports.noVariableConflict = exports.noSetSearchPath = exports.noDynamicSql = exports.LINT_RULES_BY_ID = exports.LINT_RULES_BY_CODE = exports.LINT_RULES = exports.parseUnit = exports.createLinter = exports.makeIgnoreFilter = exports.applyIgnore = exports.sqlTextDefinitions = exports.sqlTextAdapter = exports.resolveSqlFiles = exports.lintSqlText = exports.lintSource = exports.lintFiles = exports.filesAdapter = exports.severityOf = exports.PARSE_ERROR = exports.lintDefinition = exports.loadLintConfig = exports.findConfigFile = exports.configDir = exports.CONFIG_FILENAMES = exports.resolveChangedBase = exports.changedSqlFiles = exports.changedFiles = void 0;
 var changed_1 = require("./changed");
 Object.defineProperty(exports, "changedFiles", { enumerable: true, get: function () { return changed_1.changedFiles; } });
 Object.defineProperty(exports, "changedSqlFiles", { enumerable: true, get: function () { return changed_1.changedSqlFiles; } });
@@ -24,6 +24,7 @@ Object.defineProperty(exports, "findConfigFile", { enumerable: true, get: functi
 Object.defineProperty(exports, "loadLintConfig", { enumerable: true, get: function () { return config_1.loadLintConfig; } });
 var engine_1 = require("./engine");
 Object.defineProperty(exports, "lintDefinition", { enumerable: true, get: function () { return engine_1.lintDefinition; } });
+Object.defineProperty(exports, "PARSE_ERROR", { enumerable: true, get: function () { return engine_1.PARSE_ERROR; } });
 Object.defineProperty(exports, "severityOf", { enumerable: true, get: function () { return engine_1.severityOf; } });
 var file_runner_1 = require("./file-runner");
 Object.defineProperty(exports, "filesAdapter", { enumerable: true, get: function () { return file_runner_1.filesAdapter; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgsql/lint",
-  "version": "18.3.3",
+  "version": "18.3.5",
   "author": "Constructive <developers@constructive.io>",
   "description": "Source-level SQL/PL/pgSQL convention linter: fully-qualified references, no search_path, no dynamic SQL, with ESLint-style inline waivers. Pure AST, no database.",
   "main": "index.js",
@@ -34,12 +34,12 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@pgsql/traverse": "18.8.2",
+    "@pgsql/traverse": "18.8.3",
     "chalk": "^4.1.0",
     "git-changed": "^0.3.0",
     "libpg-query": "18.2.1",
     "minimist": "1.2.8",
-    "pgsql-parser": "18.3.2"
+    "pgsql-parser": "18.3.3"
   },
   "devDependencies": {
     "@types/minimist": "^1.2.5",
@@ -57,5 +57,5 @@
     "search_path",
     "dynamic-sql"
   ],
-  "gitHead": "d49ec05b871e46de411a2af1630c234d4a2bb38f"
+  "gitHead": "ce03e09604aea4b0fd7d62cf23e72d0de8ad33c1"
 }

package/parse-unit.js

@@ -13,19 +13,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseUnit = parseUnit;
 const libpg_query_1 = require("libpg-query");
 const pgsql_parser_1 = require("pgsql-parser");
+const util_1 = require("./util");
 const walk_1 = require("./walk");
-/** Count newlines in `s[0..offset)` — i.e. how many lines precede `offset`. */
-function newlinesBefore(s, offset) {
+/** Absolute 1-based line of a char offset within `text`. */
+function lineOf(text, offset) {
     let n = 0;
-    const end = Math.min(offset, s.length);
+    const end = Math.min(offset, text.length);
     for (let i = 0; i < end; i++)
-        if (s.charCodeAt(i) === 10)
+        if (text.charCodeAt(i) === 10)
             n++;
-    return n;
-}
-/** Absolute 1-based line of a char offset within `text`. */
-function lineOf(text, offset) {
-    return newlinesBefore(text, offset) + 1;
+    return n + 1;
 }
 /** The body string of a `CreateFunctionStmt` (`AS $$ … $$`), or null. */
 function functionBody(createFnStmt) {
@@ -128,13 +125,14 @@ async function parseUnit(text, language, name) {
     const dynamicSql = [];
     const lang = language.toLowerCase();
     if (lang === 'sql' && body !== null && bodyStartLine !== undefined) {
-        // A SQL-language body is itself SQL: parse it whole. Locations are
-        // relative to the body, so re-anchor them onto the definition.
+        // A SQL-language body is itself SQL: parse it whole. Locations are byte
+        // offsets relative to the body, so re-anchor them onto the definition.
         try {
             const ast = await (0, pgsql_parser_1.parse)(body);
+            const bodyBytes = (0, util_1.utf8)(body);
             fragments.push({
                 ast,
-                lineForOffset: (offset) => bodyStartLine + newlinesBefore(body, offset)
+                lineForOffset: (offset) => bodyStartLine + (0, util_1.newlinesBeforeByte)(bodyBytes, offset)
             });
         }
         catch {

package/types.d.ts

@@ -75,6 +75,12 @@ export interface LintResult {
     problems: LintProblem[];
     /** Suppressed findings, kept for the "accepted risk" report bucket. */
     suppressed: SuppressedProblem[];
+    /**
+     * Set when the definition could not be parsed. `problems` is then empty
+     * because no rule ran — not because the definition is clean — so a consumer
+     * must report this rather than treat the result as a pass.
+     */
+    parseError?: string;
 }
 /** Static metadata for a lint rule. */
 export interface LintRuleMeta {

package/util.d.ts

@@ -1,2 +1,16 @@
-/** Absolute 1-based line of a char offset within `text`. */
-export declare function lineOfOffset(text: string, offset: number): number;
+/**
+ * Offset arithmetic. Every location libpg_query reports — `stmt_location`,
+ * `stmt_len`, a node's `location` — is a **byte** offset into the UTF-8 source,
+ * while a JS string is indexed by UTF-16 code unit. The two agree only while
+ * the text is pure ASCII: one `→` or `—` earlier in a file shifts every later
+ * offset, and a definition sliced by character then fails to parse. So slice
+ * and count newlines over the UTF-8 bytes, never over the string.
+ */
+/** The UTF-8 bytes of `text` — the coordinate space parser offsets live in. */
+export declare function utf8(text: string): Uint8Array;
+/** `bytes[start, start + len)` decoded back to a string. */
+export declare function sliceBytes(bytes: Uint8Array, start: number, len: number): string;
+/** Count newline bytes in `bytes[0, byteOffset)` — the 0-based line the offset sits on. */
+export declare function newlinesBeforeByte(bytes: Uint8Array, byteOffset: number): number;
+/** Absolute 1-based line of a parser (byte) offset within `text`. */
+export declare function lineOfOffset(text: string, byteOffset: number): number;

package/util.js

@@ -1,12 +1,37 @@
 "use strict";
+/**
+ * Offset arithmetic. Every location libpg_query reports — `stmt_location`,
+ * `stmt_len`, a node's `location` — is a **byte** offset into the UTF-8 source,
+ * while a JS string is indexed by UTF-16 code unit. The two agree only while
+ * the text is pure ASCII: one `→` or `—` earlier in a file shifts every later
+ * offset, and a definition sliced by character then fails to parse. So slice
+ * and count newlines over the UTF-8 bytes, never over the string.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.utf8 = utf8;
+exports.sliceBytes = sliceBytes;
+exports.newlinesBeforeByte = newlinesBeforeByte;
 exports.lineOfOffset = lineOfOffset;
-/** Absolute 1-based line of a char offset within `text`. */
-function lineOfOffset(text, offset) {
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** The UTF-8 bytes of `text` — the coordinate space parser offsets live in. */
+function utf8(text) {
+    return encoder.encode(text);
+}
+/** `bytes[start, start + len)` decoded back to a string. */
+function sliceBytes(bytes, start, len) {
+    return decoder.decode(bytes.subarray(start, start + len));
+}
+/** Count newline bytes in `bytes[0, byteOffset)` — the 0-based line the offset sits on. */
+function newlinesBeforeByte(bytes, byteOffset) {
     let n = 0;
-    const end = Math.min(Math.max(offset, 0), text.length);
+    const end = Math.min(Math.max(byteOffset, 0), bytes.length);
     for (let i = 0; i < end; i++)
-        if (text.charCodeAt(i) === 10)
+        if (bytes[i] === 10)
             n++;
-    return n + 1;
+    return n;
+}
+/** Absolute 1-based line of a parser (byte) offset within `text`. */
+function lineOfOffset(text, byteOffset) {
+    return newlinesBeforeByte(utf8(text), byteOffset) + 1;
 }