feat: add AsciiDoc linter pre-commit hook (#285)

[raifdmueller]

Summary

Adds asciidoc-linter as a pre-commit hook to catch AsciiDoc syntax errors before commit. This addresses issue #285.

Changes

1. AsciiDoc Linter Integration

Added:

• asciidoc-linter as dev dependency (installed from GitHub, not yet on PyPI)
• Local pre-commit hook in .pre-commit-config.yaml
• tool.hatch.metadata.allow-direct-references = true to support git dependencies

Runs on: All .adoc and .asciidoc files in the repository

2. Fixed Markdown Tables in ADRs

Converted incorrect Markdown table syntax to proper AsciiDoc format:

Before (Markdown):

| Dimension | Score | Level | Evidence |
|-----------|-------|-------|----------|
| Code Type | 2 | Business Logic | ... |

After (AsciiDoc):

[cols="2,1,2,5"]
|===
| Dimension | Score | Level | Evidence

| Code Type | 2 | Business Logic | ...
|===

Files fixed:

• src/docs/arc42/adr/ADR-011.adoc
• src/docs/arc42/adr/ADR-012.adoc

3. Documentation

Updated CLAUDE.md with:

• AsciiDoc linter setup instructions
• Known issues (WS001 false positives, Markdown table detection missing)
• Workaround guide for commits blocked by false positives
• Explanation of when to use --no-verify

Known Limitations

Linter Issues (reported upstream)

1. WS001 false positives (asciidoc-linter#41)

   • Incorrectly flags *bold* syntax as list markers
   • All ADR files trigger these warnings
   • Workaround: Use git commit --no-verify when only false positives present

2. Markdown tables NOT detected (asciidoc-linter#38)

   • Current linter does not catch |---|---| syntax
   • Manual review still required for table syntax
   • Feature request filed upstream

Feature Requests Filed

Also filed upstream enhancement requests:

• asciidoc-linter#39: Native pre-commit hooks support (.pre-commit-hooks.yaml)
• asciidoc-linter#40: Publish to PyPI for easier installation

Testing

Linter verification:

# Test on ADR with known Markdown table (manually found)
uv run asciidoc-linter src/docs/arc42/adr/ADR-011.adoc

# Run pre-commit hook manually
uv run pre-commit run asciidoc-linter --all-files

Results:

• ✅ Pre-commit hook executes successfully
• ✅ Detects WS001 issues (false positives on *bold*)
• ❌ Does NOT detect Markdown tables (expected - issue tech-debt: Content Access API - Element Types and Search Gaps #38)

Migration Guide

For contributors:

1. Install dev dependencies:

   uv sync --extra dev

2. Pre-commit hooks auto-install on first commit

3. If commit is blocked by WS001 false positives:

   • Review the warnings manually
   • If only false positives (verify *bold* syntax is correct):

     git commit --no-verify -m "your message"

4. Watch for real errors:

   • Incorrect table syntax (Markdown vs AsciiDoc)
   • Heading hierarchy issues
   • Unterminated blocks

Breaking Changes

None

Related Issues

• Closes Add AsciiDoc linter as pre-commit hook #285 (Add AsciiDoc linter)
• Depends on upstream fixes:
  • asciidoc-linter#38 - Markdown table detection
  • asciidoc-linter#41 - WS001 false positives

---

Generated with 🤖 Claude Code (AI-assisted development)

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com