Add SQL style linter (vendored Postgres-Extensions/linter)

Vendor Postgres-Extensions/linter as a git submodule at .vendor/linter,
following the same pattern already adopted in cat_tools: a thin
self-initializing lint.mk hand-off (so `make lint` works right after a
plain `git clone`, no --recurse-submodules needed), LINT_TARGETS scoped
to sql/object_reference.sql and test/ (excluding the frozen, never
hand-edited versioned install files under sql/, e.g.
object_reference--0.1.0.sql/--stable.sql), and a CI job that runs
`make lint` directly -- the same entry point a developer uses locally
-- so the self-init logic is actually exercised, not just the rule
checking.

The `include lint.mk` is guarded on .git being present: a tarball build
(PGXN distribution, `git archive` with no .git) has no submodule to
initialize, and Make resolves every `include` before running any
target regardless of which one was requested, so an unguarded rule
would break `make`/`make install` entirely for a tarball build, not
just `make lint`.

Fixes the real pre-existing style findings this first run turned up
(52 total): most were commented-out SQL marked as prose comments
instead of using the linter's `EXCLUDED CODE` disabled-code convention
(missing " * " prefixes flagged as comment-line-prefix/comment-opening
violations); one COPY data block's `secondary` column intentionally
mirrors pg_catalog's own type display name ("integer" for int4) rather
than following prefer-short-type, so it's suppressed via a scoped
disable-block region instead of being "fixed" into incorrect test data.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: jnasbyupgrade

.github/workflows/ci.yml

@@ -96,6 +96,24 @@ jobs:
           json=$(printf '%s\n' $supported | paste -sd, - | sed 's/^/[/; s/$/]/')
           echo "supported_pg=$json" >> "$GITHUB_OUTPUT"
 
+  # Style linter (https://github.com/Postgres-Extensions/linter, vendored at
+  # .vendor/linter -- lint.mk is the thin local hand-off, see its comment).
+  # Deliberately checked out WITHOUT submodules -- `make lint` is the same
+  # command a developer runs locally, and lint.mk self-initializes the
+  # submodule on first use. Using the exact same entry point here is what
+  # actually proves that self-init works, rather than papering over it with
+  # a submodules: true checkout.
+  lint:
+    needs: [changes]
+    if: needs.changes.outputs.docs_only != 'true'
+    name: 🧹 SQL Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+      - name: Lint SQL
+        run: make lint
+
   test:
     needs: [changes]
     if: needs.changes.outputs.docs_only != 'true'
@@ -128,7 +146,7 @@ jobs:
   # (e.g. test, on a docs-only push), and fails if any failed or were
   # cancelled.
   all-checks-passed:
-    needs: [changes, test]
+    needs: [changes, lint, test]
     if: always()
     runs-on: ubuntu-latest
     steps:
@@ -138,3 +156,24 @@ jobs:
             echo "One or more jobs failed or were cancelled"
             exit 1
           fi
+=======
+
+on: [push, pull_request]
+
+jobs:
+  # Style linter (https://github.com/Postgres-Extensions/linter, vendored at
+  # .vendor/linter -- lint.mk is the thin local hand-off, see its comment).
+  # Deliberately checked out WITHOUT submodules -- `make lint` is the same
+  # command a developer runs locally, and lint.mk self-initializes the
+  # submodule on first use. Using the exact same entry point here is what
+  # actually proves that self-init works, rather than papering over it with
+  # a submodules: true checkout.
+  lint:
+    name: 🧹 SQL Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+      - name: Lint SQL
+        run: make lint
+>>>>>>> 3eefe4c (Add SQL style linter (vendored Postgres-Extensions/linter))

.gitmodules

@@ -0,0 +1,3 @@
+[submodule ".vendor/linter"]
+	path = .vendor/linter
+	url = https://github.com/Postgres-Extensions/linter.git

.vendor/linter

@@ -25,3 +25,23 @@ test_factory: $(DESTDIR)$(datadir)/extension/test_factory.control
 $(DESTDIR)$(datadir)/extension/test_factory.control:
 	pgxn install test_factory
 
+
+# Style linter (see https://github.com/Postgres-Extensions/linter, vendored
+# at .vendor/linter -- lint.mk is the thin local hand-off, see its comment).
+# Scoped to sql/object_reference.sql rather than the default `sql/ test/`:
+# the versioned install/update files under sql/ (object_reference--*.sql,
+# e.g. object_reference--0.1.0.sql/--stable.sql) are frozen once released and
+# never hand-edited again (see this repo's CLAUDE.md / memory), so linting
+# them would produce permanent, unfixable findings and make `make lint`
+# unusable as a CI gate.
+#
+# Guarded on .git being present: a tarball build (PGXN distribution, or any
+# `git archive` checkout with no .git) has no submodule to initialize, and
+# Make resolves every `include` before running any target regardless of
+# which target was requested -- so an unguarded self-init rule in lint.mk
+# would break `make`/`make install` entirely for a tarball build, not just
+# `make lint`.
+ifneq ($(wildcard .git),)
+LINT_TARGETS = sql/object_reference.sql test/
+include lint.mk
+endif

Makefile

