agent-comment-lint 1.2.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 (45) hide show
  1. agent_comment_lint-1.2.0/LICENSE +21 -0
  2. agent_comment_lint-1.2.0/PKG-INFO +200 -0
  3. agent_comment_lint-1.2.0/README.md +185 -0
  4. agent_comment_lint-1.2.0/agent_comment_lint/__init__.py +3 -0
  5. agent_comment_lint-1.2.0/agent_comment_lint/__main__.py +7 -0
  6. agent_comment_lint-1.2.0/agent_comment_lint/cli.py +384 -0
  7. agent_comment_lint-1.2.0/agent_comment_lint/config.py +124 -0
  8. agent_comment_lint-1.2.0/agent_comment_lint/diff.py +98 -0
  9. agent_comment_lint-1.2.0/agent_comment_lint/engine.py +30 -0
  10. agent_comment_lint-1.2.0/agent_comment_lint/gitio.py +125 -0
  11. agent_comment_lint-1.2.0/agent_comment_lint/governance.py +84 -0
  12. agent_comment_lint-1.2.0/agent_comment_lint/hook.py +94 -0
  13. agent_comment_lint-1.2.0/agent_comment_lint/lexers/__init__.py +19 -0
  14. agent_comment_lint-1.2.0/agent_comment_lint/lexers/base.py +114 -0
  15. agent_comment_lint-1.2.0/agent_comment_lint/lexers/csharp.py +23 -0
  16. agent_comment_lint-1.2.0/agent_comment_lint/lexers/css.py +37 -0
  17. agent_comment_lint-1.2.0/agent_comment_lint/lexers/hashlike.py +53 -0
  18. agent_comment_lint-1.2.0/agent_comment_lint/lexers/javascript.py +176 -0
  19. agent_comment_lint-1.2.0/agent_comment_lint/lexers/linescan.py +206 -0
  20. agent_comment_lint-1.2.0/agent_comment_lint/lexers/python.py +116 -0
  21. agent_comment_lint-1.2.0/agent_comment_lint/report.py +124 -0
  22. agent_comment_lint-1.2.0/agent_comment_lint/rules.py +174 -0
  23. agent_comment_lint-1.2.0/agent_comment_lint.egg-info/PKG-INFO +200 -0
  24. agent_comment_lint-1.2.0/agent_comment_lint.egg-info/SOURCES.txt +43 -0
  25. agent_comment_lint-1.2.0/agent_comment_lint.egg-info/dependency_links.txt +1 -0
  26. agent_comment_lint-1.2.0/agent_comment_lint.egg-info/entry_points.txt +2 -0
  27. agent_comment_lint-1.2.0/agent_comment_lint.egg-info/top_level.txt +1 -0
  28. agent_comment_lint-1.2.0/pyproject.toml +30 -0
  29. agent_comment_lint-1.2.0/setup.cfg +4 -0
  30. agent_comment_lint-1.2.0/tests/test_cli.py +1140 -0
  31. agent_comment_lint-1.2.0/tests/test_comment_after_block_close.py +98 -0
  32. agent_comment_lint-1.2.0/tests/test_config.py +124 -0
  33. agent_comment_lint-1.2.0/tests/test_css.py +49 -0
  34. agent_comment_lint-1.2.0/tests/test_decoration_lines.py +74 -0
  35. agent_comment_lint-1.2.0/tests/test_diff.py +68 -0
  36. agent_comment_lint-1.2.0/tests/test_engine.py +37 -0
  37. agent_comment_lint-1.2.0/tests/test_gitio.py +44 -0
  38. agent_comment_lint-1.2.0/tests/test_governance.py +130 -0
  39. agent_comment_lint-1.2.0/tests/test_hook.py +138 -0
  40. agent_comment_lint-1.2.0/tests/test_javascript.py +231 -0
  41. agent_comment_lint-1.2.0/tests/test_known_false_positives.py +57 -0
  42. agent_comment_lint-1.2.0/tests/test_packaging.py +244 -0
  43. agent_comment_lint-1.2.0/tests/test_pinned_rules.py +112 -0
  44. agent_comment_lint-1.2.0/tests/test_report.py +130 -0
  45. agent_comment_lint-1.2.0/tests/test_unterminated.py +43 -0
