ci: add pre-commit markdownlint gate for staged .md files#232
Merged
Conversation
- Add .github/hooks/pre-commit: lints only staged .md files via markdownlint-cli2 - Hook degrades gracefully (warns, does not block) if binary not found - Update scripts/install-hooks.sh to install pre-commit hook alongside pre-push - Add markdownlint-cli2 ^0.17.2 as dev dependency in package.json - Uses repo .markdownlint.json config for consistent rule enforcement Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
Bot
added
the
squad
Contributor
🏗️ PR Added to Squad Triage QueueThis PR has been labeled with Next steps:
|
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
mpaulosky
enabled auto-merge (squash)
May 6, 2026 05:48
There was a problem hiding this comment.
Pull request overview
Adds a new local pre-commit git hook to lint staged Markdown files before commit, and wires it into the existing hook installation flow, backed by a new npm dev dependency.
Changes:
- Added
.github/hooks/pre-committo run markdown linting against staged.mdfiles. - Updated
scripts/install-hooks.shto installpre-commitalongside existing hooks and to print updated guidance. - Added
markdownlint-cli2topackage.jsonand updatedpackage-lock.json.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
.github/hooks/pre-commit |
New pre-commit gate that runs markdown linting on staged Markdown files. |
scripts/install-hooks.sh |
Installs the new pre-commit hook and updates the post-install summary output. |
package.json |
Adds markdownlint-cli2 as a dev dependency. |
package-lock.json |
Lockfile update reflecting the new dev dependency tree. |
Comment on lines
89
to
90
| echo " 3. Unit/arch tests (tests/Architecture.Tests, tests/Unit.Tests)" | ||
| echo " 4. Integration tests (tests/Integration.Tests — Docker required)" |
Comment on lines
+24
to
+30
| if command -v markdownlint &>/dev/null; then | ||
| MARKDOWNLINT_BIN="markdownlint" | ||
| elif [[ -x "$ROOT/node_modules/.bin/markdownlint-cli2" ]]; then | ||
| MARKDOWNLINT_BIN="$ROOT/node_modules/.bin/markdownlint-cli2" | ||
| elif [[ -x "$ROOT/node_modules/.bin/markdownlint" ]]; then | ||
| MARKDOWNLINT_BIN="$ROOT/node_modules/.bin/markdownlint" | ||
| fi |
Comment on lines
+19
to
+21
| echo -e "${CYAN}━━━ Pre-Commit Markdownlint Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}" | ||
|
|
||
| # ── Probe for markdownlint binary ────────────────────────────────────────── |
Comment on lines
+45
to
+55
| CONFIG_FLAG="" | ||
| if [[ -f "$ROOT/.markdownlint.json" ]]; then | ||
| if [[ "$(basename "$MARKDOWNLINT_BIN")" == "markdownlint-cli2" ]]; then | ||
| CONFIG_FLAG="--config $ROOT/.markdownlint.json" | ||
| else | ||
| CONFIG_FLAG="--config $ROOT/.markdownlint.json" | ||
| fi | ||
| fi | ||
|
|
||
| # shellcheck disable=SC2086 | ||
| if "$MARKDOWNLINT_BIN" $CONFIG_FLAG "${MD_FILES[@]}" 2>&1; then |
Comment on lines
+47
to
+51
| if [[ "$(basename "$MARKDOWNLINT_BIN")" == "markdownlint-cli2" ]]; then | ||
| CONFIG_FLAG="--config $ROOT/.markdownlint.json" | ||
| else | ||
| CONFIG_FLAG="--config $ROOT/.markdownlint.json" | ||
| fi |
Comment on lines
+12
to
+17
| # ── Collect staged .md files ─────────────────────────────────────────────── | ||
| STAGED_MD=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$' || true) | ||
|
|
||
| if [[ -z "$STAGED_MD" ]]; then | ||
| exit 0 | ||
| fi |
| fi | ||
|
|
||
| # shellcheck disable=SC2086 | ||
| if "$MARKDOWNLINT_BIN" $CONFIG_FLAG "${MD_FILES[@]}" 2>&1; then |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## dev #232 +/- ##
=======================================
Coverage 78.64% 78.64%
=======================================
Files 43 43
Lines 721 721
Branches 112 112
=======================================
Hits 567 567
Misses 108 108
Partials 46 46 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a pre-commit git hook that runs
markdownlint-cli2on staged.mdfiles before each local commit, preventing formatting violations from ever entering commits.Changes
.github/hooks/pre-commit— new hook that:.mdfiles (fast: never scans the whole repo).markdownlint.jsonconfig for consistent rulesmarkdownlint-cli2is not installed (warns, does not block)scripts/install-hooks.sh— updated to installpre-commitalongsidepre-push; updated summary messagepackage.json— addsmarkdownlint-cli2 ^0.17.2as dev dependencypackage-lock.json— updated lockfileTesting
.mdfile → hook exits 0 silently ✅.mdfile with violations → hook exits 1 with clear error output showing file and rule ✅Context
Follows up on PR #229 which fixed 3,243+ markdownlint violations and added
.markdownlint.json. This gate prevents regressions at commit time.Working as Aragorn (Lead / Architect)