Skip to content
Metatext Decide — typed decisions for your agents, with a probability on every answerGet early access
Metatext
Sign Up

typesafe-comment

Linter that scores code comments on five heuristics with Jev and fails CI when comments fall below thresholds.

Librarybeta
View on GitHub ↗

Overview

typesafe-comment lints code comments with TypeSafe's System One model. Each comment inside a function or class is scored on five heuristics: usefulness, readability, accuracy, redundancy and coverage. Comments below configurable thresholds produce linter warnings, and the command exits non-zero so pipelines can block.

It supports Python through the standard ast module, and C, C++, JavaScript, TypeScript, Go and Rust through an optional tree-sitter extra. Output can be human-readable, GitHub Actions annotations or JSON. The key comes from the environment or a .env file, and model, base URL, timeout and retries are configurable. It is installable from PyPI, via pipx or run ad hoc with uvx. Default thresholds are modest (for example accuracy 0.25 and coverage 0.1), so teams are expected to tune them per codebase before using the tool as a hard gate.

What the decision model decides

TypeQuestionAnswers
ScoreHow useful is this comment?—
ScoreHow accurate is this comment relative to the code?—
ScoreHow redundant is this comment?—

How it works

  1. Scan source files for comments inside functions and classes.
  2. Send each comment with its code context to Jev for five scores.
  3. Compare scores with thresholds.
  4. Emit warnings and exit non-zero on failures.

Strengths

  • CI-ready with GitHub annotations and JSON output.
  • Multi-language support via tree-sitter.
  • Configurable thresholds per heuristic.

Caveats

  • API errors also cause a non-zero exit.
  • Module-level comments are not evaluated.

Getting started

pip install "typesafe-comment[tree-sitter]" && typesafe-comment --github src/

At a glance

Type
Library
Status
beta
Language
Python
Runtime
CLI
Has code
yes

Use cases and integrations

How curated lists describe it

  • Small Python package that uses typesafe.ai to evaluate code comments on certain heuristics.

    hellogumbo/awesome-jev

Frequently asked questions

What does it score?

Usefulness, readability, accuracy, redundancy and coverage of each code comment.

Can it block a pull request?

Yes, it exits non-zero when any comment fails a threshold.

Which languages are supported?

Python, C, C++, JavaScript, TypeScript, Go and Rust.

Related projects

  • JevGate

    Rust code-review gate asking Jev small typed questions about functions and tests, failing CI only on rules measured 80% right.

    CLIproductionRust
  • Abide

    Coding-agent hook that asks Jev one yes/no per project rule on every edit or turn and makes the agent fix any violation.

    HookbetaTypeScript
  • code-quality

    Advisor for coding agents: git and Stop hooks flag test tampering, secrets and skipped hooks, with optional Jev review findings.

    Hookbeta
  • jeff (Alurith)

    Read-only Go CLI that checks files against your plain-language code rules with Jev, locally or in CI.

    CLIbetaGo
  • jev-codes

    CLI and agent commands auditing a git diff against YAML standards packs, scoring each hunk with Jev so agents fix only flags.

    Agent skillbetaTypeScript
  • jev-lint

    Fuzzy linter hook for Claude Code and Codex where Jev checks each written file against team rules and reports violations at edit time.

    HookbetaTypeScript