sarj-sql-lint 0.1.0__tar.gz

sarj_sql_lint-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+node_modules/
+dist/
+build/
+*.tgz
+.npm/
+*.tsbuildinfo
+.turbo/
+.tsup/
+.vitest-cache/
+.eslintcache
+coverage/
+
+__pycache__/
+*.py[co]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.basedpyright/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.venv/
+venv/
+*.egg-info/
+
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+.zed/
+*.swp

sarj_sql_lint-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: sarj-sql-lint
+Version: 0.1.0
+Summary: Custom SQL lint rules for Postgres migrations — sqlfluff + pygrep, pre-commit-friendly.
+Project-URL: Homepage, https://github.com/sarj-ai/linting/tree/main/packages/sql
+Project-URL: Repository, https://github.com/sarj-ai/linting
+Project-URL: Issues, https://github.com/sarj-ai/linting/issues
+Author: sarj-ai
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.13
+Requires-Dist: sqlfluff>=3.0
+Description-Content-Type: text/markdown
+
+# sarj-sql-lint
+
+Custom SQL lint rules for Postgres migrations. AST-based via [sqlfluff](https://sqlfluff.com) for the SARJ101 rule + zero-dependency pygrep regex hooks for migration-hygiene checks. Designed for pre-commit.
+
+```bash
+uv tool install sarj-sql-lint
+```
+
+## Pre-commit
+
+```yaml
+- repo: https://github.com/sarj-ai/linting
+  rev: sql-v0.1.0
+  hooks:
+    - id: sarj-enforce-timestamptz
+      files: '\.sql$'
+    - id: sarj-ban-postgres-enums
+      files: '\.sql$'
+    - id: sarj-ban-create-trigger
+      files: '\.sql$'
+    - id: sarj-prefer-text-over-varchar
+      files: '\.sql$'
+```
+
+## CLI
+
+```bash
+sarj-sql-lint check --rule enforce-timestamptz svcs/db/db/migrations/*.sql
+sarj-sql-lint list-rules
+```
+
+Diagnostic format is `path:line:col: CODE message` — Ruff-compatible.
+
+Each rule's source under `src/sarj_sql_lint/rules/` carries its own `description` and diagnostic message.

sarj_sql_lint-0.1.0/README.md

@@ -0,0 +1,34 @@
+# sarj-sql-lint
+
+Custom SQL lint rules for Postgres migrations. AST-based via [sqlfluff](https://sqlfluff.com) for the SARJ101 rule + zero-dependency pygrep regex hooks for migration-hygiene checks. Designed for pre-commit.
+
+```bash
+uv tool install sarj-sql-lint
+```
+
+## Pre-commit
+
+```yaml
+- repo: https://github.com/sarj-ai/linting
+  rev: sql-v0.1.0
+  hooks:
+    - id: sarj-enforce-timestamptz
+      files: '\.sql$'
+    - id: sarj-ban-postgres-enums
+      files: '\.sql$'
+    - id: sarj-ban-create-trigger
+      files: '\.sql$'
+    - id: sarj-prefer-text-over-varchar
+      files: '\.sql$'
+```
+
+## CLI
+
+```bash
+sarj-sql-lint check --rule enforce-timestamptz svcs/db/db/migrations/*.sql
+sarj-sql-lint list-rules
+```
+
+Diagnostic format is `path:line:col: CODE message` — Ruff-compatible.
+
+Each rule's source under `src/sarj_sql_lint/rules/` carries its own `description` and diagnostic message.

sarj_sql_lint-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "sarj-sql-lint"
+version = "0.1.0"
+description = "Custom SQL lint rules for Postgres migrations — sqlfluff + pygrep, pre-commit-friendly."
+readme = "README.md"
+authors = [{ name = "sarj-ai" }]
+license = { text = "MIT" }
+requires-python = ">=3.13"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+  "sqlfluff>=3.0",
+]
+
+[project.scripts]
+sarj-sql-lint = "sarj_sql_lint.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/sarj-ai/linting/tree/main/packages/sql"
+Repository = "https://github.com/sarj-ai/linting"
+Issues = "https://github.com/sarj-ai/linting/issues"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+  "pytest-benchmark>=4.0",
+  "ruff>=0.6",
+  "basedpyright>=1.20",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sarj_sql_lint"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src",
+  "README.md",
+  "pyproject.toml",
+]
+exclude = [
+  "tests/",
+  "**/__pycache__/",
+  "**/*.pyc",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sarj_sql_lint-0.1.0/src/sarj_sql_lint/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sarj_sql_lint-0.1.0/src/sarj_sql_lint/__main__.py

@@ -0,0 +1,87 @@
+"""CLI: sarj-sql-lint check --rule <id> [--rule <id2>] <files>"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from sarj_sql_lint import __version__
+from sarj_sql_lint.rule_base import Diagnostic
+from sarj_sql_lint.rules import REGISTRY
+
+
+SKIP_DIR_NAMES = {
+    "node_modules", ".venv", "venv", ".git", "dist", "build", ".next",
+    "coverage", "__pycache__", ".pytest_cache", ".ruff_cache", ".mypy_cache",
+    ".turbo", ".yarn", ".pnpm-store",
+}
+
+
+def _expand_paths(paths: list[Path]) -> list[Path]:
+    out: list[Path] = []
+    for p in paths:
+        if not p.exists():
+            continue
+        if p.is_file():
+            out.append(p)
+            continue
+        for child in p.rglob("*.sql"):
+            if not child.is_file():
+                continue
+            if any(part in SKIP_DIR_NAMES for part in child.parts):
+                continue
+            try:
+                if child.stat().st_size > 500_000:
+                    continue
+            except OSError:
+                continue
+            out.append(child)
+    return out
+
+
+def _check(rule_ids: list[str], paths: list[Path]) -> list[Diagnostic]:
+    unknown = [rid for rid in rule_ids if rid not in REGISTRY]
+    if unknown:
+        sys.stderr.write(f"unknown rule(s): {', '.join(unknown)}\n")
+        sys.stderr.write(f"available: {', '.join(sorted(REGISTRY))}\n")
+        raise SystemExit(2)
+    rules = [REGISTRY[rid]() for rid in rule_ids]
+    expanded = _expand_paths(paths)
+    diags: list[Diagnostic] = []
+    for p in expanded:
+        try:
+            source = p.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for rule in rules:
+            diags.extend(rule.check(p, source))
+    return diags
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="sarj-sql-lint", description="Custom SQL lint rules.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    check_p = sub.add_parser("check", help="Run rules over .sql files.")
+    check_p.add_argument("--rule", action="append", required=True, help="Rule ID (repeat for multiple).")
+    check_p.add_argument("files", nargs="+", type=Path)
+
+    sub.add_parser("list-rules", help="List available rule IDs.")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "list-rules":
+        for rid, cls in sorted(REGISTRY.items()):
+            inst = cls()
+            sys.stdout.write(f"{inst.code:8}  {rid:40}  {inst.description}\n")
+        return 0
+
+    diags = _check(args.rule, args.files)
+    for d in diags:
+        sys.stdout.write(d.format() + "\n")
+    return 1 if diags else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sarj_sql_lint-0.1.0/src/sarj_sql_lint/rule_base.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    path: Path
+    line: int
+    col: int
+    code: str
+    message: str
+
+    def format(self) -> str:
+        return f"{self.path}:{self.line}:{self.col}: {self.code} {self.message}"
+
+
+class Rule(ABC):
+    id: str
+    code: str
+    description: str
+
+    @abstractmethod
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        raise NotImplementedError

sarj_sql_lint-0.1.0/src/sarj_sql_lint/rules/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from sarj_sql_lint.rule_base import Rule
+from sarj_sql_lint.rules.enforce_timestamptz import EnforceTimestamptz
+
+
+REGISTRY: dict[str, type[Rule]] = {
+    EnforceTimestamptz.id: EnforceTimestamptz,
+}
+
+__all__ = ["REGISTRY"]

sarj_sql_lint-0.1.0/src/sarj_sql_lint/rules/enforce_timestamptz.py

@@ -0,0 +1,46 @@
+"""SARJ101: detect TIMESTAMP columns missing `WITH TIME ZONE`.
+
+Postgres `TIMESTAMP` without `WITH TIME ZONE` discards offset on INSERT,
+silently producing wrong timestamps for non-UTC clients. Use TIMESTAMPTZ.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from sarj_sql_lint.rule_base import Diagnostic, Rule
+
+
+PATTERN = re.compile(
+    r"\bTIMESTAMP\b(?!\s*TZ\b)(?!\s+WITH\s+TIME\s+ZONE\b)",
+    re.IGNORECASE,
+)
+
+
+class EnforceTimestamptz(Rule):
+    """Postgres TIMESTAMP without WITH TIME ZONE — use TIMESTAMPTZ."""
+
+    id = "enforce-timestamptz"
+    code = "SARJ101"
+    description = "TIMESTAMP without TIME ZONE — use TIMESTAMPTZ."
+
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        diags: list[Diagnostic] = []
+        for lineno, line in enumerate(source.splitlines(), start=1):
+            stripped = line.lstrip()
+            if stripped.startswith("--") or stripped.startswith("/*"):
+                continue
+            for match in PATTERN.finditer(line):
+                diags.append(
+                    Diagnostic(
+                        path=path,
+                        line=lineno,
+                        col=match.start() + 1,
+                        code=self.code,
+                        message=(
+                            "Use `TIMESTAMPTZ` (or `TIMESTAMP WITH TIME ZONE`) — "
+                            "naive TIMESTAMP discards offset and is rarely correct."
+                        ),
+                    )
+                )
+        return diags