ramplint 0.2.0__tar.gz → 0.3.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 (68) hide show
  1. {ramplint-0.2.0 → ramplint-0.3.0}/CHANGELOG.md +38 -1
  2. {ramplint-0.2.0 → ramplint-0.3.0}/PKG-INFO +115 -22
  3. {ramplint-0.2.0 → ramplint-0.3.0}/README.md +113 -21
  4. ramplint-0.3.0/docs/html-report-details.png +0 -0
  5. ramplint-0.3.0/docs/html-report.png +0 -0
  6. ramplint-0.3.0/docs/rules/README.md +18 -0
  7. ramplint-0.3.0/docs/rules/RL101.md +58 -0
  8. ramplint-0.3.0/docs/rules/RL102.md +53 -0
  9. ramplint-0.3.0/docs/rules/RL201.md +54 -0
  10. ramplint-0.3.0/docs/rules/RL301.md +57 -0
  11. ramplint-0.3.0/docs/rules/RL302.md +55 -0
  12. ramplint-0.3.0/docs/rules/RL303.md +57 -0
  13. ramplint-0.3.0/docs/rules/RL401.md +58 -0
  14. ramplint-0.3.0/docs/rules/RL402.md +56 -0
  15. ramplint-0.3.0/docs/rules/RL501.md +56 -0
  16. ramplint-0.3.0/docs/rules/RL502.md +56 -0
  17. ramplint-0.3.0/docs/rules/RL503.md +54 -0
  18. ramplint-0.3.0/docs/rules/RL504.md +58 -0
  19. ramplint-0.3.0/docs/rules/RL601.md +53 -0
  20. ramplint-0.3.0/docs/rules/RL602.md +54 -0
  21. {ramplint-0.2.0 → ramplint-0.3.0}/pyproject.toml +5 -1
  22. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/__init__.py +1 -1
  23. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/cli.py +100 -12
  24. ramplint-0.3.0/src/ramplint/html_report.py +226 -0
  25. ramplint-0.3.0/src/ramplint/report.css +170 -0
  26. ramplint-0.3.0/src/ramplint/report.js +41 -0
  27. ramplint-0.3.0/src/ramplint/reporters.py +180 -0
  28. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/__init__.py +37 -1
  29. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/base.py +7 -0
  30. ramplint-0.3.0/src/ramplint/sarif.py +109 -0
  31. ramplint-0.3.0/tests/data/sarif-schema-2.1.0.json +3389 -0
  32. ramplint-0.3.0/tests/test_cli.py +295 -0
  33. {ramplint-0.2.0 → ramplint-0.3.0}/tests/test_docs.py +19 -0
  34. ramplint-0.3.0/tests/test_html_report.py +133 -0
  35. ramplint-0.3.0/tests/test_rule_docs.py +88 -0
  36. ramplint-0.3.0/tests/test_sarif.py +74 -0
  37. ramplint-0.2.0/src/ramplint/reporters.py +0 -74
  38. ramplint-0.2.0/tests/test_cli.py +0 -129
  39. {ramplint-0.2.0 → ramplint-0.3.0}/.gitignore +0 -0
  40. {ramplint-0.2.0 → ramplint-0.3.0}/LICENSE +0 -0
  41. {ramplint-0.2.0 → ramplint-0.3.0}/docs/demo.svg +0 -0
  42. {ramplint-0.2.0 → ramplint-0.3.0}/examples/README.md +0 -0
  43. {ramplint-0.2.0 → ramplint-0.3.0}/examples/templates/accounts/login.html +0 -0
  44. {ramplint-0.2.0 → ramplint-0.3.0}/examples/templates/base.html +0 -0
  45. {ramplint-0.2.0 → ramplint-0.3.0}/examples/templates/clean/tricky_but_valid.html +0 -0
  46. {ramplint-0.2.0 → ramplint-0.3.0}/examples/templates/orders/list.html +0 -0
  47. {ramplint-0.2.0 → ramplint-0.3.0}/examples/templates/orders/list_fixed.html +0 -0
  48. {ramplint-0.2.0 → ramplint-0.3.0}/examples/templates/partials/footer.html +0 -0
  49. {ramplint-0.2.0 → ramplint-0.3.0}/examples/templates/partials/navbar.html +0 -0
  50. {ramplint-0.2.0 → ramplint-0.3.0}/examples/templates/products/detail.html +0 -0
  51. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/__main__.py +0 -0
  52. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/config.py +0 -0
  53. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/dom.py +0 -0
  54. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/linter.py +0 -0
  55. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/py.typed +0 -0
  56. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/controls.py +0 -0
  57. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/document.py +0 -0
  58. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/embeds.py +0 -0
  59. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/forms.py +0 -0
  60. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/headings.py +0 -0
  61. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/ids.py +0 -0
  62. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/images.py +0 -0
  63. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/names.py +0 -0
  64. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/rules/tables.py +0 -0
  65. {ramplint-0.2.0 → ramplint-0.3.0}/src/ramplint/template.py +0 -0
  66. {ramplint-0.2.0 → ramplint-0.3.0}/tests/conftest.py +0 -0
  67. {ramplint-0.2.0 → ramplint-0.3.0}/tests/test_rules.py +0 -0
  68. {ramplint-0.2.0 → ramplint-0.3.0}/tests/test_template.py +0 -0
