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

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+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

.gitmodules

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

Makefile

@@ -32,3 +32,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

lint.mk

@@ -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

sql/object_reference--stable.sql

@@ -14,7 +14,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');
@@ -180,7 +180,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 )
@@ -193,7 +193,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) )
     */
@@ -1254,7 +1254,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

@@ -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) )
     */
@@ -1253,7 +1253,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
   ;

test/deps.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/helpers/object_table.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/sql/capture.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/event_trigger.sql

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

test/sql/object_group.sql

@@ -82,7 +82,7 @@ SELECT is(
 );
 
 -- __object__add
-/* TODO
+/* EXCLUDED CODE: TODO
 SELECT pg_temp.bogus_group(
   format(
     $$SELECT object_reference.object_group__object__add(%%s, %s)$$
@@ -107,7 +107,7 @@ SELECT throws_ok( -- Can't use helper here
   , 'object group "absurd group name used only for testing purposes ktxbye" does not exist'
   , 'object__getsert with bogus group name'
 );
-/* TODO
+/* EXCLUDED CODE: TODO
 SELECT throws_ok( -- Can't use helper here
   $$CREATE TEMP TABLE col1_id AS SELECT * FROM object_reference.object__getsert_w_group_id('table column', 'test_table_1', 'col1', -1)$$
   , ''