dataform-sqlx-lint 0.1.1__tar.gz → 0.2.0__tar.gz

{dataform_sqlx_lint-0.1.1/src/dataform_sqlx_lint.egg-info → dataform_sqlx_lint-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataform-sqlx-lint
-Version: 0.1.1
+Version: 0.2.0
 Summary: Convention linter for Dataform .sqlx files — checks the config-block and project conventions that SQL linters cannot see
 Author-email: Ivan Histand <ihistand@rotoplas.com>
 License-Expression: MIT
@@ -42,6 +42,7 @@ pip install dataform-sqlx-lint
 | 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; Dataform accepts either) |
 | 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 |
+| E011 | on* | `FOREIGN KEY` written by hand in `post_operations` under configured paths — for projects that declare keys once in a map and generate both the DDL and the referential assertions from it (*no-op until `foreign_key_paths` is configured) |
 
 Why E010 matters: `columns: {}` is what Dataform writes to BigQuery column
 descriptions — the metadata data catalogs, BI tools, and AI/conversational
@@ -78,6 +79,8 @@ documented_types = ["table", "view", "incremental", "declaration"]  # E002
 coverage_paths = ["definitions/output/"]   # E010 scope; empty = everywhere
 enable = ["E005", "W008"]                  # switch on opt-in rules
 disable = ["E004"]                         # switch off default rules
+foreign_key_paths = ["definitions/output/"] # E011 scope; empty = rule off
+foreign_key_hint = "includes/keys.js"      # named in E011's message
 
 [[dir_policies]]                           # E007 (repeatable)
 path_contains = "definitions/output/looker/"
