Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,9 @@ Do not run the same query again and again. If `gulliver_run` returns `block` wit
- When asked what costs the most: `gulliver_top`. Offer only the `fixed_sql` it marks as the same rows, and say
whether the saving is `exact` or `heuristic`.

Syntax failures stay blocked. Read the line/column in `statement.reason`, fix the syntax or choose the
correct `--dialect`, then retry. Tokenizer failures explicitly mark their location as end-of-input fallback.

## Status values

| status | meaning | what to do |
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
- `gulliver diff` says which columns differ for changed keys ("Rows differ in: country (1 key)"), computed inside the existing keys query, so no extra queries run and no values leave the engine (#46, #69).
- `gulliver prune [--older-than 30d] [--keep-last N] [--dry-run]` cleans up old receipts and expired approvals while `gulliver audit verify` keeps passing (#79).
- `gulliver lint --baseline FILE` / `--write-baseline [FILE]` and `[lint] baseline`: record today's findings and report (and fail on) only new ones on an existing repo. Findings match by path, rule and source line, so moved lines still match and copies or edits are new. The JSON result gets `baselined` and `baseline_fixed` (#45).
- SQL syntax errors show readable parser details and line/column positions instead of internal token dumps. Syntax-specific retry advice is distinct from statement restrictions; tokenizer failures use an explicit end-of-input fallback (#128).

### Thanks
- @bfs2021 for refusing NaN, infinite and negative budget limits (#40) and the GV001 fix for EXISTS subqueries (#50).
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -692,6 +692,10 @@ Fixes are applied as small text edits (comments, line endings and Jinja stay) an
edited statement re-parses to exactly the rewritten tree. Details:
[docs/features/lint-ci.md](https://github.com/laaielichter/Gulliver/blob/main/docs/features/lint-ci.md).

SQL syntax errors include readable line/column diagnostics and syntax-specific retry advice.
Tokenizer failures use an explicitly labeled end-of-input fallback. See the
[syntax-error guide](docs/features/lint-ci.md#sql-syntax-errors).

### `gulliver review` and the GitHub Action

```bash
Expand Down
15 changes: 15 additions & 0 deletions docs/features/lint-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,21 @@ join named this way, or a fact-to-dimension lookup where repeating the value is
(`sum(p.price) from order_items i join products p on p.id = i.product_id`), is flagged too; ignore it there
with `-- gulliver: ignore GV015`.

## SQL syntax errors

Syntax errors include a line and column, the highlighted token when available, and a short
parser description. For example, `gulliver lint "SELECT a b c FROM t" --json` reports:

```text
Could not parse SQL for dialect 'duckdb' at line 1, column 12, near "c": Invalid expression / Unexpected token.
```

The query stays blocked (exit code `2`). The next step is to fix the syntax or select the correct
engine with `--dialect`; restrictions on multiple statements and non-SELECT statements are unchanged.
If tokenization fails, such as an unterminated quote or comment, the message explicitly uses the
end of input as a fallback location, not the opening quote's position. File lint reports these errors
as GV900 and keeps its configured severity and exit-code policy.

## Limits

- Files mode needs no database. GV004 (missing partition filter) and the same-rows fixes need metadata, so
Expand Down
3 changes: 3 additions & 0 deletions llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,9 @@ Do not run the same query again and again. If `gulliver_run` returns `block` wit
- When asked what costs the most: `gulliver_top`. Offer only the `fixed_sql` it marks as the same rows, and say
whether the saving is `exact` or `heuristic`.

Syntax failures stay blocked. Read the line/column in `statement.reason`, fix the syntax or choose the
correct `--dialect`, then retry. Tokenizer failures explicitly mark their location as end-of-input fallback.

## Status values

| status | meaning | what to do |
Expand Down
3 changes: 3 additions & 0 deletions skills/gulliver/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,9 @@ and returns a counterexample when rows differ; a test is not a proof, so labels
| GV015 fan-trap | aggregate the many side in a subquery first, then join |
| GV016 order-by-random | for random row sampling, consider TABLESAMPLE / USING SAMPLE; check engine semantics |

Syntax failures stay blocked. Read the line/column in `statement.reason`, fix the syntax or choose the
correct `--dialect`, then retry. Tokenizer failures explicitly mark their location as end-of-input fallback.

## Reading the numbers honestly

- `estimate.accuracy`: `exact` (BigQuery dry run), `upper_bound` (Snowflake partitions), `heuristic` (DuckDB,
Expand Down
9 changes: 5 additions & 4 deletions src/gulliver/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
from .lint import Finding, _has_aggregation, _outer_select, lint, summarize
from .sampling import sample_query, sampling_tree
from .security import policy_for
from .sqlsafety import Statement, base_tables, classify, table_ref
from .sqlsafety import SYNTAX_ERROR_NEXT_STEP, Statement, base_tables, classify, table_ref
from .store import Store

DEFAULT_FRACTIONS = (0.01, 0.03, 0.1)
Expand Down Expand Up @@ -142,7 +142,8 @@ def lint_sql(sql: str, dialect: str = "duckdb") -> dict[str, Any]:
statement = classify(sql, dialect)
if statement.kind == "block" or statement.select is None:
return {"status": "block", "statement": statement.public(), "lint": [],
"next_step": "Send a single SELECT (or CREATE/INSERT ... SELECT)."}
"next_step": SYNTAX_ERROR_NEXT_STEP if statement.parse_error else
"Send a single SELECT (or CREATE/INSERT ... SELECT)."}
findings = lint(statement.select, dialect)
counts = summarize(findings)
state = "block" if counts["error"] else ("warn" if counts["warn"] else "ok")
Expand Down Expand Up @@ -227,7 +228,7 @@ def _preflight_core(settings: Settings, sql: str, connection: str | None) -> dic
}
if statement.kind == "block":
base.update(status="block", gate={"status": "block", "blocks": [statement.reason]},
next_step=statement.reason if statement.code else
next_step=SYNTAX_ERROR_NEXT_STEP if statement.parse_error else statement.reason if statement.code else
"Rewrite it as one SELECT (or CREATE/INSERT ... SELECT). " + statement.reason)
return base

Expand Down Expand Up @@ -350,7 +351,7 @@ def _rehearse(settings: Settings, sql: str, connection: str | None, fractions: l
"sql_hash": statement.sql_hash, "statement": statement.public(),
}
if statement.kind == "block":
result.update(status="block", next_step=statement.reason)
result.update(status="block", next_step=SYNTAX_ERROR_NEXT_STEP if statement.parse_error else statement.reason)
return result
if sample not in ("largest", "all"):
return _error("sample must be 'largest' or 'all'")
Expand Down
10 changes: 5 additions & 5 deletions src/gulliver/lint_files.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
from .config import ConfigError, find_config_file
from .lineage import BLOCK_RE, COMMENT_RE, CONFIG_RE, EXPR_RE, REF_RE, SOURCE_RE, THIS_RE
from .lint import RULES, SEVERITY_ORDER, Finding, lint
from .sqlsafety import classify
from .sqlsafety import SYNTAX_ERROR_NEXT_STEP, classify, parse_error_reason

try: # Python 3.11+
import tomllib # type: ignore[import-not-found]
Expand Down Expand Up @@ -775,9 +775,9 @@ def add(rule: str, severity: str, message: str, fix: str, r_start: int, r_end: i
try:
chunks = split_statements(rendered.text, dialect)
except SqlglotError as exc:
first = str(exc).splitlines()[0] if str(exc) else "tokenizer error"
add("GV900", "warn", f"Could not read the SQL for dialect '{dialect}': {first}. Nothing in this file was "
"checked.", "Check the dialect (--dialect or [lint] dialect), or fix the syntax.", 0, 0, 0)
reason = parse_error_reason(exc, rendered.text, dialect)
add("GV900", "warn", f"{reason} Nothing in this file was checked.", SYNTAX_ERROR_NEXT_STEP,
len(rendered.text), len(rendered.text), 0)
chunks = []
statement_lines: dict[int, int] = {}
for chunk in chunks:
Expand All @@ -794,7 +794,7 @@ def add(rule: str, severity: str, message: str, fix: str, r_start: int, r_end: i
if statement is None or statement.kind == "block" or statement.select is None:
if reason.startswith("Could not parse"):
add("GV900", "warn", f"{reason.rstrip('.')}. This statement was not checked.",
"Check the dialect (--dialect or [lint] dialect), or the Jinja in this model.",
SYNTAX_ERROR_NEXT_STEP,
chunk.start, chunk.tokens[0].end + 1, chunk.index)
else:
line = statement_lines[chunk.index]
Expand Down
38 changes: 34 additions & 4 deletions src/gulliver/sqlsafety.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,13 @@
from __future__ import annotations

import hashlib
import json
import re
from dataclasses import dataclass, field

import sqlglot
from sqlglot import exp
from sqlglot.errors import SqlglotError
from sqlglot.errors import ParseError, SqlglotError, TokenError

from .security import SecurityPolicy
from .security import check as security_check
Expand All @@ -28,6 +30,7 @@
# Statements that change data or schema. Inside another statement (a CTE such as WITH d AS (DELETE ... RETURNING *))
# they would run as a side effect of a read or of an INSERT/CREATE ... SELECT, so they are refused there.
DATA_CHANGING = (exp.Insert, exp.Delete, exp.Update, exp.Create, exp.Drop, exp.Merge)
SYNTAX_ERROR_NEXT_STEP = "Fix the syntax error and try again. If the SQL is for another engine, set --dialect."


@dataclass
Expand All @@ -41,6 +44,7 @@ class Statement:
target: str | None = None # write target table
tables: list[str] = field(default_factory=list)
code: str = "" # GS001-GS004 when a security rule refused it
parse_error: bool = False # internal routing for syntax-specific advice

@property
def sql_hash(self) -> str:
Expand Down Expand Up @@ -68,6 +72,32 @@ def _strip_trailing(sql: str) -> str:
return sql.strip().rstrip(";").strip()


def parse_error_reason(exc: SqlglotError, sql: str, dialect: str) -> str:
"""Format parser details without internal token dumps or ANSI-highlighted exception text.

TokenError has no structured position. Report the end of input explicitly as a fallback,
rather than guessing a quote's opening position from dialect-specific tokenization rules.
"""
details = exc.errors[0] if isinstance(exc, ParseError) and exc.errors else {}
line, column = details.get("line"), details.get("col")
if isinstance(line, int) and line > 0 and isinstance(column, int) and column > 0:
location = f"line {line}, column {column}"
if highlight := details.get("highlight"):
location += f", near {json.dumps(highlight, ensure_ascii=False)}"
else:
line = sql.count("\n") + 1
column = len(sql.rsplit("\n", 1)[-1]) + 1
location = f"line {line}, column {column} (end of input)"
if isinstance(exc, TokenError):
description = "Could not tokenize SQL; check for an unterminated quote or comment"
else:
description = str(details.get("description") or "Syntax error").split("<Token", 1)[0].strip()
description = re.sub(r"\s+but got$", "", description)
if not description or "TokenType" in description:
description = "Unexpected token"
return f"Could not parse SQL for dialect '{dialect}' at {location}: {description.rstrip('.')}."


def base_tables(tree: exp.Expression, dialect: str) -> list[exp.Table]:
"""Physical tables (and table functions such as read_parquet) referenced by a query.

Expand Down Expand Up @@ -110,10 +140,10 @@ def _classify(sql: str, dialect: str) -> Statement:
if not text:
return Statement(sql, dialect, "block", reason="Empty SQL.")
try:
trees = [t for t in sqlglot.parse(text, read=dialect) if t is not None]
# Keep leading whitespace so parser positions refer to the SQL supplied by the caller.
trees = [t for t in sqlglot.parse(sql, read=dialect) if t is not None]
except SqlglotError as exc: # ParseError and TokenError (e.g. Postgres `IN ($1,$2)`, an open quote)
first = str(exc).splitlines()[0] if str(exc) else "parse error"
return Statement(sql, dialect, "block", reason=f"Could not parse SQL for dialect '{dialect}': {first}")
return Statement(sql, dialect, "block", reason=parse_error_reason(exc, sql, dialect), parse_error=True)
if len(trees) != 1:
return Statement(sql, dialect, "block", reason="Send exactly one statement at a time.")
tree = trees[0]
Expand Down
31 changes: 31 additions & 0 deletions tests/test_cli_and_mcp.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
import asyncio
import json

import pytest

from gulliver.cli import main
from gulliver.mcp_server import build_server, export_tools

Expand Down Expand Up @@ -97,3 +99,32 @@ def test_cli_translate_output_file(tmp_path, capsys):
data = json.loads(capsys.readouterr().out)
assert data["warnings"] # still printed
assert out.read_text(encoding="utf-8") == data["sql"]


@pytest.mark.parametrize("command", ["lint", "preflight", "rehearse", "run"])
@pytest.mark.parametrize("sql", ["SELECT 1 FROM", "SELECT a b c FROM t", "SELECT 'abc"])
def test_cli_syntax_errors_stay_blocked_with_actionable_advice(command, sql, demo_db, state, capsys):
assert main(["--dsn", demo_db, command, "--json", sql]) == 2
result = json.loads(capsys.readouterr().out)
assert result["status"] == "block"
assert result["next_step"] == (
"Fix the syntax error and try again. If the SQL is for another engine, set --dialect."
)
reason = result["statement"]["reason"]
assert "line 1, column " in reason
assert "<Token" not in reason and "TokenType" not in reason


@pytest.mark.parametrize("sql", ["DROP TABLE t", "SELECT 1; SELECT 2"])
def test_cli_non_syntax_blocks_keep_existing_advice(sql, demo_db, state, capsys):
for command in ("lint", "preflight", "rehearse", "run"):
assert main(["--dsn", demo_db, command, "--json", sql]) == 2
result = json.loads(capsys.readouterr().out)
if command == "lint":
assert result["next_step"] == "Send a single SELECT (or CREATE/INSERT ... SELECT)."
elif command == "rehearse":
assert result["next_step"] == result["statement"]["reason"]
else:
assert result["next_step"] == (
"Rewrite it as one SELECT (or CREATE/INSERT ... SELECT). " + result["statement"]["reason"]
)
14 changes: 14 additions & 0 deletions tests/test_lint_report.py
Original file line number Diff line number Diff line change
Expand Up @@ -635,3 +635,17 @@ def test_write_baseline_without_any_path_is_refused(state, tmp_path, capsys):
def test_lint_baseline_key_must_be_a_path():
with pytest.raises(ConfigError):
lint_config_from_mapping({"baseline": 3})


@pytest.mark.parametrize("sql", ["SELECT 1 FROM", "SELECT a b c FROM t", "SELECT 'abc"])
def test_file_syntax_errors_have_readable_messages(tmp_path, sql):
result = lint_file(_write(tmp_path / "bad.sql", sql))
finding, = [f for f in result.findings if f.rule == "GV900"]
assert "line 1, column " in finding.message
assert "<Token" not in finding.message and "TokenType" not in finding.message
assert finding.fix == (
"Fix the syntax error and try again. If the SQL is for another engine, set --dialect."
)
if sql == "SELECT 'abc":
assert (finding.line, finding.col) == (1, len(sql) + 1)
assert "end of input" in finding.message
28 changes: 28 additions & 0 deletions tests/test_sqlsafety.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
import pytest

from gulliver.sqlsafety import classify, sql_fingerprint


Expand Down Expand Up @@ -57,3 +59,29 @@ def test_sql_that_cannot_be_tokenized_is_blocked_not_raised():
("SELECT g FROM generate_series($3,$4) g", "postgres"), ("SELECT 'oops AS a", "duckdb")):
st = classify(sql, dialect)
assert st.kind == "block" and "Could not parse" in st.reason


@pytest.mark.parametrize("dialect", ["duckdb", "postgres", "bigquery", "snowflake"])
@pytest.mark.parametrize("sql, location, description", [
("SELECT 1 FROM", 'line 1, column 13, near "FROM"', "Expected table name."),
("SELECT FROM WHERE (", 'line 1, column 17, near "WHERE"', "Expected table name."),
("SELECT a b c FROM t", 'line 1, column 12, near "c"', "Invalid expression / Unexpected token."),
("\n SELECT a b c FROM t", 'line 2, column 14, near "c"', "Invalid expression / Unexpected token."),
])
def test_syntax_error_message_uses_structured_details(sql, location, description, dialect):
statement = classify(sql, dialect)
assert statement.kind == "block"
assert statement.reason == f"Could not parse SQL for dialect '{dialect}' at {location}: {description}"
assert "<Token" not in statement.reason and "TokenType" not in statement.reason


@pytest.mark.parametrize("sql", ["SELECT 'abc", "SELECT /* unclosed", "\nSELECT 'café\nhello"])
def test_tokenizer_failure_has_an_explicit_end_of_input_fallback(sql):
statement = classify(sql)
line = sql.count("\n") + 1
column = len(sql.rsplit("\n", 1)[-1]) + 1
assert statement.kind == "block"
assert statement.reason == (
f"Could not parse SQL for dialect 'duckdb' at line {line}, column {column} (end of input): "
"Could not tokenize SQL; check for an unterminated quote or comment."
)