fix(loader): report malformed parameter directives

docs/changelog.rst

@@ -9,6 +9,18 @@ important operational fixes.
 Recent Updates
 ==============
 
+v0.58.2 - SQL file parameter diagnostics
+------------------------------------------------------------------------------
+
+**Fixed:**
+
+* Malformed ``-- param:`` directives now produce actionable warnings that name
+  the SQL file, line number, and malformed directive. Structured log records
+  expose the numeric ``line_number`` and textual ``directive`` separately.
+  Non-strict loading continues to warn and skip malformed directives, while
+  strict loading continues to raise
+  :class:`~sqlspec.exceptions.SQLFileParseError`.
+
 v0.58.1 - Migration template configuration
 ------------------------------------------------------------------------------
 

pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.58.1"
+version = "0.58.2"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -331,7 +331,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.58.1"
+current_version = "0.58.2"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

sqlspec/loader.py

@@ -406,15 +406,19 @@ def _parse_directive_block(
                 params.append(_parse_parameter_declaration(param_match))
                 continue
             if PARAM_PREFIX_PATTERN.match(stripped):
+                line_number = base_line + idx + 1
                 if strict:
                     raise SQLFileParseError(
-                        file_path,
-                        file_path,
-                        ValueError(f"Malformed -- param: directive: {stripped}"),
-                        line=base_line + idx + 1,
+                        file_path, file_path, ValueError(f"Malformed -- param: directive: {stripped}"), line=line_number
                     )
                 log_with_context(
-                    logger, logging.WARNING, "sql.parse.param", file_path=file_path, line=stripped, status="malformed"
+                    logger,
+                    logging.WARNING,
+                    f"sql.parse.param: malformed parameter directive in {file_path} at line {line_number}: {stripped}",
+                    file_path=file_path,
+                    line_number=line_number,
+                    directive=stripped,
+                    status="malformed",
                 )
         return dialect, tuple(params), "\n".join(raw_lines[body_start:])
 

tests/unit/loader/test_param_directives.py

@@ -81,7 +81,14 @@ def test_malformed_param_warns_and_skips_by_default(caplog: pytest.LogCaptureFix
         statements = SQLFileLoader._parse_statements(content, "test.sql")
     assert statements["q"].parameters == ()
     assert statements["q"].sql == "select 1"
-    assert any("malformed" in r.message or "param" in r.message.lower() for r in caplog.records)
+    record = caplog.records[-1]
+    assert record.message == "sql.parse.param: malformed parameter directive in test.sql at line 2: -- param: oops"
+    assert record.__dict__["extra_fields"] == {
+        "file_path": "test.sql",
+        "line_number": 2,
+        "directive": "-- param: oops",
+        "status": "malformed",
+    }
 
 
 def test_malformed_param_raises_in_strict_mode() -> None: