Comment Lens Scanner
Comment Lens extracts code comments and keeps them useful over time. The local command-line interface finds comments that deserve attention before they become maintenance debt, explains why with deterministic rule evidence, and helps teams maintain high comment quality without modifying repository files.
Features
- AST-Aware Parsing: Uses Tree-sitter grammars (with Pygments fallback) to distinguish docstrings, line comments, inline notes, and header blocks across major languages.
- Maintenance Signals: Flags unresolved
TODO/FIXME/HACKdirectives, symbol duplication, stale comments on changed code, and broken local file links. - Git Differential Checks: Fast pre-commit and CI checks using
--changedto focus only on comments added or modified in the current branch. - Multi-Format Export: Emits findings in JSON, NDJSON, Markdown, and SARIF for GitHub Actions PR annotations.
- Zero-Network Default: Fully local execution; code is inspected without being executed or transmitted to external servers.
Installation
pip install comment-lens-scanner
Requires Python 3.12 or newer.
Usage
Scan a Repository
Scan the current repository and generate local finding manifests (.comment-lens/scan.json and .comment-lens/comments.ndjson):
comment-lens scan .
Check Changed Comments (Pre-Commit or CI)
Check only comments touching lines changed between origin/main and HEAD, failing if any high-severity findings are introduced:
comment-lens check . --changed origin/main...HEAD --fail-on high
Generate SARIF output for CI integration:
comment-lens check . --changed HEAD --scope files --format sarif --output findings.sarif
Export an Existing Scan
Convert an existing scan artifact into Markdown or JSON:
comment-lens export . --format markdown
comment-lens export . --format json
Configuration
Place a .comment-lens.toml file at your repository root to configure exclusions and rule policies:
version = 1
exclude = ["fixtures", "legacy"]
[policy]
fail_on = "none"
[policy.rules]
todo = "review"
fixme = "high"
symbol_duplication = "review"
missing_local_reference = "high"
License
MIT License. See LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for comment-lens-scanner 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| comment_lens_scanner-0.1.0.tar.gz | 30.4 kB | With provenance | Details for comment_lens_scanner-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| comment_lens_scanner-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for comment_lens_scanner-0.1.0-py3-none-any.whl |
Total release size: 58.0 kB
Release files / comment_lens_scanner-0.1.0.tar.gz
| Download URL | comment_lens_scanner-0.1.0.tar.gz |
|---|---|
| Size | 30.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9751e4d3a9b44f43508853ed8549b747c4287e05d138261181c567f1610aed7b
|
|
BLAKE2b-256 checksum How to use checksums |
2915211de6cbe3765e8bc03f3e8b85c463c2d8738df104a18b32de9a253f36e6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / comment_lens_scanner-0.1.0-py3-none-any.whl
| Download URL | comment_lens_scanner-0.1.0-py3-none-any.whl |
|---|---|
| Size | 27.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a933dc6945e84ec3196a83ea8af23613b160a469ee68ee8405095b51fe4a4caa
|
|
BLAKE2b-256 checksum How to use checksums |
531f0074abd355667de6ed1a0bc1e743f7737c7f94a5be6384d088921bbeafcc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for comment-lens-scanner 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for comment_lens_scanner-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