@@ -6,6 +6,41 @@ and the project uses [Semantic Versioning](https://semver.org/).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.3.0] - 2026-10-21
10
+
11
+ ### Added
12
+
13
+ - `-o` / `--output FILE` writes the report to a file and prints a one-line
14
+ summary (#8).
15
+ - `--format html`: a self-contained HTML report with a summary, problems by
16
+ rule and problems grouped by template; light and dark themes (#9).
17
+ - HTML report shows the template lines around each problem, links rules to
18
+ their documentation and can be filtered by rule and template (#10).
19
+ - `--format sarif`: SARIF 2.1.0 output for GitHub Code Scanning, with a
20
+ ready-to-copy workflow in the README (#11).
21
+ - `--statistics` shows the number of problems per rule, most frequent first,
22
+ as text or JSON (#12).
23
+ - A documentation page for every rule in `docs/rules/`, with examples, WCAG
24
+ references and suppression options; `ramplint --explain RL101` shows it in
25
+ the terminal (#13).
26
+
27
+ ### Changed
28
+
29
+ - Output formats live in a small registry, so a new format is a single
30
+ decorated function (#8).
31
+
32
+ ### Fixed
33
+
34
+ - `--list-rules` columns stay aligned for long rule names.
35
+
36
+ ## [0.2.1] - 2026-10-21
37
+
38
+ ### Fixed
39
+
40
+ - Images and links in the project description on PyPI (the README used
41
+ relative paths that only work on GitHub).
42
+ - `ramplint ... | head` no longer prints a `BrokenPipeError` traceback.
43
+
9
44
  ## [0.2.0] - 2026-10-21
10
45
 
11
46
  ### Added
@@ -44,6 +79,8 @@ and the project uses [Semantic Versioning](https://semver.org/).
44
79
  - Configuration via `[tool.ramplint]` in `pyproject.toml`.
45
80
  - pre-commit hook.
46
81
 
47
- [Unreleased]: https://github.com/iLLcruS/ramplint/compare/0.2.0...HEAD
82
+ [Unreleased]: https://github.com/iLLcruS/ramplint/compare/0.3.0...HEAD
83
+ [0.3.0]: https://github.com/iLLcruS/ramplint/compare/0.2.1...0.3.0
84
+ [0.2.1]: https://github.com/iLLcruS/ramplint/compare/0.2.0...0.2.1
48
85
  [0.2.0]: https://github.com/iLLcruS/ramplint/compare/0.1.0...0.2.0
49
86
  [0.1.0]: https://github.com/iLLcruS/ramplint/releases/tag/0.1.0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: ramplint
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Accessibility (WCAG) linter for Django and Jinja2 templates
5
5
  Project-URL: Homepage, https://github.com/iLLcruS/ramplint
6
6
  Project-URL: Issues, https://github.com/iLLcruS/ramplint/issues
@@ -27,6 +27,7 @@ Classifier: Typing :: Typed
27
27
  Requires-Python: >=3.10
28
28
  Requires-Dist: tomli>=1.1; python_version < '3.11'
29
29
  Provides-Extra: dev
30
+ Requires-Dist: jsonschema>=4; extra == 'dev'
30
31
  Requires-Dist: pytest-cov>=4; extra == 'dev'
31
32
  Requires-Dist: pytest>=7; extra == 'dev'
32
33
  Requires-Dist: ruff>=0.6; extra == 'dev'
@@ -43,7 +44,7 @@ Description-Content-Type: text/markdown
43
44
  <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
45
  <a href="https://pypi.org/project/ramplint/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ramplint.svg"></a>
45
46
  <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://github.com/iLLcruS/ramplint/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
47
48
  <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
49
  </p>
49
50
 
@@ -55,12 +56,12 @@ and browser-based checkers only see the pages you remember to open.
55
56
  and reports problems with the exact line and column in the template source:
56
57
 
57
58
  <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
+ <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/demo.svg" alt="Terminal output of ramplint reporting six accessibility problems in a Django product page template">
59
60
  </p>
60
61
 
61
62
  ## Try it in 30 seconds
62
63
 
63
- The repository ships with a small demo shop in [`examples/`](examples/): a
64
+ The repository ships with a small demo shop in [`examples/`](https://github.com/iLLcruS/ramplint/tree/main/examples): a
64
65
  deliberately inaccessible set of Django templates that triggers every rule,
65
66
  plus a file full of tricky-but-valid template patterns that must stay silent.
66
67
 
@@ -83,7 +84,7 @@ examples/templates/products/detail.html:28:3: RL101 <input type="image"> needs a
83
84
  Found 32 problems in 6 of 8 files.
84
85
  ```
85
86
 
86
- See [`examples/README.md`](examples/README.md) for what each demo template contains.
87
+ See [`examples/README.md`](https://github.com/iLLcruS/ramplint/blob/main/examples/README.md) for what each demo template contains.
87
88
 
88
89
  ## Highlights
89
90
 
@@ -107,13 +108,69 @@ ramplint templates/ shop/templates/base.html
107
108
  ramplint --select RL1,RL5 # only image and control rules
108
109
  ramplint --ignore heading-order # rules can be referenced by code or name
109
110
  ramplint --format json # machine-readable output
111
+ ramplint --statistics # problems per rule, most frequent first
112
+ ramplint -o report.json --format json # save the report to a file
113
+ ramplint -o a11y-report.html --format html # shareable HTML report
110
114
  ramplint --list-rules
115
+ ramplint --explain RL303 # what a rule checks and how to fix it
111
116
  ```
112
117
 
113
118
  By default ramplint looks at `.html`, `.htm`, `.jinja`, `.jinja2`, `.j2` and
114
119
  `.djhtml` files and skips folders such as `node_modules`, `.venv`, `build` and `dist`.
115
120
  Files passed explicitly are always checked, whatever their extension.
116
121
 
122
+ ### Output formats
123
+
124
+ | Format | Use it for |
125
+ |----------|------------------------------------------------------------------|
126
+ | `text` | Reading in the terminal (default; colored when it is a terminal) |
127
+ | `json` | Scripts, dashboards and other tools |
128
+ | `github` | Annotations in GitHub pull requests (default inside Actions) |
129
+ | `html` | A single self-contained page to share with your team or a client |
130
+ | `sarif` | GitHub Code Scanning and other security dashboards |
131
+
132
+ `--output FILE` writes the report to a file and prints a one-line summary
133
+ instead. Missing folders are created, and colors are never written to files.
134
+
135
+ The HTML report needs no internet connection, so it can be attached to an email
136
+ or stored as a CI artifact. Every problem comes with the surrounding template
137
+ lines, rule names link to their documentation, and you can filter by rule or
138
+ template. It follows the light or dark theme of the viewer's system, and it
139
+ passes ramplint itself.
140
+
141
+ <p align="center">
142
+ <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/html-report.png" alt="HTML report: a blue header with 32 problems in 6 templates, a table of problems by rule and a list of templates with problems" width="800">
143
+ </p>
144
+
145
+ <p align="center">
146
+ <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/html-report-details.png" alt="HTML report details: filters by rule and template, and each problem with the highlighted line of template source" width="800">
147
+ </p>
148
+
149
+ `--statistics` replaces the list of problems with a count per rule, which helps
150
+ decide what to fix first:
151
+
152
+ ```console
153
+ $ ramplint examples/ --statistics
154
+ 6 RL401 form-label
155
+ 6 RL502 link-name
156
+ 4 RL101 img-alt
157
+ 4 RL501 button-name
158
+ 2 RL201 table-header
159
+ 2 RL301 heading-order
160
+ 1 RL102 iframe-title
161
+ 1 RL302 empty-heading
162
+ 1 RL303 duplicate-id
163
+ 1 RL402 autocomplete-valid
164
+ 1 RL503 no-positive-tabindex
165
+ 1 RL504 anchor-is-valid
166
+ 1 RL601 html-lang
167
+ 1 RL602 viewport-zoom
168
+
169
+ Found 32 problems in 6 of 8 files.
170
+ ```
171
+
172
+ It works with `--format text` (default) and `--format json`.
173
+
117
174
  | Exit code | Meaning |
118
175
  |-----------|------------------------------|
119
176
  | `0` | No problems found |
@@ -124,20 +181,24 @@ Files passed explicitly are always checked, whatever their extension.
124
181
 
125
182
  | Code | Name | What it checks | WCAG |
126
183
  |---------|-----------------|------------------------------------------------------------------------------------------|------------------|
127
- | `RL101` | `img-alt` | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A) |
128
- | `RL102` | `iframe-title` | `<iframe>` has a `title` describing its content | 4.1.2 (A) |
129
- | `RL201` | `table-header` | Data tables use real `<th>` header cells | 1.3.1 (A) |
130
- | `RL301` | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`) | 1.3.1 (A) |
131
- | `RL302` | `empty-heading` | Headings are not empty | 2.4.6 (AA) |
132
- | `RL303` | `duplicate-id` | `id` values are unique (same id in `{% if %}` / `{% else %}` branches is allowed) | 1.3.1 (A) |
133
- | `RL401` | `form-label` | `<input>`, `<select>` and `<textarea>` have an associated `<label>` | 1.3.1, 4.1.2 (A) |
134
- | `RL402` | `autocomplete-valid` | `autocomplete` uses valid autofill tokens (catches typos like `emial`) | 1.3.5 (AA) |
135
- | `RL501` | `button-name` | Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
136
- | `RL502` | `link-name` | Links have an accessible name | 2.4.4, 4.1.2 (A) |
137
- | `RL503` | `no-positive-tabindex` | `tabindex` is not greater than `0` | 2.4.3 (A) |
138
- | `RL504` | `anchor-is-valid` | Links have a real target (no `href="#"`, `javascript:` or click-only `<a>`) | 2.1.1 (A) |
139
- | `RL601` | `html-lang` | `<html>` declares the page language | 3.1.1 (A) |
140
- | `RL602` | `viewport-zoom` | `<meta name="viewport">` does not disable zoom (`user-scalable=no`, `maximum-scale` < 2) | 1.4.4 (AA) |
184
+ | [`RL101`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL101.md) | `img-alt` | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A) |
185
+ | [`RL102`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL102.md) | `iframe-title` | `<iframe>` has a `title` describing its content | 4.1.2 (A) |
186
+ | [`RL201`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL201.md) | `table-header` | Data tables use real `<th>` header cells | 1.3.1 (A) |
187
+ | [`RL301`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL301.md) | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`) | 1.3.1 (A) |
188
+ | [`RL302`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL302.md) | `empty-heading` | Headings are not empty | 2.4.6 (AA) |
189
+ | [`RL303`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL303.md) | `duplicate-id` | `id` values are unique (same id in `{% if %}` / `{% else %}` branches is allowed) | 1.3.1 (A) |
190
+ | [`RL401`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL401.md) | `form-label` | `<input>`, `<select>` and `<textarea>` have an associated `<label>` | 1.3.1, 4.1.2 (A) |
191
+ | [`RL402`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL402.md) | `autocomplete-valid` | `autocomplete` uses valid autofill tokens (catches typos like `emial`) | 1.3.5 (AA) |
192
+ | [`RL501`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL501.md) | `button-name` | Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
193
+ | [`RL502`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL502.md) | `link-name` | Links have an accessible name | 2.4.4, 4.1.2 (A) |
194
+ | [`RL503`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL503.md) | `no-positive-tabindex` | `tabindex` is not greater than `0` | 2.4.3 (A) |
195
+ | [`RL504`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL504.md) | `anchor-is-valid` | Links have a real target (no `href="#"`, `javascript:` or click-only `<a>`) | 2.1.1 (A) |
196
+ | [`RL601`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL601.md) | `html-lang` | `<html>` declares the page language | 3.1.1 (A) |
197
+ | [`RL602`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL602.md) | `viewport-zoom` | `<meta name="viewport">` does not disable zoom (`user-scalable=no`, `maximum-scale` < 2) | 1.4.4 (AA) |
198
+
199
+ Every rule has its own page with examples and the reasoning behind it: see
200
+ [docs/rules](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/README.md),
201
+ or run `ramplint --explain RL101` in the terminal.
141
202
 
142
203
  <details>
143
204
  <summary><strong>Examples for every rule</strong></summary>
@@ -331,7 +392,7 @@ extensions = [".html", ".txt"]
331
392
  # .pre-commit-config.yaml
332
393
  repos:
333
394
  - repo: https://github.com/iLLcruS/ramplint
334
- rev: 0.2.0
395
+ rev: 0.3.0
335
396
  hooks:
336
397
  - id: ramplint
337
398
  ```
@@ -346,6 +407,38 @@ problems appear as annotations right in the pull request diff.
346
407
  - run: ramplint templates/
347
408
  ```
348
409
 
410
+ ### GitHub Code Scanning
411
+
412
+ With `--format sarif`, problems also show up in the repository's
413
+ **Security → Code scanning** tab, where they are tracked over time and can be
414
+ dismissed with a reason. Code scanning is free for public repositories; private
415
+ repositories need GitHub Advanced Security.
416
+
417
+ ```yaml
418
+ name: Accessibility
419
+
420
+ on: [push, pull_request]
421
+
422
+ jobs:
423
+ ramplint:
424
+ runs-on: ubuntu-latest
425
+ permissions:
426
+ contents: read
427
+ security-events: write
428
+ steps:
429
+ - uses: actions/checkout@v4
430
+ - uses: actions/setup-python@v5
431
+ with:
432
+ python-version: "3.12"
433
+ - run: pip install ramplint
434
+ # --exit-zero: let Code Scanning decide whether the check fails
435
+ - run: ramplint templates/ --format sarif -o ramplint.sarif --exit-zero
436
+ - uses: github/codeql-action/upload-sarif@v4
437
+ with:
438
+ sarif_file: ramplint.sarif
439
+ category: ramplint
440
+ ```
441
+
349
442
  ## Python API
350
443
 
351
444
  ```python
@@ -373,7 +466,7 @@ tool such as axe.
373
466
  ## Contributing
374
467
 
375
468
  Bug reports, especially about false positives, are very welcome.
376
- See [CONTRIBUTING.md](CONTRIBUTING.md).
469
+ See [CONTRIBUTING.md](https://github.com/iLLcruS/ramplint/blob/main/CONTRIBUTING.md).
377
470
 
378
471
  ## Feedback and support
379
472
 
@@ -388,4 +481,4 @@ buy me a coffee:
388
481
 
389
482
  ## License
390
483
 
391
- [MIT](LICENSE) © Vladyslav Rostovskyi
484
+ [MIT](https://github.com/iLLcruS/ramplint/blob/main/LICENSE) © Vladyslav Rostovskyi
@@ -9,7 +9,7 @@
9
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
10
  <a href="https://pypi.org/project/ramplint/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ramplint.svg"></a>
11
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>
12
+ <a href="https://github.com/iLLcruS/ramplint/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
13
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
14
  </p>
15
15
 
@@ -21,12 +21,12 @@ and browser-based checkers only see the pages you remember to open.
21
21
  and reports problems with the exact line and column in the template source:
22
22
 
23
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">
24
+ <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/demo.svg" alt="Terminal output of ramplint reporting six accessibility problems in a Django product page template">
25
25
  </p>
26
26
 
27
27
  ## Try it in 30 seconds
28
28
 
29
- The repository ships with a small demo shop in [`examples/`](examples/): a
29
+ The repository ships with a small demo shop in [`examples/`](https://github.com/iLLcruS/ramplint/tree/main/examples): a
30
30
  deliberately inaccessible set of Django templates that triggers every rule,
31
31
  plus a file full of tricky-but-valid template patterns that must stay silent.
32
32
 
@@ -49,7 +49,7 @@ examples/templates/products/detail.html:28:3: RL101 <input type="image"> needs a
49
49
  Found 32 problems in 6 of 8 files.
50
50
  ```
51
51
 
52
- See [`examples/README.md`](examples/README.md) for what each demo template contains.
52
+ See [`examples/README.md`](https://github.com/iLLcruS/ramplint/blob/main/examples/README.md) for what each demo template contains.
53
53
 
54
54
  ## Highlights
55
55
 
@@ -73,13 +73,69 @@ ramplint templates/ shop/templates/base.html
73
73
  ramplint --select RL1,RL5 # only image and control rules
74
74
  ramplint --ignore heading-order # rules can be referenced by code or name
75
75
  ramplint --format json # machine-readable output
76
+ ramplint --statistics # problems per rule, most frequent first
77
+ ramplint -o report.json --format json # save the report to a file
78
+ ramplint -o a11y-report.html --format html # shareable HTML report
76
79
  ramplint --list-rules
80
+ ramplint --explain RL303 # what a rule checks and how to fix it
77
81
  ```
78
82
 
79
83
  By default ramplint looks at `.html`, `.htm`, `.jinja`, `.jinja2`, `.j2` and
80
84
  `.djhtml` files and skips folders such as `node_modules`, `.venv`, `build` and `dist`.
81
85
  Files passed explicitly are always checked, whatever their extension.
82
86
 
87
+ ### Output formats
88
+
89
+ | Format | Use it for |
90
+ |----------|------------------------------------------------------------------|
91
+ | `text` | Reading in the terminal (default; colored when it is a terminal) |
92
+ | `json` | Scripts, dashboards and other tools |
93
+ | `github` | Annotations in GitHub pull requests (default inside Actions) |
94
+ | `html` | A single self-contained page to share with your team or a client |
95
+ | `sarif` | GitHub Code Scanning and other security dashboards |
96
+
97
+ `--output FILE` writes the report to a file and prints a one-line summary
98
+ instead. Missing folders are created, and colors are never written to files.
99
+
100
+ The HTML report needs no internet connection, so it can be attached to an email
101
+ or stored as a CI artifact. Every problem comes with the surrounding template
102
+ lines, rule names link to their documentation, and you can filter by rule or
103
+ template. It follows the light or dark theme of the viewer's system, and it
104
+ passes ramplint itself.
105
+
106
+ <p align="center">
107
+ <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/html-report.png" alt="HTML report: a blue header with 32 problems in 6 templates, a table of problems by rule and a list of templates with problems" width="800">
108
+ </p>
109
+
110
+ <p align="center">
111
+ <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/html-report-details.png" alt="HTML report details: filters by rule and template, and each problem with the highlighted line of template source" width="800">
112
+ </p>
113
+
114
+ `--statistics` replaces the list of problems with a count per rule, which helps
115
+ decide what to fix first:
116
+
117
+ ```console
118
+ $ ramplint examples/ --statistics
119
+ 6 RL401 form-label
120
+ 6 RL502 link-name
121
+ 4 RL101 img-alt
122
+ 4 RL501 button-name
123
+ 2 RL201 table-header
124
+ 2 RL301 heading-order
125
+ 1 RL102 iframe-title
126
+ 1 RL302 empty-heading
127
+ 1 RL303 duplicate-id
128
+ 1 RL402 autocomplete-valid
129
+ 1 RL503 no-positive-tabindex
130
+ 1 RL504 anchor-is-valid
131
+ 1 RL601 html-lang
132
+ 1 RL602 viewport-zoom
133
+
134
+ Found 32 problems in 6 of 8 files.
135
+ ```
136
+
137
+ It works with `--format text` (default) and `--format json`.
138
+
83
139
  | Exit code | Meaning |
84
140
  |-----------|------------------------------|
85
141
  | `0` | No problems found |
@@ -90,20 +146,24 @@ Files passed explicitly are always checked, whatever their extension.
90
146
 
91
147
  | Code | Name | What it checks | WCAG |
92
148
  |---------|-----------------|------------------------------------------------------------------------------------------|------------------|
93
- | `RL101` | `img-alt` | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A) |
94
- | `RL102` | `iframe-title` | `<iframe>` has a `title` describing its content | 4.1.2 (A) |
95
- | `RL201` | `table-header` | Data tables use real `<th>` header cells | 1.3.1 (A) |
96
- | `RL301` | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`) | 1.3.1 (A) |
97
- | `RL302` | `empty-heading` | Headings are not empty | 2.4.6 (AA) |
98
- | `RL303` | `duplicate-id` | `id` values are unique (same id in `{% if %}` / `{% else %}` branches is allowed) | 1.3.1 (A) |
99
- | `RL401` | `form-label` | `<input>`, `<select>` and `<textarea>` have an associated `<label>` | 1.3.1, 4.1.2 (A) |
100
- | `RL402` | `autocomplete-valid` | `autocomplete` uses valid autofill tokens (catches typos like `emial`) | 1.3.5 (AA) |
101
- | `RL501` | `button-name` | Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
102
- | `RL502` | `link-name` | Links have an accessible name | 2.4.4, 4.1.2 (A) |
103
- | `RL503` | `no-positive-tabindex` | `tabindex` is not greater than `0` | 2.4.3 (A) |
104
- | `RL504` | `anchor-is-valid` | Links have a real target (no `href="#"`, `javascript:` or click-only `<a>`) | 2.1.1 (A) |
105
- | `RL601` | `html-lang` | `<html>` declares the page language | 3.1.1 (A) |
106
- | `RL602` | `viewport-zoom` | `<meta name="viewport">` does not disable zoom (`user-scalable=no`, `maximum-scale` < 2) | 1.4.4 (AA) |
149
+ | [`RL101`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL101.md) | `img-alt` | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A) |
150
+ | [`RL102`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL102.md) | `iframe-title` | `<iframe>` has a `title` describing its content | 4.1.2 (A) |
151
+ | [`RL201`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL201.md) | `table-header` | Data tables use real `<th>` header cells | 1.3.1 (A) |
152
+ | [`RL301`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL301.md) | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`) | 1.3.1 (A) |
153
+ | [`RL302`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL302.md) | `empty-heading` | Headings are not empty | 2.4.6 (AA) |
154
+ | [`RL303`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL303.md) | `duplicate-id` | `id` values are unique (same id in `{% if %}` / `{% else %}` branches is allowed) | 1.3.1 (A) |
155
+ | [`RL401`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL401.md) | `form-label` | `<input>`, `<select>` and `<textarea>` have an associated `<label>` | 1.3.1, 4.1.2 (A) |
156
+ | [`RL402`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL402.md) | `autocomplete-valid` | `autocomplete` uses valid autofill tokens (catches typos like `emial`) | 1.3.5 (AA) |
157
+ | [`RL501`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL501.md) | `button-name` | Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
158
+ | [`RL502`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL502.md) | `link-name` | Links have an accessible name | 2.4.4, 4.1.2 (A) |
159
+ | [`RL503`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL503.md) | `no-positive-tabindex` | `tabindex` is not greater than `0` | 2.4.3 (A) |
160
+ | [`RL504`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL504.md) | `anchor-is-valid` | Links have a real target (no `href="#"`, `javascript:` or click-only `<a>`) | 2.1.1 (A) |
161
+ | [`RL601`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL601.md) | `html-lang` | `<html>` declares the page language | 3.1.1 (A) |
162
+ | [`RL602`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL602.md) | `viewport-zoom` | `<meta name="viewport">` does not disable zoom (`user-scalable=no`, `maximum-scale` < 2) | 1.4.4 (AA) |
163
+
164
+ Every rule has its own page with examples and the reasoning behind it: see
165
+ [docs/rules](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/README.md),
166
+ or run `ramplint --explain RL101` in the terminal.
107
167
 
108
168
  <details>
109
169
  <summary><strong>Examples for every rule</strong></summary>
@@ -297,7 +357,7 @@ extensions = [".html", ".txt"]
297
357
  # .pre-commit-config.yaml
298
358
  repos:
299
359
  - repo: https://github.com/iLLcruS/ramplint
300
- rev: 0.2.0
360
+ rev: 0.3.0
301
361
  hooks:
302
362
  - id: ramplint
303
363
  ```
@@ -312,6 +372,38 @@ problems appear as annotations right in the pull request diff.
312
372
  - run: ramplint templates/
313
373
  ```
314
374
 
375
+ ### GitHub Code Scanning
376
+
377
+ With `--format sarif`, problems also show up in the repository's
378
+ **Security → Code scanning** tab, where they are tracked over time and can be
379
+ dismissed with a reason. Code scanning is free for public repositories; private
380
+ repositories need GitHub Advanced Security.
381
+
382
+ ```yaml
383
+ name: Accessibility
384
+
385
+ on: [push, pull_request]
386
+
387
+ jobs:
388
+ ramplint:
389
+ runs-on: ubuntu-latest
390
+ permissions:
391
+ contents: read
392
+ security-events: write
393
+ steps:
394
+ - uses: actions/checkout@v4
395
+ - uses: actions/setup-python@v5
396
+ with:
397
+ python-version: "3.12"
398
+ - run: pip install ramplint
399
+ # --exit-zero: let Code Scanning decide whether the check fails
400
+ - run: ramplint templates/ --format sarif -o ramplint.sarif --exit-zero
401
+ - uses: github/codeql-action/upload-sarif@v4
402
+ with:
403
+ sarif_file: ramplint.sarif
404
+ category: ramplint
405
+ ```
406
+
315
407
  ## Python API
316
408
 
317
409
  ```python
@@ -339,7 +431,7 @@ tool such as axe.
339
431
  ## Contributing
340
432
 
341
433
  Bug reports, especially about false positives, are very welcome.
342
- See [CONTRIBUTING.md](CONTRIBUTING.md).
434
+ See [CONTRIBUTING.md](https://github.com/iLLcruS/ramplint/blob/main/CONTRIBUTING.md).
343
435
 
344
436
  ## Feedback and support
345
437
 
@@ -354,4 +446,4 @@ buy me a coffee:
354
446
 
355
447
  ## License
356
448
 
357
- [MIT](LICENSE) © Vladyslav Rostovskyi
449
+ [MIT](https://github.com/iLLcruS/ramplint/blob/main/LICENSE) © Vladyslav Rostovskyi
Binary file
@@ -0,0 +1,18 @@
1
+ # Rules
2
+
3
+ | Code | Name | What it checks |
4
+ |------|------|----------------|
5
+ | [RL101](RL101.md) | `img-alt` | Images must have an alt attribute. |
6
+ | [RL102](RL102.md) | `iframe-title` | Frames must have a title describing their content. |
7
+ | [RL201](RL201.md) | `table-header` | Data tables must use &lt;th> header cells. |
8
+ | [RL301](RL301.md) | `heading-order` | Heading levels must not skip (e.g. &lt;h2> followed by &lt;h4>). |
9
+ | [RL302](RL302.md) | `empty-heading` | Headings must have text content. |
10
+ | [RL303](RL303.md) | `duplicate-id` | id attributes must be unique within a template. |
11
+ | [RL401](RL401.md) | `form-label` | Form controls must have an associated &lt;label>. |
12
+ | [RL402](RL402.md) | `autocomplete-valid` | autocomplete must use valid autofill tokens. |
13
+ | [RL501](RL501.md) | `button-name` | Buttons must have an accessible name. |
14
+ | [RL502](RL502.md) | `link-name` | Links must have an accessible name. |
15
+ | [RL503](RL503.md) | `no-positive-tabindex` | tabindex must not be greater than 0. |
16
+ | [RL504](RL504.md) | `anchor-is-valid` | Links must point somewhere; use &lt;button> for actions. |
17
+ | [RL601](RL601.md) | `html-lang` | The &lt;html> element must declare the page language. |
18
+ | [RL602](RL602.md) | `viewport-zoom` | The viewport meta tag must not disable zooming. |
@@ -0,0 +1,58 @@
1
+ # RL101 `img-alt`
2
+
3
+ Images must have an alt attribute.
4
+
5
+ ## WCAG
6
+
7
+ - [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) (level A)
8
+
9
+ ## Why it matters
10
+
11
+ Screen readers announce an image by its `alt` text. Without the attribute they fall back to the file name ("logo underscore final dot png") or skip the image entirely, so the information it carries is lost. An empty `alt=""` is the correct way to mark an image as decorative.
12
+
13
+ ## What ramplint reports
14
+
15
+ - `<img>` without an `alt` attribute (`alt=""` is allowed for decorative images).
16
+ - `<input type="image">` without a non-empty `alt`: it is a button and needs a name.
17
+ - `<area href>` in an image map without a non-empty `alt`.
18
+
19
+ ## Examples
20
+
21
+ Problems:
22
+
23
+ ```django
24
+ {# ✗ #} <img src="{% static 'img/logo.svg' %}">
25
+ {# ✗ #} <input type="image" src="{% static 'img/search.png' %}">
26
+ ```
27
+
28
+ Fixed:
29
+
30
+ ```django
31
+ {# ✓ #} <img src="{% static 'img/logo.svg' %}" alt="Shoply">
32
+ {# ✓ #} <img src="{% static 'img/divider.png' %}" alt="">
33
+ {# ✓ #} <img src="{{ product.image.url }}" alt="{{ product.name }}">
34
+ ```
35
+
36
+ ## Not reported
37
+
38
+ - `aria-label` or `aria-labelledby` on the image.
39
+ - Attributes rendered at runtime, e.g. `<img {{ attrs }}>`.
40
+
41
+ ## Suppressing
42
+
43
+ ```django
44
+ {# ramplint: ignore RL101 #}
45
+ ```
46
+
47
+ on the line with the problem or the line above it, or for the whole file:
48
+
49
+ ```django
50
+ {# ramplint: ignore-file RL101 #}
51
+ ```
52
+
53
+ You can also disable the rule in `pyproject.toml`:
54
+
55
+ ```toml
56
+ [tool.ramplint]
57
+ ignore = ["RL101"]
58
+ ```
@@ -0,0 +1,53 @@
1
+ # RL102 `iframe-title`
2
+
3
+ Frames must have a title describing their content.
4
+
5
+ ## WCAG
6
+
7
+ - [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (level A)
8
+
9
+ ## Why it matters
10
+
11
+ Screen readers list frames by their `title` so users can decide whether to enter them. An untitled map, video or payment widget is announced as just "frame".
12
+
13
+ ## What ramplint reports
14
+
15
+ - `<iframe>` and `<frame>` without a non-empty `title`, `aria-label` or `aria-labelledby`.
16
+
17
+ ## Examples
18
+
19
+ Problems:
20
+
21
+ ```django
22
+ {# ✗ #} <iframe src="https://www.youtube.com/embed/{{ video.id }}"></iframe>
23
+ ```
24
+
25
+ Fixed:
26
+
27
+ ```django
28
+ {# ✓ #} <iframe src="https://www.youtube.com/embed/{{ video.id }}" title="{{ video.title }}"></iframe>
29
+ {# ✓ #} <iframe src="{% url 'store:map' %}" title="Store location map"></iframe>
30
+ ```
31
+
32
+ ## Not reported
33
+
34
+ - Frames hidden from assistive technology with `aria-hidden="true"` (for example tracking frames).
35
+
36
+ ## Suppressing
37
+
38
+ ```django
39
+ {# ramplint: ignore RL102 #}
40
+ ```
41
+
42
+ on the line with the problem or the line above it, or for the whole file:
43
+
44
+ ```django
45
+ {# ramplint: ignore-file RL102 #}
46
+ ```
47
+
48
+ You can also disable the rule in `pyproject.toml`:
49
+
50
+ ```toml
51
+ [tool.ramplint]
52
+ ignore = ["RL102"]
53
+ ```