feat: per-statement linting with token-wide error spans (#161)

- sqlLinter now lints each statement via SqlStructureAnalyzer, reporting
errors for every broken statement instead of only the first parse
failure
- SqlStatement carries parse errors so the linter reuses the analyzer's
  per-statement parse (no double-parsing; cached by content)
- Diagnostic spans widen to cover the offending token instead of one
char
- New SqlLinterConfig options: perStatement (default true) and
  structureAnalyzer (share an instance to reuse its cache)

Author: mscolnick

README.md

@@ -4,7 +4,7 @@ A CodeMirror extension for SQL linting and visual gutter indicators. Built by an
 
 ## Features
 
-- ⚡ **Real-time validation** - SQL syntax checking as you type with detailed error messages
+- ⚡ **Real-time validation** - Per-statement SQL syntax checking as you type, with detailed error messages for every broken statement
 - 🎨 **Visual gutter** - Color-coded statement indicators and error highlighting
 - 💡 **Hover tooltips** - Schema info, keywords, and column details on hover
 - 🔮 **CTE autocomplete** - Auto-complete support for CTEs

_typos.toml

@@ -3,4 +3,8 @@
 extend-ignore-re = ["(#|//)\\s*typos:ignore-next-line\\n.*"]
 
 [files]
-extend-exclude = ["src/data/duckdb-keywords.json"]
+extend-exclude = [
+  "src/data/duckdb-keywords.json",
+  # Contains intentionally misspelled SQL (e.g. SELCT) to trigger parse errors
+  "src/sql/__tests__/diagnostics.test.ts",
+]

src/index.ts

@@ -1,5 +1,5 @@
 export { cteCompletionSource } from "./sql/cte-completion-source.js";
-export { sqlLinter } from "./sql/diagnostics.js";
+export { type SqlLinterConfig, sqlLinter } from "./sql/diagnostics.js";
 export { sqlExtension } from "./sql/extension.js";
 export type {
   KeywordTooltipData,

src/sql/__tests__/diagnostics.test.ts

@@ -1,17 +1,22 @@
-import { Text } from "@codemirror/state";
+import { EditorState, Text } from "@codemirror/state";
 import type { EditorView } from "@codemirror/view";
 import { describe, expect, it, vi } from "vitest";
-import { sqlLinter } from "../diagnostics.js";
+import { exportedForTesting, type SqlLinterConfig, sqlLinter } from "../diagnostics.js";
+import { NodeSqlParser } from "../parser.js";
 import type { SqlParser } from "../types.js";
 
-// Mock EditorView
-const _createMockView = (content: string) => {
-  const doc = Text.of(content.split("\n"));
+const { createLintSource } = exportedForTesting;
+
+const createMockView = (content: string) => {
   return {
-    state: { doc },
+    state: EditorState.create({ doc: content }),
   } as EditorView;
 };
 
+const lint = (content: string, config: SqlLinterConfig = {}) => {
+  return createLintSource(config)(createMockView(content));
+};
+
 describe("sqlLinter", () => {
   it("should create a linter extension", () => {
     const linter = sqlLinter();
@@ -48,3 +53,123 @@ describe("sqlLinter", () => {
     expect(linter).toBeDefined();
   });
 });
+
+describe("lint source", () => {
+  it("should return no diagnostics for an empty document", async () => {
+    expect(await lint("")).toEqual([]);
+  });
+
+  it("should return no diagnostics for a whitespace-only document", async () => {
+    expect(await lint("   \n\n  \t ")).toEqual([]);
+  });
+
+  it("should return no diagnostics for valid statements", async () => {
+    const diagnostics = await lint(
+      "SELECT * FROM users;\nINSERT INTO users (name) VALUES ('John');",
+    );
+    expect(diagnostics).toEqual([]);
+  });
+
+  it("should report one diagnostic per broken statement", async () => {
+    const doc = "SELCT * FROM users;\nSELECT * FORM users;\nDELETE FROMM users;";
+    const diagnostics = await lint(doc);
+
+    expect(diagnostics).toHaveLength(3);
+
+    const text = Text.of(doc.split("\n"));
+    expect(text.lineAt(diagnostics[0].from).number).toBe(1);
+    expect(text.lineAt(diagnostics[1].from).number).toBe(2);
+    expect(text.lineAt(diagnostics[2].from).number).toBe(3);
+    for (const diagnostic of diagnostics) {
+      expect(diagnostic.severity).toBe("error");
+      expect(diagnostic.source).toBe("sql-parser");
+    }
+  });
+
+  it("should position diagnostics in a broken statement that follows a valid one", async () => {
+    const doc = "SELECT * FROM users;\nSELCT * FROM orders;";
+    const diagnostics = await lint(doc);
+
+    expect(diagnostics).toHaveLength(1);
+    const secondStatementStart = doc.indexOf("SELCT");
+    expect(diagnostics[0].from).toBeGreaterThanOrEqual(secondStatementStart);
+    expect(diagnostics[0].to).toBeLessThanOrEqual(doc.length);
+  });
+
+  it("should not split statements on semicolons inside string literals", async () => {
+    const doc = "SELECT 'a; b' FROM users;\nSELCT * FROM orders;";
+    const diagnostics = await lint(doc);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].from).toBeGreaterThanOrEqual(doc.indexOf("SELCT"));
+  });
+
+  it("should not split statements on semicolons inside comments", async () => {
+    const doc = "SELECT 1 -- trailing; comment\n;\nSELCT * FROM orders;";
+    const diagnostics = await lint(doc);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].from).toBeGreaterThanOrEqual(doc.indexOf("SELCT"));
+  });
+
+  it("should widen the diagnostic span to cover the offending token", async () => {
+    // node-sql-parser reports this error at the "users" token
+    const doc = "SELECT 1 FROMM users;";
+    const diagnostics = await lint(doc);
+
+    expect(diagnostics).toHaveLength(1);
+    const { from, to } = diagnostics[0];
+    // The span should cover the whole token, not a single character
+    expect(doc.slice(from, to)).toBe("users");
+  });
+
+  it("should fall back to a one-character span when the error is not at a token", async () => {
+    // node-sql-parser reports this error at the ";" character
+    const doc = "SELECT * FROM users WHERE;";
+    const diagnostics = await lint(doc);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].to).toBe(diagnostics[0].from + 1);
+  });
+
+  it("should handle statements separated on the same line", async () => {
+    const doc = "SELECT 1; SELCT 2;";
+    const diagnostics = await lint(doc);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].from).toBeGreaterThanOrEqual(doc.indexOf("SELCT"));
+  });
+
+  it("should report a single diagnostic when perStatement is disabled", async () => {
+    const doc = "SELCT * FROM users;\nSELCT * FROM orders;";
+    const diagnostics = await lint(doc, { perStatement: false });
+
+    expect(diagnostics).toHaveLength(1);
+    const text = Text.of(doc.split("\n"));
+    expect(text.lineAt(diagnostics[0].from).number).toBe(1);
+  });
+
+  it("should keep diagnostics within statement bounds", async () => {
+    const doc = "SELECT * FROM users;\nSELECT FROM WHERE;\nSELECT 2;";
+    const diagnostics = await lint(doc);
+
+    expect(diagnostics.length).toBeGreaterThanOrEqual(1);
+    const stmtFrom = doc.indexOf("SELECT FROM");
+    const stmtTo = doc.indexOf("SELECT 2");
+    for (const diagnostic of diagnostics) {
+      expect(diagnostic.from).toBeGreaterThanOrEqual(stmtFrom);
+      expect(diagnostic.to).toBeLessThanOrEqual(stmtTo);
+      expect(diagnostic.to).toBeGreaterThanOrEqual(diagnostic.from);
+    }
+  });
+
+  it("should reuse errors from a provided structure analyzer without re-validating", async () => {
+    const parser = new NodeSqlParser();
+    const validateSpy = vi.spyOn(parser, "validateSql");
+
+    const diagnostics = await lint("SELCT 1;\nSELCT 2;", { parser });
+
+    expect(diagnostics).toHaveLength(2);
+    expect(validateSpy).not.toHaveBeenCalled();
+  });
+});

