sqlanvil-sqlx-lint 0.2.0__py3-none-any.whl

sqlanvil_sqlx_lint/__init__.py

@@ -0,0 +1,16 @@
+"""sqlanvil-sqlx-lint: convention linter for SQLAnvil .sqlx files."""
+
+from .config import Config, DirPolicy, detect_warehouse, load_config, load_config_file
+from .linter import Finding, lint_file, lint_text
+
+__all__ = [
+    "Config",
+    "DirPolicy",
+    "Finding",
+    "detect_warehouse",
+    "lint_file",
+    "lint_text",
+    "load_config",
+    "load_config_file",
+]
+__version__ = "0.2.0"

sqlanvil_sqlx_lint/cli.py

@@ -0,0 +1,93 @@
+"""Command-line interface.
+
+Usage: sqlanvil-sqlx-lint [--config PATH] [--warehouse NAME]
+                          [--definitions-root DIR] FILE [FILE ...]
+Exit codes: 0 = clean or warnings only, 1 = errors found, 2 = usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+from .config import WAREHOUSES, Config, load_config, load_config_file, with_detected_warehouse
+from .linter import lint_file
+
+
+def _repo_resolver(root: Path):
+    """Resolve an action name to the text of <root>/**/<name>.sqlx.
+    Used to follow `select *` through ${ref()} for E010."""
+    if not root.is_dir():
+        return lambda name: None
+    index = {p.stem: p for p in root.rglob("*.sqlx")}
+
+    def resolve(name):
+        p = index.get(name)
+        try:
+            return p.read_text(encoding="utf-8") if p else None
+        except OSError:
+            return None
+
+    return resolve
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="sqlanvil-sqlx-lint",
+        description="Convention linter for SQLAnvil .sqlx files",
+    )
+    parser.add_argument("files", nargs="+", help=".sqlx files to lint")
+    parser.add_argument(
+        "--config",
+        help="path to a TOML config file (default: .sqlx-lint.toml or "
+        "[tool.sqlx-lint] in ./pyproject.toml)",
+    )
+    parser.add_argument(
+        "--warehouse",
+        choices=WAREHOUSES,
+        help="target warehouse (default: `warehouse` in the config, else "
+        "workflow_settings.yaml in the working directory, else postgres)",
+    )
+    parser.add_argument(
+        "--definitions-root",
+        default="definitions",
+        help="directory indexed to resolve ${ref()} targets for the E010 "
+        "coverage rule (default: ./definitions)",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.config:
+            cfg: Config = with_detected_warehouse(load_config_file(args.config), ".")
+        else:
+            cfg = load_config(".")
+    except (OSError, ValueError) as exc:
+        print(f"sqlx-lint: bad config: {exc}", file=sys.stderr)
+        return 2
+    if args.warehouse:
+        cfg = replace(cfg, warehouse=args.warehouse)
+    resolver = _repo_resolver(Path(args.definitions_root))
+
+    errors = warnings = 0
+    for path in args.files:
+        try:
+            findings = lint_file(path, config=cfg, resolver=resolver)
+        except OSError as exc:
+            print(f"{path}: cannot read: {exc}")
+            errors += 1
+            continue
+        for f in sorted(findings, key=lambda f: f.line):
+            print(f"{path}:{f.line}: {f.code} [{f.severity}] {f.message}")
+            if f.severity == "error":
+                errors += 1
+            else:
+                warnings += 1
+    if errors or warnings:
+        print(f"sqlx-lint: {errors} error(s), {warnings} warning(s)")
+    return 1 if errors else 0
+
+
+def entrypoint() -> None:
+    sys.exit(main())

sqlanvil_sqlx_lint/config.py

@@ -0,0 +1,217 @@
+"""Configuration model and TOML loading.
+
+Precedence: .sqlx-lint.toml in the working directory, else the
+[tool.sqlx-lint] table of pyproject.toml, else built-in defaults.
+
+The target warehouse is resolved separately (see `detect_warehouse`):
+an explicit `warehouse` config key wins, then `workflow_settings.yaml`
+in the working directory, then "postgres".
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+#: Rules that run unless disabled.
+DEFAULT_ENABLED = {
+    "E001",
+    "E002",
+    "E003",
+    "E004",
+    "E006",
+    "E007",
+    "E010",
+    "S101",
+    "S102",
+    "S103",
+    "S104",
+    "S105",
+    "S106",
+    "S108",
+}
+#: Opt-in rules (house-style checks): enable via `enable = [...]`.
+OPT_IN = {"E005", "W008"}
+
+#: Warehouse names sqlanvil accepts in workflow_settings.yaml.
+WAREHOUSES = ("postgres", "supabase", "mysql", "bigquery")
+DEFAULT_WAREHOUSE = "postgres"
+
+
+@dataclass(frozen=True)
+class DirPolicy:
+    """Naming/type policy applied to files whose path contains a substring."""
+
+    path_contains: str
+    require_prefix: str | None = None
+    require_types: tuple[str, ...] | None = None
+    severity: str = "error"
+
+
+@dataclass(frozen=True)
+class Config:
+    #: Target warehouse; None = detect from workflow_settings.yaml, else postgres.
+    warehouse: str | None = None
+    schema_suffixes: list[str] = field(
+        default_factory=lambda: ["_prod", "_dev", "_test"]
+    )
+    documented_types: set[str] = field(
+        default_factory=lambda: {"table", "view", "incremental", "declaration"}
+    )
+    #: E010 applies only to files whose path contains one of these; empty = all.
+    coverage_paths: list[str] = field(default_factory=list)
+    #: Schemas E006 may reference directly (e.g. system catalogs, extensions).
+    allowed_schemas: list[str] = field(default_factory=list)
+    dir_policies: list[DirPolicy] = field(default_factory=list)
+    enabled_extra: set[str] = field(default_factory=set)
+    disabled: set[str] = field(default_factory=set)
+
+    def rule_on(self, code: str) -> bool:
+        if code in self.disabled:
+            return False
+        return code in DEFAULT_ENABLED or code in self.enabled_extra
+
+    @property
+    def effective_warehouse(self) -> str:
+        return (self.warehouse or DEFAULT_WAREHOUSE).lower()
+
+    def __eq__(self, other):
+        if not isinstance(other, Config):
+            return NotImplemented
+        return (
+            self.warehouse == other.warehouse
+            and self.schema_suffixes == other.schema_suffixes
+            and self.documented_types == other.documented_types
+            and self.coverage_paths == other.coverage_paths
+            and self.allowed_schemas == other.allowed_schemas
+            and self.dir_policies == other.dir_policies
+            and self.enabled_extra == other.enabled_extra
+            and self.disabled == other.disabled
+        )
+
+
+_KNOWN_KEYS = {
+    "warehouse",
+    "schema_suffixes",
+    "documented_types",
+    "coverage_paths",
+    "allowed_schemas",
+    "dir_policies",
+    "enable",
+    "disable",
+}
+
+
+def _from_dict(raw: dict) -> Config:
+    unknown = set(raw) - _KNOWN_KEYS
+    if unknown:
+        raise ValueError(
+            f"unknown sqlx-lint config key(s): {', '.join(sorted(unknown))}"
+        )
+    policies = [
+        DirPolicy(
+            path_contains=p["path_contains"],
+            require_prefix=p.get("require_prefix"),
+            require_types=tuple(p["require_types"]) if p.get("require_types") else None,
+            severity=p.get("severity", "error"),
+        )
+        for p in raw.get("dir_policies", [])
+    ]
+    kwargs = {}
+    if "warehouse" in raw:
+        wh = str(raw["warehouse"]).lower()
+        if wh not in WAREHOUSES:
+            raise ValueError(
+                f"unknown warehouse {wh!r}; expected one of {', '.join(WAREHOUSES)}"
+            )
+        kwargs["warehouse"] = wh
+    if "schema_suffixes" in raw:
+        kwargs["schema_suffixes"] = list(raw["schema_suffixes"])
+    if "documented_types" in raw:
+        kwargs["documented_types"] = set(raw["documented_types"])
+    if "coverage_paths" in raw:
+        kwargs["coverage_paths"] = list(raw["coverage_paths"])
+    if "allowed_schemas" in raw:
+        kwargs["allowed_schemas"] = list(raw["allowed_schemas"])
+    return Config(
+        dir_policies=policies,
+        enabled_extra=set(raw.get("enable", [])),
+        disabled=set(raw.get("disable", [])),
+        **kwargs,
+    )
+
+
+def load_config_file(path: str | Path) -> Config:
+    """Load a standalone TOML config file (the whole document is the config)."""
+    return _from_dict(tomllib.loads(Path(path).read_text(encoding="utf-8")))
+
+
+def detect_warehouse(root: str | Path = ".") -> str | None:
+    """Read `warehouse:` from <root>/workflow_settings.yaml without PyYAML.
+
+    Accepts both the scalar form (`warehouse: postgres`) and the mapping form
+    (`warehouse:` followed by an indented `kind: postgres`). Returns None when
+    the file is absent or carries no recognisable value.
+    """
+    settings = Path(root) / "workflow_settings.yaml"
+    if not settings.is_file():
+        return None
+    try:
+        lines = settings.read_text(encoding="utf-8").split("\n")
+    except OSError:
+        return None
+    for i, line in enumerate(lines):
+        m = re.match(r"^warehouse\s*:\s*(?:[\"']?([A-Za-z]+)[\"']?)?\s*(?:#.*)?$", line)
+        if not m:
+            continue
+        if m.group(1):
+            return m.group(1).lower()
+        for nxt in lines[i + 1 :]:
+            if not nxt.strip() or nxt.lstrip().startswith("#"):
+                continue
+            if not nxt.startswith((" ", "\t")):
+                break
+            km = re.match(r"^\s+kind\s*:\s*[\"']?([A-Za-z]+)", nxt)
+            if km:
+                return km.group(1).lower()
+        return None
+    return None
+
+
+def load_config(root: str | Path = ".") -> Config:
+    root = Path(root)
+    standalone = root / ".sqlx-lint.toml"
+    cfg = None
+    if standalone.is_file():
+        cfg = load_config_file(standalone)
+    else:
+        pyproject = root / "pyproject.toml"
+        if pyproject.is_file():
+            data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+            tool = data.get("tool", {}).get("sqlx-lint")
+            if tool is not None:
+                cfg = _from_dict(tool)
+    if cfg is None:
+        cfg = Config()
+    return with_detected_warehouse(cfg, root)
+
+
+def with_detected_warehouse(cfg: Config, root: str | Path = ".") -> Config:
+    """Fill in `warehouse` from workflow_settings.yaml when the config leaves it unset."""
+    if cfg.warehouse is not None:
+        return cfg
+    detected = detect_warehouse(root)
+    if detected is None:
+        return cfg
+    return Config(
+        warehouse=detected,
+        schema_suffixes=cfg.schema_suffixes,
+        documented_types=cfg.documented_types,
+        coverage_paths=cfg.coverage_paths,
+        allowed_schemas=cfg.allowed_schemas,
+        dir_policies=cfg.dir_policies,
+        enabled_extra=cfg.enabled_extra,
+        disabled=cfg.disabled,
+    )

