Hexdigest123/typesafe-commentArchived
User repository on GitHub
Small Python package that uses typesafe.ai to evaluate code comments on certain heuristics
- Forks
- 0
- Last pushed
- Updated Sep 2026
Repo stats from the GitHub API, cached Oct 2026.
CommunityJev Tools & CLIs
TypeSafe Comment
A Python linter that scores code comments with System One on five heuristics — usefulness, readability, accuracy, redundancy, coverage — and fails the pipeline when a comment falls under a threshold.
- Stars
- 0
- Language
- Python
- License
- MIT
- Published by
- Community
- Author
- Hexdigest123
- Last verified
- Oct 2026
About this project
Lint code comments with TypeSafe AI's System One model. Comments are scored on five heuristics (usefulness, readability, accuracy, redundancy, coverage); those below thresholds emit linter warnings and exit non-zero so pipelines block. Never embedded in source. Set it in the environment or load from a .env file (see .env.example): General environment always wins over .env values. Other env vars: TYPESAFEMODEL (default jev-latest), TYPESAFEAPIBASE, TYPESAFETIMEOUT, TYPESAFEMAXRETRIES.
Quoted from the project's README. Read the full README.
- Languages
- Python
Highlights
- Five scores per comment with tunable thresholds; defaults are usefulness and readability 0.3, accuracy and redundancy 0.25, and coverage 0.1.
- Python parses with the stdlib ast module; C, C++, JavaScript, TypeScript, Go and Rust need the tree-sitter extra.
- Exit codes are 0 when everything passes, -1 on a failed threshold or an API error, and 2 for bad CLI usage.
- Documented CI shapes cover GitHub Actions with ::warning annotations, GitLab CI, and an opencode post-edit hook over staged files.
Watch out
Every comment costs a model call, so scan time and spend scale with comment count across the directory you point it at, and the default thresholds are tight enough that the README's own example lowers accuracy and coverage before use. Runs are model-driven, so they are not byte-reproducible, and an API error exits with the same code as a genuinely bad comment, which makes a failing pipeline ambiguous without reading the output. Module-level comments are skipped entirely, so coverage is narrower than the file list suggests. The five scores come from the model and the README documents thresholds for them but no validation of the scoring itself. Copy reviewed against the repository README on 2026-10-04, not from running it.
Questions about this entry
Short answers drawn from the linked project or page.
Possibly, which is why the thresholds are per-heuristic flags rather than fixed. Defaults are usefulness 0.3, readability 0.3, accuracy 0.25, redundancy 0.25 and coverage 0.1, and the README's own example loosens two of them to 0.4 and 0.2. Treat a first run as a measurement — run with --json and inspect the distribution before you let the non-zero exit gate a pipeline.
Python alone, and it needs python-dotenv for the environment file. The base install covers .py only, using the standard library ast module; C, C++, JavaScript, TypeScript and TSX, Go and Rust all require the tree-sitter extra, which you can get through the extras syntax, a requirements file, or an on-demand runner such as uvx.
It is never embedded in source. Set TYPESAFE_API_KEY in the environment or point at a file with --env, including a required-file form, and the general environment always wins over .env values. Other knobs are TYPESAFE_MODEL, which defaults to jev-latest, plus TYPESAFE_API_BASE, TYPESAFE_TIMEOUT and TYPESAFE_MAX_RETRIES.
Yes. The README documents an opencode post-edit hook that pipes staged additions and modifications from git diff straight into the linter, and the CLI also supports --quiet for warnings only, --json for machine-readable output and --github for ::warning annotations. One gotcha: an API error and a failed threshold share an exit code, so in CI check the output rather than treating any non-zero as a bad comment.
uvx --from typesafe-comment typesafe-comment src/ runs it ad-hoc with no install at all, and pipx install typesafe-comment puts it on PATH globally. For a project, pip install -e . covers Python only and needs python-dotenv, pip install -e ".[tree-sitter]" adds C, C++, JavaScript, TypeScript and TSX, Go, and Rust, and it is also published on PyPI as typesafe-comment.
Module-level comments are skipped entirely, so coverage is narrower than the list of files you point it at suggests. It also evaluates every comment it does find with its own model call, which is why scan time and spend scale with comment count across the directory rather than with anything structural.
Every comment costs one model call, so both scan time and spend scale with comment count across the directory you point at. Runs are model-driven rather than byte-reproducible, and module-level comments are skipped, so coverage is narrower than the file list implies. There is also no validation of the scoring itself anywhere in the README.
More Jev resources like this
39GitHub stars
Video tool where Jev scores subtitle segments and code assembles a short highlights cut plus a de-watered full cut with timestamped summaries.
Jev Tools & CLIs#community#jevbest#catalog-import
Community
cclank/jevclipPython
cclank/jevclipPython547GitHub stars
Live SEO audit that crawls a site from one homepage URL, checks 52 rules tied to Google Search Central, and asks Jev typed questions about every page to rank fixes.
Jev Tools & CLIs#community#jevbest#catalog-import
Community
AgriciDaniel/jev-seoPython
AgriciDaniel/jev-seoPython27GitHub stars
Local-first trading journal and review harness that is read-only over markets, captures runs into frozen envelopes and evidence packs, and requires explicit human promotion before any rule returns.
Jev Tools & CLIs#community#jevbest#catalog-import
Community
myc0576/SmartMoney-CubPython
myc0576/SmartMoney-CubPython30GitHub stars
Forkable weekday radar that asks Jev one yes-or-no question per interest over each new arXiv announcement and publishes a page plus RSS feed.
Jev Tools & CLIs#community#jevbest#catalog-import
Community
Eliot5566/JEV-Paper-RadarPython
Eliot5566/JEV-Paper-RadarPython38GitHub stars
Async supervisory layer for Hermes Agent that locks Definitions of Done, proves mechanical criteria locally, and calls Jev only for unresolved semantic checks under a token budget.
Jev Tools & CLIs#community#jevbest#catalog-import
Community
keeltrace/hermes-nervePython
keeltrace/hermes-nervePython24GitHub stars
macOS floating WeChat companion that reads the visible chat with on-device Vision OCR, judges intent and reply risk with Jev, drafts toned replies with GPT, and only fills text after you approve it.
Jev Tools & CLIs#community#jevbest#catalog-import
Community
wuxie888/jev-yaba-wechatPython
wuxie888/jev-yaba-wechatPythonFrom the Jev guides
Original write-ups on what this entry is for.
The request shape barely changes across surfaces; the surrounding contract does. When to call the API directly and when a gateway, a Worker binding, or a router entry earns its extra hop.
Jev Tools & CLIs#gateway#vercel#cloudflare
Read article
Taking a decision checkpoint out of Python: what the GGUF and browser WebGPU exports preserve, what they change, and the parity evidence the model cards publish.
Jev Tools & CLIs#open-models#local#onnx
Read article
Jev labels a record that already exists. Code moves, flags, or holds it. How the document, mail, and transfer tools keep the action out of the model.
Jev Tools & CLIs#classification#email#security
Read article
From the Jev community
Posts from builders shipping with Jev right now.