agent_comment_lint-1.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Orodruin Labs
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.
agent_comment_lint-1.2.0/PKG-INFO ADDED
@@ -0,0 +1,200 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-comment-lint
3
+ Version: 1.2.0
4
+ Summary: Stops AI coding agents from bloating code comments. Zero dependencies.
5
+ Author: Orodruin Labs
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/OrodruinLabs/agent-comment-lint
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Environment :: Console
10
+ Classifier: Topic :: Software Development :: Quality Assurance
11
+ Requires-Python: >=3.9
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Dynamic: license-file
15
+
16
+ <h1 align="center">agent-comment-lint</h1>
17
+
18
+ <p align="center"><em>Stops AI coding agents from bloating your code comments.</em></p>
19
+
20
+ <p align="center">
21
+ <a href="https://github.com/OrodruinLabs/agent-comment-lint/actions/workflows/ci.yml"><img src="https://github.com/OrodruinLabs/agent-comment-lint/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
22
+ <a href="https://github.com/OrodruinLabs/agent-comment-lint/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
23
+ <img src="https://img.shields.io/badge/python-3.9%E2%80%933.13-3776AB" alt="Python 3.9 to 3.13" />
24
+ <img src="https://img.shields.io/badge/dependencies-none-brightgreen" alt="No dependencies" />
25
+ <img src="https://img.shields.io/badge/Claude_Code-Plugin-7c3aed" alt="Claude Code plugin" />
26
+ </p>
27
+
28
+ ---
29
+
30
+ AI coding agents comment the way they chat: three lines restating what the next line does, and a pointer to the
31
+ ticket or plan they were working from. The restatement drifts from the code, and the pointer rots when the document
32
+ moves.
33
+
34
+ **Your CLAUDE.md asks; this enforces.**
35
+
36
+ agent-comment-lint holds every comment to one line, with no ticket or plan references. In Claude Code it blocks the
37
+ write before the comment lands and shows the agent why, so the agent can rewrite it. The same check runs in CI, in
38
+ pre-commit and from the command line.
39
+
40
+ ```
41
+ src/a.ts:12: C1: 3-line prose block (limit 1)
42
+ src/a.ts:40: C3: governance reference 'ADR-0009'
43
+ agent-comment-lint: 2 violation(s) in 1 of 57 file(s) scanned.
44
+ ```
45
+
46
+ ## What it checks
47
+
48
+ | Rule | Fails when |
49
+ | :--- | :--- |
50
+ | C1 | A comment has more than one line of prose. Consecutive `//` or `#` lines, a multi-line `/* */` and a Python docstring each count as one comment. One-line tags such as `@param` do not count, and neither do rulers like `// ----` or other lines without a letter or digit. |
51
+ | C3 | A comment names a ticket, pull request, decision record, plan or doc path, such as `ADR-9`, `PR 519`, `work item 1234`, `docs/x.md` or `CLAUDE.md`. |
52
+ | C5 | An assertion message built with `+ "..."` spans more than two lines. |
53
+ | C7 | A line that carries a comment is over 120 characters. |
54
+
55
+ The numbers skip because C2, C4 and C6 need a compiler or human judgment, and this tool does not check them.
56
+
57
+ ## Supported languages
58
+
59
+ <div align="center">
60
+ <table>
61
+ <tr>
62
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/csharp/csharp-original.svg" width="44" height="44" alt=""><br><b>C#</b><br><sub><code>.cs</code></sub></td>
63
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/javascript/javascript-original.svg" width="44" height="44" alt=""><br><b>JavaScript</b><br><sub><code>.js</code> <code>.jsx</code> <code>.mjs</code> <code>.cjs</code></sub></td>
64
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/typescript/typescript-original.svg" width="44" height="44" alt=""><br><b>TypeScript</b><br><sub><code>.ts</code> <code>.tsx</code> <code>.mts</code> <code>.cts</code></sub></td>
65
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/css3/css3-original.svg" width="44" height="44" alt=""><br><b>CSS</b><br><sub><code>.css</code></sub></td>
66
+ </tr>
67
+ <tr>
68
+ <td align="center" width="25%"><img src="https://cdn.simpleicons.org/gnubash/4EAA25" width="44" height="44" alt=""><br><b>Shell</b><br><sub><code>.sh</code></sub></td>
69
+ <td align="center" width="25%"><img src="https://cdn.simpleicons.org/yaml/CB171E" width="44" height="44" alt=""><br><b>YAML</b><br><sub><code>.yml</code> <code>.yaml</code></sub></td>
70
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/terraform/terraform-original.svg" width="44" height="44" alt=""><br><b>Terraform and HCL</b><br><sub><code>.tf</code> <code>.tfvars</code> <code>.hcl</code></sub></td>
71
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/python/python-original.svg" width="44" height="44" alt=""><br><b>Python</b><br><sub><code>.py</code></sub></td>
72
+ </tr>
73
+ </table>
74
+ </div>
75
+
76
+ JSX and TSX are included. Other files are skipped, and so are dependency and build folders such as
77
+ `node_modules`, `dist` and `.venv`. Each language's comment styles are listed in [the reference](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/docs/reference.md#scope).
78
+
79
+ ## Setup
80
+
81
+ Pick where it runs; every channel runs the same check. The snippets pin `v1.2.0`. Keep a pin, so a new release never
82
+ changes your results without a commit of yours.
83
+
84
+ ### Claude Code
85
+
86
+ ```
87
+ /plugin marketplace add OrodruinLabs/agent-comment-lint
88
+ /plugin install agent-comment-lint@agent-comment-lint
89
+ ```
90
+
91
+ macOS, Linux and Windows are supported. The plugin finds Python as `AGENT_COMMENT_LINT_PYTHON`, `python3`, `python`,
92
+ then `py -3`. A write that adds a bad comment is blocked, and Claude sees why. Old comments the write
93
+ leaves alone never block it. To turn it on for a whole team, see [Claude Code setup](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/docs/reference.md#claude-code).
94
+
95
+ ### GitHub Actions
96
+
97
+ ```yaml
98
+ on: pull_request
99
+ jobs:
100
+ comments:
101
+ runs-on: ubuntu-latest
102
+ steps:
103
+ - uses: actions/checkout@v4
104
+ with:
105
+ fetch-depth: 0
106
+ - uses: OrodruinLabs/agent-comment-lint@v1.2.0
107
+ ```
108
+
109
+ Only the lines the pull request changes are checked. Keep `fetch-depth: 0`, or the step cannot see what changed and
110
+ fails. Findings appear as annotations on the changed lines. GitHub shows at most 10 per step, and the job summary
111
+ lists them all. The inputs are in [the reference](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/docs/reference.md#github-actions).
112
+
113
+ ### pre-commit
114
+
115
+ ```yaml
116
+ repos:
117
+ - repo: https://github.com/OrodruinLabs/agent-comment-lint
118
+ rev: v1.2.0
119
+ hooks:
120
+ - id: agent-comment-lint
121
+ ```
122
+
123
+ This checks each staged file whole, not only its changed lines, so fix or exclude old findings before you turn it on.
124
+
125
+ ### Command line
126
+
127
+ ```
128
+ uv tool install agent-comment-lint==1.2.0
129
+ pipx install agent-comment-lint==1.2.0
130
+ ```
131
+
132
+ To install from the repository instead:
133
+
134
+ ```
135
+ uv tool install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.2.0
136
+ pipx install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.2.0
137
+ ```
138
+
139
+ `uvx agent-comment-lint` runs it without installing, which suits CI and trials.
140
+
141
+ ```
142
+ agent-comment-lint --diff origin/main # only what the branch changes
143
+ agent-comment-lint --all # every covered file in the repository
144
+ agent-comment-lint --files a.ts b.py # the named files
145
+ ```
146
+
147
+ | Exit code | Meaning |
148
+ | :--- | :--- |
149
+ | 0 | Clean. |
150
+ | 1 | At least one violation. |
151
+ | 2 | Could not scan. Never treated as a pass. |
152
+
153
+ ## Configuration
154
+
155
+ Optional. Add `.agent-comment-lint.json` at the repository root. Settings can only make the check stricter: there
156
+ are no limits to change and no way to silence one comment inline. Every entry states its reason.
157
+
158
+ | Setting | What it does |
159
+ | :--- | :--- |
160
+ | `$schema` | Optional. Lets editors check and complete the file. |
161
+ | `exclude` | Paths that are never checked, such as vendored or generated code. |
162
+ | `governance.packs` | Turns on reference packs, below. |
163
+ | `governance.extra` | Adds your own reference patterns, as regular expressions. |
164
+
165
+ ```json
166
+ {
167
+ "$schema": "https://raw.githubusercontent.com/OrodruinLabs/agent-comment-lint/v1.2.0/schema/agent-comment-lint.schema.json",
168
+ "exclude": [{ "path": "vendor/", "reason": "third-party code" }],
169
+ "governance": {
170
+ "packs": ["azure-boards"],
171
+ "extra": [{ "pattern": "\\bWEB-\\d+", "reason": "the web team's ticket ids" }]
172
+ }
173
+ }
174
+ ```
175
+
176
+ ### Reference packs
177
+
178
+ C3 always refuses the common shapes shown in [What it checks](#what-it-checks). A pack adds the reference shapes of
179
+ one tracker or convention. Packs are off by default because the same shapes mean other things in many codebases, so
180
+ turn on only the ones your team uses.
181
+
182
+ | Pack | Turn it on if you use | It refuses |
183
+ | :--- | :--- | :--- |
184
+ | `agent-context` | AI agents that cite a plan, a chat or a notes file | `Task 8`, `step 3 of the plan`, `per the spec`, `as requested`, `the user asked`, `PLAN.md` |
185
+ | `azure-boards` | Azure Boards | `AB#4321`, `ADO #795`, `ADO 795` |
186
+ | `decision-ids` | numbered decisions | `D-7`, `D-12b`, `D7` |
187
+ | `task-ids` | task ids shaped prefix, dash, letter, number | `WEB-T022`, `AUTH-F053` |
188
+
189
+ ## Documentation
190
+
191
+ [The reference](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/docs/reference.md) has everything else:
192
+ - every reference shape C3 refuses
193
+ - each mode and exit code
194
+ - team setup for Claude Code
195
+ - what each language's lexer can and cannot tell apart
196
+ - the known false positives
197
+
198
+ ## License
199
+
200
+ MIT. See [LICENSE](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/LICENSE).
agent_comment_lint-1.2.0/README.md ADDED
@@ -0,0 +1,185 @@
1
+ <h1 align="center">agent-comment-lint</h1>
2
+
3
+ <p align="center"><em>Stops AI coding agents from bloating your code comments.</em></p>
4
+
5
+ <p align="center">
6
+ <a href="https://github.com/OrodruinLabs/agent-comment-lint/actions/workflows/ci.yml"><img src="https://github.com/OrodruinLabs/agent-comment-lint/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
7
+ <a href="https://github.com/OrodruinLabs/agent-comment-lint/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
8
+ <img src="https://img.shields.io/badge/python-3.9%E2%80%933.13-3776AB" alt="Python 3.9 to 3.13" />
9
+ <img src="https://img.shields.io/badge/dependencies-none-brightgreen" alt="No dependencies" />
10
+ <img src="https://img.shields.io/badge/Claude_Code-Plugin-7c3aed" alt="Claude Code plugin" />
11
+ </p>
12
+
13
+ ---
14
+
15
+ AI coding agents comment the way they chat: three lines restating what the next line does, and a pointer to the
16
+ ticket or plan they were working from. The restatement drifts from the code, and the pointer rots when the document
17
+ moves.
18
+
19
+ **Your CLAUDE.md asks; this enforces.**
20
+
21
+ agent-comment-lint holds every comment to one line, with no ticket or plan references. In Claude Code it blocks the
22
+ write before the comment lands and shows the agent why, so the agent can rewrite it. The same check runs in CI, in
23
+ pre-commit and from the command line.
24
+
25
+ ```
26
+ src/a.ts:12: C1: 3-line prose block (limit 1)
27
+ src/a.ts:40: C3: governance reference 'ADR-0009'
28
+ agent-comment-lint: 2 violation(s) in 1 of 57 file(s) scanned.
29
+ ```
30
+
31
+ ## What it checks
32
+
33
+ | Rule | Fails when |
34
+ | :--- | :--- |
35
+ | C1 | A comment has more than one line of prose. Consecutive `//` or `#` lines, a multi-line `/* */` and a Python docstring each count as one comment. One-line tags such as `@param` do not count, and neither do rulers like `// ----` or other lines without a letter or digit. |
36
+ | C3 | A comment names a ticket, pull request, decision record, plan or doc path, such as `ADR-9`, `PR 519`, `work item 1234`, `docs/x.md` or `CLAUDE.md`. |
37
+ | C5 | An assertion message built with `+ "..."` spans more than two lines. |
38
+ | C7 | A line that carries a comment is over 120 characters. |
39
+
40
+ The numbers skip because C2, C4 and C6 need a compiler or human judgment, and this tool does not check them.
41
+
42
+ ## Supported languages
43
+
44
+ <div align="center">
45
+ <table>
46
+ <tr>
47
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/csharp/csharp-original.svg" width="44" height="44" alt=""><br><b>C#</b><br><sub><code>.cs</code></sub></td>
48
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/javascript/javascript-original.svg" width="44" height="44" alt=""><br><b>JavaScript</b><br><sub><code>.js</code> <code>.jsx</code> <code>.mjs</code> <code>.cjs</code></sub></td>
49
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/typescript/typescript-original.svg" width="44" height="44" alt=""><br><b>TypeScript</b><br><sub><code>.ts</code> <code>.tsx</code> <code>.mts</code> <code>.cts</code></sub></td>
50
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/css3/css3-original.svg" width="44" height="44" alt=""><br><b>CSS</b><br><sub><code>.css</code></sub></td>
51
+ </tr>
52
+ <tr>
53
+ <td align="center" width="25%"><img src="https://cdn.simpleicons.org/gnubash/4EAA25" width="44" height="44" alt=""><br><b>Shell</b><br><sub><code>.sh</code></sub></td>
54
+ <td align="center" width="25%"><img src="https://cdn.simpleicons.org/yaml/CB171E" width="44" height="44" alt=""><br><b>YAML</b><br><sub><code>.yml</code> <code>.yaml</code></sub></td>
55
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/terraform/terraform-original.svg" width="44" height="44" alt=""><br><b>Terraform and HCL</b><br><sub><code>.tf</code> <code>.tfvars</code> <code>.hcl</code></sub></td>
56
+ <td align="center" width="25%"><img src="https://cdn.jsdelivr.net/gh/devicons/devicon@v2.16.0/icons/python/python-original.svg" width="44" height="44" alt=""><br><b>Python</b><br><sub><code>.py</code></sub></td>
57
+ </tr>
58
+ </table>
59
+ </div>
60
+
61
+ JSX and TSX are included. Other files are skipped, and so are dependency and build folders such as
62
+ `node_modules`, `dist` and `.venv`. Each language's comment styles are listed in [the reference](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/docs/reference.md#scope).
63
+
64
+ ## Setup
65
+
66
+ Pick where it runs; every channel runs the same check. The snippets pin `v1.2.0`. Keep a pin, so a new release never
67
+ changes your results without a commit of yours.
68
+
69
+ ### Claude Code
70
+
71
+ ```
72
+ /plugin marketplace add OrodruinLabs/agent-comment-lint
73
+ /plugin install agent-comment-lint@agent-comment-lint
74
+ ```
75
+
76
+ macOS, Linux and Windows are supported. The plugin finds Python as `AGENT_COMMENT_LINT_PYTHON`, `python3`, `python`,
77
+ then `py -3`. A write that adds a bad comment is blocked, and Claude sees why. Old comments the write
78
+ leaves alone never block it. To turn it on for a whole team, see [Claude Code setup](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/docs/reference.md#claude-code).
79
+
80
+ ### GitHub Actions
81
+
82
+ ```yaml
83
+ on: pull_request
84
+ jobs:
85
+ comments:
86
+ runs-on: ubuntu-latest
87
+ steps:
88
+ - uses: actions/checkout@v4
89
+ with:
90
+ fetch-depth: 0
91
+ - uses: OrodruinLabs/agent-comment-lint@v1.2.0
92
+ ```
93
+
94
+ Only the lines the pull request changes are checked. Keep `fetch-depth: 0`, or the step cannot see what changed and
95
+ fails. Findings appear as annotations on the changed lines. GitHub shows at most 10 per step, and the job summary
96
+ lists them all. The inputs are in [the reference](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/docs/reference.md#github-actions).
97
+
98
+ ### pre-commit
99
+
100
+ ```yaml
101
+ repos:
102
+ - repo: https://github.com/OrodruinLabs/agent-comment-lint
103
+ rev: v1.2.0
104
+ hooks:
105
+ - id: agent-comment-lint
106
+ ```
107
+
108
+ This checks each staged file whole, not only its changed lines, so fix or exclude old findings before you turn it on.
109
+
110
+ ### Command line
111
+
112
+ ```
113
+ uv tool install agent-comment-lint==1.2.0
114
+ pipx install agent-comment-lint==1.2.0
115
+ ```
116
+
117
+ To install from the repository instead:
118
+
119
+ ```
120
+ uv tool install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.2.0
121
+ pipx install git+https://github.com/OrodruinLabs/agent-comment-lint@v1.2.0
122
+ ```
123
+
124
+ `uvx agent-comment-lint` runs it without installing, which suits CI and trials.
125
+
126
+ ```
127
+ agent-comment-lint --diff origin/main # only what the branch changes
128
+ agent-comment-lint --all # every covered file in the repository
129
+ agent-comment-lint --files a.ts b.py # the named files
130
+ ```
131
+
132
+ | Exit code | Meaning |
133
+ | :--- | :--- |
134
+ | 0 | Clean. |
135
+ | 1 | At least one violation. |
136
+ | 2 | Could not scan. Never treated as a pass. |
137
+
138
+ ## Configuration
139
+
140
+ Optional. Add `.agent-comment-lint.json` at the repository root. Settings can only make the check stricter: there
141
+ are no limits to change and no way to silence one comment inline. Every entry states its reason.
142
+
143
+ | Setting | What it does |
144
+ | :--- | :--- |
145
+ | `$schema` | Optional. Lets editors check and complete the file. |
146
+ | `exclude` | Paths that are never checked, such as vendored or generated code. |
147
+ | `governance.packs` | Turns on reference packs, below. |
148
+ | `governance.extra` | Adds your own reference patterns, as regular expressions. |
149
+
150
+ ```json
151
+ {
152
+ "$schema": "https://raw.githubusercontent.com/OrodruinLabs/agent-comment-lint/v1.2.0/schema/agent-comment-lint.schema.json",
153
+ "exclude": [{ "path": "vendor/", "reason": "third-party code" }],
154
+ "governance": {
155
+ "packs": ["azure-boards"],
156
+ "extra": [{ "pattern": "\\bWEB-\\d+", "reason": "the web team's ticket ids" }]
157
+ }
158
+ }
159
+ ```
160
+
161
+ ### Reference packs
162
+
163
+ C3 always refuses the common shapes shown in [What it checks](#what-it-checks). A pack adds the reference shapes of
164
+ one tracker or convention. Packs are off by default because the same shapes mean other things in many codebases, so
165
+ turn on only the ones your team uses.
166
+
167
+ | Pack | Turn it on if you use | It refuses |
168
+ | :--- | :--- | :--- |
169
+ | `agent-context` | AI agents that cite a plan, a chat or a notes file | `Task 8`, `step 3 of the plan`, `per the spec`, `as requested`, `the user asked`, `PLAN.md` |
170
+ | `azure-boards` | Azure Boards | `AB#4321`, `ADO #795`, `ADO 795` |
171
+ | `decision-ids` | numbered decisions | `D-7`, `D-12b`, `D7` |
172
+ | `task-ids` | task ids shaped prefix, dash, letter, number | `WEB-T022`, `AUTH-F053` |
173
+
174
+ ## Documentation
175
+
176
+ [The reference](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/docs/reference.md) has everything else:
177
+ - every reference shape C3 refuses
178
+ - each mode and exit code
179
+ - team setup for Claude Code
180
+ - what each language's lexer can and cannot tell apart
181
+ - the known false positives
182
+
183
+ ## License
184
+
185
+ MIT. See [LICENSE](https://github.com/OrodruinLabs/agent-comment-lint/blob/main/LICENSE).
agent_comment_lint-1.2.0/agent_comment_lint/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """agent-comment-lint: one engine that judges code comments against fixed rules, for any repository."""
2
+
3
+ __version__ = "1.2.0"
agent_comment_lint-1.2.0/agent_comment_lint/__main__.py ADDED
@@ -0,0 +1,7 @@
1
+ """Lets `python3 -m agent_comment_lint` run the check."""
2
+ import sys
3
+
4
+ from .cli import main
5
+
6
+ if __name__ == "__main__":
7
+ sys.exit(main())