sql-error-categorizer 0.1.0__tar.gz → 0.1.2__tar.gz

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: sql_error_categorizer
-Version: 0.1.0
+Version: 0.1.2
 Summary: This project analyses SQL statements and labels possible errors or complications.
 Project-URL: Repository, https://github.com/DavidePonzini/sql_error_categorizer
-Project-URL: Documentation, https://sql_error_categorizer.readthedocs.io/en/latest/index.html
+Project-URL: Documentation, https://sql-error-categorizer.readthedocs.io/en/latest/index.html
 Project-URL: Bug Tracker, https://github.com/DavidePonzini/sql_error_categorizer/issues
 Author-email: Davide Ponzini <davide.ponzini95@gmail.com>
 License-File: LICENSE
@@ -21,7 +21,7 @@ Description-Content-Type: text/markdown
 This project analyses SQL statements and labels possible errors or complications.
 
 # Credits
-Special thanks to Davide Miggiano for implementing most of the categorizers.
+Special thanks to Davide Miggiano and Flavio Venturini for their valuable contributions to the development of this project.
 
 # Limitations
 - Fully identified schema names are not supported when specifying column names (e.g. `SELECT schema.table.column [...]`)

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/README.md

@@ -2,7 +2,7 @@
 This project analyses SQL statements and labels possible errors or complications.
 
 # Credits
-Special thanks to Davide Miggiano for implementing most of the categorizers.
+Special thanks to Davide Miggiano and Flavio Venturini for their valuable contributions to the development of this project.
 
 # Limitations
 - Fully identified schema names are not supported when specifying column names (e.g. `SELECT schema.table.column [...]`)

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/docs/conf.py

@@ -7,8 +7,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'sql_error_categorizer'
-copyright = '2025, Davide Ponzini, Davide Miggiano'
-author = 'Davide Ponzini, Davide Miggiano'
+copyright = '2025, Davide Ponzini'
+author = 'Davide Ponzini'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

sql_error_categorizer-0.1.2/docs/index.rst

@@ -0,0 +1,38 @@
+.. dav-tools documentation master file, created by
+   sphinx-quickstart on Sun Jul 16 15:00:51 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to sql_error_categorizer's documentation!
+=================================================
+This project analyses SQL statements to highlight possible **errors**.
+The detection engine tokenises the input query and applies a set of rules.
+Additional rules are applied on the AST (Abstract Syntax Tree) generated from
+the query.
+When a rule matches, it reports the type of
+error together with the relevant context.
+
+The logic is implemented in `sql_query_analyzer/detectors/` and the available
+error identifiers are listed in `sql_query_analyzer/sql_errors.py`.
+
+Below you will find a short explanation that anyone can follow, followed by a
+section with technical details for developers.
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 4
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+Installation
+============
+``$ pip install sql_error_categorizer``
+

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sql_error_categorizer"
-version = "0.1.0"
+version = "0.1.2"
 authors = [
   { name="Davide Ponzini", email="davide.ponzini95@gmail.com" },
 ]
