ramplint 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. ramplint-0.1.0/.gitignore +25 -0
  2. ramplint-0.1.0/CHANGELOG.md +25 -0
  3. ramplint-0.1.0/LICENSE +21 -0
  4. ramplint-0.1.0/PKG-INFO +317 -0
  5. ramplint-0.1.0/README.md +283 -0
  6. ramplint-0.1.0/docs/demo.svg +138 -0
  7. ramplint-0.1.0/examples/README.md +27 -0
  8. ramplint-0.1.0/examples/templates/accounts/login.html +20 -0
  9. ramplint-0.1.0/examples/templates/base.html +21 -0
  10. ramplint-0.1.0/examples/templates/clean/tricky_but_valid.html +44 -0
  11. ramplint-0.1.0/examples/templates/orders/list.html +28 -0
  12. ramplint-0.1.0/examples/templates/orders/list_fixed.html +29 -0
  13. ramplint-0.1.0/examples/templates/partials/footer.html +12 -0
  14. ramplint-0.1.0/examples/templates/partials/navbar.html +11 -0
  15. ramplint-0.1.0/examples/templates/products/detail.html +30 -0
  16. ramplint-0.1.0/pyproject.toml +70 -0
  17. ramplint-0.1.0/src/ramplint/__init__.py +16 -0
  18. ramplint-0.1.0/src/ramplint/__main__.py +5 -0
  19. ramplint-0.1.0/src/ramplint/cli.py +134 -0
  20. ramplint-0.1.0/src/ramplint/config.py +61 -0
  21. ramplint-0.1.0/src/ramplint/dom.py +152 -0
  22. ramplint-0.1.0/src/ramplint/linter.py +115 -0
  23. ramplint-0.1.0/src/ramplint/py.typed +0 -0
  24. ramplint-0.1.0/src/ramplint/reporters.py +74 -0
  25. ramplint-0.1.0/src/ramplint/rules/__init__.py +38 -0
  26. ramplint-0.1.0/src/ramplint/rules/base.py +33 -0
  27. ramplint-0.1.0/src/ramplint/rules/controls.py +59 -0
  28. ramplint-0.1.0/src/ramplint/rules/document.py +25 -0
  29. ramplint-0.1.0/src/ramplint/rules/forms.py +56 -0
  30. ramplint-0.1.0/src/ramplint/rules/headings.py +45 -0
  31. ramplint-0.1.0/src/ramplint/rules/images.py +38 -0
  32. ramplint-0.1.0/src/ramplint/rules/names.py +50 -0
  33. ramplint-0.1.0/src/ramplint/rules/tables.py +58 -0
  34. ramplint-0.1.0/src/ramplint/template.py +149 -0
  35. ramplint-0.1.0/tests/conftest.py +22 -0
  36. ramplint-0.1.0/tests/test_cli.py +129 -0
  37. ramplint-0.1.0/tests/test_rules.py +282 -0
  38. ramplint-0.1.0/tests/test_template.py +87 -0