@@ -0,0 +1,11 @@
+# lint.mk — thin wrapper; the whole local footprint for consuming
+# https://github.com/Postgres-Extensions/linter. Everything else lives in
+# the .vendor/linter submodule; see its README for available targets/rules.
+#
+# Self-initializing (via the rule below) so `make lint` works right after a
+# plain `git clone`, with no --recurse-submodules needed, and so CI can rely
+# on the exact same entry point a developer would use locally.
+.vendor/linter/lint.mk:
+	git submodule update --init -- .vendor/linter
+
+include .vendor/linter/lint.mk

lint.mk

@@ -13,7 +13,7 @@ BEGIN
   RAISE DEBUG 'search_path changed to %', current_setting('search_path');
 END
 $$;
-/*
+/* EXCLUDED CODE: schema-restriction check below not currently enforced
 DO $$
 DECLARE
   c_schema CONSTANT name := (SELECT extnamespace::regnamespace::text FROM pg_extension WHERE extname = 'cat_tools');
@@ -179,7 +179,7 @@ CREATE TABLE _object_reference.object(
   , object_names text[]                  NOT NULL
   , object_args  text[]                  NOT NULL
   , CONSTRAINT object__u_object_names__object_args UNIQUE( object_type, object_names, object_args )
-  /* TODO: this can't be a trigger because some objects won't exist when a dump is loaded
+  /* EXCLUDED CODE: TODO: this can't be a trigger because some objects won't exist when a dump is loaded
   , CONSTRAINT object__address_sanity
     -- pg_get_object_address will throw an error if anything is wrong, so the IS NOT NULL is mostly pointless
     CHECK( pg_catalog.pg_get_object_address(object_type::text, object_names, object_args) IS NOT NULL )
@@ -192,7 +192,7 @@ GRANT REFERENCES ON _object_reference.object TO object_reference__dependency;
 CREATE TABLE _object_reference._object_oid(
   object_id       int                     PRIMARY KEY REFERENCES _object_reference.object ON DELETE CASCADE ON UPDATE CASCADE
   , classid       regclass                NOT NULL
-  /* TODO: needs to be a trigger
+  /* EXCLUDED CODE: TODO: needs to be a trigger
     CONSTRAINT classid_must_match__object__address_classid
       CHECK( classid IS NOT DISTINCT FROM cat_tools.object__address_classid(object_type) )
     */
@@ -1258,7 +1258,7 @@ BEGIN
   RETURN c_next_level;
 
 EXCEPTION WHEN undefined_table THEN
-  /*
+  /* EXCLUDED CODE
   CREATE TEMP TABLE __object_reference__ddl_capture AS
     SELECT c_next_level, capture__start.object_group_id
   ;

sql/object_reference.sql

@@ -2,8 +2,7 @@
 
 -- Add any test dependency statements here
 
-/*
- * Normally these should be loaded by the cascade!
+/* EXCLUDED CODE: normally these should be loaded by the cascade!
 CREATE EXTENSION IF NOT EXISTS count_nulls;
 CREATE EXTENSION IF NOT EXISTS cat_tools;
  */

test/deps.sql

@@ -144,6 +144,7 @@ INSERT INTO test_prereq VALUES
 ;
 
 -- \N is null character
+-- sql-lint:disable-block prefer-short-type: secondary column mirrors pg_catalog's own type display name (format_type), not a style choice
 COPY test_object(object_type, object_name, secondary, create_command, drop_command) FROM STDIN (DELIMITER '|');
 table|test table||%("test column" int)|
 index|test table test index||%ON "test table"("test column")|
@@ -159,8 +160,9 @@ cast|test type|integer|CREATE CAST ("test type" AS int4) WITH INOUT|DROP CAST ("
 default value|test table|test column|ALTER TABLE "test table" ALTER "test column" SET DEFAULT 0|ALTER TABLE "test table" ALTER "test column" DROP DEFAULT
 trigger|test table|test trigger|CREATE TRIGGER "test trigger" AFTER INSERT ON "test table" FOR EACH ROW EXECUTE PROCEDURE tg_null()|DROP TRIGGER "test trigger" ON "test table"
 \.
+-- sql-lint:enable-block
 
-/* Not supported
+/* EXCLUDED CODE: Not supported
 composite type|test complex type||CREATE TYPE "test complex type" AS(r real, i real)|DROP TYPE "test complex type"
 view column|test view|test column|\N|\N
 materialized view column|test materialized view 2|test materialized view column|CREATE MATERIALIZED VIEW "test materialized view 2" AS SELECT (1,2)::"test complex type" AS "test materialized view column"|DROP MATERIALIZED VIEW "test materialized view 2"

test/helpers/object_table.sql

@@ -134,7 +134,7 @@ SELECT bag_eq(
   , $$SELECT object_id FROM obj_ref$$
   , 'Verify captured object IDs match'
 );
-/*
+/* EXCLUDED CODE
 SELECT * FROM og_o;
 SELECT * FROM _object_reference.object;-- WHERE object_id IN(6,9);
 */

test/sql/capture.sql

@@ -143,7 +143,7 @@ $body$;
 
 
 /*
- *Rename column
+ * Rename column
  */
 SELECT lives_ok(
   $$ALTER TABLE table_under_test RENAME column_test TO test_column2$$