src/sql/diagnostics.ts

@@ -2,6 +2,7 @@ import { type Diagnostic, linter } from "@codemirror/lint";
 import type { Extension, Text } from "@codemirror/state";
 import type { EditorView } from "@codemirror/view";
 import { NodeSqlParser } from "./parser.js";
+import { type SqlStatement, SqlStructureAnalyzer } from "./structure-analyzer.js";
 import type { SqlParseError, SqlParser } from "./types.js";
 
 const DEFAULT_DELAY = 750;
@@ -14,19 +15,74 @@ export interface SqlLinterConfig {
   delay?: number;
   /** Custom SQL parser instance to use for validation */
   parser?: SqlParser;
+  /**
+   * Lint each statement in the document separately so every broken statement
+   * gets its own diagnostic, instead of stopping at the first parse error (default: true)
+   */
+  perStatement?: boolean;
+  /**
+   * Structure analyzer used to split the document into statements.
+   * Pass a shared instance (e.g. the one used by the gutter) to reuse its cache.
+   */
+  structureAnalyzer?: SqlStructureAnalyzer;
 }
 
 /**
- * Converts a SQL parse error to a CodeMirror diagnostic
+ * Extends an error span from `from` to cover the token at that position,
+ * so the squiggle covers the offending word instead of a single character.
+ */
+function tokenEndAt(doc: Text, from: number): number {
+  if (from >= doc.length) {
+    return doc.length;
+  }
+  const line = doc.lineAt(from);
+  const match = line.text.slice(from - line.from).match(/^[\w"'`.]+/);
+  return match ? from + match[0].length : Math.min(from + 1, doc.length);
+}
+
+/**
+ * Converts a SQL parse error (relative to the whole document) to a CodeMirror diagnostic
  */
 function convertToCodeMirrorDiagnostic(error: SqlParseError, doc: Text): Diagnostic {
-  const lineStart = doc.line(error.line).from;
-  const from = lineStart + Math.max(0, error.column - 1);
-  const to = from + 1;
+  const line = doc.line(Math.min(error.line, doc.lines));
+  const from = Math.min(line.from + Math.max(0, error.column - 1), doc.length);
+
+  return {
+    from,
+    to: tokenEndAt(doc, from),
+    severity: error.severity,
+    message: error.message,
+    source: "sql-parser",
+  };
+}
+
+/**
+ * Converts a SQL parse error whose line/column are relative to a statement's
+ * content into a CodeMirror diagnostic positioned in the document.
+ *
+ * Error line 1 corresponds to the statement's first line, with columns
+ * relative to `stmt.from` (the statement content is trimmed, so its first
+ * character is exactly at `stmt.from`).
+ */
+function convertStatementErrorToDiagnostic(
+  error: SqlParseError,
+  stmt: SqlStatement,
+  doc: Text,
+): Diagnostic {
+  let from: number;
+  if (error.line <= 1) {
+    from = stmt.from + Math.max(0, error.column - 1);
+  } else {
+    const line = doc.line(Math.min(stmt.lineFrom + error.line - 1, doc.lines));
+    from = line.from + Math.max(0, error.column - 1);
+  }
+  // Clamp within the statement's range in case the parser's reported
+  // position drifts (e.g. comments are stripped before parsing)
+  from = Math.max(stmt.from, Math.min(from, stmt.to));
 
   return {
     from,
-    to,
+    to: Math.max(from, Math.min(tokenEndAt(doc, from), stmt.to)),
     severity: error.severity,
     message: error.message,
     source: "sql-parser",
@@ -50,23 +106,36 @@ function convertToCodeMirrorDiagnostic(error: SqlParseError, doc: Text): Diagnos
  * ```
  */
 export function sqlLinter(config: SqlLinterConfig = {}): Extension {
+  return linter(createLintSource(config), {
+    delay: config.delay || DEFAULT_DELAY,
+  });
+}
+
+function createLintSource(config: SqlLinterConfig = {}) {
   const parser = config.parser || new NodeSqlParser();
+  const perStatement = config.perStatement !== false;
+  const analyzer = config.structureAnalyzer || new SqlStructureAnalyzer(parser);
 
-  return linter(
-    async (view: EditorView): Promise<Diagnostic[]> => {
-      const doc = view.state.doc;
-      const sql = doc.toString();
+  return async (view: EditorView): Promise<Diagnostic[]> => {
+    const doc = view.state.doc;
+    const sql = doc.toString();
 
-      if (!sql.trim()) {
-        return [];
-      }
+    if (!sql.trim()) {
+      return [];
+    }
 
+    if (!perStatement) {
       const errors = await parser.validateSql(sql, { state: view.state });
-
       return errors.map((error) => convertToCodeMirrorDiagnostic(error, doc));
-    },
-    {
-      delay: config.delay || DEFAULT_DELAY,
-    },
-  );
+    }
+
+    // Lint each statement independently so errors are reported for all
+    // broken statements, not just the first one in the document
+    const statements = await analyzer.analyzeDocument(view.state);
+    return statements.flatMap((stmt) =>
+      stmt.errors.map((error) => convertStatementErrorToDiagnostic(error, stmt, doc)),
+    );
+  };
 }
+
+export const exportedForTesting = { createLintSource };

src/sql/structure-analyzer.ts

@@ -1,5 +1,5 @@
 import type { EditorState } from "@codemirror/state";
-import type { SqlParser } from "./types.js";
+import type { SqlParseError, SqlParser } from "./types.js";
 
 /**
  * Represents a SQL statement with position information
@@ -19,6 +19,8 @@ export interface SqlStatement {
   type: "select" | "insert" | "update" | "delete" | "create" | "drop" | "alter" | "use" | "other";
   /** Whether this statement is syntactically valid */
   isValid: boolean;
+  /** Parse errors for this statement, with line/column relative to the statement content */
+  errors: SqlParseError[];
 }
 
 /**
@@ -128,6 +130,7 @@ export class SqlStructureAnalyzer {
         content: cleanContent,
         type,
         isValid: parseResult.success,
+        errors: parseResult.errors ?? [],
       });
 
       currentPosition += part.length;