@@ -0,0 +1,25 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .eggs/
8
+
9
+ # Virtual environments
10
+ .venv/
11
+ venv/
12
+ env/
13
+
14
+ # Tooling caches
15
+ .pytest_cache/
16
+ .ruff_cache/
17
+ .mypy_cache/
18
+ .coverage
19
+ coverage.xml
20
+ htmlcov/
21
+
22
+ # IDEs / OS
23
+ .idea/
24
+ .vscode/
25
+ .DS_Store
@@ -0,0 +1,25 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
5
+ and the project uses [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-10-20
10
+
11
+ ### Added
12
+
13
+ - Template-aware parsing for Django and Jinja2 (`{{ }}`, `{% %}`, `{# #}`,
14
+ `{% comment %}`) with exact line/column positions.
15
+ - Rules: `RL101` img-alt, `RL201` table-header, `RL301` heading-order,
16
+ `RL302` empty-heading, `RL401` form-label, `RL501` button-name,
17
+ `RL502` link-name, `RL601` html-lang.
18
+ - Inline suppressions: `{# ramplint: ignore RL101 #}` and
19
+ `{# ramplint: ignore-file #}`.
20
+ - `text`, `json` and `github` output formats.
21
+ - Configuration via `[tool.ramplint]` in `pyproject.toml`.
22
+ - pre-commit hook.
23
+
24
+ [Unreleased]: https://github.com/iLLcruS/ramplint/compare/v0.1.0...HEAD
25
+ [0.1.0]: https://github.com/iLLcruS/ramplint/releases/tag/v0.1.0
ramplint-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vladyslav Rostovskyi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,317 @@
1
+ Metadata-Version: 2.5
2
+ Name: ramplint
3
+ Version: 0.1.0
4
+ Summary: Accessibility (WCAG) linter for Django and Jinja2 templates
5
+ Project-URL: Homepage, https://github.com/iLLcruS/ramplint
6
+ Project-URL: Issues, https://github.com/iLLcruS/ramplint/issues
7
+ Project-URL: Changelog, https://github.com/iLLcruS/ramplint/blob/main/CHANGELOG.md
8
+ Project-URL: Funding, https://ko-fi.com/innerexcept
9
+ Author-email: Vladyslav Rostovskyi <rostovskii.1020@gmail.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: a11y,accessibility,django,jinja2,linter,templates,wcag
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Environment :: Console
15
+ Classifier: Framework :: Django
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: Software Development :: Quality Assurance
25
+ Classifier: Topic :: Text Processing :: Markup :: HTML
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: >=3.10
28
+ Requires-Dist: tomli>=1.1; python_version < '3.11'
29
+ Provides-Extra: dev
30
+ Requires-Dist: pytest-cov>=4; extra == 'dev'
31
+ Requires-Dist: pytest>=7; extra == 'dev'
32
+ Requires-Dist: ruff>=0.6; extra == 'dev'
33
+ Description-Content-Type: text/markdown
34
+
35
+ <h1 align="center">ramplint</h1>
36
+
37
+ <p align="center">
38
+ <strong>Accessibility linter for Django and Jinja2 templates.</strong><br>
39
+ Catch WCAG problems in your <code>.html</code> templates before they reach production.
40
+ </p>
41
+
42
+ <p align="center">
43
+ <a href="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml/badge.svg"></a>
44
+ <a href="https://pypi.org/project/ramplint/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ramplint.svg"></a>
45
+ <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
46
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
47
+ <a href="https://ko-fi.com/innerexcept"><img alt="Support on Ko-fi" src="https://img.shields.io/badge/Ko--fi-support-72a4f2?logo=ko-fi&logoColor=white"></a>
48
+ </p>
49
+
50
+ ---
51
+
52
+ Generic HTML linters choke on `{% if %}`, `{{ variables }}` and `{% include %}`,
53
+ and browser-based checkers only see the pages you remember to open.
54
+ **ramplint** reads your templates directly, understands the template syntax,
55
+ and reports problems with the exact line and column in the template source:
56
+
57
+ <p align="center">
58
+ <img src="docs/demo.svg" alt="Terminal output of ramplint reporting six accessibility problems in a Django product page template">
59
+ </p>
60
+
61
+ ## Try it in 30 seconds
62
+
63
+ The repository ships with a small demo shop in [`examples/`](examples/): a
64
+ deliberately inaccessible set of Django templates that triggers every rule,
65
+ plus a file full of tricky-but-valid template patterns that must stay silent.
66
+
67
+ ```bash
68
+ git clone https://github.com/iLLcruS/ramplint.git
69
+ cd ramplint
70
+ pip install .
71
+ ramplint examples/
72
+ ```
73
+
74
+ ```console
75
+ examples/templates/base.html:3:1: RL601 <html> is missing a lang attribute; add e.g. lang="en" or lang="{{ LANGUAGE_CODE }}" [html-lang]
76
+ examples/templates/base.html:11:5: RL502 <a> link has no accessible name; add text, an aria-label, or alt text on the image inside it [link-name]
77
+ examples/templates/base.html:11:45: RL101 <img> is missing an alt attribute (use alt="" for decorative images) [img-alt]
78
+ examples/templates/accounts/login.html:9:3: RL401 <input type="text"> has no associated label; add an id and a matching <label for>, or wrap it in a <label> (a placeholder is not a label) [form-label]
79
+ ...
80
+ examples/templates/products/detail.html:28:3: RL101 <input type="image"> needs a non-empty alt attribute describing the action [img-alt]
81
+
82
+ Found 26 problems in 6 of 8 files.
83
+ ```
84
+
85
+ See [`examples/README.md`](examples/README.md) for what each demo template contains.
86
+
87
+ ## Highlights
88
+
89
+ - **Template-aware.** Django and Jinja2 tags, variables and comments are understood, not stripped blindly.
90
+ - **Low noise.** If something is only known at render time (`{% include %}`, `{{ widget.attrs }}`, `{% block %}`), ramplint assumes the best and stays quiet.
91
+ - **Zero dependencies.** Pure Python standard library (plus `tomli` on Python < 3.11).
92
+ - **Made for CI.** Exit codes, JSON output, GitHub Actions annotations and a pre-commit hook.
93
+ - **Fast.** No browser and no rendering. A whole project is checked in well under a second.
94
+
95
+ ## Installation
96
+
97
+ ```bash
98
+ pip install ramplint
99
+ ```
100
+
101
+ ## Usage
102
+
103
+ ```bash
104
+ ramplint # lint every template under the current directory
105
+ ramplint templates/ shop/templates/base.html
106
+ ramplint --select RL1,RL5 # only image and control rules
107
+ ramplint --ignore heading-order # rules can be referenced by code or name
108
+ ramplint --format json # machine-readable output
109
+ ramplint --list-rules
110
+ ```
111
+
112
+ By default ramplint looks at `.html`, `.htm`, `.jinja`, `.jinja2`, `.j2` and
113
+ `.djhtml` files and skips folders such as `node_modules`, `.venv`, `build` and `dist`.
114
+ Files passed explicitly are always checked, whatever their extension.
115
+
116
+ | Exit code | Meaning |
117
+ |-----------|------------------------------|
118
+ | `0` | No problems found |
119
+ | `1` | Problems found |
120
+ | `2` | Usage or configuration error |
121
+
122
+ ## Rules
123
+
124
+ | Code | Name | What it checks | WCAG |
125
+ |---------|-----------------|------------------------------------------------------------------------------------------|------------------|
126
+ | `RL101` | `img-alt` | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A) |
127
+ | `RL201` | `table-header` | Data tables use real `<th>` header cells | 1.3.1 (A) |
128
+ | `RL301` | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`) | 1.3.1 (A) |
129
+ | `RL302` | `empty-heading` | Headings are not empty | 2.4.6 (AA) |
130
+ | `RL401` | `form-label` | `<input>`, `<select>` and `<textarea>` have an associated `<label>` | 1.3.1, 4.1.2 (A) |
131
+ | `RL501` | `button-name` | Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
132
+ | `RL502` | `link-name` | Links have an accessible name | 2.4.4, 4.1.2 (A) |
133
+ | `RL601` | `html-lang` | `<html>` declares the page language | 3.1.1 (A) |
134
+
135
+ <details>
136
+ <summary><strong>Examples for every rule</strong></summary>
137
+
138
+ #### RL101 `img-alt`
139
+
140
+ ```django
141
+ {# ✗ #} <img src="{% static 'logo.png' %}">
142
+ {# ✓ #} <img src="{% static 'logo.png' %}" alt="ACME">
143
+ {# ✓ #} <img src="{% static 'divider.png' %}" alt=""> {# decorative #}
144
+ {# ✓ #} <img src="{{ product.image.url }}" alt="{{ product.name }}">
145
+ ```
146
+
147
+ #### RL201 `table-header`
148
+
149
+ ```django
150
+ {# ✗ #} <table><tr><td>Name</td><td>Price</td></tr>…</table>
151
+ {# ✓ #} <table><tr><th scope="col">Name</th><th scope="col">Price</th></tr>…</table>
152
+ {# ✓ #} <table role="presentation">…</table> {# layout table #}
153
+ ```
154
+
155
+ `role="columnheader"` on a `<td>` is not accepted. Use a real `<th>`.
156
+ Tables whose rows come from `{% include %}`, `{% block %}` or `{{ form.as_table }}`
157
+ are skipped because their content is not visible in the template.
158
+
159
+ #### RL301 `heading-order`
160
+
161
+ ```django
162
+ {# ✗ #} <h2>Orders</h2> <h4>Recent</h4>
163
+ {# ✓ #} <h2>Orders</h2> <h3>Recent</h3>
164
+ ```
165
+
166
+ The first heading in a file sets the baseline. A child template that starts at
167
+ `<h2>` (because `base.html` owns the `<h1>`) is fine.
168
+
169
+ #### RL302 `empty-heading`
170
+
171
+ ```django
172
+ {# ✗ #} <h2><i class="icon-star"></i></h2>
173
+ {# ✓ #} <h2>{% trans "Favourites" %}</h2>
174
+ ```
175
+
176
+ #### RL401 `form-label`
177
+
178
+ ```django
179
+ {# ✗ #} <input type="email" name="email" placeholder="Email">
180
+ {# ✓ #} <label for="email">Email</label> <input type="email" id="email" name="email">
181
+ {# ✓ #} <label>Email <input type="email" name="email"></label>
182
+ {# ✓ #} <input type="search" name="q" aria-label="Search">
183
+ ```
184
+
185
+ Hidden, submit, reset, button and image inputs are not checked. Neither are
186
+ widgets whose attributes are rendered dynamically (`<input {{ widget.attrs }}>`).
187
+
188
+ #### RL501 `button-name`
189
+
190
+ ```django
191
+ {# ✗ #} <button><i class="fa fa-trash"></i></button>
192
+ {# ✓ #} <button aria-label="{% trans 'Delete' %}"><i class="fa fa-trash" aria-hidden="true"></i></button>
193
+ {# ✓ #} <button><span class="visually-hidden">Delete</span><i class="fa fa-trash"></i></button>
194
+ ```
195
+
196
+ #### RL502 `link-name`
197
+
198
+ ```django
199
+ {# ✗ #} <a href="{% url 'cart' %}"><svg>…</svg></a>
200
+ {# ✓ #} <a href="{% url 'cart' %}"><svg><title>Cart</title>…</svg></a>
201
+ {# ✓ #} <a href="/"><img src="logo.png" alt="ACME home"></a>
202
+ ```
203
+
204
+ #### RL601 `html-lang`
205
+
206
+ ```django
207
+ {# ✗ #} <html>
208
+ {# ✓ #} <html lang="{{ LANGUAGE_CODE }}">
209
+ ```
210
+
211
+ </details>
212
+
213
+ ## How templates are handled
214
+
215
+ Before parsing, every template token is replaced by a placeholder of the same
216
+ length, so positions in the report always match your source:
217
+
218
+ | Template code | Treated as |
219
+ |--------------------------------------------------------------|---------------------------------|
220
+ | `{{ variable }}`, `{% trans %}`, `{% url %}`, `{% static %}` | Text that exists at runtime |
221
+ | `{% include %}`, `{% block %}`, custom tags | Unknown markup (rules back off) |
222
+ | `{% if %}`, `{% for %}`, `{% with %}`, ... | Nothing (control flow) |
223
+ | `{# ... #}`, `{% comment %}...{% endcomment %}` | Nothing |
224
+
225
+ Both branches of an `{% if %}` are checked, so a problem in either one is reported.
226
+
227
+ ## Suppressing problems
228
+
229
+ ```django
230
+ <img src="spacer.gif"> {# ramplint: ignore RL101 #}
231
+
232
+ {# ramplint: ignore img-alt, link-name #}
233
+ <a href="/"><img src="logo.png"></a>
234
+
235
+ {# ramplint: ignore-file #}
236
+ ```
237
+
238
+ `ignore` applies to its own line and the next one. With no codes it silences
239
+ every rule. HTML comments work too: `<!-- ramplint: ignore RL201 -->`.
240
+
241
+ ## Configuration
242
+
243
+ Add a `[tool.ramplint]` section to `pyproject.toml`. Command-line options take
244
+ precedence over it.
245
+
246
+ ```toml
247
+ [tool.ramplint]
248
+ select = ["RL"] # default: all rules
249
+ ignore = ["RL301"]
250
+ exclude = ["*/admin/*", "templates/vendor/*"]
251
+ extensions = [".html", ".txt"]
252
+ ```
253
+
254
+ ## pre-commit
255
+
256
+ ```yaml
257
+ # .pre-commit-config.yaml
258
+ repos:
259
+ - repo: https://github.com/iLLcruS/ramplint
260
+ rev: v0.1.0
261
+ hooks:
262
+ - id: ramplint
263
+ ```
264
+
265
+ ## GitHub Actions
266
+
267
+ When `GITHUB_ACTIONS=true`, ramplint switches to the `github` format and
268
+ problems appear as annotations right in the pull request diff.
269
+
270
+ ```yaml
271
+ - run: pip install ramplint
272
+ - run: ramplint templates/
273
+ ```
274
+
275
+ ## Python API
276
+
277
+ ```python
278
+ from ramplint import lint_source, select_rules
279
+
280
+ for problem in lint_source('<img src="a.png">', rules=select_rules(["RL1"])):
281
+ print(problem.line, problem.col, problem.code, problem.message)
282
+ ```
283
+
284
+ ## Limitations
285
+
286
+ ramplint is a static checker. It catches structural problems early and cheaply,
287
+ but it cannot judge colour contrast or focus order, or tell whether an `alt`
288
+ text is actually meaningful. Use it together with manual testing and a runtime
289
+ tool such as axe.
290
+
291
+ ## Roadmap
292
+
293
+ - [ ] More rules: `<iframe title>`, duplicate `id`s, `autocomplete` on personal-data inputs
294
+ - [ ] `aria-*` attribute and role validation
295
+ - [ ] `--fix` for safe autofixes (e.g. `scope="col"` on header rows)
296
+ - [ ] SARIF output for GitHub code scanning
297
+ - [ ] Follow `{% extends %}` / `{% include %}` to check heading order across templates
298
+
299
+ ## Contributing
300
+
301
+ Bug reports, especially about false positives, are very welcome.
302
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
303
+
304
+ ## Feedback and support
305
+
306
+ Questions, ideas, or using ramplint in your project? Open an
307
+ [issue](https://github.com/iLLcruS/ramplint/issues) or email me at
308
+ [rostovskii.1020@gmail.com](mailto:rostovskii.1020@gmail.com).
309
+
310
+ ramplint is free and built in my spare time. If it saved you time, you can
311
+ buy me a coffee:
312
+
313
+ <a href="https://ko-fi.com/innerexcept"><img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Support me on Ko-fi" height="36"></a>
314
+
315
+ ## License
316
+
317
+ [MIT](LICENSE) © Vladyslav Rostovskyi
@@ -0,0 +1,283 @@
1
+ <h1 align="center">ramplint</h1>
2
+
3
+ <p align="center">
4
+ <strong>Accessibility linter for Django and Jinja2 templates.</strong><br>
5
+ Catch WCAG problems in your <code>.html</code> templates before they reach production.
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml/badge.svg"></a>
10
+ <a href="https://pypi.org/project/ramplint/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ramplint.svg"></a>
11
+ <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
12
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
13
+ <a href="https://ko-fi.com/innerexcept"><img alt="Support on Ko-fi" src="https://img.shields.io/badge/Ko--fi-support-72a4f2?logo=ko-fi&logoColor=white"></a>
14
+ </p>
15
+
16
+ ---
17
+
18
+ Generic HTML linters choke on `{% if %}`, `{{ variables }}` and `{% include %}`,
19
+ and browser-based checkers only see the pages you remember to open.
20
+ **ramplint** reads your templates directly, understands the template syntax,
21
+ and reports problems with the exact line and column in the template source:
22
+
23
+ <p align="center">
24
+ <img src="docs/demo.svg" alt="Terminal output of ramplint reporting six accessibility problems in a Django product page template">
25
+ </p>
26
+
27
+ ## Try it in 30 seconds
28
+
29
+ The repository ships with a small demo shop in [`examples/`](examples/): a
30
+ deliberately inaccessible set of Django templates that triggers every rule,
31
+ plus a file full of tricky-but-valid template patterns that must stay silent.
32
+
33
+ ```bash
34
+ git clone https://github.com/iLLcruS/ramplint.git
35
+ cd ramplint
36
+ pip install .
37
+ ramplint examples/
38
+ ```
39
+
40
+ ```console
41
+ examples/templates/base.html:3:1: RL601 <html> is missing a lang attribute; add e.g. lang="en" or lang="{{ LANGUAGE_CODE }}" [html-lang]
42
+ examples/templates/base.html:11:5: RL502 <a> link has no accessible name; add text, an aria-label, or alt text on the image inside it [link-name]
43
+ examples/templates/base.html:11:45: RL101 <img> is missing an alt attribute (use alt="" for decorative images) [img-alt]
44
+ examples/templates/accounts/login.html:9:3: RL401 <input type="text"> has no associated label; add an id and a matching <label for>, or wrap it in a <label> (a placeholder is not a label) [form-label]
45
+ ...
46
+ examples/templates/products/detail.html:28:3: RL101 <input type="image"> needs a non-empty alt attribute describing the action [img-alt]
47
+
48
+ Found 26 problems in 6 of 8 files.
49
+ ```
50
+
51
+ See [`examples/README.md`](examples/README.md) for what each demo template contains.
52
+
53
+ ## Highlights
54
+
55
+ - **Template-aware.** Django and Jinja2 tags, variables and comments are understood, not stripped blindly.
56
+ - **Low noise.** If something is only known at render time (`{% include %}`, `{{ widget.attrs }}`, `{% block %}`), ramplint assumes the best and stays quiet.
57
+ - **Zero dependencies.** Pure Python standard library (plus `tomli` on Python < 3.11).
58
+ - **Made for CI.** Exit codes, JSON output, GitHub Actions annotations and a pre-commit hook.
59
+ - **Fast.** No browser and no rendering. A whole project is checked in well under a second.
60
+
61
+ ## Installation
62
+
63
+ ```bash
64
+ pip install ramplint
65
+ ```
66
+
67
+ ## Usage
68
+
69
+ ```bash
70
+ ramplint # lint every template under the current directory
71
+ ramplint templates/ shop/templates/base.html
72
+ ramplint --select RL1,RL5 # only image and control rules
73
+ ramplint --ignore heading-order # rules can be referenced by code or name
74
+ ramplint --format json # machine-readable output
75
+ ramplint --list-rules
76
+ ```
77
+
78
+ By default ramplint looks at `.html`, `.htm`, `.jinja`, `.jinja2`, `.j2` and
79
+ `.djhtml` files and skips folders such as `node_modules`, `.venv`, `build` and `dist`.
80
+ Files passed explicitly are always checked, whatever their extension.
81
+
82
+ | Exit code | Meaning |
83
+ |-----------|------------------------------|
84
+ | `0` | No problems found |
85
+ | `1` | Problems found |
86
+ | `2` | Usage or configuration error |
87
+
88
+ ## Rules
89
+
90
+ | Code | Name | What it checks | WCAG |
91
+ |---------|-----------------|------------------------------------------------------------------------------------------|------------------|
92
+ | `RL101` | `img-alt` | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A) |
93
+ | `RL201` | `table-header` | Data tables use real `<th>` header cells | 1.3.1 (A) |
94
+ | `RL301` | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`) | 1.3.1 (A) |
95
+ | `RL302` | `empty-heading` | Headings are not empty | 2.4.6 (AA) |
96
+ | `RL401` | `form-label` | `<input>`, `<select>` and `<textarea>` have an associated `<label>` | 1.3.1, 4.1.2 (A) |
97
+ | `RL501` | `button-name` | Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
98
+ | `RL502` | `link-name` | Links have an accessible name | 2.4.4, 4.1.2 (A) |
99
+ | `RL601` | `html-lang` | `<html>` declares the page language | 3.1.1 (A) |
100
+
101
+ <details>
102
+ <summary><strong>Examples for every rule</strong></summary>
103
+
104
+ #### RL101 `img-alt`
105
+
106
+ ```django
107
+ {# ✗ #} <img src="{% static 'logo.png' %}">
108
+ {# ✓ #} <img src="{% static 'logo.png' %}" alt="ACME">
109
+ {# ✓ #} <img src="{% static 'divider.png' %}" alt=""> {# decorative #}
110
+ {# ✓ #} <img src="{{ product.image.url }}" alt="{{ product.name }}">
111
+ ```
112
+
113
+ #### RL201 `table-header`
114
+
115
+ ```django
116
+ {# ✗ #} <table><tr><td>Name</td><td>Price</td></tr>…</table>
117
+ {# ✓ #} <table><tr><th scope="col">Name</th><th scope="col">Price</th></tr>…</table>
118
+ {# ✓ #} <table role="presentation">…</table> {# layout table #}
119
+ ```
120
+
121
+ `role="columnheader"` on a `<td>` is not accepted. Use a real `<th>`.
122
+ Tables whose rows come from `{% include %}`, `{% block %}` or `{{ form.as_table }}`
123
+ are skipped because their content is not visible in the template.
124
+
125
+ #### RL301 `heading-order`
126
+
127
+ ```django
128
+ {# ✗ #} <h2>Orders</h2> <h4>Recent</h4>
129
+ {# ✓ #} <h2>Orders</h2> <h3>Recent</h3>
130
+ ```
131
+
132
+ The first heading in a file sets the baseline. A child template that starts at
133
+ `<h2>` (because `base.html` owns the `<h1>`) is fine.
134
+
135
+ #### RL302 `empty-heading`
136
+
137
+ ```django
138
+ {# ✗ #} <h2><i class="icon-star"></i></h2>
139
+ {# ✓ #} <h2>{% trans "Favourites" %}</h2>
140
+ ```
141
+
142
+ #### RL401 `form-label`
143
+
144
+ ```django
145
+ {# ✗ #} <input type="email" name="email" placeholder="Email">
146
+ {# ✓ #} <label for="email">Email</label> <input type="email" id="email" name="email">
147
+ {# ✓ #} <label>Email <input type="email" name="email"></label>
148
+ {# ✓ #} <input type="search" name="q" aria-label="Search">
149
+ ```
150
+
151
+ Hidden, submit, reset, button and image inputs are not checked. Neither are
152
+ widgets whose attributes are rendered dynamically (`<input {{ widget.attrs }}>`).
153
+
154
+ #### RL501 `button-name`
155
+
156
+ ```django
157
+ {# ✗ #} <button><i class="fa fa-trash"></i></button>
158
+ {# ✓ #} <button aria-label="{% trans 'Delete' %}"><i class="fa fa-trash" aria-hidden="true"></i></button>
159
+ {# ✓ #} <button><span class="visually-hidden">Delete</span><i class="fa fa-trash"></i></button>
160
+ ```
161
+
162
+ #### RL502 `link-name`
163
+
164
+ ```django
165
+ {# ✗ #} <a href="{% url 'cart' %}"><svg>…</svg></a>
166
+ {# ✓ #} <a href="{% url 'cart' %}"><svg><title>Cart</title>…</svg></a>
167
+ {# ✓ #} <a href="/"><img src="logo.png" alt="ACME home"></a>
168
+ ```
169
+
170
+ #### RL601 `html-lang`
171
+
172
+ ```django
173
+ {# ✗ #} <html>
174
+ {# ✓ #} <html lang="{{ LANGUAGE_CODE }}">
175
+ ```
176
+
177
+ </details>
178
+
179
+ ## How templates are handled
180
+
181
+ Before parsing, every template token is replaced by a placeholder of the same
182
+ length, so positions in the report always match your source:
183
+
184
+ | Template code | Treated as |
185
+ |--------------------------------------------------------------|---------------------------------|
186
+ | `{{ variable }}`, `{% trans %}`, `{% url %}`, `{% static %}` | Text that exists at runtime |
187
+ | `{% include %}`, `{% block %}`, custom tags | Unknown markup (rules back off) |
188
+ | `{% if %}`, `{% for %}`, `{% with %}`, ... | Nothing (control flow) |
189
+ | `{# ... #}`, `{% comment %}...{% endcomment %}` | Nothing |
190
+
191
+ Both branches of an `{% if %}` are checked, so a problem in either one is reported.
192
+
193
+ ## Suppressing problems
194
+
195
+ ```django
196
+ <img src="spacer.gif"> {# ramplint: ignore RL101 #}
197
+
198
+ {# ramplint: ignore img-alt, link-name #}
199
+ <a href="/"><img src="logo.png"></a>
200
+
201
+ {# ramplint: ignore-file #}
202
+ ```
203
+
204
+ `ignore` applies to its own line and the next one. With no codes it silences
205
+ every rule. HTML comments work too: `<!-- ramplint: ignore RL201 -->`.
206
+
207
+ ## Configuration
208
+
209
+ Add a `[tool.ramplint]` section to `pyproject.toml`. Command-line options take
210
+ precedence over it.
211
+
212
+ ```toml
213
+ [tool.ramplint]
214
+ select = ["RL"] # default: all rules
215
+ ignore = ["RL301"]
216
+ exclude = ["*/admin/*", "templates/vendor/*"]
217
+ extensions = [".html", ".txt"]
218
+ ```
219
+
220
+ ## pre-commit
221
+
222
+ ```yaml
223
+ # .pre-commit-config.yaml
224
+ repos:
225
+ - repo: https://github.com/iLLcruS/ramplint
226
+ rev: v0.1.0
227
+ hooks:
228
+ - id: ramplint
229
+ ```
230
+
231
+ ## GitHub Actions
232
+
233
+ When `GITHUB_ACTIONS=true`, ramplint switches to the `github` format and
234
+ problems appear as annotations right in the pull request diff.
235
+
236
+ ```yaml
237
+ - run: pip install ramplint
238
+ - run: ramplint templates/
239
+ ```
240
+
241
+ ## Python API
242
+
243
+ ```python
244
+ from ramplint import lint_source, select_rules
245
+
246
+ for problem in lint_source('<img src="a.png">', rules=select_rules(["RL1"])):
247
+ print(problem.line, problem.col, problem.code, problem.message)
248
+ ```
249
+
250
+ ## Limitations
251
+
252
+ ramplint is a static checker. It catches structural problems early and cheaply,
253
+ but it cannot judge colour contrast or focus order, or tell whether an `alt`
254
+ text is actually meaningful. Use it together with manual testing and a runtime
255
+ tool such as axe.
256
+
257
+ ## Roadmap
258
+
259
+ - [ ] More rules: `<iframe title>`, duplicate `id`s, `autocomplete` on personal-data inputs
260
+ - [ ] `aria-*` attribute and role validation
261
+ - [ ] `--fix` for safe autofixes (e.g. `scope="col"` on header rows)
262
+ - [ ] SARIF output for GitHub code scanning
263
+ - [ ] Follow `{% extends %}` / `{% include %}` to check heading order across templates
264
+
265
+ ## Contributing
266
+
267
+ Bug reports, especially about false positives, are very welcome.
268
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
269
+
270
+ ## Feedback and support
271
+
272
+ Questions, ideas, or using ramplint in your project? Open an
273
+ [issue](https://github.com/iLLcruS/ramplint/issues) or email me at
274
+ [rostovskii.1020@gmail.com](mailto:rostovskii.1020@gmail.com).
275
+
276
+ ramplint is free and built in my spare time. If it saved you time, you can
277
+ buy me a coffee:
278
+
279
+ <a href="https://ko-fi.com/innerexcept"><img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Support me on Ko-fi" height="36"></a>
280
+
281
+ ## License
282
+
283
+ [MIT](LICENSE) © Vladyslav Rostovskyi