@@ -25,5 +25,5 @@ dependencies = [
 
 [project.urls]
 "Repository" = "https://github.com/DavidePonzini/sql_error_categorizer"
-"Documentation" = "https://sql_error_categorizer.readthedocs.io/en/latest/index.html"
+"Documentation" = "https://sql-error-categorizer.readthedocs.io/en/latest/index.html"
 "Bug Tracker" = "https://github.com/DavidePonzini/sql_error_categorizer/issues"

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/__init__.py

@@ -1,3 +1,5 @@
+'''Detect and categorize SQL errors in queries.'''
+
 # Hidden, internal use only
 from .detectors import BaseDetector as _BaseDetector, Detector as _Detector
 

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/catalog/__init__.py

@@ -1,4 +1,4 @@
-'''Builds a catalog of existing schemas/tables/columns by executing the provided SQL string in a temporary PostgreSQL database.'''
+'''Represents a catalog of database schemas, tables, and columns.'''
 
 from .catalog import Catalog, Schema, Table, Column, UniqueConstraintType
 import psycopg2

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/catalog/catalog.py

@@ -6,10 +6,12 @@ from copy import deepcopy
 
 # region UniqueConstraint
 class UniqueConstraintType(Enum):
+    '''Enumeration of unique constraint types.'''
     PRIMARY_KEY = 'PRIMARY KEY'
     UNIQUE = 'UNIQUE'
 
 class UniqueConstraint:
+    '''A unique constraint on a set of columns in a table.'''
     def __init__(self, columns: set[str], constraint_type: UniqueConstraintType) -> None:
         self.columns = columns
         self.constraint_type = constraint_type
@@ -19,6 +21,7 @@ class UniqueConstraint:
         return f'{indent}UniqueConstraint({self.constraint_type.value}: {self.columns})'
     
     def to_dict(self) -> dict:
+        '''Converts the UniqueConstraint to a dictionary.'''
         return {
             'columns': list(self.columns),  # JSON-friendly (list)
             'constraint_type': self.constraint_type.value,
@@ -26,6 +29,7 @@ class UniqueConstraint:
 
     @classmethod
     def from_dict(cls, data: dict) -> 'UniqueConstraint':
+        '''Creates a UniqueConstraint from a dictionary.'''
         return cls(columns=set(c.lower() for c in data['columns']),
                    constraint_type=UniqueConstraintType(data['constraint_type']))
 # endregion
@@ -33,6 +37,8 @@ class UniqueConstraint:
 # region Column
 @dataclass
 class Column:
+    '''A database table column, with type and constraints.'''
+
     name: str
     column_type: str = 'UNKNOWN'
     numeric_precision: int | None = None
@@ -45,6 +51,7 @@ class Column:
 
     @property
     def is_fk(self) -> bool:
+        '''Returns True if the column is a foreign key.'''
         return all([self.fk_schema, self.fk_table, self.fk_column])
 
     def __repr__(self, level: int = 0) -> str:
@@ -52,6 +59,7 @@ class Column:
         return f'{indent}Column(name=\'{self.name}\', type=\'{self.column_type}\', is_fk={self.is_fk}, is_nullable={self.is_nullable}, is_constant={self.is_constant})'
 
     def to_dict(self) -> dict:
+        '''Converts the Column to a dictionary.'''
         return {
             'name': self.name,
             'column_type': self.column_type,
@@ -65,6 +73,7 @@ class Column:
 
     @classmethod
     def from_dict(cls, data: dict) -> 'Column':
+        '''Creates a Column from a dictionary.'''
         return cls(
             name=data['name'],
             column_type=data['column_type'],
@@ -81,11 +90,13 @@ class Column:
 @dataclass
 class Table:
     '''A database table, with columns and unique constraints. Supports multiple columns with the same name (e.g. from joins).'''
+
     name: str
     unique_constraints: list[UniqueConstraint] = field(default_factory=list)
     columns: list[Column] = field(default_factory=list)
 
     def add_unique_constraint(self, columns: set[str], constraint_type: UniqueConstraintType) -> None:
+        '''Adds a unique constraint to the table.'''
         self.unique_constraints.append(UniqueConstraint(columns, constraint_type))
 
     def add_column(self,
@@ -98,6 +109,7 @@ class Table:
                    fk_schema: str | None = None,
                    fk_table: str | None = None,
                    fk_column: str | None = None) -> Column:
+        '''Adds a column to the table and returns it.'''
         column = Column(name=name,
                         column_type=column_type,
                         numeric_precision=numeric_precision,
@@ -139,6 +151,7 @@ class Table:
         return f'{indent}Table(name=\'{self.name}\', columns=[{columns}], unique_constraints=[{unique_constraints_str}])'
 
     def to_dict(self) -> dict:
+        '''Converts the Table to a dictionary.'''
         return {
             'name': self.name,
             'unique_constraints': [uc.to_dict() for uc in self.unique_constraints],
@@ -147,6 +160,7 @@ class Table:
 
     @classmethod
     def from_dict(cls, data: dict) -> 'Table':
+        '''Creates a Table from a dictionary.'''
         table = cls(name=data['name'])
         # Unique constraints first (so Column.is_pk works immediately on repr, etc.)
         for uc_data in data.get('unique_constraints', []):
@@ -163,6 +177,8 @@ class Table:
 # region Schema
 @dataclass
 class Schema:
+    '''A database schema, with tables and functions.'''
+
     name: str
     _tables: dict[str, Table] = field(default_factory=dict)
     functions: set[str] = field(default_factory=set)
@@ -198,6 +214,7 @@ class Schema:
         return f'{indent}Schema(name=\'{self.name}\', tables=[\n{tables}\n{indent}])'
 
     def to_dict(self) -> dict:
+        '''Converts the Schema to a dictionary.'''
         return {
             'name': self.name,
             'tables': {name: tbl.to_dict() for name, tbl in self._tables.items()},
@@ -205,6 +222,7 @@ class Schema:
 
     @classmethod
     def from_dict(cls, data: dict) -> 'Schema':
+        '''Creates a Schema from a dictionary.'''
         schema = cls(name=data['name'])
         for _, tbl_data in (data.get('tables') or {}).items():
             tbl = Table.from_dict(tbl_data)
@@ -215,6 +233,8 @@ class Schema:
 # region Catalog
 @dataclass
 class Catalog:
+    '''A database catalog, with schemas, tables, and columns.'''
+
     _schemas: dict[str, Schema] = field(default_factory=dict)
 
     def __getitem__(self, schema_name: str) -> Schema:
@@ -295,6 +315,7 @@ class Catalog:
 
     
     def to_dict(self) -> dict:
+        '''Converts the Catalog to a dictionary.'''
         return {
             'version': 1,
             'schemas': {name: sch.to_dict() for name, sch in self._schemas.items()},
@@ -302,6 +323,7 @@ class Catalog:
 
     @classmethod
     def from_dict(cls, data: dict) -> 'Catalog':
+        '''Creates a Catalog from a dictionary.'''
         cat = cls()
         for _, sch_data in (data.get('schemas') or {}).items():
             sch = Schema.from_dict(sch_data)
@@ -310,19 +332,23 @@ class Catalog:
 
     # String-based JSON (handy for DB/blob storage)
     def to_json(self, *, indent: int | None = 2) -> str:
+        '''Converts the Catalog to a JSON string.'''
         return json.dumps(self.to_dict(), indent=indent)
 
     @classmethod
     def from_json(cls, s: str) -> 'Catalog':
+        '''Creates a Catalog from a JSON string.'''
         return cls.from_dict(json.loads(s))
 
     # Convenience file helpers
     def save_json(self, path: str, *, indent: int | None = 2) -> None:
+        '''Saves the Catalog to a JSON file.'''
         with open(path, 'w', encoding='utf-8') as f:
             json.dump(self.to_dict(), f, indent=indent)
 
     @classmethod
     def load_json(cls, path: str) -> 'Catalog':
+        '''Loads a Catalog from a JSON file.'''
         with open(path, 'r', encoding='utf-8') as f:
             data = json.load(f)
         return cls.from_dict(data)

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/detectors/__init__.py

@@ -1,13 +1,17 @@
+'''SQL error detectors.'''
+
 from .. import catalog
 from ..query import Query
-from ..sql_errors import SqlErrors
 from .base import BaseDetector, DetectedError
+
+# exported detectors
 from .syntax import SyntaxErrorDetector
 from .semantic import SemanticErrorDetector
 from .logical import LogicalErrorDetector
 from .complications import ComplicationDetector
 
 class Detector:
+    '''Manages and runs SQL error detectors on a query.'''
     def __init__(self,
                  query: str,
                  *,

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/detectors/base.py

@@ -1,13 +1,16 @@
+'''Base classes for SQL error detectors.'''
+
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Any, Callable
 
 from ..sql_errors import SqlErrors
 from ..query import Query
-from ..catalog import Catalog
 
 @dataclass(repr=False)
 class DetectedError:
+    '''Represents a detected SQL error with its type and associated data.'''
+
     error: SqlErrors
     data: tuple[Any, ...] = field(default_factory=tuple)
 
@@ -23,6 +26,8 @@ class DetectedError:
         return hash((self.error, self.data))
 
 class BaseDetector(ABC):
+    '''Abstract base class for SQL error detectors.'''
+
     def __init__(self, *,
                  query: Query,
                  solutions: list[Query] = [],

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/detectors/complications.py

@@ -1,3 +1,5 @@
+'''Detector for complications in SQL queries.'''
+
 import difflib
 import re
 import sqlparse
@@ -12,6 +14,8 @@ from ..catalog import Catalog
 
 
 class ComplicationDetector(BaseDetector):
+    '''Detector for complications in SQL queries.'''
+
     def __init__(self,
                  *,
                  query: Query,

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/detectors/logical.py

@@ -1,3 +1,5 @@
+'''Detector for logical errors in SQL queries.'''
+
 import difflib
 import re
 import sqlparse
@@ -11,6 +13,7 @@ from ..catalog import Catalog
 
 
 class LogicalErrorDetector(BaseDetector):
+    '''Detector for logical errors in SQL queries.'''
     def __init__(self,
                  *,
                  query: Query,

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/detectors/semantic.py

@@ -1,3 +1,5 @@
+'''Detector for semantic errors in SQL queries.'''
+
 import difflib
 import re
 import sqlparse
@@ -14,6 +16,8 @@ from ..sql_errors import SqlErrors
 from ..catalog import Catalog
 
 class SemanticErrorDetector(BaseDetector):
+    '''Detector for semantic errors in SQL queries.'''
+    
     def __init__(self,
                  *,
                  query: Query,

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/detectors/syntax.py

@@ -1,18 +1,21 @@
+'''Detector for syntax errors in SQL queries.'''
+
 import difflib
 import re
 import sqlparse
 from sqlglot import exp
-from typing import Any, Callable
+from typing import Callable
 from copy import deepcopy
 
 from .base import BaseDetector, DetectedError
-from ..query import Query, Select
+from ..query import Query
 from ..sql_errors import SqlErrors
-from ..catalog import Catalog
 from .. import util
 
 
 class SyntaxErrorDetector(BaseDetector):
+    '''Detector for syntax errors in SQL queries.'''
+
     def __init__(self,
                  *,
                  query: Query,

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/query/__init__.py

@@ -1,3 +1,5 @@
+'''Query representation and manipulation.'''
+
 from .query import Query
 from .set_operations import SetOperation, BinarySetOperation, Union, Intersect, Except, Select
 from .util import *

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/query/set_operations/__init__.py

@@ -1,3 +1,5 @@
+'''Query representation as set operation trees.'''
+
 from .set_operation import SetOperation
 from .binary_set_operation import BinarySetOperation, Union, Intersect, Except
 from .select import Select

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/query/set_operations/select.py

@@ -187,7 +187,7 @@ class Select(SetOperation, TokenizedSQL):
             self._referenced_tables = self._get_referenced_tables()
         
         return self._referenced_tables
-
+    
     @property
     def output(self) -> Table:
         '''

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/query/smt.py

@@ -1,3 +1,5 @@
+'''Convert SQL expressions to Z3 expressions for logical reasoning.'''
+
 from typing import Any, Callable
 from sqlglot import exp
 from z3 import (

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/query/tokenized_sql.py

@@ -1,3 +1,5 @@
+'''Query representation as a list of tokens. Works even for invalid SQL.'''
+
 import sqlparse
 import sqlparse.tokens
 from sqlparse.tokens import Whitespace, Newline

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/query/util.py

@@ -1,18 +1,23 @@
+'''Utility functions for SQL query processing.'''
+
 import sqlparse
 from sqlparse.tokens import Whitespace, Newline
 from sqlglot.optimizer.normalize import normalize
 from sqlglot import exp
 
 def strip_ws(tokens: list[sqlparse.sql.Token]) -> list[sqlparse.sql.Token]:
+    '''Remove whitespace and newline tokens from a list of tokens.'''
     return [t for t in tokens if t.ttype not in (Whitespace, Newline)]
 
 def remove_parentheses(sql: str) -> str:
+    '''Remove outer parentheses from a SQL string.'''
     sql = sql.strip()
     while sql.startswith('(') and sql.endswith(')'):
         sql = sql[1:-1].strip()
     return sql
 
 def extract_DNF(expr) -> list[exp.Expression]:
+    '''Given a boolean expression, extract its Disjunctive Normal Form (DNF)'''
     dnf_expr = normalize(expr, dnf=True)
 
     if not isinstance(dnf_expr, exp.Or):
@@ -22,6 +27,7 @@ def extract_DNF(expr) -> list[exp.Expression]:
     return list(disjuncts)
 
 def extract_function_name(func_expr: exp.Func) -> str:
+    '''Extract the function name from a function expression.'''
     if isinstance(func_expr, exp.Anonymous):
         return func_expr.name.upper()
     return func_expr.__class__.__name__.lower()

{sql_error_categorizer-0.1.0 → sql_error_categorizer-0.1.2}/src/sql_error_categorizer/sql_errors.py

@@ -2,6 +2,7 @@ from enum import Enum
 
 
 class SqlErrors(Enum):
+    '''Enumeration of SQL error types with unique identifiers.'''
     SYN_1_OMITTING_CORRELATION_NAMES                                    = 1
     SYN_2_AMBIGUOUS_COLUMN                                              = 2
     SYN_3_AMBIGUOUS_FUNCTION                                            = 3

sql_error_categorizer-0.1.0/docs/index.rst

@@ -1,175 +0,0 @@
-.. dav-tools documentation master file, created by
-   sphinx-quickstart on Sun Jul 16 15:00:51 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to sql_error_categorizer's documentation!
-=====================================
-This project analyses SQL statements to highlight possible **misconceptions**
-(common mistakes or misunderstandings). The detection engine tokenises the input
-query and applies a set of rules. When a rule matches, it reports the type of
-misconception together with the token or fragment that triggered it.
-
-The logic is implemented in
-`sql_query_analyzer/utils/misconception_detector.py` and the available
-misconception identifiers are listed in
-`sql_query_analyzer/utils/misconceptions.py`.
-
-Below you will find a short explanation that anyone can follow, followed by a
-section with technical details for developers.
-
-Contents
-========
-
-.. toctree::
-   :maxdepth: 4
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
-Installation
-============
-``$ pip install sql_error_categorizer``
-
-What is checked right now?
-==========================
-
-At the moment the tool recognises the following issues:
-
-- Missing `FROM` clause in a `SELECT` statement.
-    - `SYN_6_COMMON_SYNTAX_ERROR_OMITTING_THE_FROM_CLAUSE`
-- Comparing a value with `NULL` using operators like `=` or `!=`.
-    - `SYN_6_COMMON_SYNTAX_ERROR_COMPARISON_WITH_NULL`
-- Omitting the final semicolon or adding extra semicolons.
-    - `SYN_6_COMMON_SYNTAX_ERROR_OMITTING_THE_SEMICOLON`
-    - `SYN_6_COMMON_SYNTAX_ERROR_ADDITIONAL_SEMICOLON`
-- Ambiguous column references when multiple tables share the same column name.
-    - `SYN_1_AMBIGUOUS_DATABASE_OBJECT_OMITTING_CORRELATION_NAMES`
-- Duplicate `WHERE` clauses or repeated `FROM`, `GROUP`, `HAVING` or `ORDER` clauses.
-    - `SYN_6_COMMON_SYNTAX_ERROR_USING_WHERE_TWICE`
-    - `SYN_6_COMMON_SYNTAX_ERROR_DUPLICATE_CLAUSE`
-- Using a column alias that has not been defined.
-    - `SYN_6_COMMON_SYNTAX_ERROR_USING_AN_UNDEFINED_CORRELATION_NAME`
-- Leaving out commas between expressions in the `SELECT` list.
-    - `SYN_6_COMMON_SYNTAX_ERROR_OMITTING_COMMAS`
-- Mismatched parentheses, brackets or braces.
-    - `SYN_6_COMMON_SYNTAX_ERROR_CURLY_SQUARE_OR_UNMATCHED_BRACKETS`
-- Non-standard operators such as `==`, `&&` or `||`.
-    - `SYN_6_COMMON_SYNTAX_ERROR_NONSTANDARD_OPERATORS`
-- Unqualified column names that exist in more than one table.
-    - `SYN_1_AMBIGUOUS_DATABASE_OBJECT_AMBIGUOUS_COLUMN`
-- References to tables or columns that do not exist in the provided catalogue.
-    - `SYN_2_UNDEFINED_DATABASE_OBJECT_UNDEFINED_COLUMN`
-- Invalid schema names.
-    - `SYN_2_UNDEFINED_DATABASE_OBJECT_INVALID_SCHEMA_NAME`
-- Text values without single quotes or with double quotes instead.
-    - `SYN_2_UNDEFINED_DATABASE_OBJECT_OMITTING_QUOTES_AROUND_CHARACTER_DATA`
-- Unknown functions, parameters or general identifiers.
-    - `SYN_2_UNDEFINED_DATABASE_OBJECT_UNDEFINED_FUNCTION`
-    - `SYN_2_UNDEFINED_DATABASE_OBJECT_UNDEFINED_PARAMETER`
-    - `SYN_2_UNDEFINED_DATABASE_OBJECT_UNDEFINED_OBJECT`
-- Misspellings or use of synonyms for table/column names.
-    - `SYN_2_UNDEFINED_DATABASE_OBJECT_MISSPELLINGS`
-    - `SYN_2_UNDEFINED_DATABASE_OBJECT_SYNONYMS`
-
-Other misconception categories defined in `misconceptions.py` are placeholders
-for future development.
-
-Technical details
-=================
-
-Each detection rule scans the tokenised query and returns a list of
-`(Misconceptions, token)` tuples. The list below summarises how each rule works
-and where it is implemented.
-
-- SYN_6_COMMON_SYNTAX_ERROR_OMITTING_THE_FROM_CLAUSE
-    Lines [81-84] of `misconception_detector.py` check if a SELECT statement lacks a
-    FROM clause. If so, the token `'FROM'` is reported.
-
-- SYN_6_COMMON_SYNTAX_ERROR_COMPARISON_WITH_NULL
-    Lines [85-89] scan tokens for comparison operators followed by `NULL`. If found,
-    the token `'NULL'` is returned.
-
-- SYN_6_COMMON_SYNTAX_ERROR_OMITTING_THE_SEMICOLON
-    Lines [91-93] verify that the original query text ends with a semicolon. Missing
-    termination results in this misconception.
-
-- SYN_6_COMMON_SYNTAX_ERROR_ADDITIONAL_SEMICOLON
-    Lines [95-97] detect more than one semicolon in the query, flagging an
-    additional semicolon error.
-
-- SYN_1_AMBIGUOUS_DATABASE_OBJECT_OMITTING_CORRELATION_NAMES
-    Lines [99-109] evaluate column names appearing in multiple tables without a
-    correlation alias. The offending column name is reported when ambiguity arises.
-
-- SYN_6_COMMON_SYNTAX_ERROR_USING_WHERE_TWICE
-    Lines [112-130] count top-level WHERE clauses. If more than one occurs, the
-    misconception is raised with the token `'WHERE'`.
-
-- SYN_6_COMMON_SYNTAX_ERROR_DUPLICATE_CLAUSE
-    The same loop also counts FROM, GROUP, HAVING, and ORDER clauses. When a clause
-    appears twice, its name is used as the token (lines 112‑130).
-
-- SYN_6_COMMON_SYNTAX_ERROR_USING_AN_UNDEFINED_CORRELATION_NAME
-    Lines [132-136] check for `alias.column` references where the alias was never
-    introduced. The unknown alias is returned.
-
-- SYN_6_COMMON_SYNTAX_ERROR_OMITTING_COMMAS
-    Lines [138-155] track the SELECT list, counting identifiers and commas. If more
-    than one column appears without a comma, the comma token is reported.
-
-- SYN_6_COMMON_SYNTAX_ERROR_CURLY_SQUARE_OR_UNMATCHED_BRACKETS
-    Lines [157-172] parse the raw query string for mismatched parentheses or square/
-    curly brackets. The unmatched character is returned.
-
-- SYN_6_COMMON_SYNTAX_ERROR_NONSTANDARD_OPERATORS
-    Lines [174-178] search for operators `==`, `&&` or `||` in the tokenised query.
-    The offending operator is returned when found.
-
-- SYN_1_AMBIGUOUS_DATABASE_OBJECT_AMBIGUOUS_COLUMN
-    Lines [181-195] look for duplicate column names in the SELECT clause where no
-    qualifier follows. The repeated column name triggers this misconception.
-
-- SYN_2_UNDEFINED_DATABASE_OBJECT_UNDEFINED_COLUMN
-    Lines [198-211] validate CTE and subquery aliases against cataloged columns.
-    Unknown columns referenced through an alias produce this error. The same rule
-    is reused later for general identifiers (lines 237‑248).
-
-- SYN_2_UNDEFINED_DATABASE_OBJECT_INVALID_SCHEMA_NAME
-    Lines [213-219] identify identifiers containing a schema prefix. If the schema
-    is not listed in the catalog, it is reported as invalid.
-
-- SYN_2_UNDEFINED_DATABASE_OBJECT_OMITTING_QUOTES_AROUND_CHARACTER_DATA
-    Lines [230-235] look for double-quoted identifiers that are not table or column
-    names. Additionally, lines 249‑251 flag bare alphabetic tokens treated as string
-    literals without quotes.
-
-- SYN_2_UNDEFINED_DATABASE_OBJECT_UNDEFINED_FUNCTION
-    Lines [237-242] detect alphabetic tokens followed by `(` that are not known
-    objects. These are assumed to be undefined functions.
-
-- SYN_2_UNDEFINED_DATABASE_OBJECT_UNDEFINED_PARAMETER
-    Lines [243-244] catch identifiers starting with `:` `@` or `?`, reporting them as
-    undefined parameters.
-
-- SYN_2_UNDEFINED_DATABASE_OBJECT_UNDEFINED_OBJECT
-    Lines [249-252] handle remaining unknown identifiers that do not match previous
-    cases, labelling them as undefined objects.
-
-- SYN_2_UNDEFINED_DATABASE_OBJECT_MISSPELLINGS
-    Lines [254-264] compare every alphabetic token not found in the catalog against
-    known names using `difflib.get_close_matches`. If a near match exists, the token
-    is flagged as a misspelling.
-
-- SYN_2_UNDEFINED_DATABASE_OBJECT_SYNONYMS
-    Lines [266-269] check tokens against a `synonyms` list in the catalog and report
-    usage when present.
-
-
-Other misconception types listed in `misconceptions.py` have no detection logic yet and are reserved for future work.
-