build: add commit message tooling

.github/workflows/main.yml

@@ -24,6 +24,37 @@ env:
   LITD_ITEST_BRANCH: master
 
 jobs:
+  ########################
+  # commit message lint
+  ########################
+  commit-message:
+    name: Commit Message
+    runs-on: ubuntu-latest
+    steps:
+      - name: git checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Lint commit messages
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          BEFORE_SHA: ${{ github.event.before }}
+          GITHUB_SHA: ${{ github.sha }}
+        run: |
+          if [ "$EVENT_NAME" = "pull_request" ]; then
+            range="$BASE_SHA..$HEAD_SHA"
+          elif [ "$EVENT_NAME" = "push" ] &&
+               [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
+            range="$BEFORE_SHA..$GITHUB_SHA"
+          else
+            range="$(git rev-parse HEAD^ 2>/dev/null)..HEAD"
+          fi
+
+          make commitmsg-lint range="$range"
+
   ########################
   # RPC compile and check
   ########################

Makefile

@@ -174,6 +174,43 @@ endif
 	cd tools/ && GOPROXY=direct $(GOMOD) tidy
 	if test -n "$$(git status --porcelain)"; then echo "Running go mod tidy changes go.mod/go.sum"; git status; git diff; exit 1; fi
 
+commitmsg-lint:
+	@$(call print, "Linting commit message(s).")
+	@if [ -n "$(range)" ]; then \
+		./scripts/commit_message.py lint --range "$(range)"; \
+	elif [ -n "$(commit)" ]; then \
+		./scripts/commit_message.py lint --commit "$(commit)"; \
+	elif [ -n "$(file)" ]; then \
+		./scripts/commit_message.py lint --file "$(file)"; \
+	else \
+		./scripts/commit_message.py lint --commit HEAD; \
+	fi
+
+commitmsg-fmt:
+	@$(call print, "Formatting commit message.")
+	@if [ -n "$(file)" ]; then \
+		if [ "$(inplace)" = "1" ]; then \
+			./scripts/commit_message.py fmt --file "$(file)" --in-place \
+				$(if $(filter 1,$(decode)),--decode-escaped-newlines,); \
+		else \
+			./scripts/commit_message.py fmt --file "$(file)" \
+				$(if $(filter 1,$(decode)),--decode-escaped-newlines,); \
+		fi; \
+	elif [ -n "$(commit)" ]; then \
+		./scripts/commit_message.py fmt --commit "$(commit)" \
+			$(if $(filter 1,$(decode)),--decode-escaped-newlines,); \
+	else \
+		echo "Error: provide file=<path> or commit=<rev>"; \
+		exit 1; \
+	fi
+
+commitmsg-reword:
+	@$(call print, "Rewording commit with formatted message.")
+	@./scripts/commit_message.py reword \
+		--commit "$(if $(commit),$(commit),HEAD)" \
+		$(if $(filter 1,$(decode)),--decode-escaped-newlines,) \
+		$(if $(filter 1,$(dryrun)),--dry-run,)
+
 sqlc:
 	@$(call print, "Generating sql models and queries in Go")
 	./scripts/gen_sqlc_docker.sh

docs/commit-tooling.md

@@ -0,0 +1,30 @@
+# Commit Message Tooling
+
+Use `scripts/commit_message.py` to lint, format, and safely reword commit
+messages. The script enforces subject/body wrapping (`69`/`72`), keeps real
+newlines, and preserves markdown-like body structure (lists, quotes, fenced
+blocks, trailers).
+
+## Common Workflows
+
+```bash
+# Lint the current commit message
+make commitmsg-lint commit=HEAD
+
+# Lint a commit range
+make commitmsg-lint range=upstream/master..HEAD
+
+# Format a message file in place
+make commitmsg-fmt file=/tmp/msg inplace=1
+
+# Reword a commit from formatted output
+make commitmsg-reword commit=<sha>
+
+# Preview a reword without rewriting history
+make commitmsg-reword commit=<sha> dryrun=1
+```
+
+## Literal Newlines
+
+If a message was created with literal `\n` sequences, use `decode=1` with
+`commitmsg-fmt` or `commitmsg-reword` to convert them to real line breaks.