From 4a72f2f4071ec4bed5fd65a550d4ad82e527d49c Mon Sep 17 00:00:00 2001
From: marcusquinn <6428977+marcusquinn@users.noreply.github.com>
Date: Sat, 14 Mar 2026 09:06:53 +0000
Subject: [PATCH] fix(linters): handle markdownlint execution errors separately
 from rule violations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When markdownlint fails due to bad config, invalid arguments, or other
non-rule errors, the output won't match the MD[0-9] pattern, causing
violation_count=0 and a false success return—even in blocking mode.

Capture lint_exit separately (|| lint_exit=$?) and treat non-zero exit
codes as blocking errors in changed-file mode and advisory warnings in
full-scan mode. Covers both cases: output present (non-rule error message)
and no output (silent config parse failure).

Closes #3505
Addresses CodeRabbit review on PR #271
---
 .agents/scripts/linters-local.sh | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/.agents/scripts/linters-local.sh b/.agents/scripts/linters-local.sh
index 50652b21ad..a2573bcda2 100755
--- a/.agents/scripts/linters-local.sh
+++ b/.agents/scripts/linters-local.sh
@@ -509,9 +509,9 @@ check_markdown_lint() {
 	fi
 
 	if [[ -n "$markdownlint_cmd" ]]; then
-		# Run markdownlint and capture output
-		local lint_output
-		lint_output=$($markdownlint_cmd $md_files 2>&1) || true
+		# Run markdownlint and capture output; preserve exit code separately
+		local lint_output lint_exit=0
+		lint_output=$($markdownlint_cmd $md_files 2>&1) || lint_exit=$?
 
 		if [[ -n "$lint_output" ]]; then
 			# Count violations - ensure single integer (grep -c can fail, use wc -l as fallback)
@@ -539,6 +539,24 @@ check_markdown_lint() {
 					print_warning "Markdown: $violations style issues found (advisory)"
 					return 0
 				fi
+			elif [[ $lint_exit -ne 0 ]]; then
+				# markdownlint failed for a non-rule reason (bad config, invalid args, etc.)
+				# Output doesn't match MD[0-9] pattern so violation_count=0, but the tool itself errored
+				print_error "Markdown: markdownlint failed with exit code $lint_exit (non-rule error)"
+				echo "$lint_output"
+				if [[ "$check_mode" == "changed" ]]; then
+					return 1
+				else
+					return 0
+				fi
+			fi
+		elif [[ $lint_exit -ne 0 ]]; then
+			# markdownlint failed with no output (e.g., config parse error with no stderr)
+			print_error "Markdown: markdownlint failed with exit code $lint_exit (no output)"
+			if [[ "$check_mode" == "changed" ]]; then
+				return 1
+			else
+				return 0
 			fi
 		fi
 		print_success "Markdown: No style issues found"