sqlanvil_sqlx_lint/linter.py

@@ -0,0 +1,623 @@
+"""Core linter: parses the .sqlx config block and SQL body, emits Findings.
+
+Rules (codes are stable; suppress with `-- sqlx-lint: disable=E006` on the
+offending line or `-- sqlx-lint: disable-file=E006` anywhere in the file):
+
+  E001  config {} block missing or unbalanced
+  E002  columns: {} missing or empty on documented types
+        (declarations may carry columnTypes: {} instead)
+  E003  schema: hardcodes an environment suffix (suffix-doubling trap)
+  E004  name: redundantly matches the filename (non-declarations)
+  E005  schema: set on operations/assertion configs        [opt-in]
+  E006  hardcoded table path instead of ${ref()} (warehouse-aware)
+  E007  directory policy violation (configured prefix/type per path)
+  W008  post_operations block appears before the main SELECT [opt-in]
+  E010  columns:{} does not cover every determinable output column
+
+sqlanvil-specific rules (the deltas that bite when Dataform habits carry over):
+
+  S101  BigQuery-only config (bigquery:{}, partitionBy, clusterBy, ...) on a
+        non-BigQuery warehouse — silently ignored, never applied
+  S102  `;` used to separate statements in operations / pre_operations /
+        post_operations — sqlanvil splits on `---`, so the block runs as one
+        statement and fails at run time
+  S103  postgres.indexes[].method given as a string — it is a numeric enum
+  S104  incrementalStrategy on a non-BigQuery warehouse
+  S105  ADD PRIMARY KEY / ADD CONSTRAINT in an incremental's operations block
+        not wrapped in when(!incremental(), ...) — errors on the second run
+  S106  assertions: sets both uniqueKey and uniqueKeys
+  S108  .jitCode() / jitData() — no runtime in sqlanvil
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .config import Config
+
+NO_SCHEMA_TYPES = {"operations", "assertion", "test"}
+
+#: Schemas that are never a hardcoded *source* (system catalogs).
+SYSTEM_SCHEMAS = {"pg_catalog", "information_schema", "pg_temp", "mysql", "sys",
+                  "performance_schema"}
+
+#: Config keys that only BigQuery understands (S101).
+BIGQUERY_ONLY_KEYS = ("bigquery", "partitionBy", "clusterBy", "bigqueryPolicyTags")
+
+
+@dataclass
+class Finding:
+    code: str
+    severity: str  # "error" | "warning"
+    line: int
+    message: str
+
+
+def _line_of(text, pos):
+    return text.count("\n", 0, pos) + 1
+
+
+def _balanced_block(text, open_brace_pos):
+    """Return (content, end_pos) of the brace block at open_brace_pos, else None."""
+    depth = 0
+    in_str = None
+    i = open_brace_pos
+    while i < len(text):
+        ch = text[i]
+        if in_str:
+            if ch == "\\":
+                i += 2
+                continue
+            if ch == in_str:
+                in_str = None
+        elif ch in "\"'`":
+            in_str = ch
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return text[open_brace_pos + 1 : i], i + 1
+        i += 1
+    return None
+
+
+def _config_value(config, key):
+    m = re.search(rf"\b{key}\s*:\s*([\"'])(.*?)\1", config)
+    return m.group(2) if m else None
+
+
+def _config_key_line(config, key, config_line):
+    m = re.search(rf"\b{key}\s*:", config)
+    return config_line + config[: m.start()].count("\n") if m else config_line
+
+
+def _strip_comments(text):
+    text = re.sub(
+        r"/\*.*?\*/", lambda m: re.sub(r"[^\n]", " ", m.group(0)), text, flags=re.S
+    )
+    return re.sub(r"--[^\n]*", lambda m: " " * len(m.group(0)), text)
+
+
+def _split_top_level(text, sep=","):
+    """Split text on sep occurring outside (), [], {}, and string literals."""
+    parts, depth, start, in_str, i = [], 0, 0, None, 0
+    while i < len(text):
+        ch = text[i]
+        if in_str:
+            if ch == "\\":
+                i += 2
+                continue
+            if ch == in_str:
+                in_str = None
+        elif ch in "\"'`":
+            in_str = ch
+        elif ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        elif ch == sep and depth == 0:
+            parts.append(text[start:i])
+            start = i + 1
+        i += 1
+    parts.append(text[start:])
+    return parts
+
+
+def _scan_sql(text):
+    """Walk SQL text and return (semicolons, js_regions).
+
+    semicolons: positions of `;` that sit outside string literals, dollar-quoted
+    bodies, and `${ ... }` JavaScript regions.
+    js_regions: (start, end) spans of `${ ... }` regions, so callers can tell
+    whether a match is wrapped in a template expression.
+    """
+    semis, regions = [], []
+    i, n = 0, len(text)
+    in_str = None
+    while i < n:
+        ch = text[i]
+        if in_str:
+            if ch == "\\":
+                i += 2
+                continue
+            if ch == in_str:
+                in_str = None
+            i += 1
+            continue
+        if ch == "$" and text.startswith("$$", i):
+            end = text.find("$$", i + 2)
+            i = n if end < 0 else end + 2
+            continue
+        if ch == "$" and text.startswith("${", i):
+            start = i
+            depth, j, js_str = 0, i + 1, None
+            while j < n:
+                c = text[j]
+                if js_str:
+                    if c == "\\":
+                        j += 2
+                        continue
+                    if c == js_str:
+                        js_str = None
+                elif c in "\"'`":
+                    js_str = c
+                elif c == "{":
+                    depth += 1
+                elif c == "}":
+                    depth -= 1
+                    if depth == 0:
+                        break
+                j += 1
+            regions.append((start, j + 1))
+            i = j + 1
+            continue
+        if ch in "\"'":
+            in_str = ch
+        elif ch == ";":
+            semis.append(i)
+        i += 1
+    return semis, regions
+
+
+def _statement_blocks(body):
+    """Yield (kind, start, content) for each pre_operations/post_operations block."""
+    for m in re.finditer(r"\b(pre_operations|post_operations)\s*({)", body):
+        block = _balanced_block(body, m.start(2))
+        if block:
+            yield m.group(1), m.start(2) + 1, block[0]
+
+
+def _main_projection(clean_body):
+    """Return (projection_text, from_clause_text, select_pos) of the first
+    top-level SELECT (CTE bodies and sub-selects sit inside parens/braces),
+    or None if no top-level SELECT exists."""
+    depth, in_str, i = 0, None, 0
+    select_pos = None
+    while i < len(clean_body):
+        ch = clean_body[i]
+        if in_str:
+            if ch == "\\":
+                i += 2
+                continue
+            if ch == in_str:
+                in_str = None
+        elif ch in "\"'`":
+            in_str = ch
+        elif ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        elif depth == 0 and ch in "sSfF":
+            word = re.match(r"(select|from)\b", clean_body[i:], re.I)
+            if word and (
+                i == 0 or not (clean_body[i - 1].isalnum() or clean_body[i - 1] in "_$")
+            ):
+                if word.group(1).lower() == "select" and select_pos is None:
+                    select_pos = i
+                elif word.group(1).lower() == "from" and select_pos is not None:
+                    return (clean_body[select_pos + 6 : i], clean_body[i:], select_pos)
+        i += 1
+    if select_pos is not None:  # SELECT without FROM (constants)
+        return (clean_body[select_pos + 6 :], "", select_pos)
+    return None
+
+
+_SIMPLE_IDENT = re.compile(r"^`?[A-Za-z_]\w*`?(?:\.`?([A-Za-z_]\w*)`?)?$")
+_TRAILING_ALIAS = re.compile(r"\bas\s+`?([A-Za-z_]\w*)`?\s*$", re.I | re.S)
+_STAR_ITEM = re.compile(
+    r"^(?:[A-Za-z_]\w*\.)?\*\s*(?:except\s*\(([^)]*)\))?\s*(?:replace\s*\(.*\))?$",
+    re.I | re.S,
+)
+_SINGLE_REF_FROM = re.compile(
+    r"^from\s+\$\{\s*ref\(\s*(?:\"[^\"]*\"\s*,\s*)?\"([^\"]+)\"\s*\)\s*\}\s*"
+    r"(?:as\s+\w+\s*)?"
+    r"(?:where\b|group\b|order\b|qualify\b|limit\b|window\b|post_operations\b|$)",
+    re.I | re.S,
+)
+
+
+def _known_output_columns(clean_body, resolver, _depth=0, _seen=None):
+    """Best-effort set of output column names of a file's main SELECT.
+    Unparseable items are silently skipped; `select *` is followed through a
+    single plain ${ref()} when a resolver is provided. Never raises."""
+    parsed = _main_projection(clean_body)
+    if parsed is None:
+        return set()
+    projection, from_clause, _ = parsed
+    names, star_except = set(), None
+    items = _split_top_level(projection)
+    if items:
+        items[0] = re.sub(r"^\s*(distinct|all)\b", "", items[0], flags=re.I)
+    for item in items:
+        item = item.strip()
+        if not item:
+            continue
+        sm = _STAR_ITEM.match(item)
+        if sm:
+            star_except = {
+                n.strip().strip("`").lower()
+                for n in (sm.group(1) or "").split(",")
+                if n.strip()
+            }
+            continue
+        am = _TRAILING_ALIAS.search(item)
+        if am:
+            names.add(am.group(1).lower())
+            continue
+        im = _SIMPLE_IDENT.match(item)
+        if im:
+            names.add((im.group(1) or item.strip("`")).lower())
+    if star_except is not None and resolver is not None and _depth < 3:
+        rm = _SINGLE_REF_FROM.match(from_clause.strip())
+        if rm:
+            ref_name = rm.group(1)
+            _seen = _seen or set()
+            if ref_name not in _seen:
+                _seen.add(ref_name)
+                upstream = resolver(ref_name)
+                if upstream is not None:
+                    up_names = _known_output_columns(
+                        _strip_comments(upstream), resolver, _depth + 1, _seen
+                    )
+                    names |= up_names - star_except
+    return names
+
+
+def _block_keys(config, key):
+    """Top-level keys of the `<key>: {}` block, lowercased; empty set if none."""
+    cm = re.search(rf"\b{key}\s*:\s*({{)", config)
+    block = _balanced_block(config, cm.start(1)) if cm else None
+    if not block:
+        return set()
+    keys = set()
+    for item in _split_top_level(block[0]):
+        km = re.match(r'\s*"?([A-Za-z_]\w*)"?\s*:', item)
+        if km:
+            keys.add(km.group(1).lower())
+    return keys
+
+
+def _documented_keys(config):
+    return _block_keys(config, "columns")
+
+
+# --- E006: hardcoded table paths, per warehouse -------------------------------
+
+_IDENT = r'(?:"[^"\n]+"|`[^`\n]+`|[A-Za-z_]\w*)'
+#: `schema.table` (any quoting per part) right after a table-introducing keyword.
+_TWO_PART_AFTER_KEYWORD = re.compile(
+    rf"\b(?:from|join|into|update)\s+({_IDENT})\s*\.\s*({_IDENT})(?![\w.\"`(])",
+    re.I,
+)
+#: BigQuery-style whole-path in one pair of backticks: `proj.dataset.table`
+_BQ_BACKTICK_3 = re.compile(r"`([A-Za-z][\w-]*\.[A-Za-z]\w*\.[A-Za-z]\w*)`")
+#: `dataset.table` in one pair of backticks (BigQuery shorthand)
+_BQ_BACKTICK_2 = re.compile(r"`([A-Za-z][\w-]*\.[A-Za-z]\w*)`")
+
+
+#: An open extract/substring/trim/overlay/position call with no `)` yet.
+_FUNCTION_FROM = re.compile(
+    r"\b(?:extract|substring|trim|overlay|position)\s*\([^()]*$", re.I
+)
+
+
+def _unquote(ident):
+    return ident.strip('"`').lower()
+
+
+def _hardcoded_paths(clean_body, warehouse, allowed_schemas):
+    """Yield (pos, path) for table references that bypass ${ref()}."""
+    allowed = {s.lower() for s in allowed_schemas} | SYSTEM_SCHEMAS
+    for pm in _BQ_BACKTICK_3.finditer(clean_body):
+        yield pm.start(), f"`{pm.group(1)}`"
+    if warehouse == "bigquery":
+        for pm in _BQ_BACKTICK_2.finditer(clean_body):
+            yield pm.start(), f"`{pm.group(1)}`"
+    for pm in _TWO_PART_AFTER_KEYWORD.finditer(clean_body):
+        first, second = pm.group(1), pm.group(2)
+        schema = _unquote(first)
+        if schema in allowed or schema.startswith("pg_temp"):
+            continue
+        # `extract(dow from d.date)`, `substring(x from 1)`, `trim(both from x)`:
+        # FROM as function syntax, inside an open call paren.
+        if _FUNCTION_FROM.search(clean_body[max(0, pm.start() - 200) : pm.start()]):
+            continue
+        yield pm.start(1), f"{first}.{second}"
+
+
+def lint_text(text, path, config: Config | None = None, resolver=None):
+    cfg = config or Config()
+    warehouse = cfg.effective_warehouse
+    findings: list[Finding] = []
+    path = path.replace("\\", "/")
+    stem = re.sub(r"\.sqlx$", "", path.rsplit("/", 1)[-1])
+    file_disabled = set(re.findall(r"sqlx-lint:\s*disable-file=([EWS]\d+)\b", text))
+    lines = text.split("\n")
+
+    def suppressed(code, line):
+        if code in file_disabled:
+            return True
+        if not (0 < line <= len(lines)):
+            return False
+        src = lines[line - 1]
+        return "sqlx-lint:" in src and re.search(rf"disable={code}\b", src) is not None
+
+    def add(code, severity, line, message):
+        if cfg.rule_on(code) and not suppressed(code, line):
+            findings.append(Finding(code, severity, line, message))
+
+    # --- S108: JIT compilation has no runtime in sqlanvil (checked pre-config) ---
+    for jm in re.finditer(r"\.jitCode\s*\(|\bjitData\s*\(", text):
+        add(
+            "S108",
+            "error",
+            _line_of(text, jm.start()),
+            "jitCode()/jitData() have no runtime in sqlanvil (compile error since "
+            "1.30) — generate the SQL at compile time instead",
+        )
+
+    # --- E001: locate and parse config block ---
+    m = re.search(r"\bconfig\s*({)", text)
+    if not m:
+        add("E001", "error", 1, "no config {} block found")
+        return findings
+    block = _balanced_block(text, m.start(1))
+    if block is None:
+        add(
+            "E001",
+            "error",
+            _line_of(text, m.start()),
+            "config {} block braces are unbalanced",
+        )
+        return findings
+    config_body, config_end = block
+    config_line = _line_of(text, m.start())
+    body = text[config_end:]
+    body_offset = config_end
+
+    ctype = _config_value(config_body, "type") or ""
+    schema = _config_value(config_body, "schema") or _config_value(config_body, "dataset")
+    name = _config_value(config_body, "name")
+    documented = _documented_keys(config_body)
+    column_types = _block_keys(config_body, "columnTypes")
+
+    # --- E002: columns documentation ---
+    # Declarations scaffolded by `sqlanvil introspect` carry columnTypes instead.
+    if ctype in cfg.documented_types and not documented:
+        if not (ctype == "declaration" and column_types):
+            add(
+                "E002",
+                "error",
+                config_line,
+                f'type "{ctype}" requires a non-empty columns: {{}} block',
+            )
+
+    # --- E003: schema suffix (declarations exempt: raw datasets may carry one) ---
+    suffix_re = "|".join(re.escape(s) for s in cfg.schema_suffixes)
+    if (
+        schema
+        and cfg.schema_suffixes
+        and ctype != "declaration"
+        and re.search(rf"(?:{suffix_re})$", schema)
+    ):
+        base = re.sub(rf"(?:{suffix_re})$", "", schema)
+        key = "schema" if _config_value(config_body, "schema") is not None else "dataset"
+        add(
+            "E003",
+            "error",
+            _config_key_line(config_body, key, config_line),
+            f'{key}: "{schema}" hardcodes an environment suffix; use the base '
+            f'name ("{base}") and let --schema-suffix or the environment\'s '
+            "schemaSuffix append it",
+        )
+
+    # --- E004: redundant name (declarations conventionally repeat it) ---
+    if name and ctype != "declaration" and name == stem:
+        add(
+            "E004",
+            "error",
+            _config_key_line(config_body, "name", config_line),
+            f'name: "{name}" matches the filename and is redundant — remove it',
+        )
+
+    # --- E005 (opt-in): schema on operations/assertions ---
+    # hasOutput: true operations are exempt: schema+name define ${self()}.
+    has_output = re.search(r"\bhasOutput\s*:\s*true\b", config_body) is not None
+    if schema and ctype in NO_SCHEMA_TYPES and not has_output:
+        add(
+            "E005",
+            "error",
+            config_line,
+            f'type "{ctype}" must not set schema: — '
+            "it uses the workflow_settings.yaml default",
+        )
+
+    # --- E006: hardcoded table paths in the SQL body ---
+    clean_body = _strip_comments(body)
+    for pos, table_path in _hardcoded_paths(clean_body, warehouse, cfg.allowed_schemas):
+        add(
+            "E006",
+            "error",
+            _line_of(text, body_offset + pos),
+            f"hardcoded table path {table_path} — declare a source and use ${{ref()}}",
+        )
+
+    # --- E007: directory policies ---
+    for policy in cfg.dir_policies:
+        if policy.path_contains not in path:
+            continue
+        if policy.require_prefix and not stem.startswith(policy.require_prefix):
+            add(
+                "E007",
+                policy.severity,
+                1,
+                f"files in {policy.path_contains} must be prefixed "
+                f'"{policy.require_prefix}" (got "{stem}")',
+            )
+        if policy.require_types and ctype not in policy.require_types:
+            add(
+                "E007",
+                policy.severity,
+                config_line,
+                f"files in {policy.path_contains} must be type "
+                f'{" or ".join(policy.require_types)} (got "{ctype}")',
+            )
+
+    # --- E010: columns coverage (skip when E002 already owns the file) ---
+    in_scope = not cfg.coverage_paths or any(
+        p in path for p in cfg.coverage_paths
+    )
+    if ctype in ("table", "incremental", "view") and documented and in_scope:
+        known = _known_output_columns(clean_body, resolver)
+        missing = sorted(known - documented)
+        if missing:
+            parsed = _main_projection(clean_body)
+            sel_line = (
+                _line_of(text, body_offset + parsed[2]) if parsed else config_line
+            )
+            shown = ", ".join(f'"{n}"' for n in missing[:10])
+            more = f" (+{len(missing) - 10} more)" if len(missing) > 10 else ""
+            add(
+                "E010",
+                "error",
+                sel_line,
+                f"columns: {{}} is missing documentation for output "
+                f"column(s): {shown}{more}",
+            )
+
+    # --- W008 (opt-in): post_operations placement ---
+    pm = re.search(r"\bpost_operations\s*{", body)
+    if pm:
+        sm = re.search(r"(?im)^\s*select\b", _strip_comments(body[: pm.start()]))
+        if sm is None:
+            add(
+                "W008",
+                "warning",
+                _line_of(text, body_offset + pm.start()),
+                "post_operations {} placed before the main SELECT statement",
+            )
+
+    # --- S101 / S104: BigQuery-only config on another warehouse ---
+    if warehouse != "bigquery":
+        # Keys nested inside a bigquery: {} block are reported once, via the block.
+        bqm = re.search(r"\bbigquery\s*:\s*({)", config_body)
+        bq_block = _balanced_block(config_body, bqm.start(1)) if bqm else None
+        scan = config_body
+        if bq_block:
+            s0, s1 = bqm.start(1), bqm.start(1) + len(bq_block[0]) + 2
+            scan = config_body[:s0] + re.sub(r"[^\n]", " ", config_body[s0:s1]) + config_body[s1:]
+        for key in BIGQUERY_ONLY_KEYS:
+            if re.search(rf"\b{key}\s*:", scan):
+                add(
+                    "S101",
+                    "error",
+                    _config_key_line(config_body, key, config_line),
+                    f"{key}: is BigQuery-only and is ignored on {warehouse} — "
+                    "use the postgres: {} block (indexes, partition) instead",
+                )
+        if re.search(r"\bincrementalStrategy\s*:", config_body):
+            add(
+                "S104",
+                "error",
+                _config_key_line(config_body, "incrementalStrategy", config_line),
+                f"incrementalStrategy: is BigQuery-only (compile error on {warehouse}) "
+                "— use the default merge with uniqueKey, or delete the range in "
+                "pre_operations",
+            )
+
+    # --- S103: postgres index method must be the numeric enum ---
+    pgm = re.search(r"\bpostgres\s*:\s*({)", config_body)
+    pg_block = _balanced_block(config_body, pgm.start(1)) if pgm else None
+    if pg_block:
+        for mm in re.finditer(r"\bmethod\s*:\s*([\"'])(\w+)\1", pg_block[0]):
+            add(
+                "S103",
+                "error",
+                config_line + config_body[: pgm.start() + 1 + mm.start()].count("\n"),
+                f'postgres.indexes[].method: "{mm.group(2)}" must be the numeric enum '
+                "(BTREE=0, HASH=1, GIN=2, GIST=3, BRIN=4); omit it for btree",
+            )
+
+    # --- S106: uniqueKey and uniqueKeys are mutually exclusive in assertions ---
+    am = re.search(r"\bassertions\s*:\s*({)", config_body)
+    a_block = _balanced_block(config_body, am.start(1)) if am else None
+    if a_block:
+        keys = _block_keys(config_body, "assertions")
+        if "uniquekey" in keys and "uniquekeys" in keys:
+            add(
+                "S106",
+                "error",
+                _config_key_line(config_body, "assertions", config_line),
+                "assertions: sets both uniqueKey and uniqueKeys — they are mutually "
+                "exclusive; fold the single key into uniqueKeys",
+            )
+
+    # --- S102 / S105: statement blocks (operations body, pre/post_operations) ---
+    blocks = list(_statement_blocks(body))
+    if ctype == "operations":
+        blocks.append(("operations", 0, body))
+
+    for kind, start, content in blocks:
+        semis, regions = _scan_sql(content)
+        for sp in semis:
+            rest = content[sp + 1 :]
+            # Ignore a trailing `;` — only `;` followed by another statement is a
+            # separator. Comments after it do not count as a statement.
+            if re.search(r"\S", _strip_comments(rest)):
+                add(
+                    "S102",
+                    "error",
+                    _line_of(text, body_offset + start + sp),
+                    f"`;` separates statements in {kind} — sqlanvil splits on a "
+                    "`---` line, so this runs as one statement and fails at run time",
+                )
+                break
+        if ctype == "incremental" and kind != "operations":
+            for dm in re.finditer(
+                r"\bADD\s+(?:PRIMARY\s+KEY|CONSTRAINT)\b", content, re.I
+            ):
+                guarded = any(
+                    s <= dm.start() < e
+                    and re.search(
+                        r"when\s*\(\s*!\s*incremental\s*\(\s*\)", content[s:e]
+                    )
+                    for s, e in regions
+                )
+                if not guarded:
+                    add(
+                        "S105",
+                        "error",
+                        _line_of(text, body_offset + start + dm.start()),
+                        f"{dm.group(0)} in {kind} of an incremental runs on every "
+                        "append and fails the second time — wrap it in "
+                        "${when(!incremental(), `...`)}",
+                    )
+
+    return findings
+
+
+def lint_file(path, config: Config | None = None, resolver=None):
+    with open(path, encoding="utf-8") as fh:
+        return lint_text(fh.read(), path, config=config, resolver=resolver)

sqlanvil_sqlx_lint-0.2.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: sqlanvil-sqlx-lint
+Version: 0.2.0
+Summary: Convention linter for SQLAnvil .sqlx files — config-block, project-convention, and sqlanvil-delta checks that SQL linters and compile cannot see
+Author-email: Ivan Histand <ivan@histand.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SQLAnvil/sqlanvil-sqlx-lint
+Project-URL: Documentation, https://sqlanvil.com/docs
+Project-URL: Upstream, https://github.com/acuantia/dataform-sqlx-lint
+Keywords: sqlanvil,sqlx,lint,postgres,supabase,mysql,bigquery,dataform,pre-commit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# sqlanvil-sqlx-lint
+
+A convention linter for [SQLAnvil](https://sqlanvil.com) `.sqlx` files. SQL
+linters (sqlfluff) check the SQL body; `sqlanvil compile` checks syntax and
+`sqlanvil validate` checks against the warehouse. None of them see the
+**config-block and project conventions** that keep a sqlanvil repo healthy, and
+several Dataform habits that sqlanvil silently ignores or fails on at run time.
+This tool does, in milliseconds, with no warehouse connection.
+
+Zero dependencies (Python ≥ 3.11 standard library only). Designed for
+[pre-commit](https://pre-commit.com). Warehouse-aware: PostgreSQL, Supabase,
+MySQL/MariaDB, and BigQuery-target projects.
+
+```bash
+pip install sqlanvil-sqlx-lint
+```
+
+Forked from [acuantia/dataform-sqlx-lint](https://github.com/acuantia/dataform-sqlx-lint)
+(MIT), which was extracted from a production Dataform repository.
+
+## Rules
+
+### Conventions
+
+| Code | Default | Checks |
+|------|---------|--------|
+| E001 | on | `config {}` block present and balanced |
+| E002 | on | non-empty `columns: {}` on tables/views/incrementals/declarations (declarations may carry `columnTypes: {}` from `sqlanvil introspect` instead) |
+| E003 | on | `schema:` must not hardcode an environment suffix (`_prod`/`_dev`/`_test` by default) — `--schema-suffix` and `environments.<name>.schemaSuffix` append it, so a literal doubles up (`analytics_test_test`) |
+| E004 | on | `name:` matching the filename is redundant (declarations exempt) |
+| E005 | opt-in | operations/assertions must not set `schema:` (`hasOutput: true` operations exempt — schema+name define `${self()}`) |
+| E006 | on | hardcoded table paths instead of `${ref()}` — these silently break the dependency graph. Warehouse-aware: `public.orders`, `"schema"."table"`, `` `db`.`table` ``, `` `project.dataset.table` `` |
+| E007 | on* | configurable per-directory naming/type policies (*no-op until policies are configured) |
+| W008 | opt-in | `post_operations {}` placed before the main SELECT (style preference) |
+| E010 | on | every determinable output column appears in `columns: {}` — parses the main SELECT conservatively (unparseable expressions are skipped, never false-flagged) and follows `select *` through a single plain `${ref()}` into the upstream file |
+
+Why E002/E010 matter: sqlanvil writes `description:` and `columns: {}` into the
+warehouse catalog (`COMMENT ON TABLE` / `COMMENT ON COLUMN` on Postgres, table
+and column descriptions on BigQuery). That is the metadata data catalogs, BI
+tools, and AI analytics agents read. Partial blocks leave silent gaps.
+
+### sqlanvil deltas
+
+The places where a Dataform/BigQuery habit produces a sqlanvil project that
+compiles but does the wrong thing. The first three are failures no compiler
+catches.
+
+| Code | Default | Checks | `sqlanvil compile` catches it? |
+|------|---------|--------|-------------------------------|
+| S101 | on | `bigquery: {}`, `partitionBy`, `clusterBy`, `bigqueryPolicyTags` on a non-BigQuery warehouse — ignored silently, never applied | no |
+| S102 | on | `;` separating statements in `operations` / `pre_operations` / `post_operations` — sqlanvil splits on a `---` line, so the block runs as one statement and fails at run time | no |
+| S105 | on | `ADD PRIMARY KEY` / `ADD CONSTRAINT` in an incremental's operations block not wrapped in `${when(!incremental(), …)}` — runs on every append and errors the second time | no |
+| S103 | on | `postgres.indexes[].method` given as a string — it is a numeric enum (`BTREE=0, HASH=1, GIN=2, GIST=3, BRIN=4`) | yes |
+| S104 | on | `incrementalStrategy` on a non-BigQuery warehouse | yes (≥1.29) |
+| S106 | on | `assertions:` sets both `uniqueKey` and `uniqueKeys` | yes |
+| S108 | on | `.jitCode()` / `jitData()` — no runtime in sqlanvil | yes (≥1.30) |
+
+## Usage
+
+```bash
+sqlanvil-sqlx-lint definitions/outputs/my_table.sqlx [...]
+# exit 0 = clean or warnings only; 1 = errors; 2 = bad config
+```
+
+Run from the project root. The target warehouse is read from
+`workflow_settings.yaml` there (`warehouse: postgres|supabase|mysql|bigquery`),
+and `--definitions-root` (default `./definitions`) is indexed so `${ref()}`
+targets resolve for E010's star-resolution. Override with `--warehouse` or the
+`warehouse` config key; the default with nothing configured is `postgres`.
+
+### pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/SQLAnvil/sqlanvil-sqlx-lint
+    rev: v0.2.0
+    hooks:
+      - id: sqlanvil-sqlx-lint
+```
+
+### Configuration
+
+`.sqlx-lint.toml` in the project root, or a `[tool.sqlx-lint]` table in
+`pyproject.toml` (the standalone file wins). All keys optional:
+
+```toml
+warehouse = "postgres"                     # else workflow_settings.yaml, else postgres
+schema_suffixes = ["_prod", "_dev", "_test"]  # E003 suffix list ([] disables)
+documented_types = ["table", "view", "incremental", "declaration"]  # E002
+coverage_paths = ["definitions/outputs/"]  # E010 scope; empty = everywhere
+allowed_schemas = ["extensions"]           # E006 may reference these directly
+enable = ["E005", "W008"]                  # switch on opt-in rules
+disable = ["E004"]                         # switch off default rules
+
+[[dir_policies]]                           # E007 (repeatable)
+path_contains = "definitions/outputs/"
+require_prefix = "rpt_"
+require_types = ["table", "incremental"]
+severity = "error"                         # or "warning"
+```
+
+See [`examples/sqlx-lint.toml`](examples/sqlx-lint.toml) for a complete
+sources → intermediate → outputs layout. System catalogs (`pg_catalog`,
+`information_schema`, `mysql`, `sys`, …) are always allowed.
+
+### Adopting on an existing project
+
+A migrated repository will be loud on the first run: E002 on every undocumented
+model and E010 wherever documentation is partial. Adopt in layers rather than
+suppressing:
+
+1. Start with `disable = ["E002", "E010"]` so the S-series and E006 findings,
+   which are actual defects, land first.
+2. Re-enable E002 and scope E010 with `coverage_paths` to the BI-facing layer.
+3. Widen `coverage_paths` as documentation catches up.
+
+### Suppressing findings
+
+```sql
+from public.legacy_events -- sqlx-lint: disable=E006 (declaration repoints at cutover)
+```
+
+or file-wide, anywhere in the file:
+
+```sql
+-- sqlx-lint: disable-file=E006
+```
+
+Suppress with a reason, sparingly — the convention is usually the fix.
+
+## Design notes
+
+- **Conservative by construction**: the SQL projection parser only claims
+  column names it can determine (aliases, simple identifiers, resolvable
+  `select *`); anything ambiguous is skipped, so E010 never false-flags.
+- **E006 looks only at table positions** (`FROM`, `JOIN`, `INTO`, `UPDATE`),
+  ignores `FROM` used as function syntax (`extract(dow from d.date)`), function
+  calls (`public.my_func(1)`), and anything inside `${…}`.
+- **S102 understands sqlanvil's text**: `;` inside string literals, `$$`
+  dollar-quoted PL/pgSQL bodies, and `${…}` JavaScript regions never count; a
+  single trailing `;` is fine.
+- **Declarations are exempt** from E003/E004 deliberately: raw source schemas
+  legitimately carry environment-suffixed names, and `name:` is required.
+- Rule codes are stable; gaps in the numbering are historical.
+
+## Agent Skill
+
+The `sqlanvil-sqlx-lint` Agent Skill teaches AI coding agents (Claude Code,
+Codex CLI, Cursor, or any tool supporting the open
+[Agent Skills](https://agentskills.io/) format) to run this linter on every
+`.sqlx` file they create or modify. It lives with the other SQLAnvil skills:
+
+```bash
+npx skills add SQLAnvil/agent-skills
+```
+
+Source: https://github.com/SQLAnvil/agent-skills
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e . pytest
+.venv/bin/pytest        # 103 tests
+```
+
+## License
+
+MIT — see [LICENSE](https://github.com/SQLAnvil/sqlanvil-sqlx-lint/blob/main/LICENSE).

sqlanvil_sqlx_lint-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sqlanvil_sqlx_lint/__init__.py,sha256=vZ2G-6qui9zFl1uP3z4kexym87fWLyb_8dhREUszDs0,392
+sqlanvil_sqlx_lint/cli.py,sha256=MyGUcUk7O6NUvW8TnzvzKQ4zic3Kknz_M_NQOeuPNl8,2988
+sqlanvil_sqlx_lint/config.py,sha256=aWr25wHD-dUDWHUksFBCTG3G7cAS32NzlUQcsoGTDR4,7102
+sqlanvil_sqlx_lint/linter.py,sha256=wTqqhKddVFUoDb-AtjBVQvsTLNsUfeyFistOHHunhU8,23520
+sqlanvil_sqlx_lint-0.2.0.dist-info/licenses/LICENSE,sha256=sEjSXURI0VV68CEdvtVXe2Kfa-ML9me5UvEuYzjwIHI,1164
+sqlanvil_sqlx_lint-0.2.0.dist-info/METADATA,sha256=OJC5nnwUAG1IFsDpcWggN5aSOtZiPQ8jEXwqbegwxqU,8687
+sqlanvil_sqlx_lint-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sqlanvil_sqlx_lint-0.2.0.dist-info/entry_points.txt,sha256=PZM-WS2yaoWrqLOqziFhVui0IkdzVIBlD_xv4rTPwiQ,73
+sqlanvil_sqlx_lint-0.2.0.dist-info/top_level.txt,sha256=jxsJtUo4ZiGgVLLX6pGy9vxqv6ssKiaNQbj0tzKp3HM,19
+sqlanvil_sqlx_lint-0.2.0.dist-info/RECORD,,

sqlanvil_sqlx_lint-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sqlanvil_sqlx_lint-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sqlanvil-sqlx-lint = sqlanvil_sqlx_lint.cli:entrypoint

sqlanvil_sqlx_lint-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Acuantia (original dataform-sqlx-lint)
+Copyright (c) 2026 Ivan Histand / SQLAnvil (sqlanvil-sqlx-lint fork)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sqlanvil_sqlx_lint-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sqlanvil_sqlx_lint