@@ -118,13 +121,16 @@ Suppress with a reason, sparingly — the convention is usually the fix.
 [Agent Skill](https://agentskills.io/) — instructions that teach AI coding
 agents (Claude Code, Gemini CLI, Cursor, or any tool supporting the open
 skills format) to run this linter on every `.sqlx` file they create or
-modify. Install it by copying the folder into your agent's skills directory.
+modify. Install it by copying the folder into your agent's skills directory —
+or paste one of the ready-made prompts in
+[skills/dataform-sqlx-lint/INSTALL_PROMPTS.md](https://github.com/acuantia/dataform-sqlx-lint/blob/main/skills/dataform-sqlx-lint/INSTALL_PROMPTS.md)
+and let the agent install itself.
 
 ## Development
 
 ```bash
 python3 -m venv .venv && .venv/bin/pip install -e . pytest
-.venv/bin/pytest        # 53 tests
+.venv/bin/pytest        # 59 tests
 ```
 
 ## License

{dataform_sqlx_lint-0.1.1 → dataform_sqlx_lint-0.2.0}/README.md

@@ -25,6 +25,7 @@ pip install dataform-sqlx-lint
 | 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; Dataform accepts either) |
 | 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 |
+| E011 | on* | `FOREIGN KEY` written by hand in `post_operations` under configured paths — for projects that declare keys once in a map and generate both the DDL and the referential assertions from it (*no-op until `foreign_key_paths` is configured) |
 
 Why E010 matters: `columns: {}` is what Dataform writes to BigQuery column
 descriptions — the metadata data catalogs, BI tools, and AI/conversational
@@ -61,6 +62,8 @@ documented_types = ["table", "view", "incremental", "declaration"]  # E002
 coverage_paths = ["definitions/output/"]   # E010 scope; empty = everywhere
 enable = ["E005", "W008"]                  # switch on opt-in rules
 disable = ["E004"]                         # switch off default rules
+foreign_key_paths = ["definitions/output/"] # E011 scope; empty = rule off
+foreign_key_hint = "includes/keys.js"      # named in E011's message
 
 [[dir_policies]]                           # E007 (repeatable)
 path_contains = "definitions/output/looker/"
@@ -101,13 +104,16 @@ Suppress with a reason, sparingly — the convention is usually the fix.
 [Agent Skill](https://agentskills.io/) — instructions that teach AI coding
 agents (Claude Code, Gemini CLI, Cursor, or any tool supporting the open
 skills format) to run this linter on every `.sqlx` file they create or
-modify. Install it by copying the folder into your agent's skills directory.
+modify. Install it by copying the folder into your agent's skills directory —
+or paste one of the ready-made prompts in
+[skills/dataform-sqlx-lint/INSTALL_PROMPTS.md](https://github.com/acuantia/dataform-sqlx-lint/blob/main/skills/dataform-sqlx-lint/INSTALL_PROMPTS.md)
+and let the agent install itself.
 
 ## Development
 
 ```bash
 python3 -m venv .venv && .venv/bin/pip install -e . pytest
-.venv/bin/pytest        # 53 tests
+.venv/bin/pytest        # 59 tests
 ```
 
 ## License

{dataform_sqlx_lint-0.1.1 → dataform_sqlx_lint-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dataform-sqlx-lint"
-version = "0.1.1"
+version = "0.2.0"
 description = "Convention linter for Dataform .sqlx files — checks the config-block and project conventions that SQL linters cannot see"
 readme = "README.md"
 requires-python = ">=3.11"

{dataform_sqlx_lint-0.1.1 → dataform_sqlx_lint-0.2.0}/src/dataform_sqlx_lint/__init__.py

@@ -4,4 +4,4 @@ from .config import Config, DirPolicy, load_config
 from .linter import Finding, lint_file, lint_text
 
 __all__ = ["Config", "DirPolicy", "Finding", "lint_file", "lint_text", "load_config"]
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{dataform_sqlx_lint-0.1.1 → dataform_sqlx_lint-0.2.0}/src/dataform_sqlx_lint/config.py

@@ -11,7 +11,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 #: Rules that run unless disabled.
-DEFAULT_ENABLED = {"E001", "E002", "E003", "E004", "E006", "E007", "E010"}
+DEFAULT_ENABLED = {"E001", "E002", "E003", "E004", "E006", "E007", "E010", "E011"}
 #: Opt-in rules (house-style checks): enable via `enable = [...]`.
 OPT_IN = {"E005", "W008"}
 
@@ -35,6 +35,10 @@ class Config:
     #: E010 applies only to files whose path contains one of these; empty = all.
     coverage_paths: list[str] = field(default_factory=list)
     dir_policies: list[DirPolicy] = field(default_factory=list)
+    #: E011 applies only to files whose path contains one of these; empty = rule is a no-op.
+    foreign_key_paths: list[str] = field(default_factory=list)
+    #: Where E011 tells the author to declare the key instead (named in the message).
+    foreign_key_hint: str | None = None
     enabled_extra: set[str] = field(default_factory=set)
     disabled: set[str] = field(default_factory=set)
 
@@ -51,6 +55,8 @@ class Config:
             and self.documented_types == other.documented_types
             and self.coverage_paths == other.coverage_paths
             and self.dir_policies == other.dir_policies
+            and self.foreign_key_paths == other.foreign_key_paths
+            and self.foreign_key_hint == other.foreign_key_hint
             and self.enabled_extra == other.enabled_extra
             and self.disabled == other.disabled
         )
@@ -61,6 +67,8 @@ _KNOWN_KEYS = {
     "documented_types",
     "coverage_paths",
     "dir_policies",
+    "foreign_key_paths",
+    "foreign_key_hint",
     "enable",
     "disable",
 }
@@ -88,6 +96,10 @@ def _from_dict(raw: dict) -> Config:
         kwargs["documented_types"] = set(raw["documented_types"])
     if "coverage_paths" in raw:
         kwargs["coverage_paths"] = list(raw["coverage_paths"])
+    if "foreign_key_paths" in raw:
+        kwargs["foreign_key_paths"] = list(raw["foreign_key_paths"])
+    if "foreign_key_hint" in raw:
+        kwargs["foreign_key_hint"] = str(raw["foreign_key_hint"])
     return Config(
         dir_policies=policies,
         enabled_extra=set(raw.get("enable", [])),

{dataform_sqlx_lint-0.1.1 → dataform_sqlx_lint-0.2.0}/src/dataform_sqlx_lint/linter.py

@@ -12,6 +12,7 @@ offending line or `-- sqlx-lint: disable-file=E006` anywhere in the file):
   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
+  E011  FOREIGN KEY written by hand in post_operations (configured paths) [no-op until configured]
 """
 
 from __future__ import annotations
@@ -358,6 +359,22 @@ def lint_text(text, path, config: Config | None = None, resolver=None):
                 f"column(s): {shown}{more}",
             )
 
+    # --- E011: hand-written foreign keys in post_operations (configured paths) ---
+    # Projects that generate FK DDL from one declared map (so the constraint and its
+    # referential test cannot drift apart) flag any ADD CONSTRAINT ... FOREIGN KEY that
+    # bypasses the map. Comments are stripped first, so a note like
+    # "-- No FK to looker_product" never trips it.
+    if cfg.foreign_key_paths and any(p in path for p in cfg.foreign_key_paths):
+        where = cfg.foreign_key_hint or "the project's foreign-key map"
+        for fm in re.finditer(r"\bFOREIGN\s+KEY\b", clean_body, re.I):
+            add(
+                "E011",
+                "error",
+                _line_of(text, body_offset + fm.start()),
+                f"foreign key written by hand in post_operations; declare it in "
+                f"{where} and let the map's helper emit the DDL",
+            )
+
     # --- W008 (opt-in): post_operations placement ---
     pm = re.search(r"\bpost_operations\s*{", body)
     if pm:

{dataform_sqlx_lint-0.1.1 → dataform_sqlx_lint-0.2.0/src/dataform_sqlx_lint.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataform-sqlx-lint
-Version: 0.1.1
+Version: 0.2.0
 Summary: Convention linter for Dataform .sqlx files — checks the config-block and project conventions that SQL linters cannot see
 Author-email: Ivan Histand <ihistand@rotoplas.com>
 License-Expression: MIT
@@ -42,6 +42,7 @@ pip install dataform-sqlx-lint
 | 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; Dataform accepts either) |
 | 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 |
+| E011 | on* | `FOREIGN KEY` written by hand in `post_operations` under configured paths — for projects that declare keys once in a map and generate both the DDL and the referential assertions from it (*no-op until `foreign_key_paths` is configured) |
 
 Why E010 matters: `columns: {}` is what Dataform writes to BigQuery column
 descriptions — the metadata data catalogs, BI tools, and AI/conversational
@@ -78,6 +79,8 @@ documented_types = ["table", "view", "incremental", "declaration"]  # E002
 coverage_paths = ["definitions/output/"]   # E010 scope; empty = everywhere
 enable = ["E005", "W008"]                  # switch on opt-in rules
 disable = ["E004"]                         # switch off default rules
+foreign_key_paths = ["definitions/output/"] # E011 scope; empty = rule off
+foreign_key_hint = "includes/keys.js"      # named in E011's message
 
 [[dir_policies]]                           # E007 (repeatable)
 path_contains = "definitions/output/looker/"
@@ -118,13 +121,16 @@ Suppress with a reason, sparingly — the convention is usually the fix.
 [Agent Skill](https://agentskills.io/) — instructions that teach AI coding
 agents (Claude Code, Gemini CLI, Cursor, or any tool supporting the open
 skills format) to run this linter on every `.sqlx` file they create or
-modify. Install it by copying the folder into your agent's skills directory.
+modify. Install it by copying the folder into your agent's skills directory —
+or paste one of the ready-made prompts in
+[skills/dataform-sqlx-lint/INSTALL_PROMPTS.md](https://github.com/acuantia/dataform-sqlx-lint/blob/main/skills/dataform-sqlx-lint/INSTALL_PROMPTS.md)
+and let the agent install itself.
 
 ## Development
 
 ```bash
 python3 -m venv .venv && .venv/bin/pip install -e . pytest
-.venv/bin/pytest        # 53 tests
+.venv/bin/pytest        # 59 tests
 ```
 
 ## License

{dataform_sqlx_lint-0.1.1 → dataform_sqlx_lint-0.2.0}/tests/test_config.py

@@ -7,6 +7,8 @@ schema_suffixes = ["_prod", "_dev", "_staging"]
 coverage_paths = ["definitions/output/looker/"]
 enable = ["E005", "W008"]
 disable = ["E004"]
+foreign_key_paths = ["definitions/output/looker/"]
+foreign_key_hint = "includes/keys.js"
 
 [[dir_policies]]
 path_contains = "definitions/output/looker/"
@@ -27,6 +29,8 @@ def test_load_standalone_toml(tmp_path):
     assert cfg.coverage_paths == ["definitions/output/looker/"]
     assert "E005" in cfg.enabled_extra and "W008" in cfg.enabled_extra
     assert "E004" in cfg.disabled
+    assert cfg.foreign_key_paths == ["definitions/output/looker/"]
+    assert cfg.foreign_key_hint == "includes/keys.js"
     assert len(cfg.dir_policies) == 2
     assert cfg.dir_policies[0].require_prefix == "looker_"
     assert cfg.dir_policies[1].severity == "warning"

{dataform_sqlx_lint-0.1.1 → dataform_sqlx_lint-0.2.0}/tests/test_lint.py

@@ -369,3 +369,74 @@ class TestE010ColumnCoverage:
         cfg = Config(disabled={"E010"})
         text = self._table('a: "A."', 'select a, b from ${ref("t")}')
         assert "E010" not in codes(lint_text(text, PATH, config=cfg))
+
+
+class TestE011HandWrittenForeignKeys:
+    FK_PATH = "definitions/output/looker/looker_orders.sqlx"
+    CFG = Config(
+        foreign_key_paths=["definitions/output/looker/"],
+        foreign_key_hint="includes/keys.js",
+    )
+
+    def _table(self, post_ops):
+        return (
+            'config {\n    type: "table",\n    schema: "looker",\n'
+            '    columns: { order_id: "Order." }\n}\n\n'
+            'select order_id from ${ref("vw_orders")}\n\n'
+            f"post_operations {{\n  ALTER TABLE ${{self()}}\n{post_ops}\n}}\n"
+        )
+
+    HAND_WRITTEN = (
+        "    ADD PRIMARY KEY (order_id) NOT ENFORCED,\n"
+        "    ADD CONSTRAINT o_to_c FOREIGN KEY (customer_id) "
+        'REFERENCES ${ref("looker_customer")}(customer_id) NOT ENFORCED;'
+    )
+    GENERATED = (
+        "    ADD PRIMARY KEY (order_id) NOT ENFORCED,\n"
+        "    -- No FK to looker_product: kept ids of deleted products.\n"
+        "    ${keys.fkAdd(self, ref)};"
+    )
+
+    def test_hand_written_fk_flagged_in_scope(self):
+        found = [
+            f
+            for f in lint_text(self._table(self.HAND_WRITTEN), self.FK_PATH, config=self.CFG)
+            if f.code == "E011"
+        ]
+        assert len(found) == 1
+        assert "includes/keys.js" in found[0].message
+        assert found[0].line == 12
+
+    def test_generated_fk_and_comments_pass(self):
+        assert "E011" not in codes(
+            lint_text(self._table(self.GENERATED), self.FK_PATH, config=self.CFG)
+        )
+
+    def test_out_of_scope_path_not_flagged(self):
+        assert "E011" not in codes(
+            lint_text(
+                self._table(self.HAND_WRITTEN),
+                "definitions/output/reports/orders.sqlx",
+                config=self.CFG,
+            )
+        )
+
+    def test_no_op_without_configured_paths(self):
+        assert "E011" not in codes(lint_text(self._table(self.HAND_WRITTEN), self.FK_PATH))
+
+    def test_default_hint_when_unconfigured(self):
+        cfg = Config(foreign_key_paths=["definitions/output/looker/"])
+        found = [
+            f
+            for f in lint_text(self._table(self.HAND_WRITTEN), self.FK_PATH, config=cfg)
+            if f.code == "E011"
+        ]
+        assert found and "foreign-key map" in found[0].message
+
+    def test_line_suppression(self):
+        text = self._table(
+            self.HAND_WRITTEN.replace(
+                "NOT ENFORCED;", "NOT ENFORCED; -- sqlx-lint: disable=E011 (legacy)"
+            )
+        )
+        assert "E011" not in codes(lint_text(text, self.FK_PATH, config=self.CFG))